compound-workflow 1.3.1 → 1.4.1

package/README.md

@@ -57,6 +57,10 @@ flowchart LR
 
 ---
 
+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 |
@@ -64,8 +68,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/` |
 | 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 |
+| 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 |
 
@@ -87,9 +91,11 @@ flowchart LR
 
 `/workflow:work` must not run until `/workflow:triage` has approved executable ready todos.
 
+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:** Evidence-based review + agentic validation coverage checks; no fixes by default. **Command:** `/workflow:review [PR|branch|current]`. **Output:** pass / pass-with-notes / fail.
+**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)
 
@@ -137,7 +143,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).
 
@@ -151,8 +157,12 @@ Full “when to use what” and reference standards: [src/AGENTS.md](src/AGENTS.
 
 - **Todo completion requires evidence:** acceptance/success criteria plus quality gates must be recorded before `complete`.
 
+- **Independent review policy:** code/config changes require `/workflow:review` before workflow completion; docs-only changes are exempt.
+
 - **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.
 
+- **Artifact policy:** do not create ad-hoc artifacts outside canonical outputs (`docs/plans`, `todos`, `docs/solutions`, `docs/metrics`) unless explicitly requested.
+
 - Add a separate shipping command if you want automated commit/PR and quality gates.
 
 ---
@@ -176,4 +186,5 @@ If your project does not already have `.cursor/`, run `npx compound-workflow ins
 **Source of truth**
 
 - 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)

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.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"}}

package/scripts/check-workflow-contracts.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const root = process.cwd();
+
+const requiredChecks = [
+  {
+    file: "docs/principles/workflow-baseline-principles.md",
+    pattern: "tie-breaker",
+    description: "baseline principles tie-breaker rule",
+  },
+  {
+    file: "src/AGENTS.md",
+    pattern: "## Contract Precedence",
+    description: "AGENTS contract precedence section",
+  },
+  {
+    file: "src/AGENTS.md",
+    pattern: "No ad-hoc artifacts outside canonical outputs",
+    description: "canonical artifact policy in AGENTS",
+  },
+  {
+    file: "README.md",
+    pattern: "If docs conflict:",
+    description: "README conflict resolution note",
+  },
+  {
+    file: "README.md",
+    pattern: "code/config changes require `/workflow:review`",
+    description: "README review gate policy",
+  },
+  {
+    file: "src/.agents/commands/workflow/plan.md",
+    pattern: "Contract precedence:",
+    description: "plan command precedence note",
+  },
+  {
+    file: "src/.agents/commands/workflow/triage.md",
+    pattern: "Contract precedence:",
+    description: "triage command precedence note",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "Contract precedence:",
+    description: "work command precedence note",
+  },
+  {
+    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:
+      "No file writes, implementation commands, test/lint/typecheck commands, or dependency-install commands may run before this gate passes.",
+    description: "pre-gate write/command prohibition in work command",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "workflow_complete: false (pending /workflow:review current)",
+    description: "implementation-complete pending-review status in work command",
+  },
+  {
+    file: "src/.agents/commands/workflow/review.md",
+    pattern: "Contract precedence:",
+    description: "review command precedence note",
+  },
+  {
+    file: "src/.agents/commands/workflow/review.md",
+    pattern: "Independent Reviewer Pass (REQUIRED)",
+    description: "required independent reviewer pass in review command",
+  },
+  {
+    file: "src/.agents/commands/workflow/review.md",
+    pattern: "review_independence_mode: independent|degraded",
+    description: "explicit review independence mode in review command",
+  },
+  {
+    file: "src/.agents/commands/workflow/review.md",
+    pattern: "what was skipped and why",
+    description: "review skipped-pass disclosure requirement",
+  },
+];
+
+const forbiddenChecks = [
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "## When to Use Reviewer Agents",
+    description: "legacy optional reviewer section in work command",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "**Don't use by default.**",
+    description: "legacy skip-by-default reviewer wording in work command",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "skip specialist reviewers by default",
+    description: "legacy skip-by-default specialist reviewer wording",
+  },
+];
+
+const failures = [];
+
+const readFile = (relativePath) => {
+  const absolutePath = path.join(root, relativePath);
+  if (!fs.existsSync(absolutePath)) {
+    failures.push(`Missing file: ${relativePath}`);
+    return "";
+  }
+  return fs.readFileSync(absolutePath, "utf8");
+};
+
+for (const check of requiredChecks) {
+  const contents = readFile(check.file);
+  if (!contents.includes(check.pattern)) {
+    failures.push(`Missing required contract text (${check.description}) in ${check.file}`);
+  }
+}
+
+for (const check of forbiddenChecks) {
+  const contents = readFile(check.file);
+  if (contents.includes(check.pattern)) {
+    failures.push(`Found forbidden contract text (${check.description}) in ${check.file}`);
+  }
+}
+
+if (failures.length > 0) {
+  console.error("Workflow contract drift check failed:");
+  for (const failure of failures) console.error(`- ${failure}`);
+  process.exit(1);
+}
+
+console.log("Workflow contract check passed.");

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

