compound-workflow 1.9.1 → 1.9.3

package/README.md

@@ -68,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.1",
+  "version": "1.9.3",
   "description": "Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.",
   "license": "MIT",
   "repository": {

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

@@ -16,6 +16,29 @@ 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:**
+
+- **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.
+
+**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.
@@ -70,25 +93,51 @@ 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
+
+This is the **only** user prompt in the skill. Emit one block and one question. Nothing else.
 
-Ask for any values that could not be detected. Ask one at a time.
+**Forbidden in this phase:**
 
-Required:
+- 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
 
-- `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
+**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.
 
-**Update mode only:** Show the current values and ask: "These values are already configured — confirm, update, or skip each?"
+Output exactly this structure — no preamble, no trailing questions:
+
+```
+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|updated]
+  worktree_copy_files: [<files>]     [detected|existing|updated]
+  harnesses: [<dirs>]                [detected]
+
+Reply `ok` to accept, or send `<key>: <value>` lines to override. Anything else cancels.
+```
+
+On reply: apply overrides (if any), proceed to Phase 3 and Phase 4. Do not re-confirm.
 
 ---
 
@@ -96,18 +145,9 @@ Required:
 
 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.
 
-**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.
+**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.
 
-Show the resolved list so the user can see what will be written:
-
-```
-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.
 
 ---
 
@@ -236,12 +276,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).