Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 10 additions & 11 deletions .opencode/skills/steadfast/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,17 @@ description: Use when a repository has .steadfast/ or AGENTS.md mentions steadfa

# Steadfast Memory

## Trigger

Use this skill when `.steadfast/` exists or `AGENTS.md` mentions steadfast.
## Tools

With MCP connected, call its `brief`, `context`, `check`, `verify`, `new`,
`finding` and `supersede` tools instead of the CLI below; clients prefix the
names (`steadfast_*` in OpenCode, `mcp__steadfast__*` in Claude).

## 0. Recover state

Run `npx steadfast-docs brief` first. It prints the current roadmap step, next
steps, blockers, recent commits and worktrees. Do not open
`.steadfast/roadmap.yaml` directly; edit it only to update status and evidence.
Run `npx steadfast-docs brief` first, unless the session already shows it.
Resume from the current step's `checkpoint.next`. Edit
`.steadfast/roadmap.yaml` only for status, evidence and checkpoint.

## 1. Plan the path set

Expand Down Expand Up @@ -97,9 +95,8 @@ Then set `status: active` and run `verify`.
- If a rule changes, run `steadfast supersede <id> --decision "<rule>"`.
- If you learn a fact code cannot prove yet, record it with `steadfast finding new`; retire it when a test proves it.
- Unenforceable rules are advisory and expire.
- When a roadmap step is finished, set `status: done` and `evidence: <test or
commit>` in `.steadfast/roadmap.yaml`, then make the next unblocked step
`current`.
- When a step is finished, set `status: done`, `evidence: <test or commit>`,
drop its checkpoint, and make the next unblocked step `current`.

## 7. Hand off

Expand All @@ -109,8 +106,10 @@ Tell the human only:
- decisions that need approval, one line each
- any guard that blocked a path

Leave a durable handoff in the commit body or an issue: `Finding:`, `Decision:`,
`Next:`. Update README `Status` on release changes.
Before each commit and before you stop, rewrite the current step's
`checkpoint`: `next` (one action), `done` (max 3), `open` (max 2); `check
--diff` fails if step paths changed but it did not. Update README `Status` on
release changes.

## Stop conditions

