| name | spec-writing |
| description | Guide for creating high-quality specifications for test. Use when starting a new SPEC or reviewing specs against architectural standards. |
Spec Writing & Review
Design and review specifications (SPECs) against Open Mercato architecture and quality rules.
Workflow
- Load Context: Read
AGENTS.md for module conventions and .ai/specs/ for existing specs.
- Initialize: Create
SPEC-{number}-{date}-{title}.md in .ai/specs/.
- Start Minimal: Write a Skeleton Spec (TLDR + 2-3 key sections). Do NOT write the full spec in one pass.
- Scan for critical unknowns — decisions that block data model, scope, or architecture.
- If unknowns exist, add a numbered Open Questions block (
Q1, Q2, …) after the TLDR.
- STOP after presenting the skeleton. Do not proceed until the user answers all questions.
- Iterate: Apply answers, remove Open Questions block. Repeat if new unknowns surface.
- Research: Challenge requirements against open-source market leaders.
- Design: Create architecture, data models, API contracts.
- Implementation Breakdown: Break into Phases (stories) and Steps (testable tasks).
- Review: Apply the Spec Checklist.
- Output: Finalize the specification file.
Output Formats
1. New Specification
Use the Specification Template. Adapt if needed, but ensure core concerns are addressed.
Required sections: TLDR, Problem Statement, Proposed Solution, Data Models, API Contracts, Risks, Changelog.
2. Architectural Review
# Architectural Review: {SPEC-0XX: Title}
## Summary
{1-3 sentences: what the spec proposes and overall health}
## Findings
### Critical
{Cross-module ORM, tenant isolation leaks, missing auth guards}
### High
{Missing undo logic, incorrect module placement, missing phase strategy}
### Medium
{Missing failure scenarios, inconsistent terminology}
### Low
{Style suggestions, nits}
Review Heuristics
- Command Graph vs. Independent Ops: Graph Save (coupled calculation) or Compound Command (independent steps)?
- Architectural Diff: Cut standard CRUD noise. Focus on what's unique.
- Singularity Law: Singular naming for entities, commands, events, feature IDs.
- Undo Contract: Is the "Undo" logic as detailed as the "Execute"?
- Module Isolation: Using Event Bus for side effects or cheating with direct imports?
Quick Rule Reference
- Singular naming for entities, commands, events, feature IDs.
- FK IDs only for cross-module links — no ORM relationships.
organization_id is mandatory for all tenant-scoped entities.- Undoability is the default for state changes.
- Zod validation for all API inputs.
Reference Materials
