Miniarch Step

Miniarch Step

Use this workflow only after explicit selection as $miniarch-step or a binding task instruction requiring it.

The primary object is one canonical full-arch plan doc. miniarch-step keeps the same artifact discipline and full-work posture as arch-step, but with a trimmed public command surface. It is not a lower-effort workflow: finish the requested outcome completely, but do not confuse completeness with more machinery.

When to use

• The task still benefits from canonical architecture grounding, phased execution, and one governing full-arch doc.
• The user wants phased planning, implementation, and audit against one full-arch doc.
• The user wants the trimmed command surface rather than arch-step's broader helper surface.
• The user wants native goal-mode auto flow rather than one-pass planning only.
• The ask is command-shaped: new, reformat, research, deep-dive, phase-plan, auto-plan, implement, implement-loop, auto-implement, full-auto, audit-implementation, status, or advance.
• The user wants one canonical trimmed full-arch plan driven as far as possible through planning and implementation with native goal-mode continuation.

When not to use

• The user wants a read-only router or "what's next?" answer. Use arch-flow.
• The user wants one-pass planning only. Use arch-mini-plan.
• The task is a tiny 1-3 phase feature flow. Use lilarch.
• The task is ambiguity-heavy, migration-heavy, broad, or likely to need external research or extra hardening helpers. Use arch-step.
• The remaining job is docs cleanup or consolidation after code work is clean. Use arch-docs.
• The problem is primarily a bug or open-ended loop. Use bugs-flow, native goal mode, or north-star-investigation.

Non-negotiables

