compound-workflow 1.9.0 → 1.9.2

package/README.md

@@ -30,6 +30,8 @@ If your package manager skipped the lifecycle script, or after updating the pack
 npx compound-workflow install
 ```
 
+Then run `/setup-agents` in your agent harness to tailor `AGENTS.md` to this project — it detects your stack and installed harnesses, curates the Skill Index, and prompts for anything it can't infer. Re-run it whenever harnesses or skills change.
+
 ---
 
 ## The Workflow
@@ -66,6 +68,8 @@ Log session outcomes and spot trends. `/metrics` records a single session. `/ass
 
 **`/test-browser`** — Browser-level validation of affected routes. Useful for UI changes where automated tests aren't enough.
 
+**`/setup-agents`** — Tailor `AGENTS.md` to this project. Detects your stack and installed harnesses, curates the Skill Index, and prompts for anything it can't infer. Re-run whenever harnesses or skills change.
+
 **`/install`** — Re-run setup. Safe to run again after updating the package or adding a new harness.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compound-workflow",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.",
   "license": "MIT",
   "repository": {

package/src/commands/test-browser.md

@@ -97,7 +97,7 @@ If installation fails, inform the user and stop.
 
 Before starting tests, ask user if they want to watch the browser:
 
-Use AskQuestion with:
+Use AskUserQuestion with:
 - Question: "Do you want to watch the browser tests run?"
 - Options:
   1. **Headed (watch)** - Opens visible browser window so you can see tests run
@@ -154,7 +154,7 @@ git diff --name-only "origin/${default_branch}"...HEAD
 
 </determine_scope>
 
-### 3. Map Files to Routes
+### 4. Map Files to Routes
 
 <file_to_route_mapping>
 
@@ -175,7 +175,7 @@ Build a list of URLs to test based on the mapping.
 
 </file_to_route_mapping>
 
-### 4. Verify Server is Running
+### 5. Verify Server is Running
 
 <check_server>
 
@@ -200,7 +200,7 @@ Then run `/test-browser` again.
 
 </check_server>
 
-### 5. Test Each Affected Page
+### 6. Test Each Affected Page
 
 <test_pages>
 
@@ -239,7 +239,7 @@ agent-browser screenshot --full page-name-full.png  # Full page
 
 </test_pages>
 
-### 6. Human Verification (When Required)
+### 7. Human Verification (When Required)
 
 <human_verification>
 
@@ -253,7 +253,7 @@ Pause for human input when testing touches:
 | SMS | "Verify you received the SMS code" |
 | External APIs | "Confirm the [service] integration is working" |
 
-Use AskQuestion:
+Use AskUserQuestion:
 ```markdown
 **Human Verification Needed**
 
@@ -268,7 +268,7 @@ Did it work correctly?
 
 </human_verification>
 
-### 7. Handle Failures
+### 8. Handle Failures
 
 <failure_handling>
 
@@ -307,7 +307,7 @@ When a test fails:
 
 </failure_handling>
 
-### 8. Test Summary
+### 9. Test Summary
 
 <test_summary>
 

package/src/commands/workflow-brainstorm.md

@@ -58,7 +58,7 @@ description.
 - Constrained, well-defined scope
 
 **If requirements are already clear:**\
-Use **AskQuestion** to suggest:
+Use **AskUserQuestion** to suggest:
 
 > "Your requirements seem detailed enough to proceed directly to
 > planning. Should I run `/workflow:plan` instead, or would you like to
@@ -97,9 +97,9 @@ Also consider any repo-level guidance files such as `AGENTS.md`.
 
 Engage in collaborative dialogue rather than a rapid question loop.
 
-**Critical (non-negotiable):** Default response shape is **synthesize + discussion prompts + assumptions**. Multiple-choice / AskQuestion only for handoffs (Phase 0, Phase 4) or a single blocking question when the user is stuck.
+**Critical (non-negotiable):** Default response shape is **synthesize + discussion prompts + assumptions**. Multiple-choice / AskUserQuestion only for handoffs (Phase 0, Phase 4) or a single blocking question when the user is stuck.
 
-**Enforcement rule:** Do **not** use AskQuestion during exploration until **after** at least one full dialogue iteration (Synthesize + discussion prompts + Capture). AskQuestion is only for handoffs or when one focused multiple-choice truly unblocks.
+**Enforcement rule:** Do **not** use AskUserQuestion during exploration until **after** at least one full dialogue iteration (Synthesize + discussion prompts + Capture). AskUserQuestion is only for handoffs or when one focused multiple-choice truly unblocks.
 
 **Default cadence (per iteration):**
 
@@ -191,7 +191,7 @@ For each approach, provide:
 Lead with your recommendation and explain why. Apply YAGNI --- prefer
 simpler solutions.
 
-Use **AskQuestion** to confirm preferred direction if needed.
+Use **AskUserQuestion** to confirm preferred direction if needed.
 
 ---
 
@@ -224,7 +224,7 @@ If Open Questions exist:
 
 ### Phase 4: Handoff
 
-Use **AskQuestion** to present next steps:
+Use **AskUserQuestion** to present next steps:
 
 **Question:**
 "Brainstorm captured. What would you like to do next?"

package/src/commands/workflow-plan.md

@@ -49,7 +49,7 @@ Use it to resolve optional defaults used by this command:
 
 If not present, proceed with safe defaults and state what you assumed.
 
-### 0. Idea Refinement
+### Step 1 — Idea Refinement
 
 **Check for brainstorm output first:**
 
@@ -72,11 +72,11 @@ Use file discovery tools (Glob/Read) to locate and read recent brainstorm docume
 5. Use brainstorm decisions as input to the research phase
 
 **If multiple brainstorms could match:**
-Use **AskQuestion** to ask which brainstorm to use, or whether to proceed without one.
+Use **AskUserQuestion** to ask which brainstorm to use, or whether to proceed without one.
 
 **If no brainstorm found (or not relevant), run idea refinement:**
 
-Refine the idea through collaborative dialogue using **AskQuestion**:
+Refine the idea through collaborative dialogue using **AskUserQuestion**:
 
 - Ask questions one at a time to understand the idea fully
 - Prefer multiple choice questions when natural options exist
@@ -96,7 +96,7 @@ Refine the idea through collaborative dialogue using **AskQuestion**:
 
 ## Main Tasks
 
-### 1. Local Research (Always Runs - Parallel)
+### Step 2 — Local Research (Always Runs - Parallel)
 
 <thinking>
 First, I need to understand the project's conventions, existing patterns, and any documented learnings. This is fast and local - it informs whether external research is needed.
@@ -107,7 +107,7 @@ Run these agents **in parallel** to gather local context:
 - Task repo-research-analyst(feature_description)
 - Task learnings-researcher(feature_description)
 
-Also read the Skill Index from `AGENTS.md` directly — capture which skills are available and their trigger conditions. This will be used to annotate plan tasks with relevant skills in Step 1.6.
+Also read the Skill Index from `AGENTS.md` directly — capture which skills are available and their trigger conditions. This is a read-and-hold step; you will assign skills to tasks in Step 6.
 
 **What to look for:**
 
@@ -117,9 +117,9 @@ Also read the Skill Index from `AGENTS.md` directly — capture which skills are
 
 These findings inform the next step.
 
-### 1.5. Planning Fidelity + Confidence + Research Mode (REQUIRED)
+### Step 3 — Planning Fidelity + Confidence + Research Mode (REQUIRED)
 
-After Step 0 and local research, you MUST choose planning fidelity and confidence, then decide whether to run external research.
+After Step 1 (Idea Refinement) and Step 2 (Local Research), you MUST choose planning fidelity and confidence, then decide whether to run external research.
 
 #### Fidelity
 
@@ -164,7 +164,7 @@ If risky work is detected:
 
 - Spike evaluation is mandatory.
 - Declare `spikes_needed: yes|no`.
-- If `spikes_needed: yes`, include explicit Spike Candidates with upfront dependency and priority modeling (see Step 3.5).
+- If `spikes_needed: yes`, include explicit Spike Candidates with upfront dependency and priority modeling (see Step 11).
 - If `spikes_needed: no`, include a short rationale + risk mitigation note explaining why direct implementation is safe.
 
 #### Research Mode
@@ -179,7 +179,7 @@ Baseline policy (by fidelity):
 
 Override: high-risk topics always require external research, even if the user prefers speed.
 
-**Required sections by fidelity** (ensure the chosen template includes these; see Step 4):
+**Required sections by fidelity** (ensure the chosen template includes these; see Step 12):
 
 - **Low**: problem, constraints, acceptance criteria, implementation outline, verification checklist
 - **Medium**: all Low + alternatives/tradeoffs, dependency/risk table, rollout notes, observability/test notes
@@ -202,18 +202,18 @@ Research mode: local only | local + external
 Open questions: none | <list>
 ```
 
-**When Open questions is not "none":** You MUST materialize them in the plan body as actionable items (see Step 2.5). If an unknown blocks implementation feasibility, prefer **Spike Candidates**. If confidence is `Low`, the plan MUST include at least one checkbox under Discussion Points or Spike Candidates so `/workflow:work` can create pending todos and triage can resolve them.
+**When Open questions is not "none":** You MUST materialize them in the plan body as actionable items (see Step 9). If an unknown blocks implementation feasibility, prefer **Spike Candidates**. If confidence is `Low`, the plan MUST include at least one checkbox under Discussion Points or Spike Candidates so `/workflow:work` can create pending todos and triage can resolve them.
 
-### 1.5b. External Research (Conditional)
+### Step 4 — External Research (Conditional)
 
-Run external research when Step 1.5 selected `local + external`.
+Run external research when Step 3 selected `local + external`.
 
 Run these agents in parallel:
 
 - Task best-practices-researcher(feature_description)
 - Task framework-docs-researcher(feature_description)
 
-### 1.5c. Git History Research (Conditional)
+### Step 5 — Git History Research (Conditional)
 
 Use git history research when historical context is likely to change the plan.
 
@@ -227,7 +227,7 @@ If selected, run:
 
 - Task git-history-analyzer(feature_description)
 
-### 1.6. Consolidate Research
+### Step 6 — Consolidate Research
 
 After all research steps complete, consolidate findings:
 
@@ -240,7 +240,7 @@ After all research steps complete, consolidate findings:
 
 **Optional validation:** Briefly summarize findings and ask if anything looks off or missing before proceeding to planning.
 
-### 1.7. SpecFlow Analysis (by fidelity)
+### Step 7 — SpecFlow Analysis (by fidelity)
 
 Run flow/gap analysis to surface missing requirements before locking structure:
 
@@ -248,11 +248,11 @@ Run flow/gap analysis to surface missing requirements before locking structure:
 - **Medium fidelity:** recommended
 - **High fidelity:** required
 
-**Step 1 — Dispatch subagent:** Task spec-flow-analyzer(feature_description, research_findings)
+**Dispatch subagent:** Task spec-flow-analyzer(feature_description, research_findings)
 
-**Step 2 — Parent review:** Once findings are returned, assess whether gaps and edge cases are adequately surfaced. If coverage is insufficient or a critical flow was missed, re-dispatch with refined context before locking structure. Incorporate confirmed gaps into the upcoming issue structure and acceptance criteria.
+**Parent review:** Once findings are returned, assess whether gaps and edge cases are adequately surfaced. If coverage is insufficient or a critical flow was missed, re-dispatch with refined context before locking structure. Incorporate confirmed gaps into the upcoming issue structure and acceptance criteria.
 
-### 2. Issue Planning & Structure
+### Step 8 — Issue Planning & Structure
 
 <thinking>
 Think like a product manager - what would make this issue clear and actionable? Consider multiple perspectives
@@ -278,7 +278,7 @@ Think like a product manager - what would make this issue clear and actionable?
 - [ ] Gather supporting materials (error logs, screenshots, design mockups)
 - [ ] Prepare code examples or reproduction steps if applicable, name the mock filenames in the lists
 
-### 2.5. Solution Scope Contract (REQUIRED for all plans)
+### Step 9 — Solution Scope Contract (REQUIRED for all plans)
 
 Every plan MUST include an explicit scope contract so `/workflow:work` can enforce intent.
 
@@ -299,7 +299,7 @@ Placement:
 - Put `solution_scope` in frontmatter.
 - Put `completion_expectation` and `non_goals` in a dedicated section (recommended: `## Scope Contract`) in the plan body.
 
-### 2.6. Agentic Access & Validation Contract (REQUIRED for all plans)
+### Step 10 — Agentic Access & Validation Contract (REQUIRED for all plans)
 
 Every plan MUST include an explicit contract describing how an agent will execute and verify the work without hidden assumptions.
 
@@ -322,9 +322,9 @@ Placement:
 - Add a dedicated section in the plan body: `## Agentic Access & Validation Contract`.
 - Reference this section from implementation phases/todos so `/workflow:work` can enforce it directly.
 
-### 3.5. Discussion Points & Spike Candidates
+### Step 11 — Discussion Points & Spike Candidates
 
-When you declared Open questions in Step 1.5 (other than "none"), and/or when risky-work spike evaluation requires spikes, the plan file MUST include one or both sections below with checkboxes so `/workflow:work` and `file-todos` can create pending todos for triage:
+When you declared Open questions in Step 3 (other than "none"), and/or when risky-work spike evaluation requires spikes, the plan file MUST include one or both sections below with checkboxes so `/workflow:work` and `file-todos` can create pending todos for triage:
 
 - **## Discussion Points (resolve/decide)** — Decisions to make (no code). Use `- [ ]` items (e.g. "Decide: X or Y?", "Confirm constraint Z").
 - **## Spike Candidates (timeboxed)** — Timeboxed investigations to de-risk. Use `- [ ] Spike: <short description>` items.
@@ -361,7 +361,7 @@ Example Spike Candidate:
   - Parallelizable: yes
 ```
 
-### 4. Choose Implementation Detail Level
+### Step 12 — Choose Implementation Detail Level
 
 Select how comprehensive you want the issue to be. Fidelity should drive this choice.
 
@@ -748,7 +748,7 @@ solution_scope: [partial_fix|full_remediation|migration]
 - Design documents: [links]
 ```
 
-### 5. Issue Creation & Formatting
+### Step 13 — Issue Creation & Formatting
 
 <thinking>
 Apply best practices for clarity and actionability, making the issue easy to scan and understand
@@ -792,7 +792,7 @@ Apply best practices for clarity and actionability, making the issue easy to sca
 </details>
 ````
 
-### 6. Final Review & Submission
+### Step 14 — Final Review & Submission
 
 **Pre-submission Checklist:**
 
@@ -820,7 +820,7 @@ mkdir -p docs/plans/
 
 Write the complete plan file to `docs/plans/YYYY-MM-DD-<type>-<slug>-plan.md`. This step is mandatory and cannot be skipped — even when running as part of LFG/SLFG or other automated pipelines.
 
-**When Open questions were declared (Step 1.5):** The written plan MUST include at least one of: `## Discussion Points (resolve/decide)` with `- [ ]` items, or `## Spike Candidates (timeboxed)` with `- [ ] Spike: ...` items. If confidence is `Low`, at least one checkbox is required in one of these sections. This ensures `file-todos` can create pending discussion/spike todos for `/workflow:triage`.
+**When Open questions were declared (Step 3):** The written plan MUST include at least one of: `## Discussion Points (resolve/decide)` with `- [ ]` items, or `## Spike Candidates (timeboxed)` with `- [ ] Spike: ...` items. If confidence is `Low`, at least one checkbox is required in one of these sections. This ensures `file-todos` can create pending discussion/spike todos for `/workflow:triage`.
 
 **When risky-work Spike Evaluation declared `spikes_needed: yes`:** The written plan MUST include `## Spike Candidates (timeboxed)` with at least one spike checkbox and required per-candidate metadata (`Initial priority`, `Depends on`, `Unblocks`, `Timebox`, `Deliverable`, `Parallelizable`) so ordering can be defined in plan, confirmed in triage, and enforced in work.
 
@@ -830,7 +830,7 @@ Confirm: "Plan written to docs/plans/[filename]"
 
 **Technical review (required when Fidelity is Medium or High):** After writing the plan file, if the declared **Fidelity is Medium or High**, you **must** run technical review—it is not optional. Run **Task planning-technical-reviewer(plan_path)** using the plan path just written. Do not perform technical review in-context unless the environment cannot run the Task; if you fall back, state "planning-technical-reviewer unavailable; running direct technical review (degraded bias resistance)" and then load the `technical-review` skill and run it in-context. If Fidelity is Low, skip this step; the user can still choose "Technical review" from Post-Generation Options or call `/workflow:tech-review` later.
 
-**Non-interactive mode:** When the invocation is non-interactive (e.g., `workflow:plan` run by automation, CI, or with an explicit non-interactive flag/convention), skip AskQuestion calls and do not present Post-Generation Options. For determinism, the repo should define the flag or convention (e.g., in `AGENTS.md` Repo Config Block or a documented env var). Still **declare** Fidelity, Confidence, Solution scope, Spike evaluation, Spikes needed, Research mode, and Open questions in the required announcement format before writing the plan. Use these defaults when user input is unavailable: fidelity = Medium, confidence = Medium, solution_scope = full_remediation, spike evaluation = not-required unless risky-work triggers are present, spikes needed = n/a when spike evaluation is not required, research mode = local + external for Medium/High risk topics else local only. Proceed directly to writing the plan file and then exit or return the plan path as output.
+**Non-interactive mode:** When the invocation is non-interactive (e.g., `workflow:plan` run by automation, CI, or with an explicit non-interactive flag/convention), skip AskUserQuestion calls and do not present Post-Generation Options. For determinism, the repo should define the flag or convention (e.g., in `AGENTS.md` Repo Config Block or a documented env var). Still **declare** Fidelity, Confidence, Solution scope, Spike evaluation, Spikes needed, Research mode, and Open questions in the required announcement format before writing the plan. Use these defaults when user input is unavailable: fidelity = Medium, confidence = Medium, solution_scope = full_remediation, spike evaluation = not-required unless risky-work triggers are present, spikes needed = n/a when spike evaluation is not required, research mode = local + external for Medium/High risk topics else local only. Proceed directly to writing the plan file and then exit or return the plan path as output.
 
 **Required in plan frontmatter:** Add these fields to the plan file:
 
@@ -840,7 +840,7 @@ Confirm: "Plan written to docs/plans/[filename]"
 
 ## Output Format
 
-**Filename:** Use the filename from Step 2 (Title & Categorization): `YYYY-MM-DD-<type>-<slug>-plan.md` with type and slug from the single contract.
+**Filename:** Use the filename from Step 8 (Title & Categorization): `YYYY-MM-DD-<type>-<slug>-plan.md` with type and slug from the single contract.
 
 ```
 docs/plans/YYYY-MM-DD-<type>-<slug>-plan.md
@@ -860,35 +860,21 @@ Examples:
 
 Technical review (above) is required for Medium/High fidelity and must be run via subagent when available.
 
-After writing the plan file, use **AskQuestion** to present these options:
+After writing the plan file, use **AskUserQuestion** to ask: "Plan ready at `docs/plans/YYYY-MM-DD-<type>-<slug>-plan.md`. What would you like to do next?"
 
-**Question:** "Plan ready at `docs/plans/YYYY-MM-DD-<type>-<slug>-plan.md`. What would you like to do next?"
+**Options and routing:**
 
-**Options:**
+1. **Open plan in editor** → Navigate to `docs/plans/<plan_filename>.md`
+2. **Review and refine** → Load `document-review` skill
+3. **Start `/workflow:work`** → Run `/workflow:work <plan_path>` (includes triage gate)
+4. **Start `/workflow:triage`** → Ensure plan todos exist (create via `file-todos` if needed), then run `/workflow:triage` to approve the ready queue
+5. **Create Issue** → See "Issue Creation" section below
+6. **Other** → Accept free text for rework or specific changes
 
-1. **Open plan in editor** - Open the plan file for review
-2. **Review and refine** - Improve the document through structured self-review
-3. **Start `/workflow:work`** - Execute this plan (includes default triage gate)
-4. **Start `/workflow:triage`** - Manually curate/prioritize queue before execution
-5. **Create Issue** - Create issue in project tracker (GitHub/Linear)
-6. **Other** - Adjust the plan
+Optional (only if present in this repo):
 
-Optional (only if those workflows exist in this repo):
-
-- `/deepen-plan` - Enhance each section with parallel research agents
-- **Technical review** - Load `technical-review` skill for technical correctness (no edits). Pair with `document-review` to apply any agreed changes to the plan.
-
-Based on selection:
-
-- **Open plan in editor** → Open the plan file in the editor (navigate to `docs/plans/<plan_filename>.md`)
-- **Review and refine** → Load `document-review` skill.
-- **Start `/workflow:work`** → Run `/workflow:work <plan_path>`; `/workflow:work` must run triage before implementation.
-- **Start `/workflow:triage`** → Ensure plan todos exist (create via `file-todos` if needed), then run `/workflow:triage` to approve priority/dependencies and the executable ready queue.
-- **Technical review** → Load `technical-review` skill; then if user agrees to changes, load `document-review` to update the plan.
-- **Create Issue** → See "Issue Creation" section below
-- **Other** → Accept free text for rework or specific changes
-
-**Note:** Only if `/deepen-plan` exists in this repo and the user has enabled it (e.g., ultrathink), you may run `/deepen-plan` after plan creation for extra depth; it is optional, not required.
+- **Technical review** → Load `technical-review` skill; if user agrees to changes, load `document-review` to update the plan
+- `/deepen-plan` → Enhance each section with parallel research agents (optional, not required)
 
 Loop back to options after changes until user selects `/workflow:work`, `/workflow:triage`, or ends the session.
 
@@ -903,7 +889,7 @@ When user selects "Create Issue", detect their project tracker from repo guidanc
 
 2. **If GitHub:**
 
-   Use **type** and **title** from Step 2 (title has no prefix). Compose issue title as `"<type>: <title>"` (e.g., `feat: User authentication flow`).
+   Use **type** and **title** from Step 8 (title has no prefix). Compose issue title as `"<type>: <title>"` (e.g., `feat: User authentication flow`).
 
    If the `gh` CLI is available, create the issue via:
 
@@ -915,7 +901,7 @@ When user selects "Create Issue", detect their project tracker from repo guidanc
 
 3. **If Linear:**
 
-   Use **type** and **title** from Step 2. For Linear, use either the full title or `"<type>: <title>"` per team convention.
+   Use **type** and **title** from Step 8. For Linear, use either the full title or `"<type>: <title>"` per team convention.
 
    If the `linear` CLI is available, create the issue via:
 

package/src/commands/workflow-work.md

@@ -25,12 +25,13 @@ This command is an orchestrator, not an implementer.
 This command is responsible for:
 
 - reading and validating the approved plan
-- deriving executable todo contracts from approved feature requirements
+- breaking the plan into executable todo contracts via `skill: file-todos`
 - preserving intent from the plan during task derivation and execution
-- resolving required skills from the capability registry
-- determining execution order based on dependencies and preconditions
-- **delegating execution to subagents**
-- **collecting and verifying subagent output**
+- allocating the plan's `required_skills` onto each todo and passing them to subagents at delegation time
+- determining execution order — dependencies, preconditions, priority tier, blocking spikes first
+- identifying which ready todos can run in parallel without conflicting
+- delegating execution to subagents (never implementing directly)
+- collecting and verifying subagent output
 - routing work through required review gates
 - deciding `complete`, `changes_required`, `blocked`, or `plan_conflict`
 
@@ -317,14 +318,14 @@ If yes: set `status = plan_conflict`, stop further dependent execution, surface
 
 ### Phase 1: Setup & Validation
 
-#### 1.1 Read and Validate Plan File
+#### Step 1 — Read and Validate Plan File
 
 - Read the plan file completely
 - Confirm the file exists and is readable
 - If missing acceptance criteria, scope, or non-goals — stop and return for refinement
 - Do not compensate for a weak plan by improvising hidden assumptions
 
-#### 1.2 Resolve Repo Defaults
+#### Step 2 — Resolve Repo Defaults
 
 Read `AGENTS.md` and look for the Repo Config Block. Resolve:
 
@@ -340,7 +341,7 @@ If any required quality gate command is missing:
 - record them in the first active todo work log entry
 - do not mark related todos complete unless the commands were run successfully
 
-#### 1.3 Resolve Plan Contract
+#### Step 3 — Resolve Plan Contract
 
 Extract from the plan:
 
@@ -362,7 +363,9 @@ If any of the following are missing, stop and return the plan for refinement:
 - actionable access/validation contract
 - enough implementation detail to derive executable tasks
 
-#### 1.4 Resolve Skill Assignments
+#### Step 4 — Resolve Skill Assignments
+
+The plan selects required skills per task. Work validates them against the Skill Index and allocates them to subagents at delegation — it does not re-decide skills or add universal baselines.
 
 Read the Skill Index from `AGENTS.md`.
 
@@ -370,7 +373,7 @@ For each implementation phase or task in the plan:
 
 - Check if the plan already carries `required_skills` annotations (written during `/workflow:plan`)
 - If annotations exist: validate each skill against the registry — confirm it exists and is applicable
-- If annotations are missing: resolve skills now by mapping task responsibility, objective, and constraints to the Skill Index
+- If annotations are missing on a task that needs skills: treat as a plan defect and stop — return to `/workflow:plan` for refinement
 - Record resolved skills per task — these will be attached to todo contracts in Phase 3
 
 If a required skill cannot be resolved from the registry:
@@ -378,7 +381,7 @@ If a required skill cannot be resolved from the registry:
 - surface it as a capability gap
 - do not proceed with that task until resolved
 
-#### 1.5 Resolve Testing Cadence
+#### Step 5 — Resolve Testing Cadence
 
 Infer testing cadence from the plan's risk profile.
 
@@ -432,7 +435,7 @@ Convert the approved plan into executable todo contracts.
 
 A todo is not a note. A todo is not a loose checklist item. A todo is an executable contract that can be delegated to a subagent, verified, and closed.
 
-#### 3.1 Todo Contract Rules
+#### Step 1 — Todo Contract Rules
 
 Every derived todo must be:
 
@@ -443,13 +446,13 @@ Every derived todo must be:
 - explicit about verification
 - explicit about evidence required for closure
 - explicitly anchored to approved intent
-- carrying resolved skill assignments from Phase 1.4
+- carrying resolved skill assignments from Phase 1 Step 4
 
 If a candidate task is too broad: split it before delegation.
 If a candidate task is ambiguous: refine it before delegation.
 If a candidate task depends on unresolved decisions: mark it `blocked`.
 
-#### 3.2 Required Todo Contract Schema
+#### Step 2 — Required Todo Contract Schema
 
 Every executable todo MUST contain:
 
@@ -461,7 +464,7 @@ type: build | review | qa | docs | spike | discussion
 objective: <what this task must achieve>
 responsibility: <primary responsibility domain>
 required_skills:
-  - <resolved from plan annotations or Phase 1.4>
+  - <resolved from plan annotations or Phase 1 Step 4>
 optional_skills:
   - <attached when they materially reduce risk>
 intent_anchor:
@@ -514,7 +517,7 @@ review_outcome:
   summary: pending
 ```
 
-#### 3.3 Todo Status Model
+#### Step 3 — Todo Status Model
 
 - `drafted` — derived but not yet ready to execute
 - `ready` — dependencies and preconditions satisfied
@@ -528,13 +531,13 @@ review_outcome:
 
 Important: `implemented` does not unblock downstream work. Only `complete` unblocks downstream work.
 
-#### 3.4 Responsibility Classification
+#### Step 4 — Responsibility Classification
 
 Every todo must declare one primary responsibility. If a task truly spans multiple major responsibilities, split it.
 
 Recommended values: `frontend`, `backend`, `schema`, `testing`, `playwright`, `infra`, `docs`, `spike`, `discussion`, `technical_review`, `qa_review`
 
-#### 3.5 Blocking Unknowns
+#### Step 5 — Blocking Unknowns
 
 When the plan includes unresolved decisions, missing access, risky unknowns, spike candidates, or discussion points — these must become explicit todos before dependent build work begins.
 
@@ -542,7 +545,7 @@ When the plan includes unresolved decisions, missing access, risky unknowns, spi
 - spike todos → reduce risk with a timebox and deliverable
 - build work blocked by them stays `blocked`
 
-#### 3.6 Create Todo Files
+#### Step 6 — Create Todo Files
 
 Confirm `file-todos` exists in the AGENTS.md registry before running. If missing, surface as a capability gap and stop.
 
@@ -566,7 +569,7 @@ Plan → todos mapping:
 - spike candidates → spike todos (`status: pending`)
 - review/qa requirements → review/qa todos
 
-#### 3.7 Dependency Rules
+#### Step 7 — Dependency Rules
 
 Execution order is dependency-driven, not list-order driven.
 
@@ -806,7 +809,7 @@ Ask-once fallback: if commands are not configured, ask once for run-provided com
 
 ### Phase 7: Completion
 
-#### 7.1 Final Drift Check
+#### Step 1 — Final Drift Check
 
 Verify the complete implementation still aligns to original plan intent:
 
@@ -817,7 +820,7 @@ Verify the complete implementation still aligns to original plan intent:
 
 If drift detected: set `status = plan_conflict`, stop, surface for review before claiming completion.
 
-#### 7.2 Completion Summary
+#### Step 2 — Completion Summary
 
 Provide:
 
@@ -829,7 +832,7 @@ Provide:
 - Plan conflicts / drift detected
 - Next execution step
 
-#### 7.3 Handoff Options
+#### Step 3 — Handoff Options
 
 - `/workflow:review` — validate quality of implemented work
 - `/workflow:compound` — capture durable learnings from this execution

package/src/skills/setup-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-agents
-description: Create or update AGENTS.md for any project. Detects project stack and installed harness directories, prompts for missing config, curates the Skill Index from installed skills, and writes a clean minimal AGENTS.md. Use when onboarding a new project or refreshing an existing config.
+description: Create or update AGENTS.md for any project. Detects project stack and installed harness directories, prompts for missing config, builds the Skill Index from all installed skills (no manual curation), and writes a clean minimal AGENTS.md. Use when onboarding a new project or refreshing an existing config.
 triggers:
   - setting up a new project
   - initialising AGENTS.md for the first time
@@ -70,47 +70,62 @@ From these, infer:
 | `format_command` | `scripts.format` in package.json; prettier config presence |
 | `dev_server_url` | vite config `server.port`; default `http://localhost:5173` for Vite, `http://localhost:3000` for others |
 | `worktree_install_command` | `package-lock.json` → `npm ci`; `yarn.lock` → `yarn install`; `pnpm-lock.yaml` → `pnpm install` |
+| `default_branch` | `git symbolic-ref refs/remotes/origin/HEAD` → strip `refs/remotes/origin/`; fallback `main` |
+| `project_tracker` | `.github/` exists → `github`; else `none` |
+| `worktree_dir` | default `.worktrees` |
+| `worktree_copy_files` | glob `.env*` in repo root, excluding `.env.example` and `.env.sample` |
 
-For each value, state whether it was detected or assumed.
+For each value, state whether it was detected or defaulted.
 
 ---
 
-## Phase 2: Prompt for Missing or Undetectable Values
+## Phase 2: Confirm the Proposed Config
 
-Ask for any values that could not be detected. Ask one at a time.
+Do not prompt field-by-field. Show the resolved config from Phase 1 as a single block and ask one question.
 
-Required:
+**Update mode:** start from the values already in `AGENTS.md`. Only overwrite with a Phase 1 detection when the existing value is empty or clearly stale (e.g. references a command that no longer exists in `package.json`). Flag overrides in the proposed block so the user can see what changed.
 
-- `default_branch` — cannot be reliably detected; ask (suggest `main`)
-- `project_tracker` — ask: `github`, `linear`, or none
-- `dev_server_url` — confirm detected value or ask
-- `worktree_dir` — suggest `.worktrees`
-- `worktree_copy_files` — ask which env/config files should be copied into new worktrees (e.g. `.env.local`)
-- `harnesses` — show detected list from Phase 1; confirm or correct
+Output format:
 
-**Update mode only:** Show the current values and ask: "These values are already configured — confirm, update, or skip each?"
+```
+Proposed AGENTS.md config:
+
+  default_branch: <value>            [detected|default|existing]
+  project_tracker: <value>           [detected|default|existing]
+  dev_server_url: <value>            [detected|default|existing]
+  test_command: <value>              [detected|existing]
+  test_fast_command: <value>         [detected|existing|omit]
+  lint_command: <value>              [detected|existing|omit]
+  typecheck_command: <value>         [detected|existing|omit]
+  format_command: <value>            [detected|existing|omit]
+  worktree_dir: <value>              [default|existing]
+  worktree_install_command: <value>  [detected|existing]
+  worktree_copy_files: [<files>]     [detected|existing]
+  harnesses: [<dirs>]                [detected]
+
+Accept, or reply with `<key>: <value>` lines to override. Blank line accepts.
+```
+
+One round-trip. If the user accepts, proceed to Phase 3. If they override fields, apply the overrides and proceed — do not re-confirm.
 
 ---
 
-## Phase 3: Curate the Skill Index
+## Phase 3: Build the Skill Index
 
 List all directories under `$skills_dir` (resolved in Phase 1). For each one, read `SKILL.md` frontmatter to get `name` and `description`. These are the only skills that may appear in the Skill Index — never reference a skill not present on disk.
 
-Present the full discovered list to the user as a numbered menu:
+**Include every discovered skill automatically.** The installed skill set is the source of truth; there is no curation step. Do not prompt the user to pick a subset.
+
+Show the resolved list so the user can see what will be written:
 
 ```
-Installed skills (from <$skills_dir>):
-  1. <name> — <description from frontmatter>
-  2. <name> — <description from frontmatter>
+Skill Index will include all installed skills from <$skills_dir>:
+  - <name> — <description from frontmatter>
+  - <name> — <description from frontmatter>
   ...
-
-Which should appear in the Skill Index? (Enter numbers, or "all", or "all except N,N")
 ```
 
-**Init mode:** Ask which to include.
-**Update mode:** Show which are currently included and ask: "Keep, remove, or any to add?"
-
-Do not categorise skills in advance — the user decides what is relevant for their project.
+**Update mode:** diff against the existing Skill Index and note additions/removals, then write the refreshed list. If the user wants to exclude a skill, they should uninstall or remove it from `$skills_dir` rather than hand-curate the index.
 
 ---
 
@@ -215,7 +230,7 @@ harnesses:
 
 | Skill | Use when |
 | --- | --- |
-[... one row per skill the user selected in Phase 3; use the description from each skill's SKILL.md frontmatter ...]
+[... one row per skill discovered in Phase 3; use the description from each skill's SKILL.md frontmatter ...]
 ```
 
 Confirm: "AGENTS.md written."