For Coding Agents

This page tells coding agents (Claude Code, Cursor, Copilot, Gemini CLI, etc.) how to find the right documentation when working on the Sprinter Platform.

Entry Points

How to Find the Right Doc

By file you are editing

By task you are doing

Key Rules for Agents

These rules are enforced across the codebase. Violations will cause build failures or review rejections.

1. Entity types are DB-driven — never hardcode entity type slugs in platform code
2. All DB ops are tenant-scoped — use getTenantContext() or getActiveTenantId()
3. Use the auth adapter — getUserId(), requireAuth(), hasPermission() from features/tenant/auth.ts
4. shadcn/ui for all interactive UI — never raw HTML inputs or buttons
5. No hardcoded colors — use CSS variables (zero-chroma neutrals, navy primary)
6. No "entities" in UI copy — use "records", "data", "items" in user-facing text
7. Co-located tests required — every file with exported logic needs a .test.ts
8. Messages table — use messages, not chat_messages
9. User tenants table — use user_tenants, not tenant_members

Doc Structure Convention

Every feature doc follows the same structure so agents can reliably find information:

• Overview — what, why, who
• Key Concepts — types, schemas, terminology
• How It Works — architecture, data flow
• API Reference — key functions and signatures
• For Agents — available tools and actions
• Design Decisions — non-obvious choices
• Related Modules — cross-references

Spec-First Workflow

Every new feature must have a spec before implementation begins. See Spec-First Development for the full workflow.

Quick Reference for Agents

1. Check the backlog — content/docs/roadmap/backlog.mdx lists all planned work by priority
2. Find or write a spec — content/docs/roadmap/specs/{feature}.mdx has the design
3. Claim it — Set status: in-progress and assigned-to in the spec frontmatter
4. Check file conflicts — The spec's files-touched field lists which files will be modified. If another in-progress spec touches the same files, coordinate or pick different work.
5. Build it — The spec is your source of truth
6. Complete it — Set status: completed. The documentarian promotes spec content to the feature doc.

Context and Cost Notes

• agent_context is the durable tenant-authored workspace business profile. If you change how agent context is assembled or edited, update both the agent docs and the admin/editor flow.
• Anthropic prompt caching depends on stable prompt structure and deterministic tool ordering. If you change tool registration or prompt assembly, preserve stability unless you have a measured reason not to.
• Runtime telemetry for agent runs is recorded via ai.runtime.completed. If you add or rename telemetry fields, update the analytics/cost docs and any admin surfaces that summarize them.

Spec Frontmatter

---
title: Feature Name
description: One-line summary
status: draft | approved | in-progress | completed
priority: P0 | P1 | P2 | P3
assigned-to: ""            # empty = unclaimed
branch: ""                 # git branch
target-doc: /docs/features/entity-system
files-touched:
  - features/entities/types.ts
---

Keeping Docs Updated

When you complete a feature, fix, or significant change:

1. The documentarian sub-agent runs automatically as part of the feature completion checklist
2. It updates the changelog and the relevant feature doc
3. For spec-first features, the documentarian also promotes spec content to the target feature doc
4. If you add a new module, create a new MDX file in content/docs/features/ and add its slug to content/docs/features/meta.json
5. Run npx fumadocs-mdx to regenerate the .source/ directory after adding new docs