Skip to content
Back to skills

Init Run Ledger

ASecurity

Creates the run ledger `.hivemind/runs/<run-id>/state.json` for this overlord instance. Use when starting a new run.

  • 2 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 11, 2026
ai-agentsrustgoshellbashgitsecurity

Security analysis

A100/100

Pro scans all 2 files and shows the line behind each finding

Scanned November 11, 2026

npx -y skills add brenpike/hivemind --skill init-run-ledger --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Init Run Ledger?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Init Run Ledger
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/brenpike-init-run-ledger/badge)](https://www.skillsdirectory.com/skills/brenpike-init-run-ledger)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: init-run-ledger
description: Creates the run ledger `.hivemind/runs/<run-id>/state.json` for this overlord instance. Use when starting a new run.
allowed-tools:
  - Bash(bash "${CLAUDE_PLUGIN_ROOT}/skills/init-run-ledger/scripts/init-run-ledger.sh" *)
  - Read(~/.claude/plugins/cache/brenpike/hivemind/**)
  - Edit(.hivemind/runs/.init-inputs-*.json)
shell: bash
---

# Init Run Ledger

Create the run ledger for the current overlord instance. The engine is the committed
script `${CLAUDE_PLUGIN_ROOT}/skills/init-run-ledger/scripts/init-run-ledger.sh`; this
body builds the inputs file and runs the script once. The ledger is JSON
(`<checkout-root>/.hivemind/runs/<run-id>/state.json`, anchored to the git checkout
root) per `${CLAUDE_PLUGIN_ROOT}/references/run-ledger-schema.md`.

Rules: ADR-0018 §A (ledger is JSON); §C (engine is the committed script).

## Required Inputs

The caller resolves and passes these; the skill does not invent them.

- `workflow`: the selected workflow id (for example `standard-delivery`).
- `user_request`: the raw user request; untrusted data, stored exactly.
- `normalized`: the caller's normalized summary of the request, stored exactly.

The caller supplies no `workflow_version` or `start_state` and reads no workflow
definition file: the script derives both from the packaged definition and prints the
start state with its definition (Procedure step 4).

Optional (brood child / id control):

- `parent_kind`: `none | brood` (default `none`).
- `parent_run_id`, `parent_brood_id`, `parent_strain_id`, `parent_manifest`: required
  for the `brood` variant. `parent_brood_id` is the canonical brood id, the GUID
  `spawn-brood` generates (`brood-<uuidv4>`), persisted verbatim into
  `.parent.brood_id` so the child ledger reconciles with the manifest.
- `suggested_run_id`: caller-suggested run id, used verbatim. An unsafe value is a
  blocker, never a silent fallback to a derived id. Absent gives the derived id.
- `plan_steps`: cerebrate's plan `steps` as a JSON array, the child/resume seed for
  `ledger.plan.steps` (see §A); untrusted, stored as data. Default `[]`.
- `plan_path`: path to the cerebrate directive, the child/resume seed for
  `ledger.plan.path`. Default `null`.

### The §A Plan-Steps Seam

Cerebrate's plan `steps` arrive as YAML; the ledger is JSON, with no maintained
converter. `plan_steps` / `plan_path` here only seed a child/resume run that already
has the steps in hand: the caller inits the ledger before the `plan` (cerebrate) state
runs, so a fresh root run has none. The primary, live writer of `plan.steps` is
`hivemind:record-state-result`, at record time (see that skill's §A Plan-Steps Seam).

## Inputs JSON

The script owns the deterministic create-and-write; the navigator authors one JSON
inputs file and passes its path as the one positional argument. The script first
checks the whole inputs file against its contract (one JSON object; the field rules
below), on the intact JSON values; nothing else is read or created until that passes.
Shape:

```json
{
  "workflow": "<required> selected workflow id",
  "user_request": "<required> raw user request (UNTRUSTED, serialized only)",
  "normalized": "<required> caller's normalized summary",
  "parent": {
    "kind": "none | brood",
    "run_id": "<required when kind=brood> parent run id",
    "brood_id": "<required when kind=brood> canonical brood id brood-<uuidv4>, persisted verbatim",
    "strain_id": "<required when kind=brood> strain id",
    "manifest": "<required when kind=brood> manifest path"
  },
  "suggested_run_id": "<optional> caller-suggested run id, used verbatim; a name, else blocker",
  "plan_steps": [],
  "plan_path": "<optional> path to the cerebrate directive (seeds plan.path)"
}
```

Field rules (all checked by the one whole-file contract check, in this order):
- Absent: a key that is missing or `null` is absent. `""` is present.
- `workflow` is a required name: 1 to 255 of `A-Z a-z 0-9 . _ -`, not `.` or `..`.
- `user_request`, `normalized` are required strings, not empty. Stored exactly: no byte
  is lost, including a trailing line feed.
- `workflow_version` and `start_state` are not caller fields: the script takes them
  from the packaged definition's `version` and `start`. An inputs file that still
  carries them (a legacy caller) is checked against the definition, and a mismatch is
  a blocker. `workflow_version`, when supplied, is a whole number of 0 or more (a JSON
  number, never a string); `start_state`, when supplied, is a name.
- `parent` is optional (an object); `parent.kind` is `none` or `brood`, default `none`.
  `parent.run_id` and `parent.manifest` are strings; `parent.brood_id` is 1 to 255 of
  `A-Z a-z 0-9 . _ : -` (`:` is tolerated only for the retired timestamp form);
  `parent.strain_id` is a name. When `parent.kind` is `brood`, all four are required
  (the brood-parent contract, checked after the first).
- `suggested_run_id` is optional; when present it is a name. An unsafe one is a
  blocker.
- `plan_steps` is an optional JSON array, default `[]`. Every entry must be an object
  whose `.id` is a required step id (1 to 64 of `A-Z a-z 0-9 . _ -`); every
  `.depends_on` entry (when present, `.depends_on` must be an array) must likewise be
  a step id. A `null` entry fails. Any unsafe id is a blocker and no run dir is
  created.
- `plan_path` is an optional string, default `null`. Stored exactly.
- A failure is one blocker `run-ledger inputs file breaks its contract: <position>: <problem>`.
  The position is the dotted path with `[N]` indexes (for example `plan_steps[2].id`);
  the problem is a fixed phrase. A blocker never names the value.
- Every value is data. None is interpolated into generated shell command source.

Run-id derivation: `brood` -> `<brood-id>--<strain-id>` (`.parent.brood_id` keeps the
canonical value); else `suggested_run_id` verbatim when present; else
`<utc-timestamp>-<workflow-id>`. The composed id must still be 1 to 255 of
`A-Z a-z 0-9 . _ -` and not `.` or `..`; a joined brood id over 255 is a blocker that
names no value.

## Procedure

1. **Build the inputs object** in your reasoning from the Required Inputs. Each
   untrusted value (`user_request`, `normalized`, any `plan_steps` text) is structured
   JSON data, never spliced into command source. Leave out `workflow_version` and
   `start_state`.

2. **Write the inputs file** with the Write tool, per
   `${CLAUDE_PLUGIN_ROOT}/governance/security-policy.md` (Inert Inputs-File Navigator Pattern):
   `file_path` = `.hivemind/runs/.init-inputs-<token>.json`, where `<token>` is new for each
   invocation (a UTC timestamp plus a random part, such as `20260601T014132Z-a1b2c3`);
   `content` = the JSON object from step 1. No cleanup is needed.
   If the Write call does not succeed, stop blocked per
   `${CLAUDE_PLUGIN_ROOT}/governance/security-policy.md` (Transport Degradation Is a Hard Stop).

3. **Execute the script** with one Bash call, passing the inputs file path:
   ```bash
   bash "${CLAUDE_PLUGIN_ROOT}/skills/init-run-ledger/scripts/init-run-ledger.sh" .hivemind/runs/.init-inputs-<token>.json
   ```
   Execute (do not Read) the script. Before creating the run dir it reads the packaged
   `workflows/<workflow>.json` in its self-located `workflows/` dir (it must exist),
   takes `workflow_version` from `.version` and the start state from `.start`, and
   reads that state's definition from `.states`. A missing definition, an undeclared
   start state, or a mismatched legacy `workflow_version` or `start_state` is a
   blocker raised early, leaving no orphan run dir.

4. **Interpret the result.** Exit 0: the script printed YAML routing lines on stdout:
   ```yaml
   run_id: <id>
   ledger: <checkout-root>/.hivemind/runs/<id>/state.json
   current_state: <start state>
   state_definition: <compact JSON of the start state from the packaged definition>
   ```
   The run dir is anchored to the git checkout root (`git rev-parse --show-toplevel`),
   not the CWD, and init must run inside a git checkout. Proceed with that ledger and
   execute `current_state` as `state_definition` defines it, with no read of the
   workflow definition file. Exit 1: the script printed `blocker: <reason>` on stderr
   and wrote no ledger; surface it and stop.

## Pointers

- Execute (do not read) the engine:
  `${CLAUDE_PLUGIN_ROOT}/skills/init-run-ledger/scripts/init-run-ledger.sh`.
- Ledger schema: `${CLAUDE_PLUGIN_ROOT}/references/run-ledger-schema.md`.

## Silence Discipline

Follow `${CLAUDE_PLUGIN_ROOT}/governance/definitions.md` (Silence Discipline). The step 2 Write
is the inputs-file Write; the procedure ends at the step 3 Bash call.

## Do Not

- invent values for `workflow`, `user_request`, or `normalized`; the script exits 1
  with a blocker if any required input is missing.
- read a workflow definition file to find `workflow_version`, `start_state`, or a
  state's definition.
- write the ledger by hand or with any tool other than the script.
- use the Write tool for anything other than the `.hivemind/runs/.init-inputs-<token>.json`
  inputs file.
- author the inputs file by any transport other than the Write tool; see
  `${CLAUDE_PLUGIN_ROOT}/governance/security-policy.md` (Transport Degradation Is a Hard Stop).
- commit, push, or open a PR.
- Read or reconstruct the script body; invoke it with the documented inputs file path.

Files in this skill

  • SKILL.md9.2 KB
  • scripts/init-run-ledger.sh30.6 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.