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: 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.

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 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.
• 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 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.
• 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.
• 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.
• 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? See references/audit.md.
• 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.
• 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)
• 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)

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 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). 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:

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 (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) 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 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 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