Implement

Implement

See the fixed recurrence and root-cause policy and reasoning-progress escalation policy for repeated-obstacle handling; record and validate reasoning-progress.json before another cycle after escalation trigger.

Run linear implementation with strict gates.

Input Schema

{
  "goal": "required implementation objective",
  "mode": "feature|fix|refactor|config|spike",
  "constraints": [
    "optional constraints"
  ],
  "execution": "optional auto|serial|parallel-read|parallel-write; default auto",
  "done_when": "required acceptance statement"
}

Parallel Adoption (Portable read-only)

This skill permits only its promoted portable read-only route. Resolve execution precedence from per-invocation --execution=<mode>, then CODEX_RIG_EXECUTION, then the auto default. The default execution mode is auto. auto selects this route only after this consumer's runtime matrix and promotion; otherwise it resolves safely to serial. Every write still requires a frozen plan and exact-digest approval. This route never bypasses consumer promotion, serial parent authority, or write approval.

Follow the canonical G0–G8 execution flow for shared gate order and fork outcomes. This consumer's read-only evidence passes are bounded by G0–G5; parent owns deterministic G6 integration, G7 verification, and G8 verdict/promotion.

Safe parallel work

The promoted route permits read-only evidence, acceptance, and documentation-impact passes with immutable disjoint context packs and separate outputs. Source, test, documentation, configuration, calibration, cache, generated-output, artifact, and result writes are outside this portable route.

Required barrier

Apply shared host compatibility check before preparing any child work. Include read_host only from verified launcher-supported child controls. Missing or incompatible controls make auto resolve serial with reason; explicit parallel-read stops before dispatch. A plan declaration is not effective-control proof, and post-run validation remains mandatory.

Before any dispatch, freeze goal, mode, done_when, baseline, ownership DAG, context packs, role-card hashes, checks, resource locks, and plan digest. Dispatch at most one fixed dependency-ready wave, then join every terminal handoff before implementation, integration, gates, or acceptance; changed scope requires new plan.

The frozen <run-directory>/execution-plan.json must include exact consumer_policy values consumer_id=implement, capability=portable-read-only, promotion_status=promoted, parent_mutations=serial, and canonical_gates=serial. It must also include write_policy: use parent_writes=planned with approval_requirement=exact-plan-digest when any parent mutation is planned, otherwise parent_writes=none with approval_requirement=not-required. A planned write requires <run-directory>/write-approval.json containing only exact plan SHA-256, response=approve, and source=explicit-input|user-prompt.

Before dispatch, run python PLUGIN_ROOT/shared/parallel_execution.py preflight --consumer implement --plan <run-directory>/execution-plan.json --approval <run-directory>/write-approval.json; append --execution=<mode> only for explicit invocation value. Omit --approval only when frozen write policy declares no parent writes. A nonzero result stops route.

After every spawned child reaches a terminal handoff, run python PLUGIN_ROOT/shared/parallel_execution.py validate-runtime --consumer implement --manifest <run-directory>/execution-manifest.json --plan <run-directory>/execution-plan.json --parent-rollout <authoritative-parent-rollout> --sessions-dir <authoritative-sessions-directory> --run-dir <run-directory> --roles-dir PLUGIN_ROOT/roles. Require runtime_promotion_eligible=true, consumer_id=implement, and write_parallel_eligible=false. Run the same preflight again after the terminal join and before the first parent mutation. Any plan, approval, consumer, runtime, or join drift stops mutation and requires a new frozen plan plus exact approval.

Serial parent decisions

Parent owns all implementation, test, and documentation writes; shared files and dependency chains; integration and conflict handling; calibration, artifacts, and result writes; canonical quality gates; verdict; and promotion. Never expand wave dynamically or dispatch dependent work early.

Resource conflicts

Declare only validated resource locks such as git-index, cache:<path>, generated:<path>, and test-env:<name>. Shared paths, indexes, caches, generated outputs, test environments, ports, devices, or undeclared resources force serial execution or re-planning.

