v0.3.0: slash commands in correct folder + orchestration skills + review-delta ADR

.claude/skills/docops/.docops-manifest → .claude/commands/docops/.docops-manifest

@@ -1,10 +1,19 @@
 # docops manifest — files in this directory owned by `docops upgrade`.
 # Do not hand-edit; rerun `docops upgrade` to regenerate.
 audit.md
+close.md
+do.md
+get.md
+graph.md
 init.md
+list.md
 new-adr.md
 new-ctx.md
 new-task.md
+next.md
+plan.md
+progress.md
 refresh.md
+search.md
 state.md
 upgrade.md

.claude/commands/docops/close.md

@@ -0,0 +1,42 @@
+---
+name: close
+description: Finish a task — flip status to done, refresh DocOps state, and stage a commit. Use when the user says "done with TP-X" / "mark TP-X complete".
+---
+
+# /docops:close
+
+Close out a finished task.
+
+Ask for the task ID if not provided. Then:
+
+1. Verify the task's acceptance criteria are actually met. Read the
+   task body, check for remaining TODOs, and (if code changed)
+   eyeball the diff. If something is incomplete, stop and tell the user.
+
+2. Flip the task's `status:` frontmatter to `done` via `Edit` on the
+   source file — do not hand-edit the index.
+
+3. Run:
+
+```
+docops refresh
+```
+
+4. Stage every file relevant to the task (source changes + task
+   frontmatter + `docs/.index.json` + `docs/STATE.md`), then propose a
+   commit message of the form:
+
+   ```
+   <TP-ID>: <one-line summary of what shipped>
+
+   <one or two sentences on what actually changed and why, pulled from
+   the task's Goal + Acceptance>
+   ```
+
+   Confirm with the user before committing. Never commit without their
+   explicit OK.
+
+5. After the commit, run `/docops:progress` to surface the next move.
+
+Do not mark a task `done` just because citing files changed — the
+acceptance list is the contract.

.claude/commands/docops/do.md

@@ -0,0 +1,32 @@
+---
+name: do
+description: Route a freeform natural-language intent to the right /docops:* skill. Use when the user knows what they want but doesn't know which command runs it.
+---
+
+# /docops:do
+
+Interpret the user's request and dispatch to one matching skill.
+Never do the work yourself — confirm the match, then hand off.
+
+Routing table (intent → skill):
+
+| Intent | Skill |
+|---|---|
+| "where are we", "what's the status", "summarise" | `/docops:progress` |
+| "what's next", "pick a task" | `/docops:next` |
+| "add a decision", "record that choice", "I need an ADR" | `/docops:new-adr` |
+| "capture a PRD", "memo", "save constraints", "research note" | `/docops:new-ctx` |
+| "add a task", "track this work", "create a TP" | `/docops:new-task` |
+| "find X", "search for Y" | `/docops:search` |
+| "look up ADR-0012" | `/docops:get` |
+| "what depends on ADR-X", "blast radius" | `/docops:graph` |
+| "list draft ADRs", "active tasks" | `/docops:list` |
+| "what's broken", "coverage gaps" | `/docops:audit` |
+| "finish TP-X", "mark done", "close this task" | `/docops:close` |
+| "plan from CTX-X", "draft decision + tasks" | `/docops:plan` |
+| "upgrade docops files", "refresh scaffolding" | `/docops:upgrade` |
+| "validate", "reindex", "regenerate state" | `/docops:refresh` |
+
+Match on intent, not literal wording. If two skills could fit, ask one
+short clarifying question. If nothing matches, say so — do not invent a
+command.

.claude/commands/docops/get.md

@@ -0,0 +1,21 @@
+---
+name: get
+description: Look up a single DocOps doc by ID (ADR-nnnn, CTX-nnn, TP-nnn) and print its indexed record. Use when you need the frontmatter and edges for one doc without reading the full file.
+---
+
+# /docops:get
+
+Fetch one indexed doc by ID.
+
+```
+docops get ADR-0010
+docops get TP-029 --json
+```
+
+The plain output shows title, status, coverage/priority, dates, and both
+forward and reverse edges (computed). `--json` returns the full
+`IndexedDoc` — use it when scripting or when you need the exact edge
+shape.
+
+When a user pastes an ID into chat, run `docops get <ID>` first to
+orient before reading the full file.

.claude/commands/docops/graph.md

@@ -0,0 +1,22 @@
+---
+name: graph
+description: Walk the typed edge graph outward from one doc to its neighbours (requires, related, supersedes, reverse edges). Use to understand "what depends on what" before touching an ADR or task.
+---
+
+# /docops:graph
+
+Print the typed edge graph starting at one doc.
+
+```
+docops graph ADR-0010
+docops graph ADR-0010 --depth 2
+docops graph TP-029 --json
+```
+
+`--depth N` (default 1) controls traversal depth. Depth 1 shows direct
+neighbours; higher depths show transitive closure. Edges include both
+source fields (`requires`, `related`, `supersedes`, `depends_on`) and
+computed reverse edges (`required_by`, etc. — see ADR-0006).
+
+Use this before superseding an ADR or removing a task: the graph shows
+every doc that would break.

