spec-management

Spec Management

This skill defines the canonical artifact types, phases, and hierarchy. The ER diagram below is the relationship summary; detailed definitions and templates live in references/ . If the host repo has an AGENTS.md, keep its artifact sections in sync with the skill's reference data.

Artifact relationship model

erDiagram VISION ||--o{ EPIC : "parent-vision" VISION ||--o{ JOURNEY : "parent-vision" EPIC ||--o{ SPEC : "parent-epic" EPIC ||--o{ STORY : "parent-epic" JOURNEY ||--|{ PAIN_POINT : "PP-NN" PAIN_POINT }o--o{ EPIC : "addresses" PAIN_POINT }o--o{ SPEC : "addresses" PAIN_POINT }o--o{ STORY : "addresses" PERSONA }o--o{ JOURNEY : "linked-personas" PERSONA }o--o{ STORY : "linked-stories" ADR }o--o{ SPEC : "linked-adrs" ADR }o--o{ EPIC : "linked-epics" SPEC }o--o{ SPIKE : "linked-research" SPEC ||--o| IMPL_PLAN : "seeds" RUNBOOK }o--o{ EPIC : "validates" RUNBOOK }o--o{ SPEC : "validates" BUG }o--o{ SPEC : "affected-artifacts" BUG }o--o{ EPIC : "affected-artifacts" BUG ||--o| IMPL_PLAN : "fix-ref" SPIKE }o--o{ ADR : "linked-research" SPIKE }o--o{ EPIC : "linked-research" SPIKE }o--o{ BUG : "linked-research" DESIGN }o--o{ EPIC : "linked-designs" DESIGN }o--o{ STORY : "linked-designs" DESIGN }o--o{ SPEC : "linked-designs" DESIGN }o--o{ BUG : "linked-designs"

EPIC {
    string parent_vision FK
    list success_criteria "required"
    list depends_on "optional"
}
JOURNEY {
    string parent_vision FK
    list linked_personas "optional"
}
SPEC {
    string parent_epic FK
    list linked_research "optional"
    list linked_adrs "optional"
    list addresses "optional"
}
STORY {
    string parent_epic FK
    list addresses "optional"
}
ADR {
    list linked_epics "optional"
    list linked_specs "optional"
}
PERSONA {
    list linked_journeys "optional"
    list linked_stories "optional"
}
RUNBOOK {
    list validates "required"
    string parent_epic "optional"
    string mode "agentic or manual"
    string trigger "required"
}
BUG {
    string severity "critical/high/medium/low"
    list affected_artifacts "optional"
    string discovered_in "required"
    string fix_ref "optional"
}
SPIKE {
    string question "required"
    string gate "required"
    list depends_on "optional"
}
DESIGN {
    string superseded_by "optional"
    list linked_epics "optional"
    list linked_stories "optional"
    list linked_specs "optional"
    list linked_bugs "optional"
    list depends_on "optional"
}
IMPL_PLAN {
    string origin_ref "SPEC-NNN"
    list spec_tags "mutable"
}

Key: Solid lines (||--o{ ) = mandatory hierarchy. Diamond lines (}o--o{ ) = informational cross-references. SPIKE can attach to any artifact type, not just SPEC. Any artifact can declare depends-on: blocking dependencies on any other artifact.

Stale reference watcher

The specwatch.sh script monitors docs/ for stale references. It checks two things:

Markdown link paths — text links where the target no longer exists. Suggests corrections by artifact ID lookup.
Frontmatter artifact references — all depends-on , parent-* , linked-* , addresses , validates , affected-artifacts , superseded-by , and fix-ref fields. For each artifact ID, resolves to a relative file path and checks both existence and semantic coherence (target in Abandoned/Rejected state, phase mismatches where the source is significantly more advanced than the target).

Script location: scripts/specwatch.sh (relative to this skill)

Subcommands:

Command What it does

scan

Run a full stale-reference scan (no watcher needed)

watch

Start background filesystem watcher (requires fswatch )

stop

Stop a running watcher

status

Show watcher status and log summary

touch

Refresh the sentinel keepalive timer

Log format: Findings are written to .agents/specwatch.log in a structured format. This file is a runtime artifact — add specwatch.log to your .gitignore if it isn't already.

STALE <source-file>:<line> broken: <relative-path-as-written> found: <suggested-new-path> artifact: <TYPE-NNN>

STALE_REF <source-file>:<line> (frontmatter) field: <frontmatter-field-name> target: <TYPE-NNN> resolved: NONE issue: unresolvable artifact ID

WARN <source-file>:<line> (frontmatter) field: <frontmatter-field-name> target: <TYPE-NNN> resolved: <relative-path-to-target> issue: <target is Abandoned | source is X but target is still Y>

Post-operation scan

After every artifact operation (create, edit, transition, audit), run scripts/specwatch.sh scan to catch any stale references introduced by the changes. If .agents/specwatch.log reports stale references, surface them as warnings and fix them before committing. The scan has no external dependencies — it uses only Python 3 and the filesystem.

The background watch mode (requires fswatch ) is available for long-running sessions but is not part of the default workflow.

Dependency graph

The specgraph.sh script builds and queries the artifact dependency graph from frontmatter. It caches a JSON graph in /tmp/ and auto-rebuilds when any docs/*.md file changes.

Script location: scripts/specgraph.sh (relative to this skill)

Subcommands:

Command What it does

overview

Default. Hierarchy tree with status indicators + execution tracking

build

Force-rebuild graph from frontmatter

blocks <ID>

What does this artifact depend on? (direct dependencies)

blocked-by <ID>

What depends on this artifact? (inverse lookup)

tree <ID>

Transitive dependency tree (all ancestors)

ready

Active/Planned artifacts with all deps resolved

What to work on next (ready items + what they unblock, blocked items + what they need)

mermaid

Mermaid diagram to stdout

status

Summary table by type and phase

Run blocks <ID> before phase transitions to verify dependencies are resolved. Run ready to find unblocked work. Run tree <ID> for transitive dependency chains.

Lifecycle table format

Every artifact embeds a lifecycle table tracking phase transitions:

Lifecycle

Phase	Date	Commit	Notes
Planned	2026-02-24	abc1234	Initial creation
Active	2026-02-25	def5678	Dependency X satisfied

Commit hashes reference the repo state at the time of the transition, not the commit that writes the hash stamp itself. Commit the transition first, then stamp the resulting hash into the lifecycle table and index in a second commit. This keeps the stamped hash reachable in git history.

Index maintenance

Every doc-type directory keeps a single lifecycle index (list-<type>.md ). Refreshing the index is the final step of every artifact operation — creation, content edits, phase transitions, and abandonment. No artifact change is complete until the index reflects it.

What "refresh" means

Read (or create) docs/<type>/list-<type>.md .
Ensure one table per active lifecycle phase, plus a table for each end-of-life phase that has entries.
For the affected artifact, update its row: title, current phase, last-updated date, and commit hash of the change.
If the artifact moved phases, remove it from the old phase table and add it to the new one.
Sort rows within each table by artifact number.

When to refresh

Operation Trigger

Create artifact New row in the appropriate phase table

Edit artifact content or frontmatter Update last-updated date and commit hash

Transition phase Move row between phase tables

Abandon / end-of-life Move row to the end-of-life table

This rule is referenced as the index refresh step in the workflows below. Do not skip it.

Auditing artifacts

Audits touch every artifact, so always parallelize with sub-agents — serial auditing is too slow and misses the cross-cutting checks that only make sense when run together. Spawn four agents in a single turn:

Agent Responsibility

Lifecycle auditor Check every artifact in docs/ for valid status field, lifecycle table with hash stamps, and matching row in the appropriate list-<type>.md index.

Cross-reference checker Verify all parent-* , depends-on , linked-* , and addresses frontmatter values resolve to existing artifact files. Flag dangling references.

Naming & structure validator Confirm directory/file names follow (TYPE-NNN)-Title convention, templates have required frontmatter fields, and folder-type artifacts contain a primary .md file.

Phase/folder alignment Run specwatch.sh phase-fix to detect and move artifacts whose frontmatter status: doesn't match their phase subdirectory. Review the staged git mv renames and commit.

Dependency coherence auditor Validate that depends-on edges are logically sound, not just syntactically valid. See checks below.

The dependency coherence auditor catches cases where the graph exists but is wrong. The cross-reference checker confirms targets resolve to real files; this agent checks whether those edges still make sense. Specific checks:

Dead-end dependencies — depends-on targets an Abandoned or Rejected artifact. The dependency can never be satisfied; flag it for removal or replacement.
Orphaned satisfied dependencies — depends-on targets a Complete/Implemented artifact but the dependent is still in Draft/Proposed. The blocker is resolved — is the dependent actually stalled for a different reason, or should it advance?
Phase-inversion — A dependent artifact is in a later lifecycle phase than something it supposedly depends on (e.g., an Implemented spec that depends-on a Draft spike). This suggests the edge was never cleaned up or was added in error.
Content-drift — Read both artifacts and assess whether the dependency relationship still holds given what each artifact actually describes. Artifacts evolve; an edge that made sense at creation time may no longer reflect reality. Flag edges where the content of the two artifacts has no apparent logical connection.
Missing implicit dependencies — Scan artifact bodies for references to other artifact IDs (e.g., "as decided in ADR-001" or "builds on SPIKE-003") that are not declared in depends-on or linked-* frontmatter. These are shadow dependencies that should be formalized or explicitly noted as informational.

For checks 4 and 5, the agent must actually read artifact content — frontmatter alone is not sufficient. Present findings as a table with: source artifact, target artifact, check type, evidence (quote or summary), and recommended action (remove edge, add edge, update frontmatter, or investigate).

Each agent reports gaps as a structured table with file path, issue type, and missing/invalid field. Merge the tables into a single audit report. Always include a 1-2 sentence summary of each artifact (not just its title) in result tables.

Enforce definitions, not current layout. The artifact definition files (in references/ ) are the source of truth for folder structure. If the repo's current layout diverges from the definitions (e.g., epics in a flat directory instead of phase subdirectories), the audit should flag misplaced files and propose git mv commands to bring them into compliance. Do not silently adopt a non-standard layout just because it already exists.

Status overview

When the user asks for status, progress, or "what's next?", default to showing both spec-management and execution-tracking layers unless they specifically ask for only one. The overview command is the single entry point.

specgraph.sh overview (primary — use this by default)

Renders a hierarchy tree in the terminal showing every artifact with its status, blocking dependencies, and execution-tracking progress:

✓ VISION-001: Personal Agent Patterns [Active] ├── → EPIC-007: Spec Management System [Active] │ ├── ✓ SPEC-001: Artifact Lifecycle [Implemented] │ ├── ✓ SPEC-002: Dependency Graph [Implemented] │ └── → SPEC-003: Cross-reference Validation [Draft] │ ↳ blocked by: SPIKE-002 └── → EPIC-008: Execution Tracking [Proposed]

── Cross-cutting ── ├── → ADR-001: Graph Storage Format [Adopted] └── → PERSONA-001: Solo Developer [Validated]

── Execution Tracking ── (bd status output here)

Status indicators: ✓ = resolved (Complete/Implemented/Adopted/etc.), → = active/in-progress. Blocked dependencies show inline with ↳ blocked by: . Cross-cutting artifacts (ADR, Persona, Runbook, Bug, Spike) appear in their own section. The execution-tracking tail calls bd status automatically.

Display rule: Present the specgraph.sh overview output verbatim — do not summarize, paraphrase, or reformat the tree. The script's output is already designed for human consumption. You may add a brief note after the output only if the user asked a specific question (e.g., "what should I work on next?").

spec-management

Safety Notice

Copy this and send it to your AI assistant to learn

Lifecycle

Source Transparency

Related Skills

swain-do

swain-push

swain-design

swain-update