compound-workflow 1.9.3 → 1.9.5

package/package.json

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

package/src/AGENTS.md

@@ -44,6 +44,17 @@ Onboarding:
 
 - `/install` — one action: copies agents/skills/commands, writes opencode.json, merges AGENTS.md, creates docs/todo dirs (run `npx compound-workflow install` in the project)
 
+## Orchestration Model
+
+The main agent stays lean. Context lives where it's needed, not at the top.
+
+- **Plan** selects the minimal skill set for the work and names each selection explicitly. Unused skills never load.
+- **Work** allocates tasks to subagents and passes only what each task needs: the problem statement, relevant file refs, success criteria. Not conversation history, not unrelated context.
+- **Subagents** run in isolation, return evidence and results. The main agent orchestrates, records outcomes, and moves to the next task.
+- **Skills load on demand.** Commands pull a skill into context only when a gate or step requires it — not as a precautionary baseline.
+
+Context budget rule: if a task can be done with less context, pass less. If a subagent can handle it, delegate.
+
 ## Non-negotiables (Structure Integrity)
 
 - **Commands are the public API.** Keep `/workflow:*` command docs stable; add capability via skills/agents, not new command variants.

package/src/commands/workflow-brainstorm.md

@@ -95,73 +95,53 @@ Also consider any repo-level guidance files such as `AGENTS.md`.
 
 #### 1.2 Structured Dialogue Exploration (Default)
 
-Engage in collaborative dialogue rather than a rapid question loop.
+Engage in collaborative **dialog, one question at a time**. This is a discussion, not a survey — ask open-ended, conversational questions that invite the user to think out loud. Readability beats coverage.
 
-**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.
+**Critical (non-negotiable):** Default response shape is **synthesize + ONE open question + assumptions**. No "prompts to react to" menus. No multiple-choice questions during exploration. No multi-part questions. AskUserQuestion (which forces multiple-choice) is reserved strictly for handoffs (Phase 0, Phase 4) — never for exploration.
 
-**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.
+**Enforcement rule:** Do **not** use AskUserQuestion during Phase 1 exploration. Ask open-ended questions in plain prose and let the user reply in plain prose. AskUserQuestion is only for the Phase 0 / Phase 4 handoff decisions.
 
 **Default cadence (per iteration):**
 
-1. **Synthesize Current Understanding** (2--4 bullets)
-2. **Ask at most ONE high-leverage question** (only if needed)
-3. **Surface Tensions & Unknowns** using 3--5 **discussion prompts** (not interrogation)
-4. **Capture Emerging Assumptions** (bullets)
+1. **Synthesize Current Understanding** (≤ 3 short bullets)
+2. **Ask ONE high-leverage question** (the single most useful thing to resolve now)
+3. **State Working Assumptions** (≤ 3 bullets, phrased as "tell me if any of these are wrong")
 
 **Hard rules:**
 
-- Do not ask follow-up questions in the same turn.
-- Ask **no more than one** clarifying question per iteration.
-- If blocked, ask **one** additional clarifying question max, then return to prompts.
+- Exactly **one** question per turn. No follow-ups, no "also…", no multi-part questions.
+- No "prompts to react to" / "pick any" menus. If tempted to list options, pick the single best one and ask that.
+- Keep the whole turn short — aim for ≤ 12 lines. A reader should grasp it in one glance.
+- If blocked, ask one more clarifying question **next** turn, never stack them.
 
 **First assistant message template (copy/paste shape):**
 
 ```markdown
-**What I think you're aiming for (so far):**
+**What I think you're aiming for:**
 - ...
 - ...
 
-**One question to anchor us:**
+**One question:**
 <single sentence>
 
-**Prompts to react to (pick any):**
-- Tradeoff: ...
-- Edge area: ...
-- UX vs architecture: ...
-- Scale implication: ...
-- Short-term vs long-term: ...
-
-**Working assumptions (tell me what’s wrong):**
+**I'm assuming (tell me if any of these are wrong):**
 - ...
 - ...
 ```
 
 For each iteration:
 
-1.  **Synthesize Current Understanding**
+1.  **Synthesize Current Understanding** (≤ 3 bullets)
 
     - What the feature appears to be
-    - Who it impacts
-    - What class of change this is (incremental, foundational, risky, trivial)
-    - Implied constraints
-
-2.  **Ask at most ONE high-leverage question** (only if needed to unblock discussion)
-
-3.  **Surface Tensions & Unknowns** via 3--5 prompts to react to (not interrogation), such as:
-
-    - Tradeoff
-    - Edge area
-    - Scale implication
-    - UX vs architecture tension
-    - Short-term vs long-term implication
+    - Who it impacts / what class of change (incremental, foundational, risky, trivial)
+    - Implied constraint worth surfacing
 
