Docflow

---
name: adopt
description: 'Add docflow to a repo that already has docs, without rewriting them. Adds missing config, folders, helpers, agent guidance, and an adoption review. Use when docs already exist or doctor recommends adopt.'
---

# adopt

Goal: preserve existing docs, add missing docflow infrastructure.

## Steps

1. Run doctor:
   ```bash
   bash scripts/docflow-doctor.sh --target <REPO ROOT>
   ```

2. Choose docs root:
   - Use detected docs root if present.
   - Else use `docs`.

3. Choose project name:
   - Prefer README H1.
   - Else repo folder name.

4. Run adopt:
   ```bash
   bash scripts/docflow-adopt.sh --target <REPO ROOT> --docs-root <DOCS_ROOT> --project "<PROJECT NAME>"
   ```

5. Report created/skipped files and point at the adoption review doc.

## Rules

- Never move/delete/rewrite existing docs.
- Existing root guidance files are preserved.
- Run `/docflow:repair` after manual cleanup.

---
name: author
description: 'Write a new doc in the right place with the right name. Use when asked to "write a doc", "where should this doc go", "add an ADR", "document this decision", "new spec", or "new feature plan".'
---

# author

Author docs the docflow way: **choose category → apply naming → fill template → cross-link.** Companion of [`router`](../router/SKILL.md) (read side) and [`changelog`](../changelog/SKILL.md) (history). Templates live in the plugin's `templates/` dir; `/docflow:init` drops them into a repo.

> A doc's filename should tell a teammate **what** + **when** without opening it. If it can't, rename.

## Writing style (enforce on every doc)
Direct, tech + business. No filler.
- Tables and bullets over paragraphs. One claim per line.
- Lead with the outcome/decision; cut "this document describes…", "in order to", "it is important to note".
- Concrete: names, paths, numbers, commit hashes. No adjectives that carry no info.
- Each section earns its place — if a placeholder stays empty, delete the section.
- Max one short intro line per doc; the structure does the rest.

---

## 1 — Pick the category (what is this doc?)

| The doc answers… | Category | Folder |
|------------------|----------|--------|
| WHAT a feature does (user-facing) | product spec | `product-spec/` |
| HOW it's built (data flow, API contract, lifecycle) | technical spec | `specs/` |
| WHY we chose an approach | decision (ADR) | `decisions/` |
| HOW to do X / a convention / cheat sheet | reference | `references/` |
| WHAT's planned / status / roadmap | plan | `plans/` (`features/`, `hygiene/`, `upcoming/`) |
| Current quality / known bugs / audit | review | `reviews/` (`active/`, `archive/`, `bugs/`) |
| WHAT shipped, by month | changelog | `changelog/` — see [`changelog`](../changelog/SKILL.md) |

One doc, one category. If it spans two, it's two docs that **cross-link**.

---

## 2 — Apply the naming pattern

| Folder | Pattern | Example |
|--------|---------|---------|
| `product-spec/` | `NN-topic.md` (stable, reading order) | `04-jobs.md` |
| `specs/` | `(mmm-yy)-topic.md` (dated snapshot) | `(apr-26)-tab-system-workflow.md` |
| `references/` | `topic.md` (stable) | `newtable-component.md` |
| `decisions/` | `NNNN-title.md` (monotonic, never reused) | `0001-url-as-state.md` |
| `plans/features/` | `(mmm-yy)-feature-name.md` | `(apr-26)-create-job-stepper.md` |
| `plans/hygiene/` | `(mmm-yy)-topic.md` | `(apr-26)-codebase-cleanup.md` |
| `plans/upcoming/` | rolling roadmap, no dates | `critical.md`, `now.md`, `next.md`, `later.md` |
| `reviews/active/`,`archive/` | `(mmm-yy)-topic.md` | `(may-26)-tab-system.md` |
| `changelog/` | `(mmm-yy).md` | `(may-26).md` |

Rules:
- **kebab-case** always — never `camelCase` or `snake_case`.
- **`(mmm-yy)-` prefix** on dated docs: lowercase 3-letter month + 2-digit year — `jan feb mar apr may jun jul aug sep oct nov dec`.
- **Stable numbers** (`NN-`, `NNNN-`) for ordered series that are *not* snapshots — product-spec reading order, ADRs.
- **No redundant suffixes** — never `-feature.md`, `-spec.md`, `-doc.md`. Add a qualifier only when a sibling would otherwise collide (`tab-system-overview` + `tab-system-qa-guide`).
- **Topic prefix groups siblings** so they sort together (`(apr-26)-tab-system-*`).

