savepoint 1.0.0

package/templates/project/AGENTS.md

@@ -0,0 +1,130 @@
+# Agents Guide
+
+Welcome, AI agent. This project (`{{PROJECT_NAME}}`) uses Savepoint to manage its build.
+
+## Workflow
+
+Before doing anything, read `.savepoint/router.md`. That file routes you to the next file based on the project's current state.
+
+**Skill Activation (CRITICAL):**
+When you read `.savepoint/router.md`, you MUST activate the corresponding agent skill for the current state before taking any action. Use the `activate_skill` tool (or equivalent) for the appropriate phase:
+- `state: draft-prd` -> Activate the `draft-prd` skill.
+- `state: design` -> Activate the `system-design` skill.
+- `state: planning` -> Activate the `create-plan` skill.
+- `state: task-breakdown` -> Activate the `create-task` skill.
+- `state: in-progress` -> Activate the `build-task` skill.
+- `state: audit-pending` -> Activate the `audit` skill.
+
+When you are about to write code, you must first read, in order:
+
+1. `.savepoint/router.md` — current state and next action
+2. The active epic Design: `.savepoint/releases/v{{RELEASE_NUMBER}}/epics/{E##-epic}/Design.md`
+3. The active task file: `.savepoint/releases/v{{RELEASE_NUMBER}}/epics/{E##-epic}/tasks/{T###}-*.md`
+4. Directly touched source/test files
+
+Read `.savepoint/PRD.md` only for project vision changes, major scope questions, or when the router explicitly asks for it.
+Read `.savepoint/Design.md` only when the task changes architecture or audit state. Read `.savepoint/releases/v{{RELEASE_NUMBER}}/PRD.md` only when planning epics, changing release scope, or resolving epic order.
+
+**Conditional read (token discipline):** if your active task touches **Ink/TUI implementation**, also read `agent-skills/ink-tui-design/SKILL.md` after Design.md as the execution guide. If it touches **TUI rendering, theme, or visual design**, also read `.savepoint/visual-identity.md` as the visual guardrails. Otherwise skip the extra files — they are tokens you do not need.
+
+**Do not load files outside the current task scope** unless the task requires it. Token discipline is the wedge of this product; we honor it on ourselves.
+
+Planning and implementation are separate handoffs:
+
+- Epic task breakdown and detailed task planning happen together in one pass by one planning agent.
+- Each task file must be independently buildable, objective-led, include explicit `depends_on` IDs, contain `## Acceptance Criteria` (observable outcomes) before `## Implementation Plan` (build checklist), and include a `## Context Log` for files read, estimated input tokens, and notes.
+- Implementation happens one task at a time and may be handed to any agent. Clear context between tasks by default; rehydrate only from the router, active epic Design, active task file, and directly touched source/test files.
+- During implementation, run focused tests for the touched behavior first; reserve the full quality-gate suite for task closeout.
+
+- After all tasks in an epic are `done`, hand the epic back for audit.
+- Any explicit audit request overrides the normal handoff timing for that epic. Persist the audit to `.savepoint/audit/{E##-epic}/snapshot.md` and `.savepoint/audit/{E##-epic}/proposals.md` before replying; do not stop at chat-only findings.
+
+## Task Status Canon
+
+Task frontmatter `status` must be exactly one of `planned`, `in_progress`, or `done`.
+
+Active task phase is represented separately with `phase: build`, `phase: test`, or `phase: audit`, and `phase` is only valid when `status: in_progress`.
+
+Never write `todo`, `doing`, `blocked`, `review`, `audit`, or phase names into `status`. If a task is blocked, keep its canonical status and document the blocker in the body.
+
+## Task Completion Protocol
+
+When a task reaches `status: done`, you MUST:
+
+1. Verify every `## Acceptance Criteria` line has a passing test or verified manual outcome. A task is not done until its acceptance criteria are satisfied, not merely its implementation checkboxes ticked.
+2. Tick all checkboxes in the `## Implementation Plan`.
+3. Fill the `## Context Log` (files read, estimated input tokens, notes).
+4. Run the full quality-gate suite (`npm run build && npm run typecheck && npm run lint && npm run format:check && npm test`). Record the result in the Context Log.
+5. If any gate fails, fix it or document the blocker in the task file before setting `status: done`.
+6. Set the task frontmatter to `status: done`.
+7. Update `router.md` with the next action (next unblocked task, or `audit-pending` if all tasks done).
+8. **Stop. Prompt the user:**
+   > "Task {id} is done. Quality gates: {pass/fail list}. Router updated to {next_action}. Review the changes, then tell me to continue."
+
+**Do not start the next task. Do not advance past this point without user acknowledgment.**
+
+## Task Closeout Meta-Check
+
+After marking a task `done` and before prompting the user, ask yourself:
+
+- Did this task add new source files, modules, or exports not in the Codebase Map?
+- Did this task change the architecture from what `.savepoint/Design.md` describes?
+
+If yes, append a `## Drift Notes` section to the task file:
+  - `Drift: {file} added, not yet in Codebase Map.`
+  - `Drift: {section} in Design.md may need update.`
+
+Drift notes are lightweight annotations. They do **not** replace the epic audit. They flag what the next audit should reconcile.
+
+## Audit Handoff Rule
+
+The agent session that builds an epic **must not** run its audit. Audit requires fresh eyes.
+
+When all tasks in an epic are `done`:
+1. Update `router.md` to `state: audit-pending` for that epic.
+2. Stop. Tell the user: "Epic {id} is complete. Start a new agent session for the audit."
+3. The user starts a fresh session. The new agent reads `router.md`, sees `audit-pending`, and follows the audit-reconciliation instructions.
+
+**If you are in the same session that built the epic, you must not audit it.**
+
+## Build / Test / Run
+
+<!-- FILL IN: your project's build, typecheck, lint, format, and test commands. -->
+
+```bash
+npm run build        # compile
+npm run typecheck    # type check
+npm run lint         # lint
+npm run format:check # format check
+npm test             # test suite
+```
+
+## Code Style
+
+1. **One job per file.** If a file does two things, split it.
+2. **One-sentence rule.** If you can't describe a function in one sentence, refactor.
+3. **Test what branches.** Logic with if/else/switch gets a test. Pure rendering: skip.
+4. **Types are documentation.** No `any`. Let the compiler help.
+5. **Build, don't speculate.** No code for hypothetical futures.
+6. **Errors at boundaries.** Handle failure where data enters or leaves the system.
+7. **One source of truth.** State lives in one place. No syncing copies.
+8. **Comments explain WHY,** not what. If removing the comment wouldn't confuse a future reader, delete it.
+9. **Content in data files.** Markdown/JSON/YAML, not strings in code.
+10. **Small diffs.** Each task touches as few files as possible.
+
+## Codebase Map
+
+<!-- AUTO-GENERATED BY savepoint audit. Do not edit manually. -->
+
+| Module | Epic | Purpose |
+| ------ | ---- | ------- |
+
+<!-- END AUTO-GENERATED -->
+
+## CLI rules for agents
+
+**Never run `savepoint` commands.** The CLI is for the human. Edit files directly.
+
+## Recommended planning models
+
+For PRD/Design/Task planning, this workflow assumes a top-tier model: Claude Opus, Gemini 2.5 Pro, GPT-5.5, or equivalent. Lighter models may not follow embedded prompt instructions reliably. If you are not one of those, advise the user before proceeding with planning steps.

