compound-workflow 1.4.3 → 1.4.5

package/README.md

@@ -1,193 +1,84 @@
-# Compound Workflow (.agents)
+# Compound Workflow
 
-A portable, command-first workflow: **clarify → plan → execute → verify → capture**. Commands are the public API; skills and agents are composable internals.
+Compound Workflow is a portable, command-first system for shipping software with less ambiguity and stronger verification.
+It follows a simple cycle: **clarify -> plan -> execute -> verify -> capture**.
+Use it when you want repeatable delivery without ad-hoc process drift.
 
-It reduces delivery failures from **unclear intent**, **weak verification**, and **lost context**. Use it when you want structured cycles without ad-hoc tooling.
+Inspired by [Compound Engineering](https://every.to/guides/compound-engineering) (Every).
 
-*This template and README are continually refined during development.*
+Best fit when you need:
 
-Inspired by [Compound Engineering](https://every.to/guides/compound-engineering) (Every) — the AI-native philosophy that each unit of work should compound into the next.
+- Clear intent and acceptance criteria before coding
+- Structured execution with explicit review gates
+- A repeatable process that captures reusable learnings
 
-Runtime assets live in `src/.agents/` and `src/AGENTS.md`. Supports **Cursor**, **Claude**, and **OpenCode** via one Install action per project.
+## Workflow
 
----
-
-## Get started
-
-**1. Add the package and run Install** (in the project where you want the workflow):
-
-```bash
-npm install compound-workflow
-npx compound-workflow install
-npx compound-workflow install all
-```
-
-**2. Choose how you use it:**
-
-- **Cursor:** If your project already has a `.cursor` directory, Install will create the correct structure: one symlink per skill under `.cursor/skills/`, plus `.cursor/agents`, `.cursor/commands`, and `.cursor/references` (each symlinked to the package). No plugin needed. Use the plugin from this repo if you need a different loading method.
-- **OpenCode:** Install writes `opencode.json` and a symlink at `.agents/compound-workflow-skills`; OpenCode loads from the package. Run `/install` or `npx compound-workflow install` in the project.
-- **Claude:** Add the compound-workflow plugin from this repo. In any repo, run `/install` or the CLI above.
-
-**What Install does:** Merges `AGENTS.md` (preserves your Repo Config Block), creates standard dirs (`docs/`, `todos/`), writes `opencode.json` (for OpenCode), and—if the project has a `.cursor` directory—creates `.cursor/skills/<skill>`, `.cursor/agents`, `.cursor/commands`, and `.cursor/references` (symlinks into the package). All paths reference `node_modules/compound-workflow`; no file copying.
-
-**CLI options:** `all` / `--all` (full install shortcut; same as `--cursor`), `--dry-run` (preview), `--root /path/to/project`, `--no-config` (skip Repo Config Block reminder), `--cursor` (create `.cursor` and wire Cursor symlinks even if `.cursor` does not already exist).
-
-**Legacy (clone inside repo):** If you cloned this repo inside a host repo and need to copy files without npm, use `./scripts/sync-into-repo.sh` (copy only; does not update opencode.json). Prefer the npm + Install flow above.
-
-To update to a new release, see [Updating compound-workflow](#updating-compound-workflow).
-
----
-
-## Updating compound-workflow
-
-- **Cursor (plugin):** If you load the plugin from this repo, pull latest and reload the plugin in Cursor.
-- **Cursor (npm + .cursor):** Run `npm update compound-workflow`, then run **Install** again (`npx compound-workflow install`) to refresh the `.cursor/skills`, `.cursor/agents`, `.cursor/commands`, and `.cursor/references` symlinks and AGENTS.md.
-- **OpenCode / npm:** Run `npm update compound-workflow` (or bump the version in `package.json` and `npm install`), then run **Install** again. This refreshes `opencode.json`, merges the latest `AGENTS.md` template, and ensures dirs exist; Repo Config Block is preserved.
-- **Claude (plugin):** Update via the editor’s plugin; if from repo, pull latest and reload.
-
----
-
-## Workflow at a glance
-
-Clarify what to build -> plan how (fidelity + confidence) -> triage todos -> execute -> review -> capture learnings -> log and assess.
+The workflow turns a request into validated output and reusable team knowledge.
 
 ```mermaid
 flowchart LR
-  A["brainstorm"] --> B["plan"] --> C["triage"] --> D["work"] --> E["review"] --> F["capture"] --> G["metrics"]
+  A["brainstorm"] --> B["plan"] --> C["work (includes triage)"] --> D["review"] --> E["capture"] --> F["metrics"]
 ```
 
----
-
-If docs conflict: follow [docs/principles/workflow-baseline-principles.md](docs/principles/workflow-baseline-principles.md), then [src/AGENTS.md](src/AGENTS.md), then command docs under [src/.agents/commands/](src/.agents/commands/).
-
----
-
-## Step-by-step: intent and commands
-
-| Step | Intent | Command | Output / note |
-|------|--------|---------|---------------|
-| Clarify what to build | Dialogue only; no code | `/workflow:brainstorm [topic]` | `docs/brainstorms/` |
-| Define how (fidelity + confidence) | Plan only; no code; include agentic access + validation contract | `/workflow:plan [description or brainstorm path]` | `docs/plans/` |
-| Ready the queue | Priority/dependencies + executable agentic contract checks for pending todos | `/workflow:triage` | — |
-| Execute | File-based todos; risk-tier testing; evidence-backed implementation; no auto-ship | `/workflow:work <plan-path>` | `todos/` |
-| Validate quality | Independent, evidence-based review for code/config changes (docs-only exempt); no fixes by default | `/workflow:review [PR, branch, or current]` | pass / pass-with-notes / fail |
-| Capture learnings | One solution doc for future use | `/workflow:compound [context]` | `docs/solutions/` |
-| Log and improve | Session log + optional aggregate review | `/metrics` + `/assess weekly 7` (or monthly) | `docs/metrics/daily/`, weekly/monthly |
-
-#### 1. Clarify (brainstorm)
-
-**Intent:** Dialogue only; no code. **Command:** `/workflow:brainstorm [topic]`. **Output:** `docs/brainstorms/`.
-
-#### 2. Define how (plan)
-
-**Intent:** Plan only; no code; fidelity + confidence; include an agentic access + validation contract. **Command:** `/workflow:plan [description or brainstorm path]`. **Output:** `docs/plans/`.
-
-#### 3. Ready the queue (triage)
-
-**Intent:** Priority/dependencies for pending todos and readiness checks for agentic executability. **Command:** `/workflow:triage`. **Output:** —.
-
-#### 4. Execute (work)
-
-**Intent:** File-based todos; risk-tier testing; success-criteria evidence + quality gates before completion; no auto-ship. **Command:** `/workflow:work <plan-path>`. **Output:** `todos/`.
-
-`/workflow:work` must not run until `/workflow:triage` has approved executable ready todos.
+## Get Started
 
-For code/config changes, `/workflow:work` ends at implementation-complete and requires `/workflow:review` before workflow completion. Docs-only work can close without `/workflow:review`.
-
-#### 5. Validate quality (review)
-
-**Intent:** Independent, evidence-based review with explicit independence mode (`independent|degraded`) and evidence disclosure; no fixes by default. **Command:** `/workflow:review [PR|branch|current]`. **Output:** pass / pass-with-notes / fail.
-
-#### 6. Capture learnings (compound)
-
-**Intent:** One solution doc for future use. **Command:** `/workflow:compound [context]`. **Output:** `docs/solutions/`.
-
-#### 7. Log and improve
-
-**Intent:** Session log + optional aggregate review. **Command:** `/metrics` + `/assess weekly 7` (or monthly). **Output:** `docs/metrics/daily/`, weekly/monthly.
-
-**Optional QA:** **`/test-browser [PR|branch|current]`** — Browser validation on affected pages via **agent-browser CLI only** (not MCP). Install: `npm install -g agent-browser` then `agent-browser install`. See [src/.agents/commands/test-browser.md](src/.agents/commands/test-browser.md).
-
----
-
-## Command reference
-
-**Onboarding:** `/install` — one action: merges AGENTS.md, creates dirs, preserves Repo Config Block; writes opencode.json (OpenCode) and, if present, symlinks into `.cursor/skills/` (Cursor). Run `npx compound-workflow install` in the project (requires `npm install compound-workflow`). Re-run after `npm update compound-workflow` to refresh config; see [Updating compound-workflow](#updating-compound-workflow).
-
-**Core workflow:** See [Step-by-step](#step-by-step-intent-and-commands) above.
-
-**QA:** `/test-browser [PR|branch|current]` — browser checks on affected routes (agent-browser CLI only).
-
-**Improvement:** `/metrics [plan|todo|pr|solution|label]` — log session to `docs/metrics/daily/` and assess. `/assess [daily|weekly|monthly] [count]` — aggregate metrics and optional summary files.
-
-**Experimental:** `/workflow:review-v2 [PR|branch|current]` — interactive snippet review; output-only (no GitHub publish).
-
-Full detail: [src/AGENTS.md](src/AGENTS.md), [src/.agents/commands/](src/.agents/commands/).
-
----
-
-## Artifacts
-
-- **Brainstorms:** `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`
-- **Plans:** `docs/plans/YYYY-MM-DD-<type>-<slug>-plan.md`
-- **Todos:** `todos/{id}-{status}-{priority}-{slug}.md`
-- **Solutions:** `docs/solutions/<category>/YYYY-MM-DD-<module-slug>-<symptom-slug>.md`
-- **Metrics:** `docs/metrics/daily/YYYY-MM-DD.md`, `docs/metrics/weekly/YYYY-WW.md`, `docs/metrics/monthly/YYYY-MM.md`
-
----
-
-## How it works (internals)
-
-Commands are the public API. Skills and agents are invoked by commands; you don’t call them directly.
-
-- **Workflow skills:** `brainstorming`, `file-todos`, `compound-docs`, `document-review`, `technical-review`, `git-worktree`, `agent-browser`, `process-metrics`, `react-ddd-mvc-frontend`, `xstate-actor-orchestration`, `standards`.
-- **State orchestration:** Use a state-orchestration skill when complexity exceeds simple local state (e.g. `xstate-actor-orchestration` per Skill Index)—UI container-as-orchestrator flows, backend/internal actor orchestration, receptionist/child-actor patterns, retries/timeouts/cancellation, or boolean-flag sprawl.
-- **Skill-local metadata:** Some skills may include tool-specific metadata under `src/.agents/skills/<skill>/agents/` (for example `openai.yaml`) when required by skill validation/runtime.
-- **Guardrail standards:** `data-foundations`, `pii-protection-prisma`, `financial-workflow-integrity`, `audit-traceability` — applied when work touches multi-tenant data, PII, money, or audit.
-- **Agents:** Used by plan, review, and work for research, lint, and validation (e.g. `repo-research-analyst`, `learnings-researcher`, `git-history-analyzer`, `agent-native-reviewer`, `planning-technical-reviewer`).
-
-Full “when to use what” and reference standards: [src/AGENTS.md](src/AGENTS.md).
-
----
-
-## Guardrails
-
-- **No auto-ship:** `/workflow:work` and `/workflow:review` do not commit, push, or create PRs by default.
-
-- **Brainstorm and plan do not write code.** Output is documents only.
+```bash
+npm install compound-workflow
+```
 
-- **Todo completion requires evidence:** acceptance/success criteria plus quality gates must be recorded before `complete`.
+`npm install` adds the package and automatically configures your repo (`AGENTS.md`, required directories, and runtime wiring).
+If your package manager skips lifecycle scripts, run `npx compound-workflow install` manually.
 
-- **Independent review policy:** code/config changes require `/workflow:review` before workflow completion; docs-only changes are exempt.
+Install configures:
 
-- **Standards baseline policy:** code/config changes must pass `skill: standards` as a hard gate (declarative flow, immutable transforms, maintainability boundaries) in both `/workflow:work` and `/workflow:review`; docs-only changes are exempt.
+- Workflow template content in `AGENTS.md`
+- Standard workspace directories for plans/todos/docs
+- Runtime configuration used by supported tools
 
-- **Quality gate fallback:** if `lint_command` or `typecheck_command` is missing from repo config, workflow asks once for run-provided commands and continues only if they pass.
+## Critical Path
 
-- **Artifact policy:** do not create ad-hoc artifacts outside canonical outputs (`docs/plans`, `todos`, `docs/solutions`, `docs/metrics`) unless explicitly requested.
+After install, use this default sequence:
 
-- Add a separate shipping command if you want automated commit/PR and quality gates.
+1. `/workflow:brainstorm` for requirements clarity
+2. `/workflow:plan` for implementation design
+3. `/workflow:work` to execute against the approved plan (includes automatic triage)
+4. `/workflow:review` to validate quality before completion
+5. `/workflow:compound` to capture reusable learnings
 
----
+Optional:
 
-## Troubleshooting
+- `/workflow:triage` for manual backlog curation before or during execution
+- `/metrics` and `/assess` for process improvement
 
-**Skills not showing in Cursor?** Cursor discovers skills from (1) the plugin’s `skills/` directory when you load the plugin from this repo, or (2) the project’s `.cursor/skills/` when you use npm: ensure the project has a `.cursor` directory and run `npx compound-workflow install`—Install creates the full structure (`.cursor/skills/<skill>`, `.cursor/agents`, `.cursor/commands`, `.cursor/references`). If skills still don’t appear, check Cursor Settings → Rules and any `permission.skill` settings.
+## Commands (Quick Map)
 
-If your project does not already have `.cursor/`, run `npx compound-workflow install --cursor` to create it and wire links. Install now fails fast when existing non-symlink files/directories block `.cursor` link creation, to prevent partial installs and command drift.
+Core flow: `/workflow:brainstorm` -> `/workflow:plan` -> `/workflow:work` -> `/workflow:review` -> `/workflow:compound` -> `/metrics` (optional `/assess` for rollups).
 
-**Skills not showing in OpenCode?** OpenCode uses the `.agents/compound-workflow-skills` symlink and `opencode.json` `skills.paths`. Run Install from the project root (`npx compound-workflow install`). The learnings-capture skill is named **compound-docs** (hyphen, plural); **compound_doc** (underscore) is an alias that resolves to the same skill.
+| Command | Purpose | Related skills | Related agents |
+|---|---|---|---|
+| `/install` | Configure workflow files and runtime wiring in the repo | install CLI (no workflow skill routing) | none |
+| `/workflow:brainstorm` | Clarify what to build through structured discussion | `brainstorming` (primary), `document-review` (optional refinement) | `repo-research-analyst` |
+| `/workflow:plan` | Convert intent into an executable plan with fidelity/confidence | state-orchestration skill when needed (for example `xstate-actor-orchestration`) | `repo-research-analyst`, `learnings-researcher`, `best-practices-researcher`, `framework-docs-researcher`, `git-history-analyzer`, `spec-flow-analyzer`, `planning-technical-reviewer` |
+| `/workflow:triage` | Manual queue curation for complex/multi-item backlogs (optional; `/workflow:work` runs triage automatically) | `file-todos` | none |
+| `/workflow:work` | Execute plan/todos with quality gates and validation evidence | `git-worktree`, `file-todos`, `standards`, state-orchestration skill when needed | `repo-research-analyst`, `learnings-researcher`, `best-practices-researcher`, `framework-docs-researcher`, `git-history-analyzer` |
+| `/workflow:review` | Perform independent quality review before completion | `git-worktree` (for non-current targets), `standards` | `learnings-researcher`, `lint`, `bug-reproduction-validator`, `git-history-analyzer`, `framework-docs-researcher`, `agent-native-reviewer` |
+| `/workflow:compound` | Capture reusable implementation learnings in `docs/solutions/` | `compound-docs` (primary), `document-review` (optional) | `learnings-researcher`, `best-practices-researcher`, `framework-docs-researcher` |
+| `/metrics` | Log session outcomes and improvement actions | `process-metrics`, `file-todos` (optional for follow-ups) | none |
+| `/assess` | Aggregate metrics trends and propose process improvements | `file-todos` (for approved follow-up actions) | none |
+| `/test-browser` | Validate affected routes with browser-level checks | `agent-browser`, `git-worktree` (optional branch isolation) | none |
 
----
+Canonical command docs: [src/.agents/commands/](src/.agents/commands/)
 
-## Configuration and optional bits
+## Learn More
 
-**Repo configuration:** Commands read a **Repo Config Block** (YAML) in `AGENTS.md` for `default_branch`, `dev_server_url`, `test_command`, `lint_command`, `typecheck_command`, etc. Run **`/install`** once; then edit `AGENTS.md` to set the Repo Config Block.
+- Workflow principles: [docs/principles/workflow-baseline-principles.md](docs/principles/workflow-baseline-principles.md)
+- Project command and policy index: [src/AGENTS.md](src/AGENTS.md)
+- Command definitions: [src/.agents/commands/](src/.agents/commands/)
 
-**agent-browser:** `/test-browser` uses the agent-browser CLI only. Install: `npm install -g agent-browser` then `agent-browser install`. See [src/.agents/commands/test-browser.md](src/.agents/commands/test-browser.md).
+If docs conflict: follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then command docs.
 
-**Source of truth**
+Guardrails:
 
-- Workflows and commands: [src/.agents/](src/.agents/)
-- Baseline principles (tie-breaker): [docs/principles/workflow-baseline-principles.md](docs/principles/workflow-baseline-principles.md)
-- Principles and skill index: [src/AGENTS.md](src/AGENTS.md)
+- Independent review policy: code/config changes require `/workflow:review` before workflow completion (docs-only changes are exempt).
+- Standards baseline policy: code/config changes must pass the standards baseline gate in `/workflow:work` and `/workflow:review`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compound-workflow",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "description": "Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.",
   "license": "MIT",
   "repository": {
@@ -18,7 +18,9 @@
     "skills"
   ],
   "scripts": {
-    "check:pack-readme": "node scripts/check-pack-readme.mjs"
+    "postinstall": "node scripts/postinstall.mjs",
+    "check:pack-readme": "node scripts/check-pack-readme.mjs",
+    "test:install": "node --test tests/install-cli.test.mjs"
   },
   "engines": {
     "node": ">=18"

package/scripts/check-workflow-contracts.mjs

@@ -11,6 +11,16 @@ const requiredChecks = [
     pattern: "tie-breaker",
     description: "baseline principles tie-breaker rule",
   },
+  {
+    file: "docs/principles/workflow-baseline-principles.md",
+    pattern: "/workflow:work` - implement in isolation with evidence (includes required triage gate)",
+    description: "canonical flow routes triage through work by default",
+  },
+  {
+    file: "docs/principles/workflow-baseline-principles.md",
+    pattern: "Optional manual command:",
+    description: "principles preserve standalone manual triage command",
+  },
   {
     file: "src/AGENTS.md",
     pattern: "## Contract Precedence",
@@ -33,12 +43,18 @@ const requiredChecks = [
   },
   {
     file: "README.md",
-    pattern: "code/config changes require `/workflow:review`",
+    anyOf: [
+      "code/config changes require `/workflow:review`",
+      "Independent review policy:",
+    ],
     description: "README review gate policy",
   },
   {
     file: "README.md",
-    pattern: "Standards baseline policy:",
+    anyOf: [
+      "Standards baseline policy:",
+      "standards baseline gate",
+    ],
     description: "README standards baseline guardrail",
   },
   {
@@ -51,16 +67,36 @@ const requiredChecks = [
     pattern: "Contract precedence:",
     description: "triage command precedence note",
   },
+  {
+    file: "src/.agents/commands/workflow/triage.md",
+    pattern: "independently runnable",
+    description: "triage command explicitly standalone while work auto-runs triage",
+  },
   {
     file: "src/.agents/commands/workflow/work.md",
     pattern: "Contract precedence:",
     description: "work command precedence note",
   },
+  {
+    file: "src/.agents/commands/workflow/plan.md",
+    pattern: "Start `/workflow:work`",
+    description: "plan command default next-step routes to work",
+  },
   {
     file: "src/.agents/commands/workflow/work.md",
     pattern: "HARD GATE - WORKTREE FIRST",
     description: "worktree hard-gate wording in work command",
   },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "required prompt/create gate",
+    description: "mandatory worktree decision prompt/create gate in work command",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "Do not infer or assume an answer when the user has not answered.",
+    description: "worktree decision cannot be silently assumed",
+  },
   {
     file: "src/.agents/commands/workflow/work.md",
     pattern:
@@ -160,7 +196,11 @@ const readFile = (relativePath) => {
 
 for (const check of requiredChecks) {
   const contents = readFile(check.file);
-  if (!contents.includes(check.pattern)) {
+  const hasPattern = check.pattern ? contents.includes(check.pattern) : false;
+  const hasAnyOf = Array.isArray(check.anyOf)
+    ? check.anyOf.some((pattern) => contents.includes(pattern))
+    : false;
+  if (!hasPattern && !hasAnyOf) {
     failures.push(`Missing required contract text (${check.description}) in ${check.file}`);
   }
 }

package/scripts/install-cli.mjs

@@ -14,29 +14,32 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function usage(exitCode = 0) {
   const msg = `
 Usage:
-  npx compound-workflow install [all|--all] [--root <projectDir>] [--dry-run] [--no-config] [--cursor]
+  npx compound-workflow install [all|--all] [--root <projectDir>] [--dry-run] [--no-config]
 
 One action: writes opencode.json (loads from package), merges AGENTS.md, creates dirs,
 and prompts for Repo Config Block (unless --no-config).
 
-  all, --all    Full install shortcut (enables Cursor integration; creates .cursor if needed)
+  all, --all    Kept for compatibility
   --root <dir>   Project directory (default: cwd)
   --dry-run      Print planned changes only
   --no-config   Skip Repo Config Block prompt (only write opencode.json + AGENTS.md + dirs)
-  --cursor      Force Cursor integration (create .cursor if missing, then wire links)
 `;
   (exitCode === 0 ? console.log : console.error)(msg.trimStart());
   process.exit(exitCode);
 }
 
 function parseArgs(argv) {
-  const out = { root: process.cwd(), dryRun: false, noConfig: false, cursor: false };
+  const out = { root: process.cwd(), dryRun: false, noConfig: false };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--dry-run") out.dryRun = true;
     else if (a === "--no-config") out.noConfig = true;
-    else if (a === "--cursor") out.cursor = true;
-    else if (a === "--all" || a === "all") out.cursor = true;
+    else if (a === "--cursor") {
+      // Deprecated compatibility alias; install now auto-detects .cursor.
+    }
+    else if (a === "--all" || a === "all") {
+      // Deprecated compatibility alias; install now auto-detects .cursor.
+    }
     else if (a === "--root") {
       const v = argv[i + 1];
       if (!v) usage(1);
@@ -58,7 +61,10 @@ function realpathSafe(p) {
 
 const packageRoot = realpathSafe(path.join(__dirname, ".."));
 const packageAgents = path.join(packageRoot, "src", ".agents");
-const PKG_PREFIX = "node_modules/compound-workflow";
+const LOCAL_RUNTIME_ROOT = ".agents/compound-workflow";
+const LOCAL_COMMANDS_ROOT = `${LOCAL_RUNTIME_ROOT}/commands`;
+const LOCAL_AGENTS_ROOT = `${LOCAL_RUNTIME_ROOT}/agents`;
+const LOCAL_REFERENCES_ROOT = `${LOCAL_RUNTIME_ROOT}/references`;
 
 function walkFiles(dirAbs, predicate) {
   const out = [];
@@ -101,14 +107,14 @@ function discoverCommands(agentsRoot) {
   const files = walkFiles(commandsDir, (p) => p.endsWith(".md"));
   const map = new Map();
   for (const fileAbs of files) {
-    const rel = path.relative(packageRoot, fileAbs).replaceAll(path.sep, "/");
+    const relWithinCommands = path.relative(commandsDir, fileAbs).replaceAll(path.sep, "/");
     const md = fs.readFileSync(fileAbs, "utf8");
     const fm = parseFrontmatter(md);
     const id = (fm.invocation || fm.name || path.basename(fileAbs, ".md")).trim();
     const description = (fm.description || id).trim();
     if (!id) continue;
-    const pkgRel = `${PKG_PREFIX}/${rel}`;
-    map.set(id, { id, rel: pkgRel, description });
+    const localRel = `${LOCAL_COMMANDS_ROOT}/${relWithinCommands}`;
+    map.set(id, { id, rel: localRel, description });
   }
   return map;
 }
@@ -118,18 +124,65 @@ function discoverAgents(agentsRoot) {
   const files = walkFiles(agentsDir, (p) => p.endsWith(".md"));
   const map = new Map();
   for (const fileAbs of files) {
-    const rel = path.relative(packageRoot, fileAbs).replaceAll(path.sep, "/");
+    const relWithinAgents = path.relative(agentsDir, fileAbs).replaceAll(path.sep, "/");
     const md = fs.readFileSync(fileAbs, "utf8");
     const fm = parseFrontmatter(md);
     const id = (fm.name || path.basename(fileAbs, ".md")).trim();
     const description = (fm.description || id).trim();
     if (!id) continue;
-    const pkgRel = `${PKG_PREFIX}/${rel}`;
-    map.set(id, { id, rel: pkgRel, description });
+    const localRel = `${LOCAL_AGENTS_ROOT}/${relWithinAgents}`;
+    map.set(id, { id, rel: localRel, description });
   }
   return map;
 }
 
+function copyDirContents(sourceDir, targetDir) {
+  if (!fs.existsSync(sourceDir)) return;
+  fs.mkdirSync(targetDir, { recursive: true });
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const src = path.join(sourceDir, entry.name);
+    const dst = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      copyDirContents(src, dst);
+      continue;
+    }
+    if (entry.isFile()) {
+      fs.mkdirSync(path.dirname(dst), { recursive: true });
+      fs.copyFileSync(src, dst);
+    }
+    if (entry.isSymbolicLink()) {
+      const real = realpathSafe(src);
+      const realStat = fs.statSync(real);
+      if (realStat.isDirectory()) {
+        copyDirContents(real, dst);
+      } else if (realStat.isFile()) {
+        fs.mkdirSync(path.dirname(dst), { recursive: true });
+        fs.copyFileSync(real, dst);
+      }
+    }
+  }
+}
+
+function syncRuntimeAssets(targetRoot, dryRun) {
+  const mappings = [
+    { label: "commands", src: path.join(packageAgents, "commands"), dst: path.join(targetRoot, LOCAL_COMMANDS_ROOT) },
+    { label: "agents", src: path.join(packageAgents, "agents"), dst: path.join(targetRoot, LOCAL_AGENTS_ROOT) },
+    { label: "references", src: path.join(packageAgents, "references"), dst: path.join(targetRoot, LOCAL_REFERENCES_ROOT) },
+  ];
+
+  for (const mapping of mappings) {
+    if (!fs.existsSync(mapping.src)) continue;
+    if (dryRun) {
+      console.log("[dry-run] Would sync", mapping.label, "to", path.relative(targetRoot, mapping.dst));
+      continue;
+    }
+    fs.rmSync(mapping.dst, { recursive: true, force: true });
+    copyDirContents(mapping.src, mapping.dst);
+    console.log("Synced", mapping.label + ":", path.relative(targetRoot, mapping.dst));
+  }
+}
+
 function ensureObject(v) {
   return v && typeof v === "object" && !Array.isArray(v) ? v : {};
 }
@@ -237,39 +290,29 @@ function ensureSkillsSymlink(targetRoot, dryRun) {
   }
 }
 
-function ensureCursorDirSymlink(targetRoot, cursorSubdir, pkgSubdir, dryRun, label, cursorReady) {
+function ensureCursorDirSync(targetRoot, cursorSubdir, pkgSubdir, dryRun, label, cursorReady) {
   const cursorDir = path.join(targetRoot, ".cursor");
   if (!cursorReady) return { status: "skipped-missing-cursor" };
   const pkgPath = path.join(packageRoot, "src", ".agents", pkgSubdir);
   if (!fs.existsSync(pkgPath)) return { status: "skipped-missing-package-path" };
 
-  const linkPath = path.join(cursorDir, cursorSubdir);
-  const targetRel = path.join("..", "node_modules", "compound-workflow", "src", ".agents", pkgSubdir);
-  const targetAbs = path.resolve(path.dirname(linkPath), targetRel);
-
+  const targetPath = path.join(cursorDir, cursorSubdir);
   if (dryRun) {
-    console.log("[dry-run] Would create .cursor/" + cursorSubdir, "symlink (Cursor)");
+    console.log("[dry-run] Would sync .cursor/" + cursorSubdir, "from", label || pkgSubdir, "(Cursor)");
     return { status: "dry-run" };
   }
 
-  let needCreate = true;
-  try {
-    const stat = fs.lstatSync(linkPath);
-    if (stat.isSymbolicLink() && symlinkPointsTo(linkPath, targetAbs)) needCreate = false;
-    else if (!stat.isSymbolicLink()) {
-      console.warn("Skipped", ".cursor/" + cursorSubdir, "because it exists and is not a symlink");
-      return { status: "blocked-nonsymlink", path: linkPath };
+  if (fs.existsSync(targetPath)) {
+    const stat = fs.lstatSync(targetPath);
+    if (!stat.isDirectory()) {
+      return { status: "blocked-nondirectory", path: targetPath };
     }
-  } catch (_) {}
-
-  if (needCreate) {
-    removePathIfExists(linkPath);
-    const type = process.platform === "win32" ? "dir" : "dir";
-    fs.symlinkSync(targetRel, linkPath, type);
-    console.log("Created", ".cursor/" + cursorSubdir, "->", label || pkgSubdir, "(Cursor)");
-    return { status: "created" };
   }
-  return { status: "ok" };
+
+  fs.rmSync(targetPath, { recursive: true, force: true });
+  copyDirContents(pkgPath, targetPath);
+  console.log("Synced", ".cursor/" + cursorSubdir, "from", label || pkgSubdir, "(Cursor)");
+  return { status: "synced" };
 }
 
 function ensureCursorSkills(targetRoot, dryRun, cursorReady) {
@@ -278,29 +321,13 @@ function ensureCursorSkills(targetRoot, dryRun, cursorReady) {
 
   const packageSkillsDir = path.join(packageRoot, "src", ".agents", "skills");
   if (!fs.existsSync(packageSkillsDir)) return { blocked: [] };
-
-  const skillNames = [];
-  try {
-    for (const name of fs.readdirSync(packageSkillsDir)) {
-      const skillPath = path.join(packageSkillsDir, name);
-      if (fs.statSync(skillPath).isDirectory() && fs.existsSync(path.join(skillPath, "SKILL.md"))) {
-        skillNames.push(name);
-      }
-    }
-  } catch (_) {
-    return;
-  }
-
   const skillsDir = path.join(cursorDir, "skills");
-  const type = process.platform === "win32" ? "dir" : "dir";
-
   if (dryRun) {
-    console.log("[dry-run] Would create .cursor/skills/<skill> symlinks for:", skillNames.join(", "));
+    console.log("[dry-run] Would sync .cursor/skills from package skills (Cursor)");
     return { blocked: [] };
   }
 
-  if (!fs.existsSync(skillsDir)) fs.mkdirSync(skillsDir, { recursive: true });
-  else {
+  if (fs.existsSync(skillsDir)) {
     const stat = fs.lstatSync(skillsDir);
     if (!stat.isDirectory()) {
       console.warn("Skipped .cursor/skills because it exists and is not a directory");
@@ -308,29 +335,10 @@ function ensureCursorSkills(targetRoot, dryRun, cursorReady) {
     }
   }
 
-  const blocked = [];
-  for (const name of skillNames) {
-    const linkPath = path.join(skillsDir, name);
-    const targetRel = path.join("..", "..", "node_modules", "compound-workflow", "src", ".agents", "skills", name);
-    const targetAbs = path.resolve(path.dirname(linkPath), targetRel);
-    let needCreate = true;
-    try {
-      const stat = fs.lstatSync(linkPath);
-      if (stat.isSymbolicLink() && symlinkPointsTo(linkPath, targetAbs)) needCreate = false;
-      else if (!stat.isSymbolicLink()) {
-        console.warn("Skipped", ".cursor/skills/" + name, "because it exists and is not a symlink");
-        blocked.push(linkPath);
-        continue;
-      }
-    } catch (_) {}
-
-    if (needCreate) {
-      removePathIfExists(linkPath);
-      fs.symlinkSync(targetRel, linkPath, type);
-      console.log("Created", ".cursor/skills/" + name, "-> package skill (Cursor)");
-    }
-  }
-  return { blocked };
+  fs.rmSync(skillsDir, { recursive: true, force: true });
+  copyDirContents(packageSkillsDir, skillsDir);
+  console.log("Synced .cursor/skills from package skills (Cursor)");
+  return { blocked: [] };
 }
 
 function verifyCursorIntegration(targetRoot) {
@@ -345,13 +353,12 @@ function verifyCursorIntegration(targetRoot) {
   const issues = [];
 
   for (const check of checks) {
-    const linkPath = path.join(cursorDir, check.rel);
-    const expectedAbs = path.join(targetRoot, "node_modules", "compound-workflow", "src", ".agents", check.rel);
-    if (!fs.existsSync(linkPath)) issues.push(`${check.name} is missing`);
+    const dirPath = path.join(cursorDir, check.rel);
+    if (!fs.existsSync(dirPath)) issues.push(`${check.name} is missing`);
     else {
-      const stat = fs.lstatSync(linkPath);
-      if (stat.isSymbolicLink() && !symlinkPointsTo(linkPath, expectedAbs)) {
-        issues.push(`${check.name} symlink points to unexpected target`);
+      const stat = fs.lstatSync(dirPath);
+      if (!stat.isDirectory()) {
+        issues.push(`${check.name} exists but is not a directory`);
       }
     }
   }
@@ -413,9 +420,9 @@ function ensureCursorIntegration(targetRoot, dryRun, forceCursor) {
 
   const skillReport = ensureCursorSkills(targetRoot, dryRun, cursorReady);
   const dirReports = [
-    ensureCursorDirSymlink(targetRoot, "agents", "agents", dryRun, "package agents", cursorReady),
-    ensureCursorDirSymlink(targetRoot, "commands", "commands", dryRun, "package commands", cursorReady),
-    ensureCursorDirSymlink(targetRoot, "references", "references", dryRun, "package references", cursorReady),
+    ensureCursorDirSync(targetRoot, "agents", "agents", dryRun, "package agents", cursorReady),
+    ensureCursorDirSync(targetRoot, "commands", "commands", dryRun, "package commands", cursorReady),
+    ensureCursorDirSync(targetRoot, "references", "references", dryRun, "package references", cursorReady),
   ];
 
   const issues = [];
@@ -423,8 +430,8 @@ function ensureCursorIntegration(targetRoot, dryRun, forceCursor) {
     for (const p of skillReport.blocked) issues.push(`${path.relative(targetRoot, p)} blocks symlink creation (not a symlink)`);
   }
   for (const report of dirReports) {
-    if (report?.status === "blocked-nonsymlink") {
-      issues.push(`${path.relative(targetRoot, report.path)} blocks symlink creation (not a symlink)`);
+    if (report?.status === "blocked-nondirectory") {
+      issues.push(`${path.relative(targetRoot, report.path)} blocks sync (not a directory)`);
     }
   }
 
@@ -579,12 +586,14 @@ function main() {
   console.log("Package root:", packageRoot);
   console.log("OpenCode CLI detected:", hasCommand("opencode") ? "yes" : "no");
 
+  syncRuntimeAssets(targetRoot, args.dryRun);
   writeOpenCodeJson(targetRoot, args.dryRun);
   ensureSkillsSymlink(targetRoot, args.dryRun);
   reportOpenCodeIntegration(targetRoot, args.dryRun);
-  const cursorReport = ensureCursorIntegration(targetRoot, args.dryRun, args.cursor);
+  const cursorExists = fs.existsSync(path.join(targetRoot, ".cursor"));
+  const cursorReport = ensureCursorIntegration(targetRoot, args.dryRun, cursorExists);
   if (cursorReport.status === "skipped-no-cursor") {
-    console.log("Cursor integration: skipped (.cursor missing). Run install with `all` or `--cursor` to create it.");
+    console.log("Cursor integration: skipped (.cursor not found).");
   } else {
     console.log("Cursor integration: verified skills, agents, commands, and references.");
   }

package/scripts/postinstall.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, "..");
+
+function realpathSafe(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+function isTruthy(v) {
+  const s = String(v || "").toLowerCase();
+  return s === "1" || s === "true" || s === "yes";
+}
+
+function hasFile(dir, name) {
+  try {
+    return fs.existsSync(path.join(dir, name));
+  } catch {
+    return false;
+  }
+}
+
+function shouldSkip(targetRoot) {
+  if (!targetRoot) return "INIT_CWD not set";
+  if (isTruthy(process.env.npm_config_global)) return "global install";
+  if (isTruthy(process.env.COMPOUND_WORKFLOW_SKIP_POSTINSTALL)) return "disabled by env";
+  if (!hasFile(targetRoot, "package.json")) return "no package.json in target root";
+  if (realpathSafe(targetRoot) === realpathSafe(packageRoot)) return "package development install";
+  return null;
+}
+
+function run() {
+  const targetRoot = process.env.INIT_CWD ? path.resolve(process.env.INIT_CWD) : "";
+  const skipReason = shouldSkip(targetRoot);
+  if (skipReason) {
+    console.log(`[compound-workflow] postinstall skipped (${skipReason})`);
+    return;
+  }
+
+  const cliPath = path.join(packageRoot, "scripts", "install-cli.mjs");
+  const result = spawnSync(
+    process.execPath,
+    [cliPath, "install", "--root", targetRoot, "--no-config"],
+    { stdio: "inherit", env: process.env }
+  );
+
+  if (result.status !== 0) {
+    console.warn(
+      "[compound-workflow] automatic setup failed; run `npx compound-workflow install` in your project."
+    );
+  }
+}
+
+run();

package/src/.agents/commands/workflow/plan.md

@@ -863,17 +863,16 @@ Examples:
 
 After writing the plan file, use **AskQuestion** to present these options:
 
-Do not route directly from plan generation to `/workflow:work`.
-
 **Question:** "Plan ready at `docs/plans/YYYY-MM-DD-<type>-<slug>-plan.md`. What would you like to do next?"
 
 **Options:**
 
 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:triage`** - Triage todos derived from this plan before execution
-4. **Create Issue** - Create issue in project tracker (GitHub/Linear)
-5. **Other** - Adjust the plan
+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 those workflows exist in this repo):
 
@@ -884,6 +883,7 @@ 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
@@ -891,7 +891,7 @@ Based on selection:
 
 **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.
 
-Loop back to options after changes until user selects `/workflow:triage` or ends the session.
+Loop back to options after changes until user selects `/workflow:work`, `/workflow:triage`, or ends the session.
 
 ## Issue Creation
 
@@ -933,6 +933,6 @@ When user selects "Create Issue", detect their project tracker from repo guidanc
 
 5. **After creation:**
    - Display the issue URL
-   - Ask if they want to proceed to `/workflow:triage`
+   - Ask if they want to proceed to `/workflow:work` (default path) or `/workflow:triage` (manual queue curation)
 
 NEVER CODE! Just research and write the plan.

package/src/.agents/commands/workflow/triage.md

@@ -1,7 +1,7 @@
 ---
 name: triage
 invocation: workflow:triage
-description: Triage and prioritize todo files into an executable ready queue (priority, dependencies, recommended action)
+description: Manual triage command to prioritize todo files into an executable ready queue (priority, dependencies, recommended action)
 argument-hint: "[optional: todo path, issue id, status filter ('pending'|'ready'|'active')]"
 ---
 
@@ -9,6 +9,8 @@ argument-hint: "[optional: todo path, issue id, status filter ('pending'|'ready'
 
 Turn todo items into a prioritized executable queue.
 
+This command is independently runnable. `/workflow:work` runs the same triage gate automatically before execution.
+Use `/workflow:triage` when you want explicit manual queue curation before or during execution.
 This command does not implement fixes. It approves and organizes work so `/workflow:work` can execute without ambiguity.
 Output of this command is the only executable queue for `/workflow:work`.
 

package/src/.agents/commands/workflow/work.md

@@ -100,7 +100,7 @@ The input must be a plan file path.
    - Continue only when provided commands run successfully.
    - If commands are not provided or fail, do not mark related todos complete.
 
-   Note: full execution preflight (triage + contract checks + isolation checks) runs after todo creation/triage in Step 3.5.
+   Note: full execution preflight (auto-triage + contract checks + isolation checks) runs after todo creation in Step 3.5.
 
 1.75. **Resolve Plan Scope Contract (REQUIRED)**
 
@@ -138,16 +138,23 @@ The input must be a plan file path.
    - If you are already on a branch that clearly matches this plan, continue.
    - Otherwise, continue anyway — the current active branch remains the reference/base for a new worktree unless the user explicitly requests a different base.
 
-   2) Ask the user (required decision prompt):
+   2) Resolve the user decision (required prompt/create gate):
 
-   - "Use a worktree for this work? (default: Yes; required unless you explicitly opt out)"
+   - If the user already gave an explicit instruction in this run:
+     - "create a worktree" / "yes use a worktree" => use worktree path
+     - "do not use a worktree" / "no worktree" => opt-out path
+   - Otherwise, you MUST ask this exact decision before proceeding:
+     - "Use a worktree for this work? (Yes/No; default recommendation: Yes)"
    - Options:
      - Yes (worktree)
      - No (stay in current checkout; create/switch to a feature branch)
 
-   If Yes: ask for the new branch name (e.g., `feat/<slug>`, `fix/<slug>`).
+   Mandatory behavior:
 
-   If the user does not explicitly choose "No", proceed with "Yes" by default.
+   - Do not infer or assume an answer when the user has not answered.
+   - Do not run `skill: git-worktree` until the user has answered Yes (or already explicitly requested worktree creation).
+   - If Yes: ask for the new branch name when missing (e.g., `feat/<slug>`, `fix/<slug>`), then continue.
+   - If No: require explicit opt-out confirmation, then continue with the non-worktree path.
 
    3) If worktree is chosen, run:
 
@@ -217,20 +224,21 @@ The input must be a plan file path.
    - Each todo MUST include a link back to the plan file in `Resources` and reference the specific section(s) it implements.
    - Default todo `status`:
      - `ready` when the plan is approved and confidence is not low
-     - `pending` when plan confidence is low or requires explicit triage
+     - `pending` when plan confidence is low or requires additional triage decisions
    - Default todo `priority`: `p2` unless the plan indicates urgency/risk.
 
-   After creating todos:
+   After creating todos, run an in-command triage pass (same readiness/dependency rules as `/workflow:triage`) before any implementation work:
 
-   - Run `/workflow:triage` before any implementation work to approve/prioritize the queue for this plan.
-   - Do not proceed to Phase 2 until triage completes and execution order is explicit.
-   - If triage leaves no unblocked `ready` todos, stop and report pending/deferred/blocked items.
+   - approve/prioritize queue items for this plan
+   - make execution order explicit
+   - if no unblocked `ready` todos remain, stop and report pending/deferred/blocked items
+   - use standalone `/workflow:triage` only when the user explicitly requests manual queue curation
 
 3.5. **Execution Preflight (HARD GATE before Phase 2)**
 
    Contract checksum (MUST all be true before implementation):
 
-   - triage completed for this plan
+   - auto-triage completed for this plan (or standalone `/workflow:triage` completed)
    - isolation gate recorded (`worktree_decision`, execution context, `gate_status: passed`)
    - blocking spikes execute before dependent build todos
 
@@ -241,7 +249,7 @@ The input must be a plan file path.
      - validation path is explicit (commands/routes/checks)
      - evidence expectations are explicit
      - quality gate commands are explicit or marked for ask-once fallback
-   - If a todo lacks this contract, move it to `pending` for triage before coding.
+   - If a todo lacks this contract, move it to `pending` and require triage resolution before coding.
 
 ### Phase 2: Execute
 
@@ -268,7 +276,7 @@ The input must be a plan file path.
 
    - If no unblocked `ready` todos remain:
      - summarize remaining `pending`, `deferred` (parked for reference), and blocked items
-     - require re-running `/workflow:triage` for pending/blocked prioritization
+     - require re-running triage (auto-triage within `/workflow:work` or standalone `/workflow:triage`) for pending/blocked prioritization
      - stop (do not invent work)
 
    For each task in priority order:
@@ -319,7 +327,7 @@ The input must be a plan file path.
     - If new, non-critical work is discovered, do NOT silently expand scope.
     - Ask the user to choose one:
       1) Do now (scope increase): only if small + tightly coupled
-      2) Create a triage item: create a new `pending` todo (default `p3` unless urgent) to be approved or deferred via `/workflow:triage`
+      2) Create a triage item: create a new `pending` todo (default `p3` unless urgent) to be approved or deferred via triage
       3) Park for reference: create a todo with Problem Statement + Findings + rationale, then mark it **deferred** (`*-deferred-*.md`, `status: deferred`) so it is kept for future reference but not in the executable queue
       4) Compound candidate only: capture as a `/workflow:compound` documentation candidate (no todo by default)
     - Always record the decision in the todo Work Log.
@@ -368,7 +376,7 @@ The input must be a plan file path.
    - Convert the decision into explicit todos (implementation/investigation/deferral).
    - If the chosen option is to run a timeboxed investigation or prototype, follow the **Spike Protocol** below.
    - Record the decision + rationale in the todo Work Log.
-   - Re-approve the todo through `/workflow:triage` before returning it to `ready`.
+   - Re-approve the todo through triage before returning it to `ready`.
 
    **Spike Protocol (allocate a spike)**
 
@@ -376,7 +384,7 @@ The input must be a plan file path.
 
    Steps:
 
-   1. **Spike todo:** Create a new `todos/*-pending-*.md` todo tagged `tags: [spike]` (or convert the current blocked todo to a spike todo). Fill Problem Statement, Proposed Solutions (options), and Acceptance Criteria (deliverable). Carry forward any plan metadata (initial priority, depends_on, unblocks, parallelizable). If triage has not been run, recommend `/workflow:triage` to approve the spike and set timebox + deliverable; then treat the spike as `ready` once approved.
+   1. **Spike todo:** Create a new `todos/*-pending-*.md` todo tagged `tags: [spike]` (or convert the current blocked todo to a spike todo). Fill Problem Statement, Proposed Solutions (options), and Acceptance Criteria (deliverable). Carry forward any plan metadata (initial priority, depends_on, unblocks, parallelizable). Ensure triage approves the spike and sets timebox + deliverable before treating it as `ready`.
    2. **Isolated execution:** Recommend a dedicated spike worktree. Use `skill: git-worktree` with branch name `spike/<todo_id>-<slug>` (e.g. `spike/003-auth-approach`). Run worktree bootstrap per the git-worktree skill. Execute the spike in that worktree so build work is not mixed with exploration.
    3. **Research subagents (per spike):** Run mandatory baseline research in parallel:
       - Always (when agents exist): Task repo-research-analyst(context), Task learnings-researcher(context)

package/src/AGENTS.md

@@ -26,10 +26,13 @@ This `.agents` workspace is portable and command-first.
 
 1. `/workflow:brainstorm` -> clarify what to build
 2. `/workflow:plan` -> define how to build it
-3. `/workflow:triage` -> approve and prioritize the todo queue before execution
-4. `/workflow:work` -> implement
-5. `/workflow:review` -> validate quality
-6. `/workflow:compound` -> capture durable learnings
+3. `/workflow:work` -> implement (includes triage gate for todo readiness/prioritization)
+4. `/workflow:review` -> validate quality
+5. `/workflow:compound` -> capture durable learnings
+
+Optional manual step:
+
+- `/workflow:triage` -> explicitly curate/prioritize backlog items before execution when needed
 
 Continuous improvement:
 
@@ -62,7 +65,7 @@ If workflow documents conflict, resolve them in this order:
 - **Solution scope contract is mandatory in every plan.** Plans must declare `solution_scope` (`partial_fix|full_remediation|migration`) plus explicit completion expectation and non-goals so `/workflow:work` can enforce intent.
 - **SpecFlow is a validation gate, not a rewrite engine.** High fidelity required; Medium recommended; Low optional. Output must translate into acceptance criteria/edge cases, not new scope.
 - **Isolation preflight is a hard gate.** `/workflow:work` must complete and record worktree/isolation preflight before any implementation commands. `/workflow:review` must do the same for non-current PR/branch targets before analysis.
-- **Triage before execution is mandatory.** `/workflow:work` must not execute todos until a `/workflow:triage` pass has prioritized the queue and validated dependencies/ready state for the current plan.
+- **Triage before execution is mandatory.** `/workflow:work` must run a triage pass before executing todos to prioritize the queue and validate dependencies/ready state for the current plan. `/workflow:triage` remains available as an explicit manual command.
 - **Spike governance is explicit and ordered.** Risky plans must evaluate spike need, spike candidates must declare initial priority/dependencies/unblocks/timebox/deliverable, triage confirms those assumptions, and `/workflow:work` executes blocking spikes before dependent build todos.
 - **Agentic access/testability is mandatory in planning.** Every plan must include an executable access + validation contract so work/review can run deterministically.
 - **Independent review is required for code/config changes.** `/workflow:review` must emit `review_independence_mode: independent|degraded`, plus independence evidence and skipped-pass disclosure.