| name | arch-epic |
| description | Orchestrate a goal too large for one `$arch-step` plan by decomposing it into approved ordered sub-plans, then running interactive handoffs, same-session `auto-plan` / `auto-implement`, or role-based planner/worker/critic execution. Same-host roles prefer clean native children from durable epic and sub-plan artifacts; the explicit external-harness lane remains available for deliberate provider, exact-model, lifecycle, isolation, automation, or receipt benefits. Use to break up and run a multi-plan epic, continue/resume an epic doc, plan every sub-plan before implementation, or implement an approved epic end to end. Not for a single architecture plan (`$arch-step`), one-pass mini plan (`$arch-mini-plan`), small feature (`$lilarch`), read-only status (`$arch-flow`), or foreign-repo step orchestration (`$stepwise`). |
| metadata | {"short-description":"Multi-plan orchestrator wrapping arch-step with decomposition approval, progressive North-Star gates, and a per-sub-plan scope-drift critic"} |
arch-epic
Wraps $arch-step to orchestrate goals too big for one canonical plan.
The skill takes a prose goal, proposes a plain-English decomposition
whose count follows proof gates rather than a preset range, gets user approval, and then drives
each sub-plan through arch-step's new → auto-plan → implement-loop
→ audit-implementation arc. After each sub-plan completes, a new clean
critic child inspects the shipped work for scope
drift against the approved North Star. If the critic finds missing authorized
work, post-freeze proposed expansion, or unauthorized built scope, the skill
halts. It may resume ordinary missing work, but it never enlarges scope from
the critic. A human decides whether to approve expansion and re-freeze, or keep
the boundary and require subtraction/redesign.
Otherwise it advances to the next sub-plan.
The normal lane is interactive and re-entrant: arch-epic invokes or observes
arch-step commands in the visible session one transition at a time.
The same-session automatic commands are explicit and opt-in:
auto-plan is a strict sequential driver over real $arch-step auto-plan <SUBPLAN_DOC_PATH> runs. It handles one approved sub-plan at a time, requires
the generated ArcStep receipt gate to report ready for that exact DOC_PATH, and
only then marks the sub-plan planned before moving to the next one.
auto-implement is a strict sequential driver over real $arch-step auto-implement <SUBPLAN_DOC_PATH> runs. It handles one planned sub-plan at a
time, lets ArcStep own the full implement/prove/audit loop, runs the epic
critic only after ArcStep's implementation audit says Verdict (code): COMPLETE, and marks the sub-plan complete only after that critic passes.
Role-based automatic execution is transport-aware. After decomposition
approval, arch-epic drives epic_planner, implementation_worker, and
critic roles from durable epic/sub-plan artifacts. Same-host roles normally
start as clean native children. The external-harness lane remains explicit and
opt-in when a different provider, load-bearing exact model/profile, durable or
detached lifecycle, worktree/process isolation, automation surface, structured
receipt, or another real benefit is worth the added process cost. In that lane
the existing script resolves and pins the external role table and owns only
invocation and receipt mechanics. Workers apply arch-step doctrine directly
from disk; they do not invoke nested auto-plan, implement-loop, or other
automatic continuation commands.
Planner and implementation worker roles are resumable regardless of transport.
If a new clean critic finds in-scope unfinished work, arch-epic resumes the
exact planner or implementation worker with the critic's observation and
artifact evidence. The critic never prescribes repair steps, and ordinary
repair does not start a separate repair-worker role.
Progressive lazy planning is the default for interactive and role-based
work: sub-plan N+1 is not planned until sub-plan N is complete. Same-session
auto-plan is the deliberate exception: it plans all approved sub-plans first,
but still plans exactly one sub-plan at a time and stops before implementation.
The user approves the decomposition up front, then approves each sub-plan's
North Star when it comes up in interactive mode. In role-based automatic mode,
new clean critics check North Star and Epic Requirement Coverage gates instead of
asking the user on every sub-plan.
Resume is the only mode — every $arch-epic invocation re-reads the
epic doc and sub-plan docs from disk and picks up where things left
off. "Continue my epic", "pick up where we left off", "keep going on
" all work.
The skill is a thoughtful wrapper — its job is to reduce user
orchestration burden. In interactive mode, user involvement is bounded
to the goal, decomposition, per-sub-plan North Star, and material
scope-preservation decisions. In role-based automatic mode, the user approves
the decomposition up front; an external harness also pins its role table.
Clean critics replace
per-sub-plan North-Star pauses unless a material ambiguity or scope
change requires the user.
When to use
- "This is too big for one arch-step plan. Help me break it into plans
and run them in order."
- "Orchestrate these sub-plans: X, Y, Z. Check each one before moving
to the next."
- "Continue my epic at
docs/EPIC_<slug>_<date>.md."
- "Keep going on the epic."
- "Pick up where we left off on ."
- "Automatically implement this approved epic end to end."
- "Auto-plan every sub-plan before we implement any of them."
- "Run
arch-epic auto-implement on this approved epic."
- "Run the epic automatically and ask me which models to use for the
planner, implementation worker, and critics."
When not to use
- Single architecture plan, including single-plan automatic planning through
implementation: use
$arch-step full-auto or $miniarch-step full-auto.
- One-pass mini plan that hands off to implement: use
$arch-mini-plan.
- 1–3 phase feature flow: use
$lilarch.
- Open-ended optimization with bet-and-learn iteration: use
$goal-loop.
- Read-only routing across arch artifacts: use
$arch-flow.
- Stepped orchestration in a foreign repo with a per-step critic: use
$stepwise.
- One-shot review of a diff, branch, or completion claim: use ordinary host
review. 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.
Non-negotiables
Must happen every run:
- Pin
raw_goal verbatim with sha256 in the epic doc. Any silent
rewrite clears the decomposition-approved flag.
- Produce a one-sentence-per-sub-plan decomposition and get user
approval before planning any sub-plan.
- Treat the raw human goal and approved decomposition as the epic baseline.
Decomposition approval does not authorize hidden infrastructure in later
sub-plans. Apply
../_shared/scope-and-convergence.md.
- Apply
../_shared/agent-orchestration-policy.md whenever a planner,
worker, or critic is dispatched, and apply $prompt-authoring to every
actual populated first brief or materially reframed follow-up. Prefer a clean
native child for ordinary same-host work. Use the explicit external harness
when a concrete provider, exact model/profile, durable or detached lifecycle,
worktree/process isolation, automation surface, structured receipt, or
another real benefit is worth the added process and integration cost. These
examples are recognition aids, not an allowlist.
- Native starting context is explicit. Codex dispatch always sets
fork_turns to "none" for clean planner/worker/critic roles, to a positive
count only for deliberately bounded chat context, or to "all" only when
the full conversation is genuinely required. 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 parent owns sequencing, any fanout, and final integration. Planner,
worker, and critic prompts forbid creating other model agents or invoking
delegation/consult skills unless the parent explicitly assigns a bounded
nested scope and budget.
- Each sub-plan inherits its approved epic boundary, records its own initial
minimal convergence closure during initial architecture, and freezes that
closure before implementation. After freeze, only explicit human approval
may add a path, obligation, sub-plan, mechanism, or proof category.
- Each sub-plan is its own full
$arch-step canonical DOC_PATH.
The epic doc does NOT contain plan internals (no Sections 0–10,
no call-site audit).
- Progressive planning: in interactive and role-based automatic modes, invoke
$arch-step new or planner harness work for sub-plan N+1 only after sub-plan
N is complete per the epic critic. In same-session auto-plan, assign or
create only the scaffold needed for the next sub-plan's canonical DOC_PATH,
then invoke or continue the real $arch-step auto-plan <SUBPLAN_DOC_PATH>
flow for that exact DOC_PATH. Creation, scaffold repair, copied sections, or
marker-looking text are never readiness proof.
- In same-session
auto-plan, update a sub-plan Status to planned only after
python3 skills/arch-step/scripts/arch_stage_gate.py ready --doc <SUBPLAN_DOC_PATH> exits 0 for that exact DOC_PATH. If the gate is not ready,
keep or set the sub-plan to planning and continue or report the exact
$arch-step auto-plan <SUBPLAN_DOC_PATH> command.
- Per-sub-plan North Star approval uses
$arch-step's existing
North-Star gate. arch-epic does not re-invent it — it just
stops when arch-step stops. In role-based automatic mode, this gate is
replaced by a new clean North-Star critic after the user-approved
decomposition is pinned. An external harness also pins its role table. In
same-session auto-plan, the
approved decomposition can stand in for per-sub-plan user approval only when
the sub-plan North Star is a direct, unambiguous expansion of the approved
epic scope; otherwise stop and ask.
- Per-sub-plan implementation runs through
$arch-step implement-loop in interactive mode and real $arch-step auto-implement <SUBPLAN_DOC_PATH> in same-session auto-implement.
Same-session auto-implement is not complete after one invocation; it keeps
the selected sub-plan at implementing and continues the ArcStep
implement/prove/audit loop until arch_skill:block:implementation_audit says
Verdict (code): COMPLETE or a true blocker stops progress. In
role-based automatic mode, implementation workers execute the approved
sub-plan directly from arch-step doctrine and the sub-plan doc; the top-level
orchestrator still does not edit target code itself.
- Epic critic runs once per sub-plan at sub-plan completion and returns
structured JSON
EpicVerdict. It is always a new clean child and is never
resumed. Prefer native dispatch; the external harness remains available for
deliberate external benefits.
- Permissions and worktree posture are resolved independently from starting
context. Use enforced read-only capability for critics when available,
retain the no-edit prompt contract, and compare repository state before and
after critic work. External harness processes keep the existing dangerous /
skip-permissions / no-sandbox convention; that convention does not describe
native children.
- Native role execution needs no invented runtime/model promise. For the
explicit external harness, the user supplies role execution for
epic_planner, implementation_worker, and critic; ask once for missing
load-bearing values. An omitted model on an external Codex role defaults to
gpt-5.6-sol, and an omitted effort on that Sol role defaults to ultra.
An external Kimi role defaults to kimi-code/k3 and the model-default max
effort; other runtimes, Codex models, and efforts never silently default.
Natural Grok wording resolves to grok-4.5, while explicitly named legacy
Grok ids remain exact. Existing external
policies with legacy repair_worker values may load, but ordinary critic
failures resume the exact original planner or implementation worker.
Same-session auto-plan needs no role table. Same-session
auto-implement uses the same transport-selected completion-critic policy
as interactive mode.
- Resume is re-entrant: any invocation against an existing epic doc
re-reads on-disk state and continues. No dedicated
resume
command.
Must never happen:
arch-epic editing the target repo's code directly. Sub-plans do that via
arch-step's implement-loop in interactive mode or implementation workers in
role-based automatic mode.- Scope reduction. The epic scope is the epic scope. If the critic
sees a dropped, narrowed, or silently removed requirement from the raw
goal, approved Decomposition, North Star, Epic Requirement Coverage,
Section 7, acceptance criteria, or verification obligations, the
sub-plan fails. A requirement assigned to a named later sub-plan is
preserved scope, not a failure for the current sub-plan. Agent-written
Decision Log entries are evidence, not approval to reduce scope.
- Scope expansion by an agent, critic, review, or Decision Log. The same
symmetry applies to additions: initial sub-plan architecture may record the
smallest evidenced same-contract closure before freeze; any later addition
or new sub-plan needs explicit human approval. A Decision Log entry proves a
change was recorded, not that it was authorized.
- Auto-acting on materially-different-path detections without user approval.
Material scope discoveries always halt. The human may approve expansion via
extend_current or new_sub_plan, or keep the frozen boundary and require
subtraction/redesign. No critic recommendation is self-authorizing.
- Letting critics author repair steps. Critics report verdict,
failed checks, evidence, and scope discoveries only. The parent
routes the result, and the resumed planner or implementation worker
owns the reasoning for the next attempt.
- Starting a separate repair worker for ordinary in-scope critic failures.
Exact-role resume is the default repair path; a new clean role child is only
for unrecoverable handle loss, invalidated inputs, or explicit user override.
- Parallel planning or parallel implementation. Same-session
auto-plan may
plan every sub-plan before implementation, but it still handles one sub-plan
at a time in decomposition order. Implementation always runs one sub-plan at
a time and advances only after the epic critic passes.
- Marking a same-session
auto-plan sub-plan planned from a consistency
marker, plausible Section 3-7 content, prior stored status, or ArcEpic-authored
setup. The ArcStep generated receipt gate is the proof.
- Same-session
auto-implement starting while any non-complete sub-plan is not
planned. Plan all sub-plans first with auto-plan.
- Marking a same-session
auto-implement sub-plan complete from stored
Status, worklog optimism, local proof, one $arch-step auto-implement
invocation, or ArcStep audit alone. ArcStep audit COMPLETE must come first,
then the epic critic must return pass.
- Running the epic critic while the sub-plan implementation audit is missing,
NOT COMPLETE, reopened, or otherwise not clean. Continue or report
$arch-step auto-implement <SUBPLAN_DOC_PATH> for that sub-plan instead.
- Two-second child polling. The external-harness lane defaults to 180-second waits
while waiting for external processes unless the user explicitly pins a
different cadence in the role policy.
- Calling a slow planner or worker "hung" just because it has no final
artifact after a few minutes. Native host state or external stream receipts
may show progress; external children often run for 5+ minutes;
broad
xhigh or max planner/worker runs can reasonably take 20-40
minutes. In the external lane use process state plus events.jsonl, stderr.log,
stream.log, heartbeat.json, and monitor.json; treat recent
thinking/tool/output stream activity as progress.
- Terminating an external child before the long-run floors expire unless there
is clear failure evidence. External defaults are: poll every 180s,
call a run
quiet only after 900s without stream activity, and call
it needs_attention only after 1800s without stream activity or after
the pinned max runtime.
- Passing raw model shorthand to external subprocesses. Resolve it first using
shared model-resolution doctrine; preserve exact family/version or
ask for the runnable ID.
- Heuristic keyword mapping for decomposition. Interpretation is
prose reasoning, taught by
references/decomposition-principles.md.
- A second "resume" command. The user types what they type; the
skill figures it out from the epic doc + sub-plan docs.
First move
- Capture the user's goal verbatim. Compute
sha256.
- Resolve or propose the epic doc path
(
docs/EPIC_<TITLE>_<YYYY-MM-DD>.md).
- Read
../_shared/agent-orchestration-policy.md and
references/model-and-effort.md. Prefer clean native same-host roles. Ask
one consolidated question only when an explicit external harness or another
selected external lane lacks load-bearing execution values. Same-session
auto-plan runs no critic during planning.
- Read
references/decomposition-principles.md. Draft the
Decomposition (one-sentence descriptions, assertion-style gates,
dependency-then-risk ordering, and count chosen from real proof
boundaries rather than a target range).
- Read
../_shared/scope-and-convergence.md.
- Read
references/epic-doc-contract.md. Write the epic doc.
- Surface the Decomposition and ask the user to approve or adjust.
Modes (re-entrant; one per turn)
Detail per mode lives in references/workflow-contract.md.
start — epic doc does not yet exist. Propose the path, resolve the
intended lane without inventing native model settings, ask only for missing
external values when an external lane was selected, draft the Decomposition,
and surface it for approval.approve-decomposition — epic doc has
sub_plans_approved: false. Apply user adjustments, flip flag,
set status: active.run — main orchestration pass. Routes per
references/arch-step-integration.md to the next arch-step
command for the first non-complete sub-plan or runs the critic.resume-scope-change — epic is halted after a critic flagged a
scope issue; a human has replied. Apply the explicit choice: approve and
re-freeze an extend_current/new_sub_plan expansion, or keep scope and
route subtraction/redesign. Log the human decision and resume.summary — user asked a status question. Render a table of
sub-plan statuses and the most recent log entries. No state
changes.auto-plan — same-session planning driver after decomposition
approval. Sets up the next sub-plan DOC_PATH, drives real $arch-step auto-plan <SUBPLAN_DOC_PATH> for that exact doc, runs the ArcStep readiness
gate, marks it planned only when the gate exits 0, then repeats for the
next sub-plan in decomposition order. It stops before implementation.auto-implement — same-session implementation driver. Requires every
non-complete sub-plan to be planned, then runs each in order through real
$arch-step auto-implement <SUBPLAN_DOC_PATH> until ArcStep audit is
COMPLETE, runs the epic critic, and marks the sub-plan complete only after
critic pass.auto-run — role-based automatic execution after decomposition
approval. Prefer clean native planner/worker/critic children from durable
artifacts, resume the exact planner or worker for repair, and start every
critic clean. If the external harness was deliberately selected, resolve
and pin its role table, initialize its auto run directory, and use the
script only for external invocation and receipts.
Output expectations
- Epic doc at the user-named (or proposed) path.
- Per-sub-plan canonical arch-step DOC_PATHs under
docs/epic/<EPIC_SLUG_WITH_DATE>/PHASE_<NN>_<SUBPLAN_SLUG>_<YYYY-MM-DD>.md,
owned by arch-step.
- Same-session
auto-plan leaves non-complete sub-plans at Status planned
only when their exact DOC_PATH passes the arch-step generated receipt gate.
- Native role dispatches record their exact child handles and return evidence
as compact Orchestration Log pointers. External epic critic artifacts live under
<orchestrator repo root>/.arch_skill/arch-epic/critics/<slug>/run-<ts>/
including the EpicVerdict JSON, the exact invocation.sh, and the
subprocess stream log.
- External-harness automatic artifacts live under
<orchestrator repo root>/.arch_skill/arch-epic/auto/<epic-slug>/run-<ts>/
including state.json, execution_policy.json, worker prompts,
worker session IDs, latest worker-attempt pointers, critic verdicts, child events.jsonl,
stderr.log, stream.log, heartbeat.json, monitor.json, and
report.md.
- Orchestration Log and Decision Log append-only in the epic doc.
- Console summary with the epic doc path, the per-sub-plan status
table, and the current active sub-plan's next action.
Reference map
references/workflow-contract.md — re-entrant modes with inputs,
outputs, failure modes, judgment-vs-determinism split.references/epic-doc-contract.md — epic doc shape, frontmatter,
section structure, mutation rules, validation on load.references/decomposition-principles.md — when to split a goal
into sub-plans. Prose reasoning with worked examples; no keyword
tables.../_shared/depth-first-planning.md — destination map, first
working slice, expansion map, proof gates, and scope-cut distinction
shared with arch-step and miniarch-step.references/arch-step-integration.md — sub-plan Status →
arch-step command mapping. What the skill invokes vs. what the
user or native goal-mode continuation does.references/scope-change-discipline.md — approved scope lock,
materially-different path vs noise, and preservation-only scope
decisions.references/critic-contract.md — EpicVerdict JSON schema and
scope-drift / requirement-coverage checks.references/critic-prompt.md — verbatim critic prompt body with
placeholders.references/auto-harness-prompts.md — transport-neutral role prompt
contracts for planner, implementation, exact-role continuation, and clean
critics.references/epic-verdict-schema.json — JSON schema file used by
Codex --output-schema, inlined into Claude --json-schema, and appended
to Grok and Kimi critic prompts before post-validation.references/model-and-effort.md — native-first role dispatch plus external
model shorthand resolution, exact-version preservation, and ask-once
discipline.references/resume-semantics.md — how the skill re-derives state
each turn from the epic doc + sub-plan docs.references/examples.md — worked examples: happy path,
scope-change insertion, harmless observations ignored.
The external harness adapter
scripts/run_arch_epic.py is deterministic external-lane plumbing. After the
orchestrator deliberately selects the external harness, it resolves the
external role policy, creates run directories, spawns and resumes workers,
spawns structured critics, and writes artifacts. It does NOT choose transport,
interpret decomposition, draft the epic doc, decide verdicts, or route
sub-plan states — those live in the orchestrator's prose reasoning.
python3 scripts/run_arch_epic.py critic-spawn \
--epic-doc <path> \
--sub-plan-name "<name>" \
--sub-plan-doc-path <path> \
--prompt-file <path> \
--schema-file references/epic-verdict-schema.json \
--runtime claude|codex|grok|kimi \
--model <model> \
--effort <effort> \
[--codex-profile <profile>] \
[--orchestrator-root <dir>]
External-harness examples:
python3 scripts/run_arch_epic.py resolve-execution \
--policy-file /tmp/arch-epic-auto-policy.json
python3 scripts/run_arch_epic.py auto-init \
--epic-doc docs/EPIC_BIG_GOAL_2026-04-26.md \
--policy-file /tmp/arch-epic-auto-policy.json
python3 scripts/run_arch_epic.py worker-spawn \
--run-dir .arch_skill/arch-epic/auto/big-goal/run-2026-04-26T00-00-00Z \
--target-repo . \
--role implementation_worker \
--sub-plan-name "Build the core service" \
--prompt-file /tmp/worker.prompt.md \
--run-mode auto
python3 scripts/run_arch_epic.py worker-resume \
--run-dir .arch_skill/arch-epic/auto/big-goal/run-2026-04-26T00-00-00Z \
--target-repo . \
--role implementation_worker \
--sub-plan-name "Build the core service" \
--prompt-file /tmp/continue.prompt.md \
--session-id <session-id-from-session_id.txt> \
--try-k 2 \
--run-mode auto
python3 scripts/run_arch_epic.py child-status \
--try-dir <printed-child-run-dir> \
--json
python3 scripts/run_arch_epic.py child-tail \
--try-dir <printed-child-run-dir> \
--lines 80
python3 scripts/run_arch_epic.py child-finalize \
--try-dir <printed-child-run-dir>
Foreground child runs print the session ID or verdict path after completion.
Detached child runs print the child run directory immediately; use
child-status, child-tail, and child-finalize to monitor and finalize
them. Writes:
<orch-root>/.arch_skill/arch-epic/critics/<slug>/run-<ts>/prompt.md<orch-root>/.arch_skill/arch-epic/critics/<slug>/run-<ts>/invocation.sh<orch-root>/.arch_skill/arch-epic/critics/<slug>/run-<ts>/stdout.final.json<orch-root>/.arch_skill/arch-epic/critics/<slug>/run-<ts>/events.jsonl<orch-root>/.arch_skill/arch-epic/critics/<slug>/run-<ts>/stderr.log<orch-root>/.arch_skill/arch-epic/critics/<slug>/run-<ts>/stream.log<orch-root>/.arch_skill/arch-epic/critics/<slug>/run-<ts>/heartbeat.json<orch-root>/.arch_skill/arch-epic/critics/<slug>/run-<ts>/monitor.json<orch-root>/.arch_skill/arch-epic/critics/<slug>/run-<ts>/verdict.json<orch-root>/.arch_skill/arch-epic/critics/<slug>/run-<ts>/start_ts / end_ts / exit_code