-4.  **Capture Emerging Assumptions** Explicitly note:
+2.  **Ask ONE high-leverage, open-ended question** anchored on purpose, users, success, or a hard constraint. Use "how/what/why" phrasing — not "which of these". Invite the user to think out loud.
 
-    - Working assumptions
-    - Tentative decisions
-    - Areas still unresolved
+3.  **State Working Assumptions** — the 1–3 most load-bearing beliefs you're operating on. Ask the user to flag anything wrong; do not turn these into extra questions.
 
-5.  Continue iteratively until:
+4.  Continue iteratively until:
 
     - Direction is clear
     - Or user says "proceed"
@@ -191,7 +171,7 @@ For each approach, provide:
 Lead with your recommendation and explain why. Apply YAGNI --- prefer
 simpler solutions.
 
-Use **AskUserQuestion** to confirm preferred direction if needed.
+Ask which direction resonates as an open question in the conversation ("Which of these fits best, or does something in between feel closer?"). Do **not** use AskUserQuestion here — keep it a discussion.
 
 ---
 

package/src/skills/brainstorming/SKILL.md

@@ -47,68 +47,53 @@ If requirements are clear, suggest: "Your requirements seem clear. Consider proc
 
 ### Phase 1: Understand the Idea
 
-Default to **discussion-first**. Questions are a tool of last resort to unblock discussion, not the main loop.
+Default to **one question at a time**. Readability beats coverage — the user pulls the next layer, you don't push all of it.
 
 **Default cadence (per iteration):**
 
-1. **Synthesize current understanding** (2--4 bullets)
-2. **Ask at most ONE high-leverage clarifying question** (only if needed)
-3. **Surface tensions & unknowns** via 3--5 **discussion prompts** (not interrogation)
-4. **Capture assumptions + tentative decisions** (bullets)
+1. **Synthesize current understanding** (≤ 3 short bullets)
+2. **Ask ONE high-leverage question** (the single most useful thing to resolve right now)
+3. **State working assumptions** (≤ 3 bullets, phrased as "tell me if any of these are wrong")
 
 **Hard rules:**
 
-- Ask **no more than one** clarifying question per iteration.
-- Do **not** ask follow-up questions in the same turn.
-- If ambiguity is blocking progress, ask **one** additional clarifying question max, then return to discussion prompts.
+- Exactly **one** question per turn. No follow-ups, no "also…", no multi-part questions.
+- No "prompts to react to" / "pick any" menus. If you're tempted to list options, pick the single best one and ask that.
+- Keep the whole turn short — think ≤ 12 lines of output. A reader should grasp it in one glance.
+- If ambiguity blocks progress, ask one more clarifying question next turn. Never stack them.
 
 **First response template (copy/paste shape):**
 
 ```markdown
-**What I think you're aiming for (so far):**
+**What I think you're aiming for:**
 - ...
 - ...
 
-**One question to anchor us:**
+**One question:**
 <single sentence>
 
-**Prompts to react to (pick any):**
-- Tradeoff: ...
-- Edge area: ...
-- UX vs architecture: ...
-- Scale implication: ...
-- Short-term vs long-term: ...
-
-**Working assumptions (tell me what’s wrong):**
+**I'm assuming (tell me if any of these are wrong):**
 - ...
 - ...
 ```
 
-**Choosing the ONE question (when needed):**
-
-- **Do not open with multiple-choice.** Open with synthesis and discussion prompts. Multiple-choice applies only when you have already done a dialogue iteration and are asking that one allowed question.
-
-1. **Prefer multiple choice when natural options exist** (only after a dialogue iteration)
-
-   - Good: "Should the notification be: (a) email only, (b) in-app only, or (c) both?"
-   - Avoid: "How should users be notified?"
-
-2. **Make it high-leverage**
-
-   - Anchor on **purpose**, **users**, **success**, or a **hard constraint**
-   - Avoid implementation sequencing ("how will we build it?")
-
-3. **Validate assumptions explicitly**
+**Choosing the ONE question:**
 
-   - "I'm assuming users will be logged in. Is that correct?"
+This is a **dialog**, not a survey. Ask open, conversational questions that invite the user to think out loud — not multiple-choice prompts that force a pick.
 
-4. **Prefer success criteria early**
+1. **Anchor on purpose, users, success, or a hard constraint.** Avoid implementation sequencing ("how will we build it?").
+2. **Keep it open-ended.** Prefer "how", "what", "why" over "which of these".
+   - Good: "How would you want users to be notified, and why that way?"
+   - Avoid: "Should the notification be: (a) email, (b) in-app, or (c) both?"
+3. **Validate a specific assumption** when that's the biggest unknown — phrased so the user can elaborate, not just yes/no.
+   - "I'm assuming users will be logged in when this triggers — is that right, and what happens if they aren't?"
+4. **Prefer success criteria early.**
    - "What would make you say 'this worked'?"
 
