requirements-graph

Requirements Graph

Atomic, graph-structured requirements using the filesystem. Each acceptance criterion is a file. Each user story is a directory. Traces live in frontmatter. meta.md files aggregate for humans.

Why Graph Over Monolith

Monolith (old)	Graph (new)
200-260 line single file	10-30 line atomic nodes
Duplicates stories + functional reqs	One node per concept
Traceability in separate store	Traces in frontmatter
Grep for coverage	FTS5 + frontmatter queries
All-or-nothing context load	Progressive: frontmatter, meta.md, or full

Directory Layout

requirements/
  meta.md                             # Project-level summary
  {area}/                             # Epic/feature area (kebab-case)
    meta.md                           # Area summary + story table
    {US-NNN}/                         # User story directory
      meta.md                         # Story definition + AC table
      {AC-NNN}-{slug}.md             # Atomic acceptance criterion
    {NFR-NNN}-{slug}.md              # Non-functional requirements (area-level)
  _decisions/                         # ADR-style decision records
    {DEC-NNN}-{slug}.md
  _scope.md                           # In/out/future scope
  _risks.md                           # Risk register
  _questions.md                       # Open questions

Node Types

Five node types, each a small markdown file with YAML frontmatter:

Type	Lives at	Required fields
acceptance-criterion	{area}/{US-NNN}/{AC-NNN}-{slug}.md	id, type, priority, category, story
user-story	{area}/{US-NNN}/meta.md	id, type, priority, complexity, persona, status
area	{area}/meta.md	id, type
nfr	{area}/{NFR-NNN}-{slug}.md	id, type, priority, category, target
decision	_decisions/{DEC-NNN}-{slug}.md	id, type, status, date
requirements-root	meta.md	type, project, created, status

Minimal AC (the atomic unit):

---
id: auth/US-001/AC-001
type: acceptance-criterion
priority: P0
category: happy-path
story: auth/US-001
---

Given valid credentials
When user submits login form
Then user is redirected to dashboard and session is created

12 lines. See refs/schema.md for all fields and refs/examples.md for complete story, area, NFR, and decision examples.

Frontmatter Schema

Required fields (all node types):

• id — path-derived slug, canonical reference
• type — acceptance-criterion, user-story, area, nfr, decision, requirements-root

Required for ACs:

• priority — P0/P1/P2
• category — happy-path, error, edge-case, non-functional
• story — parent story slug

Required for stories:

• priority, complexity, persona, status

Optional (all types):

• traces — list of {target, type} objects (graph edges)
• tags — keyword list for search
• compliance — regulatory refs (SOC2, HIPAA, GDPR controls)

Trace types (edges):

• DECOMPOSES_TO — story to ACs
• TRACES_TO — requirement to design
• IMPLEMENTED_BY — AC to source code
• TESTED_BY — AC to test file
• VERIFIES — test result back to AC
• SATISFIES — evidence to requirement
• DEPENDS_ON — cross-story/cross-area dependency

Authoring Process

1. Initialize graph

Create requirements/ with root meta.md, _scope.md, _questions.md:

mkdir -p requirements
# Write root meta.md, _scope.md, _risks.md, _questions.md

2. Create areas from discovery

For each feature area, create requirements/{area}/meta.md.

3. Decompose into stories

For each story, create requirements/{area}/{US-NNN}/meta.md with the As a/I want/So that definition.

4. Write atomic ACs

For each acceptance criterion, create individual files: requirements/{area}/{US-NNN}/{AC-NNN}-{slug}.md

Keep AC files small: Given/When/Then + frontmatter. No essays.

5. Add traces as work progresses

Update traces: frontmatter as code and tests are written. Traces are bidirectional by convention — if AC-001 has IMPLEMENTED_BY: src/login.ts, the navigate skill can reverse-query.

Crew Integration

Crew Phase	Graph Action
clarify	Create requirements/ structure, areas, stories, ACs
design	Add TRACES_TO links from stories to design docs
build	Add IMPLEMENTED_BY links from ACs to code
test	Add TESTED_BY links from ACs to test files
review	Navigate skill generates fresh meta.md, gate checks coverage

Progressive Disclosure

• SKILL.md (this file): Overview, layout, schema, process
• refs/schema.md: Complete frontmatter reference with all fields
• refs/examples.md: Full worked examples for different project types