---

## 3 — Fill the template (or generate a draft from code)

**Don't start specs/plans from blank** — generate a draft from the real repo, then verify:
- Spec: `bash scripts/docflow-spec.sh <code-path>` → pre-fills files, exports (Architecture), types (Data), paths+verbs (API), hooks (Flow). You group + confirm + write Risks.
- Plan: `bash scripts/docflow-plan.sh --days 30` → backlog candidates from TODO/FIXME + git churn. You triage into horizons.

Both write drafts marked `<!-- auto -->`; curate before shipping. Then fill manually where heuristics can't reach:

Each category has a skeleton in the plugin's `templates/`. Key shapes:

**ADR** (`decisions/NNNN-title.md`):
```markdown
# NNNN — Title

> **Status:** proposed | accepted | superseded by [NNNN](...) | deprecated
> **Date:** YYYY-MM-DD
> **Deciders:** names/handles

## Context        — what forced the decision? constraints, prior pain
## Decision       — what we chose (one sentence, then detail)
## Consequences   — good / bad / what gets harder
## Alternatives considered  — each + why rejected
```
Write an ADR for: cross-cutting choices, non-obvious trade-offs, reversals (supersede the old one — never edit it). NOT for: version bumps, one-file refactors, taste.

**Spec** (`specs/(mmm-yy)-topic.md`): header block (`Module:` / `Route:` / `Branch:`), then numbered sections — architecture, data model, API surface, state, edge cases. Plus a `Related:` block linking plan + review + ADRs.

**Feature plan** (`plans/features/(mmm-yy)-name.md`): `Status` / `Owner` / `Surface` header, then `## What shipped` (table w/ commit refs) · `## In flight` · `## Queued`.

**Review** (`reviews/...`): `Last updated` / `Scope` header, scorecard table, P0/P1/P2 findings.

---

## 4 — Cross-link (no orphan docs)

Bidirectional. The chain that ties a feature together:

```
product-spec/NN-feature.md   (WHAT)
   ↕
specs/(mmm-yy)-feature.md     (HOW)  ──► decisions/NNNN-*.md  (WHY)
   ↕
plans/features/(mmm-yy)-feature.md  (STATUS)
   ↕
reviews/active/(mmm-yy)-feature.md  (QUALITY)
```

- Every spec ends with a `Related:` list (plan, review, ADRs).
- Every ADR links the specs/product-specs it affects.
- The docs-root `README.md` indexes everything — **add your new doc to it.**
- **Filenames with parentheses must be wrapped in angle brackets in links**, or the renderer breaks:
  `[text](<specs/(may-26)-file.md>)` — not `[text](specs/(may-26)-file.md)`.

---

## 5 — After writing

1. **Regenerate the map**: `bash scripts/docflow-map.sh <DOCS_ROOT>` → updates `<DOCS_ROOT>/INDEX.md` (the compact `path — purpose` tree every agent reads first). New doc needs a clear H1 — that becomes its one-liner.
2. Add the doc to the docs-root `README.md` index + the folder's own README if it has one.
3. Record the document change in `## Update Log` or the feature/changelog table.
4. Run `bash scripts/docflow-validate.sh --target <REPO ROOT>` and fix validation errors before reporting completion.
5. If a decision shipped or a plan item completed, reflect it in `changelog/` (see [`changelog`](../changelog/SKILL.md)).
6. On rename: update the file, `grep -rn "old-name\.md"` every cross-link, fix README entries, re-run the link check.

```bash
# link integrity — empty output = all local links resolve
bash scripts/check-links.sh <DOCS_ROOT>
```

---
name: changelog
description: 'Record shipped work in the monthly changelog (append-only). Use when something ships or when asked "what changed", "add to changelog", "release notes", or "what shipped this month".'
---

# changelog

The memory of the knowledge base. Every month gets one file; history is **append-only**. This is what the SessionStart hook surfaces so the agent starts each session knowing recent work. Pairs with [`author`](../author/SKILL.md) and [`router`](../router/SKILL.md).

> Golden rule: **never delete or rewrite shipped history.** Reversals get a *new* entry, not an edit.

## Writing style (enforce)
Direct, tech + business. No filler. Outcome first.
- Each entry = a small table (Outcome / Delivered / Business impact / Commits). No narrative paragraphs.
- Summary = 4 bullets max: release type, biggest business change, biggest technical change, prod risk/action.
- Concrete only: feature names, paths, hashes, numbers. Cut adjectives.

---

## 1 — One file per month

