/develop

name: develop
description: Minimal codex-native develop loop. Use for implementation tasks with linear plan-build-verify flow and measurable quality gates.

Develop

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 `python PLUGIN_ROOT/shared/create_run.py --skill develop` once. Retain its single printed path as `<run-directory>` and substitute that literal path into every later artifact path and helper argument. Never store or reuse the path through a shell variable; shell variables do not persist across tool calls.

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)**: once a target module/symbol is scoped, also probe codemap-py once for callers, coupling, and test impact before implementation: `python PLUGIN_ROOT/shared/codemap_adapter.py context --category develop --target <qname> --out <run-directory>/codemap-context.json`. 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

Apply `../../shared/specialist-orchestration.md`. Stay single-agent for narrow implementation that fits in one to three files and one domain. Use specialist orchestration when the task crosses domains, benefits from independent verification, or can split into parallel context packs.

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

| role | trigger | context pack | expected output | mode | | --- | --- | --- | --- | --- |

Required orchestration patterns:

• public API or architecture: `solution-architect` for API contract/migration shape, `sw-engineer` for implementation, `qa-specialist` for acceptance matrix, and `doc-scribe` for public docs/docstrings when applicable.
• 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/m