Cross-Harness State (MOLT)
Keep durable, harness-agnostic work state inside each repo's .agents/ folder so
the NEXT session — any agent, any machine that syncs the repo — resumes from
files, not from a chat transcript.
Layout
.agents/
STATE.md # NOW: current task + latest progress bullets
JOURNAL.md # HISTORY: dated one-line decisions/changes
handoffs/ # SESSION DOCS: timestamped deep-recovery documents
diagnosis/ # from bug-diagnosis skill (optional)
Create .agents/ in the repo root if absent. These files are committed with the
repo unless it is a private scratch repo; they must never contain secrets.
File Contracts
STATE.md — always reflects NOW
# Agent State
Current task: <one sentence describing the active goal>
Progress:
- Completed <ID/slug> locally: <what changed>. Verification passed: <exact checks>.
<Explicitly what was NOT executed/persisted if relevant.>
- ...
Rules:
- Top of file = current truth. Old completed bullets get compacted: keep last
~10 detailed, compress older ones into one-liners, never delete silently.
- Every bullet ends with verification evidence (tests run, commands checked)
and explicit negative claims where safety matters ("no deploy, no secret
persistence").
- Written AFTER verification, not before.
JOURNAL.md — append-only history
# Agent Journal
- YYYY-MM-DD: <decision or change, one line, past tense>
- ...
One line per meaningful decision/change, newest at top. Include WHY for non-obvious
calls. Never edit old entries; corrections get new entries.
handoffs/ — deep recovery docs
Timestamped YYYY-MM-DD-HHMMSS-<slug>.md documents created via the
session-handoff skill when a task pauses mid-flight or context is nearly full.
STATE.md gets ONE bullet pointing to it ("paused X, see .agents/handoffs/...").
Thin pointer files: any doc elsewhere (plans, specs, maps under .agents/) may be
referenced from STATE.md by path instead of being copied in. STATE stays lean;
pointers stay valid.
Workflow
Session start (resume)
- Read
.agents/STATE.md first, then referenced pointers/handoffs as needed.
- Skim the top of JOURNAL.md for recent decisions (newest entries are first).
- Confirm repo reality matches state (branch, key files exist). If drifted,
update STATE.md noting drift BEFORE working.
During work
- Journal entries at each real decision point.
- Update wizard/ticket/map artifacts in place; STATE points to them.
Session end / milestone (save)
- Add/update the STATE.md "Current task" + progress bullet with verification.
- Append journal lines.
- If pausing mid-task: create a handoff doc (
session-handoff) and link it.
- Commit
.agents/ changes together with related code when possible.
No-Secrets Rules (hard)
- Never write tokens, keys, passwords, connection strings, client IPs of
sensitive infra, or personal data into STATE/JOURNAL/handoffs.
- Reference secrets by NAME only ("uses GITHUB_TOKEN env var").
- Before committing, scan:
rg -n "(?i)(api[_-]?key|token|secret|password)\s*[:=]" .agents
and review hits.
Harness Notes
- Works identically from Codex, Claude Code, Cursor, OpenCode, agy, Muse — plain files, no
tooling required.
- On OneDrive-synced repos, files sync across machines automatically; watch for
sync conflicts after simultaneous edits on two machines — resolve by newest
verified content, then re-append a journal line about the conflict. On
Debian/Linux the same state travels through git instead — commit and push
before switching machines.
Related Skills
session-handoff - creates the deep recovery docs stored in .agents/handoffs/
to-tickets, wayfinder - artifacts STATE.md points to
bug-diagnosis - diagnosis docs under .agents/diagnosis/
Related workflow
For durable architectural rationale, use architecture-decision-records and link the record from STATE/JOURNAL instead of duplicating it. For bounded repeated repair, use bounded-agent-loop; hand off attempts consumed, remaining time and actual test evidence.
1---2name: cross-harness-state3description: >-4 Maintain MOLT-style persistent agent state in a repo's .agents/ folder so any5 harness (Codex, Claude Code, Cursor, OpenCode) can resume work with zero6 ambiguity. Use when starting or ending significant work in a repo, when the7 user says update the state, save progress, journal this, resume from state,8 what were we doing, or when switching agents/machines mid-task and continuity9 must survive.10license: MIT11metadata:12 source: https://skillmd.com/skills/hongyime/cross-harness-state13 author: Local setup14 version: "1.0.0"15 platform: "Codex, Antigravity (agy), OpenCode, Muse, Claude Code, Cursor on Windows, macOS, Linux (Debian)"16---1718# Cross-Harness State (MOLT)1920Keep durable, harness-agnostic work state inside each repo's `.agents/` folder so21the NEXT session — any agent, any machine that syncs the repo — resumes from22files, not from a chat transcript.2324## Layout2526```text27.agents/28 STATE.md # NOW: current task + latest progress bullets29 JOURNAL.md # HISTORY: dated one-line decisions/changes30 handoffs/ # SESSION DOCS: timestamped deep-recovery documents31 diagnosis/ # from bug-diagnosis skill (optional)32```3334Create `.agents/` in the repo root if absent. These files are committed with the35repo unless it is a private scratch repo; they must never contain secrets.3637## File Contracts3839### STATE.md — always reflects NOW4041```markdown42# Agent State4344Current task: <one sentence describing the active goal>4546Progress:47- Completed <ID/slug> locally: <what changed>. Verification passed: <exact checks>.48 <Explicitly what was NOT executed/persisted if relevant.>49- ...50```5152Rules:5354- Top of file = current truth. Old completed bullets get compacted: keep last55 ~10 detailed, compress older ones into one-liners, never delete silently.56- Every bullet ends with verification evidence (tests run, commands checked)57 and explicit negative claims where safety matters ("no deploy, no secret58 persistence").59- Written AFTER verification, not before.6061### JOURNAL.md — append-only history6263```markdown64# Agent Journal6566- YYYY-MM-DD: <decision or change, one line, past tense>67- ...68```6970One line per meaningful decision/change, newest at top. Include WHY for non-obvious71calls. Never edit old entries; corrections get new entries.7273### handoffs/ — deep recovery docs7475Timestamped `YYYY-MM-DD-HHMMSS-<slug>.md` documents created via the76`session-handoff` skill when a task pauses mid-flight or context is nearly full.77STATE.md gets ONE bullet pointing to it ("paused X, see .agents/handoffs/...").7879Thin pointer files: any doc elsewhere (plans, specs, maps under `.agents/`) may be80referenced from STATE.md by path instead of being copied in. STATE stays lean;81pointers stay valid.8283## Workflow8485### Session start (resume)86871. Read `.agents/STATE.md` first, then referenced pointers/handoffs as needed.882. Skim the top of JOURNAL.md for recent decisions (newest entries are first).893. Confirm repo reality matches state (branch, key files exist). If drifted,90 update STATE.md noting drift BEFORE working.9192### During work9394- Journal entries at each real decision point.95- Update wizard/ticket/map artifacts in place; STATE points to them.9697### Session end / milestone (save)98991. Add/update the STATE.md "Current task" + progress bullet with verification.1002. Append journal lines.1013. If pausing mid-task: create a handoff doc (`session-handoff`) and link it.1024. Commit `.agents/` changes together with related code when possible.103104## No-Secrets Rules (hard)105106- Never write tokens, keys, passwords, connection strings, client IPs of107 sensitive infra, or personal data into STATE/JOURNAL/handoffs.108- Reference secrets by NAME only ("uses GITHUB_TOKEN env var").109- Before committing, scan: `rg -n "(?i)(api[_-]?key|token|secret|password)\s*[:=]" .agents`110 and review hits.111112## Harness Notes113114- Works identically from Codex, Claude Code, Cursor, OpenCode, agy, Muse — plain files, no115 tooling required.116- On OneDrive-synced repos, files sync across machines automatically; watch for117 sync conflicts after simultaneous edits on two machines — resolve by newest118 verified content, then re-append a journal line about the conflict. On119 Debian/Linux the same state travels through git instead — commit and push120 before switching machines.121122## Related Skills123124- `session-handoff` - creates the deep recovery docs stored in `.agents/handoffs/`125- `to-tickets`, `wayfinder` - artifacts STATE.md points to126- `bug-diagnosis` - diagnosis docs under `.agents/diagnosis/`127128## Related workflow129130For durable architectural rationale, use `architecture-decision-records` and link the record from STATE/JOURNAL instead of duplicating it. For bounded repeated repair, use `bounded-agent-loop`; hand off attempts consumed, remaining time and actual test evidence.