Story, Spec, and Traceability

VibePro treats Story and Spec as operating context for AI work. The Story names the intended change. The Spec captures behavior and constraints in a structure that VibePro can check against code, tests, and PR evidence.

Story workflow

Create or select a Story before asking an agent to change code:

vibepro story add . --id <story-id> --title "<title>"
vibepro story select . --id <story-id>
vibepro story status .

When the repository already contains work and you need candidates:

vibepro story derive . --run-graphify
vibepro story plan .
vibepro story map . --json

For a focused diagnosis:

vibepro story diagnose . --id <story-id> --run-graphify
vibepro story report . --id <story-id>

Spec workflow

Use a fingerprint to gather Story, code, test, and instruction context:

vibepro spec fingerprint . --id <story-id> --include-instructions > spec-fingerprint.json

Then write the generated Spec through VibePro so origin paths, patterns, and clause identifiers are validated:

vibepro spec write . --id <story-id> --from-stdin --caller codex < spec.json
vibepro spec show . --id <story-id>
vibepro spec drift . --id <story-id> --against origin/main

The Spec is not a contract humans must hand-write perfectly. It is a machine-checkable representation that helps VibePro detect drift.

Traceability

Traceability connects acceptance criteria to implementation, tests, and PR evidence.

vibepro trace backfill . --story-id <story-id> --dry-run
vibepro trace declare . --story-id <story-id> --lifecycle declared_not_started --reason "<reason>"

Use trace declare when a Story intentionally has no implementation yet. Use trace backfill when code or tests already exist and VibePro should bind them to the Story.

Narrative reports

For structured PR or decision narratives, use report fingerprints:

vibepro report fingerprint . --kind pr-body --id <story-id> --include-instructions
vibepro report write . --kind pr-body --id <story-id> --from-stdin --caller codex
vibepro report show . --kind pr-body --id <story-id>