@@ -13,6 +13,8 @@ argument-hint: "[feature description, bug report, improvement idea, or brainstor
 
 Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown plan files that follow project conventions and best practices. This command provides flexible detail levels to match your needs.
 
+Contract precedence: if this command conflicts with other workflow docs, follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then this command.
+
 This workflow MUST choose a planning fidelity and confidence level before final plan construction:
 
 - Fidelity: `Low | Medium | High`

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

@@ -9,6 +9,8 @@ argument-hint: "[PR number, GitHub URL, branch name, or 'current']"
 
 Run a structured, evidence-based **code** review. This command produces findings and recommendations; it does not implement fixes by default.
 
+Contract precedence: if this command conflicts with other workflow docs, follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then this command.
+
 **If the user provides a document path** (e.g. a plan or spec): redirect to the `technical-review` skill for technical correctness (no edits), and/or the `document-review` skill to refine the document. This command does not review documents.
 
 Guardrails (unless explicitly requested):
@@ -115,6 +117,19 @@ Protected artifacts:
 - If changes touch existing behavior and risk is medium/high: `Task git-history-analyzer(<target context>)`
 - If changes depend on framework/library behavior and version constraints: `Task framework-docs-researcher(<topic>)`
 
+### Phase 3.5: Independent Reviewer Pass (REQUIRED)
+
+Before final verdict, run an explicit independent pass and record:
+
+- `review_independence_mode: independent|degraded`
+- `independence_evidence`: what independent pass ran
+- `skipped_passes`: what was skipped and why
+
+Mode rules:
+
+- `independent` (default): run a distinct fresh-context reviewer pass (separate reviewer/agent perspective from the main synthesis).
+- `degraded`: only when independent reviewer tooling/path is unavailable. Must include explicit disclosure that confidence is reduced and why fallback was used.
+
 Then perform the main review synthesis across:
 
 - change summary (surface area, high-risk files)
@@ -130,11 +145,16 @@ Then perform the main review synthesis across:
 Provide:
 
 - Review recommendation: `pass | pass-with-notes | fail`
+- `review_independence_mode: independent|degraded`
+- `verdict_confidence: normal|degraded` (use `degraded` only when `review_independence_mode=degraded`)
 - Top risks (1–5 bullets)
 - Findings list:
   - severity (`critical | high | medium | low`)
   - evidence (file references or commands/output)
   - recommended action (concise)
+- Independence evidence summary:
+  - what independent pass ran
+  - what was skipped and why
 - What ran vs skipped (selected agents/passes)
 - Validation coverage summary:
   - tests: pass|fail|not-run

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

