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
Install
npx skills add https://github.com/grimoire-rs/grimoire/tree/main/.agents/skills/hex-execute
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install grimoire-rs-grimoire@llmmart
git clone https://github.com/grimoire-rs/grimoire.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole grimoire-rs/grimoire collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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
Files (grimoire)
-
federation.md 10.2 KB
Loading… -
SKILL.md 11.6 KB
--- name: hex-execute 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. 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 --- # 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`](../hex-core/references/protocol.md) · [`workers.md`](../hex-core/references/workers.md) · [`models.md`](../hex-core/references/models.md) · [`memory.md`](../hex-core/references/memory.md) · [`worktree.md`](../hex-core/references/worktree.md) · [`verify.md`](../hex-core/references/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`](../hex-core/references/memory.md#the-three-sections)). - `--dry-run` — print the announce block and stop; no worker launches. ## The run Counts are fixed ([`DESIGN.md`](../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`](../hex-core/references/memory.md#location-and-resolution)) — 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`](../hex-core/references/memory.md#location-and-resolution). 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`](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`](federation.md#landing-re-entry-and-upkeep)). `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`](../hex-core/references/protocol.md#worker-coordination)). 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`](../hex-core/references/worktree.md#pipeline-worktree-mechanics)). 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`](../hex-core/references/worktree.md#pipeline-worktree-mechanics)), 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`](../hex-core/references/workers.md#universal-worker-protocol) 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 › Pointers` list). - Parallel builds: use at most the pipeline's `jobs` allotment. **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`](../hex-core/references/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`](../hex-core/references/worktree.md#pipeline-worktree-mechanics)'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`](../hex-core/references/verify.md#verification)), after regenerating the hub and generated files once, minimally (no `cargo update`). - **Review call** — one autonomous `/hex-review` over `anchor..HEAD`: staged panel and codex, seats split per pipeline plus one for the seams. `/hex-review` owns seats, rounds and the [last-reviewed anchor](../hex-core/references/loop.md#the-last-reviewed-anchor). Mid-run review calls: [`loop.md` § Review calls](../hex-core/references/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](../hex-core/references/protocol.md#upkeep-step). Never push. Emit the handoff ([contract](../hex-core/references/protocol.md#handoff-contract)): ```markdown ## 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`](federation.md#handoff-addendum)). ## Plan artifact Co-owned with `/hex-plan` and `/hex-review`; no external state file. ```markdown ## 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 Deltas` block — one `Target:` for the plan (C-415), append-only, never rewriting another pipeline's entry. A `MODIFIED` entry's `Base:` is the **pasted output** of archive.md's stale-base sub-ID scan ([C-405](../hex-core/references/archive.md#safety-envelope)) over the **live** destination. A satellite-delivered entry (`Repo` ≠ `.`) defers rather than folding (C-415 clause 5). Grammar and guards: [`archive.md` § Delta grammar](../hex-core/references/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-loop` above, this run below. - Never exceed the concurrency cap ([`protocol.md`](../hex-core/references/protocol.md#worker-coordination)). - **Never push to remote.** Never leave finished work uncommitted. - No mid-flow questions; a scope surprise stops and re-routes to `/hex-plan`. $ARGUMENTS
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.