maintain-project-state
Skill2 starsChanged 9 days agoMITView on GitHub
Resume, save and recover the workspace state. Use at session start, before a handoff or context compaction, after an abrupt stop, or when ws check reports errors.
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- save-session-logSkill
- spec-workflowSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 0 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Keep docs/state/ current so the next session can continue without the chat.
- Very specific: line 12
Run python .agents/tools/ws.py brief.
- Very specific: line 13
Run the command under "Next" in the brief.
- Very specific: line 15
If ws start lists unsaved files, open each one and sort it with the table below.
- Very specific: line 16
If recovery_notes names a running job or a long command, check whether it finished and what it changed before you run it again: a second …
- Very specific: line 19
Before the first code change, run the current task's acceptance once.
- Very specific: line 61
Run ws compact when ws check warns about size or after a milestone.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Maintain project state
Keep docs/state/ current so the next session can continue without the chat.
Resume
- Run
python .agents/tools/ws.py brief. Handle its Attention section first, then read the T0 files it names. - Run the command under "Next" in the brief. When it says "do not claim", another window is working:
ask the user, and read
.agents/guides/PROTOCOL.md"Ownership" before you write anything. - If
ws startlists unsaved files, open each one and sort it with the table below. - If
recovery_notesnames a running job or a long command, check whether it finished and what it changed before you run it again: a second run may repeat a deploy or a write. - Record what you found:
ws card --set recovery_notes="...". - Before the first code change, run the current task's acceptance once. A failure that was there
before your change is the baseline; write it in
recovery_notesso it is not blamed on your work.
| An unsaved file is | Do |
| Product code or a state file the last task changed, and complete | Run that task's acceptance; record the result with ws verify |
Half-done, matching the card's current_task or stop_point | Finish it as that task, or set the task back to todo with a reason |
| A scratch script, probe output or report from another project | Move it to .tmp/ or its project; add a generated path to exclude |
| Not explained by the card, the tasks or the notes | Do not delete or seal it. Ask the user, and record it in recovery_notes |
Save
| Moment | Command |
| Every few turns, or after a finding worth keeping | ws note "..." |
| After a verified step | ws checkpoint --keep --stop "..." --next "..." |
| Before a long or risky command | ws card --set recovery_notes="running X; if it dies, check Y" |
| Context nearly full, or the user switches tools | ws checkpoint --stop "..." --next "..." |
| Brief or checkpoint reports unreconciled messages | ws reconcile, then answer each listed message |
The stop point names the exact state: file, function, test result. The next step is an action a new session can start without asking.
Recover
ws reports | Do |
NOT READY: REQUIREMENTS.md has a goal but no requirement rows | Record the confirmed requirements from the conversation, then checkpoint again |
checkpoint refused | Fix each listed error. If you cannot, add <!-- SYNC-PENDING --> under "Unfinished work" in HANDOFF.md, describe the gap and checkpoint again with --keep: the card is saved without a seal and READY waits for the fix |
this session runs with WS_ROLE set | You are a subagent or helper. Report to the session that started you; do not write state |
wrote N min ago; another conversation may still be working | Do not take over. Ask the user which window continues |
revision conflict or took over the workspace | Another session is active. Stop writing and re-read HANDOFF.md |
| a broken table with file and line | Repair that row by hand, then run ws check |
change rejected; no change can be checked until these are repaired | Repair what it lists first: a broken row by hand, a changed or missing archive file from version control or a snapshot. Ask the user before you touch the CONTINUITY line |
files changed after the last checkpoint | Inspect them, then checkpoint |
owns the workspace from another window that is still running | Do not write. Ask the user; if that window is finished, ws start --force --reason "<what the user said>" |
another ws.py command is running | Wait and retry: another window runs a ws command, and the lock ends with that process, so delete nothing. If the message names WS_LOCK=legacy, the drive cannot lock; move the project to a local disk |
<ID> was removed. IDs are permanent | Restore the row, or close it and run ws compact |
ws cannot run (no shell, no Python) | Edit the tables by hand in the PROTOCOL.md formats; run ws check when it can run again |
Size
Run ws compact when ws check warns about size or after a milestone.
It moves closed rows to docs/logs/CLOSED_ITEMS.md and rolls long logs. IDs stay reserved.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

