savepoint 1.0.3 → 1.0.6

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

@@ -1,87 +0,0 @@
----
-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,44 +0,0 @@
----
-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/agent-skills/savepoint-create-plan/SKILL.md

@@ -1,33 +0,0 @@
----
-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/agent-skills/savepoint-create-task/SKILL.md

@@ -1,44 +0,0 @@
----
-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,37 +0,0 @@
----
-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/agent-skills/savepoint-system-design/SKILL.md

@@ -1,38 +0,0 @@
----
-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/agent-skills/superpowers/brainstorming/SKILL.md

@@ -1,165 +0,0 @@
----
-name: brainstorming
-description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
----
-
-# Brainstorming Ideas Into Designs
-
-Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
-
-Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
-
-<HARD-GATE>
-Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
-</HARD-GATE>
-
-## Anti-Pattern: "This Is Too Simple To Need A Design"
-
-Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
-
-## Checklist
-
-You MUST create a task for each of these items and complete them in order:
-
-1. **Explore project context** — check files, docs, recent commits
-2. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See the Visual Companion section below.
-3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
-4. **Propose 2-3 approaches** — with trade-offs and your recommendation
-5. **Present design** — in sections scaled to their complexity, get user approval after each section
-6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
-7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
-8. **User reviews written spec** — ask user to review the spec file before proceeding
-9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
-
-## Process Flow
-
-```dot
-digraph brainstorming {
-    "Explore project context" [shape=box];
-    "Visual questions ahead?" [shape=diamond];
-    "Offer Visual Companion\n(own message, no other content)" [shape=box];
-    "Ask clarifying questions" [shape=box];
-    "Propose 2-3 approaches" [shape=box];
-    "Present design sections" [shape=box];
-    "User approves design?" [shape=diamond];
-    "Write design doc" [shape=box];
-    "Spec self-review\n(fix inline)" [shape=box];
-    "User reviews spec?" [shape=diamond];
-    "Invoke writing-plans skill" [shape=doublecircle];
-
-    "Explore project context" -> "Visual questions ahead?";
-    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
-    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
-    "Offer Visual Companion\n(own message, no other content)" -> "Ask clarifying questions";
-    "Ask clarifying questions" -> "Propose 2-3 approaches";
-    "Propose 2-3 approaches" -> "Present design sections";
-    "Present design sections" -> "User approves design?";
-    "User approves design?" -> "Present design sections" [label="no, revise"];
-    "User approves design?" -> "Write design doc" [label="yes"];
-    "Write design doc" -> "Spec self-review\n(fix inline)";
-    "Spec self-review\n(fix inline)" -> "User reviews spec?";
-    "User reviews spec?" -> "Write design doc" [label="changes requested"];
-    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
-}
-```
-
-**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
-
-## The Process
-
-**Understanding the idea:**
-
-- Check out the current project state first (files, docs, recent commits)
-- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
-- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
-- For appropriately-scoped projects, ask questions one at a time to refine the idea
-- Prefer multiple choice questions when possible, but open-ended is fine too
-- Only one question per message - if a topic needs more exploration, break it into multiple questions
-- Focus on understanding: purpose, constraints, success criteria
-
-**Exploring approaches:**
-
-- Propose 2-3 different approaches with trade-offs
-- Present options conversationally with your recommendation and reasoning
-- Lead with your recommended option and explain why
-
-**Presenting the design:**
-
-- Once you believe you understand what you're building, present the design
-- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
-- Ask after each section whether it looks right so far
-- Cover: architecture, components, data flow, error handling, testing
-- Be ready to go back and clarify if something doesn't make sense
-
-**Design for isolation and clarity:**
-
-- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
-- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
-- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
-- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
-
-**Working in existing codebases:**
-
-- Explore the current structure before proposing changes. Follow existing patterns.
-- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
-- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
-
-## After the Design
-
-**Documentation:**
-
-- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
-  - (User preferences for spec location override this default)
-- Use elements-of-style:writing-clearly-and-concisely skill if available
-- Commit the design document to git
-
-**Spec Self-Review:**
-After writing the spec document, look at it with fresh eyes:
-
-1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
-2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
-3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
-4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
-
-Fix any issues inline. No need to re-review — just fix and move on.
-
-**User Review Gate:**
-After the spec review loop passes, ask the user to review the written spec before proceeding:
-
-> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
-
-Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
-
-**Implementation:**
-
-- Invoke the writing-plans skill to create a detailed implementation plan
-- Do NOT invoke any other skill. writing-plans is the next step.
-
-## Key Principles
-
-- **One question at a time** - Don't overwhelm with multiple questions
-- **Multiple choice preferred** - Easier to answer than open-ended when possible
-- **YAGNI ruthlessly** - Remove unnecessary features from all designs
-- **Explore alternatives** - Always propose 2-3 approaches before settling
-- **Incremental validation** - Present design, get approval before moving on
-- **Be flexible** - Go back and clarify when something doesn't make sense
-
-## Visual Companion
-
-A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
-
-**Offering the companion:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
-
-> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"
-
-**This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. The message should contain ONLY the offer above and nothing else. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
-
-**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**
-
-- **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
-- **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
-
-A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.
-
-If they agree to the companion, read the detailed guide before proceeding:
-`skills/brainstorming/visual-companion.md`