gsd-cc 0.9.0 → 1.0.0

package/bin/install.js

@@ -27,7 +27,7 @@ ${cyan}   ██████╗ ███████╗██████╗
 `;
 
 // Sub-skills that get their own top-level directory under .claude/skills/
-const SUB_SKILLS = ['apply', 'auto', 'config', 'discuss', 'help', 'ideate', 'plan', 'profile', 'seed', 'status', 'tutorial', 'unify', 'update'];
+const SUB_SKILLS = ['apply', 'auto', 'config', 'discuss', 'help', 'ideate', 'plan', 'profile', 'seed', 'status', 'tutorial', 'unify', 'update', 'vision'];
 
 // Shared directories that go into gsd-cc-shared/
 const SHARED_DIRS = ['checklists', 'prompts', 'templates'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-cc",
-  "version": "0.9.0",
+  "version": "1.0.0",
   "description": "Get Shit Done on Claude Code — structured AI development with your Max plan",
   "author": "Philipp Briese (https://github.com/0ui-labs)",
   "homepage": "https://github.com/0ui-labs/GSD-CC#readme",

package/skills/gsd/SKILL.md

@@ -184,6 +184,7 @@ Execute S01? (manual or auto)
 ## Delegating to Sub-Skills
 
 When routing to a sub-skill, tell the user what you're doing and then invoke the skill:
+- Vision document → `/gsd-cc-vision`
 - Decision profile → `/gsd-cc-profile`
 - Brainstorming → `/gsd-cc-ideate`
 - Ideation → `/gsd-cc-seed`

package/skills/gsd/apply/SKILL.md

@@ -34,9 +34,12 @@ Load ONLY these files — nothing else:
 | `.gsd/S{nn}-PLAN.md` | Slice overview for context |
 | `.gsd/DECISIONS.md` | Decisions that affect implementation |
 | `.gsd/S{nn}-T{prev}-SUMMARY.md` | Previous task summaries (all that exist for this slice) |
+| `.gsd/VISION.md` | User's detailed intentions (if it exists) — check alignment during implementation |
 
 **Do NOT load:** PLANNING.md, ROADMAP.md, PROJECT.md, RESEARCH.md, CONTEXT.md, or files from other slices. These are not needed during execution and waste context window space.
 
+**Vision alignment:** If the task implements something described in VISION.md, ensure the implementation matches the user's intention. If you must deviate, note it in the task summary: "Vision says X, implemented Y because Z."
+
 ## Step 3: Read and Announce the Plan
 
 Parse the task plan XML. Display to the user:

package/skills/gsd/discuss/SKILL.md

@@ -23,6 +23,7 @@ Check for "GSD-CC language: {lang}" in CLAUDE.md (loaded automatically). All out
 3. Read `.gsd/PLANNING.md` — for overall project context
 4. Read `.gsd/DECISIONS.md` — for decisions already made
 5. Read `.gsd/type.json` — for project type and rigor
+6. Read `.gsd/VISION.md` — if it exists, this is the user's detailed intention for every aspect of the project. Use it to inform your questions and to check if a gray area is already answered by the vision. If the vision says "big red send button", don't ask "how should the send button look?" — it's already decided.
 
 ## Step 2: Identify Gray Areas
 

package/skills/gsd/plan/SKILL.md

@@ -25,6 +25,7 @@ Read these files (all that exist):
 4. `.gsd/DECISIONS.md` — all decisions made so far
 5. `.gsd/S{nn}-CONTEXT.md` — discuss phase output (if it exists)
 6. `.gsd/type.json` — rigor and type config
+7. `.gsd/VISION.md` — if it exists, the user's detailed intentions. Acceptance criteria should align with vision details. If a task implements something the user described in the vision, reference it.
 
 ## Step 2: Research
 

package/skills/gsd/profile/SKILL.md

@@ -30,73 +30,99 @@ If `.gsd/PROFILE.md` already exists, ask: "You already have a profile. Update it
 
 Go deep. This interview should take 15-25 minutes. Don't rush. Ask ONE question at a time. Follow up on interesting answers. The goal is to understand the person, not fill out a form.
 
-### Section 1: Background & Context
+**CRITICAL: Adapt your language to the user's level.** The questions below are guidelines, not scripts. A senior engineer can handle "monolith or microservices?" A first-time builder needs "should it start simple or be built for growth from day one?" Read the room from the first answer and adjust everything that follows.
 
-- "What's your technical background? Self-taught, bootcamp, CS degree, something else?"
-- "How long have you been building software?"
-- "What's the biggest project you've shipped?"
-- "Do you code full-time or is this a side project / business tool?"
+### Section 1: Who Are You?
 
-Adapt the rest of the interview based on their level. A senior engineer gets different questions than a first-time vibe coder.
+Start casual. Get a feel for who you're talking to.
 
-### Section 2: Architecture & Design Philosophy
+- "Tell me a bit about yourself — do you build software for a living, or is this more of a side thing?"
+- "Have you built something before that you were proud of? What was it?"
+- "How do you usually work — do you plan everything first, or do you figure it out as you go?"
 
-- "When you start a new project, what do you set up first?"
-- "Monolith or microservices — and why?"
-- "How do you feel about ORMs? Raw SQL? Query builders?"
-- "REST, GraphQL, tRPC, gRPC — what's your instinct and why?"
-- "How much abstraction is too much? When does DRY become harmful?"
-- "Do you prefer convention over configuration (Rails-style) or explicit control (Express-style)?"
-- "What's a popular pattern or tool that you think is overrated?"
-- "What's an unpopular opinion you hold about software architecture?"
+**Based on their answers, determine their level:**
+- **Beginner/Vibe Coder:** No CS background, maybe built a few things with AI help, thinks in terms of "I want it to do X" not "I need an API endpoint"
+- **Intermediate:** Has shipped a few projects, knows some frameworks, has opinions but not strong ones
+- **Advanced:** Years of experience, strong opinions, can discuss tradeoffs in depth
 
-### Section 3: Tech Stack Preferences
+**Adapt ALL following questions to their level.** The sections below show both styles — pick the right one.
 
-- "What languages do you reach for? What languages do you avoid?"
-- "Frontend framework preference? Why?"
-- "Database preference? SQL vs NoSQL — when and why?"
-- "How do you feel about TypeScript? Strict mode?"
-- "Testing: TDD, test-after, or 'I'll add tests when it breaks'?"
-- "CSS approach: Tailwind, CSS modules, styled-components, vanilla?"
-- "Package preferences: do you prefer fewer dependencies or best-in-class for each need?"
+### Section 2: How Do You Like Things Built?
 
-### Section 4: Quality & Standards
+**For beginners:**
+- "When you imagine your project — should it be simple and just work, or do you want it built so it can grow into something bigger later?"
+- "Do you care about what's under the hood, or just that it works?"
+- "If Claude has to pick between two ways to build something — one is quicker but messier, one takes longer but is cleaner — which would you prefer?"
+- "Are there apps or tools you use that you think are really well made? What do you like about them?"
+- "Is there software you've used that frustrated you? What was annoying about it?"
 
-- "What does 'done' mean to you? When is code ready to ship?"
-- "How much error handling is enough? Do you handle every edge case upfront or ship and iterate?"
-- "Logging and observability: how much do you add from the start?"
-- "Performance: optimize early or only when there's a measured problem?"
-- "Security: what do you always do, what do you skip for MVPs?"
-- "Code comments: a lot, a little, or 'the code should speak for itself'?"
+**For advanced users:**
+- "What drives your architecture decisions — simplicity, scalability, developer experience, something else?"
+- "Where do you fall on the 'build it right vs. ship it fast' spectrum? Does it depend on context?"
+- "What's a popular approach that you think is overrated?"
+- "What's an unpopular opinion you hold about how software should be built?"
 
-### Section 5: Process & Decision-Making
+### Section 3: Tools & Technologies
 
-- "When you face two valid approaches, how do you decide? Gut feeling? Research? Ask someone?"
-- "How do you handle scope creep? Are you strict about MVP or do you let features grow?"
-- "When something isn't working, how long do you try before switching approaches?"
-- "What makes you rage-quit a library or tool?"
-- "What's a mistake you've made that changed how you build things?"
+**For beginners:**
+- "Do you have a preference for how things look? Modern and clean? Colorful? Simple?"
+- "Is this going to be a website, an app, something that runs on your computer, or something else?"
+- "Have you used or heard about specific tools or languages that you'd like to use — or avoid?"
+- "Do you want Claude to pick the best tools, or do you want to have a say?"
 
-### Section 6: Aesthetics & UX (if relevant)
+**For advanced users:**
+- "What's your go-to stack? What do you reach for by default?"
+- "Any technologies you refuse to use? Why?"
+- "How do you feel about dependencies — fewer is better, or best tool for each job?"
+- "Testing philosophy — when and how much?"
 
-- "How important is UI polish for v1?"
-- "Do you prefer minimal/clean or feature-rich/dense interfaces?"
-- "Mobile-first or desktop-first?"
-- "Dark mode?"
-- "What apps or websites do you think are really well-designed?"
+### Section 4: Quality & "Good Enough"
 
-### Section 7: Red Lines & Non-Negotiables
+**For beginners:**
+- "When would you say something is 'done'? When it works? When it looks nice? When it handles weird situations?"
+- "If something goes wrong while someone uses your app — should it crash, show an error message, or try to fix itself?"
+- "How polished does it need to be for version 1? Perfect, or good enough to use?"
+- "Is speed important? Should it feel instant?"
 
-- "What should Claude NEVER do in your projects?"
-- "What patterns or approaches are absolute no-gos for you?"
-- "Any libraries or tools you refuse to use? Why?"
-- "Is there anything where you'd rather have ugly-but-working than clean-but-incomplete?"
+**For advanced users:**
+- "What's your bar for shipping? What's your bar for 'done done'?"
+- "Error handling strategy — defensive from day one, or add as needed?"
+- "Performance — optimize early or measure first?"
+- "Security baseline — what do you always do, what do you defer?"
 
-### Section 8: Wildcards
+### Section 5: How You Think & Decide
 
-- "If you could mass-delete one concept from modern software development, what would it be?"
-- "What do beginners understand better than experts?"
-- "Is there a 'wrong' way of doing things that you secretly think is fine?"
+**For everyone (adapt tone):**
+- "When there's no obvious right answer — how do you usually decide? Gut feeling? Research? Ask someone?"
+- "Have you ever built something and halfway through realized you should have done it differently? What happened?"
+- "What makes you give up on a tool or approach and try something else?"
+- "Is there something about how things are usually done that you think is stupid or overcomplicated?"
+
+### Section 6: Look & Feel
+
+**For everyone:**
+- "How important is it that it looks good — on a scale from 'who cares, it just needs to work' to 'design is everything'?"
+- "When you think of apps you love using — what's the vibe? Clean and minimal? Packed with features? Playful?"
+- "Phone first or computer first?"
+- "Any apps or websites that you think nailed the design?"
+
+### Section 7: Things You Don't Want
+
+**For beginners:**
+- "Is there anything where you'd say 'I definitely don't want that'?"
+- "Any features or behaviors in apps that annoy you? Things you'd never put in your own project?"
+- "Anything that Claude should absolutely not decide on its own — something where it should always ask you first?"
+
+**For advanced users:**
+- "Hard no-gos — patterns, tools, approaches?"
+- "Anything where you'd rather have ugly-but-working than clean-but-incomplete?"
+- "What should Claude never do without asking?"
+
+### Section 8: The Fun Ones
+
+- "If you could change one thing about how software is built today, what would it be?"
+- "Is there something that 'everyone knows is wrong' that you secretly think is fine?"
+- "What do people who are new to this understand better than the experts?"
 
 ## Generating PROFILE.md
 

package/skills/gsd/unify/SKILL.md

@@ -40,6 +40,7 @@ Read ALL of these:
 | `.gsd/S{nn}-T{nn}-PLAN.md` | Per-task plans (all tasks in slice) |
 | `.gsd/S{nn}-T{nn}-SUMMARY.md` | What actually happened (all tasks in slice) |
 | `.gsd/DECISIONS.md` | Existing decisions |
+| `.gsd/VISION.md` | User's original intentions (if it exists) |
 
 Use `Glob` to find all matching files for the current slice.
 
@@ -163,7 +164,33 @@ Roadmap needs update:
 
 If the roadmap needs an update, describe what should change but do NOT modify the roadmap file. That happens in the next planning phase.
 
-## Step 8: Quality Gate
+## Step 8: Vision Alignment Check
+
+If `.gsd/VISION.md` exists, compare what was built in this slice against the user's original intentions:
+
+For each vision detail that relates to this slice:
+
+```
+Vision Alignment:
+
+| Vision Detail | What User Wanted | What Was Built | Alignment |
+|--------------|-----------------|----------------|-----------|
+| {detail}     | {user's words}  | {what we did}  | ✓ Aligned / ⚠ Adjusted / ✗ Deviated |
+
+Adjustments:
+- {detail}: Vision said "{user's words}". Implemented as {what we did}
+  because {technical reason}. Result is {how close to the original intent}.
+
+Deviations:
+- {detail}: Vision said "{user's words}". Could not implement because
+  {reason}. Alternative: {what we did instead}. Recommendation: {keep as-is / revisit later}.
+```
+
+This section is critical for auto-mode transparency. The user should be able to read this and immediately see where their vision was honored and where it wasn't — and why.
+
+If no VISION.md exists, skip this step.
+
+## Step 9: Quality Gate
 
 Check against `checklists/unify-complete.md`:
 

package/skills/gsd/vision/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: gsd-cc-vision
+description: >
+  Deep vision document that captures the user's detailed intentions for
+  every aspect of the project. Optional but powerful — serves as the
+  north star that all planning and execution aligns to. Use when user
+  says /gsd-cc-vision, wants to describe their project in detail before
+  building, or wants to ensure auto-mode stays true to their intentions.
+allowed-tools: Read, Write, Edit, Glob
+---
+
+# /gsd-cc-vision — Detailed Vision Document
+
+You help the user describe their project in as much detail as they want. This is NOT planning — no tasks, no slices, no technical decomposition. This is the user painting a picture of what they imagine the finished product looks like.
+
+The result is a VISION.md that serves as a permanent reference throughout the entire project. It is never modified by the system — only by the user. Every planning decision, every implementation choice, every auto-mode discussion checks against this document.
+
+## Language
+
+Check for "GSD-CC language: {lang}" in CLAUDE.md (loaded automatically). All output must use that language. If not found, default to English.
+
+## When to Run
+
+- After Ideation or Seed, before the first slice is planned
+- Anytime the user wants to describe their vision in more detail
+- The router should suggest this after Seed if rigor is `deep`
+
+## Mindset
+
+You are a listener and clarifier. Your job is to help the user get what's in their head onto paper. You don't judge, you don't say "that's not possible", you don't optimize. You capture their INTENTION.
+
+If they say "I want a big red button that sends the email" — you write that down. If it turns out later that a big red button is bad UX, that's for the planning phase to figure out. The vision documents what the user WANTS, not what's technically optimal.
+
+## The Conversation
+
+### Start
+
+```
+Let's capture your vision — how you imagine the finished product.
+
+Don't worry about what's realistic or technical. Tell me what you
+see when you close your eyes and imagine it working perfectly.
+
+We can go as deep as you want. Some people describe the big picture,
+others want to specify every button and animation. Both are fine.
+
+Where do you want to start?
+```
+
+### How to Guide
+
+Let the user lead. They might want to describe:
+
+- **The big picture:** "When someone opens the app, they see..."
+- **Specific features:** "There's a dashboard that shows..."
+- **User journeys:** "A new user signs up, then..."
+- **Look and feel:** "It should feel like Notion meets Spotify..."
+- **Specific interactions:** "When you click the send button, there's a satisfying animation and..."
+- **Edge cases they care about:** "If the internet drops, it should..."
+- **Things they explicitly DON'T want:** "No popups, ever."
+
+For each thing they describe, ask ONE follow-up to sharpen it:
+- "When you say 'fast' — what does that feel like? Instant? Under a second?"
+- "You said 'simple dashboard' — are we talking 3 numbers on a screen, or more like 10 cards with charts?"
+- "The notification — is that an email, a push notification, a sound, or just something on the screen?"
+
+**Don't ask about:**
+- Technical implementation ("should this be a REST endpoint?")
+- Architecture ("monolith or microservices?")
+- Tools ("React or Vue?")
+
+Those questions belong in Seed and Discuss. Vision is pure user intention.
+
+### Depth Control
+
+Let the user decide how deep to go. After covering a topic, ask:
+
+```
+Got it. Want to go deeper on this, or move on to the next area?
+```
+
+Some users will spend 5 minutes. Some will spend an hour. Both are valid. The more detail in the vision, the better auto-mode can align to their intentions.
+
+### Areas to Cover (if the user doesn't naturally go there)
+
+Gently guide toward these if they haven't been mentioned, but don't force:
+
+1. **First impression** — What does someone see when they first open it?
+2. **Core workflow** — The main thing people do, step by step
+3. **Key moments** — The 2-3 moments that make or break the experience
+4. **What it feels like** — Speed, personality, vibe
+5. **What it's NOT** — Things they want to avoid
+6. **Success scenario** — "I'll know it's working when..."
+
+## Generate VISION.md
+
+Write `.gsd/VISION.md`:
+
+```markdown
+# Project Vision
+
+> This document captures the user's detailed intentions.
+> It is NEVER modified by the system — only by the user.
+> All planning and execution aligns to this vision.
+> Deviations are documented and justified, never hidden.
+
+## Overview
+{The big picture in the user's own words — 1-2 paragraphs}
+
+## First Impression
+{What someone sees/feels when they first encounter the product}
+
+## Core Experience
+{The main workflow or journey, described from the user's perspective.
+Not technical — just what they imagine happening.}
+
+## Key Details
+{Specific things the user described in detail. Use their exact words.
+Each detail is a reference point for later planning.}
+
+### {Detail 1 — e.g. "The Dashboard"}
+{User's description}
+
+### {Detail 2 — e.g. "The Send Button"}
+{User's description}
+
+### {Detail 3}
+...
+
+## Look & Feel
+{How it should feel — speed, personality, vibe, references to other products}
+
+## Explicitly NOT Wanted
+{Things the user specifically said they don't want}
+
+## Success Criteria
+{How the user will know the project succeeded — in their own words}
+```
+
+### Rules for VISION.md
+
+- **Use the user's words.** Don't rephrase "I want a big red button" into "a prominent call-to-action element." Write "big red button."
+- **Don't add things.** Only write what the user said or confirmed. No "best practice" additions.
+- **Don't remove things.** Even if something seems contradictory or impractical, write it down. The planning phase handles contradictions.
+- **Mark specificity levels.** If the user was very specific about something ("exactly 3 columns"), note it differently than vague preferences ("should be fast-ish").
+
+## After Vision
+
+```
+✓ Vision captured.
+
+  .gsd/VISION.md — {n} sections, {n} specific details
+
+  This is your north star. Every planning decision will align to it.
+  When something can't be built exactly as you described, you'll see
+  exactly what changed and why.
+
+┌─────────────────────────────────────────────┐
+│  Start a fresh session to continue:         │
+│                                             │
+│  1. Exit this session                       │
+│  2. Run: claude                             │
+│  3. Type: /gsd-cc                           │
+│                                             │
+│  Next up: roadmap and detailed planning.    │
+└─────────────────────────────────────────────┘
+```
+
+**Do NOT continue in this session.** Each phase gets a fresh context window.
+
+## How Other Skills Use VISION.md
+
+This skill only CREATES the vision. Other skills READ it:
+
+- **Discuss (manual):** "The vision says X about this area. How do you want to handle it technically?"
+- **Discuss (auto/synthetic):** "VISION.md says the user wants a big red send button. Implementing as a prominent CTA button in the primary action position."
+- **Plan:** Task acceptance criteria should align with vision details where applicable
+- **Apply:** If implementation deviates from vision, note it in the task summary
+- **UNIFY:** Vision alignment check — "Vision said X, we built Y, because Z"
+
+The vision is never modified by these skills. Only the user can update it via `/gsd-cc-vision`.