.claude/skills/docops/init.md → .claude/commands/docops/init.md

@@ -20,7 +20,7 @@ What it does:
 - Writes JSON Schemas to `docs/.docops/schema/` for in-editor validation.
 - Writes or refreshes the `<!-- docops:start -->` block inside `AGENTS.md` and `CLAUDE.md` (both files share the same docops block; Claude Code reads CLAUDE.md by default while other agents read AGENTS.md).
 - Installs a language-agnostic pre-commit hook that runs `docops validate`.
-- Scaffolds `/docops:*` skills into `.claude/skills/docops/` and `.cursor/commands/docops/`.
+- Scaffolds `/docops:*` slash commands into `.claude/commands/docops/` and `.cursor/commands/docops/`.
 
 Flags:
 

.claude/commands/docops/list.md

@@ -0,0 +1,26 @@
+---
+name: list
+description: List DocOps docs with optional filters (kind, status, coverage, tag, stale, since). Use when looking for a set of docs, not one — e.g. "all draft ADRs", "all active tasks".
+---
+
+# /docops:list
+
+Enumerate docs with filters. Prefer this over reading `docs/.index.json`
+directly.
+
+```
+docops list --kind ADR --status draft
+docops list --kind TP --status active
+docops list --kind ADR --coverage required
+docops list --tag release
+docops list --stale
+docops list --since 2026-04-01
+docops list --json
+```
+
+Filters compose (AND). `--status` semantics are per-kind:
+- ADR: `draft`, `accepted`, `superseded`, `rejected`
+- TP: `backlog`, `active`, `done`
+- CTX: has no status; `--status` with `--kind CTX` is invalid
+
+Default output is a table. Use `--json` for scripting.

.claude/commands/docops/next.md

@@ -0,0 +1,27 @@
+---
+name: next
+description: Ask DocOps which task to pick up next. Uses assignee, priority, status, and depends_on to recommend one task. Use at session start or after finishing a task.
+---
+
+# /docops:next
+
+Find the next task to work on.
+
+```
+docops next
+```
+
+Filter when the project has multiple contributors or priority bands:
+
+```
+docops next --assignee nachiket
+docops next --priority p0
+docops next --json
+```
+
+The CLI picks one task by descending priority (p0 → p2), then ascending
+ID among tasks with no unmet `depends_on`. If no task matches, exit code
+is non-zero and stderr says `no task matches`.
+
+After selecting a task, read every doc in its `requires:` and
+`depends_on:` before writing code.

.claude/commands/docops/plan.md

@@ -0,0 +1,51 @@
+---
+name: plan
+description: Given a CTX (PRD, memo, research note), draft one ADR and one or more tasks that cite it. Human-confirmed before write. Use when turning stakeholder input into actionable work.
+---
+
+# /docops:plan
+
+Convert context into a decision plus tasks.
+
+Ask for the CTX ID if not provided. Read it, then draft:
+
+1. **One ADR** capturing the decision the CTX implies or demands. Propose
+   title, Context/Decision/Rationale/Consequences body. Confirm with the
+   user before writing.
+
+2. **One or more tasks** that cite the ADR. Each task should carry
+   priority, an acceptance checklist, and (if relevant) a depends-on
+   reference to other tasks. Confirm the full set before writing.
+
+Write via `--body -` heredocs so drafts land populated on creation (no
+stub-then-rewrite round-trip):
+
+```
+docops new adr "Title" --related ADR-xxxx --body - <<'EOF'
+## Context
+...
+## Decision
+...
+## Rationale
+...
+## Consequences
+...
+EOF
+
+docops new task "Title" --requires ADR-0026 --priority p1 --body - <<'EOF'
+## Goal
+...
+## Acceptance
+- ...
+EOF
+```
+
+After all writes, run `docops refresh` to regenerate index and STATE.md.
+
+Rules:
+
+- Every task must cite ≥1 ADR or CTX in `requires:`. If the user cannot
+  name a citation, stop and draft the missing ADR/CTX first.
+- Keep ADR `status: draft` unless the user explicitly accepts it.
+- Don't write anything the user hasn't confirmed. Show proposed
+  frontmatter and body summary, then ask.

.claude/commands/docops/progress.md

