Stepwise

stepwise

After explicit selection of $stepwise, execute the chosen ordered process. Each independent step runs in a new clean child using transport selected for that step. Same-host work normally uses an active-host native child; the existing Claude, Codex, Grok, and Kimi subprocess harness is the explicit external adapter. A new clean critic judges whether each attempt honored its declared contract. When a critic fails or abstains with inspectable evidence, Stepwise diagnoses the failure before repair: it reads the evidence, talks directly to the exact relevant child, walks upstream when inputs are suspect, and authors the repair prompt itself.

Stepwise maintains a truthful chain from user intent to manifest, from manifest to owner skill, from owner skill to worker action, from worker action to evidence, and from evidence to critic judgment. When the chain breaks, Stepwise locates the break and restores truth. It does not paper over the break.

When to use

• "ramp up on and implement strictly according to order"
• "run in ../ and make sure no steps are skipped"
• "orchestrate with a critic checking each step"
• "just get it done but don't make stuff up" where the request still needs ordered child roles and auditable evidence

When not to use

• Free-form requirement loops with no step manifest -> native /goal.
• Plan-doc-backed implementation of a fixed architecture plan -> $arch-step.
• Bet-and-learn optimization, one bet per iteration with worklog -> native goal mode.
• One-shot review of a diff or branch -> the host agent's normal review response. Use $codex-review-yolo only when the exact external yolo profile and its receipts are the requested benefit.
• Work that fits in a single orchestrator turn with no child roles.

Non-negotiables

• Truthful propagation is the single invariant. Every pass corresponds to honest evidence. Every fail is diagnosed to root cause before repair. No step passes with fabricated evidence; no repair prompt contains invented constraints.
• Pin raw_instructions verbatim with sha256. Any rewrite clears run state.
• Produce a Step Manifest and confirm it with the user before any step executes. Strictness tunes the gate's behavior; it never removes it.
• Apply ../_shared/agent-orchestration-policy.md at every dispatch. Apply $prompt-authoring to every actual populated first brief or materially reframed follow-up. Prefer clean native children for ordinary same-host workers and critics. Use an external session when a concrete provider, exact model/profile, durable lifecycle, worktree/process isolation, automation surface, structured receipt, or another real benefit is worth the extra process and integration cost. These examples are recognition aids, not an allowlist.
• Every worker step starts as a new clean child. Diagnostic and repair messages resume that exact child so the worker keeps its own role history.
• Every critic is a new clean, independent child. The critic observes and returns structured JSON conforming to StepVerdict; it never prescribes future worker actions and is never resumed.
• The critic observes; the orchestrator reasons; the worker executes. The critic never writes agent commands. The orchestrator never edits target-repo files or invents constraints. The worker never sees orchestrator-internal vocabulary.
• Native starting context is explicit. Codex dispatch always sets fork_turns to "none" for normal workers and critics, to a positive count only for deliberately bounded chat context, or to "all" only when the full conversation is genuinely load-bearing. Claude uses a clean named subagent by default; an explicit conversation fork means full inherited conversation, while a skill with context: fork is an isolated clean subagent context. Context is separate from permissions, capabilities, and worktree isolation.
• The orchestrator owns external topology and integration. Worker and critic prompts allow each role its own native sub-agents on its own host and forbid starting external agents.
• Every critic fail and every inspectable abstain enters the same diagnostic protocol. Stepwise holds read-only diagnostic conversation with the agents involved, walking upstream when evidence points there, until root cause is located or the diagnostic turn cap is exhausted.
• If diagnosis shows a step received bad input from an earlier step, repair the upstream worker that owns the bad input. Downstream steps start new clean replacements after upstream repair; resuming downstream children would compound broken context.
• Every hard boundary and operational instruction in a repair prompt carries an authority tag: user, manifest, or owner runbook. Critic evidence and a parent-confirmed diagnosis may travel only as non-binding, falsifiable context; they cannot create a worker command. Unsourced boundaries or instructions are invented and must be removed.
• Learnings are consulted with applicability tests and surfaced in Stepwise's reasoning. They never appear as worker-facing doctrine. Workers act on owner doctrine, not on Stepwise process memory.
• Permissions and worktree behavior are resolved independently from context. Use enforced read-only capability for critics when the host exposes it, retain the no-edit prompt contract, and compare target-repo state before and after critic work. External worker and critic subprocesses keep the existing dangerous / skip-permissions / no-sandbox convention; that convention does not describe native children.
• Native same-host roles need no invented runtime/model promise. For an external lane, base runtime and normally effort are supplied by the user or target doctrine for worker and critic independently. Models are also supplied except that an external Codex lane with no named model defaults to gpt-6-astra, and that Astra lane defaults an omitted effort to xhigh; Kimi defaults to kimi-code/k3 and an omitted effort to max. Natural Grok wording resolves to grok-4.6, while explicit legacy Grok ids stay exact. Ask once only for missing load-bearing external values.
• Optional execution preferences are interpreted after the Step Manifest is drafted. A phrase like "copywriting steps use Claude Fable 5.1" is a routing preference to resolve against real steps, not a built-in category.
• Orchestrator does not persistently load the target repo's contents into its own context. It points clean children at paths; children read source truth.
• Resolve profile, execution routing, and repair limits from the complete user prompt, then quote the source phrase in the announcement when a specific phrase drives the decision.
• Default broken-step repair limit is 5 operational repair bounces. A clear user bound such as "up to three times" can override it; otherwise keep 5. Strict/balanced/lenient never changes this number.
• Diagnostic read-only turns do not consume repair bounces. Operational repair prompts do.
• In the external lane, do not use stateless-only worker flags because workers must be resumable. External critics use the runtime's fresh/stateless command shape where supported. Kimi always persists a session, so a Kimi critic is a new clean session that is never resumed, not a stateless/no-persist process.
• Silent worker repair past the resolved repair limit, silent skipping, and silent advance on fail are forbidden. Apply stop_discipline when repair capacity is exhausted.
• Fabricated step completion, claim without artifact or transcript evidence, fails the step regardless of profile.
• Do not use /loop or ScheduleWakeup to bridge child work. Native roles use host wait/status primitives. The external lane uses foreground run_stepwise.py calls; if a subprocess genuinely outlasts the shell timeout, use supported background execution and its harness receipt.
• Long children commonly take 5+ minutes. For native roles, use host child state; for external xhigh or max turns, inspect live stream.log and process liveness every few minutes rather than polling every few seconds or treating a missing final file as a hang before exit.

