savepoint 1.0.1 → 1.0.3

package/AGENTS.md

@@ -1,141 +1,99 @@
 # Agents Guide
 
-Welcome, AI agent. This project (`savepoint`) uses its own conventions to manage its own build. You are about to dogfood the workflow.
-
 ## Workflow
 
-Before doing anything, read `.savepoint/router.md`. That file routes you to the next file based on the project's current state.
-
-**Available Custom Skills:**
-Savepoint ships with skills that define your role at each stage.
-- `draft-prd`: Acts as a strict Product Manager to interrogate the user and write the PRD.
-- `system-design`: Acts as a Staff Engineer mapping the architecture.
-- `create-plan` / `create-task`: Acts as a Technical PM breaking work into Epics and ACs.
-- `build-task`: Acts as the disciplined execution engine writing code and logging drift.
-- `audit`: Acts as the QA Lead reconciling code with documentation.
-
-**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/v1/epics/{E##-epic}/Design.md`
-3. The active task file: `.savepoint/releases/v1/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/v1/PRD.md` only when planning epics, changing release scope, or resolving epic order.
-
-**Conditional read:** if the active task touches TUI implementation, also read `agent-skills/ink-tui-design/SKILL.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.
+1. Read `.savepoint/router.md` — state + next action
+2. Activate skill per table below
+3. Read: router → epic → task → source files
 
-- 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.
+## Skill Activation
 
-## Task Status Canon
+| 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 |
 
-Task frontmatter `status` must be exactly one of `planned`, `in_progress`, or `done`.
+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.
 
-Active task phase is represented separately with `phase: build`, `phase: test`, or `phase: audit`, and `phase` is only valid when `status: in_progress`.
+Read `.savepoint/PRD.md` only for vision changes, `.savepoint/Design.md` only for architecture/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.
+## Task Status
 
-## Task Completion Protocol
+- `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.
 
-When a task reaches `status: done`, you MUST:
+## Implementation
 
-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 (`make build && make 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."
+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.**
 
-**Do not start the next task. Do not advance past this point without user acknowledgment.**
+## Drift Check
 
-## Task Closeout Meta-Check
+- New files/modules not in Codebase Map?
+- Architecture changed from Design.md?
 
-After marking a task `done` and before prompting the user, ask yourself:
+If yes → append `## Drift Notes` to task file.
 
-- 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?
+## Audit Handoff
 
-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.`
+The agent that builds an epic **must not audit it**. Start a fresh session.
 
-Drift notes are lightweight annotations. They do **not** replace the epic audit. They flag what the next audit should reconcile.
+## Audit File Structure
 
-## Audit Handoff Rule
+- 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.
 
-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.
+## Code Style
 
-**If you are in the same session that built the epic, you must not audit it.**
+- **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.
 
-## Build / Test / Run
+## Build
 
 ```bash
-make build # go build -o savepoint main.go
-make test  # go test ./...
-make run   # go run main.go
-make clean # rm -f savepoint
+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
 
-| Module                               | Purpose                                                                                              |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------- |
-| `main.go`                            | CLI Entrypoint and root command wiring                                                               |
-| `internal/board/`                    | TUI board models, layout, rendering, overlays, task transitions, router priority markers, and fsnotify refresh |
-| `internal/data/`                     | Task/router/config models, frontmatter parsing, checklist state parsing, mtime-guarded writes, discovery, and generic file readers |
-| `internal/styles/`                   | Atari-Noir palette constants, terminal color fallbacks, shared TUI styles, semantic glyph/tag styles, and footer/header styling |
-| `cmd/`                               | Additional CLI subcommands (if any)                                                                  |
-| `templates/`                         | Default project scaffold markdown, YAML assets, and agent prompt templates                           |
-| `agent-skills/`                      | Custom skill guides for different agent phases (`draft-prd`, `audit`, etc.)                          |
-
-## CLI rules for agents
+| Module | Purpose |
+|--------|---------|
+| `main.go` | CLI entrypoint, --version |
+| `cmd/` | CLI command arg parsing and dispatch for init, board, and doctor |
+| `internal/init/` | Target validation, scaffold writing from templates |
+| `internal/board/` | TUI board, overlays, epic sidebar, Next Activity line, router priority key, detail checklist rendering, status glyphs, forced color profile, async update I/O commands, shared board utilities |
+| `internal/buildtool/` | Makefile helper, cross-compile, archives |
+| `internal/doctor/` | Read-only project diagnostics, integrity checks, timed quality gate execution, report formatting, typed repair suggestions |
+| `internal/data/` | Task/router models, frontmatter parsing/splitting, lifecycle validation/defaulting, discovery including root-dir traversal, unified task status constants, canonical write helpers |
+| `internal/testutil/` | Shared Go test fixtures and filesystem helpers for internal package tests |
+| `internal/styles/` | Atari-Noir palette, TUI styles |
+| `templates/` | Scaffold markdown, YAML, prompts |
+| `agent-skills/` | Phase-specific skill guides |
+
+## CLI Rules
 
 **Never run `savepoint` commands.** The CLI is for the human. Edit files directly.
-
-(For this repo specifically: `savepoint` doesn't exist yet — we're building it. Even once it exists, this rule stands.)
-
-## 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.
- instructions reliably. If you are not one of those, advise the user before proceeding with planning steps.

package/Makefile

@@ -1,7 +1,9 @@
-.PHONY: build test run clean
+.PHONY: build test run clean build-linux build-darwin build-all dist smoke-test
+
+VERSION ?=
 
 build:
-	go build -o savepoint main.go
+	go run ./internal/buildtool -version "$(VERSION)" build
 
 test:
 	go test ./...
@@ -10,4 +12,18 @@ run:
 	go run main.go
 
 clean:
-	rm -f savepoint
+	go run ./internal/buildtool -version "$(VERSION)" clean
+
+build-linux:
+	go run ./internal/buildtool -version "$(VERSION)" build-linux
+
+build-darwin:
+	go run ./internal/buildtool -version "$(VERSION)" build-darwin
+
+build-all: build-linux build-darwin
+
+dist:
+	go run ./internal/buildtool -version "$(VERSION)" dist
+
+smoke-test:
+	go run ./internal/buildtool -version "$(VERSION)" smoke-test

package/README.md

@@ -34,11 +34,11 @@ Savepoint turns your project into a series of hard gates, enforced by **six bund
 
 Small scopes. Small context windows. No wandering.
 
-- **The PRD Gate (`draft-prd`):** The agent interviews you to ensure your idea is crisp enough for a V1 before writing any architecture.
-- **The Design Gate (`system-design`):** Write down what you actually want. If you can't explain it simply in a markdown file, the AI is going to make a mess of it.
-- **The Plan Gate (`create-plan` & `create-task`):** Break the idea down into small, manageable steps. No giant leaps. This becomes the checklist the AI _must_ follow.
-- **The Build Gate (`build-task`):** The AI writes code for one small step at a time. The scope stays tight so it doesn't wander off into the weeds. It logs "Drift Notes" instead of cowboy-coding architectural changes.
-- **The Audit Gate (`audit`):** Before moving on, we stop and check. Does the code match the plan? We don't advance until the map matches the territory.
+- **The PRD Gate (`savepoint-draft-prd`):** The agent interviews you to ensure your idea is crisp enough for a V1 before writing any architecture.
+- **The Design Gate (`savepoint-system-design`):** Write down what you actually want. If you can't explain it simply in a markdown file, the AI is going to make a mess of it.
+- **The Plan Gate (`savepoint-create-plan` & `savepoint-create-task`):** Break the idea down into small, manageable steps. No giant leaps. This becomes the checklist the AI _must_ follow.
+- **The Build Gate (`savepoint-build-task`):** The AI writes code for one small step at a time. The scope stays tight so it doesn't wander off into the weeds. It logs "Drift Notes" instead of cowboy-coding architectural changes.
+- **The Audit Gate (`savepoint-audit`):** Before moving on, we stop and check. Does the code match the plan? We don't advance until the map matches the territory.
 
 > 🔒 **The Audit Loop** — When the last task in an epic moves to `done`, the next epic stays _locked_ until your docs (`Design.md`, `AGENTS.md`, and the epic's own design) are reconciled with the actual code via the audit agent. **No existing markdown-first task tool has this gate.**
 
@@ -61,7 +61,6 @@ Built for a cinematic, technical feel without the bloat.
 | :----------------- | :--------------------------------------------------------------------------------------------------- |
 | `savepoint init`   | Scaffold the loop, write your `AGENTS.md` guide, drop the baby gates, and generate the magic prompt. |
 | `savepoint board`  | Launch the Atari-Noir Kanban TUI to track the vibe.                                                  |
-| `savepoint audit`  | Stop the AI. Sync the map with the territory.                                                        |
 | `savepoint doctor` | Check the integrity of the state machine.                                                            |
 
 ---
@@ -76,3 +75,4 @@ I’m sharing it to prove a point: The real power of AI isn't just the size of t
 
 **License:** MIT  
 **Status:** Recursive Construction (v1 MVP in progress)
+us:** Recursive Construction (v1 MVP in progress)

package/agent-skills/savepoint-audit/SKILL.md

@@ -1,35 +1,87 @@
-# 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/audit/{E##-slug}/snapshot.md` (what changed).
-- `.savepoint/releases/v1/epics/{E##-slug}/Design.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.
-3.  **Process Drift Notes (Reconciliation):** Read every task file in the Epic and look for `## Drift Notes`.
-4.  **Draft Proposals:** Based on the code changes and the Drift Notes, write exactly ONE file: `.savepoint/audit/{E##-slug}/proposals.md`. It must contain:
-    *   **Design.md section:** Propose updates to merge the epic's architectural changes into the project-level `Design.md`.
-    *   **AGENTS.md section:** Propose updates to refresh the Codebase Map table with new or changed modules.
-    *   **Epic-Design.md section:** Add "Implemented as:" notes showing where reality deviated from the original plan.
-    *   **Quality Review section:** List any minor code-style infractions that must be fixed before the next Epic.
-5.  **Review Format:** Use `## Target File`, `## Replace`, and `## With` formatting in the proposals document so it is easy for a human (or an agent) to apply later.
-6.  **Handoff:** Do not apply the proposals yourself. Do not mark the epic audited. Stop and prompt the user to review `.savepoint/audit/{E##-slug}/proposals.md` (often via the TUI). Once the user approves, the proposals are applied, and the router moves to the next Epic.
-
-## 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.
+---
+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/agent-skills/savepoint-build-task/SKILL.md

@@ -1,4 +1,9 @@
-# Savepoint Skill: Build Task (`build-task`)
+---
+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.
@@ -7,11 +12,11 @@ Act as a disciplined coding agent that strictly follows Savepoint's implementati
 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 `in-progress` and points to a specific task file.
+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 Design: `.savepoint/releases/v1/epics/{E##-epic}/Design.md`.
+- 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.
 
@@ -36,4 +41,4 @@ This skill is activated when the `.savepoint/router.md` state is `in-progress` a
 
 ## 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.
+- **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/agent-skills/savepoint-create-plan/SKILL.md

@@ -1,4 +1,9 @@
-# Savepoint Skill: Create Plan (`create-plan`)
+---
+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.
@@ -7,22 +12,22 @@ Turn the Product Requirements Document (PRD) and the architectural `Design.md` i
 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 `planning`.
+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/PRD.md` (Optional: Release-scoped PRD)
+- `.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 `Design.md` inside `.savepoint/releases/v1/epics/{E##-epic-name}/Design.md`. This file should describe the *delta* (what this specific epic adds to the overall architecture).
+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.
+- **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/agent-skills/savepoint-create-task/SKILL.md

@@ -1,31 +1,44 @@
-# 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 `task-breakdown` and the router points to a specific task file.
-
-## Input
-- `.savepoint/releases/v1/epics/{E##-epic}/Design.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.  **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.
+---
+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/agent-skills/savepoint-draft-prd/SKILL.md

@@ -1,4 +1,9 @@
-# Savepoint Skill: Draft PRD (`draft-prd`)
+---
+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.
@@ -7,7 +12,7 @@ Help the user write a structured, sufficiently detailed Product Requirements Doc
 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 `draft-prd` or when the user explicitly asks you to help them write or refine their PRD.
+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.
@@ -29,4 +34,4 @@ This skill is activated when the `.savepoint/router.md` state is `draft-prd` or
 ## 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*.
+- **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/agent-skills/savepoint-system-design/SKILL.md

@@ -1,4 +1,9 @@
-# Savepoint Skill: System Design (`system-design`)
+---
+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.
@@ -7,7 +12,7 @@ Translate the Product Requirements Document (PRD) into the initial architectural
 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 `design` or when the user explicitly asks to design the system based on the PRD.
+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").
@@ -30,4 +35,4 @@ This skill is activated when the `.savepoint/router.md` state is `design` or whe
 ## 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.
+- **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.