-**Prompt menu (examples):**
+**Question bank (pick one per turn — never list several):**
 
 - Purpose: "What problem is painful enough to fix now?"
-- Users/context: "Who is the primary user and what’s their moment-of-need?"
+- Users: "Who is the primary user and what's their moment-of-need?"
 - Constraints: "What constraint should we treat as immovable?"
 - Success: "What does success look like (observable behavior)?"
 - Edges: "What must not happen? What failure would be unacceptable?"
@@ -222,14 +207,16 @@ This prevents wasted effort on misaligned designs.
 
 ## Anti-Patterns to Avoid
 
-| Anti-Pattern                          | Better Approach                             |
-| ------------------------------------- | ------------------------------------------- |
-| Asking many questions in a row        | Ask 1 high-leverage question, then prompts  |
-| Jumping to implementation details     | Stay focused on WHAT, not HOW               |
-| Proposing overly complex solutions    | Start simple, add complexity only if needed |
-| Ignoring existing codebase patterns   | Research what exists first                  |
-| Making assumptions without validating | State assumptions explicitly and confirm    |
-| Creating lengthy design documents     | Keep it concise—details go in the plan      |
+| Anti-Pattern                           | Better Approach                             |
+| -------------------------------------- | ------------------------------------------- |
+| Asking many questions in a row         | Exactly one question per turn               |
+| Listing "prompts to react to"          | Pick the single best question and ask it    |
+| Dense walls of bullets                 | ≤ 12 lines per turn; readable at a glance   |
+| Jumping to implementation details      | Stay focused on WHAT, not HOW               |
+| Proposing overly complex solutions     | Start simple, add complexity only if needed |
+| Ignoring existing codebase patterns    | Research what exists first                  |
+| Making assumptions without validating  | State assumptions explicitly and confirm    |
+| Creating lengthy design documents      | Keep it concise—details go in the plan      |
 
 ## Integration with Planning
 

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

@@ -24,11 +24,12 @@ This skill is a config generator, not a survey. The developer interaction budget
 
 **Hard constraints — violating any of these is a skill failure:**
 
-- **One prompt total.** Do not emit numbered question lists (`1. … 2. … 3. …`). Do not split prompts across multiple messages. Phase 2 is the only user interaction.
-- **Never ask about skills.** Skill inclusion is not a decision — every skill in `$skills_dir` is included automatically. Do not ask "keep all four guardrails?", "which skills to include?", or anything equivalent.
-- **Never ask meta questions.** Do not surface observations like "project-specific skills appear elsewhere — flag as a gap?" or "strip extra sections?". If the template forbids something, silently conform; if it's out of scope, ignore it.
-- **Never present "ambiguous — need your call" sections.** Ambiguity is resolved by the deterministic rules below, then surfaced in the proposed config block for the user to override if they disagree. Pick a value. Do not ask.
-- **Never re-confirm.** After the user replies to the Phase 2 prompt (accept or overrides), write the file. No second confirmation pass.
+- **At most two prompts per run.** (1) Phase 1b alignment prompt — only if harness skill sets differ. (2) Phase 2 config block — always. No other questions.
+- **No numbered question lists.** Never emit `1. … 2. … 3. …` walls. Never split a single decision across multiple messages.
+- **Never ask about skill inclusion.** Every skill in any discovered skills directory is included in the Skill Index automatically. Do not ask "keep all four guardrails?" or "which skills to include?".
+- **Never ask meta questions.** No "project-specific skills appear elsewhere — flag as a gap?", no "strip extra sections?", no commentary on memory vs. code mismatches. If the template forbids something, silently conform.
+- **Never present "ambiguous — need your call" sections.** Ambiguity is resolved by the deterministic rules below and surfaced in the Phase 2 block for the user to override. Pick a value.
+- **Never re-confirm.** After the user replies to Phase 2, write the file. No second confirmation pass.
 
 **Ambiguity resolution (apply without asking):**
 
@@ -56,19 +57,16 @@ Announce the mode before proceeding.
 
 Check which directories exist at the project root. Do not assume any are present — record only what is actually found on disk.
 
-Known harness patterns to check: directories named `.agents`, `.claude`, `.cursor`. Check all three; others may exist.
+Known harness patterns: `.agents`, `.claude`, `.cursor`. Check all three; others may exist.
 
-For each found harness, note where its skills live:
-- `<harness>/skills/` — if that subdirectory exists
-- `.claude/` has no skills directory (agents only, in `.claude/agents/`)
+For each found harness, check `<harness>/skills/`. Record:
 
