compound-workflow 1.3.0 → 1.4.0

package/README.md

@@ -48,11 +48,11 @@ To update to a new release, see [Updating compound-workflow](#updating-compound-
 
 ## Workflow at a glance
 
-Clarify what to build → plan how (fidelity + confidence) → execute via todos → triage and review → capture learnings → log and assess.
+Clarify what to build -> plan how (fidelity + confidence) -> triage todos -> execute -> review -> capture learnings -> log and assess.
 
 ```mermaid
 flowchart LR
-  A["brainstorm"] --> B["plan"] --> C["work"] --> D["triage"] --> E["review"] --> F["capture"] --> G["metrics"]
+  A["brainstorm"] --> B["plan"] --> C["triage"] --> D["work"] --> E["review"] --> F["capture"] --> G["metrics"]
 ```
 
 ---
@@ -63,8 +63,8 @@ flowchart LR
 |------|--------|---------|---------------|
 | 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/` |
-| Execute | File-based todos; risk-tier testing; evidence-backed completion; no auto-ship | `/workflow:work <plan-path>` | `todos/` |
 | Ready the queue | Priority/dependencies + executable agentic contract checks for pending todos | `/workflow:triage` | — |
+| Execute | File-based todos; risk-tier testing; evidence-backed completion; no auto-ship | `/workflow:work <plan-path>` | `todos/` |
 | Validate quality | Evidence-based review + agentic executability checks; 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 |
@@ -77,13 +77,15 @@ flowchart LR
 
 **Intent:** Plan only; no code; fidelity + confidence; include an agentic access + validation contract. **Command:** `/workflow:plan [description or brainstorm path]`. **Output:** `docs/plans/`.
 
-#### 3. Execute (work)
+#### 3. Ready the queue (triage)
 
-**Intent:** File-based todos; risk-tier testing; success-criteria evidence + quality gates before completion; no auto-ship. **Command:** `/workflow:work <plan-path>`. **Output:** `todos/`.
+**Intent:** Priority/dependencies for pending todos and readiness checks for agentic executability. **Command:** `/workflow:triage`. **Output:** —.
 
-#### 4. Ready the queue (triage)
+#### 4. Execute (work)
 
-**Intent:** Priority/dependencies for pending todos and readiness checks for agentic executability. **Command:** `/workflow:triage`. **Output:** —.
+**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.
 
 #### 5. Validate quality (review)
 
@@ -135,7 +137,7 @@ Commands are the public API. Skills and agents are invoked by commands; you don
 - **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`).
+- **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).
 

package/package.json

@@ -1 +1 @@
-{"name":"compound-workflow","version":"1.3.0","description":"Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/cjerochim/compound-workflow.git"},"bin":{"compound-workflow":"scripts/install-cli.mjs"},"files":["src","scripts",".cursor-plugin",".claude-plugin","skills"],"scripts":{"check:pack-readme":"node scripts/check-pack-readme.mjs"},"engines":{"node":">=18"},"devDependencies":{"@semantic-release/git":"^10.0.1","@semantic-release/npm":"^13.1.4","semantic-release":"^25.0.3"}}
+{"name":"compound-workflow","version":"1.4.0","description":"Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/cjerochim/compound-workflow.git"},"bin":{"compound-workflow":"scripts/install-cli.mjs"},"files":["src","scripts",".cursor-plugin",".claude-plugin","skills"],"scripts":{"check:pack-readme":"node scripts/check-pack-readme.mjs"},"engines":{"node":">=18"},"devDependencies":{"@semantic-release/git":"^10.0.1","@semantic-release/npm":"^13.1.4","semantic-release":"^25.0.3"}}

package/src/.agents/agents/review/planning-technical-reviewer.md

@@ -0,0 +1,94 @@
+---
+name: planning-technical-reviewer
+description: "Independent technical reviewer for brainstorm/plan outputs before execution."
+model: inherit
+---
+
+<examples>
+<example>
+Context: A plan was written after a long brainstorm and needs an independent check.
+user: "Run technical review on this plan before we start work."
+assistant: "I'll use the planning-technical-reviewer to run an independent plan check first, then return a build approval verdict."
+<commentary>Use this reviewer when you need a second opinion not anchored to the original planning chain.</commentary>
+</example>
+<example>
+Context: Plan confidence is low and there are open spikes.
+user: "Can we trust this plan or does it need rework?"
+assistant: "I'll run planning-technical-reviewer to stress-test assumptions and identify blocking gaps."
+<commentary>The reviewer should prioritize disconfirming evidence and feasibility risks before build starts.</commentary>
+</example>
+</examples>
+
+# Planning Technical Reviewer
+
+You are an independent technical reviewer for plan documents. Your purpose is to reduce confirmation bias by evaluating plans as if they were authored by someone else.
+
+## Inputs
+
+- Plan document path (required)
+- Repo conventions from `AGENTS.md`
+- Relevant local references cited by the plan
+
+## Independence Rules
+
+1. Treat prior recommendations as untrusted until verified.
+2. Look for disconfirming evidence first, then supporting evidence.
+3. Do not preserve weak assumptions for momentum.
+4. If feasibility is unclear, do not approve for build.
+
+## What to Evaluate
+
+1. Direction integrity
+   - Does the plan stay inside the declared problem boundary?
+   - Are non-goals respected?
+   - Is scope expansion explicit and justified?
+2. Technical correctness
+   - Alignment with repository architecture and conventions
+   - Plausibility of implementation path and dependencies
+3. Validation realism
+   - Are acceptance criteria testable?
+   - Are validation and quality gate commands executable?
+   - Is evidence required for completion clear?
+4. Execution readiness
+   - Are blockers, discussion points, and spikes explicit where needed?
+   - Is ordering/dependency logic deterministic?
+5. Risk handling
+   - Are failure modes and rollback expectations appropriate for risk level?
+
+## Required Output
+
+```markdown
+## Fresh Context Plan Review
+
+- Risk level: low | medium | high
+- Build approval: yes | no
+- Confidence in verdict: high | medium | low
+
+### Blocking Findings
+1. [Issue]
+   - Why it blocks
+   - Where found (file:line)
+   - Required fix
+
+### Non-Blocking Findings
+1. [Issue]
+   - Impact
+   - Suggested improvement
+
+### Direction Drift Check
+- In-scope: yes|no
+- Drift signals found: [none | list]
+
+### Recommendation
+- Option A: proceed as-is
+- Option B: proceed with specific changes
+- Option C: rework or spike before build
+- Preferred option + why
+```
+
+## Guardrails
+
+- Do not edit the plan in this agent.
+- Do not add new product scope.
+- Do not approve when blocking findings exist.
+- When uncertain, choose non-approval and require clarification or spike.

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