First move

1. Capture the user's prompt verbatim. Compute sha256.
2. Read ../_shared/agent-orchestration-policy.md.
3. Read references/strictness-profiles.md. Interpret profile, forced checks, stop discipline, and broken-step repair limit.
4. Read references/model-and-effort.md and references/execution-routing.md. Resolve transport, clean starting context, and any external execution preferences. Ask one consolidated question only when a selected external lane lacks load-bearing values.
5. Resolve target_repo_path as an absolute path. Fail loud if unresolvable.
6. Read references/workflow-contract.md for the five-phase workflow.
7. Read references/diagnose-and-repair.md before executing any child loop.
8. Read references/unblocking.md before deciding a child failure is a user-facing blocker.
9. Announce the interpretation before Phase 2.

Workflow

Five phases. Detail lives in references/workflow-contract.md.

1. Intake & interpretation. Parse the prompt; set profile, forced checks, stop discipline, repair limit, execution defaults, and unresolved execution preferences. Announce.
2. Process grounding. Read the target repo's CLAUDE.md / AGENTS.md and the named process's SKILL.md. Draft steps, resolve execution preferences against those steps, and write manifest.json per references/manifest-schema.md.
3. Plan confirmation. Print manifest + interpretation. Gate per profile: strict always pauses, balanced pauses once, lenient prints and proceeds. Always include the resolved dispatch table.
4. Step execution loop. For each step: start a clean worker, start a clean observational critic, advance on pass, and on fail or inspectable abstain run the single diagnose-and-repair protocol. Repair at the root-cause worker, start downstream replacements clean after upstream repair, and halt when repair capacity or diagnostic clarity is exhausted.
5. Report. Per-step status table, run directory path, instructive critic observations, diagnostic records, learnings considered/written, and pending work if halted. No certification language.

Output expectations

• Run directory at .arch_skill/stepwise/runs/<run-id>/ in the orchestrator repo root.
• Per-step artifacts under steps/<n>/try-<k>/.
• Attempt origin metadata at steps/<n>/try-<k>/origin.json.
• Diagnostic records under steps/<n>/try-<k>/diagnostic/.
• Learnings under .arch_skill/stepwise/learnings/.
• report.md summarizing the run in plain English.
• Console summary with run path, status table, and any halted root cause.

Reference map

• references/workflow-contract.md - five phases with inputs, outputs, failure modes, and where judgment lives.
• references/diagnose-and-repair.md - single failure-handling protocol, diagnostic conversation, upstream traversal, repair authorship, budgets, and halt conditions.
• references/strictness-profiles.md - profile, forced checks, stop discipline, and repair-bounce policy.
• references/model-and-effort.md - how to elicit base worker/critic runtime, model, and effort from the user.
• references/execution-routing.md - how to resolve optional execution preferences against drafted steps without hardcoded task taxonomies.
• references/unblocking.md - how roles handle known blockers before asking or halting.
• references/manifest-schema.md - Step Manifest and StepDescriptor shape.
• references/critic-contract.md - observational StepVerdict schema and check definitions.
• references/step-verdict.schema.json - canonical StepVerdict JSON schema.
• references/critic-prompt.md - verbatim observation-only critic prompt.
• references/session-prompt-contracts.md - initial, diagnostic, and repair prompt contracts for worker sessions.
• references/session-resume.md - native context/continuation mapping plus the external Claude, Codex, Grok, and Kimi session adapter.
• references/run-directory-layout.md - on-disk artifact layout.
• references/learnings.md - persistent process-learning ledger.
• references/examples.md - worked examples of local diagnosis and upstream traversal.

The orchestration script

scripts/run_stepwise.py is deterministic run-state plumbing plus the explicit external-session adapter. Its transport-neutral subcommands create and inspect run artifacts; its launch subcommands spawn external processes, capture session ids, and validate critic verdicts. It does not choose transport, interpret the user's prompt, draft the manifest, decide root cause, or author repairs.

Subcommands:

• init-run - create the run directory and initial state.json.
• step-spawn - spawn a new clean external worker session; capture session id.
• step-resume - resume an existing worker session with an operational repair prompt.
• step-diagnose - resume an existing worker session read-only and write the diagnostic turn into diagnostic/ without consuming a repair bounce.
• critic-spawn - spawn a new clean external critic with a structured schema; parse and validate the observational verdict.
• latest-session - print latest try/session metadata for a step.
• upstream-for - print manifest-declared upstream artifacts and latest sessions for a step.
• report-scaffold - print or write a deterministic report.md scaffold.

Run python3 scripts/run_stepwise.py <subcommand> --help for flags.