@@ -0,0 +1,28 @@
+---
+name: progress
+description: Situational awareness — read STATE.md, run audit, and name the next action in one go. Use at session start or when the user asks "where are we?" / "what's next?".
+---
+
+# /docops:progress
+
+Summarise project state and recommend one next action.
+
+Run these, in order:
+
+```
+docops state
+docops audit
+docops next
+```
+
+Then produce a single short briefing:
+
+- **Counts:** doc totals and anything in needs-attention from STATE.md.
+- **Active work:** tasks currently `status: active` (from `docops list --kind TP --status active --json`).
+- **Audit gaps:** one line per finding; skip if audit is empty.
+- **Next task:** whatever `docops next` picked, with its `requires:` IDs.
+- **Recommendation:** one of `/docops:next`, `/docops:new-ctx`, `/docops:new-adr`, `/docops:new-task`, or `/docops:close <TP-ID>` depending on state.
+
+Keep the briefing under 10 lines. Do not regenerate STATE.md unless
+something in the repo changed — running `docops state` is cheap and
+idempotent, but a dirty diff shows up in git.

.claude/commands/docops/search.md

@@ -0,0 +1,28 @@
+---
+name: search
+description: Substring or regex search across DocOps doc titles, tags, and bodies, with structured filters (kind, status, coverage, tag, priority, assignee, since). Use when looking for docs by content, not ID.
+---
+
+# /docops:search
+
+Query docs by text and/or frontmatter.
+
+```
+docops search "release process"
+docops search "homebrew" --kind ADR
+docops search --kind TP --status active --priority p1
+docops search "upgrade" --regex --case
+docops search --tag release --since 2026-04-01
+docops search "migration" --json
+```
+
+The query is optional when at least one filter flag is present. Default
+match is case-insensitive substring; add `--regex` for regular
+expressions and `--case` for case-sensitive matching.
+
+Filters narrow before text match, so `--kind TP --status active "foo"`
+is cheaper than searching and then filtering.
+
+Semantic/embedding search is out of scope (see ADR-0017) — use
+substring + filters, or let the user point at specific IDs via
+`/docops:get`.

.claude/skills/docops/upgrade.md → .claude/commands/docops/upgrade.md

@@ -15,7 +15,8 @@ docops upgrade
 
 Touches only DocOps-owned scaffolding:
 
-- `.claude/skills/docops/*.md` and `.cursor/commands/docops/*.md` — synced to the shipped bundle (creates new files, refreshes changed ones, removes files that left the bundle).
+- `.claude/commands/docops/*.md` and `.cursor/commands/docops/*.md` — synced to the shipped bundle (creates new files, refreshes changed ones, removes files that left the bundle).
+- `.claude/skills/docops/*.md` — if this legacy folder exists from an older docops, its contents are removed (Claude Code reads slash commands from `.claude/commands/`, not `.claude/skills/`).
 - `docs/.docops/schema/*.schema.json` — regenerated from `docops.yaml`.
 - The `<!-- docops:start --> … <!-- docops:end -->` block inside `AGENTS.md` and `CLAUDE.md` — refreshed in place; content outside the markers is preserved. Either file is created if absent (so v0.1.x users gain CLAUDE.md on first upgrade).
 
@@ -47,5 +48,6 @@ docops upgrade --json
 ```
 
 Exit codes: `0` on success or user abort; `2` when there is no
-`docops.yaml` (run `docops init` first) or when the `.claude/skills/docops/`
-directory contains user-added files docops did not write.
+`docops.yaml` (run `docops init` first) or when the
+`.claude/commands/docops/` directory contains user-added files docops did
+not write.

.cursor/commands/docops/.docops-manifest

@@ -1,10 +1,19 @@
 # docops manifest — files in this directory owned by `docops upgrade`.
 # Do not hand-edit; rerun `docops upgrade` to regenerate.
 audit.md
+close.md
+do.md
+get.md
+graph.md
 init.md
+list.md
 new-adr.md
 new-ctx.md
 new-task.md
+next.md
+plan.md
+progress.md
 refresh.md
+search.md
 state.md
 upgrade.md

.cursor/commands/docops/close.md

@@ -0,0 +1,42 @@
+---
+name: close
+description: Finish a task — flip status to done, refresh DocOps state, and stage a commit. Use when the user says "done with TP-X" / "mark TP-X complete".
+---
+
+# /docops:close
+
+Close out a finished task.
+
+Ask for the task ID if not provided. Then:
+
+1. Verify the task's acceptance criteria are actually met. Read the
+   task body, check for remaining TODOs, and (if code changed)
+   eyeball the diff. If something is incomplete, stop and tell the user.
+
+2. Flip the task's `status:` frontmatter to `done` via `Edit` on the
+   source file — do not hand-edit the index.
+
+3. Run:
+
+```
+docops refresh
+```
+
+4. Stage every file relevant to the task (source changes + task
+   frontmatter + `docs/.index.json` + `docs/STATE.md`), then propose a
+   commit message of the form:
+
+   ```
+   <TP-ID>: <one-line summary of what shipped>
+
+   <one or two sentences on what actually changed and why, pulled from
+   the task's Goal + Acceptance>
+   ```
+
+   Confirm with the user before committing. Never commit without their
+   explicit OK.
+
+5. After the commit, run `/docops:progress` to surface the next move.
+
+Do not mark a task `done` just because citing files changed — the
+acceptance list is the contract.