gsd-cc 0.9.1 → 1.1.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', 'ingest', '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.1",
+  "version": "1.1.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,8 @@ 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:
+- Import concept → `/gsd-cc-ingest`
+- 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/ingest/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: gsd-cc-ingest
+description: >
+  Import an existing concept document, spec, or brief into GSD-CC.
+  Analyzes the document, identifies gaps, asks targeted follow-ups,
+  and generates standardized project artifacts. Use when user says
+  /gsd-cc-ingest, pastes a concept, or uploads a document.
+allowed-tools: Read, Write, Edit, Glob, Bash
+---
+
+# /gsd-cc-ingest — Import External Concept
+
+You take an existing document — any format, any quality — and turn it into clean GSD-CC project artifacts. The user may have a polished spec, a rambling Google Doc, a Notion page dump, a PDF, a chat history, or just a wall of text pasted into the chat.
+
+Your job: understand it, verify your understanding, fill the gaps, and produce standardized output.
+
+## Language
+
+Check for "GSD-CC language: {lang}" in CLAUDE.md (loaded automatically). All output must use that language. If not found, default to English.
+
+## Step 1: Receive the Input
+
+The input can come in many forms:
+
+- **Pasted text** — the user copies their concept into the chat
+- **File path** — "here's my concept: /path/to/concept.md"
+- **Multiple files** — "look at these files: /docs/spec.md, /docs/wireframes.md"
+- **URL content** — the user might paste content from a web page
+
+Read whatever they provide. If it's a file path, use `Read`. If it's multiple files, read all of them.
+
+Say:
+```
+Got it. Let me read through this carefully.
+```
+
+## Step 2: Analyze and Summarize
+
+Read the entire document. Then present a structured summary back to the user:
+
+```
+Here's what I understood from your document:
+
+PROJECT: {one sentence — what is this?}
+
+WHAT'S CLEAR:
+  ✓ {Area 1} — {brief summary of what's defined}
+  ✓ {Area 2} — {brief summary}
+  ✓ {Area 3} — {brief summary}
+  ...
+
+WHAT'S VAGUE OR MISSING:
+  ? {Area 1} — {what's unclear or not mentioned}
+  ? {Area 2} — {what's unclear}
+  ...
+
+CONTRADICTIONS (if any):
+  ⚠ {Description of contradiction}
+  ...
+
+Did I get this right? Anything I misunderstood?
+```
+
+**This confirmation step is critical.** The user must verify that you understood their concept correctly before you generate any artifacts. Misunderstanding a concept and generating wrong artifacts is worse than asking.
+
+Wait for confirmation before proceeding.
+
+## Step 3: Fill the Gaps
+
+For each vague or missing area, ask targeted questions. Don't ask about things the document already covers — that's annoying.
+
+Adapt your questions to the user's level (same as /gsd-cc-profile — read the room from how the document is written).
+
+**For a technical spec with missing areas:**
+- "Your spec covers the API endpoints but doesn't mention authentication. What's the plan — JWT, sessions, OAuth?"
+
+**For a non-technical brief with gaps:**
+- "You described what the dashboard shows, but not what happens when someone clicks a number. Should it open a detail view, filter something, or just be informational?"
+
+**For a vague concept:**
+- "You mention 'user management' — what does that mean to you? Just login/signup, or also roles, permissions, teams?"
+
+Group related questions. Don't fire 15 questions at once. 3-4 at a time, then wait.
+
+## Step 4: Assess Coverage
+
+After filling gaps, check which GSD-CC artifacts you have enough information for:
+
+| Artifact | Can generate? | Why / why not |
+|----------|--------------|---------------|
+| PLANNING.md | Yes/Partial/No | {explanation} |
+| VISION.md | Yes/Partial/No | {explanation} |
+| PROJECT.md | Yes/No | {explanation} |
+| type.json | Yes/No | {explanation} |
+
+Tell the user:
+```
+Based on your document and our conversation, I can generate:
+  ✓ PLANNING.md — full project brief
+  ✓ PROJECT.md — elevator pitch
+  ✓ type.json — {type} / {rigor}
+  ◐ VISION.md — partial (you described the core experience in detail
+                but not the look & feel — want to add that now or later?)
+
+Generate these now?
+```
+
+## Step 5: Generate Artifacts
+
+On confirmation, create the `.gsd/` directory and write:
+
+### `.gsd/PLANNING.md`
+Same format as Seed output. Map the document's content to the standard sections:
+- Vision (from the document's intro/summary)
+- Users (from any user descriptions, personas, or target audience sections)
+- Requirements v1, v2, Out of Scope (from feature lists, must-haves, nice-to-haves)
+- Tech Stack (from any technical decisions in the document, or leave for Seed to fill)
+- Architecture Decisions (from any technical choices mentioned)
+- Open Questions (from remaining gaps)
+
+**Source everything.** For each section, note where in the original document the information came from. This lets the user verify the mapping.
+
+### `.gsd/VISION.md` (if enough detail)
+Only generate this if the document contains detailed descriptions of how things should look, feel, or work from the user's perspective. If it's a dry technical spec, skip VISION.md — the user can create it later with `/gsd-cc-vision`.
+
+### `.gsd/PROJECT.md`
+3-5 sentence elevator pitch, distilled from the document.
+
+### `.gsd/type.json`
+Detect project type and rigor from the document content, same logic as Seed.
+
+### `.gsd/STATE.md`
+Initialize with phase: seed-complete (since we're replacing the Seed step).
+
+### `.gsd/DECISIONS.md`
+Log any decisions that were already made in the original document:
+```markdown
+# Decisions
+
+## From Original Concept
+- {Decision from document} (source: original concept, section X)
+- {Decision from document} (source: original concept, section Y)
+
+## From Ingest Conversation
+- {Decision from gap-filling conversation} (reason: {rationale})
+```
+
+### `.gsd/INGEST-SOURCE.md`
+Keep a reference to what was ingested:
+```markdown
+# Ingest Source
+
+Ingested on: {date}
+Source: {file path(s) or "pasted text"}
+Original length: ~{word count} words
+Gaps identified: {count}
+Gaps resolved: {count}
+Gaps remaining: {count — these are in PLANNING.md Open Questions}
+```
+
+## Step 6: What's Still Missing?
+
+After generating artifacts, honestly assess what wasn't in the document and wasn't covered in the conversation:
+
+```
+✓ Artifacts generated.
+
+Still open — you might want to address these later:
+  • {Open question 1} — consider /gsd-cc-discuss during planning
+  • {Open question 2} — could be covered in /gsd-cc-vision
+  ...
+
+These are also listed in PLANNING.md under "Open Questions".
+```
+
+## Step 7: Hand Off
+
+```
+✓ Ingest complete.
+
+  .gsd/PLANNING.md       — project brief (from your document)
+  .gsd/PROJECT.md        — elevator pitch
+  .gsd/type.json         — {type} / {rigor}
+  .gsd/STATE.md          — initialized
+  .gsd/DECISIONS.md      — {n} decisions from your document
+  .gsd/INGEST-SOURCE.md  — reference to source
+  {.gsd/VISION.md        — if generated}
+
+┌─────────────────────────────────────────────┐
+│  Start a fresh session to continue:         │
+│                                             │
+│  1. Exit this session                       │
+│  2. Run: claude                             │
+│  3. Type: /gsd-cc                           │
+│                                             │
+│  Next: roadmap creation.                    │
+│  Optional: /gsd-cc-vision for more detail   │
+└─────────────────────────────────────────────┘
+```
+
+**Do NOT continue in this session.** The ingested document may have consumed significant context.
+
+## Rules
+
+- **Don't assume.** If the document says "user management" without detail, ask. Don't invent features.
+- **Respect the document.** The user spent time writing it. Don't dismiss parts of it. If something seems wrong, ask — don't silently fix it.
+- **Preserve specificity.** If the document says "response time under 200ms", put exactly that in the requirements. Don't generalize to "should be fast."
+- **Flag contradictions, don't resolve them.** "Your document says X in section 2 but Y in section 5. Which one is correct?" Don't pick one silently.
+- **Don't over-generate.** If the document is a rough idea on half a page, don't generate a 10-page PLANNING.md full of assumptions. Generate what you have, mark the rest as Open Questions.

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/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`.