@esthernandez/vibe-cartographer 1.0.0

package/plugins/vibe-cartographer/skills/guide/references/eval-rubric.md

@@ -0,0 +1,103 @@
+# Review Dimensions — Agent Reference
+
+This document is for the agent only. It defines how you reason about the builder's work in /reflect. Use these dimensions to structure your thinking, but your output is qualitative observations — what landed and what to tighten — not scores or grades.
+
+## How to Use This
+
+For each dimension:
+1. **Read the relevant artifacts.** Know what you're looking at before forming opinions.
+2. **Reason through the evidence.** What's there, what's missing, what it means.
+3. **Cite specifics.** Quote or reference exact passages from the artifacts. No vague claims.
+4. **Calibrate to the builder.** The same artifact quality means different things for a first-timer vs a senior dev. Read their technical background and adjust accordingly.
+5. **Output one strength and one improvement area per dimension.** Keep each to 2-3 sentences with evidence.
+
+## Guards
+
+Apply these throughout every review:
+
+- **Calibrate to project context.** Don't expect production-quality code or professional-grade documents from a rapid build.
+- **Brevity that nails the idea beats length.** A concise scope doc that's sharp is better than a long one full of filler. Judge substance, not word count.
+- **Evaluate against the PRD, not your own taste.** The PRD's acceptance criteria are the anchor. Did the app do what the builder said it should do?
+- **If evidence is insufficient, say so.** Don't fill gaps with charitable assumptions or harsh ones. Note what's missing.
+- **Ownership matters.** A polished app built by a passive builder is less notable than a rougher app built by someone who drove every decision.
+
+## Dimensions
+
+### 1. Scope & Idea Clarity
+
+How well-defined is the idea? Does `scope.md` give a clear picture of what's being built and why?
+
+**What to look at:**
+- Is the idea stated clearly enough that someone could picture the app?
+- Is a specific user and problem identified (not "everyone" or "people")?
+- Does "What's Explicitly Cut" name real features with rationale?
+- Is "What Done Looks Like" concrete enough to verify?
+- Is the scope realistic given the builder's experience?
+
+**Strong:** The idea is sharp — one sentence and you get it. The user, problem, and constraints are specific and grounded. Scope cuts show genuine prioritization.
+
+**Needs tightening:** The idea is vague, no specific user, nothing explicitly cut, "done" is described in generalities.
+
+### 2. Requirements Thinking
+
+Does `prd.md` define complete, testable requirements? Were edge cases surfaced? Did the builder invest in specification depth?
+
+**What to look at:**
+- Do user stories cover the core user journey?
+- Are acceptance criteria specific and testable (not vague like "works well")?
+- Are edge cases and error states addressed (empty states, bad input, no results)?
+- Does "What we're building" vs "What we'd add" show genuine prioritization?
+- Is the PRD substantially more detailed than the scope doc?
+- How many deepening rounds did the builder choose? (Check process notes.) Did extra rounds produce materially better requirements, or did the builder stop at the minimum?
+
+**Strong:** Stories are comprehensive and grouped meaningfully. Every acceptance criterion is specific enough to verify by looking at the screen. Multiple edge cases addressed. Extra deepening rounds (if taken) produced tangible improvements.
+
+**Needs tightening:** PRD is a reformatted copy of the scope doc. Acceptance criteria say "it should work." No edge cases mentioned. Skipped deepening rounds and the gaps show in the build.
+
+### 3. Technical Decisions
+
+Does `spec.md` show intentional architecture choices? Does the checklist sequence make sense? Did specification depth prevent build problems?
+
+**What to look at:**
+- Are stack choices explained with rationale tied to the builder's experience?
+- Are file structure and data flow documented clearly enough for building?
+- Do architecture decisions reference PRD epics — is there traceability?
+- Is the checklist sequenced logically (dependencies respected)?
+- Does the spec address how the submission will work?
+- Did deepening rounds in /spec catch issues that would have caused problems during /build? Or did skipping them leave gaps?
+
+**Strong:** Every decision has clear rationale. File structure is annotated. Data flow is diagrammed. PRD cross-references are thorough. The builder actively shaped the architecture. Deepening round investment shows in build smoothness.
+
+**Needs tightening:** Stack listed without rationale. No file structure. No PRD connection. Checklist is a flat list with no dependency logic. Shallow specification led to build problems that deeper planning would have caught.
+
+### 4. Plan vs. Reality
+
+Does the finished app do what the PRD said it should do?
+
+**What to look at:**
+- Does the app run without crashing on the core flow?
+- How many "What we're building" acceptance criteria are met?
+- Is the core user journey functional end-to-end?
+- Where did the build drift from the plan, and did the builder adapt?
+
+**Strong:** The app does what the PRD said. Most acceptance criteria are met. The gap between plan and execution is small, or the builder noticed drift and adjusted.
+
+**Needs tightening:** Major gap between plan and build. Core features missing or broken. The builder didn't notice or address the drift.
+
+### 5. How You Worked
+
+From `process-notes.md` and comprehension check answers: did the builder actively shape the project?
+
+**What to look at:**
+- Did the builder make real decisions (not just agree to everything)?
+- Did they push back on or modify agent suggestions?
+- Were comprehension check answers engaged and accurate (if they opted in)?
+- Did the builder contribute ideas the agent hadn't suggested?
+- Did the builder's decision-making sharpen across the phases?
+- How did they approach deepening rounds? Strategic investment or rushing through?
+
+**Strong:** Process notes show full engagement at every step. Multiple instances of pushing back, redirecting, adding ideas. Comprehension checks are concise and accurate. Deepening rounds were used strategically. The project distinctly reflects the builder's vision.
+
+**Needs tightening:** The builder accepted most suggestions without pushback. Comprehension checks are vague or confused. Skipped all deepening rounds and the documents are thin. The project feels like the agent built what the agent wanted.
+
+**If the builder was mostly passive,** say it directly: "On longer projects, passive acceptance means you end up with code you can't debug, extend, or explain. Own every decision — push back, redirect, make it yours."

