compound-workflow 1.9.4 → 1.9.6

package/package.json

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

package/scripts/install-cli.mjs

@@ -2,14 +2,14 @@
 /**
  * compound-workflow install
  *
- * Copies agents, skills, and commands from the package into target platform dirs:
- *   .claude/agents/   — flat agent .md files (Claude Code)
- *   .cursor/agents/   — agents preserving subdirs (Cursor)
- *   .cursor/skills/   — skill dirs (Cursor)
- *   .cursor/commands/ — command .md files (Cursor)
- *   .agents/agents/   — agents (OpenCode / general)
- *   .agents/skills/   — skills (OpenCode / general)
- *   .agents/commands/ — commands (OpenCode / general)
+ * Copies agents, skills, and commands from the package into every harness dir.
+ * Harnesses are declared in HARNESSES below; every harness receives all three
+ * asset kinds so skills and commands stay in parity across .claude/, .cursor/,
+ * and .agents/. Only agent layout varies per harness (flat vs. recursive).
+ *
+ *   .claude/{agents,skills,commands}  — Claude Code (flat agents)
+ *   .cursor/{agents,skills,commands}  — Cursor (recursive agents)
+ *   .agents/{agents,skills,commands}  — OpenCode / generic (recursive agents)
  *
  * Also writes opencode.json, AGENTS.md, and standard docs directories.
  *
@@ -365,6 +365,18 @@ function parseArgs(argv) {
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// Harness registry — every harness receives agents + skills + commands.
+// Agent layout varies because Claude Code requires flat .md files while
+// Cursor and OpenCode preserve subdirectories.
+// ---------------------------------------------------------------------------
+
+const HARNESSES = [
+  { name: ".claude", agentsMode: "flat" },
+  { name: ".cursor", agentsMode: "recursive" },
+  { name: ".agents", agentsMode: "recursive" },
+];
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -391,18 +403,16 @@ function main() {
   console.log("Package:", PACKAGE_ROOT);
   console.log("OpenCode CLI:", hasCommand("opencode") ? "yes" : "no");
 
-  // .claude/agents/ — flat (Claude Code requires flat .md files)
-  copyAgentsFlat(srcAgents, path.join(targetRoot, ".claude", "agents"), args.dryRun, ".claude/agents/");
+  for (const h of HARNESSES) {
+    const agentsDest = path.join(targetRoot, h.name, "agents");
+    const skillsDest = path.join(targetRoot, h.name, "skills");
+    const commandsDest = path.join(targetRoot, h.name, "commands");
 
-  // .cursor/agents/, .cursor/skills/, .cursor/commands/
-  copyAgentsRecursive(srcAgents, path.join(targetRoot, ".cursor", "agents"), args.dryRun, ".cursor/agents/");
-  copySkills(srcSkills, path.join(targetRoot, ".cursor", "skills"), args.dryRun, ".cursor/skills/");
-  copyCommands(srcCommands, path.join(targetRoot, ".cursor", "commands"), args.dryRun, ".cursor/commands/");
-
-  // .agents/agents/, .agents/skills/, .agents/commands/ (OpenCode / general)
-  copyAgentsRecursive(srcAgents, path.join(targetRoot, ".agents", "agents"), args.dryRun, ".agents/agents/");
-  copySkills(srcSkills, path.join(targetRoot, ".agents", "skills"), args.dryRun, ".agents/skills/");
-  copyCommands(srcCommands, path.join(targetRoot, ".agents", "commands"), args.dryRun, ".agents/commands/");
+    const copyAgents = h.agentsMode === "flat" ? copyAgentsFlat : copyAgentsRecursive;
+    copyAgents(srcAgents, agentsDest, args.dryRun, `${h.name}/agents/`);
+    copySkills(srcSkills, skillsDest, args.dryRun, `${h.name}/skills/`);
+    copyCommands(srcCommands, commandsDest, args.dryRun, `${h.name}/commands/`);
+  }
 
   writeOpenCodeJson(targetRoot, packageSrc, args.dryRun);
   writeAgentsMd(targetRoot, PACKAGE_ROOT, args.dryRun);

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