Specification-driven development

Use this workflow to formalize a True Specification conversation or carry a consequential product or system change from intent to accepted implementation, within the requested scope. Follow Discuss → True Spec Worksheet → Decide → SPEC and/or SPECARC → systems.md → Plan → Implement → Verify → Human Acceptance where applicable, using only the stages needed. A specification-only request ends with the requested definitions and relevant map review/update. For a narrow defect with established expected behavior, use audit-repair; routine maintenance, cosmetic edits, and implementation already specified at the needed level do not require the full specification path.

Before substantial specification, architecture or implementation, demonstrate a concise Understanding Check after relevant inspection and before proposing implementation. Keep trivial explicitly authorized work proportional; this is not a new approval gate.

1. Read the adopting repository's instructions, authority hierarchy, and current context. Use its existing authoritative documents and names; this package supplies a development method, not product truth.
2. Inspect relevant existing specifications, accepted decisions, operational context, and an existing systems.md for architecture, dependencies, and impacts. Resume from the appropriate stage. Use true-spec-worksheet when consequential product or architecture decisions remain unresolved; it prepares a provisional decision aid, not final definitions. Avoid reopening settled choices without cause. Then formalize explicitly accepted decisions into SPEC and/or SPECARC, sibling types with no fixed ordering. SPEC defines product/system requirements; SPECARC defines accepted architecture for a durable concern and may precede surrounding SPEC documents or a complete map. Respect the project's approval and precedence. Do not let an existing map override newly accepted higher product decisions or invent requirements to preserve old architecture.
3. After substantive SPEC or SPECARC creation or revision, review the complete current specification set. Include unaffected documents and both sibling types. Create or update systems.md when there is enough specification material for useful integration; record an early deferral rather than invent a meaningless map. Map governing specifications, required systems, state ownership, reads/writes, responsibilities, communication, interfaces, dependencies, data/control/event flows, lifecycles, and enforcing cross-system invariants. Record IDs/paths, versions or unversioned status, acceptance status, overlaps, conflicts, gaps, and whole-system coherence. Update the map when architecture, ownership, boundaries, dependencies, interfaces, flows, or cross-system behavior change. Preserve its established path or use the project's directory (default docs/systems/systems.md). Follow the handoff procedure. A SPECARC concern does not replace the complete-set map. Return missing decisions to their owners and refresh affected definitions and integration. Report a review that needs no meaningful map change without mechanically bumping its version.
4. Reuse existing owners and apply the project's standard and document versioning to specifications and systems.md. Sequence IDs remain identities: use dotted metadata such as Version: v3.1, keep the same ID and live path, and archive the complete predecessor with filename form _v3dot1.md when that revision is superseded. Retain SYS as project-defined system-level documentation and ADR as decision context/rationale; neither is automatically interchangeable with SPECARC. Load only the needed aid: True Specification template, Canonical Specification template, architecture specification template, systems map checklist, systems.md template, detailed system template, or increment checklist. Do not create every document for every task.
5. When implementation is in scope and the relevant layers are sufficiently settled, inspect implementation, tests, schemas, interfaces, and explanatory Git history. Use an adopted Feature Map for capability-level clauses, entrypoints, dependencies and verification navigation; preserve complete-set systems review and inspect original sources. Build an implementation plan from authority and repository reality, then use the plan and adversarial review rubric when complexity warrants review. Return missing product decisions to the owning specification layer.
6. For authorized implementation, use bounded units through the agent execution loop and workbranch rule. Use maintained verification tools when repeated nontrivial procedures warrant them. Check affected map/tool freshness after relevant changes. Verify actual behavior, repair narrowly, and keep the three-failure escalation boundary. Do not reinterpret product truth to simplify code. Preserve the specification/prototype boundary; apply the architecture discrepancy trigger immediately, independently of the three-failure ceiling.
7. Prepare human acceptance guidance where the project reserves final acceptance to a human owner. Report agent verification and human acceptance separately.

When a downstream layer exposes an upstream error, correct the smallest authoritative unit, propagate its effects forward, and repeat affected review. Keep project-specific decisions in the adopting repository.

For implementation and verification, apply the no-code-comments rule; keep necessary explanations and reasoning in the owning specifications and review changed code and examples before completion.