package/templates/prompts/audit-reconciliation.prompt.md

@@ -0,0 +1,67 @@
+# Prompt: Audit Reconciliation
+
+<!-- AGENT: Produce one patch-shaped proposal bundle. Prefer delta-only edits. Do not write separate proposal files. -->
+
+You are reconciling an epic after its last task is done. The epic is `status: audit-pending`.
+
+**Context gate:** If you built this epic in the current session, you **must not** audit it. Close this session and let the user start a fresh one.
+
+## Input
+
+- `.savepoint/audit/{E##-slug}/snapshot.md` — what changed during the epic. If this file is missing while the audit CLI is still unavailable, create one manual snapshot from the known epic scope once; do not search broadly for replacement inputs.
+- `.savepoint/releases/v{N}/epics/{E##-slug}/Design.md` — the epic design (may have deltas from the original plan).
+- `.savepoint/Design.md` — project architecture.
+- `AGENTS.md` — agent guide and codebase map.
+- Only the source and test files listed in the snapshot.
+
+## Output
+
+One file: `.savepoint/audit/{E##-slug}/proposals.md`
+
+The proposals bundle must contain these sections in order:
+
+1. **Design.md section** — merge only the epic's architectural delta into the project-level `.savepoint/Design.md`.
+2. **AGENTS.md section** — refresh the Codebase Map table with new or changed modules; preserve existing rows.
+3. **epic-Design.md section** — add "Implemented as:" notes and deviations from the original plan.
+4. **Quality Review section** — semantic-review findings against the project's code style rules.
+
+## Proposal Format
+
+Use this shape for every proposed change:
+
+```md
+## Target File
+
+`path/to/file.md`
+
+## Replace
+
+<exact old heading, marker, or section>
+
+## With
+
+<new content>
+```
+
+## Quality Review Format
+
+```md
+## Must Fix Before Close
+
+## Must Fix Before Next Epic
+
+## Carry Forward
+
+## Already Fixed
+```
+
+## Rules
+
+1. **One proposals file only.** Do not create `proposal-1.md`, `proposal-2.md`, or any other separate files.
+2. **Prefer delta-only edits.** Use `## Replace` anchored to exact existing text. Do not quote and replace entire large sections unless the whole section genuinely changed.
+3. **Do not apply changes yourself.** Write the proposals; the user reviews them in the TUI before commit.
+4. **Track context.** Count only intentional audit context reads, and keep notes short.
+5. **Stop after proposals.** Do not update the router, do not mark the epic audited, and do not commit.
+6. **Be honest about deviations.** If the implementation diverged from the design, document why in the epic-Design.md section.
+7. **Never stop at chat-only findings.** Persist `.savepoint/audit/{E##-slug}/proposals.md` before you report the audit result back to the user.
+8. **Carry-forwards must be actionable.** If an item is "Must Fix Before Next Epic," explain what the next epic's agent should verify. Vague carry-forwards are rejected.

