spike-start

Stratum

An agent harness for Claude Code. Stratum runs every change through a lane sized by its impact: a main session (the orchestrator) plans with you, hands the work to st-* subagents, checks what they return, and stops at a few clear gates for your decision.

Stratum merges two workflows and adds its own layer:

• GitHub Spec Kit: the spec, plan, and tasks files, and their templates.
• vibecode-pro-max (RIPER-5): role agents for validate, build, test, review, debug, and git.
• Stratum's own layer: lane selection, the build loop, a git guard, a session handoff, a statusline, and forked design and navigation tools, all shipped as one plugin.

The full design and the reason for each choice are in DESIGN.md.

Install

Stratum is a Claude Code plugin and its own marketplace.

claude plugin marketplace add HyuseCS/stratum
claude plugin install stratum@stratum --scope project

Then, in a new session in your project:

/stratum:st-init

st-init creates the project's .stratum/ files and specs/, asks for the git guard modes and any model overrides, asks for the advisor mode, grills you for the project's rules (the constitution), writes the AGENTS.md and CLAUDE.md pointers, sets the statusline and asks for its theme, shape and Token Weather line, turns off a global ponytail or Token Weather plugin for this project, offers to upgrade graphify, installs its post-commit hook, and checks your tools.

Requirements

Use

Describe the work. Stratum picks the lane:

/stratum:st add a parent notice when the bus is 10 minutes away

It answers with one line, for example Lane: full (privacy and access: new notice to parents). Say full, fast, or quick to override.

Lanes

The lane follows the highest impact area the change touches.

Full lane: five phases and three gates.

Fast lane: a short change plan in specs/<feature>/changes/, your OK, test-first build, st-review, commit, drift fix and shortcut list, commit docs.

Quick lane: one file, no gate, related tests, commit. A small fix across a few files goes to st-build in brief mode. It moves up a lane if it needs a change plan.

Design lane: a new look or a new page or screen. New look: a grill for the design file, one reference screen, its checks, your yes. Autonomous: the page in the existing look, checked, then your OK.

Skills

All skills are called as /stratum:<name>.

Agents

The Model column is the plugin default. st-init's template runs st-build, st-debug, st-quick, st-plan, and st-fast on Opus with effort high, and st-close, st-git, and st-test on Haiku with effort xhigh. See Model overrides under Built in.

Every agent reads the SR-OPUS-5 communication contract first and finds files graph first, then search, then read. Code-writing agents carry the ponytail rule and add no explanatory comments.

Project files

.stratum/
├── constitution.md      project rules (committed)
├── state.json           current feature, phase, lane (committed)
├── advisor.json         advisor mode (codex, both, off), optional Codex model and effort (committed)
├── templates/           optional overrides of plugin templates (committed)
├── handoff.md           session handoff (git-ignored)
├── powerline.json       statusline theme, shape, colors (git-ignored, per machine)
├── git-guard.json       git guard modes for this repo (git-ignored, per machine)
├── models.json         agent model and effort overrides (git-ignored, per machine)
└── weather.json         Token Weather growth and compact point (git-ignored)
specs/NNN-feature/       spec, plan, research, data model, contracts, quickstart, tasks, checklists/, changes/, advisor.md
AGENTS.md, CLAUDE.md     point every tool at the constitution

Templates and scripts stay in the plugin. A file in .stratum/templates/ overrides the plugin's copy for that project only.

Built in

