hex-init
Initialize or reconfigure a project for the hex swarm - audits project context (CLAUDE.md/AGENTS.md) for the knowledge the orchestrators need (how to verify, spec/plan conventions), provisions what is missing into project context, optionally seeds default templates, and bootstrap
#setup #configuration
Install
npx skills add https://github.com/grimoire-rs/grimoire/tree/main/.agents/skills/hex-init
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-init — Project Initializer
hex-init audits and bootstraps a project for the hex swarm. Run it only
when the user explicitly invokes it — it never triggers itself from
another skill's flow. It is re-entrant: every run re-audits, reports
drift, and fixes it with the user's consent.
Core stance
Knowledge about the project — how to verify it, where specs, plans, and
ADRs live and in what format, which rules carry architectural weight, and
what the product is and who uses it — belongs in the project's own context
(CLAUDE.md, AGENTS.md, or docs they point to), where every agent and tool
already reads it. hex never keeps a second copy of that knowledge; a
second source of truth would drift and rot. hex-init is an auditor and
provisioner of project context first, and a config writer only for what
genuinely belongs to the swarm — model preferences, cross-model review,
perspectives of interest. The swarm file (.agents/memory/hex.md)
holds only three things: a cache of pointers to where that project
knowledge lives, swarm config, and the orchestrators' working memory (see
../hex-core/references/memory.md).
Every fact has exactly one home: useful to any agent → project context;
useful only to the swarm → hex.md › Preferences. Never both — project
knowledge is recorded in hex.md › Pointers only as a pointer to where
it lives, never copied.
The wizard
hex-init runs as an interactive wizard, not a batched form. The
single-gate rule (protocol.md) that
forbids mid-flow questions governs the four orchestrators, which run long
autonomous swarms where an interruption strands parallel workers.
hex-init runs no swarm and is exempt — it may ask its questions in
sequence. The exemption is narrow and named — hex-init is one of the two
skills it covers, each on its own ground; the list is owned by
protocol.md § The meta-plan approval
gate.
Every question the Flow below asks obeys this shape:
- Flags are validated before any prompting. A bad flag surfaces its
Error:/Fix:up front — it cannot discard a finished wizard walk. [n/N]progress header on each question, its label stating why the step matters, not just the field name.- Validation re-prompts in place — a rejected answer re-asks with the
validator's error string and prior answers intact; an accepted one echoes
back (
Added 'reviewer:accessibility' (.agents/workers/)). - Detectable answers are never asked — the harness in use, whether
.agents/worktrees/is gitignored, whether a project persona file exists, the verification command, anything answered on a prior run and unchanged. Asking a detectable thing is the tell of a badly designed init. - Conditional questions fire only on a Step 1 trigger — the perspectives question only when the audit found a security-sensitive path or a project persona; the research-axes question only when research artifacts exist.
- Current state prints before the first question; each value carries a
[current]label and is its default, and multi-selects are pre-checked from current state. - A diff prints before every write — one line per changed key, old → new, derived keys named alongside touched ones.
- Apply is a separate consent, taken after the diff.
- Cancellation is always available and aborts with nothing written;
every refusal pairs
Error:withFix:.
This replaces the former "one batched approval" in Steps 2 and 4½: the
questions are walked in sequence, then one diff and its apply consent gate
the write. The non-interactive twin (--yes, -d, and its triggers)
is documented under Arguments.
Flow
1. Audit project context
Run the checklist in references/audit.md against
the client's project-context file(s) (CLAUDE.md, AGENTS.md, or the
client's equivalent) and any docs they point to. Each item carries a
de facto discovery hint — scan the places a practiced-but-undocumented
scheme actually lives (CI workflows, task runners, docs/adr*, …) and
propose adopting what exists via pointer before proposing anything new:
- Is verification (build/test/lint) documented, or only discoverable by guessing?
- Is a selective test command documented — one that runs the tests a change affects, rather than the whole suite?
- Are the project's commit and landing requirements documented — sign-off,
signing, message convention, which suites are release-grade, which
workflows gate a release? Checked-in files only; this item reads no
forge. See
references/audit.md. - Are spec/plan/ADR conventions documented — location, format, template?
- Is a spec home documented — a conditional sub-check, asked only when
a plan carries an unresolved
## Spec Deltasblock, or the item above names plans and ADRs but no specs; nothing is asked of a project that never planned anything. Seereferences/audit.md. - Is a discussions home documented — a conditional item, asked only
when a discussion artifact already exists, or the user asks for one at
invocation or at any wizard question in Step 2; hex never raises it
first, and nothing is asked of a project that never discussed
anything. See
references/audit.md. - Is a goals home documented — a conditional item, asked only when a
goal file already exists, or the user asks for one; hex never raises it
first, and nothing is asked of a project that never ran a goal loop.
See
references/audit.md. - Are goal-loop defaults recorded — a
- Goal loop:prose hint inhex.md › Preferences, proposed with consent when Memory notes of hand-written goal prompts show a de facto default? Optional; absent is fine. Seereferences/audit.md. - Do the project's rules carry architectural context (boundaries, invariants, security-sensitive paths), not just style/lint rules?
- Is product context documented — what the product is, who uses it and where, related repos, research keywords, comparable tools? (The one item usually not discoverable from the repo; gaps become Step 2 wizard questions.)
- Is a constitution / governing-principles doc pointed at (project
context, cached in
hex.md › Pointers) — or none used? Optional; absent is fine. - Is the worktree path (default
.agents/worktrees/) gitignored — and does this project use a different one? And the converse: is that rule narrow enough to leavehex.mdcommittable? A bare.agents/line drops the team-shared memory file from version control and is a defect, not a safer-because-broader choice. Seereferences/audit.md. - Is a cross-model adversary skill installed but not pinned — a skill
carrying the
hex-adversary-scopesmarker with no matchingadversary:line inhex.md › Preferences? And the reverse: does an existingadversary:pin name a skill that is not installed (report-only drift — a user-typed pin is never overwritten)? Reads installed frontmatter only; executes nothing. Seereferences/audit.md. - Is the project's single-build job count recorded — one build's parallel
jobs, the budget live pipelines share? See
references/audit.md. - Does any project lesson or script make a worker wait on a build lock,
semaphore, or exclusive tool? See
references/audit.md. - Does every always-on "verify before commit" line carry a hex-run
carve-out? See
references/audit.md. - Does any scoped or selective test command silently escalate to the full
suite? See
references/audit.md. - Is the hub / generated file list documented — lockfiles, baselines,
goldens that pipelines must never commit? See
references/audit.md. - Is the release gate's no-cache switch documented? See
references/audit.md. - Are agent worktrees (
.agents/worktrees/by default) excluded from IDE file watchers and search indexers, not just from version control? Seereferences/audit.md. - Is the project's scratch/temp convention documented, and has it
opted
HOMEinto the per-run scratch redirect — for a suite known to write to$HOME, or to keep credentials from a verification command it does not fully trust? Seereferences/audit.md. - If
.agents/memory/hex.mdalready exists: does every pointer in its Pointers section, and every index line it seeded in the context file, still resolve? (a re-audit item, not first-run-only) - If a
Federation lead:bullet exists: does each plan slug it lists still name a live, unfinished plan in the lead repo — or has the slug gone stale (the lead-side plan is absent or done)? (a re-audit item — seereferences/audit.md) - If any
workflows.<skill>.<tier>pointer exists: does each fork file resolve, carry itsForked from … @ hex <version>stamp, and match the installed hex version — or has the shipped tier file moved on (drift)? (a re-audit item — seereferences/audit.md)
Produce a gap report — found / missing / drifted, one line per item. This step never writes anything.
2. Fill gaps, with consent
For every gap, propose the matching best-practice block from
references/audit.md and a
destination for it. Each proposal is a wizard question —
walked in sequence with [n/N] headers and in-place validation, skipped
when the answer is already detectable, conditional ones gated on Step 1's
findings; the assembled set then prints as one diff before the write.
Destination is the user's choice. The rule of thumb: knowledge useful
to any agent (verification, worktree location, conventions, product
identity) → project context; knowledge only the swarm consumes →
hex.md › Preferences. Propose accordingly, but the user may redirect
it — e.g.
"put the worktree convention in CLAUDE.md so every tool uses it, not just
the swarm." See the destination-of-knowledge rule in
../hex-core/references/memory.md.
Product knowledge is provisioned into project context, never captured
in swarm memory. Short facts (what the product is, who uses it,
comparable tools) become a section in the client's context file; a larger
body gets its own doc — a de-facto home when one exists (README,
docs/), else a provisioned file such as .agents/product.md — plus a
one-line index entry in the context file so every agent finds it.
hex.md › Pointers then records only where it landed.
Spec home (conditional). When the spec-home
sub-check fires,
propose in this order: an existing practiced location first, else
.agents/specs/ as the last resort — with consent. Ask whether
the destination uses the default ID-marker heading shape or a
project-specific one; a non-default answer is recorded as Spec ID marker: prose in hex.md › Preferences, never in hex.md › Pointers.
When the resolved home is empty, offer to seed it — copy
assets/templates/spec.md to <home>/spec_<slug>.md,
copy-only-if-absent. Mechanics (resolution order, the ID-marker
convention, containment) are defined once in
../hex-core/references/archive.md;
this step only asks and records the answer, never restates them.
Discussions home (conditional). When the discussions-home
item
fires, propose in this order: an existing practiced location first, else
.agents/discussions/ as the last resort — with consent. Record the
one outcome as a hex.md › Pointers row:
- Discussions: `<home>` — pre-plan discussion artifacts (/hex-discuss).
<home> is the location the user consented to, .agents/discussions/
only when the last resort was taken. Discussion artifacts carry no
C-/S- IDs, so there is no ID-marker question here and nothing is
written to hex.md › Preferences. When the resolved home is empty, offer
to seed it — copy assets/templates/discussion.md to
<home>/_template.md, copy-only-if-absent, saying in the offer that
the underscore prefix marks it as never a discussion, so nothing scanning
the home for a live one picks it up. Mechanics are defined once
elsewhere: home resolution and verify-on-consumption in
../hex-core/references/memory.md,
containment in
../hex-core/references/archive.md,
whose path conditions bind every write under <home> — this seed copy
and /hex-discuss's own <home>/<slug>.md alike (its already-exists and
git-tracked conditions belong to the fold; the no-symlink, no-directory
clause still binds — a dangling symlink reads as absent). This step only
asks and records the answer, never restates them.
Goals home (conditional). When the goals-home
item fires,
propose in this order: an existing practiced location first, else
.agents/goals/ as the last resort — with consent. Record the one
outcome as a hex.md › Pointers row:
- Goals: `<home>` — per-run goal files (/hex-loop).
<home> is the location the user consented to, .agents/goals/ only
when the last resort was taken. There is no seed offer: goal files are
written only by /hex-loop, one per run, from
assets/templates/goal.md. Mechanics are defined once elsewhere: home
resolution and verify-on-consumption in
../hex-core/references/memory.md,
containment in
../hex-core/references/archive.md,
whose path conditions bind /hex-loop's <home>/<slug>.md write.
This step only asks and records the answer, never restates them.
Selective test command. A command found by the selective-test
item is proposed
for adoption via pointer, with the matching block from
references/audit.md; that
block pins the grammar of the hex.md › Pointers row this run records —
where the selective test command is documented. It is a wizard question
inside the existing sequence, written under the same apply consent as the
discussions row above.
Run-cost items. What the single-build, hub-file and fresh-gate items
find is proposed for adoption via pointer; their rows (Build jobs:,
Hub files:, Fresh gate:) and the best-practice blocks are in
references/audit.md. A lock
to remove or a carve-out line to add is project text: propose the exact
edit as a diff, write it only with consent, never rewrite a project lesson
unasked.
Commit and landing requirements. A requirement found by the
commit-and-landing
item is
proposed for adoption via pointer, and two hex.md › Pointers rows record
what only the swarm consumes:
- Forge: `<forge>` — CLI `<cli>`, used by /hex-finalize.
- Target branch: `<branch>` — where feature branches land (/hex-finalize).
The forge row is proposed whenever a forge is in use, determined from the
checked-in remote alone (git remote -v and its URL host) — never from a
CLI auth probe, which would reach the network. The target-branch row
is proposed only where the trunk is not the obvious default — a repo
whose default branch is plainly main gets no row. Pair the proposal with
the item's branch-protection recommendation; that recommendation is the one
control enforced outside hex, so it is offered even to a project that
already documents its commit requirements.
Series shape (conditional). When the commit-and-landing item's
series-shape
offer
fires, offer to record the team's preference as prose in hex.md › Preferences, with consent. It is prose, never a config key: config.md's
vocabulary is frozen and gains nothing here. Mechanics (the trigger, the
named alternative, the shipped default, the documented-convention defer)
are defined once in
audit.md;
this step only asks and records the answer, never restates them.
After the apply consent, write each block into the chosen file. If a hex-authored block from a prior run already lives there, replace it in place; never touch content the user or another tool wrote. Declined items are skipped and noted in the closing summary as still-missing — nothing is written without consent.
3. Templates (only if wanted)
Only when Step 1 found no spec/plan/ADR conventions documented, no
de-facto scheme to adopt, and the user opts into shipped defaults
as part of the Step 2 approval: copy
assets/templates/ (plan.md, adr.md,
discussion.md, research.md, spec.md) to a location of the user's
choice, only if that file is absent — never overwrite an existing
file. Document the chosen location in the conventions block written in
Step 2.
This is a fallback, not a default push. A project with its own RST/Sphinx templates keeps them and just documents where they live — hex never forces its own formats onto a project that already has one.
4. Instantiate the model classes
Present the four shipped capability classes
(../hex-core/references/models.md):
light, standard, standard-high, deep. Detect the harness in use
(from the client running this skill, or ask if ambiguous) and propose a
literal model and an effort per class; models.md carries the example
mapping for a Claude harness, not restated here. Each class becomes one
agent definition in the client's agent directory (Claude Code:
.claude/agents/hex-<class>.md) — the Agent tool takes no per-spawn
effort, so the definition is what binds model and effort together.
Orchestrators spawn by that name:
---
name: hex-<class>
description: hex worker, class <class>.
model: <literal model for the class>
effort: <effort for the class>
---
You are a hex worker. The spawn prompt carries your task; do that only.
An existing definition is updated only in model and effort, after the
diff; a user's other edits stay. A per-role override is the
models.overrides key (config.md),
not a separate definition. Skipping this step is fine — spawns then
run the harness default and class escalation has no effect. Nothing from
this step is written until Step 4½'s apply consent.
4½. Assemble the Preferences block, with consent
Gather every swarm-only choice from this run — an adversary skill, limits,
perspectives, research-axes, and the review settings (plus any
candidate a prior run recorded in hex.md › Memory under the
upkeep step) — into the
single fenced yaml block
that carries hex.md › Preferences. Key set, types, defaults, and effects
are defined once, in
../hex-core/references/config.md;
do not restate them here. The block is the first content under
## Preferences, prose bullets continuing below it
(placement). Use
vocabulary v4: v1's six keys (models, adversary, limits,
perspectives, research-axes, tiers), plus workflows, the fork
pointer written into this same block by the
workflow-fork flow
(config.md § Workflows),
plus review (adr_0016 C-990); tier segments take the five-value grammar
and adversary may be a list (v4, adr_0017 C-997).
Present the assembled block as one diff against the file's current state
(one line per changed key, old → new), gated by the
wizard's separate apply consent, with the Step 4 agent
definitions listed in the same diff. On consent, write the block and the
definitions; on decline, leave hex.md › Preferences as-is
and note it still-missing in the Step 7 summary. An unconfigured project
writes nothing here — empty is normal, shipped defaults apply.
5. Bootstrap .agents/memory/hex.md
Write or update .agents/memory/hex.md per
../hex-core/references/memory.md.
hex.md › Preferences is already written by Step 4½ — this step covers
the other two sections:
hex.md › Pointers— a cache seeded from Step 1's findings: where verification is documented, where the selective test command is documented, where spec/plan/ADR conventions live, the doc and product-knowledge homes provisioned in Step 2, the discussions home when one was resolved, the goals home when one was resolved, key architectural rules, any worktree-location deviation, the constitution location (optional), and the run-cost rowsBuild jobs:,Hub files:andFresh gate:when found. Pointers only, never copies — the product-knowledge pointer is how researchers and reviewers reach the product facts that live in project context.hex.md › Memory— left empty at bootstrap; the orchestrators maintain it during their own runs.
On a re-entrant run, update only what Step 1 found drifted or what the
user changed in Steps 2–4½; never rewrite the whole file.
hex.md › Pointers and hex.md › Memory are skill-managed — the
orchestrators own them day-to-day; a re-run re-points
hex.md › Pointers where the audit found drift but clobbers neither
section beyond that, and never touches hex.md › Memory.
A missing .agents/memory/hex.md is normal and fully supported —
every hex skill falls back to its shipped defaults without one.
6. Discovery note (optional)
For a client that doesn't already load project context ambiently, or on
request: write a 3-line marker-fenced pointer block into the client's
context file (template in
references/audit.md). It
only points — never duplicates content from .agents/memory/hex.md
or from project context. On a re-run, replace the block between the
markers in place.
7. Summary
Close with three short lists: what was audited (pass/gap per item), what was written and where (file → section), and what was proposed but skipped (declined, or not applicable). No prose beyond that.
Workflow forks (/hex-init workflows)
/hex-init workflows manages workflow forks — project-authored tier
files that redirect an orchestrator's phase plan. The fork file format
(node schema, the Forked from … @ hex <version> stamp, the Count
grammar, the seven validation checks) is defined once in
config.md § Workflows;
this flow only creates and tracks the files, and asks through the
wizard:
- List the forkable skill × tier pairs (the orchestrators that ship
tier files ×
low/medium/high/xhigh/max), each with its shipped phase list and a[forked]marker whereworkflows.<skill>.<tier>already points at a file. - Fork. On selection, copy the shipped
hex-<skill>/tier-<tier>.mdto.agents/workflows/<skill>-<tier>.md, prepend the header table derived from its shipped phases, and stamp it per config.md § Workflows (Forked from hex-<skill>/tier-<tier>.md @ hex <version>— both validation and drift detection read the stamp). Never overwrite an existing fork. - Edit. The user edits the copy — delete a phase row and its section, add a role, re-point an edge.
- Diff, consent, write. Print the diff by cell, not just by phase —
added / removed / re-pointed rows and
Roles/Countdeltas inside a kept phase, each against the file the stamp names. A narrowedRolescell (e.g. droppingreviewer:securityfrom a retained Review-Fix Loop) must surface here — it is the human's one look at the fork before it is wired in, and it is the consent backstop for the security-reviewer invariant (config.md validation check 6). Take the wizard's apply consent, then write theworkflows.<skill>.<tier>pointer into the Preferences block (Step 4½'s block;workflowsis vocabulary v2). - Drift on re-audit. A later
/hex-initre-audit (references/audit.md) compares each fork's stamped version against the installed hex version; on a mismatch it reports drift and shows what changed in the shipped tier file — it never auto-merges and never rewrites the fork.
Re-entrancy
Every property above holds on every run, not just the first: Step 1
always re-audits, including whether existing hex.md › Pointers entries
and the context-file index lines still resolve; nothing is overwritten
without consent; templates are only-if-absent; marker-fenced blocks (the
Step 2 best-practice blocks, the Step 6 discovery note) replace in place.
Run hex-init again any time drift is suspected or the setup needs to
change — there is no separate "reconfigure" flow.
The Preferences block is user-owned; a re-run never clobbers it.
Deterministic scaffolding (the hex.md section skeleton, seeded pointers,
marker-fenced blocks) regenerates every run; the fenced yaml block does
not. Keys the user did not touch keep their values and their comments
and their existing order; the wizard rewrites only the keys its diff named
— changing a value in place while keeping that line's quoting — and a newly
added key is appended in the § Complete
example's style. A key
the block still carries that a later hex version dropped from the
vocabulary is reported deprecated in the Step 7 summary, never silently
deleted — unlike OpenCode/fast-agent, hex has no code layer that can
safely auto-rewrite a user-owned block, so deprecated keys are reported,
not migrated. If the hand-edited block already carries a key in both the
nested and flat spelling that
C-222 tolerates on read,
the wizard surfaces C-222's duplicate-key Error:/Fix: and leaves the
user's spellings untouched rather than collapsing them.
Structure
SKILL.md— this flow.references/audit.md— the audit checklist and the best-practice block templates used in Steps 1, 2, and 6.assets/templates/— the fallbackplan.md,adr.md,discussion.md,research.md,spec.mdused in Step 3, andgoal.md, which only/hex-loopinstantiates.
The reference links above resolve when hex-core is installed alongside
this skill; if it isn't: grim add ghcr.io/michael-herwig/arcana/hex-core:latest.
Arguments
A positional concern narrows the run to one area: verification,
conventions, worktrees, models, templates, or workflows (the
fork lifecycle above). Omitted,
hex-init runs the full flow above.
Two flags drive the non-interactive twin — the wizard's questions answered without prompting:
--yesaccepts every recommendation the audit produces, writing the same diff the wizard would, without asking.-d key=value(repeatable) sets one config key directly, e.g.-d limits.max-workers=6 -d adversary=codex:rescue.
The twin engages automatically when there is no TTY, when any -d is
given, or when CI is set. A non-interactive refusal still pairs Error:
with Fix: and enumerates the accepted values inline so the correction
is paste-able (e.g. Error: -d adversary=nope unknown. Fix: accepted: <skill-name> | none).
$ARGUMENTS
Files (grimoire)
-
assets
-
templates
-
adr.md 3.8 KB
Loading… -
discussion.md 3.1 KB
Loading… -
goal.md 6.3 KB
Loading… -
plan.md 12.7 KB
Loading… -
research.md 2 KB
Loading… -
spec.md 5 KB
Loading…
-
-
-
references
-
audit.md 30.1 KB
Loading…
-
-
SKILL.md 29.3 KB
--- name: hex-init description: Initialize or reconfigure a project for the hex swarm - audits project context (CLAUDE.md/AGENTS.md) for the knowledge the orchestrators need (how to verify, spec/plan conventions), provisions what is missing into project context, optionally seeds default templates, and bootstraps the AI-maintained swarm memory at .agents/memory/hex.md (cached pointers, orchestration preferences, perspectives of interest). Re-entrant - run again anytime to re-audit pointers or change the setup. license: Apache-2.0 metadata: keywords: init,setup,configuration,conventions,templates,swarm,onboarding repository: https://github.com/michael-herwig/arcana summary: Project-context audit and setup for the hex swarm bundle --- # hex-init — Project Initializer `hex-init` audits and bootstraps a project for the hex swarm. Run it only when the user explicitly invokes it — it never triggers itself from another skill's flow. It is re-entrant: every run re-audits, reports drift, and fixes it with the user's consent. ## Core stance Knowledge about the *project* — how to verify it, where specs, plans, and ADRs live and in what format, which rules carry architectural weight, and what the product is and who uses it — belongs in the project's own context (CLAUDE.md, AGENTS.md, or docs they point to), where every agent and tool already reads it. hex never keeps a second copy of that knowledge; a second source of truth would drift and rot. `hex-init` is an **auditor and provisioner of project context first**, and a config writer only for what genuinely belongs to the swarm — model preferences, cross-model review, perspectives of interest. The swarm file (`.agents/memory/hex.md`) holds only three things: a cache of pointers to where that project knowledge lives, swarm config, and the orchestrators' working memory (see [`../hex-core/references/memory.md`](../hex-core/references/memory.md)). Every fact has exactly one home: useful to *any* agent → project context; useful only to the swarm → `hex.md › Preferences`. Never both — project knowledge is recorded in `hex.md › Pointers` only as a pointer to where it lives, never copied. ## The wizard `hex-init` runs as an **interactive wizard**, not a batched form. The single-gate rule ([`protocol.md`](../hex-core/references/protocol.md)) that forbids mid-flow questions governs the four *orchestrators*, which run long autonomous swarms where an interruption strands parallel workers. `hex-init` runs no swarm and is **exempt** — it may ask its questions in sequence. The exemption is narrow and named — `hex-init` is one of the two skills it covers, each on its own ground; the list is owned by [`protocol.md` § The meta-plan approval gate](../hex-core/references/protocol.md#the-meta-plan-approval-gate). Every question the Flow below asks obeys this shape: - **Flags are validated before any prompting.** A bad flag surfaces its `Error:`/`Fix:` up front — it cannot discard a finished wizard walk. - **`[n/N]` progress header** on each question, its label stating *why the step matters*, not just the field name. - **Validation re-prompts in place** — a rejected answer re-asks with the validator's error string and prior answers intact; an accepted one echoes back (`Added 'reviewer:accessibility' (.agents/workers/)`). - **Detectable answers are never asked** — the harness in use, whether `.agents/worktrees/` is gitignored, whether a project persona file exists, the verification command, anything answered on a prior run and unchanged. Asking a detectable thing is the tell of a badly designed init. - **Conditional questions fire only on a Step 1 trigger** — the perspectives question only when the audit found a security-sensitive path or a project persona; the research-axes question only when research artifacts exist. - **Current state prints before the first question**; each value carries a `[current]` label and is its default, and multi-selects are pre-checked from current state. - **A diff prints before every write** — one line per changed key, old → new, derived keys named alongside touched ones. - **Apply is a separate consent**, taken after the diff. - **Cancellation is always available** and aborts with nothing written; every refusal pairs `Error:` with `Fix:`. This replaces the former "one batched approval" in Steps 2 and 4½: the questions are walked in sequence, then one diff and its apply consent gate the write. The **non-interactive twin** (`--yes`, `-d`, and its triggers) is documented under [Arguments](#arguments). ## Flow ### 1. Audit project context Run the checklist in [`references/audit.md`](references/audit.md) against the client's project-context file(s) (CLAUDE.md, AGENTS.md, or the client's equivalent) and any docs they point to. Each item carries a **de facto discovery** hint — scan the places a practiced-but-undocumented scheme actually lives (CI workflows, task runners, `docs/adr*`, …) and propose adopting what exists via pointer before proposing anything new: - Is verification (build/test/lint) documented, or only discoverable by guessing? - Is a selective test command documented — one that runs the tests a change affects, rather than the whole suite? - Are the project's commit and landing requirements documented — sign-off, signing, message convention, which suites are release-grade, which workflows gate a release? Checked-in files only; this item reads no forge. See [`references/audit.md`](references/audit.md#commit-and-landing-requirements-documented). - Are spec/plan/ADR conventions documented — location, format, template? - Is a spec home documented — a **conditional** sub-check, asked only when a plan carries an unresolved `## Spec Deltas` block, or the item above names plans and ADRs but no specs; nothing is asked of a project that never planned anything. See [`references/audit.md`](references/audit.md#spec-home-documented-conditional). - Is a discussions home documented — a **conditional** item, asked only when a discussion artifact already exists, or the user asks for one at invocation or at any wizard question in Step 2; hex never raises it first, and nothing is asked of a project that never discussed anything. See [`references/audit.md`](references/audit.md#discussions-home-documented-conditional). - Is a goals home documented — a **conditional** item, asked only when a goal file already exists, or the user asks for one; hex never raises it first, and nothing is asked of a project that never ran a goal loop. See [`references/audit.md`](references/audit.md#goals-home-documented-conditional). - Are goal-loop defaults recorded — a `- Goal loop:` prose hint in `hex.md › Preferences`, proposed with consent when Memory notes of hand-written goal prompts show a de facto default? Optional; absent is fine. See [`references/audit.md`](references/audit.md#goal-loop-defaults-recorded-optional). - Do the project's rules carry architectural context (boundaries, invariants, security-sensitive paths), not just style/lint rules? - Is product context documented — what the product is, who uses it and where, related repos, research keywords, comparable tools? (The one item usually not discoverable from the repo; gaps become Step 2 wizard questions.) - Is a constitution / governing-principles doc pointed at (project context, cached in `hex.md › Pointers`) — or none used? Optional; absent is fine. - Is the worktree path (default `.agents/worktrees/`) gitignored — and does this project use a different one? **And the converse: is that rule narrow enough to leave `hex.md` committable?** A bare `.agents/` line drops the team-shared memory file from version control and is a defect, not a safer-because-broader choice. See [`references/audit.md`](references/audit.md#worktree-path-gitignored). - Is a cross-model adversary skill installed but not pinned — a skill carrying the `hex-adversary-scopes` marker with no matching `adversary:` line in `hex.md › Preferences`? And the reverse: does an existing `adversary:` pin name a skill that is not installed (report-only drift — a user-typed pin is never overwritten)? Reads installed frontmatter only; executes nothing. See [`references/audit.md`](references/audit.md#cross-model-adversary-skill-installed). - Is the project's single-build job count recorded — one build's parallel jobs, the budget live pipelines share? See [`references/audit.md`](references/audit.md#single-build-job-count-recorded). - Does any project lesson or script make a worker wait on a build lock, semaphore, or exclusive tool? See [`references/audit.md`](references/audit.md#no-worker-side-build-locks). - Does every always-on "verify before commit" line carry a hex-run carve-out? See [`references/audit.md`](references/audit.md#verify-before-commit-lines-carry-a-hex-run-carve-out). - Does any scoped or selective test command silently escalate to the full suite? See [`references/audit.md`](references/audit.md#scoped-commands-that-escalate-to-full). - Is the hub / generated file list documented — lockfiles, baselines, goldens that pipelines must never commit? See [`references/audit.md`](references/audit.md#hub--generated-file-list-documented). - Is the release gate's no-cache switch documented? See [`references/audit.md`](references/audit.md#release-gate-no-cache-switch-documented). - Are agent worktrees (`.agents/worktrees/` by default) excluded from IDE file watchers and search indexers, not just from version control? See [`references/audit.md`](references/audit.md#agent-worktrees-excluded-from-watchers-and-indexers). - Is the project's scratch/temp convention documented, and has it opted `HOME` into the per-run scratch redirect — for a suite known to write to `$HOME`, or to keep credentials from a verification command it does not fully trust? See [`references/audit.md`](references/audit.md#scratch--temp-convention-documented). - If `.agents/memory/hex.md` already exists: does every pointer in its Pointers section, and every index line it seeded in the context file, still resolve? (a re-audit item, not first-run-only) - If a `Federation lead:` bullet exists: does each plan slug it lists still name a live, unfinished plan in the lead repo — or has the slug gone stale (the lead-side plan is absent or done)? (a re-audit item — see [`references/audit.md`](references/audit.md#federation-back-pointer-slugs-still-live)) - If any `workflows.<skill>.<tier>` pointer exists: does each fork file resolve, carry its `Forked from … @ hex <version>` stamp, and match the installed hex version — or has the shipped tier file moved on (drift)? (a re-audit item — see [`references/audit.md`](references/audit.md#workflow-fork-stamps-current)) Produce a gap report — found / missing / drifted, one line per item. This step never writes anything. ### 2. Fill gaps, with consent For every gap, propose the matching best-practice block from [`references/audit.md`](references/audit.md#best-practice-blocks) and a destination for it. Each proposal is a [wizard](#the-wizard) question — walked in sequence with `[n/N]` headers and in-place validation, skipped when the answer is already detectable, conditional ones gated on Step 1's findings; the assembled set then prints as one diff before the write. **Destination is the user's choice.** The rule of thumb: knowledge useful to *any* agent (verification, worktree location, conventions, product identity) → project context; knowledge only the swarm consumes → `hex.md › Preferences`. Propose accordingly, but the user may redirect it — e.g. "put the worktree convention in CLAUDE.md so every tool uses it, not just the swarm." See the destination-of-knowledge rule in [`../hex-core/references/memory.md`](../hex-core/references/memory.md). **Product knowledge is provisioned into project context, never captured in swarm memory.** Short facts (what the product is, who uses it, comparable tools) become a section in the client's context file; a larger body gets its own doc — a de-facto home when one exists (`README`, `docs/`), else a provisioned file such as `.agents/product.md` — plus a one-line index entry in the context file so every agent finds it. `hex.md › Pointers` then records only where it landed. **Spec home (conditional).** When the [spec-home sub-check](references/audit.md#spec-home-documented-conditional) fires, propose in this order: an existing practiced location first, else `.agents/specs/` as the **last resort** — with consent. Ask whether the destination uses the default ID-marker heading shape or a project-specific one; a non-default answer is recorded as `Spec ID marker:` prose in `hex.md › Preferences`, never in `hex.md › Pointers`. When the resolved home is empty, offer to seed it — copy `assets/templates/spec.md` to `<home>/spec_<slug>.md`, **copy-only-if-absent**. Mechanics (resolution order, the ID-marker convention, containment) are defined once in [`../hex-core/references/archive.md`](../hex-core/references/archive.md#destination-resolution); this step only asks and records the answer, never restates them. **Discussions home (conditional).** When the [discussions-home item](references/audit.md#discussions-home-documented-conditional) fires, propose in this order: an existing practiced location first, else `.agents/discussions/` as the **last resort** — with consent. Record the one outcome as a `hex.md › Pointers` row: ``- Discussions: `<home>` — pre-plan discussion artifacts (/hex-discuss).`` `<home>` is the location the user consented to, `.agents/discussions/` only when the last resort was taken. Discussion artifacts carry no `C-`/`S-` IDs, so there is no ID-marker question here and nothing is written to `hex.md › Preferences`. When the resolved home is empty, offer to seed it — copy `assets/templates/discussion.md` to `<home>/_template.md`, **copy-only-if-absent**, saying in the offer that the underscore prefix marks it as never a discussion, so nothing scanning the home for a live one picks it up. Mechanics are defined once elsewhere: home resolution and verify-on-consumption in [`../hex-core/references/memory.md`](../hex-core/references/memory.md#location-and-resolution), containment in [`../hex-core/references/archive.md`](../hex-core/references/archive.md#destination-resolution), whose **path** conditions bind every write under `<home>` — this seed copy and `/hex-discuss`'s own `<home>/<slug>.md` alike (its already-exists and git-tracked conditions belong to the fold; the no-symlink, no-directory clause still binds — a dangling symlink reads as absent). This step only asks and records the answer, never restates them. **Goals home (conditional).** When the [goals-home item](references/audit.md#goals-home-documented-conditional) fires, propose in this order: an existing practiced location first, else `.agents/goals/` as the **last resort** — with consent. Record the one outcome as a `hex.md › Pointers` row: ``- Goals: `<home>` — per-run goal files (/hex-loop).`` `<home>` is the location the user consented to, `.agents/goals/` only when the last resort was taken. There is no seed offer: goal files are written only by `/hex-loop`, one per run, from `assets/templates/goal.md`. Mechanics are defined once elsewhere: home resolution and verify-on-consumption in [`../hex-core/references/memory.md`](../hex-core/references/memory.md#location-and-resolution), containment in [`../hex-core/references/archive.md`](../hex-core/references/archive.md#destination-resolution), whose **path** conditions bind `/hex-loop`'s `<home>/<slug>.md` write. This step only asks and records the answer, never restates them. **Selective test command.** A command found by the [selective-test item](references/audit.md#selective-test-command-documented) is proposed for adoption via pointer, with the matching block from [`references/audit.md`](references/audit.md#best-practice-blocks); that block pins the grammar of the `hex.md › Pointers` row this run records — where the selective test command is documented. It is a wizard question inside the existing sequence, written under the same apply consent as the discussions row above. **Run-cost items.** What the single-build, hub-file and fresh-gate items find is proposed for adoption via pointer; their rows (`Build jobs:`, `Hub files:`, `Fresh gate:`) and the best-practice blocks are in [`references/audit.md`](references/audit.md#best-practice-blocks). A lock to remove or a carve-out line to add is project text: propose the exact edit as a diff, write it only with consent, never rewrite a project lesson unasked. **Commit and landing requirements.** A requirement found by the [commit-and-landing item](references/audit.md#commit-and-landing-requirements-documented) is proposed for adoption via pointer, and two `hex.md › Pointers` rows record what only the swarm consumes: ``- Forge: `<forge>` — CLI `<cli>`, used by /hex-finalize.`` ``- Target branch: `<branch>` — where feature branches land (/hex-finalize).`` The forge row is proposed whenever a forge is in use, determined from the checked-in remote alone (`git remote -v` and its URL host) — never from a CLI auth probe, which would reach the network. The target-branch row is proposed **only where the trunk is not the obvious default** — a repo whose default branch is plainly `main` gets no row. Pair the proposal with the item's branch-protection recommendation; that recommendation is the one control enforced outside hex, so it is offered even to a project that already documents its commit requirements. **Series shape (conditional).** When the [commit-and-landing item's series-shape offer](references/audit.md#commit-and-landing-requirements-documented) fires, offer to record the team's preference as prose in `hex.md › Preferences`, with consent. It is prose, never a config key: `config.md`'s vocabulary is frozen and gains nothing here. Mechanics (the trigger, the named alternative, the shipped default, the documented-convention defer) are defined once in [`audit.md`](references/audit.md#commit-and-landing-requirements-documented); this step only asks and records the answer, never restates them. After the apply consent, write each block into the chosen file. If a hex-authored block from a prior run already lives there, replace it in place; never touch content the user or another tool wrote. Declined items are skipped and noted in the closing summary as still-missing — nothing is written without consent. ### 3. Templates (only if wanted) Only when Step 1 found no spec/plan/ADR conventions documented, **no de-facto scheme to adopt**, **and** the user opts into shipped defaults as part of the Step 2 approval: copy [`assets/templates/`](assets/templates/) (`plan.md`, `adr.md`, `discussion.md`, `research.md`, `spec.md`) to a location of the user's choice, **only if that file is absent** — never overwrite an existing file. Document the chosen location in the conventions block written in Step 2. This is a fallback, not a default push. A project with its own RST/Sphinx templates keeps them and just documents where they live — hex never forces its own formats onto a project that already has one. ### 4. Instantiate the model classes Present the four shipped capability classes ([`../hex-core/references/models.md`](../hex-core/references/models.md)): `light`, `standard`, `standard-high`, `deep`. Detect the harness in use (from the client running this skill, or ask if ambiguous) and propose a literal `model` and an `effort` per class; `models.md` carries the example mapping for a Claude harness, not restated here. Each class becomes one **agent definition** in the client's agent directory (Claude Code: `.claude/agents/hex-<class>.md`) — the Agent tool takes no per-spawn effort, so the definition is what binds model and effort together. Orchestrators spawn by that name: ```markdown --- name: hex-<class> description: hex worker, class <class>. model: <literal model for the class> effort: <effort for the class> --- You are a hex worker. The spawn prompt carries your task; do that only. ``` An existing definition is updated only in `model` and `effort`, after the diff; a user's other edits stay. A per-role override is the `models.overrides` key ([`config.md`](../hex-core/references/config.md#key-vocabulary)), not a separate definition. Skipping this step is fine — spawns then run the harness default and class escalation has no effect. Nothing from this step is written until Step 4½'s apply consent. ### 4½. Assemble the `Preferences` block, with consent Gather every swarm-only choice from this run — an adversary skill, `limits`, `perspectives`, `research-axes`, and the `review` settings (plus any candidate a prior run recorded in `hex.md › Memory` under the [upkeep step](../hex-core/references/protocol.md#upkeep-step)) — into the single fenced `yaml` block that carries `hex.md › Preferences`. Key set, types, defaults, and effects are defined once, in [`../hex-core/references/config.md`](../hex-core/references/config.md#key-vocabulary); do not restate them here. The block is the **first content** under `## Preferences`, prose bullets continuing below it ([placement](../hex-core/references/config.md#carrier-and-placement)). Use vocabulary v4: v1's six keys (`models`, `adversary`, `limits`, `perspectives`, `research-axes`, `tiers`), plus `workflows`, the fork pointer written into this same block by the [workflow-fork flow](#workflow-forks-hex-init-workflows) ([`config.md` § Workflows](../hex-core/references/config.md#workflows)), plus `review` (`adr_0016` C-990); tier segments take the five-value grammar and `adversary` may be a list (v4, `adr_0017` C-997). Present the assembled block as one diff against the file's current state (one line per changed key, old → new), gated by the [wizard](#the-wizard)'s separate apply consent, with the Step 4 agent definitions listed in the same diff. On consent, write the block and the definitions; on decline, leave `hex.md › Preferences` as-is and note it still-missing in the Step 7 summary. An unconfigured project writes nothing here — empty is normal, shipped defaults apply. ### 5. Bootstrap `.agents/memory/hex.md` Write or update `.agents/memory/hex.md` per [`../hex-core/references/memory.md`](../hex-core/references/memory.md). `hex.md › Preferences` is already written by Step 4½ — this step covers the other two sections: - **`hex.md › Pointers`** — a cache seeded from Step 1's findings: where verification is documented, where the selective test command is documented, where spec/plan/ADR conventions live, the doc and product-knowledge homes provisioned in Step 2, the discussions home when one was resolved, the goals home when one was resolved, key architectural rules, any worktree-location deviation, the constitution location (optional), and the run-cost rows `Build jobs:`, `Hub files:` and `Fresh gate:` when found. Pointers only, never copies — the product-knowledge pointer is how researchers and reviewers reach the product facts that live in project context. - **`hex.md › Memory`** — left empty at bootstrap; the orchestrators maintain it during their own runs. On a re-entrant run, update only what Step 1 found drifted or what the user changed in Steps 2–4½; never rewrite the whole file. `hex.md › Pointers` and `hex.md › Memory` are skill-managed — the orchestrators own them day-to-day; a re-run re-points `hex.md › Pointers` where the audit found drift but clobbers neither section beyond that, and never touches `hex.md › Memory`. A missing `.agents/memory/hex.md` is normal and fully supported — every hex skill falls back to its shipped defaults without one. ### 6. Discovery note (optional) For a client that doesn't already load project context ambiently, or on request: write a 3-line marker-fenced pointer block into the client's context file (template in [`references/audit.md`](references/audit.md#best-practice-blocks)). It only points — never duplicates content from `.agents/memory/hex.md` or from project context. On a re-run, replace the block between the markers in place. ### 7. Summary Close with three short lists: what was audited (pass/gap per item), what was written and where (file → section), and what was proposed but skipped (declined, or not applicable). No prose beyond that. ## Workflow forks (`/hex-init workflows`) `/hex-init workflows` manages **workflow forks** — project-authored tier files that redirect an orchestrator's phase plan. The fork *file format* (node schema, the `Forked from … @ hex <version>` stamp, the `Count` grammar, the seven validation checks) is defined once in [`config.md` § Workflows](../hex-core/references/config.md#workflows); this flow only creates and tracks the files, and asks through the [wizard](#the-wizard): 1. **List** the forkable skill × tier pairs (the orchestrators that ship tier files × `low`/`medium`/`high`/`xhigh`/`max`), each with its shipped phase list and a `[forked]` marker where `workflows.<skill>.<tier>` already points at a file. 2. **Fork.** On selection, copy the shipped `hex-<skill>/tier-<tier>.md` to `.agents/workflows/<skill>-<tier>.md`, prepend the header table derived from its shipped phases, and stamp it per config.md § Workflows (`Forked from hex-<skill>/tier-<tier>.md @ hex <version>` — both validation and drift detection read the stamp). Never overwrite an existing fork. 3. **Edit.** The user edits the copy — delete a phase row and its section, add a role, re-point an edge. 4. **Diff, consent, write.** Print the diff **by cell, not just by phase** — added / removed / re-pointed rows **and** `Roles` / `Count` deltas inside a kept phase, each against the file the stamp names. A narrowed `Roles` cell (e.g. dropping `reviewer:security` from a retained Review-Fix Loop) must surface here — it is the human's one look at the fork before it is wired in, and it is the consent backstop for the [security-reviewer invariant](../hex-core/references/config.md#workflows) (config.md validation check 6). Take the wizard's apply consent, then write the `workflows.<skill>.<tier>` pointer into the Preferences block (Step 4½'s block; `workflows` is vocabulary v2). 5. **Drift on re-audit.** A later `/hex-init` re-audit ([`references/audit.md`](references/audit.md#workflow-fork-stamps-current)) compares each fork's stamped version against the installed hex version; on a mismatch it **reports drift and shows what changed in the shipped tier file** — it never auto-merges and never rewrites the fork. ## Re-entrancy Every property above holds on every run, not just the first: Step 1 always re-audits, including whether existing `hex.md › Pointers` entries and the context-file index lines still resolve; nothing is overwritten without consent; templates are only-if-absent; marker-fenced blocks (the Step 2 best-practice blocks, the Step 6 discovery note) replace in place. Run `hex-init` again any time drift is suspected or the setup needs to change — there is no separate "reconfigure" flow. **The `Preferences` block is user-owned; a re-run never clobbers it.** Deterministic scaffolding (the `hex.md` section skeleton, seeded pointers, marker-fenced blocks) regenerates every run; the fenced `yaml` block does not. Keys the user did not touch keep their values **and their comments** and their existing order; the wizard rewrites only the keys its diff named — changing a value in place while keeping that line's quoting — and a newly added key is appended in the [§ Complete example](../hex-core/references/config.md#complete-example)'s style. A key the block still carries that a later hex version dropped from the vocabulary is **reported deprecated in the Step 7 summary, never silently deleted** — unlike OpenCode/fast-agent, hex has no code layer that can safely auto-rewrite a user-owned block, so deprecated keys are reported, not migrated. If the hand-edited block already carries a key in both the nested and flat spelling that [C-222](../hex-core/references/config.md#dotted-keys) tolerates on read, the wizard surfaces C-222's duplicate-key `Error:`/`Fix:` and leaves the user's spellings untouched rather than collapsing them. ## Structure - `SKILL.md` — this flow. - [`references/audit.md`](references/audit.md) — the audit checklist and the best-practice block templates used in Steps 1, 2, and 6. - `assets/templates/` — the fallback `plan.md`, `adr.md`, `discussion.md`, `research.md`, `spec.md` used in Step 3, and `goal.md`, which only `/hex-loop` instantiates. The reference links above resolve when `hex-core` is installed alongside this skill; if it isn't: `grim add ghcr.io/michael-herwig/arcana/hex-core:latest`. ## Arguments A positional concern narrows the run to one area: `verification`, `conventions`, `worktrees`, `models`, `templates`, or `workflows` (the [fork lifecycle](#workflow-forks-hex-init-workflows) above). Omitted, `hex-init` runs the full flow above. Two flags drive the **non-interactive twin** — the wizard's questions answered without prompting: - `--yes` accepts every recommendation the audit produces, writing the same diff the wizard would, without asking. - `-d key=value` (repeatable) sets one config key directly, e.g. `-d limits.max-workers=6 -d adversary=codex:rescue`. The twin engages automatically when there is **no TTY**, when any `-d` is given, or when `CI` is set. A non-interactive refusal still pairs `Error:` with `Fix:` and **enumerates the accepted values inline** so the correction is paste-able (e.g. `Error: -d adversary=nope unknown. Fix: accepted: <skill-name> | none`). $ARGUMENTS
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.