package/plugins/vibe-cartographer/skills/guide/references/prd-guide.md

@@ -0,0 +1,100 @@
+# PRD Guide — Agent Reference
+
+This document is for the agent only. It informs how you conduct the /prd conversation and write the PRD. Do not surface PM jargon, framework names, or theory to the builder. Use this knowledge to ask better questions and produce a more rigorous document.
+
+## What Makes a Good PRD
+
+A good PRD is exhaustive about *what* the user wants without touching *how* to build it. It translates a brainstorm (scope.md) into precise behavior descriptions. Every ambiguity, assumption, and edge case the builder didn't know they were making gets surfaced here.
+
+The PRD should be significantly more detailed than the scope doc. The scope doc is a big-picture sketch. The PRD is a zoomed-in, exhaustive accounting of what "done" actually means.
+
+## User Stories
+
+User stories are the backbone of requirements. The format is simple and accessible to anyone:
+
+**"As a [specific person], I want [thing I can do] so that [why it matters to me]."**
+
+What makes a good story:
+- The person is specific enough to picture ("a first-time visitor" not "a user")
+- The capability describes what they want to accomplish, not how the UI works ("find recipes that use what I have" not "click a dropdown menu")
+- The benefit explains the real-world value ("so I don't waste food" not "so the feature works")
+
+Common mistakes to watch for and gently redirect:
+- Too vague: "I want the app to work well" — push for specifics
+- Prescribing UI: "I want a sidebar with filters" — redirect to the need behind it
+- Missing the "so that": stories without benefits are tasks, not stories
+- Too big: "I want to manage my account" — help break it into specific capabilities
+
+When the builder describes what they want, translate their casual language into stories naturally. Don't make them write the stories — you write them together through conversation, and the builder confirms they capture what they meant.
+
+## Grouping Stories into Epics
+
+An epic is just a group of related stories that belong together. Use epics to organize the PRD when a project has multiple areas of functionality.
+
+For example, a recipe app might have:
+- **Finding recipes**: stories about searching, filtering, browsing
+- **Managing ingredients**: stories about adding what's in the fridge, tracking what's used
+- **Cooking flow**: stories about following a recipe step by step
+
+Name epics in plain language that describes the area of the app, not PM terminology. The builder should see epics as natural groupings of "things the app does," not as a framework.
+
+**Important:** Give epics clear, stable heading names in the PRD. Downstream commands (/spec, /checklist, /build) reference these headings to trace requirements through the whole process. For example, `/spec` might say "this component implements the stories in `prd.md > Finding Recipes`" and `/checklist` might reference `prd.md > Finding Recipes > no-results story`. This cross-referencing makes the documents work as a connected system, not isolated files.
+
+## Acceptance Criteria
+
+For each story or requirement, write acceptance criteria as simple checklists. These describe specific, testable behaviors — things the builder can verify with their own eyes during /build.
+
+Good acceptance criteria:
+- [ ] When I search for "chicken", recipes with chicken appear
+- [ ] If I have no ingredients saved, the app shows a helpful empty state
+- [ ] Clicking a recipe shows the full ingredient list and steps
+
+Avoid:
+- Vague criteria: "the search works well"
+- Implementation-specific criteria: "the SQL query returns results in < 100ms"
+- Untestable criteria: "the UX is intuitive"
+
+Cover the happy path first, then ask about what happens when things go wrong or are empty. Frame edge cases as "what ifs" the builder will actually encounter during build.
+
+## Asking Sharpening Questions
+
+The core technique is translating vague intentions into precise behaviors. Useful question patterns:
+
+**Zooming in:** "You said users can browse recipes. What do they see first? A list? Cards? How are they sorted?"
+
+**Surfacing assumptions:** "You're assuming people will add their ingredients. But what does the app look like before they've added anything? What's the very first thing a new user sees?"
+
+**Finding contradictions:** "You want it to be simple, but you also want filtering by cuisine, diet, and cook time. Which matters most if you had to pick one?"
+
+**Testing completeness:** "Walk me through this from start to finish. You open the app. Then what? What do you tap first? What happens next?"
+
+**Probing the edges:** "What if someone searches for something and there are no results? What if they have only one ingredient? What if they have fifty?"
+
+Calibrate depth to experience level:
+- First-timers: 2-3 "what if" moments that open their eyes to planning value
+- Junior devs: push on the interactions between features, state management implications (without using that phrase)
+- Senior devs: they'll likely anticipate edge cases — focus on helping them be explicit about decisions they're making implicitly
+
+## Scope Guarding
+
+The PRD naturally wants to expand. Your job is to be exhaustive about what's IN without letting scope grow beyond what's realistic.
+
+Watch for:
+- Requirements that keep spawning sub-requirements
+- "While we're at it" additions
+- Features the builder is excited about but that would significantly extend the build
+- Vague requirements that hide enormous complexity ("social features," "real-time sync," "recommendations")
+
+When you spot creep, name it directly: "This is growing. Is this essential for your project, or would you add it with more time?" This naturally sorts requirements into the two sections without teaching prioritization theory.
+
+## Non-Goals
+
+Strong non-goals prevent scope creep during build. They should be specific and named — "we are NOT building user profiles, because the app works fine with anonymous/session-based use" is better than "no extra features."
+
+Pull non-goals from two sources:
+1. What was explicitly cut in scope.md
+2. Adjacent features that will tempt the builder during build
+
+## Open Questions
+
+Some things won't resolve during the PRD conversation. That's fine — name them explicitly so they don't become surprise roadblocks during build. Flag whether each needs to be answered before /spec or can wait until build time.