Expand Down
2 changes: 1 addition & 1 deletion .steadfast/decisions/ADR-0002.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -9,5 +9,5 @@ decision: Decision records are YAML; Markdown is reserved for agent contracts an
why:
- Prose budgets cannot be enforced; data can.
enforced_by: test/validate.test.ts
verified_by: h1:f751be4b1e95bc479b70138a5a7b576232dd6bff0d9fe1fbe85cb4e4326caaca
verified_by: h1:f4bae5285a62401270d8b8ece0d35bf16f1e6488bf073ff7d305a8ba067a01e7
by: agent
2 changes: 1 addition & 1 deletion .steadfast/decisions/ADR-0007.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ decision: The canonical skill is budgeted, and every project copy is verified ag
why:
- Global copies are user-managed; project copies are enforced.
enforced_by: test/skill.test.ts
verified_by: h1:19c49b970bd9e616aa6976151bc1374a34600f44246f9810118e78944c18f061
verified_by: h1:806e39cb49f2b5381b9059240f86c23514831f67c0a32c6b774d42e63bc7eb4b
supersedes:
- ADR-0006
by: agent
2 changes: 1 addition & 1 deletion .steadfast/decisions/ADR-0008.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -11,5 +11,5 @@ decision: Legacy documentation is deleted after migration; check fails if a reti
why:
- The pack is the only context; stale docs are the drift this replaces.
enforced_by: test/retire.test.ts
verified_by: h1:11cbf5ccd00b71880ac07bcbb3eaefb98523dcd9fef0921ccc026b399cb80006
verified_by: h1:1a0d070f7ce565ab916cdeed819bffdd9766892a657c0cf9de2d75bf2f84fed8
by: agent
2 changes: 1 addition & 1 deletion .steadfast/decisions/ADR-0009.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,5 @@ decision: The MCP server wraps the CLI, so every command has one implementation
why:
- A second implementation would drift and double the test burden.
enforced_by: test/mcp.test.ts
verified_by: h1:cea336eb4526c6ee4382f4e434dde4722873b2fb7fbc27e0c1f11f9b512d98d6
verified_by: h1:d309321c91f8d88ca63ee8392f1986074d0d002b03fad93861f014c8ae3e7caa
by: agent
2 changes: 1 addition & 1 deletion .steadfast/decisions/ADR-0010.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -11,5 +11,5 @@ decision: The pre-commit hook validates the index, and refuses when governed fil
why:
- A hook that reads only the working tree can approve a different commit.
enforced_by: test/hook.test.ts
verified_by: h1:bc7ffd28919212f071e8fc157061bd0a34361ba507986b2c0ded5e209cd8d868
verified_by: h1:d25df35a4e112b7dd104ffd44707150645862e21ab0dbe5904ae6853dc47ae18
by: agent
2 changes: 1 addition & 1 deletion .steadfast/decisions/ADR-0014.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,5 @@ decision: A config change that only updates retired_docs is not decision debt.
why:
- retire records the retirement itself; a second record would be noise.
enforced_by: test/retire.test.ts
verified_by: h1:c5753d9f2a65d774cda525b362d2936241ac6c90303a43284ef8e2ff6cf7262d
verified_by: h1:9644a79fba2791a41064779c81ed3f872aa5d0c39c24c76c61c8e86f69367954
by: agent
2 changes: 1 addition & 1 deletion .steadfast/decisions/ADR-0016.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -15,5 +15,5 @@ decision: Execution state lives in a mutable, token-budgeted roadmap; decisions
why:
- Session handoff needs a current step, but a second normative store would drift.
enforced_by: test/roadmap.test.ts
verified_by: h1:795e400d27e8e719d8de0bd22ccbdedc8b48e1389197500d512264639664c036
verified_by: h1:56030221ddd95bbcd5f34402dfb6ece921aed6c2f04fc54228c8be4f87a9cf34
by: agent
2 changes: 1 addition & 1 deletion .steadfast/decisions/ADR-0017.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -16,5 +16,5 @@ decision: Findings are append-only, target-versioned observations; they enter co
why:
- Facts code cannot prove yet are lost between sessions, but a second decision store would drift.
enforced_by: test/finding.test.ts
verified_by: h1:83994bc5706a9a709258a4e4933f6257c195c5e9e92aa890feb9de155aa8b044
verified_by: h1:773140bd04fd73c0684c19225324665a999dee2ada7e0fbafc065a6165860165
by: agent
20 changes: 20 additions & 0 deletions .steadfast/decisions/ADR-0018.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
id: ADR-0018
topic: session-checkpoint
scope: global
status: active
created: 2026-10-30
applies_to:
- src/core/roadmap.ts
- src/commands/brief.ts
- src/commands/check.ts
- schema/roadmap.schema.json
- test/checkpoint.test.ts
decision: The current roadmap step carries a checkpoint rewritten in place; check --diff fails when the step's paths change but the checkpoint does not.
why:
- A context reset loses in-progress state; binding the resume point to commits saves it without predicting when context runs out.
rejected:
- "Appended session log: grows without bound and becomes the docs that rot."
- "Date-based staleness: an old date says nothing about whether the work moved."
enforced_by: test/checkpoint.test.ts
by: agent
verified_by: h1:bc4b3504b62cf4de1d660149180b7b92fb065af552bd060a9424df7093207c29
16 changes: 16 additions & 0 deletions .steadfast/decisions/ADR-0019.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
id: ADR-0019
topic: session-start
scope: global
status: active
created: 2026-10-30
applies_to:
- src/commands/hook.ts
- test/hook.test.ts
decision: hook install --platform claude adds a SessionStart hook that runs brief; platforms without a session-start context hook are refused.
why:
- Memory the agent must pull gets skipped; a harness hook pushes it into every new, resumed or compacted session.
rejected:
- "OpenCode compaction plugin: experimental API and it fires only on compaction, not at session start."
enforced_by: test/hook.test.ts
by: agent
verified_by: h1:49a9e159038fb341ba42dfdf702e0de6bc99fc1ac67ca88d69f1a8640164f8fe
18 changes: 18 additions & 0 deletions .steadfast/decisions/ADR-0020.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
id: ADR-0020
topic: session-start
scope: global
status: active
created: 2026-10-30
applies_to:
- src/commands/hook.ts
- test/hook.test.ts
decision: hook install --platform claude adds a SessionStart brief; --platform opencode writes a managed .opencode/plugins/steadfast-brief.js pushing brief into compaction context.
why:
- Agents skip memory they must pull; harness hooks push it at Claude session start and into every OpenCode compaction.
rejected:
- "Setting output.prompt: it replaces OpenCode's own compaction prompt instead of adding to it."
enforced_by: test/hook.test.ts
verified_by: h1:c1bafd596bfa9c6895d6fbdcc960533022f286c3fa36190ffdb5bb2e19106ad5
supersedes:
- ADR-0019
by: agent
19 changes: 18 additions & 1 deletion .steadfast/roadmap.yaml
Original file line number Diff line number Diff line change
@@ -1,3 +1,20 @@
# Execution state: mutable. One current step. Decisions stay in .steadfast/decisions/.
version: 1
steps: []
updated: 2026-10-30
steps:
- id: STEP-001
goal: Make a new session resume where the last one stopped
why: Context resets lose the in-progress state, and agents skip memory they must pull.
paths: [src/**, schema/roadmap.schema.json, test/**, skills/steadfast/SKILL.md, README.md]
acceptance: npm test and steadfast check --strict pass
status: done
evidence: test/checkpoint.test.ts
decisions: [ADR-0018, ADR-0019]
- id: STEP-002
goal: Push the brief into every OpenCode compaction
why: OpenCode has no session-start hook, so a compacted session loses the step unless the summary carries it.
paths: [src/commands/hook.ts, src/commands/mcp.ts, test/hook.test.ts, README.md]
acceptance: npm test and steadfast check --strict pass
status: done
evidence: test/hook.test.ts
decisions: [ADR-0020]
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,8 @@ After `steadfast new`, fill the record you just created.
If the steadfast MCP server is connected, call `steadfast_context` (OpenCode) or `mcp__steadfast__context` (Claude) with the paths you will touch; otherwise run `npx steadfast-docs context --for <paths>`. Use only that output for context.
If context fails, narrow the paths or ask the human before raising the budget; do not pass `--allow-partial`.
Records are not reading material: do not load other records, legacy docs or architecture notes. The pack is the only context.
At session start, run `npx steadfast-docs brief` to recover the current roadmap step. Update `.steadfast/roadmap.yaml` when a step starts or finishes.
At session start, run `npx steadfast-docs brief` to recover the current roadmap step and its checkpoint. Update `.steadfast/roadmap.yaml` when a step starts or finishes.
Before each commit and before the session ends, rewrite the current step's `checkpoint` (`next`, `done`, `open`) so the next session resumes where this one stopped.
If you discover a fact code cannot prove yet, record a finding; retire it when a test proves it.
After a new record, fill the record you just created. Never edit an active record; supersede it.

Expand Down
Loading
Loading