Fallback

Unavailable or unsafe fan-out uses equal-gate serial-fallback from the same frozen plan with the same quality gates and retained evidence. Never label fallback as parallel or weaken checks because dispatch was unavailable.

Acceptance

This skill's shared runtime matrix and consumer promotion must remain complete before auto selects this route. Acceptance must prove freeze, complete join, truthful execution label, resource compatibility, equal gates, and unchanged serial parent authority.

Stop rule

Generic parallel writes remain disabled. Stop without dispatch on missing promotion, mutable packs, ownership or resource overlap, sensitive or unproven controls, missing terminal evidence, or incomplete join; implementation, test, documentation, and all other mutations remain parent-serial.

Workflow (Exact Commands)

01: Create run directory

Run create_run.py --skill implement per ../../shared/helper-cli-contract.md.

02: Record baseline diff and branch

Run git rev-parse --abbrev-ref HEAD as argv command and write stdout to <run-directory>/branch.txt.

Inspect python PLUGIN_ROOT/shared/collect_diff.py --help; collect working-tree into <run-directory>/baseline.

03: Route the change type and define ownership

Modes:

• feature: define public behavior, acceptance checks, docs impact, and tests before implementation.
• fix: reproduce or cite failing behavior before editing.
• refactor: preserve behavior with characterization tests or equivalent safety net.
• config: inventory references and calibration/routing impact before editing.
• spike: read-only or disposable probe; do not present as completed implementation.

Define narrowest reversible change, owners, acceptance. For 3+ steps/design tradeoffs, update plan before edit.

Structural context (optional): select one task-neutral route at decision point, then invoke adapter once: python PLUGIN_ROOT/shared/codemap_adapter.py context --category implementation --query-kind <kind> [--target <qname>] --out <run-directory>/codemap-context.json. Use skip for exact localized edit with no unresolved structural fact, matching single route (central, callers, blast, dependencies, test-impact, or coupling) for one unresolved fact, and standard for broad or unknown scope. Map direct, all, or production caller questions to callers; use blast only for explicitly transitive caller questions. An explicit user or tool request for structural evidence overrides skip. Per ../../shared/codemap-contract.md, absence/incompatibility is non-fatal — continue with routing above. Persist result once here, before step 05 implementation; step 06 specialist fan-out consumes <run-directory>/codemap-context.json, never fresh query.

04: Run the anti-rationalization gate before editing

• Existing code and tests for target surface have been read.
• Failure mode or new behavior is captured by failing doctest, pytest, or explicit acceptance check.
• Coding changes have project coding-principles plan from applicable AGENTS.md layers: simple/readable/reproducible structure first, short reusable units without low-value argument-remapping wrappers, guard clauses or early return/yield/continue for invalid or terminal cases, project docstring-style detection, concise purpose docstrings, and inline comments only for non-trivial implementation blocks.
• feature mode has feature demo contract before production edits:
  • simple public API: inline doctest or focused pytest that shows intended call and result
  • multi-step behavior: minimal example or pytest exercising user-visible workflow end to end
  • demo must be automatically executable and must fail against current code for intended missing behavior
  • if demo passes before implementation, stop and re-scope; do not silently proceed unless user explicitly overrides gate
• Review demo contract for goal alignment, API shape, missing scenarios, and automatic verifiability before implementation.
• If task starts from symptom, failing test, failing CI, flaky behavior, regression, tool/environment error, or unexplained metric shift, run investigate first or document equivalent root-cause evidence before editing.
• Root-cause evidence includes claim, supporting logs/code, falsification check, and at least one rejected alternative. A workaround-only change is temporary mitigation, not completion, unless explicitly requested by user.
• Behavior-preserving refactors have characterization tests or equivalent current-behavior safety net.
• The next edit is smallest reversible step, not speculative refactor.

05: Implement minimal change

While implementing, keep code understandable from code itself:

