Skip to content

Resume agent sessions from a roadmap checkpoint - #1

Open
done6666 wants to merge 2 commits into
mainfrom
feat/session-checkpoint
Open

done6666 wants to merge 2 commits into
mainfrom
feat/session-checkpoint

Conversation

@done6666

Copy link
Copy Markdown
Owner

Why

Large projects outlive a single context window. When the context fills and a new session starts, the work in progress is lost: what is done, what comes next, and which assumptions are still unproven. Agents also skip memory they are expected to fetch for themselves. This PR shifts steadfast from "normative docs" to repository memory that survives a context reset.

What changed

Roadmap checkpoint (ADR-0018)

  • The current roadmap step can carry a checkpoint with three fields: next (the next concrete action), up to 3 done items and up to 2 open items. It is rewritten in place, never appended to, so it cannot grow into another doc that goes stale.
  • brief shows the checkpoint under the current step. If the brief runs over budget, the checkpoint is the last section to be cut.
  • check --diff warns, and fails under --strict (which the pre-commit hook uses), when the current step's paths changed but its checkpoint did not. Every commit therefore leaves a point to resume from, even if the context runs out mid-task.
  • A done or dropped step must not carry a checkpoint. Facts that should outlive the step go into findings or decisions.

Session-start wiring (ADR-0019 → ADR-0020)

  • hook install --platform claude adds a SessionStart hook to .claude/settings.json that runs brief. Every new, resumed, cleared or compacted Claude Code session starts with the current step and its checkpoint.
  • hook install --platform opencode writes a managed .opencode/plugins/steadfast-brief.js, which uses OpenCode's experimental.session.compacting hook to add the brief to the compaction context.
  • Existing settings, hooks and plugin files are preserved. hook remove deletes only what steadfast wrote, and --check reports whether each hook is installed.

Agent contract and docs

  • The skill, the AGENTS.md contract written by init, and the README now describe the resume loop. The skill still fits its 1200-token budget.

Reviewer notes

  • OpenCode documents no way to add context at session start. A brand-new OpenCode session still relies on the AGENTS.md instruction to run brief. The plugin covers compaction only, and its hook is marked experimental upstream.
  • I haven't exercised the Claude SessionStart hook or the OpenCode plugin in a live harness. The behavior follows each tool's docs and is covered by CLI tests.
  • Fingerprints (verified_by) were refreshed for existing records whose governed files changed. ADR-0019 is superseded by ADR-0020, not edited.
  • npm test: 187/187 pass. steadfast check --strict: 0 errors, 0 warnings.

🤖 Generated with Claude Code

done6666 and others added 2 commits October 30, 2026 04:49
- The current roadmap step carries a checkpoint (next, done, open) that
  brief shows first and keeps when the budget is tight.
- check --diff fails when the current step's paths change but its
  checkpoint does not, so every commit leaves a resume point (ADR-0018).
- hook install --platform claude adds a SessionStart hook that runs
  brief in every new, resumed, cleared or compacted session; platforms
  without such a hook are refused (ADR-0019).
- Skill, AGENTS.md contract and README now describe repository memory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`hook install --platform opencode` now writes a managed
.opencode/plugins/steadfast-brief.js on OpenCode's
experimental.session.compacting hook. The plugin runs the project's own
brief and pushes it into output.context, so the summary a compacted
session continues from carries the current step and its checkpoint; if
brief fails it tells the agent to run it. `hook remove --platform
opencode` deletes only that file, `--check` reports it, and a plugin
file steadfast did not write is never overwritten or removed.

ADR-0020 supersedes ADR-0019 with the OpenCode rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant