compound-workflow 1.3.1 → 1.4.0

package/README.md

@@ -137,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.1","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/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

@@ -166,6 +166,7 @@ worktree_bootstrap_notes:
   - `lint`
   - `bug-reproduction-validator`
   - `agent-native-reviewer`
+  - `planning-technical-reviewer`
 
 ## Skill Index (When to Use What)