Stateroot

StateRoot

StateRoot gives a project one persistent state of record that any agent harness (Claude Code, Codex, Cursor, OpenCode, Kimi Code, OpenClaw, Hermes, StateSmith) can attach to. This skill is the behavioral contract for working in a stateroot project. Follow it mechanically, every session.

When To Use

1. the project root contains a .stateroot/ directory, or stateroot status reports an attached project
2. starting, continuing, or handing off work in such a project

When Not To Use

Do not use this skill when:

1. the project is not stateroot-initialized and the user has not asked to initialize it (suggest stateroot init instead)
2. the task is unrelated to project work (casual Q&A, one-off questions)

Hard Rules

0) Shared rules (constitution)

StateRoot keeps a shared rules pool — same idea as skills and learnings. Product-intent ships by default. Rules from other harnesses (Cursor .mdc, Codex/Claude AGENTS.md/CLAUDE.md, …) are pulled in on stateroot rules sync (also run by init / install).

Before any architectural or behavioral change, read stateroot rules show product-intent. Preserve product intent. Do not replace agent judgment with classifiers, approval gates, or generic architecture. Do not add friction "because it seems safer." Follow imported harness rules in the pool as well (stateroot rules list).

Keep the tool fresh (updates)

When the digest notes Update available: <tag>, run stateroot self-update — it re-arms harness wiring automatically. Otherwise run stateroot self-update --check occasionally; the CLI and this skill improve often. Never update mid-task: finish the step, checkpoint, then update.

Capabilities are pooled — delegate, never refuse

Skills and capabilities are shared across harnesses. When the user asks for a capability you lack natively (image generation, docs of another vendor, a harness-specific automation, …):

1. check the digest's Shared Capabilities section or stateroot skill list for a reference_only capability another harness owns
2. answer with the path, not a refusal: "I can't natively — but codex can. Say the word and I delegate."
3. on an explicit ask, delegate the bounded microtask: stateroot delegate --to <harness> --skill <slug> --task "<task>" — then inspect the produced outputs; do not replay the foreign transcript
4. never claim another harness's capability as your own: say which harness would do it

Identity changes are soul changes — never learnings, never memory

When the user asks to change the agent's personality, voice, name, character, or boundaries (anything about who you are or how you speak):

1. that is a soul change, full stop — not a learning (taste for work), not a memory (facts about the project)
2. write it to the canonical soul: stateroot soul propose --stdin (pipe the updated soul) or soul edit — it lands in ~/.stateroot/soul/SOUL.md with a history snapshot
3. soul sync then pushes it to every harness's native persona files (openclaw, hermes) — the change propagates to all harnesses at their next session
4. the digest identity hash changes on adoption, so every harness re-anchors with a FULL injection automatically

1) Session start -> consume identity, resume only as fallback

At the start of every session in a stateroot project, before doing any work:

1. consume the auto-injected StateRoot digest (persona + USER.md + work body) when the harness put it in context. Automatic harnesses inject on session-start and/or the first prompt. Do not wait to be asked who you are.
2. only run the harness-specific resume (e.g. stateroot resume --harness cursor / --harness codex / --harness claude / --harness kimi) — or scripts/resume.sh --harness <id> — if no identity/resume digest appeared. Manual resume is the last fallback, not the primary reliability mechanism. Degraded harnesses (Hermes, Copilot, Crush) need this fallback. Hook-less sessions (IDE/ACP integrations fire no hooks) never receive the digest — there resume at session start is required, not a fallback, and stateroot resume --force after any context compaction re-anchors identity.
3. treat that entire output — current handoff, hot-apex memory, context pack — as the project state of record
4. never truncate resume or the hook digest. Run the command as-is. Do not pipe it through head, tail, less, sed, awk, cut, wc, or any line/byte limiter. Do not add --budget. The CLI already sized the digest. A clipped resume is a corrupted state of record.
5. do not run resume again in the same session unless the user explicitly asks (--force reprints)
6. do not re-derive project state by scanning the tree when resume already answers the question

2) State-changing step -> checkpoint

After completing ANY step that changes project state (files written, decisions made, milestones reached, blockers discovered, approaches abandoned):

1. run scripts/checkpoint.sh --note "<what changed and why>" [--files a,b]
2. keep the note specific: what changed, why, and what it unblocks
3. checkpoint the finished step BEFORE starting the next one; never batch several finished steps into one checkpoint

3) Before attempting an approach -> check failed approaches

Before attempting any non-trivial approach:

1. run scripts/search.sh "failed approach <topic>" (wraps stateroot memory recall) or read failed_approaches in the current handoff
2. if a matching failure exists, do not repeat it — state explicitly why the new attempt differs

