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 an escalation trigger.

Run linear implementation with strict gates.

Input Schema

{
  "goal": "required implementation objective",
  "mode": "feature|fix|refactor|config|spike",
  "constraints": [
    "optional constraints"
  ],
  "done_when": "required acceptance statement"
}

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 an 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 the failing behavior before editing.
• refactor: preserve behavior with characterization tests or an 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 the decision point, then invoke the 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 an exact localized edit with no unresolved structural fact, the 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 the routing above. Persist the result once here, before step 05 implementation; step 06 specialist fan-out consumes <run-directory>/codemap-context.json, never a fresh query.

04: Run the anti-rationalization gate before editing

• Existing code and tests for the target surface have been read.
• Failure mode or new behavior is captured by a failing doctest, pytest, or explicit acceptance check.
• Coding changes have a project coding-principles plan from the 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 a feature demo contract before production edits:
  • simple public API: inline doctest or focused pytest that shows the intended call and result
  • multi-step behavior: minimal example or pytest exercising the user-visible workflow end to end
  • the demo must be automatically executable and must fail against current code for the intended missing behavior
  • if the demo passes before implementation, stop and re-scope; do not silently proceed unless the user explicitly overrides the gate
• Review the demo contract for goal alignment, API shape, missing scenarios, and automatic verifiability before implementation.
• If the task starts from a 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 the claim, supporting logs/code, a falsification check, and at least one rejected alternative. A workaround-only change is a temporary mitigation, not completion, unless explicitly requested by the user.
• Behavior-preserving refactors have characterization tests or an equivalent current-behavior safety net.
• The next edit is the smallest reversible step, not a speculative refactor.

05: Implement minimal change

While implementing, keep the code understandable from the code itself:

• Apply the consolidated project coding principles from the 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 the logic inline, use a local helper, or use functools.partial when only binding arguments.
• Match the 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 a block needs a long explanation to be understandable.

06: Orchestrate specialists when the change crosses a domain boundary

Read and apply ../../shared/specialist-orchestration.md only when the 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 the user expressly requests Sol or selects that role; it returns a bounded read-only design artifact to the Terra parent/session, which continues and accepts.
• bug fix or regression: investigate or equivalent root-cause evidence first, then sw-engineer for the 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: the Terra parent/session scopes the risk before implementation and pairs sw-engineer with qa-specialist as needed. Use read-only security-auditor only when the user expressly requests Sol or selects that role; it returns a bounded evidence artifact to the 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 the verified public behavior, API signatures, examples, and migration notes; do not send unrelated implementation details.
• high-risk or broad changes: challenger runs after the 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 the full task history. If specialist fan-out is unavailable, record the 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 the 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 the shared confidence band policy from ../../shared/quality-gates.md. This skill records the 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 a gate; if the evidence is missing, keep the lower score and fail or time out with the 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 the 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 an 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 a purpose docstring in the configured, established, or fallback project style => fail unless it is generated or third-party code explicitly outside the edited ownership.
16. Non-trivial new or changed code block without an explanatory inline comment => fail unless the code was refactored until the rationale is obvious from names and structure.
17. Explanatory inline comment immediately before a new or changed function/class definition => fail; move that explanation into the 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 the local project pattern requires the structure.
19. Low-value tiny function/class that only remaps arguments, wraps one call without a 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 the 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 the 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, 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 the 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 the 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.