@@ -12,6 +12,8 @@ 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`.
 
+Contract precedence: if this command conflicts with other workflow docs, follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then this command.
+
 ## Inputs
 
 - Default: triage all active todos under `todos/` (`pending` + `ready`)

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

@@ -13,6 +13,8 @@ Execute a work plan efficiently while maintaining quality and finishing features
 
 This command takes a plan file and executes it systematically. The focus is on completing the work while understanding requirements quickly, following existing patterns, and maintaining quality throughout.
 
+Contract precedence: if this command conflicts with other workflow docs, follow `docs/principles/workflow-baseline-principles.md`, then `src/AGENTS.md`, then this command.
+
 Non-goals (unless explicitly requested):
 
 - Creating commits
@@ -89,22 +91,7 @@ The input must be a plan file path.
    - Prefer `test_command` and optional `test_fast_command` from `AGENTS.md`.
    - If missing, ask once for the repo's test command and suggest adding it to `AGENTS.md`.
 
-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:
-     - access preconditions are explicit
-     - 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.
+1.6. **Run-Scoped Quality Gate Fallback Setup (PREP STEP)**
 
    Ask-once fallback policy for missing lint/typecheck config:
 
@@ -113,6 +100,8 @@ 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.
+
 1.75. **Resolve Plan Scope Contract (REQUIRED)**
 
    Before any environment setup or implementation, resolve the plan's scope contract:
@@ -132,11 +121,15 @@ The input must be a plan file path.
    - `migration`: identify migration verification + rollback checks before executing todos.
    - `full_remediation`: complete all known gaps in the scoped area before completion.
 
-2. **Setup Environment (HARD GATE)**
+2. **Setup Environment (HARD GATE - WORKTREE FIRST)**
 
    Determine how to isolate the work for this plan.
 
-   No implementation commands or code edits may run before this gate passes.
+   This gate MUST run immediately after Step 1.75.
+
+   No file writes, implementation commands, test/lint/typecheck commands, or dependency-install commands may run before this gate passes.
+
+   Allowed before gate: read-only inspection only (e.g., `ls`, `rg`, `cat`, `git status`, `git branch`).
 
    Default: use a worktree. Opt-out requires explicit user confirmation.
 
@@ -154,6 +147,8 @@ The input must be a plan file path.
 
    If Yes: ask for the new branch name (e.g., `feat/<slug>`, `fix/<slug>`).
 
+   If the user does not explicitly choose "No", proceed with "Yes" by default.
+
    3) If worktree is chosen, run:
 
    ```bash
@@ -231,6 +226,23 @@ The input must be a plan file path.
    - 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.
 
