compound-workflow 1.9.2 → 1.9.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compound-workflow",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "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/skills/setup-agents/SKILL.md

@@ -16,6 +16,30 @@ triggers:
 
 Create or update a minimal, authoritative `AGENTS.md` for any project.
 
+---
+
+## Developer Experience Contract (CRITICAL)
+
+This skill is a config generator, not a survey. The developer interaction budget is **one round-trip**: propose a complete config, let the user accept or override.
+
+**Hard constraints — violating any of these is a skill failure:**
+
+- **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):**
+
+- **Monorepo with multiple apps:** pick the workspace whose `scripts.dev` / `scripts.test` matches the detected harness target, or the newest one by `package.json` mtime. Record as `[detected]` and let the user override in Phase 2.
+- **Multiple candidate commands (e.g. `npm test` vs `npm run test:web2:run`):** prefer the most specific workspace-scoped command over the root alias.
+- **Memory or prior config suggests a different target than current code:** treat code as source of truth. Surface the detected value; the user can override.
+- **Legacy/deprecated paths visible in code:** ignore for detection. Pick the active target.
+
+---
+
 ## Mode Detection
 
 Before doing anything, check whether `AGENTS.md` exists in the repo root.
@@ -33,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
@@ -79,53 +100,85 @@ 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
 
-Do not prompt field-by-field. Show the resolved config from Phase 1 as a single block and ask one question.
+This is the **only** user prompt in the skill. Emit one block and one question. Nothing else.
+
+**Forbidden in this phase:**
 
-**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.
+- Numbered question lists
+- Separate "Ambiguous — need your call" sections
+- Any prompt about skills, guardrails, extra sections, or template compliance
+- Per-field prompting ("confirm this? confirm that?")
+- Commentary about memory, deprecated paths, or detected inconsistencies outside the block itself
 
-Output format:
+**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 (references a command that no longer exists). Mark overrides `[updated]` so the user can see what changed.
+
+Output exactly this structure — no preamble, no trailing questions:
 
 ```
-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]
+Proposed AGENTS.md config (update|init mode):
+
+  default_branch: <value>            [detected|default|existing|updated]
+  project_tracker: <value>           [detected|default|existing|updated]
+  dev_server_url: <value>            [detected|default|existing|updated]
+  test_command: <value>              [detected|existing|updated]
+  test_fast_command: <value>         [detected|existing|updated|omit]
+  lint_command: <value>              [detected|existing|updated|omit]
+  typecheck_command: <value>         [detected|existing|updated|omit]
+  format_command: <value>            [detected|existing|updated|omit]
   worktree_dir: <value>              [default|existing]
-  worktree_install_command: <value>  [detected|existing]
-  worktree_copy_files: [<files>]     [detected|existing]
+  worktree_install_command: <value>  [detected|existing|updated]
+  worktree_copy_files: [<files>]     [detected|existing|updated]
   harnesses: [<dirs>]                [detected]
 
-Accept, or reply with `<key>: <value>` lines to override. Blank line accepts.
+Reply `ok` to accept, or send `<key>: <value>` lines to override. Anything else cancels.
 ```
 
-One round-trip. If the user accepts, proceed to Phase 3. If they override fields, apply the overrides and proceed — do not re-confirm.
+On reply: apply overrides (if any), proceed to Phase 3 and Phase 4. Do not re-confirm.
 
 ---
 
 ## 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.** The installed skill set is the source of truth; there is no curation step. Do not prompt the user to pick a subset.
+Never reference a skill not present on disk. Never invent a description.
 
-Show the resolved list so the user can see what will be written:
+**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.
 
-```
-Skill Index will include all installed skills from <$skills_dir>:
-  - <name> — <description from frontmatter>
-  - <name> — <description from frontmatter>
-  ...
-```
-
-**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.
+**Update mode:** diff against the existing Skill Index silently and write the refreshed list. Do not surface the diff as a question.
 
 ---
 
@@ -176,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.
@@ -246,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.
 
@@ -254,12 +318,19 @@ If any check fails, fix before confirming completion.
 
 ## Rules
 
-- Never add sections beyond what the template defines — keep it minimal
-- Never hardcode skill names — discover everything from the detected skills directory
-- Never hardcode harness paths — detect what exists on disk first; `harnesses` in AGENTS.md reflects reality, not assumptions
-- Never invent skill descriptions — always read from the skill's `SKILL.md` frontmatter
-- Never hardcode tool or platform names
-- Never duplicate content that lives in command or skill docs
-- In update mode, never silently overwrite values the user confirmed as correct
-- If a detected value looks wrong, surface it and ask — do not assume
-- When the Phase 4 template changes, update `src/AGENTS.md` to match (it is the populated default instance)
+**Developer experience (non-negotiable):**
+
+- One user prompt per run — the Phase 2 block. No other questions.
+- No numbered question lists, no "ambiguous — need your call" sections, no skill curation prompts, no meta-observations about the codebase.
+- Resolve ambiguity deterministically using the rules in the Developer Experience Contract. Surface the pick in the block; let the user override.
+
+**Content integrity:**
+
+- Never add sections beyond what the template defines — keep it minimal. Silently conform; do not ask.
+- Never hardcode skill names — discover everything from the detected skills directory.
+- Never hardcode harness paths — detect what exists on disk first; `harnesses` in AGENTS.md reflects reality, not assumptions.
+- Never invent skill descriptions — always read from the skill's `SKILL.md` frontmatter.
+- Never hardcode tool or platform names.
+- Never duplicate content that lives in command or skill docs.
+- In update mode, preserve values that are still valid; only replace stale or empty ones.
+- When the Phase 4 template changes, update `src/AGENTS.md` to match (it is the populated default instance).