doc-flow

What this skill does

# doc-flow

## Purpose

Route the **Specification-Driven Development (SDD) workflow**: point at the
right skill for the task, report current position, enforce the
upstream-artifact policy. `doc-flow` never creates artifacts itself — the
artifact skills do.

**Layer**: cross-cutting (no upstream; routes into all 8 layers).
**Authoritative spec**: `${CLAUDE_PLUGIN_ROOT}/framework/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md`.

## When to Use

| Situation | Action |
|-----------|--------|
| Unsure which skill applies | Use `doc-flow` (this) |
| Brand-new project | `../project-init/SKILL.md` first, then `doc-flow` |
| Adopting SDD into existing code | `../project-adopt/SKILL.md` first |
| Editing a published artifact | `../doc-chg/SKILL.md` — not the linear flow |
| Single-layer end-to-end generation | that layer's `-autopilot` |

## The 8-layer flow

```
BRD (1) → PRD (2) → EARS (3) → BDD (4) → ADR (5) → SPEC (6) → TDD (7) → IPLAN (8) → Code
```

| Layer | Artifact | Purpose | Base skill |
|-------|----------|---------|-----------|
| 1 | BRD | Business requirements | `doc-brd` |
| 2 | PRD | Product requirements & KPIs | `doc-prd` |
| 3 | EARS | Formal WHEN-THE-SHALL requirements | `doc-ears` |
| 4 | BDD | Gherkin test scenarios | `doc-bdd` |
| 5 | ADR | Architecture decisions | `doc-adr` |
| 6 | SPEC | Technical specifications | `doc-spec` |
| 7 | TDD | Test-case definitions & thresholds | `doc-tdd` |
| 8 | IPLAN | Executable implementation plan | `doc-iplan` |

Each layer ships **four** skills: base (create), `-autopilot` (end-to-end),
`-audit` (gate report), `-fixer` (apply audit fixes).

## Skill selection

| You have | You need | Use |
|----------|----------|-----|
| Nothing | Business requirements | `doc-brd` |
| BRD | Product requirements | `doc-prd` |
| PRD | Formal requirements | `doc-ears` |
| EARS | Test scenarios | `doc-bdd` |
| BDD | Architecture decisions | `doc-adr` |
| ADR | Technical specifications | `doc-spec` |
| SPEC | Test-case definitions | `doc-tdd` |
| TDD | Implementation plan | `doc-iplan` |
| IPLAN | Code | Implement |
| Any stage | Supplementary docs | `doc-ref` |

**Intent → skill** (when the layer is clear, pick by verb):

| Action | Skill |
|--------|-------|
| create / draft | layer's base or `-autopilot` |
| audit / score | layer's `-audit` |
| fix / remediate | layer's `-fixer` |
| validate / trace / links / orphans | `../doc-validator/SKILL.md` |
| change a published artifact | `../doc-chg/SKILL.md` + `../gate-check/SKILL.md` |
| roadmap / phasing | `../adr-roadmap/SKILL.md` |
| scaffold / new project | `../project-init/SKILL.md` |
| adopt / brownfield | `../project-adopt/SKILL.md` |
| tailor / profile | `../project-profile/SKILL.md` |
| security / threats | `../security-audit/SKILL.md` |

When the user names a skill, run it directly.

## Where you are & what's next

**Where you are.** Scan `docs/<NN>_<X>/` for artifacts; read each Document
Control `Status` (most layers `Draft → In Review → Approved`; IPLAN
`Draft → In Progress → Completed`). Map to the project's **active** layers
(see *Adaptation*); report position + progress = terminal-status artifacts ÷
active layers.

**Template-conformance check (mandatory).** For every artifact found, load
`${CLAUDE_PLUGIN_ROOT}/framework/layers/<NN>_<X>/<TYPE>-TEMPLATE.yaml` and
verify every required top-level section appears as a `##` heading. Report
missing sections as **drift findings** (`Status` notwithstanding), e.g.
*"BRD-01 missing 6 of 18 required sections: …"*. **Do not** rationalise
drift as a "compact" variant, "documented walkthrough", or "lint-pinned"
exception — one template, one canonical section list. Lint passing is the
structural subset, not full template conformance. Recommend
`doc-<layer>-fixer` (or `-autopilot` for a re-author) to close gaps.

