code-production-process

What this skill does

# 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