@josstei/maestro 1.6.4-rc.1

package/plugins/maestro/src/references/architecture.md

@@ -0,0 +1,139 @@
+# Maestro Architecture Reference
+
+## Orchestration Model
+
+Maestro is a multi-agent orchestration system that coordinates 39 specialized agents through a structured 4-phase workflow:
+
+1. **Design** — Structured requirements discovery, tradeoff-backed design questions, and design approval
+2. **Plan** — Phase-based implementation planning with dependencies, file ownership, and validation gates
+3. **Execute** — Delegated execution through child agents in parallel or sequential mode
+4. **Complete** — Deliverable verification, code review gate, archival, and summary
+
+The TechLead orchestrator does not implement code directly. It designs, plans, delegates to specialized agents, validates results, and reports outcomes.
+
+## Agent Roster
+
+| Agent | Focus |
+| --- | --- |
+| `accessibility-specialist` | WCAG compliance auditing, ARIA review |
+| `analytics-engineer` | Event tracking, conversion funnels |
+| `api-designer` | API contracts and endpoint design |
+| `architect` | System design and architecture decisions |
+| `cloud-architect` | AWS/GCP/Azure topology, IaC, multi-region design |
+| `cobol-engineer` | Mainframe COBOL, JCL, CICS/IMS on z/OS |
+| `code-reviewer` | Code quality review and bug identification |
+| `coder` | Feature implementation |
+| `compliance-reviewer` | Legal and regulatory compliance (GDPR, CCPA, licensing) |
+| `content-strategist` | Content planning and strategy |
+| `copywriter` | Marketing copy and landing-page content |
+| `data-engineer` | Schema design, queries, and data pipelines |
+| `database-administrator` | RDBMS tuning, indexes, migration safety (Postgres, MySQL, Oracle, SQL Server) |
+| `db2-dba` | DB2 for z/OS and LUW, REORG, RUNSTATS, bind/rebind |
+| `debugger` | Root cause analysis and defect investigation |
+| `design-system-engineer` | Design tokens and theming |
+| `devops-engineer` | CI/CD, containerization, and deployment |
+| `hlasm-assembler-specialist` | IBM HLASM for z/OS, macros, SVCs |
+| `i18n-specialist` | Internationalization and locale management |
+| `ibm-i-specialist` | IBM i RPG/CL, DB2 for i, OS/400 |
+| `integration-engineer` | B2B APIs, ETL, message brokers (Kafka, MQ) |
+| `ml-engineer` | Model training, feature pipelines, evaluation |
+| `mlops-engineer` | Model registry, CI/CD for models, drift detection |
+| `mobile-engineer` | iOS/Android/React Native/Flutter platform work |
+| `observability-engineer` | Metrics, logs, traces, OpenTelemetry, dashboards |
+| `performance-engineer` | Performance profiling and optimization |
+| `platform-engineer` | Internal developer platforms, paved paths |
+| `product-manager` | Requirements and product strategy |
+| `prompt-engineer` | LLM prompt design, few-shot, RAG tuning |
+| `refactor` | Structural refactoring and technical debt |
+| `release-manager` | Release notes, changelogs, rollout planning |
+| `security-engineer` | Security assessment and vulnerability analysis |
+| `seo-specialist` | Technical SEO auditing and structured data |
+| `site-reliability-engineer` | SLOs, error budgets, runbooks, postmortems |
+| `solutions-architect` | Enterprise integration, cross-team architecture |
+| `technical-writer` | Documentation and technical writing |
+| `tester` | Test implementation and coverage analysis |
+| `ux-designer` | User experience design |
+| `zos-sysprog` | z/OS systems programming, JCL, USS, RACF |
+
+Agent names use the format specified by the runtime's Agent Naming Convention section. When delegating, use the exact name from the roster.
+
+## State Contract
+
+<!-- @feature scriptBasedStateContract -->
+Maestro maintains session state under `<state_dir>` (resolved from `MAESTRO_STATE_DIR`):
+
+- **Active session**: `<state_dir>/state/active-session.md`
+- **Plans**: `<state_dir>/plans/`
+- **Archives**: `<state_dir>/state/archive/`, `<state_dir>/plans/archive/`
+
+State scripts:
+
+- `node ${extensionPath}/src/scripts/ensure-workspace.js <state_dir>` — initialize workspace directories
+- `node ${extensionPath}/src/scripts/read-active-session.js` — read current session state
+- `node ${extensionPath}/src/scripts/read-state.js <relative-path>` — read arbitrary state file
+- `node ${extensionPath}/src/scripts/write-state.js <relative-path>` — write state from stdin
+- `node ${extensionPath}/src/scripts/read-setting.js <SETTING_NAME>` — resolve a Maestro setting
+<!-- @end-feature -->
+<!-- @feature claudeStateContract -->
+Maestro maintains session state under `docs/maestro` (resolved from `MAESTRO_STATE_DIR`):
+
+- **Active session**: `docs/maestro/state/active-session.md`
+- **Plans**: `docs/maestro/plans/`
+- **Archives**: `docs/maestro/state/archive/`, `docs/maestro/plans/archive/`
+
+State scripts:
+
+- `node ${CLAUDE_PLUGIN_ROOT}/../src/scripts/ensure-workspace.js docs/maestro` — initialize workspace directories
+- `node ${CLAUDE_PLUGIN_ROOT}/../src/scripts/read-active-session.js` — read current session state
+- `node ${CLAUDE_PLUGIN_ROOT}/../src/scripts/read-state.js <relative-path>` — read arbitrary state file
+- `node ${CLAUDE_PLUGIN_ROOT}/../src/scripts/write-state.js <relative-path>` — write state from stdin
+- `node ${CLAUDE_PLUGIN_ROOT}/../src/scripts/read-setting.js <SETTING_NAME>` — resolve a Maestro setting
+<!-- @end-feature -->
+<!-- @feature codexStateContract -->
+Maestro maintains session state under `docs/maestro` in the workspace root:
+
+- **Active session**: `docs/maestro/state/active-session.md`
+- **Plans**: `docs/maestro/plans/`
+- **Archives**: `docs/maestro/state/archive/`, `docs/maestro/plans/archive/`
+
+State scripts:
+
+- `node ./src/scripts/ensure-workspace.js docs/maestro` — initialize workspace directories
+- `node ./src/scripts/read-active-session.js` — read current session state
+- `node ./src/scripts/read-state.js <relative-path>` — read arbitrary state file
+- `node ./src/scripts/write-state.js <relative-path>` — write state from stdin
+- `node ./src/scripts/read-setting.js <SETTING_NAME>` — resolve a Maestro setting
+<!-- @end-feature -->
+
+## Session Management
+
+Sessions track:
+
+- Session ID and creation timestamp
+- Current phase and overall status
+- Phase-by-phase progress with assigned agents, file manifests, and validation results
+- Execution mode (`parallel` or `sequential`)
+- Downstream context for inter-phase dependencies
+- Error history and retry counts
+
+Session lifecycle: create -> active -> (resume if interrupted) -> archive on completion.
+
+## Execution Modes
+
+- **parallel**: Dispatch multiple child agents for phases at the same dependency depth with non-overlapping file ownership
+- **sequential**: Dispatch one child agent at a time in dependency order
+- **ask**: Prompt the user for mode selection after plan approval (default)
+
+The execution mode gate must resolve before any implementation delegation begins.
+
+## Delegation Contract
+
+Every delegated agent query must include the header:
+- `Agent: <agent_name>`
+- `Phase: <id>/<total>`
+- `Batch: <batch_id|single>`
+- `Session: <session_id>`
+
+Every agent must conclude with:
+- `## Task Report` — what was done, files changed, tests run
+- `## Downstream Context` — information needed by subsequent phases