• DOC_PATH is the primary state. Commands are subordinate to the artifact.
• Every invocation must check both structure and quality before doing command-local work.
• No command may leave the doc less canonical, less honest, or more contradictory than it found it.
• Present-but-weak sections are not done.
• A plan is not ready, complete, or implementation-ready while any unresolved decision remains about requested behavior, adjacent surfaces that must stay in sync, compatibility posture, architecture, canonical owner path, required deletes, fallback policy, acceptance evidence, or implementation scope.
• Section 0 must contain the binding Scope and Simplicity Contract from references/artifact-contract.md: human authorization, smallest sufficient solution, initial convergence closure or none, scope sign-off, enough proof, do-not-build boundary, and accepted residual risk.
• Treat overbuilding as a known default failure mode. Agents often confuse thoroughness with quality and keep adding abstractions, harnesses, edge cases, and proof after the real fix is already sufficient. Assume that bias is active; before adding machinery, try to reuse, delete, or simplify.
• Match the size of the solution and its proof to the demonstrated failure and blast radius. A systemic fix belongs at the narrowest shared boundary that eliminates the failure class; "systemic" does not mean "build a framework around the incident."
• Every Section 7 item must directly serve the human outcome, the pre-approval minimal convergence closure, or enough proof. Remove items that serve none before calling the plan implementation-ready.
• Initial architecture may add only the smallest evidenced same-contract convergence closure before implementation readiness. The approved contract outranks later plan expansion. A later planner, worker, review, audit, or Decision Log entry cannot authorize new work; only explicit human approval recorded as Scope expansion (human-approved) can widen it.
• During implementation, adding an unapproved adjacent path, framework, harness, verifier, abstraction, command, dependency, operational surface, or test category is a hard stop. Ask for human approval before changing plan or code. Apply ../_shared/scope-and-convergence.md.
• Correctness and approved intent outrank convenience or scope trimming.
• The agent has no authority to cut requested behavior, acceptance criteria, or required implementation work unless the user or the governing plan already marked that item out of scope.
• Cutting, downgrading, deferring, or "simplifying away" approved behavior, acceptance criteria, or phase obligations is a hard stop. Surface to the user with what you want to cut, why, what Section 0 / TL;DR / Section 7 say about it, and the exact approval you need. Do not proceed until the user explicitly approves; record the approved cut in the Decision Log using the Scope cut (user-approved) shape.
• miniarch-step is a trimmed command surface, not a lower-effort workflow. Full effort means a complete result at the simplest sufficient architecture, not maximum code, testing, or ceremony.
• Section 7 uses the depth-first doctrine in ../_shared/depth-first-planning.md: protect the full destination map, prove the first real working slice through the highest-risk seam, then expand along named axes.
• Phase boundaries are proof boundaries. Phase count is an outcome of dependency edges, proof gates, reversibility or migration boundaries, and user-review boundaries; split only when a phase blends separately provable work.
• A phase is not complete while any checklist item or exit criterion in that phase remains unmet.
• For modern Section 7 docs, Work is explanatory only. Every required phase obligation must live in Checklist (must all be done) or Exit criteria (all required), and fresh audit must validate both before a phase can stay complete.
• During implement and implement-loop, the approved plan stays authoritative for requirements, scope, acceptance criteria, and phase obligations. Execution may record progress truth, but it may not rewrite the plan to make unfinished work disappear.
• During implement and implement-loop, execution scope is the current approved ordered implementation frontier: the earliest incomplete or reopened phase plus later phases whose prerequisites and proof gates are reachable in this implementation arc. Named later expansion is not current missing work until its proof gate is due; silent removal from the destination map is still a scope cut.
• Credible proof supports continued implementation. It does not justify stopping after one local fix, one phase, or one convenient subset while later approved phases are still reachable.
• If the doc is materially non-canonical, repair only the safe owned portion or route to reformat.
• Keep one planning source of truth. Do not create sidecar plan docs or competing checklists.
• All planning commands are docs-only. Only implement and implement-loop may change code; full-auto may reach code changes only by routing to implement-loop.
• When planning benefits from child planners or implement-loop benefits from an independent auditor, prefer new clean same-host native children when the active host can satisfy the role's capabilities. In Codex, set fork_turns: "none"; in Claude Code, use clean named or custom subagents rather than a conversation fork.
• Planner and auditor children are analysis-only: use a read-only capability when the host confirms one, also give explicit no-edit/no-write guidance, and let the parent verify repo state, synthesize returns, and own all DOC_PATH or audit-block writes. Children may use their own native sub-agents on their own host and may not start external agents; the parent's fanout stays proportional to independent work, host slots, collision risk, and parent integration capacity.
• For miniarch planner and auditor roles, prefer gpt-5.4-mini with xhigh reasoning only when the active native tool schema can select and confirm both. Otherwise use the inherited native capability and do not claim the child used an unconfirmed model or effort. If exact identity is genuinely load-bearing, an external exact-model lane remains available; the dispatch must explain the concrete quality, provider, profile, lifecycle, isolation, automation, or receipt benefit that makes its added process and integration cost worthwhile.
• Distinguish the human-authorized outcome from the initial minimal convergence closure, and sign off both before implementation.
• Search for the canonical existing path before designing a new one. Reuse it, refactor it as much as required to fully own the change, or justify why it cannot own the change.
• During initial planning, convergence may include the smallest evidenced touched-file or adopter set needed to eliminate a directly competing owner. After sign-off, a newly found path requires a human decision.
• Any refactor, shared-path extraction, or consolidation must preserve existing behavior and name a credible verification signal before it is considered done.
• Use repo evidence first. Ask only for true product, UX, external-constraint, access, or doc-path gaps.
• Before asking the user any plan-shaping question, consult approved intent on the plan doc: Section 0 (North Star), TL;DR, and the Section 7 phase frontier. Only ask when intent plus repo evidence genuinely leave two credible branches. Record intent-derived resolutions in the Decision Log using the Intent-derived shape.
• If repo evidence cannot settle a plan-shaping decision, ask the user instead of guessing, defaulting, or parking the choice as a pseudo-complete plan.
• Before hardening target architecture or Section 7, inspect adjacent surfaces tied to the exact changed contract, source of truth, or migration boundary. Put directly competing paths in the pre-approval closure, sequence them inside the approved destination map, exclude merely similar neighbors, or ask the exact blocker question. Pattern parity alone is not scope authority.
• Compatibility posture is a first-class plan decision separate from fallback_policy.
• When the changed behavior is agent- or LLM-driven, inspect current prompt surfaces, runtime or agent configuration, native model capabilities, and existing tool/file/context exposure before designing.
• For agent-backed systems, prefer prompt engineering, grounding/context shaping, and better use of native capabilities before custom harnesses, wrappers, parsers, OCR stacks, fuzzy matchers, or deterministic sidecars.
• If the real lever is prompt repair, say so plainly and recommend prompt-authoring instead of inventing deterministic scaffolding.
• Default to fail-loud boundaries, hard cutover, and explicit deletes. Runtime shims are forbidden unless the plan explicitly approves them.
• auto-plan is one command. In native goal mode, keep advancing the real planning sequence until the artifact is decision-complete or a true blocker stops it. Outside goal mode, run one bounded pass and name the exact next command.
• implement-loop is one command. In native goal mode, keep running implementation-frontier work and fresh audit-implementation until the audit is clean or a true blocker stops it. Outside goal mode, run one bounded pass and name the exact next command.
• full-auto is a re-entrant doctrine mode that reads artifact truth and routes to the next existing command. It must plan before implementation and must not bypass readiness gates.
• Git is the history for retired live truth surfaces. Delete dead competing code paths, stale live docs, and stale comments instead of keeping them for archaeology.
• Broader docs audit, consolidation, and final plan/worklog retirement after a clean code audit belong to arch-docs, not to hidden miniarch-step commands.
• status is compact, read-only, and grounded in the actual artifact.
• advance owns the longer checklist surface and optional one-step execution.
• No-progress rule. After two consecutive passes with no real change (no repo file edit, no plan/doc edit, no new evidence a fresh audit has not seen), stop with the exact blocker instead of firing another identical pass.
• No invented budgets. Do not call authorized work blocked because it feels expensive. This does not authorize violating the approved Scope and Simplicity Contract or adding unapproved machinery. In goal mode, keep moving until the objective is complete or a real blocker meets the native goal-mode stop rule.
• Exhaust the frontier before auditing. Do not hand to audit after one local fix when later approved-contract-compliant phases are reachable. Finish that frontier or record the real blocker plainly.
• Respect the tree state the user gave you. Do not stash changes, create new branches, split the work across multiple PRs, or rewrite history. Commit hygiene, branch strategy, and PR shape are the user's decisions.
• Parallel-agent edits are a pause signal, not a revert signal. If the working tree contains edits this pass did not make (foreign file, unexpected compiler error, unfamiliar commit), pause briefly to let the other agent land its fix. Do not revert. Escalate to the user only after two pause-retry cycles fail.

