gsd-cc 0.2.0 → 0.3.0

package/bin/install.js

@@ -26,6 +26,12 @@ ${cyan}   ██████╗ ███████╗██████╗
   Get Shit Done on Claude Code ${dim}v${pkg.version}${reset}
 `;
 
+// Sub-skills that get their own top-level directory under .claude/skills/
+const SUB_SKILLS = ['apply', 'auto', 'discuss', 'help', 'plan', 'seed', 'status', 'tutorial', 'unify', 'update'];
+
+// Shared directories that go into gsd-cc-shared/
+const SHARED_DIRS = ['checklists', 'prompts', 'templates'];
+
 // Parse args
 const args = process.argv.slice(2);
 const hasGlobal = args.includes('--global') || args.includes('-g');
@@ -39,8 +45,8 @@ if (hasHelp) {
   console.log(`  ${yellow}Usage:${reset} npx gsd-cc [options]
 
   ${yellow}Options:${reset}
-    ${cyan}-g, --global${reset}      Install globally to ~/.claude/skills/gsd/ ${dim}(default)${reset}
-    ${cyan}-l, --local${reset}       Install locally to ./.claude/skills/gsd/
+    ${cyan}-g, --global${reset}      Install globally to ~/.claude/skills/ ${dim}(default)${reset}
+    ${cyan}-l, --local${reset}       Install locally to ./.claude/skills/
     ${cyan}--uninstall${reset}       Remove GSD-CC skills
     ${cyan}-h, --help${reset}        Show this help message
 
@@ -88,13 +94,13 @@ function removeDir(dir) {
 }
 
 /**
- * Resolve target directory
+ * Resolve skills base directory
  */
