savepoint 1.0.0 → 1.0.2

package/templates/project/AGENTS.md

@@ -1,130 +1,76 @@
 # 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
+1. Read `.savepoint/router.md` — state + next action
+2. Activate skill per table below
+3. Read: router → epic → task → source files
 
-Task frontmatter `status` must be exactly one of `planned`, `in_progress`, or `done`.
+## Skill Activation
 
-Active task phase is represented separately with `phase: build`, `phase: test`, or `phase: audit`, and `phase` is only valid when `status: in_progress`.
+| State | Skill |
+|-------|-------|
+| pre-implementation | savepoint-draft-prd |
+| epic-design | savepoint-system-design |
+| epic-task-breakdown | savepoint-create-task |
+| task-building | savepoint-build-task |
+| audit-pending | savepoint-audit |
 
-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.
+Use `skill` tool.
 
-## Task Completion Protocol
+Read `.savepoint/PRD.md` only for vision changes, `.savepoint/Design.md` only for architecture/audit.
 
-When a task reaches `status: done`, you MUST:
+## Task Status
 
-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."
+- `status`: only `planned`, `in_progress`, or `done`
+- `phase` (build/test/audit): only when `status: in_progress`
+- Never: todo, doing, blocked, review, audit
 
-**Do not start the next task. Do not advance past this point without user acknowledgment.**
+## Implementation
 
-## Task Closeout Meta-Check
+1. Read task's `## Acceptance Criteria` + `## Implementation Plan`
+2. Execute in order, tick checkboxes
+3. Verify every AC has passing test/outcome
+4. Run quality gates (build + test)
+5. Update task: tick boxes, fill `## Context Log`, set `status: done`
+6. Update router.md: next task or `audit-pending`
+7. **Stop. Prompt user before continuing.**
 
-After marking a task `done` and before prompting the user, ask yourself:
+## Drift Check
 
-- 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?
+- New files/modules not in Codebase Map?
+- Architecture changed from Design.md?
 
-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.`
+If yes → append `## Drift Notes` to task file.
 
-Drift notes are lightweight annotations. They do **not** replace the epic audit. They flag what the next audit should reconcile.
+## Audit Handoff
 
-## Audit Handoff Rule
+The agent that builds an epic **must not audit it**. Start a fresh session.
 
-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.**
+## Code Style
 
-## Build / Test / Run
+1. One job per file
+2. One-sentence functions
+3. Test branches
+4. Types are documentation
+5. Build, don't speculate
+6. Errors at boundaries
+7. One source of truth
+8. Comments explain WHY
+9. Content in data files
+10. Small diffs
 
-<!-- FILL IN: your project's build, typecheck, lint, format, and test commands. -->
+## Build
 
 ```bash
-npm run build        # compile
-npm run typecheck    # type check
-npm run lint         # lint
-npm run format:check # format check
-npm test             # test suite
+npm run build && npm run test
 ```
 
-## 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
+## CLI Rules
 
-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.
+**Never run `savepoint` commands.** The CLI is for the human. Edit files directly.

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

@@ -8,21 +8,21 @@ You are reconciling an epic after its last task is done. The epic is `status: au
 
 ## 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/audit/{release}/{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/{release}/epics/{E##-slug}/E##-Detail.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`