**What's next.** Recommend the next artifact per the cumulative chain
(each layer needs its prerequisite). Prioritise:

- **P0** — required upstream missing OR next step on the critical-path spine.
- **P1** — next ready layer once P0 is unblocked.
- **P2** — optional / parallel work (extra ADRs, `doc-ref` supplements).

Surface parallel-work opportunities (independent tracks with no shared
prerequisite); name the skill to run for each.

**Context scan (before authoring).** Rank candidate upstream documents for
the target type by directness, topic match, recency, and `Approved` status;
collect project vocabulary (titles, headings, glossary) so the new document
reuses real IDs and consistent terms.

## Utility skills

| Skill | Use for |
|-------|---------|
| `../project-init/SKILL.md` | Scaffold a new project (run before any layer) |
| `../project-adopt/SKILL.md` | Adopt SDD into an existing codebase (brownfield) |
| `../project-profile/SKILL.md` | Tailor the flow (optional; sets `.aidoc/profile.yaml`) |
| `../doc-naming/SKILL.md` | ID / naming authority (`TYPE-NN`, `TYPE.NN.SS.xxxx`) |
| `../doc-ref/SKILL.md` | Free-format reference documents (BRD-REF / ADR-REF) |
| `../doc-validator/SKILL.md` | Cross-document validation + bidirectional traceability + prose review |
| `../review-team/SKILL.md` | Multi-persona review mode for audits / fixers / autopilots |
| `../quality-advisor/SKILL.md` | Real-time authoring guidance for a single document |
| `../charts-flow/SKILL.md` | Mermaid diagrams and file management |
| `../adr-roadmap/SKILL.md` | Implementation roadmaps from ADRs |
| `../security-audit/SKILL.md` | Security review (OWASP/CWE, STRIDE) |

## Change management

Changes to already-published artifacts use the **CHG overlay**, not the
linear flow. `../doc-chg/SKILL.md` (+ `-autopilot` / `-audit` / `-fixer`)
classifies the change (C1–C3 / Emergency) and routes it to the right gate;
`../gate-check/SKILL.md` runs the gate (GATE-01/03/06/08/CODE, or
**GATE-SPEC** for `framework/` spec changes) and prepares the sign-off
form. A human approves — the skill never does.

## Upstream-artifact policy

Do **NOT** invent missing upstream artifacts. Every artifact must trace to
a real business/product justification.

| Situation | Action |
|-----------|--------|
| Upstream exists | Reference with its exact ID |
| Required upstream missing | Skip; report; advise creating it first |
| Optional upstream missing | `null` in the tag |
| Not applicable | Omit the tag |

## Validation model

Each skill **is** the validator (no runtime code). After each artifact,
run that layer's `-audit`; before moving on, confirm cumulative upstream
tags are present (PRD→1 … IPLAN→7).

## Adaptation

Read `.aidoc/profile.yaml`. Honor `active_layers`: a disabled skippable
layer (BDD / ADR) is excluded from the critical path, the progress
denominator, and next-step recommendations. Ignore unknown keys; absent
a profile, use the full 8-layer flow.
Authority: `${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md`.

## Reading bundled files

Skill paths use `${CLAUDE_PLUGIN_ROOT}/framework/…`. `CLAUDE_PLUGIN_ROOT`
is an **env var** Claude Code sets at install — never a literal folder
name. In a shell it expands (`cat "$CLAUDE_PLUGIN_ROOT/framework/…"`); if
unset, the `framework/` bundle ships beside `skills/` at the plugin root.
Never open the literal `${CLAUDE_PLUGIN_ROOT}` text.

## Related Resources

- Spec guide: `${CLAUDE_PLUGIN_ROOT}/framework/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md`
- Layer registry: `${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml`
- ID standards: `${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md`
- Traceability: `${CLAUDE_PLUGIN_ROOT}/framework/governance/TRACEABILITY.md`
- Governance core: `${CLAUDE_PLUGIN_ROOT}/framework/governance/DOC_GOVERNANCE_CORE.md`
- Authoring style: `${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md`
- Per-layer guidance: `${CLAUDE_PLUGIN_ROOT}/framework/layers/NN_<X>/README.md`