package/plugins/maestro/src/references/orchestration-steps.md

@@ -0,0 +1,193 @@
+STARTUP (Turn 1 — tool calls only, no text output)
+ 0. If get_runtime_context appears in your available tools, call it. Carry the returned mappings (tool names, agent dispatch syntax, MCP prefix, paths) through the entire session. If unavailable, use the fallback mappings in the entry-point skill preamble.
+ 1. Call resolve_settings.
+ 2. Read `workspace_suggestion` from the `get_runtime_context` response (populated from MCP roots and/or runtime env var). Call `initialize_workspace(workspace_path=<workspace_suggestion or explicit user workspace>, state_dir=<resolved>)`. If no suggestion is available, ask the user via the runtime's user-prompt tool. `initialize_workspace` rejects paths inside extension caches.
+ 3. Call get_session_status — if active, present status and offer resume/archive.
+ 4. Call assess_task_complexity.
+ 5. Parse MAESTRO_DISABLED_AGENTS from resolved settings. Exclude listed agents from all planning.
+ 6. STOP. Turn 1 is ONLY steps 1-5. No text, no design questions, no file reads.
+
+CLASSIFICATION (Turn 2)
+ 7. Pre-load architecture plus every skill used before Phase 3 in a single batch:
+    `get_skill_content(["architecture", "design-dialogue", "design-document", "implementation-planning", "implementation-plan"])`.
+    <HARD-GATE>
+    This batch MUST complete before any `enter_plan_mode` call. Some runtimes
+    (notably Gemini CLI) deregister MCP tools once Plan Mode is active —
+    attempting to fetch these skills from inside Plan Mode will fail with
+    "tool not found" and strand the orchestrator. Execution-phase templates
+    (session-management, session-state, execution, delegation, validation,
+    agent-base-protocol, filesystem-safety-protocol, code-review) still load
+    lazily at their consumption points because Phase 3 never enters Plan Mode.
+    </HARD-GATE>
+ 8. Classify task as simple/medium/complex. Present classification with rationale.
+ 9. Route: simple → Express (step 31). Medium/complex → continue to step 10.
+
+DESIGN GATE (Phase 1 pre-entry)
+ 9a. Finalize the session_id now and use it verbatim for every subsequent MCP call. Format: `YYYY-MM-DD-<kebab-task-slug>`. Then call `enter_design_gate(session_id)`. This blocks `create_session` until `record_design_approval` is called. Idempotent; safe to call on resume.
+    <HARD-GATE>
+    Session ID Invariance — the session_id chosen here MUST be passed unchanged
+    to every MCP call that accepts a session_id parameter for the remainder of
+    this workflow: `record_design_approval`, `get_design_gate_status`,
+    `create_session`, `update_session`, `get_session_status`, `transition_phase`,
+    `scan_phase_changes`, `reconcile_phase`, and `archive_session`. Do NOT
+    substitute a placeholder id for initial calls and a final id later — the
+    design gate is keyed by session_id, so a drift orphans the approved gate
+    and strands the design document. `create_session` rejects with
+    `DESIGN_GATE_SESSION_MISMATCH` when it detects an approved gate for a
+    different session_id than the one passed in.
+    </HARD-GATE>
+
+DESIGN (Phase 1)
+10. Enter Plan Mode. If `plan_mode_native` from `get_runtime_context` is false (Codex), the server-side Design Gate (9a + step 13) is the authoritative contract; runtime-native plan mode is a UI affordance only.
+11. Using the `design-dialogue` protocol already loaded in step 7, run the design conversation:
+    - Design depth selector (first design question)
+    - Repository grounding (for existing codebases, skip for greenfield)
+    - One question at a time via user prompt
+    - Enrichment per chosen depth (Quick/Standard/Deep)
+    <HARD-GATE>
+    Technology Recommendation Gate: Before presenting technology options, re-read
+    the <user-request>. If the request implies static delivery (fan site, portfolio,
+    landing page, profile page) or specifies vanilla/static/no-frameworks, the
+    recommended option MUST be vanilla HTML/CSS/JS. Do NOT recommend frameworks
+    (Next.js, React, Vue, Svelte, Astro) unless the request explicitly requires
+    server-side rendering, authentication, database queries, or real-time updates.
+    </HARD-GATE>
+    <ANTI-PATTERN>
+    WRONG: user requests "fan site" → options include React, Next.js, Astro
+    CORRECT: user requests "fan site" → recommended option is vanilla HTML/CSS/JS
+    </ANTI-PATTERN>
+12. Present design sections one at a time, per the design-dialogue skill's convergence protocol.
+    <HARD-GATE>
+    Each section must be presented individually and approved via user prompt before
+    proceeding to the next. Do NOT present the full design as a single block.
+    Quick depth may combine sections. Standard/Deep MUST validate individually.
+    </HARD-GATE>
+13. Using the `design-document` template already loaded in step 7, write the approved design document to the runtime's write surface (Plan Mode tmp for Gemini, `<state_dir>/plans/` when Plan Mode is unavailable). Do NOT call `record_design_approval` while still inside Plan Mode — Gemini deregisters MCP tools during Plan Mode and the call will fail.
+14. If Plan Mode is active, exit Plan Mode with the plan path. MCP tools become available again at this point.
+14a. Call `record_design_approval` to clear the design gate. Choose the variant by runtime:
+     - **Content variant (required for Gemini)**: pass `design_document_content` + `design_document_filename`. The MCP server materializes the canonical copy inside `<state_dir>/plans/` atomically. Required whenever the runtime's write surface resolves relative paths against a root the MCP server cannot reach — Gemini Plan Mode writes to `~/.gemini/tmp/<uuid>/...`, so a path handed back to the server never resolves to the same file.
+     - **Path variant (Codex, Claude direct writes)**: pass `design_document_path` (absolute or workspace-relative). The approval handler records the path without requiring the file to already be on disk; `create_session` in step 21 materializes the file into `<state_dir>/plans/` and will reject if the file is still missing at that point.
+     <HARD-GATE>
+     The two variants are mutually exclusive. Supplying both, or neither, fails with VALIDATION_ERROR.
+     </HARD-GATE>
+
+PLANNING (Phase 2)
+15. Using the `implementation-planning` and `implementation-plan` resources already loaded in step 7, follow the planning protocol to draft the implementation plan. If the planning skill instructs you to re-enter Plan Mode for the plan-approval UI, write the plan document first; all subsequent MCP calls (including `validate_plan`) must happen after the next `exit_plan_mode`, not inside Plan Mode.
+16. Call validate_plan with the generated plan and task_complexity.
+    <HARD-GATE>
+    You MUST call validate_plan BEFORE presenting the plan for approval. Do NOT
+    present the plan, write it to state_dir, or proceed to step 17 without first
+    calling validate_plan and resolving any error-severity violations.
+    validate_plan enforces server-side: phase count limits, dependency cycles,
+    unknown agents, file ownership conflicts, and agent-deliverable compatibility
+    (read-only agents cannot be assigned to file-creating phases). If it returns
+    violations with severity "error", fix them in the plan and re-validate.
+    </HARD-GATE>
+17. Present plan for user approval (Approve / Revise / Abort via user prompt).
+18. Write approved implementation plan to <state_dir>/plans/.
+
+EXECUTION SETUP (Phase 3 — pre-delegation)
+19. Call `get_skill_content` with resources: ["execution"]. Follow its Execution Mode Gate.
+    <HARD-GATE>
+    Present ONLY "Parallel" and "Sequential" as execution mode options.
+    Do NOT present "Ask" as a user-facing choice — "ask" is a setting value
+    that means "prompt the user", not an execution mode the user selects.
+    </HARD-GATE>
+20. Call `get_skill_content` with resources: ["session-management", "session-state"].
+21. Pass the exact plan object returned by `validate_plan` to `create_session`. Do not reshape phases — `create_session` rejects plans whose phases are missing required fields ({id, name, agent, parallel, blocked_by}). Set `execution_mode` to the value resolved in step 19. Attach the implementation plan document by runtime:
+    - **Content variant (required for Gemini)**: pass `implementation_plan_content` + `implementation_plan_filename`. Mirrors the design-document content path in step 14a and closes the same runtime-tmp resolution gap when Plan Mode is used for plan approval.
+    - **Path variant (Codex, Claude direct writes)**: pass `implementation_plan` as an absolute or workspace-relative path. Requires the file to exist on disk at the workspace-resolved path when `create_session` runs.
+    <HARD-GATE>
+    The two variants are mutually exclusive. Supplying both fails with VALIDATION_ERROR. Supplying neither is valid — the session records no implementation plan.
+    </HARD-GATE>
+22. Call `get_skill_content` with resources: ["delegation", "validation", "agent-base-protocol", "filesystem-safety-protocol"].
+
+EXECUTION (Phase 3 — delegation loop)
+23. For each phase (or parallel batch): call `get_agent` for the assigned agent, then delegate using the returned methodology and tool restrictions. Before constructing the dispatch, read `delegation.constraints` from the cached `get_runtime_context` and shape the call accordingly — omit `agent_type`/`model`/`reasoning_effort` when `fork_full_context_incompatible_with` includes them and you are spawning with full-history fork.
+    <HARD-GATE>
+    Dispatch by calling the agent's registered tool directly.
+    Do NOT use the built-in generalist tool or invoke agents by bare name.
+    Each Maestro agent carries specialized methodology, tool restrictions, temperature,
+    and turn limits from its frontmatter that the generalist ignores.
+    </HARD-GATE>
+24. After each agent returns, parse the response. If a `## Blockers` section is present and non-empty, do NOT call `transition_phase`: aggregate blockers across the batch, ask the user via the user-prompt tool, and re-delegate the phase with the answer in the context block. Only when blockers are empty, parse Task Report + Downstream Context.
+25. Call transition_phase to persist results. `transition_phase` rejects with `HANDOFF_INCOMPLETE` if the phase produced files but downstream_context is empty — re-request the handoff. It sets `requires_reconciliation: true` when all manifests AND downstream_context are empty — in that case, invoke the Recovery Protocol in the execution skill (`scan_phase_changes` → user confirmation → `reconcile_phase`).
+    <HARD-GATE>
+    For parallel batches: call transition_phase INDIVIDUALLY for EVERY completed
+    phase in the batch. The MCP tool writes files_created, files_modified,
+    files_deleted, and downstream_context to the SPECIFIC phase identified by
+    completed_phase_id. Extract each agent's Task Report separately and pass
+    that agent's files and context to the corresponding phase's call. Do NOT
+    merge all agents' files into one call — the archive attributes files per
+    phase, so empty payloads mean lost traceability.
+    </HARD-GATE>
+26. Repeat steps 23-25 until all phases complete.
+
+COMPLETION (Phase 4)
+27. Call `get_skill_content` with resources: ["code-review"].
+28. If execution changed non-documentation files, delegate to the code reviewer agent. Block on Critical/Major findings.
+    <HARD-GATE>
+    If Critical/Major findings: re-delegate to the implementing agent to fix.
+    The orchestrator MUST NOT write code directly.
+    </HARD-GATE>
+29. If MAESTRO_AUTO_ARCHIVE is true (or unset), call archive_session. If false, inform user session is complete but not archived.
+30. Present final summary with files changed, phase outcomes, and next steps.
+
+RECOVERY (referenced from any step on user request)
+If the user says the flow moved too fast: return to the most recent unanswered approval gate.
+If the user asks for implementation before approval: remind them Maestro requires approval first.
+If the user asks to skip execution-mode: remind them parallel/sequential is required unless MAESTRO_EXECUTION_MODE pins it.
+If an answer invalidates a prior choice: restate the updated assumption and re-run the relevant gate.
+If delegation collapses to parent session without fallback approval: return to step 19 or re-scope the child-agent work packages.
+
+EXPRESS WORKFLOW (simple tasks only — jumped to from step 9)
+
+EXPRESS MODE GATE BYPASS: Express bypasses the execution-mode gate entirely. Express always dispatches sequentially. Do NOT prompt for parallel/sequential.
+
+EXPRESS MCP FALLBACK: If MCP state tools (create_session, transition_phase, archive_session) are unavailable, fall back to direct file writes on <state_dir>/state/active-session.md.
+
+31. Verify classification is simple. If task requires multiple phases or agents, override to medium → step 10.
+    <HARD-GATE>
+    Express sessions MUST have exactly one implementation phase with exactly one agent.
+    </HARD-GATE>
+32. Ask 1-2 clarifying questions from Area 1 only.
+    <HARD-GATE>
+    Each question MUST use the user prompt tool (not plain text). Use the choose
+    variant with 2-4 options where possible. Do NOT ask questions as plain text
+    in the model response — the user prompt tool is the only input mechanism.
+    </HARD-GATE>
+33. Present structured Express brief as plain text, then ask for approval.
+    <HARD-GATE>
+    The brief MUST be plain text output in the model response.
+    The approval MUST be a SEPARATE user prompt tool call — not embedded in the
+    brief text. The prompt contains only: "Approve this Express brief to proceed?"
+    These are two distinct actions: first emit the brief as text, then call the
+    user prompt tool for approval. Do NOT combine them into one text block.
+    </HARD-GATE>
+34. On approval, create session with workflow_mode: "express", exactly 1 phase.
+    On rejection, revise. On second rejection, escalate to Standard → step 10.
+35. Call `get_skill_content` with resources: ["agent-base-protocol", "filesystem-safety-protocol"] and prepend them to the delegation prompt.
+36. Delegate to the assigned agent.
+    <HARD-GATE>
+    Same dispatch rule as step 23: call agent by registered tool name, not generalist.
+    </HARD-GATE>
+37. Parse Task Report from the agent's response. Call transition_phase to persist results.
+    <HARD-GATE>
+    You MUST call transition_phase after the implementing agent returns. Extract
+    files_created, files_modified, files_deleted, and downstream_context from the
+    Task Report and pass them to transition_phase. Without this call, the session
+    state has no record of what was delivered. Do NOT skip to code review or archive
+    without calling transition_phase first.
+    </HARD-GATE>
+38. Delegate to the code reviewer agent.
+    <HARD-GATE>
+    If Critical/Major findings: re-delegate to implementing agent (1 retry).
+    Orchestrator MUST NOT write code directly. If retry fails, escalate to user.
+    </HARD-GATE>
+39. Call archive_session.
+40. Present summary.
+
+EXPRESS RESUME (when resuming an Express session from get_session_status)
+If phase is pending: re-generate and present brief (step 33). On approval, proceed to delegation (step 36).
+If phase is in_progress: re-delegate with same scope (step 36).
+If phase is completed but session is in_progress: run code review (step 38), then archive (step 39).

