gsd-cc 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# GSD-CC — Get Shit Done on Claude Code
+
+A project management system for AI-powered software development. Structure your ideas, break them into executable units, and let Claude Code do the work — guided or fully autonomous.
+
+## Why GSD-CC?
+
+Claude Code is the best coding agent available. But without structure, large projects degrade into chaos: context rot, lost decisions, no quality control.
+
+GSD-CC orchestrates Claude Code with native Skills (Markdown) — no API costs, no dependencies, no custom agent.
+
+| Feature | GSD-CC |
+|---------|--------|
+| Runtime | Claude Code (native) |
+| Cost model | Max Plan (flat rate) |
+| Dependencies | Zero (Markdown + Bash) |
+| Quality control | Mandatory UNIFY after every slice |
+| Boundary enforcement | Explicit DO NOT CHANGE rules per task |
+| Custom project types | Drop 3 files, done |
+
+## Install
+
+```bash
+npx gsd-cc            # Install globally (default)
+npx gsd-cc --local    # Install to current project only
+npx gsd-cc --uninstall
+```
+
+## Usage
+
+```bash
+claude          # Open Claude Code
+> /gsd-cc       # That's it. The router handles the rest.
+```
+
+GSD-CC reads your project state and suggests the next action. The full cycle:
+
+**SEED** (ideation) → **PLAN** (tasks with acceptance criteria) → **APPLY** (execute) → **UNIFY** (mandatory plan vs. actual)
+
+Auto-mode runs tasks autonomously via `claude -p` on your Max Plan.
+
+## Requirements
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
+- Claude Code **Max Plan** (recommended for auto-mode)
+- **Git** initialized in your project
+- **jq** installed (`brew install jq`) — required for auto-mode
+
+## Documentation
+
+Full documentation, architecture details, and custom type guide: [GitHub](https://github.com/0ui-labs/GSD-CC)
+
+## License
+
+[MIT](https://github.com/0ui-labs/GSD-CC/blob/main/LICENSE)

package/bin/install.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+// Colors
+const cyan = '\x1b[36m';
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+const red = '\x1b[31m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+const pkg = require('../package.json');
+
+const banner = `
+${cyan}   ██████╗ ███████╗██████╗        ██████╗ ██████╗
+  ██╔════╝ ██╔════╝██╔══██╗      ██╔════╝██╔════╝
+  ██║  ███╗███████╗██║  ██║█████╗██║     ██║
+  ██║   ██║╚════██║██║  ██║╚════╝██║     ██║
+  ╚██████╔╝███████║██████╔╝      ╚██████╗╚██████╗
+   ╚═════╝ ╚══════╝╚═════╝        ╚═════╝ ╚═════╝${reset}
+
+  Get Shit Done on Claude Code ${dim}v${pkg.version}${reset}
+`;
+
+// Parse args
+const args = process.argv.slice(2);
+const hasGlobal = args.includes('--global') || args.includes('-g');
+const hasLocal = args.includes('--local') || args.includes('-l');
+const hasUninstall = args.includes('--uninstall');
+const hasHelp = args.includes('--help') || args.includes('-h');
+
+console.log(banner);
+
+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}--uninstall${reset}       Remove GSD-CC skills
+    ${cyan}-h, --help${reset}        Show this help message
+
+  ${yellow}Examples:${reset}
+    ${dim}# Install globally (default)${reset}
+    npx gsd-cc
+
+    ${dim}# Install to current project only${reset}
+    npx gsd-cc --local
+
+    ${dim}# Remove GSD-CC${reset}
+    npx gsd-cc --uninstall
+`);
+  process.exit(0);
+}
+
+/**
+ * Recursively copy a directory
+ */
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Remove a directory recursively
+ */
+function removeDir(dir) {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Resolve target directory
+ */
+function getTargetDir(isGlobal) {
+  if (isGlobal) {
+    return path.join(os.homedir(), '.claude', 'skills', 'gsd');
+  }
+  return path.join(process.cwd(), '.claude', 'skills', 'gsd');
+}
+
+/**
+ * Install skills to target directory
+ */
+function install(isGlobal) {
+  const skillsSrc = path.join(__dirname, '..', 'skills', 'gsd');
+  const targetDir = getTargetDir(isGlobal);
+  const label = isGlobal
+    ? targetDir.replace(os.homedir(), '~')
+    : targetDir.replace(process.cwd(), '.');
+
+  if (!fs.existsSync(skillsSrc)) {
+    console.error(`  ${red}Error:${reset} Skills source not found at ${skillsSrc}`);
+    process.exit(1);
+  }
+
+  console.log(`  Installing to ${cyan}${label}${reset}\n`);
+
+  // Copy skills
+  copyDir(skillsSrc, targetDir);
+
+  // 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);
+  }
+
+  // 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++;
+      }
+    }
+  }
+  countFiles(targetDir);
+
+  console.log(`  ${green}✓${reset} Installed ${fileCount} files to ${label}`);
+  console.log(`
+  ${green}Done.${reset} Open Claude Code and type ${cyan}/gsd-cc${reset} to start.
+`);
+}
+
+/**
+ * Uninstall skills
+ */
+function uninstall() {
+  const globalDir = getTargetDir(true);
+  const localDir = getTargetDir(false);
+
+  let removed = false;
+
+  if (removeDir(globalDir)) {
+    console.log(`  ${green}✓${reset} Removed global install (${globalDir.replace(os.homedir(), '~')})`);
+    removed = true;
+  }
+
+  if (removeDir(localDir)) {
+    console.log(`  ${green}✓${reset} Removed local install (${localDir.replace(process.cwd(), '.')})`);
+    removed = true;
+  }
+
+  if (!removed) {
+    console.log(`  ${yellow}No GSD-CC installation found.${reset}`);
+  } else {
+    console.log(`\n  ${green}Done.${reset} GSD-CC has been removed.`);
+  }
+}
+
+/**
+ * Prompt for install location
+ */
+function promptLocation() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const globalPath = getTargetDir(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
+`);
+
+  rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
+    rl.close();
+    console.log();
+    const choice = answer.trim() || '1';
+    install(choice !== '2');
+  });
+}
+
+// Main
+if (hasUninstall) {
+  uninstall();
+} else if (hasGlobal && hasLocal) {
+  console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
+  process.exit(1);
+} else if (hasGlobal) {
+  install(true);
+} else if (hasLocal) {
+  install(false);
+} else {
+  promptLocation();
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "gsd-cc",
+  "version": "0.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",
+  "bin": {
+    "gsd-cc": "./bin/install.js"
+  },
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "ai-development",
+    "project-management",
+    "gsd",
+    "claude",
+    "anthropic",
+    "coding-agent",
+    "ai-agents",
+    "developer-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0ui-labs/GSD-CC"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/skills/gsd/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: gsd-cc
+description: >
+  GSD project management. Reads .gsd/STATE.md and suggests the one
+  next action. Use when user types /gsd-cc, mentions project planning,
+  milestones, slices, or tasks. Also triggers when no .gsd/ exists
+  and user wants to start a new project.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# /gsd-cc — Main Router
+
+You are the GSD-CC router. Your job is to read the current project state and suggest **exactly one** next action. Not a menu. Not "what do you want to do?". One clear recommendation.
+
+## Step 1: Detect State
+
+Check what exists on disk:
+
+```
+1. Does .gsd/ directory exist?
+2. Does .gsd/STATE.md exist? If yes, read it.
+3. Does .gsd/PLANNING.md exist?
+4. Does .gsd/M001-ROADMAP.md exist? (check for any M*-ROADMAP.md)
+5. Does .gsd/auto.lock exist? (crash/interrupt)
+6. Which S*-PLAN.md files exist?
+7. Which S*-UNIFY.md files exist?
+8. Which S*-T*-SUMMARY.md files exist?
+```
+
+Use `Glob` to check for file patterns. Use `Read` for STATE.md.
+
+## Step 2: Route to Action
+
+Follow this decision tree **top to bottom**. Take the FIRST match:
+
+### Crash Recovery
+```
+IF .gsd/auto.lock exists:
+  → Read the lock file.
+  → Check if the task's SUMMARY.md exists.
+    - If SUMMARY exists: "S{nn}/T{nn} finished but auto-mode was interrupted. Clean up and continue?"
+    - If no SUMMARY: "S{nn}/T{nn} was interrupted mid-execution. Resume or restart this task?"
+  → Wait for user confirmation, then delete auto.lock and proceed.
+```
+
+### No Project
+```
+IF .gsd/ does not exist:
+  → "No project found. What do you want to build?"
+  → Delegate to /gsd-cc-seed for ideation.
+```
+
+### Ideation Done, No Roadmap
+```
+IF .gsd/PLANNING.md exists AND no M*-ROADMAP.md exists:
+  → "Your plan is ready. Shall I create a roadmap with milestones and slices?"
+  → On confirmation: read PLANNING.md and PROJECT.md, create M001-ROADMAP.md
+    with slices, update STATE.md.
+```
+
+### Roadmap Exists, Next Slice Needs Planning
+```
+IF M*-ROADMAP.md exists AND there are slices without a S*-PLAN.md:
+  → Find the first unplanned slice.
+  → "Next up: S{nn} — {slice name}. Plan it in detail?"
+  → On confirmation: delegate to /gsd-cc-plan.
+```
+
+### Plan Ready, Not Executed
+```
+IF S*-PLAN.md exists for current slice AND no T*-SUMMARY.md files for it:
+  → "S{nn} is planned with {n} tasks. Execute manually or auto?"
+  → "manual" → delegate to /gsd-cc-apply
+  → "auto" → delegate to /gsd-cc-auto
+```
+
+### Execution In Progress
+```
+IF some T*-SUMMARY.md exist but not all tasks are done:
+  → Find next incomplete task.
+  → "S{nn}/T{nn} is next: {task name}. Continue?"
+  → On confirmation: delegate to /gsd-cc-apply for that task.
+```
+
+### UNIFY Required (MANDATORY — NO ESCAPE)
+```
+IF all tasks for current slice have SUMMARY.md files
+   AND no S*-UNIFY.md exists for that slice:
+  → "All tasks for S{nn} are done. UNIFY is required before moving on."
+  → Do NOT offer alternatives. Do NOT let the user skip.
+  → Delegate to /gsd-cc-unify immediately.
+```
+
+### UNIFY Done, Next Slice
+```
+IF S*-UNIFY.md exists for current slice:
+  → Check roadmap for next pending slice.
+  → If next slice exists: "S{nn} complete and unified. Continue with S{nn+1} — {name}?"
+  → If no next slice: go to Milestone Complete.
+```
+
+### Milestone Complete
+```
+IF all slices are unified:
+  → "Milestone M{n} is complete! All slices planned, executed, and unified."
+  → "Start a new milestone or wrap up?"
+```
+
+## Step 3: Respond
+
+Follow these UX rules strictly:
+
+1. **One action.** Always suggest exactly ONE thing. Never present a numbered menu.
+2. **Be direct.** State where we are and what's next. No preamble.
+3. **Quick confirmation.** If the user says "yes", "go", "ja", "weiter", "ok", "do it" — execute immediately. Don't ask again.
+4. **Show context.** Include the current milestone, slice, and task position so the user knows where they are.
+5. **Short format.** Use this structure:
+
+```
+{Current position — e.g. "M001 / S02 / T03"}
+
+{What just happened or where we are — one line}
+
+{Suggested next action — one line, phrased as a question or suggestion}
+```
+
+Example:
+```
+M001 / S01
+
+Planning complete. 3 tasks, 4 acceptance criteria.
+
+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:
+- Ideation → `/gsd-cc-seed`
+- Discussion → `/gsd-cc-discuss`
+- Planning → `/gsd-cc-plan`
+- Execution → `/gsd-cc-apply`
+- Reconciliation → `/gsd-cc-unify`
+- Auto mode → `/gsd-cc-auto`
+- Status overview → `/gsd-cc-status`
+
+Power users can invoke these directly. But the default path only needs `/gsd-cc` + Enter.
+
+## Roadmap Creation
+
+When the user confirms roadmap creation (after PLANNING.md exists):
+
+1. Read `.gsd/PLANNING.md` and `.gsd/PROJECT.md`
+2. Read `.gsd/type.json` for rigor level
+3. Break the project into **slices** — each slice is a coherent unit of work:
+   - A slice should be completable in 2-7 tasks
+   - Each task must fit in one context window
+   - Slices should be ordered by dependency (foundations first)
+4. Write `.gsd/M001-ROADMAP.md` with this format:
+
+```markdown
+# M001 — {Milestone Name}
+
+## Slices
+
+### S01 — {Slice Name}
+{One paragraph description of what this slice delivers}
+
+### S02 — {Slice Name}
+{One paragraph description}
+
+...
+```
+
+5. Update `.gsd/STATE.md`:
+   - Set `current_slice: S01`
+   - Set `phase: roadmap-complete`
+   - Update the Progress table with all slices as `pending`

package/skills/gsd/apply/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: gsd-cc-apply
+description: >
+  Execute the next task in the current slice. Loads task plan, enforces
+  boundaries, implements actions, verifies acceptance criteria, writes
+  summary, commits to git. Use when /gsd-cc routes here, when user says
+  /gsd-cc-apply, or when a planned slice is ready for execution.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# /gsd-cc-apply — Task Execution
+
+You execute one task at a time from the current slice plan. Each task has a plan with acceptance criteria and boundaries. Follow the plan precisely.
+
+## Step 1: Determine Current Task
+
+1. Read `.gsd/STATE.md` — get `current_slice` and `current_task`
+2. If `current_task` is `—` or empty, start with `T01`
+3. Construct the task plan path: `.gsd/S{nn}-T{nn}-PLAN.md`
+
+If the task plan file doesn't exist, stop and tell the user: "No plan found for S{nn}/T{nn}. Run /gsd-cc-plan first."
+
+## Step 2: Load Context (Context Matrix)
+
+Load ONLY these files — nothing else:
+
+| File | Purpose |
+|------|---------|
+| `.gsd/S{nn}-T{nn}-PLAN.md` | The task plan (primary input) |
+| `.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) |
+
+**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.
+
+## Step 3: Read and Announce the Plan
+
+Parse the task plan XML. Display to the user:
+
+```
+S{nn} / T{nn} — {task name}
+
+Files: {file list}
+ACs:   {count} acceptance criteria
+```
+
+Then read the boundaries aloud:
+
+```
+Boundaries:
+  DO NOT CHANGE: {file list with reasons}
+```
+
+This makes boundaries visible to you and to the user before any code is written.
+
+## Step 4: Enforce Boundaries
+
+Before writing any code, internalize the boundary rules:
+
+**For each file listed in `<boundaries>` as DO NOT CHANGE:**
+- Do NOT open it in Edit
+- Do NOT write to it
+- You MAY Read it for reference
+- If you find yourself needing to change a boundary file, STOP and tell the user: "T{nn} needs to modify {file} which is in the boundaries. This is a plan issue — should I adjust?"
+
+This is non-negotiable. Boundary violations are tracked in UNIFY.
+
+## Step 5: Execute Actions
+
+Follow the `<action>` steps from the task plan. For each step:
+
+1. **Do exactly what it says.** Don't reinterpret or "improve" the plan.
+2. **Create or modify files** as specified in `<files>`.
+3. **Write tests** if the action says to write tests.
+4. **Reference ACs** — make sure your implementation satisfies the acceptance criteria.
+
+If you encounter an issue during execution:
+- **Minor issue** (typo in plan, obvious small fix): fix it, note it in the summary.
+- **Major issue** (plan is wrong, dependency missing, approach doesn't work): STOP. Tell the user. Don't improvise a different approach.
+
+## Step 6: Verify Acceptance Criteria
+
+Run the `<verify>` command from the task plan. For each AC:
+
+```
+AC-1: {Given/When/Then summary}
+      → Pass ✓ | Partial ⚠ | Fail ✗
+      Evidence: {test output, manual verification, etc.}
+```
+
+**All ACs must pass before proceeding.** If an AC fails:
+1. Try to fix the issue (within the scope of this task)
+2. Re-run verification
+3. If it still fails after a reasonable attempt, mark it as Partial or Fail and note why in the summary
+
+## Step 7: Write Task Summary
+
+Create `.gsd/S{nn}-T{nn}-SUMMARY.md`:
+
+```markdown
+# S{nn}/T{nn} — {task name}
+
+## Status
+{complete | partial | blocked}
+
+## What Was Done
+{Brief description of what was implemented, 3-5 bullet points}
+
+## Files Changed
+{List of files created or modified, with one-line description each}
+
+## Acceptance Criteria Results
+
+| AC | Status | Evidence |
+|----|--------|----------|
+| AC-1 | Pass ✓ | {evidence} |
+| AC-2 | Pass ✓ | {evidence} |
+
+## Decisions Made
+{Any implementation decisions not in the original plan, with rationale.
+"None — implemented as planned." if nothing deviated.}
+
+## Issues
+{Any problems encountered. "None." if clean execution.}
+```
+
+## Step 8: Git Commit
+
+Stage and commit the changes from this task:
+
+```bash
+git add {specific files changed by this task}
+git commit -m "feat(S{nn}/T{nn}): {task name}"
+```
+
+**Commit only the files this task changed.** Do not `git add -A` — that could include unrelated changes.
+
+## Step 9: Update STATE.md
+
+Determine what comes next:
+
+### If there are more tasks in this slice:
+```
+current_task: T{nn+1}
+phase: applying
+```
+
+### If this was the LAST task in the slice:
+```
+current_task: T{nn}
+phase: apply-complete
+unify_required: true
+```
+
+Setting `phase: apply-complete` triggers the UNIFY requirement. The `/gsd-cc` router will not allow any other action until UNIFY is done.
+
+Update the Progress table in STATE.md with the AC results.
+
+## Step 10: Report and Continue
+
+```
+S{nn}/T{nn} complete.
+
+  AC-1: Pass ✓
+  AC-2: Pass ✓
+  Committed: feat(S{nn}/T{nn}): {task name}
+
+{If more tasks: "Next: T{nn+1} — {name}. Continue?"}
+{If last task: "All tasks done. UNIFY is required next. Type /gsd-cc to proceed."}
+```
+
+If the user says "yes", "go", "weiter" — immediately start the next task (go back to Step 1 with the next task).
+
+## Multi-Task Flow
+
+In manual mode, the user stays in the session. After each task:
+- Report results
+- Ask if they want to continue
+- If yes, seamlessly start the next task
+- The user can interrupt at any time between tasks
+
+This is different from auto mode (`/gsd-cc-auto`), where each task gets its own fresh `claude -p` session.