package/plugins/vibe-cartographer/skills/guide/references/spec-patterns.md

@@ -0,0 +1,133 @@
+# Spec Patterns — Agent Reference
+
+This document is for the agent only. It informs how you conduct the /spec conversation, choose architectures, and produce the technical specification.
+
+**Important:** If the builder provided architecture docs during `/onboard`, those take precedence over the patterns in this file. Use this file as a fallback when no architecture docs are provided, or to supplement architecture docs that are incomplete.
+
+For default stack patterns and recommendations, see `architecture/default-patterns.md`.
+
+## Adapting to Architecture Docs
+
+When architecture docs are provided:
+- Use the specified stack, patterns, and conventions as your starting point
+- Still validate choices against the builder's experience level
+- Still discuss tradeoffs and alternatives, but frame them relative to the provided architecture
+- Propose modifications only when the architecture docs conflict with the project requirements from the PRD
+
+When no architecture docs are provided:
+- Use the patterns in `architecture/default-patterns.md` to recommend a stack
+- Propose whichever fits the builder's project and experience level
+
+## Diagramming
+
+Use whatever format communicates best. Options:
+
+**ASCII box diagrams** — work everywhere, no rendering dependencies:
+```
+┌──────────┐     ┌──────────┐     ┌──────────┐
+│ Frontend │────→│   API    │────→│ Database │
+└──────────┘     └──────────┘     └──────────┘
+```
+
+**Mermaid** — richer rendering in many tools:
+```mermaid
+graph LR
+  Frontend --> API --> Database
+```
+
+Ask the builder if they have a preference. If they don't care, pick whichever is clearest for the specific diagram.
+
+## File Structure Conventions
+
+Always include a full file tree in the spec. Use ASCII tree format:
+
+```
+project/
+├── src/
+│   ├── components/    # UI components
+│   ├── pages/         # Route-level pages
+│   ├── lib/           # Shared utilities
+│   └── api/           # API routes or client
+├── docs/              # Planning artifacts (scope, prd, spec, etc.)
+├── process-notes.md   # Process journal
+├── package.json
+└── README.md
+```
+
+Annotate directories with brief comments explaining purpose. The builder should be able to look at this tree and understand where everything lives.
+
+If architecture docs specify a file structure convention, use that instead.
+
+## Data Flow Documentation
+
+For any app with data, document how data moves through the system:
+1. Where does data originate? (User input, external API, file, etc.)
+2. Where is it stored? (Database, localStorage, in-memory, file)
+3. How does it get from A to B? (API call, function call, event, etc.)
+4. What transforms happen along the way?
+
+For projects, keep this pragmatic. A simple data flow narrative or diagram is enough — no need for formal data flow diagrams.
+
+## Stack Research
+
+When proposing a stack, **always web search for current documentation** on the specific tools, libraries, and APIs being used. Things change fast — a library that was standard 6 months ago might be deprecated. Check:
+- Is this library actively maintained?
+- What's the current stable version?
+- Are there known issues or migration paths?
+- Is there a simpler alternative that does the same thing?
+
+For external APIs (Supabase, Firebase, OpenAI, etc.), search for current pricing, rate limits, and quickstart guides. Link to relevant docs in the spec so the agent has them during /build.
+
+## Granular Subsections
+
+The spec MUST have granular subsections — every architectural component gets its own heading. These headings become addresses that /checklist references.
+
+Bad: one big "Architecture" section with everything in it.
+Good: `## Frontend > ### Search Component`, `## API > ### Endpoints > #### GET /recipes`, `## Data Model > ### Recipes Table`.
+
+The depth of nesting should match the complexity. A simple CLI tool might only need two levels. A full-stack app might need three or four. The rule is: if /checklist needs to point to it, it needs its own heading.
+
+## Cross-Referencing the PRD
+
+When writing the spec, reference PRD epic headings to maintain traceability:
+- "This component implements the stories in `prd.md > Finding Recipes`"
+- "See `prd.md > Managing Ingredients` for the acceptance criteria this must satisfy"
+
+This connects the architectural decisions back to the requirements. During /build, the agent can look up both the spec (how to build it) and the PRD (what it should do) for any given checklist item.
+
+## Other Areas Worth Spending Time On
+
+Beyond data flow and file structure, these areas deserve real conversation time in /spec:
+
+### State Management
+Where does state live? This is the #1 source of confusion during build. For every piece of data the app touches, the builder should be able to answer: "Where is this stored? How does it get updated? What happens when the user navigates away and comes back?" Don't use the phrase "state management" with beginners — just ask the questions in plain language.
+
+### API Contract / Interface Design
+If the app talks to any external service (Supabase, OpenAI, a third-party API), spell out the exact calls: what endpoint, what payload, what comes back. This prevents the build from stalling while the agent figures out an API it's never seen before. Include links to the relevant docs.
+
+### Error Boundaries and Fallbacks
+Not exhaustive error handling — just the 2-3 places where things will actually break during a demo. What if the API is slow? What if the database is empty? What if the user's input is weird? Decide on a simple strategy: show a loading spinner, show a helpful error message, fall back to sample data. Keep it proportional to the project scope.
+
+### Documentation & Security Review
+What does the project need to be ready to share? Walk through the README requirements, docs artifacts, and security posture now — make sure the architecture supports clean documentation and doesn't have baked-in security issues. If the app handles user data, authentication, or external APIs, those patterns need to be secure by design, not patched after the fact.
+
+If the builder wants to deploy the app for a live link, discuss options appropriate to their stack (Vercel, Netlify, GitHub Pages, Railway, Fly.io, etc.) and make sure the architecture supports easy deployment. Verify that deployment config uses environment variables for secrets, enforces HTTPS, and has intentional CORS settings. A deployed link strengthens the project but isn't required.
+
+## Deployment Considerations
+
+Ask once where the builder plans to run their app:
+- **Local only:** Simplest. Just needs to run on localhost. Screenshots and description carry the submission.
+- **Deployed URL:** Note target platform (Vercel, Netlify, GitHub Pages, Railway, Fly.io, etc.). Include deployment steps in spec. If the builder wants to deploy but doesn't know how, help them pick an option that fits their stack.
+- **Optional demo video:** The builder can record a short video and upload to YouTube or Vimeo. Not required, but it can strengthen the project.
+
+Most builders will run locally and submit with screenshots — that's fine. Don't over-invest in deployment unless the builder specifically wants a live URL.
+
+## Architecture Self-Review
+
+After drafting the spec, the agent should review its own work for:
+- Ambiguities that would confuse /build ("what exactly does 'handle auth' mean here?")
+- Failure points ("if this API is down, the whole app breaks — is there a fallback?")
+- Complexity that doesn't match the time constraint ("this data model has 6 tables for a 3-hour build")
+- Mismatches between the spec and the PRD ("the PRD says users can delete items but the spec has no delete endpoint")
+
+Surface 2-3 of the most important issues for the builder to weigh in on. Specs are living documents that benefit from review — not perfect blueprints handed down from above.

