@popoverai/dotrequirements 0.24.1 → 0.24.3

package/dist/templates/skills/codebase-to-spec/SKILL.md

@@ -1,118 +1,209 @@
 ---
 name: codebase-to-spec
-description: Generate dotrequirements behavioral specifications from a codebase. Use this when the user wants to capture what an existing codebase does as a set of testable behavioral requirements — e.g. for legacy systems, third-party libraries, or before refactoring.
+description: Generate dotrequirements behavioral specifications from a codebase via the conversational orchestrator. The user's CC session drives the pipeline directly — dispatching workers as subagents, reviewing per-area drafts, and iterating with editor passes. Use this when the user wants to capture what an existing codebase does as a set of testable behavioral requirements (legacy systems, third-party libraries, before refactoring).
 ---
 
-# Codebase to Spec
+# Codebase to Spec — Conversational Orchestrator
 
-You are a thin conversational wrapper around the `dotrequirements cts run` CLI. **You do not implement any pipeline logic yourself.** The CLI handles packing, planning, fan-out parallelism, retry, resumability, review loops, and presentation. Your job is to:
+You are the conversational orchestrator for codebase-to-spec. Unlike a thin CLI wrapper, **you drive the pipeline directly** — dispatching workers as `cts-worker` subagents (via the Task tool), reading their outputs, writing per-stage reviews into `.dotrequirements-cache/outline.yaml`, and looping until each stage converges.
 
-1. Confirm the user's scope.
-2. Run the CLI via the Bash tool.
-3. Narrate progress as the CLI emits it.
-4. Surface the final summary and residual notes.
-5. Offer sensible follow-ups (push to cloud, re-run, narrow scope, etc.).
+The CLI provides dispatch-instruction commands (`cts dispatch-*`) that you call to scaffold each step; you then dispatch the worker subagent yourself. The substrate is the single evolving `outline.yaml` file — it carries both the spec content (areas, customers, source files) and the review thread for each stage.
 
 ## When this skill is right
 
-Use it when the user wants behavioral requirements *from* code that already exists. Typical phrasings:
+Use when the user wants behavioral requirements *from* code that already exists. Typical phrasings:
 - "Generate requirements from this codebase"
 - "Capture the behavior of this library"
 - "I want a behavioral spec for the auth module"
 - "Document what this service does"
 
-Do **not** use it for:
-- New feature design (use `dotreq-requirements` / the capture flow instead)
-- Bug investigation
-- Code review
+Do **not** use for new feature design (use the `dotreq-requirements` skill instead), bug investigation, or code review.
 
 ## Workflow
 
 ### Step 1 — Confirm scope
 
-If the user passed a scope argument (e.g. a path like `src/auth`), use it. Otherwise, ask one concise question:
+If the user passed a scope argument (path), use it. Otherwise ask one concise question:
 
-> "Which part of the codebase should I spec? You can give me a path (e.g. `src/auth`) or say 'the whole thing'."
+> "Which part of the codebase should I spec? Give me a path (e.g. `src/auth`) or say 'the whole thing'."
 
-Whole-codebase runs are fine for small repos. For larger ones, encourage scoping to a single area — the CLI will tell you if the working-context budget is exceeded.
+For larger codebases, encourage scoping to a single area. The CLI will surface a `BudgetExceeded` exit code if the compressed pack is too large.
 
-### Step 2 — Run the CLI
+### Step 2 — Pack
 