The flagship flow: plan in one harness, implement in another

When the user asks you to make a plan that another harness will implement — or any time a plan should outlive your session:

1. Record the plan in the shared store, never only in your harness's native plan location (~/.claude/plans/, ~/.cursor/plans/, plan-mode files):
   • write the plan body and run stateroot plan record --stdin --title "<title>" (pipe the body), or --from <your-harness>
   • on harnesses with native plan mode: author in plan mode as usual, then record the same body into the store before exiting plan mode (--file <path> exists to ingest that existing plan-mode file)
   • never author a plan markdown inside the project repo just to hand it off — repo docs are project artifacts; the shared store carries the plan and the executor reads it with stateroot plan show <id>
2. Hand it off: stateroot handoff write --from <you> --to <target harness> --objective "…" --task "Execute recorded plan <id> (stateroot plan show <id>)" [...] — the store auto-attaches the approved/active plan's plan_ref to the handoff
3. The executor's digest then says "execute this plan; do not re-plan or re-explore" — approve with stateroot plan approve <id> when the user has reviewed. For parallel work, materialize one sibling fork per plan with stateroot fork <root> --worktree <path> --plan <id>, then activate that plan inside its fork worktree. Activation is one-per-checkout, not one-per-project: independent forks activate independently.
4. Harness-native plans written in native plan mode DO federate in automatically at session boundaries (as drafts) — but the record-then-handoff path is immediate and deliberate; use it when the plan is meant for another harness NOW

Integrating parallel forks (appointed coordinator)

When fork lineages are ready to fold into the trunk and the user appoints you to coordinate the integration:

1. stateroot merge --prepare <fork>… --json freezes the trunk tip and every fork tip and returns a durable attempt: ready when clean, attention with exact conflict paths/kinds when not. Preparing changes no refs or worktrees.
2. ready → stateroot merge --continue <attempt> publishes one N+1-parent root (frozen refs are CAS-revalidated first).
3. attention → the attempt record names a machine-local reconciliation worktree: the accumulated clean fold with every text conflict rendered with standard markers (trunk (accumulated fold) vs fork <name>). Edit and test in that worktree, then stateroot merge --continue <attempt> --evidence "<tests you ran>". Continue refuses while markers remain and refuses stale frozen refs — prepare again after any source moved. Never resolve by silently picking a side; the reconciled worktree IS the resolution.
4. stateroot merge --status <attempt> --json is read-only; --abort <attempt> removes only attempt-local state.
5. Merged fork worktrees are marked cleanup_pending (the merge never waits on deletion); stateroot merge --cleanup <fork>… is bounded and idempotent.
6. stateroot merge <fork>… without --prepare still runs the one-shot deterministic fold; conflicts report paths and create no root.

2b) Work-state lineage -> automatic snap

Lineage does not depend on you remembering: stateroot checkpoint and the turn-end (stop) hook automatically snap the working tree whenever project files actually changed (.stateroot/ bookkeeping alone never creates a root). Automatic snaps run with a bounded scan budget — a dependency-heavy tree skips the root but never the checkpoint; stateroot doctor names the heavy paths and the exact ignore lines, and an explicit stateroot snap always performs the deliberate full scan.

1. explicit milestones: run stateroot snap [--reason "..."] to record a root on demand under refs/stateroot
2. use stateroot log / stateroot show <root> to inspect lineage; stateroot diff / stateroot compare for deltas
3. use stateroot revert <root> only for verified restoration (append-only — creates a new root)
4. use stateroot fork <root> when divergent work should branch from an earlier root; integrate finished forks with stateroot merge (see Integrating parallel forks)
5. handoff carries session continuity — it does not replace snap/revert/fork lineage

4) Session end / usage limit / harness switch -> handoff

Before ending a session, when approaching usage limits, or when the user asks to switch harness:

1. prefer a flag-first one-liner: scripts/handoff.sh write --from <resolved-current-harness> [--to <harness>] --objective "…" --task "…" --context-summary "…" [--next "…"] — one command, no temp JSON
2. omit --to for continuity-only; use it only when orchestrating a cross-harness switch; when continuity suffices and hooks may not run, stateroot handoff finalize is acceptable — or rely on session_end/stop hook finalize when it ran
3. resolve --from to the actual current harness id; never copy a placeholder or infer it from an environment variable
4. include the durable objective, immediate task (--task, not immediate_task), detailed continuity narrative, decisions, next actions, and truthful failures; the CLI auto-captures recent verified conversation when author content is absent
5. use --input <handoff.json> only when the payload is too large for flags; never write under .stateroot/handoffs/ by hand
6. thin fields warn; they do not refuse the write — continuity beats form-filling
7. do not paste giant state or transcript dumps into --note; --note is only a legacy short-summary fallback
8. never invent a second approval story — learnings, soul, skills, memory, and distill activate immediately