`changelog/(mmm-yy).md` — lowercase 3-letter month + 2-digit year: `(apr-26).md`, `(may-26).md`.
`changelog/README.md` is the index: a table of `| Month | Highlights |`, newest first.

Link to a month file (parens need angle brackets): `[may-26](<(may-26).md>)`.

---

## 2 — Anatomy of a month file

```markdown
# Month YEAR — <release / period title>

> Window: `<base>` (`hash`, date) → `<head>` (`hash`, date). Scope: `N` commits.

## Summary
- Release type: patch | feature | architectural
- Biggest business change: <one line>
- Biggest technical change: <one line>
- Risk / action for prod: <one line>

## What Changed

### 1. <Feature / theme>
| | |
|---|---|
| Outcome | <one line> |
| Delivered | <bullet; bullet> |
| Business impact | <one line> |
| Commits | `<hash>` <desc>; `<hash>` <desc> |

### 2. <next theme>
```

A reader skimming the `Outcome` rows alone should understand the release.

---

## 3 — The shipping flow (where changelog fits)

The roadmap (`plans/upcoming/`) and the changelog are two ends of one pipe:

```
plans/upcoming/{critical,now,next,later}.md   ── ships ──►   changelog/(mmm-yy).md
        (what's coming)                                        (what landed)
```

When something ships:
1. **Move** the line out of the `plans/upcoming/*` horizon — don't let shipped work linger there (it kills the roadmap's signal).
2. **Add / update** the entry in the current `changelog/(mmm-yy).md`.
3. **Cross-link**: the feature plan's `## What shipped` table references the changelog month; the ADR/spec stay linked from the plan.
4. If a known bug got fixed, move it from `reviews/bugs/open.md` to `reviews/bugs/fixed.md` with the commit ref.

`plans/upcoming/README.md` keeps a short "Recently shipped" pointer list to the last few months — **pointers only, no restating**.

---

## 4 — Generating an entry from git

To build a month/release entry, diff the two refs and group commits by theme:

```bash
# commits in head not yet in base, newest first
git log --no-merges --pretty='%h %ad %s' --date=short BASE..HEAD
# count for the scope line
git rev-list --count --no-merges BASE..HEAD
```

Then: cluster commits into 3–8 themes → write a `### N. Theme` block each → fill outcome / delivered / why / commits → write the Executive Summary last (it summarizes the blocks).

---

## 5 — Why append-only matters

The changelog is the project's long-term memory. An agent (or a new teammate) that reads the newest one or two month files gets the recent trajectory: what was built, why it mattered, which commits. Editing or pruning old months erases that trail. Superseded decisions are recorded as *new* lines that reference the old — the history of the change is itself information.

---
name: check
description: 'Friendly docflow readiness check: one status, one reason, and the exact next command. Use when asked if docflow is set up, ready, or "what do I do next".'
---

# check

Goal: answer "is this usable and what do I do next?" in one screen.

## Run

```bash
bash scripts/docflow-check.sh --target <REPO ROOT>
```

If running from an installed plugin where scripts are not in the target repo, use the plugin script path.

## Interpret

| Status | Meaning | Next |
|--------|---------|------|
| `Ready` | DocFlow is installed and validation is clean | Start normal docs work |
| `Needs setup` | No meaningful docs or config detected | `/docflow:init` |
| `Needs adoption` | Existing docs need docflow infrastructure | `/docflow:adopt` |
| `Needs repair` | Generated helpers/guidance are missing or managed helpers are outdated | `/docflow:repair` |
| `Blocked` | Validation found hard errors | `/docflow:validate` |

## Rules

- Use this before asking the user to choose a setup path.
- Keep the response short: status, reason, next command.
- Do not run mutating commands from this skill; hand off to the matching skill.

---
name: doctor
description: 'Read-only docflow diagnosis: scans docs, config, changelog, and links, then recommends init, adopt, or repair. Use when asked "check docs setup", "should I set up docflow", "why is docflow not working", or "doctor".'
---

# doctor

Goal: inspect before changing anything. This skill is read-only.

## Run

```bash
bash scripts/docflow-doctor.sh --target <REPO ROOT>
```

If running from an installed plugin where scripts are not in the target repo, use the plugin script path.

## Interpret the recommendation

- `docflow-init` = no meaningful docs found; scaffolding is safe → run `/docflow:init`.
- `docflow-adopt` = docs/README already exist; preserve them → run `/docflow:adopt`.
- `docflow-repair` = docflow exists; regenerate map/check links → run `/docflow:repair`.
- `validation: fail` = docs have blockers; run `/docflow:validate` for details.

## Report

Use these headings: `Status`, `Detected`, `Missing`, `Risks`, `Recommended next command`.

