irahardianto / structured-spec

Structured Spec

Specification documents that are readable by humans, writable by agents, and parseable by machines. Standard GitHub-Flavored Markdown plus typed annotations carried in HTML comments, so renderers ignore them and parsers don't have to guess.

Standard version 2.0.0. Every file in this directory is at 2.0.0; do not mix with v1 documents (see specification.md §9 to migrate one).

Use this skill when

• Writing or reviewing a PRD, SDD, implementation plan, TSD, BDD spec, or ADR
• Validating a spec's completeness or requirement traceability
• Migrating plain Markdown into the structured format
• Slicing a spec into work packages for multiple agents

Not for: ordinary prose docs, READMEs, or runbooks that have no requirements to trace.

Where to look

Read only what the task needs. These files do not repeat each other — each fact lives in exactly one place.

Pick the profile

doc_type is a closed set of seven. Choose by the question the document answers:

If the request spans several, write separate documents and link them via dependencies.specs. Do not merge a PRD and an SDD into one file.

When to consolidate vs separate

Not every project needs six documents. Use project scale to decide:

Rule of thumb: Start with one document. Separate when a section grows past what a single reader needs to scan (typically >15 scenarios for BDD, >10 endpoints for TSD, or when different audiences need different documents).

Phased delivery

For large features, use milestones in frontmatter and milestone fields on annotations to split delivery into phases:

1. Define milestones in frontmatter: milestones: [{name: "Phase 1: Core", target_date: "2026-09-01", status: "in-progress"}, ...]
2. Tag annotations with milestone: "Phase 1: Core" — requirements, contracts, tests, and tasks
3. Review per phase — completeness rules (§6.5) apply per milestone. Phase 2 requirements don't block Phase 1 approval.
4. Slice by milestone — orchestrators can dispatch Phase 1 tasks first, then Phase 2 after review

Annotations without a milestone field belong to all phases (backward compatible).

Document storage

Structured spec documents live under docs/ alongside other project documentation. Each document type has a prescribed location:

docs/
├── specs/                    ← PRDs, SDDs, TSDs, BDD specs, Implementation Plans
│   ├── prd-billing-export.md
│   ├── sdd-payment-service.md
│   ├── tsd-billing-api.md
│   ├── bdd-checkout-flow.md
│   └── plan-v2-migration.md
├── decisions/                ← ADRs (convention from `adr` skill)
│   ├── 0001-use-postgresql.md
│   └── 0002-adopt-feature-structure.md
├── research_logs/            ← Research findings (convention from `research-methodology` skill)
├── audits/                   ← Audit reports (convention from `code-review` skill)
└── debugging/                ← Debug investigations (convention from `debugging-protocol` skill)

File naming for specs: {doc_type}-{short-slug}.md (e.g., prd-billing-export.md, sdd-payment-service.md). The spec_id in frontmatter is the canonical identifier; the filename is for human navigation.

ADRs stay in docs/decisions/ — the adr skill owns that convention (NNNN-short-title.md numbering). Do not move ADRs to docs/specs/.

.agentwork/ is ephemeral — scope cards, handoffs, findings, and pipeline artifacts go there. Persisted specifications always go under docs/.

Workflow

1. Pick the profile from the table above. If genuinely ambiguous, ask; otherwise infer and state the choice.
2. Open profiles/<doc_type>.md for that profile's ID prefixes, section order, and extra rules.
3. Write frontmatter. Nine required fields. New documents start at status: draft.
4. Write the narrative. Plain Markdown. Context and reasoning that annotations cannot carry.
5. Add annotations immediately above what they describe — specification.md §4 for fields, taxonomy.md for type values.
6. Link once, from the child. Contracts, tests, architecture, SLOs, and decisions name the requirements they serve. Requirements never point back; the reverse index is derived. Adding a test never means editing a requirement.
7. Verify completeness against specification.md §6. Fix gaps before raising status above draft.

Minimum viable spec

Enough to be valid. Everything else is elaboration.

---
$schema: "https://raw.githubusercontent.com/irahardianto/awesome-agv/main/.agents/skills/structured-spec/spec-schema.json"
spec_id: "PRD-BILLING-EXPORT-V1"
title: "Billing Export"
doc_type: "prd"
status: "draft"
version: "0.1.0"
owners: ["platform-team"]
created: "2026-08-18"
modified: "2026-08-18"
---

# 1. Problem Context

Finance reconciles invoices by hand because usage data never leaves the platform.

<!-- requirement
  id: REQ-001
  title: Export daily usage as CSV
  priority: must
  category: functional
  rationale: Manual reconciliation costs the finance team two days per month
-->

Exports run nightly and cover the previous UTC day.

<!-- contract
  id: CT-API-001
  type: api-contract
  title: Usage export endpoint
  stack_category: application-code
  implements_requirements: [REQ-001]
-->

paths:
/exports/usage:
get:
parameters: [{ name: date, in: query, required: true, schema: { type: string, format: date } }]
responses: { "200": { description: CSV export } }

<!-- test
  id: TC-001
  type: acceptance-test
  title: Export returns the previous day's usage
  verifies_requirements: [REQ-001]
-->

Scenario: Export returns the previous day's usage
Given usage exists for 2026-08-17
When the client requests the export for 2026-08-17
Then the response is CSV containing that day's rows

Rules that are easy to get wrong

1. Link once, from the child. Never mirror a link on both ends — that is what made v1 documents contradict themselves.
2. Tests are not contracts. acceptance-test and integration-test are test types. A Gherkin block is never a <!-- contract -->.
3. Code contracts run as written. No pseudocode, no ... elisions inside a contract's code block.
4. IDs are unique per document and never renumbered once the status is approved — other specs cite them.
5. Annotations touch the content they describe, separated by at most one blank line.
6. draft is never blocked. Enforcement scales with status; see specification.md §6.3. Do not refuse to write a rough draft because it lacks tests.