savepoint 1.2.6 → 1.2.7

package/README.md

@@ -1,127 +1,127 @@
-![Savepoint Logo](assets/logo.png)
-
-# 💾 SAVEPOINT
-
-> **Hard Gates. Zero Drift. All Vibe.**
-
-Built for **vibe coders** on tight token budgets who still want to ship.
-
-```bash
-npx savepoint init
-```
-
-I love building side projects with AI. It feels like magic. But the reality of "vibe coding" is that it usually falls apart on day three. Not because the model is bad, but because there are no boundaries.
-
-AI-driven development fails for three specific reasons:
-
-1. **The Drift:** Your `Design.md` and agent instructions go stale after the first iteration; nobody updates them.
-2. **Token Bloat:** Monolithic backlogs and MCP overhead burn your context window — and your budget.
-3. **The Chaos:** No repeatable process from a "vibe" to a working MVP.
-
-**Savepoint is a baby gate for AI agents.**
-
-It’s a simple, file-based state machine and cinematic Terminal UI (TUI) designed to force you—and your agent (Claude, Cursor, Aider, Gemini)—to slow down, write down what you're actually building, and check your work before moving on.
-
-No database. No proprietary cloud. **No telemetry, ever.** Your filesystem is the map, and Savepoint keeps the agent on it.
-
----
-
-## 🔄 The Loop (Driven by Agent Skills)
-
-Savepoint turns your project into a series of hard gates, enforced by **six bundled custom agent skills** (`draft-prd`, `system-design`, `create-plan`, `create-task`, `build-task`, `audit`). You cannot move forward until the current gate is cleared.
-
-`[ PRD ]` **→** `[ DESIGN ]` **→** `[ EPICS ]` **→** `[ TASKS ]` **→** `[ BUILD ]` **→** `[ AUDIT ]`
-
-Small scopes. Small context windows. No wandering.
-
-- **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.**
-
----
-
-## 🛠 The Stack (Atari-Noir)
-
-Built for a cinematic, technical feel without the bloat.
-
-- **Cinematic TUI:** Built with Go and Bubble Tea. It feels like a proper terminal tool, lightning-fast and dependency-free.
-- **File-First:** Your project's state lives in markdown and JSON files right next to your code.
-- **Agent-Agnostic:** Claude, Cursor, Aider, Gemini — if it reads markdown and edits files, it works. No MCP server. No per-agent adapters.
-- **Token-Efficient by Design:** Tasks read <2KB of context. Audits stay under ~15KB. No more burning your AI budget on bloated backlogs.
-
----
-
-## 💻 Commands (0.1.0-MVP)
-
-| Command            | Action                                                                                               |
-| :----------------- | :--------------------------------------------------------------------------------------------------- |
-| `savepoint --version` | Print the installed Savepoint version.                                                            |
-| `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 doctor` | Check the integrity of the state machine.                            |
-| `savepoint upgrade-assets [dir] [--dry-run] [--force]` | Refresh package-owned templates and agent skills in an existing Savepoint project without touching project state. |
-
----
-
-## 🐛 Defect Workflow
-
-When a bug surfaces during a build or after a release, create a defect file instead of a new task. Defects live in `.savepoint/releases/{release}/defects/` and are tracked separately from the epic backlog so the audit trail stays clean.
-
-```
-.savepoint/releases/v1/defects/
-  D001-auth-crash.md
-  D002-slow-query.md
-```
-
-Each defect file uses YAML frontmatter:
-
-```yaml
----
-id: v1/D001-auth-crash
-release: v1
-status: planned          # planned | in_progress | done
-severity: high           # critical | high | medium | low
-title: "Auth crash on empty token"
-introduced: v1.0.3       # optional: version where bug appeared
-reference: E12-slug/T003-slug  # optional: related task ID
----
-```
-
-- Press **`d`** on the board to open the defect overlay and see all defects for the current release.
-- `savepoint doctor` validates defect files and reports malformed frontmatter, invalid status, and broken task references.
-
-**Use a defect when:** a regression is found in TUI testing, a build breaks after a merged epic, or a production bug is traced to a known release.
-
-**Do NOT use a defect when:** a planned task needs rework (update the task instead), a scope changes (that is an epic), or something is a future enhancement.
-
----
-
-## 📦 Updating
-
-After updating the Savepoint package:
-
-```bash
-npm update -g savepoint
-savepoint upgrade-assets
-```
-
-The `upgrade-assets` command refreshes bundled `agent-skills/**/SKILL.md` files and the Savepoint-managed block in `AGENTS.md` from the latest templates. It never overwrites `.savepoint/PRD.md`, `.savepoint/Design.md`, `.savepoint/releases/**`, or any task/epic/audit files.
-
-Use `--dry-run` to preview changes before applying them.
-
----
-
-## 🪞 Recursive Construction
-
-I am building Savepoint to dogfood the very workflow it enables. **This entire repository is being built by agents, guided by Savepoint’s own state machine.**
-
-I’m sharing it to prove a point: The real power of AI isn't just the size of the LLM—it’s the structure you give it. Token-efficient, documentation-first development is the only way to build at scale with AI without losing your mind.
-
-**The goal:** Go from `npx savepoint init` to a merged epic in one weekend.
-
-**License:** MIT  
-**Status:** Recursive Construction (v1 MVP in progress)
+![Savepoint Logo](assets/logo.png)
+
+# 💾 SAVEPOINT
+
+> **Hard Gates. Zero Drift. All Vibe.**
+
+Built for **vibe coders** on tight token budgets who still want to ship.
+
+```bash
+npx savepoint init
+```
+
+I love building side projects with AI. It feels like magic. But the reality of "vibe coding" is that it usually falls apart on day three. Not because the model is bad, but because there are no boundaries.
+
+AI-driven development fails for three specific reasons:
+
+1. **The Drift:** Your `Design.md` and agent instructions go stale after the first iteration; nobody updates them.
+2. **Token Bloat:** Monolithic backlogs and MCP overhead burn your context window — and your budget.
+3. **The Chaos:** No repeatable process from a "vibe" to a working MVP.
+
+**Savepoint is a baby gate for AI agents.**
+
+It’s a simple, file-based state machine and cinematic Terminal UI (TUI) designed to force you—and your agent (Claude, Cursor, Aider, Gemini)—to slow down, write down what you're actually building, and check your work before moving on.
+
+No database. No proprietary cloud. **No telemetry, ever.** Your filesystem is the map, and Savepoint keeps the agent on it.
+
+---
+
+## 🔄 The Loop (Driven by Agent Skills)
+
+Savepoint turns your project into a series of hard gates, enforced by **six bundled custom agent skills** (`draft-prd`, `system-design`, `create-plan`, `create-task`, `build-task`, `audit`). You cannot move forward until the current gate is cleared.
+
+`[ PRD ]` **→** `[ DESIGN ]` **→** `[ EPICS ]` **→** `[ TASKS ]` **→** `[ BUILD ]` **→** `[ AUDIT ]`
+
+Small scopes. Small context windows. No wandering.
+
+- **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.**
+
+---
+
+## 🛠 The Stack (Atari-Noir)
+
+Built for a cinematic, technical feel without the bloat.
+
+- **Cinematic TUI:** Built with Go and Bubble Tea. It feels like a proper terminal tool, lightning-fast and dependency-free.
+- **File-First:** Your project's state lives in markdown and JSON files right next to your code.
+- **Agent-Agnostic:** Claude, Cursor, Aider, Gemini — if it reads markdown and edits files, it works. No MCP server. No per-agent adapters.
+- **Token-Efficient by Design:** Tasks read <2KB of context. Audits stay under ~15KB. No more burning your AI budget on bloated backlogs.
+
+---
+
+## 💻 Commands (0.1.0-MVP)
+
+| Command            | Action                                                                                               |
+| :----------------- | :--------------------------------------------------------------------------------------------------- |
+| `savepoint --version` | Print the installed Savepoint version.                                                            |
+| `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 doctor` | Check the integrity of the state machine.                            |
+| `savepoint upgrade-assets [dir] [--dry-run] [--force]` | Refresh package-owned templates and agent skills in an existing Savepoint project without touching project state. |
+
+---
+
+## 🐛 Defect Workflow
+
+When a bug surfaces during a build or after a release, create a defect file instead of a new task. Defects live in `.savepoint/releases/{release}/defects/` and are tracked separately from the epic backlog so the audit trail stays clean.
+
+```
+.savepoint/releases/v1/defects/
+  D001-auth-crash.md
+  D002-slow-query.md
+```
+
+Each defect file uses YAML frontmatter:
+
+```yaml
+---
+id: v1/D001-auth-crash
+release: v1
+status: planned          # planned | in_progress | done
+severity: high           # critical | high | medium | low
+title: "Auth crash on empty token"
+introduced: v1.0.3       # optional: version where bug appeared
+reference: E12-slug/T003-slug  # optional: related task ID
+---
+```
+
+- Press **`d`** on the board to open the defect overlay and see all defects for the current release.
+- `savepoint doctor` validates defect files and reports malformed frontmatter, invalid status, and broken task references.
+
+**Use a defect when:** a regression is found in TUI testing, a build breaks after a merged epic, or a production bug is traced to a known release.
+
+**Do NOT use a defect when:** a planned task needs rework (update the task instead), a scope changes (that is an epic), or something is a future enhancement.
+
+---
+
+## 📦 Updating
+
+After updating the Savepoint package:
+
+```bash
+npm update -g savepoint
+savepoint upgrade-assets
+```
+
+The `upgrade-assets` command refreshes bundled `agent-skills/**/SKILL.md` files and the Savepoint-managed block in `AGENTS.md` from the latest templates. It never overwrites `.savepoint/PRD.md`, `.savepoint/Design.md`, `.savepoint/releases/**`, or any task/epic/audit files.
+
+Use `--dry-run` to preview changes before applying them.
+
+---
+
+## 🪞 Recursive Construction
+
+I am building Savepoint to dogfood the very workflow it enables. **This entire repository is being built by agents, guided by Savepoint’s own state machine.**
+
+I’m sharing it to prove a point: The real power of AI isn't just the size of the LLM—it’s the structure you give it. Token-efficient, documentation-first development is the only way to build at scale with AI without losing your mind.
+
+**The goal:** Go from `npx savepoint init` to a merged epic in one weekend.
+
+**License:** MIT  
+**Status:** Recursive Construction (v1 MVP in progress)