package/templates/prompts/design.prompt.md

@@ -0,0 +1,43 @@
+# Prompt: Project Design Creation
+
+<!-- AGENT: You have an approved project PRD. Produce a project-level Design.md. Stop when the design is complete; do not proceed to epics or tasks. -->
+
+You are architecting a Savepoint-managed project based on an approved PRD.
+
+## Input
+
+- `.savepoint/PRD.md` — the project vision and constraints.
+- Any additional context the user provides about tech stack or patterns.
+
+## Output
+
+A single markdown file matching the structure of `.savepoint/Design.md`:
+
+```
+---
+type: project-design
+status: active
+last_audited: never
+---
+
+# {Project Name} — System Architecture
+
+## 1. Architecture model
+## 2. Directory layout
+## 3. Hierarchy semantics
+## 4. Status model & gates
+## 5. Dependencies
+## 6. CLI surface
+## 7. Audit pipeline
+## 8. Testing strategy
+## 9. Release versioning
+```
+
+## Rules
+
+1. **Design for the PRD, not for the future.** Include only patterns and components needed to satisfy the approved scope.
+2. **Directory layout should be specific.** List expected top-level directories and key files; avoid vague bullets.
+3. **Status model should name every state** and describe what gates move work between them.
+4. **CLI surface is optional.** If the project has no CLI, state that explicitly.
+5. **Do not write epics or tasks.** The Design is architecture only.
+6. **Keep visual identity separate.** If the project has UI/TUI/theme concerns, note that `.savepoint/visual-identity.md` will carry them.

package/templates/prompts/epic-design.prompt.md