+3.5. **Execution Preflight (HARD GATE before Phase 2)**
+
+   Contract checksum (MUST all be true before implementation):
+
+   - triage completed for this plan
+   - isolation gate recorded (`worktree_decision`, execution 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:
+     - access preconditions are explicit
+     - 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.
+
 ### Phase 2: Execute
 
 1. **Task Execution Loop**
@@ -431,13 +443,15 @@ The input must be a plan file path.
    - If `test_command` is not configured, ask once for the project's test command and suggest adding it to `AGENTS.md`.
    - If `lint_command` or `typecheck_command` is not configured, ask once for run-provided commands and use them for this run.
 
-2. **Consider Reviewer Agents** (Optional)
+2. **Prepare Review Handoff (REQUIRED for code/config changes)**
 
-   Use for complex, risky, or large changes.
+   If this run changed code or configuration, prepare an explicit `/workflow:review current` handoff summary:
 
-   If this repo defines preferred review agents in `AGENTS.md`, follow that.
+   - files changed
+   - validations run and outcomes
+   - known risks or unresolved notes
 
-   If not configured, skip specialist reviewers by default.
+   Docs-only runs may skip this handoff using the docs-only review exemption.
 
 3. **Final Validation**
    - All todo files created for this plan are marked complete
@@ -463,9 +477,14 @@ The input must be a plan file path.
      - Note any follow-up work needed
      - Suggest next steps if applicable
 
-   Risk-based recommendation:
+   Completion policy:
 
-   - If the plan fidelity is `high` or confidence is `low`, recommend running `/workflow:review current` before considering the work complete.
+   - If this run changed code or configuration, report status as:
+     - `implementation_complete: true`
+     - `workflow_complete: false (pending /workflow:review current)`
+   - If this run is docs-only (no code/config changes), report status as:
+     - `implementation_complete: true`
+     - `workflow_complete: true (docs-only review exemption)`
 
 Stop here by default.
 
@@ -475,11 +494,11 @@ If the user wants to ship (commits/PR/screenshots), handle that as a separate ex
 
 ## Key Principles
 
-### Start Fast, Execute Faster
+### Execute with Deterministic Gates
 
-- Get clarification once at the start, then execute
-- Don't wait for perfect understanding - ask questions and move
-- The goal is to **finish the feature**, not create perfect process
+- Resolve unclear requirements early, then execute decisively
+- Keep hard gates explicit and non-skippable
+- Optimize for correct, verifiable completion
 
 ### The Plan is Your Guide
 
@@ -498,7 +517,7 @@ If the user wants to ship (commits/PR/screenshots), handle that as a separate ex
 - Follow existing patterns
 - Write tests for new code
 - Run linting/typechecking/formatting as configured in `AGENTS.md` (or run-provided via ask-once fallback)
-- Use reviewer agents for complex/risky changes only
+- For code/config changes, require `/workflow:review current` before declaring workflow completion
 
 ### Ship Complete Features
 
@@ -521,25 +540,23 @@ Before marking work complete, verify:
 - [ ] For `partial_fix`, unresolved work is captured as `pending/deferred` todos
 - [ ] If shipping is requested, capture any required artifacts (screenshots, release notes) per repo conventions
 
-## When to Use Reviewer Agents
+## Review Completion Gate
 
-**Don't use by default.** Use reviewer agents only when:
+For code/config changes, completion of `/workflow:work` is implementation-complete only. Workflow completion requires `/workflow:review current`.
 
-- Large refactor affecting many files (10+)
-- Security-sensitive changes (authentication, permissions, data access)
-- Performance-critical code paths
-- Complex algorithms or business logic
-- User explicitly requests thorough review
+Docs-only exception:
 
-For most features: tests + linting + following patterns is sufficient.
+- If no code/config files changed, `/workflow:work` may close as workflow-complete without `/workflow:review`.
+- When taking this exemption, explicitly state "docs-only review exemption" in the final summary.
 
 ## Common Pitfalls to Avoid
 
 - **Analysis paralysis** - Don't overthink, read the plan and execute
 - **Skipping clarifying questions** - Ask now, not after building wrong thing
 - **Skipping the worktree hard gate** - No implementation before Step 2 gate passes
+- **Starting writes before isolation gate** - no file writes or run commands before Step 2
 - **Ignoring plan references** - The plan has links for a reason
 - **Testing at the end** - Test continuously or suffer later
 - **Forgetting todo updates** - Update todo files and plan checkboxes or lose track of progress
 - **80% done syndrome** - Finish the feature, don't move on early
-- **Over-reviewing simple changes** - Save reviewer agents for complex work
+- **Skipping required review on code/config changes** - workflow completion requires `/workflow:review current`

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

@@ -44,6 +44,15 @@ This workspace currently implements `brainstorm`, `plan`, `triage`, `work`, `rev
 
 Use the canonical command names (`/workflow:plan`, `/workflow:work`, `/workflow:review`, etc.). This template does not ship aliases.
 
+## Contract Precedence
+
+If workflow documents conflict, resolve them in this order:
+
+1. `docs/principles/workflow-baseline-principles.md`
+2. This file (`src/AGENTS.md`) non-negotiables and repo config
+3. Workflow command specs (`src/.agents/commands/workflow/*.md`)
+4. Skill docs (`src/.agents/skills/*/SKILL.md`)
+
 ## Non-negotiables (Structure Integrity)
 
 - **Commands are the public API.** Keep `/workflow:*` command docs stable; add capability via skills/agents, not new command variants.
@@ -56,11 +65,12 @@ Use the canonical command names (`/workflow:plan`, `/workflow:work`, `/workflow:
 - **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.
 - **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.
 - **Todo completion requires evidence.** A todo may move to `complete` only after success criteria evidence and quality gate evidence are recorded in Work Log.
 - **Blockers change todo state immediately.** Blocked work must move from `ready` back to `pending` with `tags: [blocker]` and an options+recommendation decision record.
 - **Quality gates are enforced with ask-once fallback.** If `lint_command` or `typecheck_command` is missing, ask once per run and continue only when commands are provided and pass.
 - **Skills are invoked only by trigger.** `document-review` only when user selects "Review and refine" (or explicit request); guardrail skills (PII/financial/audit/data) only when the feature touches that domain.
-- **No new files/directories by default** beyond `docs/plans/...` for planning output.
+- **No ad-hoc artifacts outside canonical outputs** (`docs/plans`, `todos`, `docs/solutions`, `docs/metrics`) unless explicitly requested.
 - **Plan file is the artifact.** Post-generation options are actions on the artifact; they do not change the workflow shape.
 - **Tighten over expand.** Resolve ambiguity, standardize naming, enforce sections—avoid adding new process steps unless they reduce rework.
 
@@ -166,6 +176,7 @@ worktree_bootstrap_notes:
   - `lint`
   - `bug-reproduction-validator`
   - `agent-native-reviewer`
+  - `planning-technical-reviewer`
 
 ## Skill Index (When to Use What)