Code Production Process

Code Production Process

Overview

This skill implements a six-stage quality-gate pipeline that every non-trivial code implementation task must pass through before being declared complete. The pipeline exists because the repository owner cannot visually assess code quality — all quality assurance must therefore be enforced by automated gates inside the agent pipeline itself, not by human review after the fact. Each stage produces a concrete artifact and must clear a defined gate before the next stage may begin. No stage may be skipped on the standard path. The critic agent operates with full context isolation to prevent anchoring bias from the implementer's own framing. A deliberately adversarial review catches issues that a cooperative pass-through would miss.

Trigger Conditions

This skill loads when any of the following conditions are true:

Explicit triggers (pre-dispatch):

• PM is about to dispatch an engineer agent for a task that will produce >50 lines of source code
• PM is about to dispatch an engineer agent for a task that will touch >1 source file
• Task description contains implementation verbs: "implement", "write", "build", "create", "refactor", "add feature", "fix bug in [module]"

Post-dispatch detection:

• Engineer agent returns and git diff --stat shows source file changes (.py, .ts, .js, .go, .rs, .java, .rb, .sh with logic) regardless of stated task scope
• Engineer agent produces new files under src/, lib/, app/, services/, api/ directories

Explicit exclusions — do NOT trigger this pipeline for:

• Documentation edits (.md, .rst, .txt, .html content-only)
• Commit messages, PR descriptions, changelogs
• Config-only changes (*.yaml, *.toml, *.json, *.env with no code logic)
• Single-line fixes with scope verified to be <5 lines
• Dependency version bumps with no code changes

When in doubt: err toward triggering the pipeline. A false positive costs one critic dispatch. A false negative ships broken or insecure code.

The 6-Stage Pipeline

Each stage has a defined agent, required output artifact, and a gate condition. The gate condition must be satisfied before proceeding. Failing a gate returns to the current stage, not to stage 1, unless the failure indicates a fundamental misunderstanding of requirements.

Stage 1: Research

Agent: research

Tools: mcp__vector-indexer-mcp__search_hybrid, mcp__knowledge__kb_search, mcp__knowledge__search_local

What the agent does:

• Searches the existing codebase for similar implementations that can be reused or extended
• Identifies existing abstractions, patterns, and conventions the implementation must follow
• Locates relevant KB entries covering architecture decisions, data models, API contracts
• Enumerates external dependencies and their established usage patterns in the codebase

Required output artifact: A written spec document (markdown) covering:

• What exists already (cite file paths and function names)
• What must be built new
• Which existing patterns the implementation must follow
• Input/output contracts the new code must satisfy
• Known edge cases from existing usage

Gate: Spec document exists and names at least one existing codebase reference. Research agent MUST NOT produce implementation code. If no relevant existing code exists, the output explicitly states "no prior implementation found" — this is a valid research finding, not a failure.

See: references/stage-research.md for prompt templates and search strategy.

---

Stage 2: Architect

Agent: python-engineer (in design mode — no implementation code produced)

Skills loaded: software-patterns

What the agent does:

• Reads the Stage 1 spec document
• Designs the public interface: class signatures, function signatures, data models, type annotations
• Specifies abstract base classes (ABCs) or Protocol classes where polymorphism is needed
• Documents invariants and preconditions for each public method
• Notes which external dependencies will be used and how

Required output artifact: An interface specification document containing:

• All public class/function signatures with full type annotations
• ABC or Protocol definitions (no method bodies — only ... or pass)
• Data model schemas (Pydantic models, dataclasses, TypedDicts — no logic)
• Error types that will be raised and their hierarchy
• A one-paragraph statement of what the implementation will NOT do

Gate: Interface document exists. Zero implementation code (no function bodies with logic, no algorithm steps, no I/O calls). The architect produces the contract; the engineer fills it.

Important: The code-critic agent may optionally be dispatched here to review the interface design for API coherence before implementation begins. This is the Phase 2 design critic pass. If dispatched, critic input is the interface document only — no code exists yet.

See: references/stage-architect.md for interface specification templates.

---

Stage 3: Implement

Agent: python-engineer

Skills loaded: software-patterns, asyncio (if async code required), pytest

What the agent does:

• Implements the interface defined in Stage 2 exactly (no scope creep — flag to PM if interface

needs amendment)

• Writes unit tests in pytest covering:
• Happy path for each public function
• Each documented error condition
• At least one edge case per function
• Runs mypy --strict on the new code and resolves all type errors before declaring done
• Runs pytest locally and confirms all tests pass before returning

Required output artifact:

• Source file(s) implementing the Stage 2 interface
• Test file(s) with pytest tests
• mypy --strict output showing zero errors
• pytest output showing all tests passed

Gate: Engineer must provide mypy and pytest output with zero errors/failures before returning to PM. If engineer cannot provide this output, the engineer did not finish — PM must re-dispatch, not proceed to Stage 3.5.

See: references/stage-implement.md for implementation standards and self-check checklist.

---

Stage 3.5: Tests-Must-Pass Gate

Agent: PM (not an agent dispatch — PM evaluates the Stage 3 output directly)

What PM does:

• Inspects the pytest output artifact from Stage 3
• If pytest shows ANY failure: immediately return to Stage 3 engineer. Do NOT dispatch

code-critic. Do NOT attempt to advance the pipeline. Failing tests mean implementation is incomplete.

• If pytest passes green (zero failures): proceed to Stage 4

This gate is non-negotiable. Dispatching code-critic against code with failing tests wastes tokens on findings that may be artifacts of the broken state. The critic reviews working code, not code under active repair.

Failure return message to engineer (template):

Tests failed. Return to Stage 3. Fix the following failures before requesting critic review:

[paste pytest output here]

When tests pass green, provide updated implementation + passing pytest output.

See: references/stage-tests.md for test quality requirements and coverage standards.

---

Stage 4: Critic Review

Agent: code-critic

Skills loaded: code-review-standards, code-production-process

Context isolation is mandatory. See "Critic Isolation Rule" section below for full requirements. Failure to isolate the critic context is a process violation.

What the critic agent does:

• Reviews the implementation against the Stage 2 interface specification
• Applies the code-review-standards severity-tagged checklist (CRITICAL/HIGH/MEDIUM/LOW)
• Produces a structured finding table with file+line citations for each finding
• Returns a top-level verdict: APPROVE, WARN, or BLOCK

Required output artifact:

• Verdict (APPROVE / WARN / BLOCK) stated at the top of response
• Finding table (may be empty for APPROVE) with columns: Severity | File | Line | Issue | Fix
• Summary paragraph explaining the verdict

Gate: Critic returns a verdict. PM acts on verdict per the Verdict Protocol below.

See: references/stage-critic.md for dispatch template and isolation checklist.

---

Stage 5: Security

Agent: security

Scope: OWASP Top 10, secrets/credentials exposure, injection vulnerabilities (SQL, shell, template), authentication and authorization bypass, arbitrary code execution paths, insecure deserialization, cryptographic weaknesses.

What the agent does:

