compound-workflow 1.4.2 → 1.4.4

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.2",
+  "version": "1.4.4",
   "description": "Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.",
   "license": "MIT",
   "repository": {
@@ -18,6 +18,7 @@
     "skills"
   ],
   "scripts": {
+    "postinstall": "node scripts/postinstall.mjs",
     "check:pack-readme": "node scripts/check-pack-readme.mjs"
   },
   "engines": {

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,11 +67,21 @@ 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",
@@ -160,7 +186,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/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/agents/review/planning-technical-reviewer.md

@@ -75,6 +75,17 @@ You are an independent technical reviewer for plan documents. Your purpose is to
    - Impact
    - Suggested improvement
 
+### Findings Queue (for stepwise dialogue)
+1. [Finding title]
+   - Summary: [one-line]
+   - Intent: [why it matters]
+   - Options:
+     - A: [path]
+     - B: [path]
+     - C: [path, optional]
+   - Recommendation: [preferred option]
+   - Initial status: pending
+
 ### Direction Drift Check
 - In-scope: yes|no
 - Drift signals found: [none | list]
@@ -86,6 +97,8 @@ You are an independent technical reviewer for plan documents. Your purpose is to
 - Preferred option + why
 ```
 
+The `Findings Queue` is mandatory when at least one finding exists. It is consumed by `technical-review` for one-finding-at-a-time review (`next` progression).
+
 ## Guardrails
 
 - Do not edit the plan in this agent.

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)**
 
@@ -217,20 +217,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 +242,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 +269,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 +320,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 +369,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 +377,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/skills/technical-review/SKILL.md

@@ -5,7 +5,7 @@ description: Use when a feature approach or plan doc has passed document review
 
 # Technical Review
 
-Review a feature approach or plan document for technical alignment with architecture, code standards, and quality. Output risk level, three options with justifications, and a recommendation. Do not approve for build until the plan is updated via a second document review.
+Review a feature approach or plan document for technical alignment with architecture, code standards, and quality. Keep a running summary of findings, then review findings one at a time through user-driven dialogue (`next`). For each finding, output intent, options, and a recommendation. Do not approve for build until the plan is updated via a second document review.
 
 Primary execution model: run an independent planning-phase pass first using `planning-technical-reviewer` (when available), then synthesize final technical review verdict.
 
@@ -27,6 +27,15 @@ Primary execution model: run an independent planning-phase pass first using `pla
 - Treat its blocking findings as pre-build blockers.
 - If the agent is not available, explicitly state: "planning-technical-reviewer unavailable; running direct technical review (degraded bias resistance)".
 
+## Step 1.6: Build Findings Queue (Required)
+
+- Consolidate all blocking and non-blocking findings into an ordered queue.
+- Keep a persistent `Findings Summary` visible throughout the review with status per finding:
+  - `pending`
+  - `aligned`
+  - `deferred`
+- Do not process findings in bulk. Process one finding at a time.
+
 ## Step 2: Assess Against Technical Criteria
 
 Evaluate the plan against:
@@ -52,7 +61,29 @@ Assign one **overall** risk level for the plan:
 
 State the risk level and one-line rationale.
 
-## Step 4: Three Options with Justifications
+## Step 4: One-Finding Dialogue Loop (Required)
+
+For each queued finding, present:
+
+- `Finding:` concise summary
+- `Intent:` why this matters technically
+- `Options:` 2-3 viable paths with tradeoffs
+- `Recommendation:` preferred option with rationale
+- `Outcome:` leave as `pending` until user aligns
+
+After each finding, stop and prompt exactly:
+
+- `Say "next" to continue to the next finding.`
+
+Supported user controls in this loop:
+
+- `next` -> advance to the next pending finding
+- `accept` -> mark current finding as `aligned`, record chosen outcome
+- `revise: <note>` -> update current finding framing/options/recommendation before moving on
+
+Do not skip ahead automatically while findings remain pending.
+
+## Step 5: Three Options with Justifications (Overall Verdict)
 
 For each option, provide 2–3 sentences justification:
 
@@ -60,25 +91,27 @@ For each option, provide 2–3 sentences justification:
 - **Option B — Proceed with changes** — When risk is medium. List specific doc or code changes; justify why this is sufficient.
 - **Option C — Rework or spike** — When risk is high or uncertain. Say what to rework or spike; justify why build should wait.
 
-## Step 5: Recommendation
+## Step 6: Recommendation (Overall Verdict)
 
 State the **preferred option** and clear rationale (e.g. "Recommend Option B because …"). Tie to the risk level and findings.
 
-## Step 6: Output and Handoff
+## Step 7: Output and Handoff
 
-- **If pass (Option A or B with changes agreed):** Say "Approved for build" and optional notes. **Handoff:** Run **document review again** to update the plan with technical review findings (recommendation, agreed changes). Then build.
+- **If pass (Option A or B with changes agreed):** Say "Approved for build" and optional notes. **Handoff:** Run **document review again** to update the plan with all aligned technical review findings (recommendation, agreed changes, per-finding outcomes). Then build.
 - **If issues (Option C or B with open changes):** List issues to fix in the doc; do not approve for build until addressed. Handoff: update the plan (or re-run document review to incorporate fixes), then optionally re-run technical review.
 
 ## Required Output
 
 End every technical review with:
 
+- `Findings summary:` full list with status `pending|aligned|deferred`
+- `Per-finding outcomes:` one line each for every aligned finding
 - `Risk level:` low | medium | high (plus one-line rationale)
 - `Fresh-context pass:` ran | unavailable (degraded)
 - `Options A/B/C:` 2–3 sentences each
 - `Recommendation:` preferred option and rationale
 - `Approved for build:` yes | no
-- `Handoff:` re-run document review to update plan with findings before build (when approved), or list issues to fix (when not approved)
+- `Handoff:` re-run document review to update the plan with related findings and outcomes before build (when approved), or list issues to fix (when not approved)
 
 ## What NOT to Do
 
@@ -86,6 +119,7 @@ End every technical review with:
 - Do not add scope or new requirements.
 - Do not approve for build when risk is high and no rework is agreed.
 - Do not skip the second document review—the plan must be updated with technical review findings before build.
+- Do not collapse multiple findings into one response when interactive finding review is active.
 
 ## Integration
 

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.