diff --git a/.claude/AGENTS.md b/.claude/AGENTS.md index 6fb4ae6..99b15cc 100644 --- a/.claude/AGENTS.md +++ b/.claude/AGENTS.md @@ -125,6 +125,7 @@ Do not run full validation suites after every small edit by habit. Run the narro | Editing AGENTS.md, .agents/skills/, docs/ai/ | writing-docs.md | | Maintaining or troubleshooting ask-intern | ask-intern.md | | Operating or changing the learning system | learning-system.md | + | Managing a multi-hour or multi-session autonomous workstream | long-running-workstreams.md | - Re-read the hard rules before implementation. ## Session Tools diff --git a/docs/ai/long-running-workstreams.md b/docs/ai/long-running-workstreams.md new file mode 100644 index 0000000..64576cc --- /dev/null +++ b/docs/ai/long-running-workstreams.md @@ -0,0 +1,46 @@ +> **IMPORTANT: Before reading, check if you already read this file earlier in this session. If yes, skip the read and announce "Context already loaded: long-running-workstreams.md (re-using from earlier)". If no, read it and announce "Context loaded: long-running-workstreams.md".** + +# Long-Running Workstreams + +Read this when managing a multi-hour or multi-session autonomous workstream where the agent must resume after compaction or hand off context across runs. + +## Contract + +- Maintain a `scratch.md` control surface alongside any evidence or triage files. Evidence explains what happened; scratch state tells the next agent what to do without rediscovering the whole thread. +- Keep the "Current Truth" section current and sharp. Archaeology grows below it and stays compressed. +- Apply compaction-time maintenance every time context is compacted or a session resumes: update "Current Truth", move completed next-steps into a short archaeology entry, delete detail now covered by links or evidence files, and compact the top section before continuing. +- Do not let the scratch file grow into a second transcript. Garbage-collect it on every re-read after compaction. + +## Scratch File Structure + +Use this shape for `scratch.md`: + +``` +## Current Truth (update at every compaction) +<3-5 line summary of the actual state right now> + +## Next Steps +- [ ] +- [ ] + +## Archaeology +### - + +``` + +Keep "Current Truth" and "Next Steps" together at the top; archaeology grows at the bottom. If "Next Steps" is empty, the workstream is done. + +## Canonical Files + +- `docs/specs//scratch.md` — primary control surface for a feature workstream. +- Separate evidence files (`triage.md`, `shakedown-log.md`, run artifacts) hold full detail; scratch summarizes. + +## Verification + +After any compaction or resume, check that "Current Truth" reflects the actual current state, not an earlier snapshot. A stale "Current Truth" is the sign that the compaction maintenance step was skipped. + +## Notes + +- Do not write the same content to both scratch.md and evidence files. Scratch summarizes; evidence files contain full detail. +- This pattern is most valuable for: shakedown loops, experiment queues, autonomous workstreams, and any session expected to compact at least once. +- If the workstream has a living triage file, keep them separate: triage captures what was found; scratch captures what to do next.