@@ -0,0 +1,43 @@
+# Prompt: Epic Design Creation
+
+<!-- AGENT: You have a release PRD and a project Design. Write one epic Design.md. Stop when that single epic design is complete. -->
+
+You are designing one epic for a Savepoint-managed release.
+
+## Input
+
+- `.savepoint/releases/v{N}/PRD.md` — release scope and epic list.
+- `.savepoint/Design.md` — project architecture and constraints.
+- The epic name and one-sentence purpose from the release PRD table.
+
+## Output
+
+A single markdown file at `.savepoint/releases/v{N}/epics/{E##-slug}/Design.md`:
+
+```
+---
+type: epic-design
+status: active
+---
+
+# Epic {E##}: {slug}
+
+## Purpose
+## What this epic adds
+## Components and files
+## Architectural delta
+## Boundaries
+## Quality gates
+## Design constraints
+## Open decisions
+```
+
+## Rules
+
+1. **One epic only.** Do not write tasks, do not design other epics, and do not modify the release PRD.
+2. **Purpose is one paragraph.** Explain what the epic adds to the system and why it is ordered where it is.
+3. **Components and files must be a table.** Each row needs a path and a one-sentence purpose.
+4. **Architectural delta explains before/after.** What does the system lack before this epic? What will it have after?
+5. **Boundaries split in/out of scope explicitly.** Use "In scope" and "Out of scope" sub-lists.
+6. **Quality gates are testable.** List commands, file checks, or behavioral criteria that prove the epic is done.
+7. **Open decisions are honest.** If something is unclear, state it as an open decision rather than guessing.

package/templates/prompts/magic-prompt.prompt.md

@@ -0,0 +1,7 @@
+<!-- AGENT: Read AGENTS.md, then .savepoint/router.md. Follow the router's next action. -->
+
+This project uses Savepoint for AI-driven development workflows.
+
+To start, read `AGENTS.md` in the project root for workflow rules and the codebase map. Then read `.savepoint/router.md` for the current state and next action. Follow the router's instructions.
+
+Project: {{PROJECT_NAME}}

package/templates/prompts/prd.prompt.md

@@ -0,0 +1,42 @@
+# Prompt: Project PRD Creation
+
+<!-- AGENT: Read the user's intent, then interview them until you can write a concise project PRD. Stop when the PRD is complete; do not proceed to design or implementation. -->
+
+You are helping a user define a new Savepoint-managed project. Your goal is to produce a project-level PRD file that an agent can use later to design and build the system.
+
+## Input
+
+The user may provide:
+
+- A rough idea, feature list, or problem statement.
+- Existing code, sketches, or references.
+- Constraints (tech stack, timeline, team size).
+
+## Output
+
+A single markdown file matching the structure of `.savepoint/PRD.md`:
+
+```
+---
+type: project-prd
+status: active
+---
+
+# {Project Name} — Product Vision
+
+## What it is
+## Why
+## Target user
+## Headline differentiator
+## Success metrics
+## Constraints
+## Out of scope (forever or for now)
+```
+
+## Rules
+
+1. **One paragraph per section** unless the user explicitly provides more detail.
+2. **Out of scope is mandatory.** If the user does not specify it, ask what they are explicitly not building.
+3. **Do not invent implementation details.** The PRD is about problems and outcomes, not libraries or file structures.
+4. **Stop after the PRD.** Do not suggest next steps, design, or task breakdown.
+5. **Use concise language.** Token discipline starts here.

package/templates/prompts/task-breakdown.prompt.md

