hex-execute
Multi-agent execution orchestrator — implements an approved hex-plan artifact (or a free-text task) as parallel pipelines of serial steps cut along contracts, merges them onto a feature branch, runs one integration gate concurrent with one review, and hands to /hex-finalize. Use to execute, implement, build, or run an approved plan, resume an interrupted execution, or turn a design into tested, reviewed, committed code.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 15
- Forks
- 1
01 前言 Front Matter
- name
- hex-execute
- license
- Apache-2.0
- metadata
- { "summary": "Swarm execution — plan artifact to reviewed, gated branch", "keywords": "execution,swarm,multi-agent,tdd,implementation,pipelines,worktrees", "repository": "https://github.com/michael-herwig/arcana" }
- description
- Multi-agent execution orchestrator — implements an approved hex-plan artifact (or a free-text task) as parallel pipelines of serial steps cut along contracts, merges them onto a feature branch, runs one integration gate concurrent with one review, and hands to /hex-finalize. Use to execute, implement, build, or run an approved plan, resume an interrupted execution, or turn a design into tested, reviewed, committed code.
02 资源文件 1
- 参考文档federation.md10.2 KB
03 SKILL.md 正文
hex-execute — Execution Orchestrator
Thin dispatcher. A plan is a few pipelines cut along contracts; a pipeline
is a chain of steps in one worktree. This file resolves the target, runs
the contract wave, dispatches steps, merges, runs the integration gate
concurrent with the review call, fixes, and hands to /hex-finalize.
Vocabulary lives in hex-core and is linked here, never copied.
Shared contracts:
protocol.md ·
workers.md ·
models.md ·
memory.md ·
worktree.md ·
verify.md.
If hex-core is not installed: grim add ghcr.io/michael-herwig/arcana/hex-core:latest.
Argument syntax
/hex-execute [target] [--dry-run]
- target (optional): a plan artifact path; a free-text task (no plan
artifact, one pipeline); or omitted — resolve the active-plan pointer from
hex.md › Memory(memory.md). --dry-run— print the announce block and stop; no worker launches.
The run
Counts are fixed (DESIGN.md): two full gates (integration,
release), ≤ 3 review calls, workers never wait, escalation by the
orchestrator only.
1. Resolve memory and target
Locate .agents/memory/hex.md searching upward; a missing file is normal
(memory.md) —
use shipped defaults and note that /hex-init can create one. When present,
read it whole: Pointers (verification, hub/generated files, fresh-build
switch, worktree location), Preferences (model-class agent definitions,
limits), Memory (active-plan pointer). A Federation lead: bullet means this
repo is a satellite: halt per
memory.md.
Resolve the target: explicit plan path (read it whole), active-plan pointer
(none recorded: stop and ask), or free text (scope contracts inline).
A plan carrying a Repo column: follow federation.md before
anything else is written.
Plan State decides entry: plan-approved is normal. executing is a prior
run — resume from the pipeline table's Status column
(pending | active | merged | failed), resetting an unfinished pipeline to its
last committed step; branches and worktrees are evidence only, the Implementation
Steps checkboxes are the finer progress, and a resuming run never reads the
per-run scratch root. landing is a finalize-only re-entry
(federation.md). review or
done: stop and report; the human decides whether to re-execute.
2. Announce
No approval gate — print the resolved config and proceed (the user can abort):
hex-execute
Target: .agents/plans/plan_cache.md
Pipelines: 3 (A, B, C) — contract wave first, then A ∥ B ∥ C
Jobs: 3 live × 4 = 12 (project single-build jobs: 12)
Classes: steps standard; B step 4 standard-high (plan mark)
Review: 1 call after all pipelines land
Gates: integration (with review) · release (/hex-finalize)
Branches: feature hex/plan-cache; per pipeline hex/plan-cache--<pipeline>
Plus the federation pre-flight lines, when federated. A client that cannot spawn
subagents announces Degraded: inline workers and runs each brief inline,
sequentially (protocol.md).
Then set the plan's State: executing.
3. Contract wave
Resolve the feature branch — the non-trunk branch already checked out, else
hex/<plan-slug> from the trunk
(worktree.md).
A single pipeline (small task) skips the wave and the worktree: its steps
run directly on the feature branch.
Otherwise one or a few standard steps write the stubs plus contract tests
for every pipeline — public surface with not-implemented bodies, and the tests
that pin each cross-pipeline contract, derived from the plan's component
contracts, not from the stubs. Commit once. That commit is the frozen base of
every pipeline.
4. Pipelines and steps
Each pipeline gets a branch hex/<plan-slug>--<pipeline-slug> and a worktree
(worktree.md),
all created from the wave commit; all pipelines start together. Pipelines own
disjoint file sets. Inside a pipeline: serial steps, shared worktree, no merge,
no review, no gate between steps. The orchestrator spawns every step itself
(foreground results reach it; there is no driver agent in between) and starts a
pipeline's next step the instant the previous returns.
Step. A fresh agent of class standard (standard-high only where the plan
marks the step — at most 1 pipeline in 4), one small brief
(workers.md
rule 8: the excerpt, not the plan body). The step does contract-first TDD
inside itself — specify, implement — and commits with --no-verify. Brief
states:
- Step feedback is the only inner check. A behavioural step runs the tests
it wrote or touched, once, with the narrowest command it picks (e.g.
cargo test -p x), never the project's gate wrapper. A non-behavioural step (docs, taskfiles, config, renames, comments) runs nothing — "will this be exercised later anyway?" means skip. - Every commit and merge on hex-owned branches uses
--no-verify. This run's integration and release gates satisfy the project's "verify before commit" instructions; do not run the full gate. - Never wait on a lock, a gate or a poll — return instead. No worker-side locks. A heavy or exclusive tool (bazel server, docker acceptance project) is gate-only; a step that needs a one-off exclusive check hands it to the orchestrator and does not wait.
- Never commit hub or generated files (lockfiles, baselines, goldens; the
hex.md › Pointerslist). - Parallel builds: use at most the pipeline's
jobsallotment.
Job budget. live pipelines × jobs per pipeline ≤ the project's single-build jobs. The orchestrator sets the allotment in every brief.
Contract drift. At each step return, git diff <wave-commit> over the
contract-wave files. A touched contract: the orchestrator applies the edit to
the feature branch, merges it into the affected pipelines' branches, and states
the change in their next brief. No review is triggered.
Failure and escalation (orchestrator only,
models.md): a step has failed when it
returned incomplete or its output was rejected; a red TDD phase is not a failure.
Same step failing again: retry at the same class with the failure attached →
one class up → defer as residue and keep the loop going.
Pipeline done = its steps all returned. Merge it onto the feature branch
with --no-verify, one pipeline at a time in dependency order, never a batch;
no gate on the merge. Set its table Status: merged. Merge-time file-set
re-validation and the conflict playbook are
worktree.md's.
5. Integration gate ∥ review call
When every pipeline has merged, in the background and concurrently:
- Integration gate — the project's full documented verification on the
feature branch (
verify.md), after regenerating the hub and generated files once, minimally (nocargo update). - Review call — one autonomous
/hex-reviewoveranchor..HEAD: staged panel and codex, seats split per pipeline plus one for the seams./hex-reviewowns seats, rounds and the last-reviewed anchor.
Mid-run review calls: loop.md § Review calls.
One fix pass serves both: gate failures and the review's findings go to
standard fixers per pipeline, in parallel, then the gate runs again. Red →
one fix pass → gate again; at most 2 fix passes, then stop and hand the
residue to the user. A gate that failed on infrastructure is rerun once.
6. Hand off
Set the plan's State: review, Next: /hex-finalize, Updated refreshed (a
free-text target has no Status block — say so in the handoff). Run the
upkeep step. Never push.
Emit the handoff
(contract):
## Execution Complete: <feature | plan name>
### Run
- Pipelines: <n> merged, <n> deferred · contract wave <sha>
- Integration gate: green | red after 2 fix passes (<cause>)
- Review calls: <n> · anchor <sha>
### Artifacts
- <plan path> (Status block advanced to `review`)
- <feature branch and tip>
### Deferred findings (need human judgment)
- Review: …
- Residue: … (steps deferred after escalation)
### Next step
/hex-finalize
A plan carrying a Repo column adds the per-repo landing order and
back-pointer list (federation.md).
Plan artifact
Co-owned with /hex-plan and /hex-review; no external state file.
## Status
- State: executing <!-- planning → plan-approved → executing → review → done -->
- Updated: 2026-07-19
- Next: /hex-execute <this plan path>
- Living design record. When execution reveals a behaviour the plan did not specify, update the plan first, then the test, then the code.
- Spec deltas (C-419). On each pipeline merge, append its delta entries to
the plan's single
## Spec Deltasblock — oneTarget:for the plan (C-415), append-only, never rewriting another pipeline's entry. AMODIFIEDentry'sBase:is the pasted output of archive.md's stale-base sub-ID scan (C-405) over the live destination. A satellite-delivered entry (Repo≠.) defers rather than folding (C-415 clause 5). Grammar and guards:archive.md§ Delta grammar.
Constraints
- Project rules, verification and artifact conventions come from project context
and the
hex.md › Pointers, never a hardcoded table; no documented verification means detect one command once and suggest/hex-init. - The orchestrator's main loop only dispatches and merges; anything slow runs in
the background. Event-driven on step returns, with a fallback tick of at
least 20 minutes. Two levels:
/hex-loopabove, this run below. - Never exceed the concurrency cap
(
protocol.md). - Never push to remote. Never leave finished work uncommitted.
- No mid-flow questions; a scope surprise stops and re-routes to
/hex-plan.
$ARGUMENTS
04 同仓库更多 Skills
rca
Use when a bug ticket, GitHub issue or error report needs a root cause analysis before code is touched — "is this a bug", "why does this fail". Read-only. Gives a verdict (bug or not-a-bug kind), file:line evidence, ruled-out hypotheses, other affected sites, fix direction and size. A ticket, not a diff (hex-review).
fix
Use when a bug ticket or GitHub issue should go from report to an approved fix plan — "plan a fix", "fix this issue". Root-causes it via rca, then plans in plan mode with the failing regression test first. Routes to hex-plan instead when the fix is large or moves an interface contract.
p9-skill
Principle 9 differential fixture skill (v2).
p9-member
Bundle member skill for the Principle 9 fixture (v2).
p9-hookish
Hook-free skill carrying an ignored hook.toml (v2).
p9-skill
Principle 9 differential fixture skill (v1).