Order of operations
- Spec first: the spec is the durable source of truth. Code can be deleted and rewritten; the spec survives.
- Tests are not optional: tests and code are written together, but specs define what to test before implementation begins. Only test code that has meaningful logic (branching, transformations, error handling). Don't test code that can only break if the language, runtime, or a dependency breaks.
- Code implements the spec: write code along with tests, implementing the spec in full.
Drift rule: resolve drift by propagating changes upward in this order: code -> execution plan -> implementation spec -> design spec.
If code/tests reveal missing or incorrect requirements, the agent must report the drift to the user and wait for approval before updating affected layers in that sequence.
Specs are drafted by the agent and refined through human review and feedback. The human provides direction, constraints, and approval; the agent produces the written artifact.
This repo uses two persistent spec types and one transient execution activity.
Purpose: define what the system must do — from the perspective of someone who uses it, not someone who builds it.
Design specs contain:
- User-visible behavior and contracts.
- CLI/API surface, default configuration values, and any paths or identifiers users interact with.
- Scope, non-goals, and acceptance criteria.
- Architecture constraints that should remain true across rewrites.
- Mermaid diagrams where they clarify flows, state machines, or relationships.
Design specs do not contain:
- Library/framework/package choices (see Boundary Rule for exceptions).
- Internal type/function signatures, symbol names, or file layout.
- Internal algorithms or step-by-step execution mechanics unless externally observable.
Purpose: define how a feature is built in durable engineering terms — decisions that an implementer needs but a user never sees.
Implementation specs contain:
- Concrete dependency choices and rationale.
- Invariants, constraints, and error contracts.
- Wire formats, protocols, and internal data representations.
- Required tests for meaningful logic.
- Structural boundaries only when they are durable architectural constraints; include rationale when enforced.
- Mermaid diagrams where they clarify architecture, data flow, or component interaction.
Implementation specs do not contain:
- One-time task sequencing, timelines, or PR choreography.
- Incidental file/package/directory layout that can change without violating the spec contracts.
Unless explicitly declared as an architectural constraint, code organization is refactorable.
A phased plan is required before implementation work begins. It is transient and not committed to the repository.
When implementing a doc from /docs/implementation/, the agent must follow this flow:
- Propose a phased breakdown to the user.
- Wait for user review and an explicit start instruction before making implementation edits or commits.
- Keep each phase atomic — producing a coherent, compilable, runnable product — and small enough for human review (ideally under 200 lines changed, excluding lockfiles and generated files).
- After start, execute phases autonomously: commit after each phase and continue to the next without waiting for additional user confirmation unless blocked by missing input, failures, or detected drift.
- Report when all phases are complete or when blocked. Reports must focus on decision-relevant content: requirements now satisfied, scope boundaries unchanged, validation evidence, assumptions made, risks introduced, any detected drift and proposed updates across execution plan/implementation spec/design spec, and why continuing is safe.
If a statement would become false after swapping implementation dependencies while preserving behavior, it belongs in an implementation spec, not a design spec.
Exception: A design spec may name a concrete dependency only when that dependency is itself a product requirement (for example compliance, mandated platform/runtime, or explicit interoperability commitment). The reason must be stated explicitly.
Spec files are numbered with a zero-padded three-digit prefix starting from 001, followed by a hyphen and a descriptive slug: 001-slug.md. New specs take the next available number within their directory.
- Design specs may cover multiple features.
- Implementation specs must be small enough to implement in a few phases; split by feature/coherent slice.
- Design docs may reference design docs.
- Implementation docs may reference design and implementation docs.
- Design docs must never reference implementation docs.
- All references use markdown links.
Specs must be definitive and concise: no TBDs, no unresolved decisions, no optional ambiguity. When uncertain, the agent makes a decision on the human's behalf and presents it with enough context for the human to review and override if needed. Specs must also be internally consistent and coherent: avoid patchy wording, contradictions, and overlapping rules that change meaning, and ensure revisions read as if written that way from the beginning.
- Code changes must be coherent and maintainable; prefer refactoring over layered, patchy fixes.
- Prefer fewer lines when correctness and maintainability are preserved; avoid duplicate logic by relying on existing guarantees from types, called functions, and validated interfaces.
- Directory and package structure should reflect durable boundaries defined by specs, not short-term convenience.
- Adding a dependency is preferred over bespoke code.
- Do not introduce hacky workarounds. If a workaround is unavoidable, pause and get user approval first.
- Commit messages follow
type(scope): summary. - Always use package manager commands to add or update dependencies.
README.mdis not a spec, but it must be updated when it is no longer true due to code change.- This file (
CLAUDE.md/AGENTS.md) must be updated when the human approves a change to project conventions or processes that makes the current content no longer accurate. - If a user request appears to conflict with these guidelines, explicitly double-check intent with the user before proceeding.