package/bin/savepoint.js

@@ -1,34 +1,34 @@
-#!/usr/bin/env node
-
-const { spawnSync } = require("node:child_process");
-const path = require("node:path");
-
-const platformMap = {
-  darwin: "darwin",
-  linux: "linux",
-  win32: "windows",
-};
-
-const archMap = {
-  arm64: "arm64",
-  x64: "amd64",
-};
-
-const goos = platformMap[process.platform];
-const goarch = archMap[process.arch];
-
-if (!goos || !goarch) {
-  console.error(`savepoint does not support ${process.platform}/${process.arch}`);
-  process.exit(1);
-}
-
-const executable = goos === "windows" ? "savepoint.exe" : "savepoint";
-const binary = path.join(__dirname, "..", "dist", "npm", `${goos}-${goarch}`, executable);
-const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
-
-if (result.error) {
-  console.error(result.error.message);
-  process.exit(1);
-}
-
-process.exit(result.status ?? 0);
+#!/usr/bin/env node
+
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const platformMap = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+};
+
+const archMap = {
+  arm64: "arm64",
+  x64: "amd64",
+};
+
+const goos = platformMap[process.platform];
+const goarch = archMap[process.arch];
+
+if (!goos || !goarch) {
+  console.error(`savepoint does not support ${process.platform}/${process.arch}`);
+  process.exit(1);
+}
+
+const executable = goos === "windows" ? "savepoint.exe" : "savepoint";
+const binary = path.join(__dirname, "..", "dist", "npm", `${goos}-${goarch}`, executable);
+const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 0);