-Record detected harnesses as `$harnesses` (ordered list of directories found). This will be written to AGENTS.md.
+- `$harnesses` — ordered list of harness directories found
+- `$skills_dirs` — map of `<harness>` → `<harness>/skills/` for every harness that has a skills subdirectory
 
-If **no harness directories exist**, stop and tell the user:
+If **no harness directories exist**, stop:
 > No harness directories found. Run `npx compound-workflow install` first, then re-run this skill.
 
-Use the **first found skills directory** across `$harnesses` as the canonical source for skill discovery in Phase 3. Record this as `$skills_dir`.
-
 > **Note:** `harnesses` in AGENTS.md Repo Config may become stale if harness directories are added or removed. Re-run `/setup-agents` to refresh it.
 
 ### Project stack detection
@@ -102,6 +100,37 @@ For each value, state whether it was detected or defaulted.
 
 ---
 
+## Phase 1b: Discover Skills Across Harnesses
+
+For every entry in `$skills_dirs`, list subdirectories and read each `SKILL.md` frontmatter (`name`, `description`).
+
+Build `$skill_matrix`: `<skill name>` → `{harnesses where present, source description}`. The **Skill Index** in AGENTS.md is the union of all skill names across all harnesses.
+
+**If every harness with a skills directory has the same skill set:** proceed silently to Phase 2. No prompt, no table output.
+
+**If harnesses diverge** (a skill is in one harness but missing from another), emit the comparison table and one prompt:
+
+```
+Skill presence across harnesses:
+
+| Skill | <harness 1> | <harness 2> | ... |
+| --- | --- | --- |
+| <name> | ✓ | ✗ | ... |
+| <name> | ✓ | ✓ | ... |
+
+Skills differ across harnesses. Align them? Aligning copies each skill's files into every harness so all locations have the same set.
+
+Reply `align` to sync, `skip` to leave them as-is.
+```
+
+**If `align`:** for each skill, pick the harness where it lives as the source and copy its directory into every other harness's skills directory (create the directory if missing). Note what was copied in the final summary.
+
+**If `skip`:** proceed with the union as the Skill Index; record in the summary that harnesses remain out of sync.
+
+Either way, proceed to Phase 2 after this single prompt.
+
+---
+
 ## Phase 2: Confirm the Proposed Config
 
 This is the **only** user prompt in the skill. Emit one block and one question. Nothing else.
@@ -143,9 +172,11 @@ On reply: apply overrides (if any), proceed to Phase 3 and Phase 4. Do not re-co
 
 ## 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.
+Use `$skill_matrix` from Phase 1b. The Skill Index is the union of skill names across all harnesses. For each skill, use the `description` from that skill's `SKILL.md` frontmatter.
 
-**Include every discovered skill automatically. No user prompt.** The installed skill set is the source of truth. If the user wants to exclude a skill, they remove it from `$skills_dir` — this skill does not curate.
+Never reference a skill not present on disk. Never invent a description.
+
+**Include every discovered skill automatically. No user prompt.** If the user wants to exclude a skill, they remove it from the skills directories — this skill does not curate.
 
 **Update mode:** diff against the existing Skill Index silently and write the refreshed list. Do not surface the diff as a question.
 
@@ -198,6 +229,17 @@ Continuous improvement:
 - `/metrics` — log + assess a session
 - `/assess` — aggregate metrics and propose improvements
 
+## Orchestration Model
+
+The main agent stays lean. Context lives where it's needed, not at the top.
+
+- **Plan** selects the minimal skill set for the work and names each selection explicitly. Unused skills never load.
+- **Work** allocates tasks to subagents and passes only what each task needs: the problem statement, relevant file refs, success criteria. Not conversation history, not unrelated context.
+- **Subagents** run in isolation, return evidence and results. The main agent orchestrates, records outcomes, and moves to the next task.
+- **Skills load on demand.** Commands pull a skill into context only when a gate or step requires it — not as a precautionary baseline.
+
+Context budget rule: if a task can be done with less context, pass less. If a subagent can handle it, delegate.
+
 ## Non-negotiables (Structure Integrity)
 
 - **Commands are the public API.** Keep `/workflow:*` command docs stable; add capability via skills/agents, not new command variants.
@@ -268,7 +310,7 @@ After writing, verify:
 - [ ] Every skill in the Skill Index was discovered from `$skills_dir` — no invented entries
 - [ ] All skill descriptions come from `SKILL.md` frontmatter — none invented by the agent
 - [ ] No hardcoded tool, platform, or directory names
-- [ ] File is under 130 lines
+- [ ] File is under 160 lines
 
 If any check fails, fix before confirming completion.