@@ -0,0 +1,54 @@
+# Prompt: Task Breakdown
+
+<!-- AGENT: You have an epic Design. Break it into independently buildable tasks with depends_on and checkbox plans. Stop when every task file is written and the router is updated to task-building for the first unblocked task. -->
+
+You are breaking an approved epic into a set of tasks that agents can build one at a time.
+
+## Input
+
+- `.savepoint/releases/v{N}/epics/{E##-slug}/Design.md` — the epic to break down.
+- `.savepoint/Design.md` — project architecture (for boundary checks).
+
+## Output
+
+One task file per task at `.savepoint/releases/v{N}/epics/{E##-slug}/tasks/TNNN-slug.md`:
+
+```
+---
+id: {E##-slug}/TNNN-slug
+status: planned
+objective: "<one sentence>"
+depends_on: []
+---
+
+# TNNN: slug
+
+## Acceptance Criteria
+
+- [ ] Criterion one (observable outcome)
+- [ ] Criterion two (observable outcome)
+
+## Implementation Plan
+
+- [ ] Step one
+- [ ] Step two
+
+## Context Log
+
+- Files read:
+- Estimated input tokens:
+- Notes:
+```
+
+## Rules
+
+1. **Each task must be independently buildable.** A task should compile, pass its own tests, and leave the repo in a valid state when done.
+2. **Objective is one sentence.** If you need more words, split the task.
+3. **depends_on must be explicit.** List full task IDs. Avoid circular dependencies.
+4. **Acceptance criteria come first.** Every task needs `## Acceptance Criteria` (observable outcomes that define "done") before `## Implementation Plan` (the build checklist that satisfies them).
+5. **Checkboxes are the plan.** Use inline `- [ ]` items under `## Implementation Plan` before any code is written.
+6. **Use only canonical task status.** New task frontmatter must use `status: planned`. Do not write `todo`, `doing`, `blocked`, `review`, `audit`, or phase names into `status`.
+7. **Use phase separately.** Only implementation flow may add `phase: build`, `phase: test`, or `phase: audit`, and only when `status: in_progress`.
+8. **Order tasks by dependency.** The first task should have no `depends_on` (or only depend on prior epic tasks).
+9. **Update the router.** After all tasks are written, set `.savepoint/router.md` `state: task-building` and point `task` to the first unblocked task.
+10. **Do not implement.** Stop at planned tasks with unchecked boxes.

package/templates/prompts/task-building.prompt.md

@@ -0,0 +1,38 @@
+# Prompt: Task Building
+
+<!-- AGENT: Execute the task plan. Tick checkboxes as you complete them. Run focused tests. Stop at done. -->
+
+You are implementing one Savepoint task that is `in_progress` with all `depends_on` done.
+
+## Input
+
+- `.savepoint/router.md` — confirms you are on the correct task.
+- `.savepoint/releases/v{N}/epics/{E##-slug}/Design.md` — epic context.
+- The active task file: `.savepoint/releases/v{N}/epics/{E##-slug}/tasks/TNNN-slug.md` — your checklist.
+- Any directly touched source or test files.
+
+## Output
+
+- Code changes that satisfy every line in the task's `## Acceptance Criteria`.
+- Updated task file with all checkboxes ticked: `- [x]`.
+- Updated task file `## Context Log` with files read, estimated input tokens, notes, and quality-gate results.
+- Task frontmatter `status: done`.
+
+## Status Rules
+
+- Task frontmatter `status` must only be `planned`, `in_progress`, or `done`.
+- Active phases are separate: `phase: build`, `phase: test`, or `phase: audit`.
+- `phase` is only valid with `status: in_progress`; remove `phase` when setting `status: planned` or `status: done`.
+- Never write `todo`, `doing`, `blocked`, `review`, `audit`, or phase names into `status`.
+
+## Rules
+
+1. **Follow the checklist in order.** Do not skip steps.
+2. **Satisfy acceptance criteria first.** Every `## Acceptance Criteria` line must have a passing test or a verified manual outcome before the task can be `done`. The implementation checklist exists to produce those outcomes; every checked box should map to an observable result.
+3. **Run focused tests first.** If the task touches new behavior, write or run tests for that behavior before moving to the next checkbox.
+4. **Run full quality gates at closeout.** After all checkboxes are ticked, run the project's full quality-gate suite (build, typecheck, lint, format:check, test). Record pass/fail for each gate in the Context Log.
+5. **If a gate fails,** fix it or document the blocker in the task file before setting `status: done`.
+6. **Make minimal changes.** Touch as few files as possible. Small diffs are easier to audit.
+7. **Stop at done. Update the router. Prompt the user.** Do not start the next task, do not commit, and do not advance without user acknowledgment.
+8. **If a checkbox is blocked,** leave it unchecked, add a `<!-- BLOCKED: reason -->` comment under it, and stop.
+9. **Drift check before handoff.** Ask yourself: did this task add new files/modules not in the Codebase Map? Did it change the architecture from Design.md? If yes, append `## Drift Notes` to the task file.