package/package.json

@@ -1,35 +1,35 @@
-{
-  "name": "savepoint",
-  "version": "1.2.6",
-  "description": "It’s a simple, file-based state machine and cinematic Terminal UI (TUI) designed to force you—and your agent (Claude, Cursor, Aider, Gemini)—to slow down, write down what you're actually building, and check your work before moving on.",
-  "keywords": [
-    "board",
-    "kanban",
-    "planning"
-  ],
-  "homepage": "https://github.com/anipatke/savepoint#readme",
-  "bugs": {
-    "url": "https://github.com/anipatke/savepoint/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/anipatke/savepoint.git"
-  },
-  "license": "MIT",
-  "author": "anipatke",
-  "bin": {
-    "savepoint": "./bin/savepoint.js"
-  },
-  "files": [
-    "bin/savepoint.js",
-    "dist/npm",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "go run ./internal/buildtool build-npm",
-    "test": "echo \"Run 'make test' for Go tests\"",
-    "postinstall": "node -e \"console.log('Run \\\"savepoint upgrade-assets\\\" in each existing Savepoint project to refresh agent skills and templates.')\"",
-    "prepublishOnly": "npm run build"
-  }
-}
+{
+  "name": "savepoint",
+  "version": "1.2.7",
+  "description": "It’s a simple, file-based state machine and cinematic Terminal UI (TUI) designed to force you—and your agent (Claude, Cursor, Aider, Gemini)—to slow down, write down what you're actually building, and check your work before moving on.",
+  "keywords": [
+    "board",
+    "kanban",
+    "planning"
+  ],
+  "homepage": "https://github.com/anipatke/savepoint#readme",
+  "bugs": {
+    "url": "https://github.com/anipatke/savepoint/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anipatke/savepoint.git"
+  },
+  "license": "MIT",
+  "author": "anipatke",
+  "bin": {
+    "savepoint": "./bin/savepoint.js"
+  },
+  "files": [
+    "bin/savepoint.js",
+    "dist/npm",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "go run ./internal/buildtool build-npm",
+    "test": "echo \"Run 'make test' for Go tests\"",
+    "postinstall": "node -e \"console.log('Run \\\"savepoint upgrade-assets\\\" in each existing Savepoint project to refresh agent skills and templates.')\"",
+    "prepublishOnly": "npm run build"
+  }
+}