savepoint 1.0.1 → 1.0.3

package/templates/project/AGENTS.md

@@ -1,130 +1,88 @@
 # 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.
+1. Read `.savepoint/router.md` — state + next action
+2. Activate skill per table below
+3. Read: router → epic → task → source files
 
-## Task Status Canon
+## Skill Activation
 
-Task frontmatter `status` must be exactly one of `planned`, `in_progress`, or `done`.
+| 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 |
 
-Active task phase is represented separately with `phase: build`, `phase: test`, or `phase: audit`, and `phase` is only valid when `status: in_progress`.
+Use the `skill` tool when the listed skill is available. If the agent says the skill is not found, read `agent-skills/{skill}/SKILL.md` directly and follow it as the active skill.
 
-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.
+Read `.savepoint/PRD.md` only for vision changes, `.savepoint/Design.md` only for architecture/audit.
 
-## Task Completion Protocol
+## Task Status
 
-When a task reaches `status: done`, you MUST:
+- `status`: only `planned`, `in_progress`, or `done`
+- `stage` (build/test/audit): **required** when `status: in_progress` — omitting it is a parse error
+- Never: todo, doing, blocked, review, audit
+- Agents may set a task to `status: in_progress` when starting implementation.
+- Only the user may set a task to `status: done` or retreat a task to an earlier 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."
+## Implementation
 
-**Do not start the next task. Do not advance past this point without user acknowledgment.**
+1. Read task's `## Context Files` using `Read` tool — one call per file, no explore, no glob
+2. Read task's `## Acceptance Criteria` + `## Implementation Plan`
+3. When starting implementation, set task frontmatter to `status: in_progress` + `stage: build` (both required together)
+4. After setting `in_progress`, press `p` in the TUI to mark the focused task as router priority
+5. Execute in order, tick checkboxes
+6. Verify every AC has passing test/outcome
+7. Run quality gates (build + test)
+8. Update router.md: next task or `audit-pending`
+9. **Stop. Prompt user before continuing.**
 
-## Task Closeout Meta-Check
+## Drift Check
 
-After marking a task `done` and before prompting the user, ask yourself:
+- New files/modules not in Codebase Map?
+- Architecture changed from Design.md?
 
-- 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 `## Drift Notes` to task file.
 