-Invoke the pipeline via Bash. The command is:
+Run `dotrequirements cts pack --scope <PATH>` via Bash. This is deterministic — no LLM work. The CLI emits `[CTS] pack/done` and `[CTS] pack/budget-ok` lines.
+
+### Step 3 — Plan: dispatch the planner, review, iterate to approval
+
+**3a. Initial planner dispatch.** Run `dotrequirements cts dispatch-planner` via Bash. The output is JSON like `{ "dispatch_id": "planner-initial", "output_path": "..." }`. Dispatch the worker:
+
+```
+Task(subagent_type="cts-worker", prompt="dispatch-id=planner-initial")
+```
+
+The PreToolUse hook composes the full planner prompt; the worker writes `outline.yaml` and signals completion.
+
+**3b. Review the outline.** Read `.dotrequirements-cache/outline.yaml`. Assess:
+- **Customer naming**: Each area must have ≥1 customers with concrete, area-scoped descriptions (not "a developer" — "a Python data engineer building ETL pipelines"). Same role across areas is OK if described freshly per area's context.
+- **Area set**: Customer-vocabulary names, not architectural labels. Coverage of substantive files; non-behavioral files (tests, build infrastructure) excluded.
+- **Mechanical correctness**: distinct prefixes per area; paths matching the pack; ≥1 customer per area.
+
+**3c. Write your review into outline.yaml.** Edit the outline to add a top-level `review:` section. Two shapes:
+
+```yaml
+# Approved
+review:
+  result: approved
+  thread:
+    - result: approved
+```
+
+```yaml
+# Needs revision (revisions list is required, ≥1 entries)
+review:
+  result: needs-revision
+  thread:
+    - result: needs-revision
+      revisions:
+        - "Split the FOO area into two areas, separating the producer behavior from the reviewer behavior. Each should have its own customer and source files."
+        - "Tighten the customer description on BAR — it currently reads as generic 'a developer'; ground it in what the customer is doing at this specific moment in the system."
+```
+
+Revisions must be specific, actionable directives the planner can apply mechanically. Avoid "this feels off" — say what to change.
+
+**3d. If needs-revision, dispatch the planner again.** Run `dotrequirements cts dispatch-planner --revise`. Dispatch:
+
+```
+Task(subagent_type="cts-worker", prompt="dispatch-id=planner-revise-<N>")
+```
+
+(N comes from the CLI's payload — `planner-revise-2` for the 2nd round, `planner-revise-3` for the 3rd, etc.)
+
+The worker rewrites outline.yaml's content while preserving the existing `review` section. After it completes, return to step 3b and review the revised outline. Append another entry to the `review.thread` array based on what you find.
+
+**3e. Approval.** When you're satisfied, edit outline.yaml to set `review.result: approved` and append a `{ result: approved }` entry to the thread. Proceed to step 4.
+
+### Step 4 — Fan out: dispatch all specifiers in parallel
+
+Run `dotrequirements cts dispatch-spec`. The output is a JSON array of N payloads, one per area:
+
+```json
+[
+  { "dispatch_id": "specifier-PLAN", "output_path": "...", "area_name": "...", "area_prefix": "PLAN" },
+  ...
+]
+```
+
+Fire all N background Task dispatches in **one message** (parallel, not sequential):
 
-```bash
-dotrequirements cts run --scope <PATH> --non-interactive
 ```
+Task(subagent_type="cts-worker", prompt="dispatch-id=specifier-PLAN", run_in_background=true)
+Task(subagent_type="cts-worker", prompt="dispatch-id=specifier-OREV", run_in_background=true)
+... etc
+```
+
+Each worker:
+- Reads the area's source files via Read tool (from `.dotrequirements-cache/source.txt` or directly from the worktree)
+- Drafts the partial at `.dotrequirements-cache/partials/<sanitized-area>.partial.md`
+- Runs `cts validate` + `cts style-check` on its own draft via Bash (self-style-check loop, capped at 2 runs)
+- Signals completion via task-notification
+
+### Step 5 — Per-area review and editor loops
+
+As each specifier's task-notification arrives, review that area's partial:
+
+**5a. Read the partial.** Pull up the file the worker wrote.
 
-Flags:
-- `--scope <path>` — limit packing to a subdirectory. Omit for the whole repo.
-- `--non-interactive` — important: you're running in an agentic context, so prompts won't work.
-- `--overwrite` — replace existing `.requirements/*.requirements.md` files.
-- `--skip-existing` — leave existing files untouched.
-- `--fresh` — clear the cache before running (use only if a previous run is corrupt).
+**5b. Review against per-area criteria.** The area's customer descriptions in outline.yaml ground your review. Look for:
+- **Customer-grounding**: requirements use named personas from the area's customers
+- **Behavioral framing**: requirements describe what the customer observes, not API contracts or implementation mechanics
+- **Independent testability**: no cross-references between requirements; each readable on its own
+- **Coverage**: behaviors visible in source files are captured; tests/recipes informed but didn't drift into the spec
+- **Schema cleanliness**: validate already ran (worker self-validated); just sanity-check
 
-Default to `--non-interactive`. Decide between `--overwrite` and `--skip-existing` based on what the user wants if there are existing `.requirements/` files; otherwise neither flag is needed (the default `fail-fast` policy will surface conflicts).
+**5c. Write your review into outline.yaml's area section.** Same shape as the project-level review, on the area:
 
-### Step 3 — Narrate progress
+```yaml
+areas:
+  - name: ...
+    prefix: PLAN
+    review:
+      result: approved
+      thread:
+        - result: approved
+    ...
+```
+
+Or needs-revision with a revisions list (≥1 entries).
 
-The CLI emits lines like:
+**5d. If needs-revision, dispatch the editor.** Run `dotrequirements cts dispatch-editor <area-prefix>`. Then:
 
 ```
-[CTS] pack/done Packed 16 files → ... (compressed), ... (uncompressed)
-[CTS] plan/done Plan loop converged at turn 1 with verdict: approved-with-revisions
-[CTS] specify/summary Completed: 7 / Skipped (resume): 0 / Failed: 0
-[CTS] spec-review/done Edit loop converged at turn 1 with verdict: approved-with-revisions
-[CTS] present/created created: .../sample.requirements.md
+Task(subagent_type="cts-worker", prompt="dispatch-id=editor-<prefix>")
 ```
 
-Surface these to the user in conversational form as they appear. **Do not invent progress claims** — narrate only what the CLI has actually emitted. If the CLI is silent for a long stretch (specifier fan-out can take minutes), a single reassuring note ("still working — the specifier fan-out runs in parallel and takes a few minutes for larger areas") is fine. Don't repeat it.
+The worker reads the current partial + the revisions list inline (in the composed prompt), applies each revision via Edit, runs validate + style-check, signals completion. Return to 5a and re-review.
+
+**5e. Convergence.** Continue per-area loops until every area's `review.result` is `approved`. Each area can converge independently; don't block on one area to start reviewing another.
+
+### Step 6 — Cross-area review
+
+Once all per-area reviews are approved, run `cts compose-orchestrator` to assemble the composed spec. Then read it and check:
+
+- **Persona consistency**: same role mentioned across areas should use consistent naming
+- **Duplicated behaviors**: same behavior captured in two areas (one should own it)
+- **Cross-area gaps**: behaviors that fell between areas
+- **Framing drift**: areas in different voices
+
+If cross-area concerns surface, edit the affected areas' `review` to needs-revision with appropriate revisions, dispatch editors per 5d, then re-compose. Otherwise proceed to step 7.
+
+### Step 7 — Present
+
+Run `dotrequirements cts present-orchestrator [--overwrite] [--skip-existing]` via Bash. Writes the final files under `.requirements/`. Per CTS-PRESENT-1, splits into per-area files when the outline has ≥5 areas; single file otherwise.
+
+In non-interactive mode without `--overwrite` / `--skip-existing`, the CLI errors on conflicts. Ask the user which they want when a conflict is detected.
 
-### Step 4 — Surface the final summary
+### Step 8 — Summarize and offer follow-ups
 
-When the CLI finishes successfully, it prints a "Pipeline summary:" block with:
-- total areas
-- total top-level requirements
-- outline review turns and verdict
-- specifier completion count
-- spec review turns and verdict
-- the list of output files written
-- residual notes (issues the reviewer flagged in `approved-with-revisions` outcomes)
+Present the final summary in conversational form:
+- How many areas, how many requirements
+- Any unconverged areas (latest thread entry was max-turns-hit)
+- File paths written
 
-Present that summary back to the user. **Highlight the residual notes** prominently — these are concerns the reviewer wanted the human to verify. Common categories:
-- `outline.coverage_gap` — files the planner didn't assign to any area
-- `spec.coverage_gap` — behaviors the spec missed
-- `spec.framing_error` — requirements written as guidance/explanation rather than observable behavior
-- `spec.cross_area` — duplication across areas
-- `spec.internal_mechanics` — internal vocabulary that leaked into a user-facing spec
+Offer useful follow-ups:
+- **Push to cloud** — `dotrequirements push` syncs to dotrequirements cloud. Only suggest if the user has cloud configured (check `.dotrequirements/config.json` or ask).
+- **Refine an area** — re-review one area; mark needs-revision; re-dispatch editor.
+- **Re-run on different scope** — start over with a different `--scope` path.
 
-### Step 5 — Offer follow-ups
+## Pausing for user input
 
-After surfacing the summary, ask the user what they want next. Useful options:
+These moments naturally invite user judgment — surface them in conversation rather than auto-deciding:
+- **Scope confirmation** at the start
+- **Outline approval** before fan-out (the area decomposition is high-leverage)
+- **Cross-area concerns** that look like the user's call (e.g., "should X and Y be one area or two?")
+- **Residual concerns** at the end (anything the loop didn't fully address)
 
-- **Push to cloud** — `dotrequirements push` syncs the generated `.requirements/*.requirements.md` files to dotrequirements cloud. Only suggest this if the user has a cloud account (you can check by reading `.dotrequirements/config.json` or asking).
-- **Refine a specific area** — re-run `dotrequirements cts specify-area "<name>"` for one area, optionally with `--model <name>` for a stronger model.
-- **Refine the whole spec** — re-run `dotrequirements cts edit-loop` to iterate on the composed spec.
-- **Narrow the scope** — re-run with a smaller `--scope`.
-- **Hand-edit** — the output files are plain Markdown; the user can edit them directly.
+Routine progress narration ("dispatching planner...", "fan-out complete...") should NOT interrupt the user. Only judgment-requiring moments surface as questions.
 
 ## Failure handling
 
-The CLI uses stable exit codes (see `dotrequirements cts run --help`). Common cases:
+The CLI uses stable exit codes:
 
-- **Exit code 10 (BudgetExceeded)** — the codebase is too large for a single agent's context window after compression. Explain this in plain language and offer to retry with a narrower `--scope`.
-- **Exit code 11 (MaxTurnsHit)** — a review loop hit its cap without converging. The CLI still writes the latest artifact; surface the residual review and ask the user whether to ship it, re-run the stage (`dotrequirements cts edit-loop`), or hand-edit.
-- **Exit code 12 (OverwriteRefused)** — existing `.requirements/` files would be overwritten in non-interactive mode. Offer `--overwrite` or `--skip-existing`.
-- **Exit code 3 (StageFailed)** — a stage errored. Read stderr for details. Offer: resume (re-run the same command — the cache means earlier stages are skipped), restart fresh (`--fresh`), or investigate (read files in `.dotrequirements-cache/`).
-- **Any other non-zero exit** — surface stderr verbatim, then offer the same three options.
+- **Exit 10 (BudgetExceeded)** — codebase too large after compression. Surface, offer narrower `--scope`.
+- **Exit 11 (MaxTurnsHit)** — review loop hit its cap. Latest artifact is on disk; surface residual notes and ask user whether to ship, re-iterate, or hand-edit.
+- **Exit 12 (OverwriteRefused)** — present found existing files. Offer `--overwrite` or `--skip-existing`.
+- **Exit 2 (MissingInput)** — usually means a prior step wasn't run. Surface CLI message verbatim.
+- **Exit 3 (StageFailed)** — a stage errored. Read stderr; offer resume (re-run same command — the cache means earlier stages are skipped), restart fresh (`--fresh`), or investigate.
 
 ## What you must NOT do
 
-- Don't try to generate requirements yourself; always use the CLI.
-- Don't paraphrase or summarize the CLI's progress lines in ways that change their meaning.
-- Don't claim the pipeline did something it didn't (e.g. don't say "the reviewer approved this" if the verdict was `approved-with-revisions`).
+- Don't try to generate requirements yourself; always dispatch workers.
+- Don't paraphrase the CLI's progress lines in misleading ways. If the CLI emits "specifier failed", don't say "specifier completed."
+- Don't claim convergence when an area's thread ends with `needs-revision`. The loop hasn't closed.
 - Don't push to cloud without asking — `dotrequirements push` is a destructive sync.
-- Don't suggest editing files inside `.dotrequirements-cache/`; that's internal CLI state.
+- Don't edit files inside `.dotrequirements-cache/` other than `outline.yaml` (which you DO edit, to write reviews). Other cache files are managed by the CLI and workers.
+- Don't dispatch a worker without the corresponding `cts dispatch-*` call first — the dispatch-id must match what the CLI scaffolded.
 
 ## Host portability
 
-This skill makes no assumptions about subagent mechanisms, Task tools, or framework-specific features. Its only host requirements are: Agent Skills format support, a Bash tool (or equivalent shell-out), and `dotrequirements` installed on the user's machine.
+This skill relies on Claude Code's Task tool, PreToolUse hook, and Bash. It does not work on hosts without subagent dispatch (Cursor, Codex) — those should use the legacy `cts run` CLI directly. The skill is bundled with `dotrequirements ai-setup` for Claude Code; the `cts-worker` agent definition and persona-injection hook are installed at the same time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.24.1",
+  "version": "0.24.3",
   "description": "Requirements tracking CLI, test harness, and MCP server",
   "type": "module",
   "bin": {
@@ -24,10 +24,9 @@
     "test": "vitest",
     "test:run": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "prepublish:check": "git diff-index --quiet HEAD || (echo 'Error: Uncommitted changes detected. Commit or stash them first.' && exit 1)",
-    "publish:patch": "pnpm prepublish:check && npm version patch && pnpm build && npm publish && git push && git push --tags",
-    "publish:minor": "pnpm prepublish:check && npm version minor && pnpm build && npm publish && git push && git push --tags",
-    "publish:major": "pnpm prepublish:check && npm version major && pnpm build && npm publish && git push && git push --tags"
+    "publish:patch": "echo 'ERROR: publish:patch is decommissioned. CLI npm publishes now happen via the cli-publish GitHub Action when a production PR with a CLI version bump merges. Use the /release Claude Code skill to queue a bump and open the production PR. See docs/working/cli-publish-workflow.md for details.' && exit 1",
+    "publish:minor": "echo 'ERROR: publish:minor is decommissioned. CLI npm publishes now happen via the cli-publish GitHub Action when a production PR with a CLI version bump merges. Use the /release Claude Code skill to queue a bump and open the production PR. See docs/working/cli-publish-workflow.md for details.' && exit 1",
+    "publish:major": "echo 'ERROR: publish:major is decommissioned. CLI npm publishes now happen via the cli-publish GitHub Action when a production PR with a CLI version bump merges. Use the /release Claude Code skill to queue a bump and open the production PR. See docs/working/cli-publish-workflow.md for details.' && exit 1"
   },
   "keywords": [
     "requirements",