• Reviews the Stage 3 implementation for security vulnerabilities in the above scope
• Does NOT re-review for code style or structural issues (that is the critic's domain)
• Produces a finding list with severity (CRITICAL / HIGH / MEDIUM / LOW) and remediation

Gate: Zero security findings at CRITICAL or HIGH severity. MEDIUM findings are documented and logged. LOW findings are noted. If CRITICAL or HIGH security findings are present, PM halts and surfaces to user — same protocol as a critic BLOCK.

See: references/stage-security.md for security review scope and OWASP mapping.

---

Critic Isolation Rule

The critic agent's verdict is only as independent as the context it receives. Anchoring bias — where the reviewer unconsciously accepts the author's framing of what the code does — is the primary failure mode of code review in multi-agent systems.

The PM MUST construct the critic dispatch prompt to contain ONLY: 1. The Stage 1 spec document (what was asked) 2. The Stage 2 interface specification (what was designed) 3. The Stage 3 implementation files (what was built) 4. The Stage 3 pytest output (test results)

The PM MUST NOT include in the critic dispatch prompt:

• The engineer's commit message
• The engineer's stated rationale or design notes from the implementation response
• Any summary the PM wrote about what the engineer did
• Phrases like "the engineer explained that..." or "according to the implementer..."

If the engineer's implementation response contains inline explanatory text mixed with code, PM must extract only the code and test output for the critic dispatch — strip the implementer's narration.

This rule exists because an engineer who writes "I chose this approach because the alternative would have performance issues" subtly pre-argues against the critic raising performance concerns. The critic must encounter the code cold.

See: references/critic-isolation.md for prompt construction templates.

Verdict Protocol

PM behavior is fully determined by the critic's top-level verdict. PM MUST NOT use judgment to override or soften the verdict protocol.

APPROVE (zero CRITICAL findings, zero HIGH findings):

• Proceed to Stage 5 (Security)
• No additional action required from engineer
• Finding table (if non-empty, containing only MEDIUM/LOW) is passed to the Documentation

agent handoff as "notes for future reference"

WARN (zero CRITICAL findings, one or more HIGH findings):

• Proceed to Stage 5 (Security) — do NOT halt the pipeline
• PM MUST append the full critic finding table to the handoff message sent to the

Documentation agent

• PM MUST log the findings in a note (KB entry or todo comment) for tracking
• PM MUST NOT silently discard HIGH findings — they must be surfaced somewhere

BLOCK (any CRITICAL finding):

• PM halts the pipeline immediately
• PM surfaces the critic finding table verbatim to the user
• PM states: "Critic has blocked this implementation. The following CRITICAL issues must be

resolved before the pipeline can continue. Please confirm your direction."

• PM awaits explicit user direction: fix-and-retry, override with justification, or abandon
• PM MUST NOT auto-re-delegate to engineer without user input
• When user directs fix-and-retry: return to Stage 3 (Implement) with the critic finding

table as an additional input. The architect interface from Stage 2 remains authoritative unless the CRITICAL finding reveals a fundamental interface design flaw, in which case PM returns to Stage 2.

Skip Rules (Hotfix Path)

The following rules define when stages may be skipped. Stages 3 through 5 are NEVER skippable regardless of path.

Standard path: All 6 stages. Required for all new features, refactors >100 lines, any change to authentication/authorization code, any change to data models.

Hotfix path: Stages 1 and 2 may be skipped when ALL of the following are true:

• The bug being fixed is confirmed in production (not a hypothetical or local-only failure)
• The fix scope is verified to be ≤20 lines of net new code across ≤2 files
• The fix does NOT touch authentication, authorization, cryptography, or data serialization
• PM explicitly notes "hotfix path" in the session log

Even on the hotfix path: Stage 3 (Implement + Tests), Stage 3.5 (Tests-Must-Pass Gate), Stage 4 (Critic), and Stage 5 (Security) are mandatory and cannot be skipped.

Documentation-only path: If ALL changes are confirmed to be documentation, configuration values, or dependency version bumps with no logic changes — all 6 stages are skipped. PM should verify via git diff --stat that no source files were modified.

See: references/skip-rules.md for skip rule decision tree and examples.

Failure Loop Protocol

When a stage gate fails, the finding returns to the responsible agent in a structured format. PM does not attempt to interpret or patch the finding — PM passes it verbatim.

Format for returning to engineer after BLOCK:

PIPELINE GATE FAILURE — Return to Stage [N]

Critic verdict: BLOCK
Findings (CRITICAL):

| Severity | File | Line | Issue | Required Fix |
|----------|------|------|-------|--------------|
[paste finding table verbatim]

Instructions:
- Fix ALL CRITICAL items above
- Re-run pytest (must pass green)
- Re-run mypy --strict (must pass)
- Return updated implementation with fresh test output

Do NOT return until all CRITICAL findings are resolved and tests pass.

Format for returning to engineer after WARN (if user requests fixes):

PIPELINE GATE — WARN findings for review

Critic verdict: WARN
Pipeline proceeded, but the following HIGH findings were logged:

| Severity | File | Line | Issue | Recommended Fix |
|----------|------|------|-------|-----------------|
[paste finding table]

These were noted in the documentation handoff. If you choose to address them in this session,
re-run tests and confirm they still pass. No re-critic required for WARN resolutions.

Token Efficiency Note

Stages 1 and 2 are lightweight by design. Research and Architect agents operate primarily on text documents (specs, KB entries, interface files) rather than large codebases. The majority of token spend occurs in Stages 3-5, where the implementation, tests, critic review, and security review all operate on the full codebase context. Dispatching Research and Architect first ensures that Stage 3 (Implement) receives a clear spec and does not require iterative clarification, reducing the number of engineer re-dispatches — which is the primary source of token waste in unstructured implementation workflows.

Critic Isolation — Prompt Construction Rules

Why Isolation Matters

Anchoring bias is the primary failure mode of code review in multi-agent systems. When the critic receives the implementer's stated rationale alongside the code, the critic unconsciously anchors to that framing and evaluates whether the rationale is valid rather than whether the code is correct and safe.

An engineer who writes "I used a list here because the dataset is small" has pre-argued against the critic raising memory complexity concerns. The critic must encounter the code cold — with no context about why choices were made — so that the critic's job is pure evaluation, not arbitration of the implementer's intent.

What PM Includes in the Critic Prompt

PM constructs the critic dispatch from scratch. Include ONLY:

1. Stage 1 spec document — verbatim, unmodified 2. Stage 2 interface specification — verbatim, unmodified 3. Stage 3 source files — verbatim, unmodified (code only, not the engineer's response text) 4. Stage 3 pytest output — verbatim (the raw terminal output, not a summary)

What PM MUST NOT Include

The following are explicitly prohibited from the critic prompt:

• The engineer's commit message
• The engineer's stated design rationale ("I chose X because Y")
• Any notes the engineer included about trade-offs or alternatives considered
• PM's own summary of what the engineer did or what changed
• Phrases like:
• "The engineer explained that..."
• "According to the implementer..."
• "The engineer noted that this approach was chosen because..."
• "Note: this is a simplified version because..."

Extraction Procedure

When the engineer's Stage 3 response mixes code with explanatory text:

1. Identify code blocks (between ` fences or clearly indented source) 2. Extract code blocks only — discard all surrounding prose 3. Do the same for pytest output: extract the raw output block, discard the engineer's commentary about what it means 4. Assemble critic prompt from extracted content only

If the engineer did not use code fences, PM should request the engineer re-submit with clear code block delimiters before proceeding to Stage 4.

Correct Critic Prompt Structure

Code review task.

Apply the code-review-standards checklist. Output verdict as first line.

== SPEC ==
[verbatim Stage 1 spec — no modifications]

== INTERFACE ==
[verbatim Stage 2 interface document — no modifications]

== SOURCE: path/to/file.py ==

[verbatim source code — no modifications]

== SOURCE: path/to/tests/test_file.py ==

[verbatim test code — no modifications]

== TEST RESULTS ==

[verbatim pytest terminal output]

Incorrect Critic Prompt (Anti-Pattern)

The engineer implemented the FetchService as requested. They noted that they
used a synchronous fallback because the async version was causing issues in
the test environment. Here is the code for your review:

[code follows]

The phrase "they noted that they used a synchronous fallback because..." gives the critic a ready-made excuse to accept what would otherwise be a HIGH finding (synchronous I/O inside an async function). This version is a process violation.

PM Self-Check Before Dispatch

Before dispatching the critic, PM answers these questions:

• [ ] Does my critic prompt contain the word "engineer"? (If yes, remove the sentence)
• [ ] Does my critic prompt contain "because" or "since" explaining any code choice? (If yes, remove it)
• [ ] Is the source code verbatim from the files, not paraphrased? (Verify)
• [ ] Is the pytest output verbatim terminal output, not a summary? (Verify)

All four must be clean before critic dispatch.

TODO: Expand with isolation verification patterns

<!-- TODO: Add automated check script that scans critic prompt for prohibited phrases --> <!-- TODO: Add examples of edge cases: engineer-added inline comments that explain rationale --> <!-- TODO: Add guidance for multi-engineer sessions where Stage 3 had multiple iterations -->

Skip Rules — Decision Tree and Examples

Overview

The pipeline has two legitimate skip paths. Everything else is a violation. Stages 3 through 5 are NEVER skippable.

Decision Tree

Is this a code change?
  NO → Documentation-only path (all stages skipped)
  YES → Continue

Is it a confirmed production bug fix ≤20 lines across ≤2 files?
  YES → Does it touch auth/crypto/serialization?
    YES → Standard path (all 6 stages)
    NO → Hotfix path (skip stages 1-2, run 3-5)
  NO → Standard path (all 6 stages)

Standard Path (All 6 Stages)

Required for:

• New features (any size)
• Refactors >20 lines of net new code
• Any change touching:
• Authentication or authorization logic
• Cryptographic operations
• Data serialization/deserialization
• Database schema or migration
• External API contracts
• Any change across >2 source files

Hotfix Path (Skip Stages 1 and 2)

Allowed only when ALL of the following are true:

1. The bug is confirmed in production — not a hypothetical, not a local-only failure 2. The fix scope is ≤20 lines of net new code across ≤2 files (verify with git diff --stat) 3. The fix does NOT touch: authentication, authorization, cryptography, data serialization 4. PM explicitly logs "hotfix path" in the session record

On hotfix path: Stage 3 (Implement + Tests), Stage 3.5 (Tests-Must-Pass Gate), Stage 4 (Critic), and Stage 5 (Security) remain mandatory.

Documentation-Only Path (All Stages Skipped)

Allowed only when ALL changes are:

• Markdown, RST, or plain text documentation
• Configuration values (no logic — e.g., updating a port number in config.yaml)
• Dependency version bumps with no code changes

PM MUST verify via git diff --stat that no .py, .ts, .js, .go, .rs, or other source files were modified. If any source file appears in the diff — even with one line changed — the documentation-only path is disqualified.

Examples

Violations

The following are process violations — if caught mid-session, PM must restart from the last valid stage:

• Skipping Stage 3 (Implement + Tests) for any reason
• Skipping Stage 4 (Critic) for any reason
• Skipping Stage 5 (Security) for any reason
• Declaring hotfix path for a change that modifies auth/crypto code
• Declaring documentation-only path without verifying git diff --stat

TODO: Expand with edge cases

<!-- TODO: Add guidance on changes that are "mostly config" but include one-line logic changes --> <!-- TODO: Add examples for migration files (schema change = standard path) --> <!-- TODO: Add handling for test-only changes (tests are source files — standard path applies) -->

Stage 2: Architect — Detailed Protocol

Purpose

The Architect stage produces the binding contract between "what was asked" (Stage 1 spec) and "what will be built" (Stage 3 implementation). By separating interface design from implementation, the pipeline allows critic review of API design before any code is written, catching structural problems when they are cheapest to fix.

Agent and Mode

• Agent: python-engineer (in design mode — implementation code is prohibited)
• Skills loaded: software-patterns

What "Design Mode" Means

The architect agent produces ONLY:

• Class and function signatures (with full type annotations)
• Abstract Base Class (ABC) or Protocol definitions
• Pydantic/dataclass/TypedDict data model schemas
• Exception class hierarchies
• A brief "non-goals" statement

The architect agent MUST NOT produce:

• Function bodies with logic (only ... or pass or raise NotImplementedError)
• Any algorithm steps, loops, conditionals in method bodies
• I/O calls, network calls, file operations
• Any executable code that performs work

Dispatch Prompt Template

Architecture task for: [task description]

Input: Stage 1 research spec (attached below)

Design the public interface. Produce:

1. All public class/function signatures with complete type annotations
2. ABC or Protocol definitions where polymorphism is needed
3. Data model schemas (Pydantic BaseModel or dataclass) — no logic, only fields + validators
4. Exception class hierarchy
5. Non-goals: one paragraph stating what this interface explicitly does NOT do

Constraints:
- No function bodies with logic
- No algorithm implementation
- No I/O operations
- Type all parameters and return values — no Any

[Stage 1 spec document here]

Interface Document Format

# interface.py — generated by Architect stage (Stage 2)
# DO NOT IMPLEMENT — this file defines contracts only

from abc import ABC, abstractmethod
from typing import Protocol
from pydantic import BaseModel

class FetchResult(BaseModel):
    """TODO: define fields"""
    url: str
    status_code: int
    data: dict

class FetcherProtocol(Protocol):
    async def fetch(self, url: str, timeout: float) -> FetchResult: ...

class BaseFetcher(ABC):
    @abstractmethod
    async def fetch(self, url: str, timeout: float) -> FetchResult: ...

class FetchError(Exception): ...
class TimeoutError(FetchError): ...
class ParseError(FetchError): ...

Gate Checklist

Before proceeding to Stage 3:

• [ ] All public functions have complete type annotations (no missing params, no missing return types)
• [ ] Data models are defined (no raw dicts in public APIs)
• [ ] Exception hierarchy is explicit
• [ ] Non-goals statement present
• [ ] Zero function bodies with logic (grep for any return, if, for, while, await in method bodies)

TODO: Expand with architecture patterns

<!-- TODO: Add examples for async vs sync interface decisions --> <!-- TODO: Add guidance on when Protocol vs ABC is appropriate --> <!-- TODO: Add data model design patterns (flat vs nested, validation rules) --> <!-- TODO: Add checklist for backward-compatibility constraints -->

Stage 4: Critic Review — Detailed Protocol

Purpose

The Critic stage provides an independent adversarial review of the implementation. By dispatching a separate agent with context isolation, the pipeline catches issues that the implementer — who already understands why they made each choice — cannot see objectively. The critic's job is to find real problems, not to approve work.

Agent and Skills

• Agent: code-critic
• Skills loaded: code-review-standards, code-production-process

Context Isolation Requirement

The critic prompt MUST be constructed by PM, not by the engineer. See references/critic-isolation.md for full rules. Short version:

• Include: Stage 1 spec, Stage 2 interface, Stage 3 source files, pytest output
• Exclude: engineer's commit message, stated rationale, design notes, PM summaries

Dispatch Prompt Template

Code review task.

You are reviewing an implementation for correctness, quality, and security.
Apply the code-review-standards checklist (CRITICAL, HIGH, MEDIUM, LOW).

== SPEC (Stage 1 output) ==
[paste Stage 1 spec document verbatim]

== INTERFACE (Stage 2 output) ==
[paste Stage 2 interface specification verbatim]

== IMPLEMENTATION (Stage 3 source files) ==
[paste source file(s) verbatim — no paraphrasing, no summaries]

== TEST RESULTS (Stage 3 pytest output) ==
[paste pytest output verbatim]

Required output format:
1. VERDICT: APPROVE / WARN / BLOCK (first line of response)
2. Finding table (may be empty):
   | Severity | File | Line | Issue | Required Fix |
3. Summary paragraph explaining the verdict

Verdict Definitions

Gate Checklist

Before accepting the critic output:

• [ ] Verdict is stated at the top (APPROVE / WARN / BLOCK)
• [ ] Finding table is present (even if empty)
• [ ] Each finding has file + line citation
• [ ] Summary paragraph explains the verdict
• [ ] No findings manufactured without >80% confidence (see code-review-standards)

TODO: Expand with critic calibration guidance

<!-- TODO: Add examples of well-formed vs poorly-formed findings --> <!-- TODO: Add guidance on how PM should evaluate suspiciously clean APPROVE verdicts --> <!-- TODO: Add patterns for multi-file implementations (how to cite cross-file issues) --> <!-- TODO: Add notes on the optional Phase 2 design critic pass (interface review before Stage 3) -->

Stage 3: Implement — Detailed Protocol

Purpose

Implementation fills the Stage 2 interface with working code and validates it with tests. The engineer does not invent new public APIs — they implement the ones designed in Stage 2. Any deviation from the Stage 2 interface must be flagged to PM before proceeding.

Agent and Skills

• Agent: python-engineer
• Skills loaded: software-patterns, asyncio (if async code), pytest

Scope

The engineer implements: 1. The source file(s) implementing the Stage 2 interface 2. Pytest unit tests with minimum 90% coverage on new code 3. Type-correct code that passes mypy --strict with zero errors

Engineer Self-Check (Before Returning to PM)

The engineer MUST perform these checks and include output in the response:

# 1. Run mypy strict
mypy --strict path/to/new_module.py

# 2. Run pytest with coverage
pytest tests/test_new_module.py -v --cov=path/to/new_module --cov-report=term-missing

# 3. Verify no bare except
grep -n "except:" path/to/new_module.py  # should return nothing

# 4. Verify no eval/exec
grep -n "\beval\b\|\bexec\b" path/to/new_module.py  # should return nothing

All four checks MUST return clean output before the engineer declares the implementation done.

Implementation Standards

• Functions: ≤20 lines preferred, ≤50 lines maximum before extraction
• No mutable default arguments (def foo(items=[]) is forbidden)
• No global mutable state
• No bare except: — always catch specific exceptions or Exception with logging
• Async functions: no synchronous I/O inside (no requests.get, open() in async def)
• Error paths: every exception must be either re-raised, logged and re-raised, or converted to a domain error type — never silently swallowed

Dispatch Prompt Template

Implementation task for: [task description]

Inputs:
- Stage 1 spec: [attached]
- Stage 2 interface specification: [attached]

Implement the interface exactly as designed. Do NOT modify the public API.
If you find the interface is unimplementable as specified, flag the issue
to PM before proceeding — do not silently work around it.

Required deliverables:
1. Source file(s) implementing the Stage 2 interface
2. Pytest test file(s) with ≥90% coverage on new code
3. mypy --strict output (zero errors required)
4. pytest output (zero failures required)

Standards:
- All functions: complete type annotations
- All exceptions: explicitly handled, not swallowed
- All async functions: no synchronous I/O inside

TODO: Expand with implementation patterns

<!-- TODO: Add async HTTP implementation patterns (aiohttp, httpx) --> <!-- TODO: Add database access patterns (SQLAlchemy async, psycopg3) --> <!-- TODO: Add test fixture patterns for common dependencies (DB, HTTP, filesystem) --> <!-- TODO: Add coverage threshold enforcement (conftest.py settings) -->

Stage 1: Research — Detailed Protocol

Purpose

The Research stage prevents "build from scratch" when an existing implementation can be reused or extended. It also surfaces the codebase conventions the new code must follow, so the engineer does not introduce a third pattern where two already exist.

Agent and Tools

• Agent: research
• Primary tools:
• mcp__vector-indexer-mcp__search_hybrid — semantic + lexical code search
• mcp__knowledge__kb_search — KB entries for architecture decisions
• mcp__knowledge__search_local — local document search
• Secondary tools: Grep, Glob for exact-string follow-up on vector results

Dispatch Prompt Template

Research task for: [task description]

Perform the following searches and document findings:

1. Search the codebase for existing implementations of [domain concept]:
   - Use search_hybrid("[domain keywords]")
   - List file paths, function/class names, and what each does

2. Search KB for prior architectural decisions about [domain]:
   - Use kb_search("[domain] architecture")
   - Note any decisions that constrain the new implementation

3. Identify established patterns for [specific mechanism, e.g., async HTTP, DB access]:
   - Search for existing usage in the codebase
   - Identify which libraries/frameworks are already in use

4. List known edge cases from existing implementations

Output format:
- Section: "Existing Implementations Found" (paths + descriptions)
- Section: "Conventions to Follow" (patterns, naming, error handling)
- Section: "What Must Be Built New" (gaps research found)
- Section: "Edge Cases Noted"
- Section: "Input/Output Contracts Required"

Gate Checklist

Before proceeding to Stage 2:

• [ ] Spec document is written (not just a list of search results)
• [ ] At least one existing codebase reference is cited (or "no prior implementation found" stated explicitly)
• [ ] Conventions section identifies naming patterns, error handling style, import style
• [ ] No implementation code appears in the research output

TODO: Expand with domain-specific search strategies

<!-- TODO: Add example searches for common domains: async HTTP, database access, auth, file I/O --> <!-- TODO: Add guidance on interpreting zero-result searches (new domain vs. wrong query) --> <!-- TODO: Add checklist for reviewing external dependency usage patterns -->

Stage 5: Security Review — Detailed Protocol

Purpose

Security review is a distinct pass from code quality review. Where Stage 4 (Critic) checks structure, style, and correctness, Stage 5 checks for exploitable vulnerabilities. A clean critic APPROVE does not guarantee security — the security agent applies a different lens and terminates the pipeline if CRITICAL or HIGH vulnerabilities are found.

Agent

• Agent: security
• Skills loaded: none required beyond agent's built-in security knowledge

Scope

The security agent reviews ONLY for security vulnerabilities. It MUST NOT re-flag issues already addressed by the critic (code style, coverage, type hints). Scope is:

OWASP Top 10 Mapping

Additional Security Checks

• Hardcoded secrets: grep for api_key, password, secret, token in literals
• Arbitrary code execution: eval, exec, subprocess with shell=True + user input
• Path traversal: user-controlled filenames used in open(), os.path.join()
• XML vulnerabilities: XXE in lxml, xml.etree with external entity loading
• Timing attacks: non-constant-time comparison for secrets/tokens

Dispatch Prompt Template

Security review task.

Review the following implementation for security vulnerabilities.
Scope: OWASP Top 10, secrets exposure, injection, auth bypass, code execution paths.
Do NOT flag code style, coverage, or type hint issues — focus only on exploitable flaws.

== IMPLEMENTATION (source files) ==
[paste source file(s) verbatim]

Required output format:
1. SECURITY VERDICT: PASS / WARN / BLOCK (first line)
   - PASS: zero CRITICAL or HIGH security findings
   - WARN: zero CRITICAL, one or more HIGH (pipeline proceeds with findings logged)
   - BLOCK: any CRITICAL finding (pipeline halts)
2. Finding table:
   | Severity | File | Line | Vulnerability | Remediation |
3. Summary paragraph

Gate

Zero CRITICAL or HIGH security findings. If any CRITICAL or HIGH:

• PM halts pipeline
• PM surfaces finding table verbatim to user
• Same protocol as a critic BLOCK (see Verdict Protocol in SKILL.md)

TODO: Expand with tooling integration

<!-- TODO: Add pip-audit / safety command for dependency vulnerability scanning --> <!-- TODO: Add bandit static analysis configuration and interpretation --> <!-- TODO: Add patterns for common false positives (crypto in tests, test hardcoded secrets) --> <!-- TODO: Add SSRF validation patterns for URL-fetching code -->

Stage 3.5: Tests-Must-Pass Gate — Detailed Protocol

Purpose

This gate enforces a hard prerequisite: code-critic reviews working code only. Dispatching the critic against code with failing tests wastes tokens on findings that may be artifacts of the broken state, not real issues in the final implementation. The gate is a PM-level evaluation — no agent dispatch needed.

PM Decision Tree

Engineer returns from Stage 3
         |
         v
PM reads pytest output artifact
         |
   ┌─────┴─────┐
   |           |
FAILURES    ALL PASS
   |           |
   v           v
Return to   Proceed to
Stage 3     Stage 4

What PM Checks

1. Open the pytest output artifact from the engineer's Stage 3 response 2. Look for the summary line: X passed, Y failed or X passed (no failures) 3. If ANY failures: stop. Do not proceed. Return to engineer with the failure template. 4. If zero failures: check mypy output (also required). If mypy has errors: return to engineer. 5. Only if BOTH pytest and mypy are clean: proceed to Stage 4.

Return-to-Engineer Template

Tests failed — return to Stage 3.

Required: pytest passes with zero failures AND mypy --strict passes with zero errors
before critic review can be dispatched.

Pytest failures:
[paste failures verbatim]

Mypy errors (if any):
[paste mypy output verbatim]

Fix the above, re-run both checks, and return with clean output.
Do NOT guess at the fix — if the test logic itself is wrong, fix the test.
If the implementation is wrong, fix the implementation.
Report which was fixed.

Test Quality Requirements

Tests returned from Stage 3 must meet these minimums to be accepted by this gate:

• Coverage: ≥90% on new code (check --cov-report=term-missing output)
• Test types required:
• At least one happy-path test per public function
• At least one error-condition test per documented exception
• At least one edge-case test per function (empty input, None, boundary values)
• Forbidden test patterns:
• Tests that only assert True or is not None — must assert specific values
• Tests that call pass or have empty assertion blocks
• Tests with sleep() for timing (use asyncio.sleep with pytest-asyncio or mock)
• Tests that access production databases, external APIs, or network resources

TODO: Expand with coverage tooling

<!-- TODO: Add conftest.py setting for minimum coverage threshold (fail-under=90) --> <!-- TODO: Add pytest-asyncio configuration for async test functions --> <!-- TODO: Add mock patterns for common external dependencies --> <!-- TODO: Add guidance on when integration tests are required vs unit tests sufficient -->