-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.`
+## Audit Handoff
 
-Drift notes are lightweight annotations. They do **not** replace the epic audit. They flag what the next audit should reconcile.
+The agent that builds an epic **must not audit it**. Start a fresh session.
 
-## Audit Handoff Rule
+## Audit File Structure
 
-The agent session that builds an epic **must not** run its audit. Audit requires fresh eyes.
+- Audit is agent-led via `savepoint-audit`, not a `savepoint audit` CLI pipeline.
+- Write exactly one `.savepoint/releases/{release}/epics/{E##-slug}/E##-Audit.md`.
+- The TUI Audit tab renders `## Main Findings` and `## Code Style Review` only.
+- Keep file-specific `### Target File` / `### Replace` / `### With` blocks under `## Proposed Changes` so admin apply details do not appear in the Epic Detail panel.
+- During audit apply/close, update the same `E##-Audit.md` visible sections so `## Main Findings` and `## Code Style Review` describe the applied outcome, not stale pre-apply blockers.
 
-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
+- **One job per file** — split files when responsibilities mix.
+- **One job per function** — small, named, testable units.
+- **Test branches** — cover meaningful conditionals and edge cases.
+- **Types document intent** — prefer explicit types over comments.
+- **Build only what is needed** — no speculative abstractions.
+- **Handle errors at boundaries** — validate inputs, APIs, IO, and external data.
+- **One source of truth** — no duplicated rules, constants, state, or config.
+- **Comments explain why** — not what the code already says.
+- **Content lives in data** — keep copy/config out of logic.
+- **Small diffs** — minimal, reviewable, behaviour-preserving changes.
 
-<!-- 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
+make build && make 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
+## CLI Rules
 
 **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/project/agent-skills/savepoint-audit/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: savepoint-audit
+description: Performs Savepoint audit-pending work for a completed epic, reviewing implementation against task acceptance criteria and writing the required E##-Audit.md handoff file.
+---
+
+# Savepoint Skill: Audit (`audit`)
+
+## Objective
+At the end of an epic, review the implemented code against the Epic objectives and Task Acceptance Criteria, and reconcile any documentation "Drift".
+
+## Context
+The Audit Gate is Savepoint's wedge. It prevents projects from degrading into chaos. The `audit` agent acts as the Quality Assurance and Documentation Lead. It reviews the work of the `build-task` agent with "fresh eyes," ensuring that the `Design.md` and the `AGENTS.md` Codebase Map reflect the actual reality of the codebase before the next Epic begins.
+
+## Trigger
+This skill is activated when the `.savepoint/router.md` state is `audit-pending`.
+
+## Input
+- `.savepoint/releases/{release}/epics/{E##-slug}/E##-Detail.md` (the epic design).
+- `.savepoint/Design.md` (project architecture).
+- `AGENTS.md` (agent guide and codebase map).
+- The source and test files modified during the Epic.
+
+## Workflow
+
+1.  **Fresh Eyes Check:** If you are the exact same agent session that just built the `build-task` code for this Epic, you MUST STOP. Tell the user: "Epic complete. Start a new agent session for the audit."
+2.  **Verify ACs:** Review the completed tasks for the Epic. Ensure the Acceptance Criteria were actually met by the committed code. Also confirm each task file has a `## Context Files` section — flag any missing ones under `## Main Findings` as a process gap.
+3.  **Process Drift Notes (Reconciliation):** Read every task file in the Epic and look for `## Drift Notes`.
+4.  **Draft Audit File:** Based on the code changes and the Drift Notes, write exactly ONE file: `.savepoint/releases/{release}/epics/{E##-slug}/E##-Audit.md`. It must use this format:
+    ````md
+    ---
+    type: audit-findings
+    audited: YYYY-MM-DD
+    ---
+    # Audit Findings: E## {Epic Name}
+
+    ## Main Findings
+    [human-readable audit summary only: AC verification, important drift, and notable risks. Do not include per-file replacement blocks here.]
+
+    ## Code Style Review
+    - [ ] One job per file
+    - [ ] One-sentence functions
+    - [ ] Test branches
+    - [ ] Types are documentation
+    - [ ] Build, don't speculate
+    - [ ] Errors at boundaries
+    - [ ] One source of truth
+    - [ ] Comments explain WHY
+    - [ ] Content in data files
+    - [ ] Small diffs
+
+    ## Proposed Changes
+    ### Target File
+    path/to/file.md
+
+    ### Replace
+    ```
+    exact old text
+    ```
+
+    ### With
+    ```
+    replacement text
+    ```
+    ````
+    The TUI Audit tab renders only `## Main Findings` and `## Code Style Review`. Keep `## Proposed Changes` as admin/apply metadata so the Epic Detail panel does not show stale file-change blocks.
+5.  **Review Format:** Use `### Target File`, `### Replace`, and `### With` formatting only inside `## Proposed Changes`. Include proposals for:
+    *   **Design.md:** Merge the epic's architectural changes into the project-level `Design.md`.
+    *   **AGENTS.md:** Refresh the Codebase Map table with new or changed modules.
+    *   **Epic E##-Detail.md:** Add "Implemented as:" notes showing where reality deviated from the original plan.
+    *   **Implementation fixes:** Include any must-fix code or test changes found during audit.
+6.  **Handoff:** Do not apply the proposals yourself. Do not mark the epic audited. Stop and prompt the user to review `.savepoint/releases/{release}/epics/{E##-slug}/E##-Audit.md` (via the TUI Audit tab). Tell them: "Review the audit tab. When ready, say 'apply audit' to apply proposals and close the epic."
+7.  **Apply + Close** (only when the user approves by saying "apply audit" or equivalent):
+    1.  Read `E##-Audit.md` — extract every `### Target File` / `### Replace` / `### With` block from `## Proposed Changes`.
+    2.  For each pair, apply the replacement to the target file named in the preceding `### Target File` line.
+    3.  Update `E##-Audit.md` visible sections: rewrite `## Main Findings` and `## Code Style Review` so the TUI Audit tab reflects the applied outcome, resolved findings, remaining risks if any, and final code-style status. Keep `## Proposed Changes` intact as admin/apply trace unless the user asks to remove it.
+    4.  Update `E##-Detail.md` frontmatter: set `status: audited`.
+    5.  Update `.savepoint/Design.md` frontmatter: set `last_audited: {release}/{E##-slug}`.
+    6.  Read `.savepoint/router.md` current state. Advance:
+        - If more epics remain in the release: set `state: epic-design`, `epic: {next-epic-slug}`, `task: ""`, `next_action: "Draft epic design"`.
+        - If no more epics: set `state: epic-design`, `epic: ""`, `next_action: "Plan next epic"`.
+    7.  Print apply summary: "Applied X proposals. Updated audit findings. Epic {E##} closed as audited. Router → {new state}."
+
+## Constraints
+- **Do not write product code.** You are an auditor.
+- **Do not apply the changes immediately.** Write the proposals document first.
+- **One proposals file.** Do not create multiple proposal files.
+- **No CLI audit pipeline.** Savepoint audit is agent-led and skill-driven; do not invoke or design around a `savepoint audit` command.

package/templates/project/agent-skills/savepoint-build-task/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: savepoint-build-task
+description: Executes Savepoint task-building work when .savepoint/router.md state is task-building, including implementing one active task, checking acceptance criteria, running quality gates, and stopping for user review.
+---
+
+# Savepoint Skill: Build Task (`build-task`)
+
+## Objective
+Act as a disciplined coding agent that strictly follows Savepoint's implementation loop.
+
+## Context
+The `build-task` skill is the execution engine. It reads the detailed task plan, writes the code, and proves that the Acceptance Criteria (ACs) have been met. It is strictly constrained to the scope of the single active task. It does not rewrite architecture, and it does not fix unrelated bugs.
+
+## Trigger
+This skill is activated when the `.savepoint/router.md` state is `task-building` and points to a specific task file.
+
+## Input
+- `.savepoint/router.md` (Current state).
+- The active epic E##-Detail.md: `.savepoint/releases/v1/epics/{E##-epic}/E##-Detail.md`.
+- The active task file: `.savepoint/releases/v1/epics/{E##-epic}/tasks/{T###}-*.md`.
+- Directly touched source/test files.
+
+## Workflow
+
+1.  **Read the Task Plan:** Review the `## Acceptance Criteria` and the `## Implementation Plan`.
+2.  **Test-First Implementation:** If testing is part of the project constraints, write the focused tests for the required behavior first.
+3.  **Execute:** Write the code to check off every item in the `## Implementation Plan`.
+4.  **Validate ACs:** You must verify that every single item in the `## Acceptance Criteria` has been met. A task is not done just because the code is written; it is done when the ACs are demonstrably true.
+5.  **Run Quality Gates:** Run the project's build, lint, and test commands (e.g., `npm run build && npm test` or `go test ./...`).
+6.  **Log Context:** Fill out the `## Context Log` at the bottom of the task file:
+    *   List files read/edited.
+    *   Estimate tokens used.
+    *   Record the result of the quality gates.
+7.  **Log Drift Notes:** **CRITICAL STEP.** Ask yourself:
+    *   Did I add new source files, modules, or exports not listed in the `AGENTS.md` Codebase Map?
+    *   Did I change the architecture from what `.savepoint/Design.md` describes?
+    *   If YES to either, append a `## Drift Notes` section to the bottom of the task file explaining what changed. DO NOT edit `Design.md` or `AGENTS.md` yourself. The `audit` agent will handle that later.
+8.  **Status Update:** Change the task frontmatter to `status: done`.
+9.  **Handoff:** Update `router.md` to point to the next unblocked task. If all tasks in the Epic are done, update it to `state: audit-pending`.
+10. **Stop:** Prompt the user: "Task {id} is done. Quality gates passed. Review the changes, then tell me to continue." Do not start the next task automatically.
+
+## Constraints
+- **Stay in scope:** Do not touch files outside of what is required for the Acceptance Criteria.
+- **Do not edit architecture documents.** If you must deviate from the plan, write the code and log a "Drift Note" in the task file.

package/templates/project/agent-skills/savepoint-create-plan/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: savepoint-create-plan
+description: Creates Savepoint release epics from the PRD and Design documents when the router is in pre-implementation planning.
+---
+
+# Savepoint Skill: Create Plan (`create-plan`)
+
+## Objective
+Turn the Product Requirements Document (PRD) and the architectural `Design.md` into Epics (logical slices of work) and high-level tasks that can be implemented independently.
+
+## Context
+Savepoint enforces small scopes to prevent AI agents from "wandering." The `create-plan` skill acts as the Technical Project Manager. It takes the grand vision and the architectural blueprint and slices it into a sequence of achievable, testable milestones (Epics).
+
+## Trigger
+This skill is activated when the `.savepoint/router.md` state is `pre-implementation`.
+
+## Input
+- `.savepoint/PRD.md` (Vision and constraints)
+- `.savepoint/Design.md` (Architecture and layout)
+- `.savepoint/releases/v1/v1-PRD.md` (Optional: Release-scoped PRD)
+
+## Workflow
+
+1.  **Read the Context:** Consume the PRD and Design documents to understand the scope and technical constraints.
+2.  **Define Epics:** Group the work into high-level features or milestones. Name them clearly (e.g., `E01-scaffolding`, `E02-database`, `E03-auth`). Each Epic must represent a deliverable slice of value.
+3.  **Draft Epic Designs:** For each Epic, create a shell `E##-Detail.md` inside `.savepoint/releases/v1/epics/{E##-epic-name}/E##-Detail.md`. This file should describe the *delta* (what this specific epic adds to the overall architecture).
+4.  **Breakdown Tasks (High Level):** Inside each Epic folder, list out the high-level tasks required to complete it. Do not write full implementation plans yet—just identify the discrete chunks of work (e.g., `T001-setup-repo.md`, `T002-init-db.md`).
+5.  **Order and Dependency:** Ensure the Epics and tasks are ordered logically. You cannot build the frontend auth UI (E03) before the database models (E02) exist.
+6.  **Handoff:** Update `.savepoint/router.md` to `state: task-breakdown` and point it at the first Epic. Prompt the user to review the Epic list.
+
+## Constraints
+- **Do not write code.**
+- **Do not write detailed implementation steps.** That is the job of the `create-task` skill. Keep the task outlines high-level at this stage.

package/templates/project/agent-skills/savepoint-create-task/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: savepoint-create-task
+description: Plans Savepoint task files during epic-task-breakdown by writing acceptance criteria, implementation checklists, dependencies, and context-log shells.
+---
+
+# Savepoint Skill: Create Task (`create-task`)
+
+## Objective
+Take high-level tasks identified during the planning phase and build detailed, actionable task plans with strict Acceptance Criteria.
+
+## Context
+A task plan is a contract between the planner and the builder. If the task plan is vague, the resulting code will be buggy. The `create-task` skill acts as a Senior Engineer writing tickets for a Junior Developer (the `build-task` agent). It must define exactly *what* constitutes success and *how* to achieve it, without actually writing the code.
+
+## Trigger
+This skill is activated when the `.savepoint/router.md` state is `epic-task-breakdown` and the router points to a specific epic.
+
+## Input
+- `.savepoint/releases/v1/epics/{E##-epic}/E##-Detail.md` (The active Epic's design).
+- The high-level task markdown file (e.g., `.savepoint/releases/v1/epics/{E##-epic}/tasks/T001-slug.md`).
+
+## Workflow
+
+1.  **Read Context:** Understand the goal of the specific task within the context of its parent Epic.
+2.  **Define Acceptance Criteria (ACs):** This is the most critical step. Write explicit, observable outcomes. (e.g., "Running `npm test` passes 5 tests for the auth module" or "The `/login` route returns a 200 OK with a valid JWT"). Do not use subjective language like "looks good."
+3.  **Draft Implementation Plan:** Create a step-by-step checklist for the `build-task` agent to follow.
+    *   List which files need to be created or modified.
+    *   Specify which functions or components need to be written.
+    *   Include instructions to write tests *first* if applicable.
+4.  **Populate Context Files:** Add a `## Context Files` section listing the exact file paths the build agent must read before coding. Pull these from the epic's Components table — only the files this task actually touches or depends on. Example:
+    ```markdown
+    ## Context Files
+    - `internal/board/board.go`
+    - `internal/board/model.go`
+    - `internal/data/config.go`
+    ```
+    No globs. No directories. Exact paths only.
+5.  **Add Context Log Shell:** Ensure the bottom of the task file includes a `## Context Log` section with placeholders for `Files read:`, `Estimated input tokens:`, and `Notes:`.
+5.  **Define Dependencies:** If this task relies on another task being completed first, explicitly declare it in the YAML frontmatter (e.g., `depends_on: [T001-setup]`).
+6.  **Status Update:** Change the task frontmatter to `status: planned`.
+7.  **Handoff:** Update `.savepoint/router.md` to `state: in-progress` and ensure it points to the newly planned task. Prompt the user to approve the task plan before building begins.
+
+## Constraints
+- **Do not write code.** Your job is to plan the work, not execute it.
+- **Keep it isolated:** The task plan should touch as few files as possible. If a task plan requires modifying 15 files, it is too large and should be broken down further.

package/templates/project/agent-skills/savepoint-draft-prd/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: savepoint-draft-prd
+description: Guides Savepoint PRD drafting and refinement before implementation, interviewing the user until the product scope is clear enough for design.
+---
+
+# Savepoint Skill: Draft PRD (`draft-prd`)
+
+## Objective
+Help the user write a structured, sufficiently detailed Product Requirements Document (PRD) before any design or planning occurs.
+
+## Context
+In the Savepoint workflow, the PRD is the absolute source of truth. If the PRD is a vague brain-dump, the resulting architecture and code will be a mess. Your job as the `draft-prd` agent is to act as a strict Product Manager. You do not write code. You interrogate the user's idea until it is crisp enough to build a V1.
+
+## Trigger
+This skill is activated when the `.savepoint/router.md` state is `pre-implementation` or when the user explicitly asks you to help them write or refine their PRD.
+
+## Input
+- The user's initial idea, brain-dump, or `.txt` file outline.
+- The template located at `.savepoint/PRD.md`.
+
+## Workflow
+
+1.  **Read the Template:** Review the current state of `.savepoint/PRD.md`. If it is the default template (mostly comments), prepare to interview the user.
+2.  **Interrogation (The Grill):** Do not immediately overwrite the file with guesses. If the user's input lacks:
+    *   A specific core mechanic.
+    *   A defined target user.
+    *   Clear V1 constraints (e.g., tech stack).
+    *   Explicit "Out of scope" items.
+    ...you MUST ask them questions. Force them to define boundaries.
+3.  **Synthesis:** Once you have sufficient detail, synthesize the conversation into the `.savepoint/PRD.md` file, strictly adhering to its markdown structure. Remove the instructional HTML comments as you fill in each section.
+4.  **The V1 Gate:** Review the final document. If the scope still feels too large for a rapid MVP (e.g., "Build a full clone of Jira with AI"), warn the user. Suggest moving features to the "Out of Scope" section for V1.
+5.  **Handoff:** Once the PRD is solid and approved by the user, update `.savepoint/router.md` to `state: design`. Instruct the user to review the PRD and then prompt the agent to continue to the design phase.
+
+## Constraints
+- **Do not write code.**
+- **Do not plan Epics.** That is the job of the `create-plan` skill.
+- **Do not make technical architectural decisions.** That is the job of the `system-design` skill. Your focus is strictly on *what* and *why*, not *how*.

package/templates/project/agent-skills/savepoint-system-design/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: savepoint-system-design
+description: Produces Savepoint system or epic design documents from the PRD when the router is in epic-design or the user asks for architectural design.
+---
+
+# Savepoint Skill: System Design (`system-design`)
+
+## Objective
+Translate the Product Requirements Document (PRD) into the initial architectural blueprint (`Design.md`) before the planning phase breaks the work down into Epics.
+
+## Context
+Before any tasks can be planned, the project needs a high-level technical direction. The `system-design` skill acts as the Staff Engineer. It reads the vision and constraints from the PRD and makes authoritative technical decisions regarding architecture, directory layout, dependency strategies, and workflow rules.
+
+## Trigger
+This skill is activated when the `.savepoint/router.md` state is `epic-design` or when the user explicitly asks to design the system based on the PRD.
+
+## Input
+- `.savepoint/PRD.md` (The source of truth for "what" and "why").
+- Any existing template or shell in `.savepoint/Design.md`.
+
+## Workflow
+
+1.  **Read the PRD:** Analyze `.savepoint/PRD.md` to understand the goal, constraints (e.g., tech stack, budget), and what is out of scope.
+2.  **Architectural Mapping:** Make firm, opinionated technical decisions that solve the PRD's goals. Do not offer options unless absolutely necessary; pick a path and justify it briefly.
+3.  **Draft `.savepoint/Design.md`:** Write or update the architectural design document. It must include:
+    *   **Architecture Model:** The core pattern (e.g., "File-only state machine," "Client-side React with Firebase," "CLI Tool").
+    *   **Directory Layout:** A clear, visual tree mapping out the structure of the project (`src/`, `test/`, etc.).
+    *   **Hierarchy Semantics:** Definitions of what constitutes an Epic vs. a Task.
+    *   **Status Model & Gates:** How work moves from `planned` to `done`.
+    *   **Dependencies:** How modules or tasks rely on each other.
+    *   **CLI Surface/API Contract:** If applicable, define the boundary interactions.
+4.  **Review Against Constraints:** Ensure your design strictly adheres to the constraints and out-of-scope items listed in the PRD. If the PRD says "no database," do not add a database to the architecture.
+5.  **Handoff:** Update `.savepoint/router.md` to `state: planning`. Instruct the user to review the `Design.md` and then prompt the agent to start the epic breakdown.
+
+## Constraints
+- **Do not write code.**
+- **Do not break down tasks.** That is the job of the `create-plan` skill.
+- **Maintain Token Discipline:** Keep the `Design.md` concise. It is meant to be read by AI agents on every turn. Rambling design docs destroy context windows.

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

@@ -1,6 +1,6 @@
 # Prompt: Audit Reconciliation
 
-<!-- AGENT: Produce one patch-shaped proposal bundle. Prefer delta-only edits. Do not write separate proposal files. -->
+<!-- AGENT: Produce one epic-local audit findings file. 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`.
 
@@ -8,60 +8,65 @@ 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/releases/{release}/epics/{E##-slug}/E##-Detail.md` — the epic design (may have deltas from the original plan).
+- `.savepoint/releases/{release}/epics/{E##-slug}/tasks/*.md` — task plans, ACs, and drift notes.
 - `.savepoint/Design.md` — project architecture.
 - `AGENTS.md` — agent guide and codebase map.
-- Only the source and test files listed in the snapshot.
+- Source and test files in the epic scope.
 
 ## Output
 
-One file: `.savepoint/audit/{E##-slug}/proposals.md`
+One file: `.savepoint/releases/{release}/epics/{E##-slug}/E##-Audit.md`
 
-The proposals bundle must contain these sections in order:
+The audit file 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.
+1. **Main Findings** — user-facing summary only: AC verification, important drift, and notable risks. Do not include per-file replacement blocks here.
+2. **Code Style Review** — checklist against the 10 AGENTS.md code style rules.
+3. **Proposed Changes** — admin/apply metadata only. This section may contain `### Target File`, `### Replace`, and `### With` blocks.
 
-## Proposal Format
+The TUI Audit tab renders only `## Main Findings` and `## Code Style Review`. Keep all file-specific proposal blocks under `## Proposed Changes` so the panel does not show stale admin details.
 
-Use this shape for every proposed change:
+## File Format
 
 ```md
-## Target File
+---
+type: audit-findings
+audited: YYYY-MM-DD
+---
+# Audit Findings: E## Epic Name
 
-`path/to/file.md`
+## Main Findings
 
-## Replace
+## Code Style Review
 
-<exact old heading, marker, or section>
-
-## With
-
-<new content>
+## Proposed Changes
 ```
 
-## Quality Review Format
-
-```md
-## Must Fix Before Close
+Use this shape for every proposed change inside `## Proposed Changes`:
 
-## Must Fix Before Next Epic
+````md
+### Target File
+path/to/file.md
 
-## Carry Forward
+### Replace
+```
+<exact old heading, marker, or section>
+```
 
-## Already Fixed
+### With
+```
+<new content>
 ```
+````
 
 ## Rules
 
-1. **One proposals file only.** Do not create `proposal-1.md`, `proposal-2.md`, or any other separate files.
+1. **One audit file only.** Do not create `proposal-1.md`, `proposal-2.md`, `.savepoint/audit/...`, or any other separate audit 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.
+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/releases/{release}/epics/{E##-slug}/E##-Audit.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.
+9. **No CLI audit pipeline.** Savepoint audit is agent-led and skill-driven; do not invoke or design around a `savepoint audit` command.

package/templates/prompts/design.prompt.md

@@ -28,7 +28,7 @@ last_audited: never
 ## 4. Status model & gates
 ## 5. Dependencies
 ## 6. CLI surface
-## 7. Audit pipeline
+## 7. Agent audit workflow
 ## 8. Testing strategy
 ## 9. Release versioning
 ```
@@ -41,3 +41,5 @@ last_audited: never
 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.
+7. **Audit is agent-led.** Do not design a `savepoint audit` CLI pipeline. The audit gate is performed by a fresh agent using the audit skill, producing one epic-local `E##-Audit.md` file.
+8. **Audit file structure is fixed.** `E##-Audit.md` user-facing sections are `## Main Findings` and `## Code Style Review`; file-specific replacement blocks belong under `## Proposed Changes` as admin/apply metadata and should not be rendered in the Epic Detail Audit tab.

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