package/plugins/maestro/src/skills/shared/code-review/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: code-review
+description: Standalone code review methodology for structured, severity-classified code assessment
+---
+
+# Code Review Skill
+
+Activate this skill when performing standalone code reviews via the runtime-specific Maestro review entrypoint or during orchestration quality gates (post-phase checks and final completion gate). This skill provides the methodology for scoping, executing, and reporting code reviews.
+
+## Scope Detection Protocol
+
+Determine review scope using the following priority order:
+
+1. **User-specified paths**: If the user provides file paths or glob patterns, expand glob patterns using the `glob` tool to resolve them to concrete file paths before delegating to the `code-reviewer` agent
+2. **Staged changes**: If `git diff --staged` produces output, review staged changes
+3. **Last commit diff**: If no staged changes exist, review the last commit via `git diff HEAD~1`
+4. **Fallback**: If none of the above yield content, ask the user to specify scope
+
+Always confirm the detected scope with the user before proceeding.
+
+If scope is provided as file paths and a git diff is empty for some paths (for example, new unstaged files), include those files' current contents directly in review context so they are still reviewed.
+
+## Review Orchestration
+
+### Delegation Flow
+
+1. Detect review scope using the protocol above
+2. Gather the full diff content for the detected scope, and include current file contents when diff content is unavailable for scoped files
+3. Delegate to the `code-reviewer` agent with:
+   - The full diff content
+   - File paths involved
+   - Any user-provided focus areas or concerns
+4. Process the agent's Task Report
+5. Present findings to the user in the structured output format below
+
+### Context Enrichment
+
+When delegating to the `code-reviewer` agent, include:
+- The diff content (not just file names)
+- Surrounding context for modified sections (10 lines before/after when available)
+- Project language and framework information (detected from package.json, Cargo.toml, go.mod, etc.)
+
+## Severity Classification
+
+### Critical
+Issues that could cause security vulnerabilities, data loss, or system crashes:
+- SQL/NoSQL injection vectors
+- Authentication/authorization bypasses
+- Unvalidated user input at system boundaries
+- Resource leaks (unclosed connections, file handles)
+- Race conditions with data corruption potential
+
+### Major
+Issues that cause bugs, design flaws, or significant maintainability problems:
+- Logic errors in business rules
+- Missing error handling on external calls
+- SOLID principle violations that impact extensibility
+- Incorrect API contracts or type mismatches
+- Missing null/undefined checks on external data
+
+### Minor
+Issues related to style, naming, or minor convention violations:
+- Naming inconsistencies
+- Code style deviations from project conventions
+- Suboptimal but correct implementations
+- Missing type annotations where inference is insufficient
+
+### Suggestion
+Optional improvements that enhance readability or maintainability:
+- Alternative patterns that improve clarity
+- Performance optimizations with marginal impact
+- Structural improvements for future extensibility
+
+## Output Format
+
+Present findings in a structured table followed by a summary:
+
+```
+## Code Review Results
+
+**Scope**: [description of what was reviewed]
+**Files Reviewed**: [count]
+**Total Findings**: [count by severity]
+
+### Findings
+
+| # | Severity | File | Line | Description | Suggested Fix |
+|---|----------|------|------|-------------|---------------|
+| 1 | Critical | path/to/file.ts | 42 | [description] | [fix] |
+| 2 | Major | path/to/file.ts | 87 | [description] | [fix] |
+
+### Summary
+
+[1-2 paragraph summary of overall code quality, patterns observed, and priority actions]
+```
+
+## Verification Rule
+
+Every finding **must**:
+- Reference a specific file and line number
+- Be verified against the actual code (not assumed from patterns)
+- Include a concrete suggested fix or action
+- Be classified with a severity that matches the classification criteria above
+
+Do NOT report:
+- Speculative issues based on assumptions about runtime behavior
+- Style preferences not established by the project's conventions
+- Issues in code outside the review scope
+
+## Review Scope Calibration
+
+Calibrate the depth and focus of review based on the type of change being reviewed:
+
+### Calibration Rules
+- **New files**: Full review across all dimensions — architecture fit, pattern compliance, security, naming conventions, error handling, testability, dependency direction
+- **Modified files (behavior change)**: Focus on the diff — correctness of new behavior, regression risk, contract compliance with existing interfaces, edge case handling in new code paths
+- **Modified files (refactoring)**: Focus on behavior preservation — verify same inputs produce same outputs, no unintended side effects introduced, no behavior changes disguised as refactoring
+- **Deleted files**: Dependency verification — confirm no remaining code imports from, references, or depends on the deleted files. Check for orphaned tests that tested the deleted code.
+- **Configuration changes**: Environment impact assessment — does this change affect production? Staging? Local development? All environments? Are there secrets or credentials involved?
+
+### Application
+When reviewing a diff that contains multiple change types (new files + modifications + deletions), apply the appropriate calibration to each file independently. Do not apply "new file" depth to a file that only had a minor modification.
+
+## Finding Deduplication Protocol
+
+When reviewing multiple files, identify and consolidate findings that share the same root cause.
+
+### Deduplication Rules
+- If the same pattern violation appears in 3+ files, report it **once** as a systemic finding with the list of all affected locations — not as N separate findings
+- A systemic finding includes: the pattern being violated, why it matters, the full list of affected file:line locations, and a single remediation recommendation that addresses all instances
+- Unique findings (appearing in only 1-2 files) are reported individually as normal
+
+### Deduplication Format
+```
+### Systemic Finding: [Pattern Violation Name]
+- **Severity**: [Critical | Major | Minor | Suggestion]
+- **Description**: [What the pattern violation is and why it matters]
+- **Affected Locations**:
+  - `path/to/file1.ext:line` — [brief context]
+  - `path/to/file2.ext:line` — [brief context]
+  - `path/to/file3.ext:line` — [brief context]
+- **Remediation**: [Single recommendation that addresses all instances]
+```
+
+This produces cleaner, more actionable review output by surfacing systemic issues as patterns rather than repeating the same finding across multiple files.