## Rules

- Do not edit files.
- Do not run scaffold/adopt/repair.
- Keep output concise and copy the doctor's section headings.

---
name: init
description: 'Set up docflow in a repo with no docs yet: scaffold the docs tree, write docflow.json, add agent guidance. Use when asked to "set up docflow", "initialize docs", "scaffold docs", or "make this repo use docflow".'
---

# init

Goal: initialize docflow only when doctor says this repo has no meaningful docs yet. Keep existing user-authored files; generated maintenance files may be refreshed.

## Steps

1. Run doctor first.

```bash
bash scripts/docflow-doctor.sh --target <REPO ROOT>
```

2. Route by recommendation.
   - `docflow-init`: continue.
   - `docflow-adopt`: stop and run `/docflow:adopt` instead (preserves existing docs).
   - `docflow-repair`: stop and run `/docflow:repair` instead.

3. Pick docs root.
   - Use `docs/` unless the user explicitly chooses another root.

4. Pick project name.
   - Prefer repo folder name.
   - If root `README.md` has clear project title, use that.

5. Run scaffold from plugin root (idempotent; skips existing user content, refreshes generated files):

```bash
bash scripts/scaffold.sh --docs-root <DOCS_ROOT> --project "<PROJECT NAME>" --target "<REPO ROOT>"
```

This creates the category tree, drops templates, writes `docflow.json`, and scaffolds `AGENTS.md` + `GEMINI.md` + `.cursorrules`.

6. Add root README link if missing:
   - `## Documentation`
   - link to `<DOCS_ROOT>/README.md`

7. Seed the first changelog. Create `<DOCS_ROOT>/changelog/(mmm-yy).md` for the current month from the template, summarizing recent history (`git log --no-merges --pretty='%h %ad %s' --date=short -20`). Use the `changelog` skill for the format.

8. Regenerate the map and validate:
   ```bash
   bash scripts/docflow-map.sh "<REPO ROOT>/<DOCS_ROOT>"
   bash scripts/docflow-validate.sh --target "<REPO ROOT>"
   ```
   Fresh template placeholders are warnings; validation errors are blockers.

9. Report what was created (docs root, `docflow.json`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, validation status) and point the user at `/docflow:author` (writing), `/docflow:router` (reading), `/docflow:validate` (readiness), `/docflow:repair` (maintenance).

## Rules

- Never overwrite existing user-authored docs files.
- If docs already exist, prefer `/docflow:adopt` over `/docflow:init`.
- Keep `AGENTS.md` and `docflow.json` aligned on docs root.
- Follow the naming rules in `<DOCS_ROOT>/NAMING.md` for every file you create after.

---
name: repair
description: 'Safe maintenance for an existing docflow setup. Regenerates INDEX.md, installs or refreshes recognized DocFlow-managed helper scripts, runs link checks, and reports placeholder/validation issues. Use when docflow exists, after adding or renaming docs, or when doctor recommends repair.'
---

# repair

Goal: safe generated-file maintenance only.

## Run

```bash
bash scripts/docflow-repair.sh --target <REPO ROOT>
```

## It May Change

- `<DOCS_ROOT>/INDEX.md`
- missing helper scripts under `scripts/`
- existing helper scripts whose headers identify them as DocFlow-managed

## It Must Not Change

- README content
- product specs
- ADRs
- changelog months
- roadmap/plans
- existing project docs
- customized helper scripts without a DocFlow-managed header

Report broken links, placeholders, and validation warnings instead of fixing content unless the user asks.

---
name: router
description: 'Find the right doc before reading code. Use when asked "where is X documented", "is there a spec/ADR for X", "what''s the roadmap", "open bugs", "read the docs about X", or "share the docs".'
---

# router

Project-agnostic. No hardcoded tree — **discover, then route**. Works in any repo.

---

## 1 — Discover the docs (do this first, once per session)

Run a cheap scan to learn what this project has. Cache the result mentally for the session.

```bash
# docs roots + entry points
ls README* CONTRIBUTING* 2>/dev/null
fd -t d -d 2 -i 'docs?|spec|adr|decisions|wiki|reference' 2>/dev/null \
  || find . -maxdepth 3 -type d \( -iname 'docs' -o -iname 'spec*' -o -iname 'adr' -o -iname 'decisions' \) -not -path '*/node_modules/*'
# the markdown tree under the main docs dir (swap <DOCS> for what you found)
fd -e md . <DOCS> 2>/dev/null | head -80 || find <DOCS> -name '*.md' | head -80
```