+One file: `.savepoint/audit/{release}/{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.
+3. **epic-E##-Detail.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
@@ -62,6 +62,6 @@ Use this shape for every proposed change:
 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.
+6. **Be honest about deviations.** If the implementation diverged from the design, document why in the epic-E##-Detail.md section.
+7. **Never stop at chat-only findings.** Persist `.savepoint/audit/{release}/{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/epic-design.prompt.md

@@ -1,18 +1,18 @@
 # 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. -->
+<!-- AGENT: You have a release PRD and a project Design. Write one epic E##-Detail.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/releases/{release}/{release}-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`:
+A single markdown file at `.savepoint/releases/{release}/epics/{E##-slug}/E##-Detail.md`:
 
 ```
 ---

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

@@ -6,7 +6,7 @@ You are breaking an approved epic into a set of tasks that agents can build one
 
 ## Input
 
-- `.savepoint/releases/v{N}/epics/{E##-slug}/Design.md` — the epic to break down.
+- `.savepoint/releases/v{N}/epics/{E##-slug}/E##-Detail.md` — the epic to break down.
 - `.savepoint/Design.md` — project architecture (for boundary checks).
 
 ## Output

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

@@ -7,7 +7,7 @@ You are implementing one Savepoint task that is `in_progress` with all `depends_
 ## Input
 
 - `.savepoint/router.md` — confirms you are on the correct task.
-- `.savepoint/releases/v{N}/epics/{E##-slug}/Design.md` — epic context.
+- `.savepoint/releases/v{N}/epics/{E##-slug}/E##-Detail.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.
 

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

@@ -7,7 +7,7 @@ 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/releases/v{N}/epics/{E##-slug}/E##-Detail.md` — epic context.
 - `.savepoint/router.md` — current state.
 
 ## Output

package/.savepoint/releases/v1/epics/E06-atari-noir-layout/Design.md

@@ -1,42 +0,0 @@
----
-type: epic-design
-status: planned
----
-
-# Epic E07: Atari-Noir Layout Uplift
-
-## Purpose
-
-Update the existing TUI to align with the **Atari-Noir SavePoint design system**. This is a visual and layout uplift focused on restraint, clarity, and control, preserving existing functionality while eliminating visual noise and strictly adhering to the new color and layout rules.
-
-## What this epic adds
-
-- Centralized Atari-Noir color system in `palette.go`.
-- Restructured `styles.go` mapped to exact usage rules.
-- Static header component: `▣  S A V E P O I N T`.
-- Static footer component: `PLAN      │      BUILD      │      AUDIT`.
-- Full-width subtle horizontal dividers.
-- Refined component styling (columns, cards, epic panel) to remove unnecessary borders and improve spacing.
-
-## Definition of Done
-
-- All colors match the Atari-Noir strict specification.
-- Header renders correctly with no wrapping.
-- Footer displays PLAN / BUILD / AUDIT cleanly without dynamic status text.
-- Full-width dividers frame the content.
-- Cards/panels feel like surfaces, not text blocks.
-- Spacing is consistent and components breathe.
-- Focus/selection is obvious through position and Atari Orange borders, not relying solely on color text changes.
-- Existing functionality remains 100% intact.
-
-## Components and files
-
-| Path | Purpose |
-|------|---------|
-| `internal/styles/palette.go` | Define strict hex values |
-| `internal/styles/styles.go` | Map styles to new usage rules |
-| `internal/board/view.go` | Implement header, footer, dividers |
-| `internal/board/layout.go` | Adjust layout height calculations |
-| `internal/board/column.go` | Refine column styling and spacing |
-| `internal/board/card.go` | Refine card surface and focus state |
-| `internal/board/epic_panel.go` | Refine epic panel layout |

package/.savepoint/releases/v1.1/epics/E01-tui-optimisation/Design.md

@@ -1,26 +0,0 @@
----
-type: epic-design
-status: planned
----
-
-# Epic E01: TUI Optimisation
-
-## Purpose
-
-Performance, layout robustness, and structural improvements for the board TUI. Focused on fixing rendering edge-cases (resize clipping, wasted space) and improving the codebase's architectural hygiene around file watching and data refresh.
-
-## Definition of Done
-
-- Right-border clipping is eliminated at all terminal widths ≥ 40
-- Resize handling is robust — no corruption, no artifacts when growing/shrinking
-- The board auto-refreshes when task files change on disk via fsnotify
-
-## Components and files
-
-| Path | Purpose |
-|------|---------|
-| `internal/board/layout.go` | Layout arithmetic and resize guards |
-| `internal/board/view.go` | Minimum width clamping |
-| `internal/board/watch.go` | File watcher and reload commands |
-| `internal/board/model.go` | Watcher lifecycle |
-| `internal/board/update.go` | Reload message handling |

package/.savepoint/releases/v1.1/epics/E01-tui-optimisation/tasks/T001-border-resize-fix.md

@@ -1,35 +0,0 @@
----
-id: E01-tui-optimisation/T001-border-resize-fix
-status: planned
-objective: "Fix right-border clipping and ensure clean rendering on terminal resize"
-depends_on: []
----
-
-# T001: Fix Right-Border Clipping and Resize Robustness
-
-## Acceptance Criteria
-
-- The board frame right border (`│` or rounded corner) is always visible at any terminal width ≥ 40 chars
-- Reducing terminal width below a breakpoint (120→119, 80→79) does not leave stray pixels or broken border artifacts
-- Reducing to very narrow widths (< 50) degrades gracefully (no visual corruption)
-- Expanding terminal width back renders cleanly with no leftover characters from previous dimensions
-- All existing layout breakpoints (120/80) still function correctly
-
-## Implementation Plan
-
-- [ ] Edit `internal/board/layout.go` — audit width arithmetic to ensure total content width exactly fills `width - boardFrameOverhead` at every breakpoint; use `totalWidth := cw*colCount + colOverhead*colCount` and pad any remainder so it matches `inner` exactly.
-- [ ] Edit `internal/board/view.go` — add minimum terminal width clamping (e.g., floor to 40) in `View()` to prevent degenerate states.
-- [ ] Edit `internal/board/layout.go` — add a `minBoardWidth` const and guard `CalculateLayout` inputs below it.
-- [ ] Run `make build && make test` to verify no regressions.
-
-## Context Log
-
-Files read:
-- `internal/board/layout.go`
-- `internal/board/view.go`
-- `internal/board/update.go`
-
-Estimated input tokens: 600
-
-Notes:
-- Moved from `E06-atari-noir-layout/T006-border-resize-fix` (release v1) to `E01-tui-optimisation` (release v1.1).