• Apply consolidated project coding principles from applicable AGENTS.md layers.
• Refactor long, dense, or deeply nested blocks into named helpers/classes before adding explanatory text.
• Avoid tiny rarely used helpers that only remap arguments; keep logic inline, use local helper, or use functools.partial when only binding arguments.
• Match project's configured or established docstring style, and keep function/class purpose in docstrings rather than comments directly above definitions.
• Refactor instead of writing long docstrings or comments when block needs long explanation to be understandable.

06: Orchestrate specialists when the change crosses a domain boundary

Read and apply ../../shared/specialist-orchestration.md only when task crosses domains, benefits from independent verification, or splits into parallel context packs; do not load it for narrow one-domain implementation in one to three files.

Before spawning or substituting specialists, write <run-directory>/specialist-plan.md with one row per planned pass:

Required orchestration patterns:

• public API or architecture: sw-engineer for implementation, qa-specialist for acceptance matrix, and doc-scribe for public docs/docstrings when applicable. Use solution-architect only when user expressly requests Sol or selects that role; it returns bounded read-only design artifact to Terra parent/session, which continues and accepts.
• bug fix or regression: investigate or equivalent root-cause evidence first, then sw-engineer for fix and qa-specialist for failure-before/pass-after proof.
• CI/tooling: cicd-steward for workflow behavior and linting-expert for ruff/mypy/pre-commit or suppression policy.
• security-sensitive code: Terra parent/session scopes risk before implementation and pairs sw-engineer with qa-specialist as needed. Use read-only security-auditor only when user expressly requests Sol or selects that role; it returns bounded evidence artifact to Terra parent/session, which continues and accepts.
• ML/data/research behavior: data-steward for data contracts, scientist for method/metric validity, squeezer for performance claims, plus qa-specialist for tensor boundary tests.
• docs-impacting behavior: doc-scribe gets only verified public behavior, API signatures, examples, and migration notes; do not send unrelated implementation details.
• high-risk or broad changes: challenger runs after draft plan or diff to stress-test assumptions and residual risk.

Each specialist context pack must include only relevant files, hunks, logs, and questions. Do not give every specialist full task history. If specialist fan-out is unavailable, record in-main substitute in <run-directory>/specialist-notes.md and lower confidence when independence mattered.

07: Write <run-directory>/development-notes.md before running gates

Required sections:

• Scope
• Acceptance Criteria
• Evidence
• Specialist Policy
• Gates

08: Run shared quality gates

Inspect python PLUGIN_ROOT/shared/run_gates.py --help, then run all project-relevant gates with explicit commands or skip reasons.

09: Review the changed files and the gate output before deciding pass/fail

10: Classify findings using ../../shared/severity-map.md

11: Run confidence calibration and recovery before any user-facing output

Write <run-directory>/confidence-calibration.md with these sections:

• Initial Confidence: starting score and concrete uncertainty sources.
• Objective Evidence: code paths read, tests/checks run, reproduction or acceptance evidence, and artifacts inspected.
• Confidence Gaps: missing evidence, unverified assumptions, risky substitutions, or unavailable checks.
• Recovery Actions: internal loops already performed to increase confidence, such as reading more source, running focused checks, adding/adjusting tests, consulting specialist policy, or reducing scope.
• Recomputed Confidence: final score after recovery, with why it is objectively supported.
• Remaining Limits: residual uncertainty and why it is acceptable or blocking.

Shared confidence policy:

Apply shared confidence band policy from ../../shared/quality-gates.md. This skill records required evidence in confidence-calibration.md and mirrors it in IMPLEMENT_METADATA.confidence_recovery before output.

Confidence must be honest and objectively verifiable. Do not inflate it to pass gate; if evidence is missing, keep lower score and fail or time out with missing evidence named.

12: Write and validate the mandatory result artifact

Follow ../../shared/helper-cli-contract.md and authoritative help. Write with IMPLEMENT_METADATA, validate as skill implement, and promote only validated candidate.

