Purpose
Consume an existing graphspec bundle as the source of truth for implementation, one unit of work at a time. The value this skill protects: pull the minimal subgraph relevant to the Component/System you're building right now — its Contracts, DataModels, Requirements, Constraints, and covering TestScenarios — instead of loading the entire bundle into context for every change.
Always invoke the CLI as npx graph-spec-cli … — that is the npm package name, and it needs no
prior install. The installed binary is named graphspec, so graphspec … also works wherever
the package is already installed or on PATH.
Workflow
Copy this checklist and track progress:
Spec-Driven Build Progress:
- [ ] 1. Bundle validated (trust but verify)
- [ ] 2. Coverage gaps surfaced and a decision made about them
- [ ] 3. Build order obtained
- [ ] 4. Per unit of work: targeted subgraph pulled and read
- [ ] 5. Per unit of work: covering test scenarios ported to real tests
- [ ] 6. Post-implementation: coverage gap closed, validate --strict still clean
1. Trust but verify
Before reading anything else, confirm the bundle is actually sound:
npx graph-spec-cli validate <path> --strict
If this reports errors or warnings, surface them to the user before proceeding — don't silently build on top of an unsound bundle (a filename/type mismatch, a bad enum value, or a relation to the wrong target type can all mean the graph doesn't mean what it appears to mean).
2. Check completeness
npx graph-spec-cli coverage <path>
This reports, by category: unsatisfied Requirements (nothing satisfies them), untested
Requirements/UserJourneys (nothing covers them), empty Features (no includes), unrealized
Features (nothing realizes them), dangling Constraints (nothing they constrain), orphan
concepts, and unresolved relation targets. npx graph-spec-cli coverage <path> --strict exits non-zero if
any gap exists at all — useful as a CI gate, less useful mid-build since real bundles commonly
have some gaps in flight.
Decide with the user up front: close the gaps that block this unit of work first, or proceed and track the rest. Don't assume — a dangling Constraint or an unsatisfied Requirement might be exactly what you're about to implement, or it might be scoped for later.
3. Get the build order
npx graph-spec-cli order <path>
This is the topological order of System/Component concepts from their depends-on edges —
each node listed after everything it depends on. Use this order, not file order or intuition,
to decide what to build first. A non-zero exit with reported cycles means the dependency graph
itself is broken; fix that before using the order.
4. Per unit of work: pull the targeted subgraph
For each Component/System in the order from step 3, pull only what it needs — don't re-read the
whole bundle per unit of work. Its outgoing relations (exposes, uses, satisfies,
depends-on) are the default --direction out walk:
npx graph-spec-cli graph <path> --from <component-id> --rel exposes,uses,satisfies --depth 1 --format json
This surfaces its Contracts (exposes), DataModels/Contracts (uses), and Requirements
(satisfies) in one shot. Read those specific concept files in full before writing any code
— the subgraph tells you what's connected, the files tell you what it actually says.
Direction note: constrains (Constraint → your concept) and covers (TestScenario → your
concept) originate at the annotator, not at your concept, so the default --direction out finds
nothing for them even when a real edge exists. Pull those with --direction in instead, which
walks the edge backward:
npx graph-spec-cli graph <path> --from <component-id> --rel constrains --direction in --depth 1
See references/traversal.md for the full relation-direction table and a verified example
against this repo's own bundle. Don't skip Constraints just because the default out direction
came back empty.
5. Pull the covering test scenarios
Before or while implementing, find the TestScenarios that cover this unit of work so you can port them into real automated tests (TDD-friendly: red before green):
npx graph-spec-cli graph <path> --from <component-id> --rel covers --direction in --depth 1
covers also originates at the annotator (the TestScenario), so this needs --direction in —
each other node in the result is a covering TestScenario id. Read its level
(unit/integration/e2e) and its # Given/When/Then body, and write the corresponding real test
before or alongside the implementation. npx graph-spec-cli query <path> --type TestScenario --json lists
every TestScenario's id/title/description if you want the full inventory first — note it does
not include relations, so confirming which one covers your unit still needs the graph --rel covers --direction in step above (or opening the file directly).
6. After implementing
Re-run both checks to confirm the targeted gap actually closed and nothing regressed:
npx graph-spec-cli coverage <path> # the gap you targeted should be gone
npx graph-spec-cli validate <path> --strict # must still be clean
If you added a Requirement/Component/relation while implementing, this is also when a drifted bundle would show up — fix the bundle (not just the code) before moving to the next unit of work in the order from step 3.
Worked example
EXAMPLE.md in this skill directory runs this exact workflow against this repo's own spec/
dogfood bundle — including a real coverage gap it surfaces and --direction in finding a
constrains/covers edge in practice — using one real Component
(architecture/validator.component) as the unit of work.
Reference
references/traversal.md has the full CLI flag reference, the complete relation table annotated
with traversal direction, and the order algorithm's tie-breaking behavior.