package/plugins/vibe-cartographer/skills/guide/templates/builder-profile-template.md

@@ -0,0 +1,36 @@
+<!-- This template captures who the builder is. Every downstream command reads this
+     document to calibrate its depth, tone, and recommendations. Keep it scannable. -->
+
+# Builder Profile
+
+## Who They Are
+Name (if shared), background, what brings them to this project.
+
+## Technical Experience
+Experience level (first-time coder / beginner / intermediate / experienced).
+Languages, frameworks, and tools they know.
+What they don't know but want to explore.
+AI coding agent experience (which tools, how they've used them).
+
+## Mode
+<!-- Learner | Builder -->
+<!-- Learner: guided walkthrough with explanations and encouragement -->
+<!-- Builder: streamlined flow for people ready to move -->
+
+## Project Goals
+What they want to accomplish with this project — the outcome they're building toward.
+
+## Design Direction
+The app's intended look and feel — design references, aesthetic direction, mood.
+If design docs exist, pull from those. If they referenced specific apps, games,
+or visual styles, note those as design signals.
+(If nothing surfaced, note "No strong signals — default to clean and functional.")
+
+## Prior SDD Experience
+Whether they've done structured planning before building — formal or informal.
+How this should calibrate the /reflect quiz and process explanations.
+
+## Architecture Docs
+Whether the builder provided architecture docs. If yes, note where they live
+and a brief summary of what they specify (stack, patterns, conventions).
+If no, note "No architecture docs provided — will use defaults in /spec."

package/plugins/vibe-cartographer/skills/guide/templates/checklist-template.md

@@ -0,0 +1,37 @@
+<!-- Every item MUST use the five-field format below. /build reads each item
+     and relies on all five fields being present and consistently formatted.
+     The header encodes methodology choices so /build doesn't re-ask. -->
+
+# Build Checklist
+
+## Build Preferences
+
+- **Build mode:** [Autonomous / Step-by-step]
+- **Comprehension checks:** [Yes / No / N/A (autonomous mode)]
+- **Git:** [Commit cadence and style — e.g., "Commit after each item with message: 'Complete step N: [title]'"]
+- **Verification:** [Yes / No. Step-by-step: per-item verification. Autonomous: checkpoints every 3-4 items. If No, verification is skipped.]
+- **Check-in cadence:** [Step-by-step only: Learning-driven / balanced / speed-run — how much discussion during build. N/A for autonomous.]
+
+## Checklist
+
+- [ ] **1. [Clear title — what's done when this step is complete]**
+  Spec ref: `spec.md > [Section] > [Subsection]`
+  What to build: Concrete description of the work. Specific enough that /build can execute without guessing.
+  Acceptance: Testable criteria from prd.md. What the builder verifies with their own eyes.
+  Verify: Specific action — "Run dev server and confirm [what you should see]."
+
+- [ ] **2. [Title]**
+  Spec ref: `spec.md > [Section] > [Subsection]`
+  What to build: [...]
+  Acceptance: [...]
+  Verify: [...]
+
+<!-- Continue for all items. Typical project: 8-12 items.
+     Sequence respects dependencies — earlier items unblock later ones.
+     Last item is always documentation & security verification. -->
+
+- [ ] **N. Documentation & security verification**
+  Spec ref: `prd.md > What We're Building` + `spec.md > [all sections]`
+  What to build: Write a README.md covering what the app does, how to install/run locally, required environment variables (without real values), and tech stack. Confirm all docs/ artifacts (scope, PRD, spec, checklist) are up to date. Create a `.env.example` with placeholder values. Run a secrets scan — verify no API keys, tokens, or credentials are hardcoded and that `.gitignore` covers `.env` and sensitive paths. Run a dependency audit (`npm audit` / `pip audit` / equivalent) and address critical findings. Spot-check input validation for OWASP Top 10 basics (injection, XSS). If the app has auth, verify protected routes require it server-side. If deploying, confirm env vars use the platform’s secrets manager, HTTPS is enforced, CORS is intentional, and debug mode is off. Push code to GitHub.
+  Acceptance: README exists and is clear. `.env.example` exists. No secrets in committed code. Dependency audit shows no unaddressed critical vulnerabilities. Security spot-check documented. Code is pushed to GitHub.
+  Verify: Clone the repo fresh, follow the README to set up — can someone who’s never seen the project get it running? Run `git log --all -p | grep -i "password\|secret\|api_key"` and confirm nothing sensitive appears.

package/plugins/vibe-cartographer/skills/guide/templates/prd-template.md

@@ -0,0 +1,49 @@
+<!-- This template is a starting point. Add sections if the conversation surfaces
+     things worth capturing. The PRD should be significantly more detailed than
+     the scope doc — that expansion is the whole point of this step. -->
+
+# [Project Name] — Product Requirements
+
+## Problem Statement
+2-3 sentences. Who experiences this problem, how often, and what it costs them.
+Grounded in the scope doc but sharper and more specific.
+
+## User Stories
+
+<!-- Group stories into epics (natural groupings of related functionality).
+     Name each epic in plain language that describes the area of the app.
+     Order stories within each epic by importance. -->
+
+### [Epic: area of functionality]
+
+- As a [specific person], I want [capability] so that [benefit].
+  - [ ] Acceptance criterion
+  - [ ] Acceptance criterion
+  - [ ] Edge case or error state
+
+- As a [specific person], I want [capability] so that [benefit].
+  - [ ] Acceptance criterion
+  - [ ] Acceptance criterion
+
+### [Epic: another area]
+
+- ...
+
+## What We're Building
+Everything the app must do to be complete.
+Each item has acceptance criteria — specific, testable behaviors the builder
+can verify with their own eyes. These become the basis for the build checklist.
+
+## What We'd Add With More Time
+Features or polish that would make the app better but aren't essential.
+Keep these lighter — a sentence or two each, no full acceptance criteria.
+These are available as starting points if the builder runs /iterate after build.
+
+## Non-Goals
+3-5 things this project explicitly will NOT do.
+Each with a brief rationale. Pull from scope.md cuts and any new ones
+surfaced during the PRD conversation.
+
+## Open Questions
+Unresolved items that might surface during spec or build.
+Flag whether each needs answering before /spec or can wait.

package/plugins/vibe-cartographer/skills/guide/templates/reflection-template.md

@@ -0,0 +1,55 @@
+<!-- This reflection is generated by an AI. It ships with the project
+     as part of the documentation. The note at the top is intentional
+     and should not be removed. -->
+
+# Reflection — [Project Name]
+
+> **Note:** This feedback is AI-generated. It's observational, not authoritative. Use what's useful.
+
+## Scope & Idea Clarity
+
+**What landed:** [One specific strength, with evidence from scope.md]
+
+**What to tighten:** [One specific, actionable improvement]
+
+## Requirements Thinking
+
+**What landed:** [One specific strength, with evidence from prd.md]
+
+**What to tighten:** [One specific, actionable improvement]
+
+## Technical Decisions
+
+**What landed:** [One specific strength, with evidence from spec.md and checklist.md]
+
+**What to tighten:** [One specific, actionable improvement]
+
+## Plan vs. Reality
+
+**What landed:** [One specific strength — where the build matched the plan, or where the builder adapted well to drift]
+
+**What to tighten:** [One specific, actionable improvement]
+
+## How You Worked
+
+**What landed:** [One specific strength from process-notes.md — a moment of active engagement, pushback, or original thinking]
+
+**What to tighten:** [One specific, actionable improvement]
+
+## Your Goals
+
+[Loop back to the builder's stated project goals. Connect the feedback to what they said they wanted to accomplish.]
+
+## Reflection
+
+[The builder's answer to the reflection question, and the agent's response.]
+
+## Milestone Completion
+
+- /scope: [complete/incomplete]
+- /prd: [complete/incomplete]
+- /spec: [complete/incomplete]
+- /checklist: [complete/incomplete]
+- /build: [N/M checklist items completed]
+- /iterate: [N iteration cycles, or "skipped"]
+- /reflect: complete

package/plugins/vibe-cartographer/skills/guide/templates/scope-template.md

@@ -0,0 +1,29 @@
+<!-- This template is a starting point. Add more sections if the conversation
+     surfaces things worth capturing that don't fit neatly below. The scope doc
+     should reflect the full richness of the conversation. -->
+
+# [Project Name]
+
+## Idea
+One-line description, refined through conversation.
+
+## Who It's For
+Specific user, specific problem, specific unmet need.
+
+## Inspiration & References
+Links, examples, visual references, mood/aesthetic notes.
+Design energy: fonts, colors, style direction (if applicable).
+Include URLs to everything referenced — these become a research map
+that /spec and other downstream commands can use to gather more context.
+
+## Goals
+What the builder wants this project to accomplish. What would make them proud.
+
+## What "Done" Looks Like
+Concrete description of the finished product.
+
+## What's Explicitly Cut
+Named features, use cases, or scope that is OUT. With brief rationale.
+
+## Loose Implementation Notes
+Early thinking on approach. Non-binding. Gets refined in /spec.

package/plugins/vibe-cartographer/skills/guide/templates/spec-template.md

@@ -0,0 +1,68 @@
+<!-- This template is fully adaptive — section names and depth should match
+     whatever the project actually is. The only hard rule: every architectural
+     component gets its own heading so /checklist can reference it.
+     Add or remove sections freely.
+     If architecture docs were provided during /onboard, use them as the
+     foundation for stack choices, patterns, and file structure. -->
+
+# [Project Name] — Technical Spec
+
+## Stack
+Language, framework, key libraries. Brief rationale tied to builder's
+preferences and experience level.
+Link to current documentation for each major dependency.
+
+## Runtime & Deployment
+Where the app runs (web, desktop, CLI, mobile).
+Deployment target: local demo, deployed URL, screen recording only.
+Any environment requirements (Node version, Python version, API keys needed).
+
+## Architecture Overview
+Diagram showing major components and how they connect.
+Data flow between frontend, backend, database, external services.
+Use ASCII or Mermaid — whatever communicates best.
+
+<!-- Each section below is an example. Replace with whatever sections
+     match this project's actual architecture. The key rule: granular
+     enough that /checklist can point to specific subsections. -->
+
+## [Component Area 1]
+### [Subcomponent]
+What it does. How it connects to other components.
+PRD ref: `prd.md > [Epic]` — the stories this implements.
+
+### [Subcomponent]
+...
+
+## [Component Area 2]
+### [Subcomponent]
+...
+
+## Data Model
+Schema, relationships, state shape — whatever fits the stack.
+### [Entity/Table/Collection]
+Fields, types, relationships.
+
+## File Structure
+Full ASCII tree of every file and folder, annotated with purpose.
+
+```
+project/
+├── src/
+│   └── ...
+├── docs/           # planning artifacts
+├── process-notes.md
+└── ...
+```
+
+## Key Technical Decisions
+2-3 decisions made during the conversation.
+Each with: what was decided, why, and what tradeoff was accepted.
+
+## Dependencies & External Services
+APIs, databases, hosting, anything outside the codebase.
+Link to documentation. Note any rate limits, pricing, or API keys needed.
+
+## Open Issues
+Ambiguities or risks surfaced during architecture self-review.
+Any unresolved questions from the PRD's open questions section.