-function getTargetDir(isGlobal) {
+function getSkillsBase(isGlobal) {
   if (isGlobal) {
-    return path.join(os.homedir(), '.claude', 'skills', 'gsd');
+    return path.join(os.homedir(), '.claude', 'skills');
   }
-  return path.join(process.cwd(), '.claude', 'skills', 'gsd');
+  return path.join(process.cwd(), '.claude', 'skills');
 }
 
 /**
@@ -102,10 +108,10 @@ function getTargetDir(isGlobal) {
  */
 function install(isGlobal) {
   const skillsSrc = path.join(__dirname, '..', 'skills', 'gsd');
-  const targetDir = getTargetDir(isGlobal);
+  const skillsBase = getSkillsBase(isGlobal);
   const label = isGlobal
-    ? targetDir.replace(os.homedir(), '~')
-    : targetDir.replace(process.cwd(), '.');
+    ? skillsBase.replace(os.homedir(), '~')
+    : skillsBase.replace(process.cwd(), '.');
 
   if (!fs.existsSync(skillsSrc)) {
     console.error(`  ${red}Error:${reset} Skills source not found at ${skillsSrc}`);
@@ -114,28 +120,40 @@ function install(isGlobal) {
 
   console.log(`  Installing to ${cyan}${label}${reset}\n`);
 
-  // Copy skills
-  copyDir(skillsSrc, targetDir);
+  let fileCount = 0;
 
-  // Make auto-loop.sh executable if it exists
-  const autoLoop = path.join(targetDir, 'auto', 'auto-loop.sh');
-  if (fs.existsSync(autoLoop)) {
-    fs.chmodSync(autoLoop, 0o755);
+  // 1. Install main router: gsd-cc/SKILL.md
+  const routerDest = path.join(skillsBase, 'gsd-cc');
+  fs.mkdirSync(routerDest, { recursive: true });
+  fs.copyFileSync(path.join(skillsSrc, 'SKILL.md'), path.join(routerDest, 'SKILL.md'));
+  fileCount++;
+
+  // 2. Install each sub-skill as its own top-level directory
+  for (const skill of SUB_SKILLS) {
+    const srcDir = path.join(skillsSrc, skill);
+    const destDir = path.join(skillsBase, `gsd-cc-${skill}`);
+
+    if (fs.existsSync(srcDir)) {
+      copyDir(srcDir, destDir);
+      fileCount += countFiles(destDir);
+    }
   }
 
-  // Count installed files
-  let fileCount = 0;
-  function countFiles(dir) {
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        countFiles(path.join(dir, entry.name));
-      } else {
-        fileCount++;
-      }
+  // 3. Install shared resources (templates, checklists, prompts)
+  const sharedDest = path.join(skillsBase, 'gsd-cc-shared');
+  for (const dir of SHARED_DIRS) {
+    const srcDir = path.join(skillsSrc, dir);
+    if (fs.existsSync(srcDir)) {
+      copyDir(srcDir, path.join(sharedDest, dir));
+      fileCount += countFiles(path.join(sharedDest, dir));
     }
   }
-  countFiles(targetDir);
+
+  // 4. Make auto-loop.sh executable
+  const autoLoop = path.join(skillsBase, 'gsd-cc-auto', 'auto-loop.sh');
+  if (fs.existsSync(autoLoop)) {
+    fs.chmodSync(autoLoop, 0o755);
+  }
 
   console.log(`  ${green}✓${reset} Installed ${fileCount} files to ${label}`);
   console.log(`
@@ -143,23 +161,48 @@ function install(isGlobal) {
 `);
 }
 
+/**
+ * Count files in a directory recursively
+ */
+function countFiles(dir) {
+  let count = 0;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      count += countFiles(path.join(dir, entry.name));
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
 /**
  * Uninstall skills
  */
 function uninstall() {
-  const globalDir = getTargetDir(true);
-  const localDir = getTargetDir(false);
+  const locations = [getSkillsBase(true), getSkillsBase(false)];
+  const allDirs = ['gsd-cc', ...SUB_SKILLS.map(s => `gsd-cc-${s}`), 'gsd-cc-shared', 'gsd'];
 
   let removed = false;
 
-  if (removeDir(globalDir)) {
-    console.log(`  ${green}✓${reset} Removed global install (${globalDir.replace(os.homedir(), '~')})`);
-    removed = true;
-  }
+  for (const base of locations) {
+    const label = base.includes(os.homedir())
+      ? base.replace(os.homedir(), '~')
+      : base.replace(process.cwd(), '.');
 
-  if (removeDir(localDir)) {
-    console.log(`  ${green}✓${reset} Removed local install (${localDir.replace(process.cwd(), '.')})`);
-    removed = true;
+    let removedFromLocation = false;
+    for (const dir of allDirs) {
+      const fullPath = path.join(base, dir);
+      if (removeDir(fullPath)) {
+        removedFromLocation = true;
+      }
+    }
+
+    if (removedFromLocation) {
+      console.log(`  ${green}✓${reset} Removed GSD-CC from ${label}`);
+      removed = true;
+    }
   }
 
   if (!removed) {
@@ -178,12 +221,12 @@ function promptLocation() {
     output: process.stdout,
   });
 
-  const globalPath = getTargetDir(true).replace(os.homedir(), '~');
+  const globalPath = getSkillsBase(true).replace(os.homedir(), '~');
 
   console.log(`  ${yellow}Where would you like to install?${reset}
 
   ${cyan}1${reset}) Global ${dim}(${globalPath})${reset} — available in all projects
-  ${cyan}2${reset}) Local  ${dim}(./.claude/skills/gsd/)${reset} — this project only
+  ${cyan}2${reset}) Local  ${dim}(./.claude/skills/)${reset} — this project only
 `);
 
   rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-cc",
-  "version": "0.2.0",
+  "version": "0.3.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

@@ -148,6 +148,8 @@ When routing to a sub-skill, tell the user what you're doing and then invoke the
 - Auto mode → `/gsd-cc-auto`
 - Status overview → `/gsd-cc-status`
 - Update skills → `/gsd-cc-update`
+- Help → `/gsd-cc-help`
+- Tutorial → `/gsd-cc-tutorial`
 
 Power users can invoke these directly. But the default path only needs `/gsd-cc` + Enter.
 

package/skills/gsd/auto/SKILL.md

@@ -84,10 +84,10 @@ Resolve the script location:
 
 ```bash
 # Check local first, then global
-if [[ -f ".claude/skills/gsd/auto/auto-loop.sh" ]]; then
-  SCRIPT=".claude/skills/gsd/auto/auto-loop.sh"
-elif [[ -f "$HOME/.claude/skills/gsd/auto/auto-loop.sh" ]]; then
-  SCRIPT="$HOME/.claude/skills/gsd/auto/auto-loop.sh"
+if [[ -f ".claude/skills/gsd-cc-auto/auto-loop.sh" ]]; then
+  SCRIPT=".claude/skills/gsd-cc-auto/auto-loop.sh"
+elif [[ -f "$HOME/.claude/skills/gsd-cc-auto/auto-loop.sh" ]]; then
+  SCRIPT="$HOME/.claude/skills/gsd-cc-auto/auto-loop.sh"
 fi
 ```
 

package/skills/gsd/help/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: gsd-cc-help
+description: >
+  Show available GSD-CC commands and how they work. Use when user says
+  /gsd-cc-help, /gsd-cc help, or asks what commands are available.
+allowed-tools: Read, Glob
+---
+
+# /gsd-cc-help — Command Reference
+
+## Language
+
+Read the `language` field from `.gsd/STATE.md` if it exists. All output must use that language. If no project exists or no language is set, default to English.
+
+## Output
+
+Show this reference, adapted to the configured language:
+
+```
+GSD-CC — Get Shit Done on Claude Code
+
+MAIN COMMAND
+  /gsd-cc                 Reads project state, suggests the next action.
+                          This is the only command you need.
+
+PHASE COMMANDS (power users)
+  /gsd-cc-seed            Start a new project — guided ideation
+  /gsd-cc-discuss         Resolve ambiguities before planning
+  /gsd-cc-plan            Break a slice into tasks with acceptance criteria
+  /gsd-cc-apply           Execute the next task (manual mode)
+  /gsd-cc-auto            Start autonomous execution via claude -p
+  /gsd-cc-unify           Mandatory plan-vs-actual reconciliation
+
+INFO & MANAGEMENT
+  /gsd-cc-status          Show project progress and AC tracking
+  /gsd-cc-update          Update GSD-CC to the latest version
+  /gsd-cc-help            This help screen
+  /gsd-cc-tutorial        Guided walkthrough with a sample project
+
+THE FLOW
+  1. /gsd-cc  →  Seed (what are you building?)
+  2. /gsd-cc  →  Roadmap (milestones and slices)
+  3. /gsd-cc  →  Plan (tasks with ACs and boundaries)
+  4. /gsd-cc  →  Execute (manual or auto)
+  5. /gsd-cc  →  UNIFY (mandatory quality check)
+  6. /gsd-cc  →  Next slice or milestone complete
+
+PROJECT FILES
+  .gsd/STATE.md           Current position and progress
+  .gsd/PLANNING.md        Project brief from ideation
+  .gsd/PROJECT.md         Elevator pitch (3-5 sentences)
+  .gsd/M001-ROADMAP.md    Milestones and slices
+  .gsd/S01-PLAN.md        Slice plan with architecture notes
+  .gsd/S01-T01-PLAN.md    Task plan with ACs and boundaries
+  .gsd/S01-T01-SUMMARY.md What actually happened
+  .gsd/S01-UNIFY.md       Plan vs. actual comparison
+  .gsd/DECISIONS.md       All decisions, append-only
+  .gsd/COSTS.jsonl        Token usage tracking (auto-mode)
+
+TIPS
+  • You only need /gsd-cc — it always knows what to do next
+  • Type "auto" when asked to run tasks autonomously
+  • Come back tomorrow — state survives between sessions
+  • UNIFY cannot be skipped — it's what keeps quality high
+```
+
+## After showing help
+
+If a `.gsd/` directory exists, add a one-line status: where the project currently is and what the suggested next step would be.

package/skills/gsd/plan/SKILL.md

@@ -201,8 +201,8 @@ One file per task, using the PLAN.xml template format:
 
 Before finishing, check against `checklists/planning-ready.md`:
 
-Read: `~/.claude/skills/gsd/checklists/planning-ready.md`
-(or `./.claude/skills/gsd/checklists/planning-ready.md`)
+Read: `~/.claude/skills/gsd-cc-shared/checklists/planning-ready.md`
+(or `./.claude/skills/gsd-cc-shared/checklists/planning-ready.md`)
 
 Verify ALL of these:
 

package/skills/gsd/seed/SKILL.md

@@ -65,14 +65,14 @@ If ambiguous, ask ONE clarifying question. Don't overthink it.
 
 Read the type-specific guide from:
 ```
-~/.claude/skills/gsd/seed/types/{type}/guide.md
+~/.claude/skills/gsd-cc-seed/types/{type}/guide.md
 ```
 
-If installed locally, check `./.claude/skills/gsd/seed/types/{type}/guide.md` instead.
+If installed locally, check `./.claude/skills/gsd-cc-seed/types/{type}/guide.md` instead.
 
 Also read the config:
 ```
-~/.claude/skills/gsd/seed/types/{type}/config.md
+~/.claude/skills/gsd-cc-seed/types/{type}/config.md
 ```
 
 The guide contains numbered sections with `Explore` and `Suggest` fields. The config sets the rigor level and section count.
@@ -108,8 +108,8 @@ Walk through the guide sections **one at a time**. For each section:
 
 After completing all sections, mentally check against `checklists/planning-ready.md`:
 
-Read: `~/.claude/skills/gsd/seed/../../checklists/planning-ready.md`
-(or `./.claude/skills/gsd/checklists/planning-ready.md`)
+Read: `~/.claude/skills/gsd-cc-shared/checklists/planning-ready.md`
+(or `./.claude/skills/gsd-cc-shared/checklists/planning-ready.md`)
 
 Verify:
 - Is there enough information to create a roadmap?
@@ -124,7 +124,7 @@ Create the `.gsd/` directory and write these files:
 
 #### `.gsd/PLANNING.md`
 
-Use the template from `templates/PLANNING.md`. Fill in all sections from the conversation:
+Use the template from `~/.claude/skills/gsd-cc-shared/templates/PLANNING.md` (or `./.claude/skills/gsd-cc-shared/templates/PLANNING.md`). Fill in all sections from the conversation:
 - Vision (from their initial description + refinements)
 - Users (from user/auth discussions)
 - Requirements v1, v2, Out of Scope (from exploration)

package/skills/gsd/tutorial/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: gsd-cc-tutorial
+description: >
+  Interactive walkthrough that builds a small sample project step by step.
+  Use when user says /gsd-cc-tutorial, /gsd-cc tutorial, or asks for a
+  guided introduction to GSD-CC.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# /gsd-cc-tutorial — Guided Walkthrough
+
+You guide the user through building a small project with GSD-CC, explaining each phase as it happens. This is a teaching mode — go slow, explain what's happening and why.
+
+## Language
+
+Ask the user which language to use before starting, just like `/gsd-cc-seed` does. Default to English.
+
+## Step 1: Welcome
+
+```
+Welcome to the GSD-CC Tutorial!
+
+I'll walk you through building a small project from start to finish.
+You'll see every phase in action: Seed → Plan → Execute → UNIFY.
+
+The whole tutorial takes about 10-15 minutes.
+
+We'll build a simple CLI tool together — small enough to finish quickly,
+big enough to see every GSD-CC feature.
+
+Ready? (yes to start)
+```
+
+Wait for confirmation.
+
+## Step 2: Explain the Philosophy
+
+Briefly explain (3-4 sentences max):
+- Claude Code is the agent, GSD-CC tells it what to do and when
+- Projects are broken into Milestones → Slices → Tasks
+- Each task fits one context window (fresh session, no context rot)
+- UNIFY checks that what was built matches what was planned
+
+Then say: "Let's start. I'll run `/gsd-cc-seed` now — this is the ideation phase."
+
+## Step 3: Run Seed (with commentary)
+
+Delegate to `/gsd-cc-seed` but with a twist: use this project idea:
+
+```
+A Node.js CLI tool called "mdcount" that counts words, sentences,
+and reading time in Markdown files. Takes a file path as argument,
+outputs a summary.
+```
+
+Let the user confirm or pick their own idea. If they pick their own, use that instead.
+
+Before each seed question, add a brief explanation:
+- "Now I'll ask about [topic]. This helps me understand [why]."
+
+After seed completes, explain what was created:
+- "Seed created 5 files in .gsd/. Let me show you the key one..."
+- Show a brief excerpt of PLANNING.md
+
+## Step 4: Run Roadmap (with commentary)
+
+Say: "Next, /gsd-cc would create a roadmap. For this small project, we'll have 1 milestone with 2-3 slices."
+
+Create the roadmap. After creation, explain:
+- What a milestone is (a major deliverable)
+- What a slice is (a coherent work unit, 2-7 tasks)
+- Why ordering matters (foundations first)
+
+## Step 5: Run Plan (with commentary)
+
+Say: "Now I'll plan the first slice in detail. Each task gets acceptance criteria (Given/When/Then) and boundaries (what NOT to touch)."
+
+Delegate to `/gsd-cc-plan`. After planning, show:
+- One task plan as an example
+- Highlight the acceptance criteria format
+- Highlight the boundaries section
+- "These boundaries prevent Claude from going on tangents — a common problem in AI coding."
+
+## Step 6: Execute One Task (manual)
+
+Say: "Let's execute the first task manually so you can see what happens."
+
+Delegate to `/gsd-cc-apply` for T01 only. After execution:
+- Show the SUMMARY.md that was created
+- Explain how it compares to the plan
+- "In auto-mode, this happens for every task without you doing anything."
+
+## Step 7: Explain Auto-Mode
+
+Don't actually run auto-mode (that would take too long for a tutorial). Instead explain:
+- "For the remaining tasks, you'd type `/gsd-cc` and choose 'auto'"
+- "Auto-mode runs each task in a fresh `claude -p` session"
+- "It uses your Max Plan — no API costs"
+- "When all tasks in a slice are done, UNIFY runs automatically"
+
+## Step 8: Explain UNIFY
+
+Explain what UNIFY does:
+- Compares what was planned vs. what was built
+- Documents deviations and decisions
+- Cannot be skipped — the router blocks until it's done
+- "This is what prevents 'it sort of works but doesn't match the design'"
+
+## Step 9: Wrap Up
+
+```
+That's GSD-CC!
+
+What you learned:
+  ✓ Seed     — turns your idea into a structured plan
+  ✓ Roadmap  — breaks it into milestones and slices
+  ✓ Plan     — creates tasks with acceptance criteria + boundaries
+  ✓ Apply    — executes tasks (manual or auto)
+  ✓ UNIFY    — mandatory quality check after each slice
+
+Next steps:
+  1. Delete this tutorial project: rm -rf .gsd/
+  2. Start your real project: /gsd-cc
+  3. Or explore: /gsd-cc-help for all commands
+
+Happy building!
+```
+
+## Rules
+
+- **Go slow.** This is teaching, not production. Pause between phases.
+- **Explain the WHY**, not just the what. Users should understand the design decisions.
+- **Keep the project small.** 1 milestone, 2-3 slices, 2-3 tasks per slice max.
+- **Only execute 1 task.** The tutorial should take 10-15 minutes, not an hour.
+- **Be encouraging.** The user is learning something new.

package/skills/gsd/unify/SKILL.md

@@ -167,14 +167,14 @@ If the roadmap needs an update, describe what should change but do NOT modify th
 
 Check against `checklists/unify-complete.md`:
 
-Read: `~/.claude/skills/gsd/checklists/unify-complete.md`
-(or `./.claude/skills/gsd/checklists/unify-complete.md`)
+Read: `~/.claude/skills/gsd-cc-shared/checklists/unify-complete.md`
+(or `./.claude/skills/gsd-cc-shared/checklists/unify-complete.md`)
 
 Verify ALL items pass. If any fails, fix the UNIFY document before proceeding.
 
 ## Step 9: Write UNIFY.md
 
-Write `.gsd/S{nn}-UNIFY.md` using the template from `templates/UNIFY.md`. Include all sections from Steps 2-7.
+Write `.gsd/S{nn}-UNIFY.md` using the template from `~/.claude/skills/gsd-cc-shared/templates/UNIFY.md` (or `./.claude/skills/gsd-cc-shared/templates/UNIFY.md`). Include all sections from Steps 2-7.
 
 Set frontmatter:
 ```yaml

package/skills/gsd/update/SKILL.md

@@ -15,8 +15,8 @@ You update GSD-CC to the latest version by running the installer.
 Check where GSD-CC is installed:
 
 ```
-1. Check ~/.claude/skills/gsd/SKILL.md (global)
-2. Check ./.claude/skills/gsd/SKILL.md (local)
+1. Check ~/.claude/skills/gsd-cc/SKILL.md (global)
+2. Check ./.claude/skills/gsd-cc/SKILL.md (local)
 ```
 
 Use `Glob` to find which exists. If both exist, update both.