Create Requirements Specification

Create the spec.md and manage the requirements lifecycle.

Workflow

1. Initialize: Create spec.md from assets/spec-template.md.
2. Capture Requirements:
   • spec-write-str: Stakeholder needs.
   • spec-write-us: User stories.
3. Specify Behavior:
   • spec-us-to-fr: Derive FRs from stories.
   • spec-write-fr: System behavior.
   • spec-write-nfr: Quality constraints.
4. Define Domain Model:
   • Identify domain objects from master spec § 8-9.
   • Create typed FRs for entities, events, state machines, processes.
   • Create architecture FRs for API endpoints, queues, schemas, UI components.
   • Create operational FRs for configuration, migrations.
   • See spec-write-fr object-type-guide.md.
5. Verify Coverage:
   • spec-matrix: Test matrix.
6. Review (required):
   • spec-review: Validate quality.

Process

1. Check prerequisites:
   • Single Repo: spec/
   • Multi-Repo: specs/<category>/<component>/spec/
2. Copy template: assets/spec-template.md
3. Set frontmatter:
   • artifact_type: Must be master-requirements.
   • name: Component name matching the repo.
   • org: Organization owning the component.
   • component_type: Authoritative type (e.g., fastapi-service, react-lib).
   • tags: Optional capabilities (e.g., [postgres, sqlmodel]).
   • relationships: Structured array of relationship objects (target, type, cardinality). Do NOT use depends_on. Specify exact semantic linkages such as calls, implements, publishes, consumes, reads, writes, triggers, or requires.

[!IMPORTANT] Individual artifacts (FR, NFR, StR, US, IT) also require YAML frontmatter with id, title, and type. See each writing skill's Frontmatter section.

4. Customize: Processes, states, diagrams.
5. Apply component instructions from golden-path/components/<component-type>/agent-instructions.md.

Repository Structure

spec/
├── spec.md                     # Master specification
├── stakeholder/                # StR-XXX
├── usecase/                    # US-XXX
├── functional/                 # FR-XXX (behavioral + domain-typed)
├── non-functional/             # NFR-XXX
├── tests.md                    # Test Matrix
└── assets/                     # Diagrams, POCs

ID Schema

• Stakeholder: StR-XXX
• User Story: US-XXX
• Functional: FR-XXX
• Non-Functional: NFR-XXX
• Test Case: TC-XXX

Application-Type Specifications

[!IMPORTANT] When component_type: application, use assets/app-spec-template.md instead of assets/spec-template.md. The application spec standard is fundamentally different from a service or library spec.

What the Application Spec Owns

An application spec describes how multiple component repositories compose into a coherent system. It owns only cross-service concerns — things that cannot be expressed within any single component's spec.

What Stays at Service Level

• Per-endpoint API contracts (routes, schemas)
• Database schema and data models
• Per-service latency/throughput NFRs
• Events and signals (defined at service or domain level — never pulled to app level)
• Per-service error codes and test matrix
• Environment variables beyond shared/cross-service ones

Required Functional Requirements

For component_type: application, every spec MUST include:

Required Non-Functional Requirements

Reference Implementation

Refer to a known well-formed application spec in your org as a model when authoring a new one.