@@ -861,13 +861,15 @@ 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:work`** - Begin implementing this plan locally
+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
 
@@ -880,13 +882,14 @@ 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: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
 - **Other** → Accept free text for rework or specific changes
 
 **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:work` or ends the session.
+Loop back to options after changes until user selects `/workflow:triage` or ends the session.
 
 ## Issue Creation
 
@@ -928,6 +931,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:work`
+   - Ask if they want to proceed to `/workflow:triage`
 
 NEVER CODE! Just research and write the plan.

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

@@ -10,6 +10,7 @@ argument-hint: "[optional: todo path, issue id, status filter ('pending'|'ready'
 Turn todo items into a prioritized executable queue.
 
 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`.
 
 ## Inputs
 

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

@@ -91,6 +91,12 @@ The input must be a plan file path.
 
 1.6. **Agentic Access + Validation Preflight (HARD GATE)**
 
+   Contract checksum (MUST all be true before implementation):
+
+   - triage completed for this plan
+   - isolation gate recorded (`worktree_decision`, context, `gate_status: passed`)
+   - blocking spikes execute before dependent build todos
+
    Before any implementation commands:
 
    - Verify each `ready` todo has an executable Agentic Execution Contract:

package/src/.agents/skills/technical-review/SKILL.md

@@ -7,6 +7,8 @@ description: Use when a feature approach or plan doc has passed document 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.
 
+Primary execution model: run an independent planning-phase pass first using `planning-technical-reviewer` (when available), then synthesize final technical review verdict.
+
 ## When to Use
 
 - After **document review** on a feature approach doc (pre-build gate flow).
@@ -19,6 +21,12 @@ Review a feature approach or plan document for technical alignment with architec
 
 **If no document is specified:** Use the doc just reviewed in document review, or look for the most recent feature approach/plan in `docs/brainstorms/` or `docs/plans/` (e.g. by date prefix).
 
+## Step 1.5: Independent Fresh-Context Pass (Required)
+
+- If `planning-technical-reviewer` exists under `.agents/agents/review/`, run it on the plan first.
+- 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 2: Assess Against Technical Criteria
 
 Evaluate the plan against:
@@ -66,6 +74,7 @@ State the **preferred option** and clear rationale (e.g. "Recommend Option B bec
 End every technical review with:
 
 - `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

package/src/AGENTS.md

@@ -40,7 +40,7 @@ Onboarding:
 
 - `/install` -> one action: writes opencode.json, merges AGENTS.md, creates dirs, preserves Repo Config Block (run `npx compound-workflow install` in the project)
 
-This workspace currently implements `brainstorm`, `plan`, `work`, `review`, `compound`, and optional QA utilities.
+This workspace currently implements `brainstorm`, `plan`, `triage`, `work`, `review`, `compound`, and optional QA utilities.
 
 Use the canonical command names (`/workflow:plan`, `/workflow:work`, `/workflow:review`, etc.). This template does not ship aliases.
 
@@ -154,7 +154,7 @@ worktree_bootstrap_notes:
 
 ## Implemented Components (Current Scope)
 
-- Commands: `workflow:brainstorm`, `workflow:plan`, `workflow:work`, `workflow:triage`, `workflow:review`, `workflow:compound` (under `.agents/commands/workflow/`), plus `test-browser`, `metrics`, `assess`, `setup`, `sync` (root commands)
+- Commands: `workflow:brainstorm`, `workflow:plan`, `workflow:triage`, `workflow:work`, `workflow:review`, `workflow:compound` (under `.agents/commands/workflow/`), plus `test-browser`, `metrics`, `assess`, `setup`, `sync` (root commands)
 - Skills: `brainstorming`, `document-review`, `technical-review`, `compound-docs` (alias: `compound_doc`), `capture-skill`, `file-todos`, `agent-browser`, `git-worktree`, `process-metrics`, `react-ddd-mvc-frontend`, `xstate-actor-orchestration`, `standards`, `pii-protection-prisma`, `financial-workflow-integrity`, `audit-traceability`, `data-foundations`
 - Agents:
   - `repo-research-analyst`
@@ -166,6 +166,7 @@ worktree_bootstrap_notes:
   - `lint`
   - `bug-reproduction-validator`
   - `agent-native-reviewer`
+  - `planning-technical-reviewer`
 
 ## Skill Index (When to Use What)