spec-writing

An architecture spec template standardizes design documentation to reduce ambiguity and ensure traceable decisions. You need spec-writing when starting new SPEC initiatives or performing architectural reviews across Open Mercato projects to align with structural standards.

To write a technical spec, load context, initialize the SPEC skeleton, iterate through open questions, and research against benchmarks. This skill enforces templates for API contracts, data models, and phased implementation plans to ensure comprehensive design documentation.

Yes, you can use this spec-writing workflow for architectural reviews. It provides a built-in Spec Checklist and review workflow to evaluate existing SPECs, ensuring consistency across modules and verifying alignment with Open Mercato architectural standards.

You create a phased implementation plan by documenting user stories, defining data models, and establishing API contracts within the spec. The workflow includes risk assessment and changelog tracking to generate verifiable, auditable roadmaps from your design.

Yes, the spec checklist supports tracking open questions. The standardized workflow guides you through iterating on unresolved questions and researching against benchmarks before finalizing the implementation plan, ensuring all architectural gaps are addressed.

The best way to start a new spec document is to create a SPEC-0000.md skeleton in the .ai/specs/ directory. Begin with a TLDR and 2-3 key sections, then use the template guidance to expand into data models, API contracts, and implementation phases.