First move

1. Read references/artifact-contract.md.
2. Read references/shared-doctrine.md.
3. Before creating or resuming another agent, read ../_shared/agent-orchestration-policy.md.
4. Resolve the requested command and DOC_PATH when the command needs an existing doc.
5. If the ask is generic mini full-arch execution rather than a named command:
   • no doc yet: treat the first move as new
   • doc exists or the user gave a doc path: treat the first move as advance
6. Inspect the current doc against:
   • required frontmatter
   • # TL;DR
   • planning_passes
   • exact canonical headings
   • command-owned blocks
   • obvious contradictions across TL;DR, Section 0, target architecture, call-site audit, phase plan, verification, rollout, and decision log
   • canonical-path ownership and behavior-preservation claims
   • a concrete Scope and Simplicity Contract and whether planned work stays inside it
7. Read references/section-quality.md for the sections this command depends on.
8. Read the matching command reference. If the command is full-auto, read references/full-auto.md.
9. If the command is advance, read references/advance.md, choose the one move that most improves artifact integrity or flow progress, and stop unless RUN=1 explicitly asks for that one step to execute.

Workflow

Public command surface

• new
• reformat
• research
• deep-dive
• phase-plan
• auto-plan
• implement
• implement-loop
• auto-implement
• full-auto
• audit-implementation
• status
• advance

Top-level model

miniarch-step reasons about one canonical full-arch artifact with this exact shape:

• required frontmatter
• # TL;DR
• planning_passes
• # 0) through # 10) with exact canonical headings and subsection structure
• optional helper blocks folded into the same plan doc only when they belong to the mini surface
• WORKLOG_PATH once implementation begins

The finished artifact is one internally consistent, decision-complete plan that says the same thing about outcome, requested behavior scope, architectural convergence scope, architecture, verification, rollout, and drift history from multiple angles.

advance selection rule

Choose exactly one next command using this precedence:

1. No plan doc yet: run new.
2. Existing doc is not canonical enough to trust: run reformat.
3. North Star is still draft or too weak to support planning: stop for confirmation or repair the artifact with reformat.
4. After North Star confirmation, stop and wait for the user's explicit next command; do not auto-advance into research or any later stage.
5. Earliest required structure or owned block is missing: run the command that repairs it.
6. Required structure exists but the next critical sections are still weak or still contain unresolved decisions: run the command that strengthens them or stop and ask the exact blocker question.
7. Otherwise follow the core arc:
   • new or reformat
   • North Star confirmation
   • research
   • deep-dive
   • phase-plan
   • implement
   • audit-implementation
8. If the code audit is clean and the feature still needs docs cleanup, hand off to arch-docs.

Do not auto-run more than one command.

Explicit automatic commands

These stay explicit unless the user directly asks for them:

• auto-plan
• implement-loop
• auto-implement

full-auto is not in this list because it routes over the existing commands.

Re-entrant full-auto mode

full-auto is an explicit mode for one canonical mini/full-arch plan. It does not add a new controller, state file, runner, hook behavior, script, or heuristic layer. It reads DOC_PATH, WORKLOG_PATH, and the implementation audit block, then invokes the next existing command only when the artifact is ready for that command.