5) Never edit .stateroot/ directly

All reads and writes of project state go through the CLI. Do not open, edit, move, or delete files under .stateroot/ with file tools or shell commands — the CLI maintains revisions, indexes, and outbox consistency.

6) Offline behavior

The CLI is offline-safe: when the server is unreachable it queues operations in the local outbox and still exits successfully. Therefore:

1. checkpoint and hand off anyway — never skip a checkpoint because of connectivity
2. do not re-issue the same queued operation in a retry loop
3. never hand-edit outbox files

Command Reference

Failure Modes

Output Discipline

1. after resume: tell the user the objective, current state, and next actions in 2-3 sentences. That summary does not replace reading the full digest — you must ingest every section, including the observed context pack.
2. after checkpoint or handoff: confirm in one line what was recorded
3. never paste raw .stateroot/ file contents into the transcript — quote CLI output instead
4. never clip CLI state commands (resume, status, doctor, log, handoff show) with head/tail/pagers. If a tool UI offers "limit output", disable it for these commands.

References And Assets

Read as needed:

• references/protocol.md — checkpoint cadence, handoff packet fields, offline outbox semantics
• references/learnings.md — quality bar, examples, anti-examples for learn record
• references/harnesses.md — per-harness install layout
• assets/ — harness stub templates used by stateroot skill install
• scripts/ — thin wrappers: resume.sh, checkpoint.sh, handoff.sh, search.sh

Learnings (taste — not memory)

Learnings are durable preferences: how the next harness should judge a choice when two valid options exist. They are the StateRoot equivalent of CommandCode taste. They are not a wiki, not a layout dump, and not a fact log.

learn_record always writes a learning. Facts go to memory / memory_save (curated MEMORY.md). Procedures go to skill_propose. Pull long-term knowledge with memory_recall or wiki_show — page bodies are not dumped into the digest.

Layers

• Global (user): stateroot learn record --user "…" or MCP learn_record with scope: "user" — communication, recurring methods, design/engineering judgment, boundaries that follow this human across repos.
• Workspace: stateroot learn record --workspace "…" or MCP scope: "workspace" — org-wide bars shared across projects in the same workspace registry id.
• Domain: stateroot learn record --domain <slug> "…" or MCP scope: "domain:<slug>" — taste shared across repos bound to that domain slug in the project manifest.
• Project: stateroot learn record "…" or MCP learn_record with scope: "project" — this repo's quality bars, preferred patterns, anti-patterns.

Read first: stateroot learnings list, stateroot learnings list --user, stateroot learnings list --workspace, and stateroot learnings list --domain <slug>. Update rather than duplicate.

When to write

1. the user corrects you
2. the user states a durable preference
3. first session after stateroot init, if a layer is empty — seed 2–7 evidenced judgments, then stop. Evidence means a user correction, a real failure, or completed work this session — never a decision or intention you formed moments ago. Seed at wrap-up or between tasks; the user's task always outranks seeding
4. you just followed a rule the next harness would otherwise miss

When not to write

• inventory ("this is a TypeScript/Python monorepo", "uses uv") → memory_save / memory if it must persist at all
• facts (deadline, version, port, "the dashboard is graphite") → memory_save (or memory add/replace)
• slogans ("write good code", "be careful", "prefer evidence")
• intentions ("ask before planning", "write the plan file now") — a decision you just made is not a learning
• session recap, directory listings, one-off notes
• anything already in learnings list
• anything re-read from an empty store — an empty layer is a terminal answer; do not re-poll it

Format (required)

One learn record call per learning. The note must stand alone so another harness can apply it without this session:

<judgment>. <when it applies / what to do / what never to do>.

Good:

• Prefer small, reviewable diffs over rewrites. Touch only files that implement the asked change; do not restyle or restructure adjacent code.
• Server-side tools must never include arbitrary command execution. exec belongs on the client.
• Always read .gitignore before exploring a codebase so ignored trees do not pollute context.
• When two designs are valid, prefer the restrained, practical one. Do not add architecture from another project without fitting this one.

Bad:

• Laiq is a TypeScript/Python monorepo — fact
• prefer evidence over assertion — too thin; no when, no never
• the deploy uses systemd — inventory

First session after init: seed whichever layer is empty with this quality bar at wrap-up or between tasks — never before or instead of the user's first request. Later harnesses inherit and must keep both current.