---
name: develop-workflow
description: Runs feature work and other multi-step code changes through repository research, an approved implementation plan, isolated Git worktrees, explicit UI and risk gates, verification, independent review, and local integration. Use by default for features, non-trivial bug fixes, refactors, migrations, dependency changes, security-sensitive work, and UI changes. Excludes questions, research-only requests, and obvious low-risk edits requiring at most two steps.
---

# Develop workflow

Own orchestration in the parent agent. Treat Git and the retained workflow record as recovery evidence; use task tools only as the live progress view. Give subagents bounded assignments, then verify their claims against repository state.

## 0. Classify the request

Choose the smallest sufficient path before mutation:

- **Answer:** explain or research read-only. Make no changes.
- **Light:** make one obvious low-risk edit requiring at most two steps. Inspect, edit, run focused checks, and summarize. Record why this is safe when near the boundary.
- **Full:** use the phases below for three or more steps, multiple files or modules, ambiguity, architecture, dependencies, migrations, security implications, non-trivial UI, or meaningful regression risk.

Promote light work to full before editing when discovery reveals meaningful scope or risk.

**Complete when:** observed scope and risk justify the selected path.

## Risk gates for every path

Ask just in time before adding, removing, or materially upgrading dependencies; schema/data migration; production or live-database access; public API or compatibility breaks; destructive Git/filesystem actions outside the narrowly proven final cleanup; force push or shared-history rewrite; non-fast-forward integration; conflict resolution that changes approved behavior; material scope or acceptance expansion; security-posture changes; publishing; or deployment.

Present concrete evidence, scope the authorization, and mark one option recommended with its reason. Checkpoint the decision before acting. Treat approval as specific to that action; ask again when later evidence broadens it. Promote light work to full before editing when meaningful risk appears.

## 1. Preflight and isolate

For the full path, require Git worktrees, a writable repository record, `ask_user`, Git-capable independent reviewers, and target-interface validation when UI applies. Stop before product mutation when a mandatory capability is unavailable. Let task tools degrade to the retained record and let `artifact-presenter` degrade to reporting the exact artifact path; neither optional convenience may bypass a gate. In print or JSON mode, emit the pending gate or validation instructions and stop.

Read repository instructions, relevant docs/ADRs/tests, and Git state. Follow [Git and integration](references/git-and-integration.md) to capture source evidence, resolve dirty-source approval, and establish the isolated branch/worktree. Prepare a unique record from [`assets/workflow-record.md`](assets/workflow-record.md) and publish it with the helper in [evidence and recovery](references/evidence-and-recovery.md). Create the available live progress view, run applicable documentation checks, and commit the initial record before product mutation.

**Complete when:** worktree identity is proven and the initial record commit names the next safe action.

## 2. Discover and decide requirements

Launch independent read-only research lanes directly when concerns can be investigated separately; state that no files are owned. Give each child a self-contained prompt. Keep the parent active on other work and verify that every required result was delivered. Treat missing delivery as missing evidence.

Reconcile repository evidence into scope, out-of-scope items, acceptance criteria, affected surfaces, constraints, and risks. Use `ask_user` only for decisions repository evidence cannot answer. Checkpoint decisions.

**Complete when:** requirements and unresolved questions are explicit.

## 3. Design and obtain plan approval

Record an exact implementation plan containing:

- acceptance criteria mapped to slices;
- one named owner and concrete path ownership per mutating assignment;
- existing seams and patterns;
- focused and full verification commands with realistic data needs;
- UI classification, dependencies, migrations, production effects, and risk gates;
- review fixed point and specification source;
- integration and rollback strategy;
- a 15-minute default deadline per mutating assignment, or an explicitly approved alternative.

Present the complete record through `artifact-presenter`, then obtain explicit approval with `ask_user`. Checkpoint and commit the decision before production edits. Return to this gate after any material scope, acceptance, ownership, verification, or architecture change.

**Complete when:** the user explicitly approved the exact committed plan.

## 4. Resolve non-trivial UI direction

For non-trivial UI, invoke `prototype` and create three structurally different throwaway candidates before production-component edits. Ask approval for a smaller explicit count when three meaningful alternatives are impossible. Validate candidates through `browser-harness` for web UI or the real PTY/application for terminal/native UI, including representative responsive sizes.

Retain candidates on a dedicated throwaway branch and record its commit. Present them and obtain direction approval through `ask_user`. Checkpoint the selected direction before production mutation. Rewrite the chosen direction as production code rather than promoting prototype code. Record why minor or non-visual UI skips this phase.

**Complete when:** target-interface evidence, retained prototype commit, selected direction, and reflected plan are recorded.

## 5. Implement owned slices

State one owner and exclusive paths for every mutating assignment. Serialize by default; parallelize only disjoint low-integration paths. Give each implementer the approved plan, decisions, acceptance criteria, test seam, allowed commands, and deadline. Tell workers to stop at the deadline and leave commits, integration, user interaction, and mutation delegation to the parent.

Follow [assignment evidence and recovery](references/evidence-and-recovery.md#assignment-evidence) before accepting, retrying, or reassigning mutation. Use TDD at agreed seams where practical. Run focused tests after behavioral slices. Inspect each returned diff and repository state before marking it complete.

**Complete when:** every acceptance criterion has intentional owned code and test evidence.

## 6. Verify the integrated worktree

Inspect the complete diff and status. Run focused behavioral tests, then repository-required typecheck, lint, build, and full tests. Exercise realistic E2E data across process/UI boundaries. Validate changed UI in its target interface and representative sizes. Synchronize affected documentation.

Record exact commands, exit codes, and concise outcomes. Keep flaky or environmental failures visible until resolved or escalated. Never infer success from a child transcript.

**Complete when:** the approved verification matrix passes against the integrated worktree state.

## 7. Commit, synchronize, and review

Create focused commits after their checks pass. Follow [Git and integration](references/git-and-integration.md) to fetch/rebase, reverify changed trees, and produce the pinned review brief and exact diff fingerprint. Follow [review and remediation](references/review-and-remediation.md) for two independent review axes, mutator exclusion, findings, and fresh-review rules.

**Complete when:** standards and specification reviewers approve the exact verified product diff.

## 8. Integrate and close

Follow [Git and integration](references/git-and-integration.md). Recheck the source branch and checkout, fast-forward only when evidence remains valid, then create one metadata-only closure commit touching only the record. Run a cheap final sanity check. Remove the workflow-owned worktree and branch only after reachability and clean-state proofs.

Mark tasks complete and report product/closure commits, review command and digest, reviewer identities, record path, and verification evidence. Keep push, publish, deployment, production access, unsafe cleanup, conflict-driven behavior changes, force operations, and non-fast-forward integration behind explicit just-in-time approval.

**Complete when:** reviewed work and closure are reachable from the intended local source branch and temporary state is safely removed.