Read references/full-auto.md before using this mode. The main rule is simple: plan first with auto-plan, prove implementation readiness with the normal miniarch readiness inventory, then implement with implement-loop. If the North Star is still draft, a decision gap remains, Section 7 is not execution-grade, stop honestly instead of chaining.

auto-plan

The automatic planning command for this trimmed full-arch surface. DOC_PATH is the planning ledger.

Workflow:

1. Read doc truth and North Star status.
2. Run the first incomplete planning stage in order: research, deep-dive, then phase-plan.
3. In native goal mode, continue taking the next incomplete stage until phase-plan clears decision gaps and the doc is implementation-ready, or until a true blocker stops the run.
4. Outside native goal mode, run one bounded stage and end with the exact next command.

miniarch-step-specific rules:

• User-facing invocation: $miniarch-step auto-plan or $miniarch-step auto-plan <DOC_PATH>.
• Rerunning auto-plan on a partially complete doc is legal; resume from the first incomplete stage already visible in DOC_PATH.
• Prefer the current session's canonical mini/full-arch doc when DOC_PATH is omitted.
• Do not claim the planning arc is complete or emit the implement-loop handoff while any decision gaps remain.

implement-loop / auto-implement

implement-loop is an implementation-frontier delivery command; auto-implement is an exact user-facing synonym resolving to the same behavior.

Workflow:

1. Read the approved plan and current audit/worklog truth.
2. Implement the current approved ordered implementation frontier.
3. Run audit-implementation after the implementation pass.
4. If audit is clean, hand off to $arch-docs.
5. If audit is not clean and work remains reachable, continue from the reopened or incomplete phase. In native goal mode, repeat until clean or truly blocked. Outside native goal mode, report the next exact implementation command.

miniarch-step-specific rules:

• User-facing invocation: $miniarch-step implement-loop <DOC_PATH> or $miniarch-step auto-implement <DOC_PATH>.
• Implementation covers the current approved ordered implementation frontier in order: the earliest incomplete or reopened phase plus later phases whose prerequisites and proof gates are reachable in this implementation arc.
• The implementation pass may ship code and sync plan/worklog truth, but the audit must be a real audit-implementation pass against current repo state before the loop can finish clean.

Output expectations

• Keep console output high-signal and natural.
• Start with a one-line North Star reminder.
• Then give the punchline plainly.
• Put exhaustive detail in DOC_PATH or WORKLOG_PATH, not in console output.
• For generic mini full-arch asks that did not name a command, say which command you resolved to and why.
• status should emit:
  • one artifact line
  • one line per core stage
  • one best-next-move line
• advance should emit:
  • the full ordered checklist with evidence notes
  • the exact next move, even when that handoff is arch-docs
  • optional one-step execution only when RUN=1

Reference map

• references/artifact-contract.md - canonical mini full-arch artifact, exact section shape, frontmatter, block inventory, and worklog contract
• references/shared-doctrine.md - cross-cutting doctrine: question policy, alignment checks, evidence, SSOT, scope defaults, and consistency repair
• ../_shared/agent-orchestration-policy.md - transport, clean context, continuation, isolation, topology, and return evidence for optional planners and independent auditors
• ../_shared/scope-and-convergence.md - human scope authority, initial planning convergence, scope sign-off, finding dispositions, and scope-cycling prohibition
• ../_shared/depth-first-planning.md - destination map, first working slice, expansion map, proof gates, scope-cut distinction, and failure-mode recognition tests
• references/section-quality.md - purpose, strong/weak bar, trust rules, and failure modes for each section and supporting block
• references/arch-new.md - bootstrap the canonical artifact and stop for North Star confirmation
• references/arch-reformat.md - convert an existing doc into the canonical artifact without losing meaning
• references/arch-research.md - research grounding contract
• references/arch-deep-dive.md - current architecture, target architecture, call-site audit, and single-pass planning rules
• references/arch-phase-plan.md - authoritative phase-plan contract
• references/arch-auto-plan.md - automatic planning over research, one deep-dive pass, and phase-plan
• references/full-auto.md - doctrine-only re-entrant mode over auto-plan and implement-loop
• references/arch-implement.md - implementation, worklog, and completion discipline
• references/arch-implement-loop.md - implementation-frontier implement/audit loop and proof contract
• references/arch-audit-implementation.md - code-completeness audit and phase reopening
• references/status.md - compact artifact-first status rules
• references/advance.md - full checklist, next-command selection, and optional one-step execution