agentleFS
yourhoneypomelo-cellyourhoneypomelo-cell/agent-workspace-template/.agents/skills/maintain-project-state/SKILL.md

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.

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
  1. Very specific:

    Keep docs/state/ current so the next session can continue without the chat.

    line 8
  2. Very specific:

    Run python .agents/tools/ws.py brief.

    line 12
  3. Very specific:

    Run the command under "Next" in the brief.

    line 13
  4. Very specific:

    If ws start lists unsaved files, open each one and sort it with the table below.

    line 15
  5. Very specific:

    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 …

    line 16
  6. Very specific:

    Before the first code change, run the current task's acceptance once.

    line 19
  7. Very specific:

    Run ws compact when ws check warns about size or after a milestone.

    line 61

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Maintain project state

Keep docs/state/ current so the next session can continue without the chat.

Resume

  1. Run python .agents/tools/ws.py brief. Handle its Attention section first, then read the T0 files it names.
  2. 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.
  3. If ws start lists unsaved files, open each one and sort it with the table below.
  4. 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 run may repeat a deploy or a write.
  5. Record what you found: ws card --set recovery_notes="...".
  6. 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_notes so it is not blamed on your work.
An unsaved file isDo
Product code or a state file the last task changed, and completeRun that task's acceptance; record the result with ws verify
Half-done, matching the card's current_task or stop_pointFinish it as that task, or set the task back to todo with a reason
A scratch script, probe output or report from another projectMove it to .tmp/ or its project; add a generated path to exclude
Not explained by the card, the tasks or the notesDo not delete or seal it. Ask the user, and record it in recovery_notes

Save

MomentCommand
Every few turns, or after a finding worth keepingws note "..."
After a verified stepws checkpoint --keep --stop "..." --next "..."
Before a long or risky commandws card --set recovery_notes="running X; if it dies, check Y"
Context nearly full, or the user switches toolsws checkpoint --stop "..." --next "..."
Brief or checkpoint reports unreconciled messagesws 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 reportsDo
NOT READY: REQUIREMENTS.md has a goal but no requirement rowsRecord the confirmed requirements from the conversation, then checkpoint again
checkpoint refusedFix 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 setYou 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 workingDo not take over. Ask the user which window continues
revision conflict or took over the workspaceAnother session is active. Stop writing and re-read HANDOFF.md
a broken table with file and lineRepair that row by hand, then run ws check
change rejected; no change can be checked until these are repairedRepair 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 checkpointInspect them, then checkpoint
owns the workspace from another window that is still runningDo not write. Ask the user; if that window is finished, ws start --force --reason "<what the user said>"
another ws.py command is runningWait 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 permanentRestore 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.