If a hand-maintained index exists (`<DOCS>/README.md`, `SUMMARY.md`, `mkdocs.yml`, `docusaurus.config.*`), **read that** — it's the authoritative map. Don't rebuild what the maintainer already wrote.

---

## 2 — Route a question → one doc

Match the question's *shape* to a folder by its conventional name, then **Read that one doc**. Don't bulk-read the tree.

| Question shape | Look in (by conventional name) |
|----------------|-------------------------------|
| "What does feature X do?" (user-facing) | `product-spec/`, `docs/features/`, top-level `README` |
| "How is X implemented / data flow / API contract?" | `specs/`, `docs/architecture/`, `design/` |
| "Why did we choose X?" | `decisions/`, `adr/`, `docs/adr/` (ADR files) |
| "How do I do X / convention for X?" | `references/`, `docs/guides/`, `CONTRIBUTING.md` |
| "What's planned / status of X?" | `plans/`, `roadmap/`, `docs/roadmap/`, project board |
| "Known issues / open bugs?" | `reviews/bugs/`, `ISSUES.md`, GitHub issues |
| "What shipped recently?" | `CHANGELOG.md`, `changelog/`, releases |

If names don't match these, fall back to the discovered index from step 1.

### Rules
- Map question → doc → **Read** exactly that doc. Grep the tree only when no index resolves it.
- Docs reflect state *when written* (check dates / filenames) — verify against code before acting on stale detail.
- For how-to-*code* questions, prefer the project's own coding-rules / conventions doc over re-deriving from spec.
- Before fixing a bug, check the bug catalog / issues for an existing entry + severity.

---

## 3 — Share docs + this skill with collaborators (GitHub)

Three layers — do whichever the user asked for.

### A. Ship the skill in the repo (teammates auto-get it)
Project skills live at `.claude/skills/<name>/SKILL.md` and are **checked into git** — anyone who pulls + uses Claude Code gets them automatically, zero setup.

```bash
mkdir -p .claude/skills/router
cp ~/.claude/skills/router/SKILL.md .claude/skills/router/SKILL.md   # or author a project-tuned copy
git add .claude/skills/router && git commit -m "docs: add docs router skill"
```
- **Global** copy (`~/.claude/skills/`) = only you, every project.
- **Project** copy (`.claude/skills/` in repo) = whole team, this repo. Commit it to share.
- A project copy can hardcode the real tree (faster, no discovery) — keep this generic one global as the template.

### B. Make docs browsable on GitHub (no Claude Code needed)
- **Minimum:** a `<DOCS>/README.md` index with relative links to every doc — GitHub renders it; links are clickable in the web UI.
- **Link from root:** add a "## Documentation" section in the top-level `README.md` pointing at `<DOCS>/`.
- **Full site (optional):** GitHub Pages via MkDocs or Docusaurus, or a GitHub **Wiki** for free-form pages. Pages = versioned with code; Wiki = separate, easier for non-devs.

### C. Shareable onboarding link (Claude Code)
For a teammate who'll use Claude Code: create an `ONBOARDING.md` at repo root (point them at `<DOCS>/` + the skills), then use the **ShareOnboardingGuide** tool to upload it and get a link they open in Claude Code. Generic and project-agnostic.

---

## Reuse note
This skill is intentionally project-agnostic — it lives in `~/.claude/skills/` so it loads in every repo. To specialize it for one project, copy it into that repo's `.claude/skills/` and replace step 1's discovery with the project's actual doc tree (like a hand-written router).

---
name: validate
description: 'Run the profile-aware DocFlow documentation readiness gate. Always blocks broken links, stale maps, and missing headings; applies native naming and section rules strictly to new scaffolds while treating established adopted structures as cleanup guidance.'
---

# validate

Goal: block objectively broken documentation before an agent reports work as complete.

## Run

```bash
bash scripts/docflow-validate.sh --target <REPO ROOT>
```

If running from an installed plugin where scripts are not in the target repo, use the plugin script path.

## Interpret

- `Errors` are blockers. Fix them before saying the docs are complete.
- `Warnings` are legacy/adoption cleanup. Report them, but they do not block unless the user asked for a strict cleanup.
- Fresh scaffold placeholders are warnings because new repos intentionally start from templates.
- `strict` is the native scaffold profile; `adopted` preserves established naming and section vocabulary.

## Rules

- Run after `/docflow:author`, `/docflow:changelog`, `/docflow:repair`, or any manual docs edit.
- Regenerate `INDEX.md` before validation when files were added, renamed, or removed.
- Keep the output concise: status, blockers, warnings worth acting on.