IMPLEMENT_METADATA.confidence_recovery must mirror confidence-calibration.md and include initial_confidence, final_confidence, status, evidence, recovery_actions, and remaining_limits. IMPLEMENT_METADATA.confidence_gap_closures must include one closure record per non-empty confidence_gaps entry, with status=closed|unresolved|deferred and matching evidence or rationale.

Fail-fast Rules

1. Missing goal or done_when => fail.
2. Shared gate script missing => fail.
3. Any critical finding => fail.
4. Ambiguous scope or missing ownership => fail.
5. Missing failing doctest, pytest, or explicit acceptance check for changed behavior => fail.
6. feature mode without executable failing demo contract before production edits => fail.
7. Feature demo passes before implementation without explicit user override and re-scope note => fail.
8. Symptom-first task edited without investigate output or equivalent root-cause evidence => fail.
9. Workaround-only fix presented as completion without explicit temporary-mitigation instruction => fail.
10. Behavior-changing config/agent/skill edit without calibration/routing decision => fail.
11. Specialist-required domain change without specialist output or labeled substitute => fail.
12. Missing development-notes.md sections => fail.
13. Result artifact validator failure => fail.
14. Result artifact missing => fail.
15. New or materially changed function/method without purpose docstring in configured, established, or fallback project style => fail unless it is generated or third-party code explicitly outside edited ownership.
16. Non-trivial new or changed code block without explanatory inline comment => fail unless code was refactored until rationale is obvious from names and structure.
17. Explanatory inline comment immediately before new or changed function/class definition => fail; move that explanation into docstring.
18. Long, dense, or deeply nested new/changed code block that could be split into clear helpers/classes or simplified with guard clauses => fail unless local project pattern requires structure.
19. Low-value tiny function/class that only remaps arguments, wraps one call without semantic purpose, or is rarely used => fail unless it materially improves readability, testability, or API stability.
20. Missing confidence-calibration.md sections => fail.
21. Shared confidence policy violation from ../../shared/quality-gates.md => fail.

Quality Gates

Required checks:

• review: git diff --check, changed-file inspection, acceptance criteria trace, simplicity/readability/reproducibility inspection, project docstring-style detection, and docstring/comment policy inspection for changed code.
• tests: failing-then-passing check or explicit acceptance probe for changed behavior; feature mode must include demo failure before edits and demo pass after implementation.
• artifact: shared validator confirms development-notes.md, gate logs, and result JSON shape.
• confidence: confidence-calibration.md and IMPLEMENT_METADATA.confidence_recovery satisfy shared confidence band policy from ../../shared/quality-gates.md.

Conditional checks:

• lint/format/types: run project-configured commands when code or typed config changed.
• calibration: run when workflow skills, role/agent routing, .codex/config.toml, or calibration fixtures changed; Codex Rig source uses runtime/calibration/run.py --layout plugin.

Calibration Hooks

Update calibration when implementation routing or output expectations change:

• benchmark patterns: implement
• behavioral cases: symptom-first routing, specialist substitution, config behavior changes, premature portable read-only adoption, missing acceptance probe, feature demo gate bypass, missing project docstring-style detection, missing function docstrings, overlong docstrings masking complex code, long code blocks not factored, deep branching without guard clauses, low-value argument-remapping wrappers, pre-definition comments that should be docstrings, missing explanatory inline comments, low-confidence recovery loop, objective confidence evidence, artifact validator bypass

Output Contract

Before writing result candidate, follow ../../shared/final-handoff-contract.md: render and bind final-handoff.json, final.md, and final-handoff.validation.json; after both validators and promotion pass, emit final.md verbatim.

Use ../../shared/quality-gates.md. Final chat follows its ordered frame. Outcome is pass, fail, partial, or blocked and states whether done_when was met. When multiple surfaces changed, Results uses exactly Surface | Outcome | Verification | Remaining limit. Apply shared Verification, Remaining, Next steps, and supplemental Artifact rules. Confidence also includes band, recovery actions, material gaps/degradation reasons, and closure status from metadata.confidence_gaps and metadata.confidence_gap_closures.

Minimum artifact payload template: result-template.json.