• Advisor. Codex (OpenAI's codex CLI), a model from another vendor, runs at two points in the Full lane. At the end of the Plan phase, before its gate, it only advises on a simpler or better approach and does not validate the plan (st-inspect does that). It also reviews a test still red after two tries. The full diff before the build is called done and the whole Fast lane use /advisor if you set one. The Quick lane has no advisor. The orchestrator runs scripts/st-advisor.sh in the foreground and waits for the answer. Codex runs in the read-only sandbox and only reviews: it never builds or fixes. It answers APPROVED, REVISE (findings, checked against the source like any finding, then one more run, two rounds at most), or BLOCKED (the orchestrator stops and asks you). A failed, empty, malformed or late answer (540 seconds) is BLOCKED, never approval. Each run appends the point, a SHA256 of the input, the verdict and the findings to specs/<feature>/advisor.md. An approval of a plan that changed since then is stale. What leaves the machine: each call sends the prompt and the files Codex reads to OpenAI, on your Codex login and quota (about 37,000 tokens per plan review). At the plan point the prompt names the plan files and Codex reads them; at the test point it holds the task text, the test path and both failure outputs. The prompt tells Codex to stay inside the named inputs, never open env or secret files, and never quote a secret value. The sandbox does not block reads. Whether Codex's own shell sees your environment variables is not checked. .stratum/advisor.json sets the mode: {"mode": "codex"}, {"mode": "both"} (Codex, then /advisor if you set one), or {"mode": "off"}. "mode": "off" is the off switch: nothing goes to OpenAI. With no file the advisor is off and prints no advisor: mode not set. Write .stratum/advisor.json with "mode": "codex", "both" or "off". st-init writes the file for new projects. A project set up before this feature has no file, so the advisor stays off until you write it. With no codex on PATH you get one line, no advisor: codex not found, and the flow runs as before, with /advisor if you set one. Optional model and effort keys in the same file pick the Codex model and reasoning effort, for example {"mode": "codex", "model": "gpt-6-astra", "effort": "high"}. Without them Codex uses its own default. The call runs with --ignore-user-config: neither ~/.codex/config.toml nor a project .codex/config.toml is read, so no MCP server, hook or notify command from them runs during a review, and the model and effort come only from this file. Your Codex login works as before.
• Git guard. One mode per command: commit, worktree_remove, worktree_prune, branch_delete, reset_hard, clean (clean -f), discard (checkout ., restore .), and force_push. Each is auto (runs), ask, or deny (blocked). The guard reads the repo's .stratum/git-guard.json first (st-init writes it), then the plugin option of the same name from /config or /plugin config, which is global to the machine. The default is ask. A commit that asks or is blocked shows a staged-file summary. Push, rebase, and commit --amend always ask. git config writes, git add -A, git add ., and --no-verify are always blocked. Remote branch delete is blocked: you delete remote branches yourself. commit: auto runs only in this checkout. A commit asks when cd, pushd or -C points at another checkout, or with --git-dir, --work-tree, or a GIT_DIR= or GIT_WORK_TREE= prefix. merge, pull, cherry-pick, revert and am there ask too. update-ref, branch -f, -M or -C, and a fetch or pull with a <src>:<dst> refspec always ask: they move a branch with no commit. -c core.hooksPath is blocked like --no-verify, and -c alias.* asks. A command the guard cannot parse asks. Known gap: an env, export, sudo, nice, nohup or timeout wrapper, or a GIT_CONFIG_* override, is not checked.
• Worker guard. st-worker writes the worker's guard file with commit: auto and its branch. Commit and the merge family run without a question only while that branch is checked out. st-worker.sh close deletes the file, and refuses while the branch has an open PR.
• PR flow. Every merge into main goes through its GitHub PR, never a local merge. The session that works a branch opens its own PR with st-pr and stays open until it is merged. Nothing merges before you test it. An Approve at the st-pr gate counts as "push". A worker whose branch goes to main opens its own PR.
• Model overrides. .stratum/models.json maps an agent name to an optional model and effort, for example { "st-close": { "model": "haiku", "effort": "xhigh" } }. Agents: st-build, st-close, st-debug, st-design, st-fast, st-git, st-impeccable, st-inspect, st-plan, st-ponytail-audit, st-ponytail-debt, st-quick, st-review, st-test, st-triage. Models: sonnet, opus, haiku, fable. Efforts: low, medium, high, xhigh, max. st-init writes it from templates/models.json: st-build, st-debug, st-quick, st-plan, st-fast on opus with effort high, and st-close, st-git, st-test on haiku with effort xhigh. st-inspect and st-review have no entry and keep the plugin default. st-design, st-impeccable, st-ponytail-audit, st-ponytail-debt and st-triage have no entry either. A hook applies the file each time a Stratum agent starts, so the next start picks up an edit. A bad file blocks every Stratum agent start with a message that names the problem. Only Stratum agents are affected. CLAUDE_CODE_EFFORT_LEVEL beats the file's effort. The per-call effort needs Claude Code 2.1.292 or later. On an older client, remove the effort keys from the file. A linked worktree has no models.json: it is git-ignored and scripts/st-worktree.sh does not link it, so agents there use the plugin defaults, as with git-guard.json. To change an entry, run /stratum:st-model st-close opus, say it in plain words ("make st-close use opus"), or edit the file.
• Session handoff. st-handoff writes the goal, decisions, open questions, and next step. Mid-session it runs in a background fork that has the whole conversation, so you keep talking. When you say you are done, it runs in the main session. A hook adds a facts block (branch, phase, tasks done, last commits, uncommitted files) at session end and before compaction. The next session starts by reading it.
• Background audits. Say "run st-ponytail-audit in the background" (or st-ponytail-debt, an st-impeccable audit, or st-review). The agent of the same name runs it read-only while you keep talking, and its report comes back. Any other skill runs only in the main session.
• Phase tracking. A hook sets phase and lane in .stratum/state.json when a phase skill, st-fast, st-quick or st-full starts, whether you type /stratum:st-plan or the orchestrator starts it. A phase out of order gets one warning, then runs.
• Who is speaking. Each reply starts with a label: [Full lane | Plan], [Fast lane] or [Quick lane] while a lane runs, else [Orchestrator]. The phase hook adds the label from state.json; the st-close agent (Full and Fast lanes) or the st-quick agent (Quick lane) sets phase to done at the end of its run. After you upgrade, a project whose last feature is finished may still show its old phase: set phase to done once. Each Agent call is named with only its task, like US1 review, and each agent's report starts with its tag, like [st-build].
• Verify in one call. After a subagent builds, the orchestrator runs scripts/st-verify.sh '<test command>' <files>. It re-runs the test and checks the listed files (new ones too) for added comment lines, and prints one ok or FAIL line, so each check is one short call.
• Statusline. A powerline in two lines. Line 1: Stratum, project path, and session length on the left, git branch on the right. Line 2: model with its thinking level, and ponytail on the left, the commit option on the right. Each line fits the terminal width: the path becomes the folder name, other segments get shorter, then drop. The branch and the commit option always stay. See Statusline colors.
• Token Weather. A context forecast as the statusline's third line, from ☀ Clear to ↯ Compact soon, with a fill bar and tokens used on the left and the turns left before auto-compaction on the right: ☂ Showers ━━━━━━━━━━━━──────── 600k/1M about 4 turns left.
• Parallel sessions. scripts/st-worktree.sh <branch> <name> makes a sibling worktree that shares this project's local settings and Claude memory. Worktrees and branches stay until you delete them.

Statusline colors

The defaults are in statusline/powerline.json (rose-pine). To change them for one project, create .stratum/powerline.json. Its keys merge over the defaults. Git ignores it, so each person keeps their own look.

Pick a theme: rose-pine, nord, tokyo-night, gruvbox, dark, or light. All segments and the Token Weather line follow it. Pick a shape: arrow (default), rounded, slanted, blocks, or flat (colored text, no backgrounds). arrow, rounded, and slanted need a Nerd Font. /stratum:st-shape <shape> and /stratum:st-theme <theme> set them for you.

Claude Code draws the statusline a few columns narrower than the terminal and cuts what does not fit with …. Each line leaves reserve columns free (default 8). If the right side is still cut, raise it: { "reserve": 10 }.

To hide the Token Weather line, set { "weather": false }.

The Stratum label starts with a Nerd Font layers icon (󰌨). Set "logo" to another character, or to "" for none. The font itself comes from your terminal settings.

{ "theme": "nord", "shape": "rounded" }

Or set your own colors. Keys you leave out keep the rose-pine color.

{
  "theme": "custom",
  "colors": {
    "custom": {
      "git": { "bg": "#1f1d2e", "fg": "#9ccfd8" },
      "ponytail": { "bg": "#2a273f", "fg": "#eb6f92" },
      "stratum": { "bg": "#191724", "fg": "#ebbcba" },
      "commit": { "bg": "#1f1d2e", "auto": "#9ccfd8", "ask": "#f6c177", "deny": "#eb6f92" }
    }
  }
}

Other keys: directory (project folder), model, and metrics (session length). The stratum label uses the model colors unless you set it. Other color options from the claude-powerline docs also work here.

Duplicate installs

If ponytail, impeccable, ui-ux-pro-max, graphify's skill, grilling, or hallmark are also installed globally, their hooks or skills can run twice. st-init turns off a global ponytail or Token Weather plugin in the project's .claude/settings.json. st-status lists the rest. Turn the global ones off for projects that use Stratum.

Maintaining the forks

Stratum owns modified copies of its sources. vendor.lock pins each upstream commit. Once a month, run /stratum:st-sync in this repo: it lists upstream changes since the pin, drafts the ports, and waits for review before updating vendor.lock.

Tests

python3 tests/test_git_guard.py
python3 tests/test_model_hook.py
python3 tests/test_phase_hook.py
bash tests/test_advisor.sh
bash tests/test_design_check.sh
bash tests/test_design_lane.sh
bash tests/test_model_files.sh
bash tests/test_herdr_workspace.sh
bash tests/test_inspect.sh
bash tests/test_on_demand.sh
bash tests/test_pr_skill.sh
bash tests/test_session_hooks.sh
bash tests/test_shortcuts.sh
bash tests/test_st_worker.sh
bash tests/test_statusline.sh
bash tests/test_verify.sh
node tests/test_token_weather.mjs
node tests/test_pr_workflow.mjs
claude plugin validate .claude-plugin/plugin.json

Credits and license

Stratum is MIT licensed. It contains modified copies of GitHub Spec Kit, vibecode-pro-max-kit, ponytail, mattpocock/skills, ui-ux-pro-max, impeccable, frontend-design, graphify's skill, Token Weather, and the theme colors of claude-powerline, each under its own MIT or Apache-2.0 license. See THIRD_PARTY_NOTICES.md and licenses/.