package/templates/prompts/task-planning.prompt.md

@@ -0,0 +1,53 @@
+# Prompt: Task Planning (Repair or Late Add)
+
+<!-- AGENT: A single task needs a plan. Write its Implementation Plan as checkboxes and set status: planned. Do not implement. -->
+
+You are repairing or late-adding one task to an epic that is already in progress.
+
+## Input
+
+- The task file stub (may have an empty or incomplete `## Implementation Plan`).
+- `.savepoint/releases/v{N}/epics/{E##-slug}/Design.md` — epic context.
+- `.savepoint/router.md` — current state.
+
+## Output
+
+The updated task file with:
+
+```yaml
+---
+id: {E##-slug}/TNNN-slug
+status: planned
+objective: "<one sentence>"
+depends_on: ["..."]
+---
+
+# TNNN: slug
+
+## Acceptance Criteria
+
+- [ ] Criterion one (observable outcome)
+- [ ] Criterion two (observable outcome)
+
+## Implementation Plan
+
+- [ ] Step one
+- [ ] Step two
+
+## Context Log
+
+- Files read:
+- Estimated input tokens:
+- Notes:
+```
+
+## Rules
+
+1. **One task only.** Do not touch other tasks, the epic Design, or the release PRD.
+2. **Respect existing depends_on.** Do not remove dependencies; you may add them if the task truly requires prior work.
+3. **Acceptance criteria come first.** Write `## Acceptance Criteria` (observable outcomes) before `## Implementation Plan` (build checklist).
+4. **Plan before code.** Every task must have checkboxes before an agent implements it.
+5. **Use only canonical task status.** Planned task frontmatter must use `status: planned`. Do not write `todo`, `doing`, `blocked`, `review`, `audit`, or phase names into `status`.
+6. **Use phase separately.** Only implementation flow may add `phase: build`, `phase: test`, or `phase: audit`, and only when `status: in_progress`.
+7. **Do not implement.** Set `status: planned` and stop.
+8. **If the task is a repair,** reference the defect or gap that triggered it in a `## Repair Context` section above the plan.

package/templates/release/v1/PRD.md

@@ -0,0 +1,37 @@
+---
+version: { { RELEASE_NUMBER } }
+name: "{{RELEASE_NAME}}"
+status: in_progress
+---
+
+# Release v{{RELEASE_NUMBER}} — {{RELEASE_NAME}}
+
+## What ships in v{{RELEASE_NUMBER}}
+
+<!-- One paragraph describing the release theme and primary deliverables. -->
+
+### In scope
+
+<!-- Bullet list of features, commands, or capabilities included in this release. -->
+
+### Out of v{{RELEASE_NUMBER}} scope (deferred to later releases)
+
+<!-- Bullet list of what is explicitly not included, with target future release if known. -->
+
+## Proposed epic breakdown
+
+These are the proposed epics for v{{RELEASE_NUMBER}}. Order matters: each builds on the prior. The first epic is E01-scaffolding (per the savepoint convention). Epic folders use `E##-slug` prefixes so humans can navigate the filesystem without reopening this table.
+
+| #   | Epic name | Purpose                         |
+| --- | --------- | ------------------------------- |
+| 01  | `E01-...` | <!-- Purpose of first epic. --> |
+
+<!-- Add additional rows as needed. -->
+
+## Success criteria for v{{RELEASE_NUMBER}}
+
+<!-- How do you know the release is shippable? -->
+
+## Risks tracked at this release level
+
+<!-- What could derail the release and what is the mitigation? -->