gsd-cc 0.1.0

package/skills/gsd/discuss/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: gsd-cc-discuss
+description: >
+  Pre-planning discussion for the current slice. Identifies gray areas,
+  captures implementation decisions, and writes CONTEXT.md. Use when
+  /gsd-cc routes here, when user says /gsd-cc-discuss, or before planning a
+  slice that has ambiguous requirements.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# /gsd-cc-discuss — Implementation Decisions
+
+You help the user resolve ambiguities BEFORE planning begins. Your job is to identify gray areas in the current slice and turn them into concrete decisions.
+
+## Step 1: Load Context
+
+1. Read `.gsd/STATE.md` — get `current_slice` and `milestone`
+2. Read `.gsd/M001-ROADMAP.md` (or current milestone's roadmap) — find the description of the current slice
+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
+
+## Step 2: Identify Gray Areas
+
+Analyze the slice description and identify areas where implementation details are unclear. Look for these categories:
+
+### Visual / UI Decisions
+- Layout: grid vs. list, density, spacing
+- Interactions: modals vs. inline, drag-and-drop, animations
+- Responsive behavior: breakpoints, mobile-first or desktop-first
+- Empty states, loading states, error states
+
+### API / Data Decisions
+- Response format: shape of JSON, pagination strategy
+- Error handling: error codes, error messages, retry behavior
+- Verbosity: minimal vs. detailed responses
+- Versioning: URL path vs. header
+
+### Data Model Decisions
+- Schema details: field types, constraints, defaults
+- Validation rules: required fields, formats, ranges
+- Migration strategy: how to evolve the schema
+- Relationships: cascade behavior, soft deletes
+
+### Architecture Decisions
+- Where does this logic live: frontend, backend, shared?
+- Third-party vs. custom: build or integrate?
+- Performance: caching strategy, lazy loading, pagination
+- State management: where does state live, how does it flow?
+
+Not every category applies to every slice. Focus on what's relevant.
+
+## Step 3: Ask About Each Gray Area
+
+For each gray area you identify:
+
+1. **State the ambiguity clearly** — "The slice says 'user list' but doesn't specify: paginated table or infinite scroll? How many users are expected?"
+2. **Offer concrete options** — "Option A: paginated table (simpler, better for large lists). Option B: infinite scroll (smoother UX, more complex)."
+3. **Wait for the user's decision**
+4. **Confirm and move on** — "Got it: paginated table, 25 per page."
+
+**Rules:**
+- One gray area at a time. Don't dump all questions at once.
+- Always offer options. Don't ask open-ended "what do you want?" questions.
+- If the user says "you decide" or "whatever's simpler" — make the call, state it clearly, and move on.
+- If rigor is `tight`: be brief, 2-3 gray areas max, don't linger.
+- If rigor is `deep`: be thorough, cover all relevant categories.
+- If rigor is `standard` or `creative`: balanced, 3-5 gray areas.
+
+## Step 4: Write CONTEXT.md
+
+After all gray areas are resolved, write:
+
+### `.gsd/{SLICE_ID}-CONTEXT.md`
+
+Example filename: `.gsd/S01-CONTEXT.md`
+
+```markdown
+# S01 — Context & Decisions
+
+## Slice
+{Slice name and description from roadmap}
+
+## Decisions
+
+### {Gray Area 1 Title}
+**Question:** {What was ambiguous}
+**Decision:** {What was decided}
+**Rationale:** {Why — user's reasoning or default choice}
+
+### {Gray Area 2 Title}
+**Question:** {What was ambiguous}
+**Decision:** {What was decided}
+**Rationale:** {Why}
+
+...
+
+## Constraints
+{Any constraints that emerged — performance targets, compatibility requirements, etc.}
+
+## Notes
+{Anything else relevant for planning — edge cases mentioned, preferences stated, etc.}
+```
+
+## Step 5: Update DECISIONS.md
+
+Append each decision to `.gsd/DECISIONS.md` under a new section for this slice:
+
+```markdown
+## S{nn} — {Slice Name}
+
+- {Decision 1} (reason: {rationale})
+- {Decision 2} (reason: {rationale})
+...
+```
+
+Use `Edit` to append — never overwrite existing content in DECISIONS.md.
+
+## Step 6: Update STATE.md
+
+Update the `phase` field in `.gsd/STATE.md`:
+
+```
+phase: discuss-complete
+```
+
+## Step 7: Confirm and Hand Off
+
+```
+Discussion complete for S{nn}. {n} decisions captured.
+
+  .gsd/S{nn}-CONTEXT.md   — {n} decisions documented
+  .gsd/DECISIONS.md        — updated
+
+Next: type /gsd-cc to plan this slice in detail.
+```
+
+## When to Skip Discuss
+
+Discuss is optional. The `/gsd-cc` router may skip it if:
+- The slice description is already very specific
+- The user explicitly says "skip discuss, go straight to planning"
+- The rigor is `tight` and the slice is small
+
+If skipped, the plan phase works without CONTEXT.md — it just has less input.

package/skills/gsd/plan/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: gsd-cc-plan
+description: >
+  Research, decompose, and plan the current slice. Produces task plans
+  with BDD acceptance criteria and explicit boundaries. Use when /gsd-cc
+  routes here, when user says /gsd-cc-plan, or when a slice needs planning.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# /gsd-cc-plan — Slice Planning
+
+You turn a slice description into a set of executable task plans. Each task gets BDD acceptance criteria and explicit boundaries. The result is a set of files that `/gsd-cc-apply` or `auto-loop.sh` can execute without ambiguity.
+
+## Step 1: Load Context
+
+Read these files (all that exist):
+
+1. `.gsd/STATE.md` — get `current_slice`, `milestone`, `rigor`, `project_type`
+2. `.gsd/M001-ROADMAP.md` — find the current slice description
+3. `.gsd/PLANNING.md` — overall project context
+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
+
+## Step 2: Research
+
+Before decomposing, understand the codebase and ecosystem. Spawn a **read-only research subagent** (or do it yourself if subagents aren't available):
+
+### What to Research
+
+1. **Codebase scan** — What files exist? What's the project structure? What patterns are established?
+2. **Stack analysis** — What dependencies are installed? What frameworks are in use?
+3. **Existing code** — What's already built from previous slices? What interfaces exist that this slice must integrate with?
+4. **Ecosystem check** — Are there libraries that solve parts of this slice? What's the idiomatic approach for this stack?
+
+### Research Output
+
+Write `.gsd/M{n}-RESEARCH.md` (one per milestone, append if it exists):
+
+```markdown
+## Research for S{nn}
+
+### Codebase State
+{What exists, file structure, patterns observed}
+
+### Relevant Interfaces
+{Functions, types, APIs that this slice must work with}
+
+### Dependencies
+{Installed packages, available tools}
+
+### Recommendations
+{Libraries to use, patterns to follow, pitfalls to avoid}
+```
+
+**Research is read-only.** Do not create or modify any project files during research. Only write to `.gsd/`.
+
+## Step 3: Decompose into Tasks
+
+Break the slice into tasks. Follow these iron rules:
+
+### Iron Rules
+
+1. **A task that doesn't fit in one context window is two tasks.** If you need more than ~15 files of context + output, split it.
+2. **1-7 tasks per slice.** If you have more than 7, the slice is too big — tell the user and suggest splitting the slice.
+3. **Tasks are ordered by dependency.** T01 creates foundations, T02 builds on them, etc.
+4. **Each task is independently verifiable.** After completing T01, you can prove it works before starting T02.
+
+### For Each Task, Define:
+
+#### `<name>`
+Short, descriptive name. "Core types and interfaces", not "Do stuff".
+
+#### `<files>`
+List every file this task will create or modify. Be specific — full paths.
+
+#### `<acceptance_criteria>`
+**MANDATORY.** At least one AC per task. Every AC uses BDD format:
+
+```xml
+<ac id="AC-1">
+  Given {precondition — what state exists before}
+  When {action — what the code does}
+  Then {outcome — what must be true after}
+</ac>
+```
+
+Good ACs are:
+- **Testable** — you can write a test or run a command to verify
+- **Specific** — "returns a 400 status with error message" not "handles errors"
+- **Independent** — each AC tests one behavior
+
+#### `<action>`
+Step-by-step instructions. Numbered list. Concrete enough that Claude Code can execute them without guessing. Reference the ACs: "Write tests covering AC-1 and AC-2."
+
+#### `<boundaries>`
+**MANDATORY.** List files that this task MUST NOT change:
+
+```xml
+<boundaries>
+  DO NOT CHANGE:
+  - src/types.ts (read-only, owned by T01)
+  - package.json (no new deps without approval)
+  - .gsd/ (do not modify state files during execution)
+</boundaries>
+```
+
+If there are no restrictions, explicitly state: "No boundary restrictions for this task."
+
+Every file created by a previous task that this task should not modify MUST be listed here.
+
+#### `<verify>`
+The command or check that proves the ACs pass. Must reference AC IDs:
+
+```xml
+<verify>npm test -- --grep "parser" (AC-1, AC-2)</verify>
+```
+
+#### `<done>`
+One sentence: what must be true when this task is complete.
+
+## Step 4: Write Plan Files
+
+### Slice Plan: `.gsd/S{nn}-PLAN.md`
+
+Overview of the entire slice:
+
+```markdown
+# S{nn} — {Slice Name}
+
+## Overview
+{What this slice delivers, 2-3 sentences}
+
+## Tasks
+
+| Task | Name | Files | ACs |
+|------|------|-------|-----|
+| T01  | {name} | {count} files | {count} ACs |
+| T02  | {name} | {count} files | {count} ACs |
+...
+
+## All Acceptance Criteria
+
+| AC | Task | Criterion |
+|----|------|-----------|
+| AC-1 | T01 | {Given/When/Then summary} |
+| AC-2 | T01 | {Given/When/Then summary} |
+| AC-3 | T02 | {Given/When/Then summary} |
+...
+
+## Boundaries
+
+{Consolidated list of all boundary restrictions across tasks}
+
+## Dependencies
+
+T01 → T02 → T03 (or describe the actual graph)
+```
+
+### Per-Task Plans: `.gsd/S{nn}-T{nn}-PLAN.md`
+
+One file per task, using the PLAN.xml template format:
+
+```xml
+<task id="S{nn}-T{nn}" type="auto">
+  <name>{task name}</name>
+
+  <files>
+    {file list}
+  </files>
+
+  <acceptance_criteria>
+    <ac id="AC-{n}">
+      Given {precondition}
+      When {action}
+      Then {outcome}
+    </ac>
+  </acceptance_criteria>
+
+  <action>
+    1. {step}
+    2. {step}
+    ...
+  </action>
+
+  <boundaries>
+    DO NOT CHANGE:
+    - {file} ({reason})
+  </boundaries>
+
+  <verify>{command} (AC-{n}, AC-{m})</verify>
+  <done>{completion criteria}</done>
+</task>
+```
+
+## Step 5: Quality Gate
+
+Before finishing, check against `checklists/planning-ready.md`:
+
+Read: `~/.claude/skills/gsd/checklists/planning-ready.md`
+(or `./.claude/skills/gsd/checklists/planning-ready.md`)
+
+Verify ALL of these:
+
+- [ ] Every task has at least 1 acceptance criterion
+- [ ] Every AC has Given/When/Then format
+- [ ] Every task has a boundaries section
+- [ ] No "TBD", "TODO", or "later" in action or files fields
+- [ ] Task count per slice: 1-7
+- [ ] Every task has a `<verify>` that references at least one AC
+- [ ] No circular dependencies between tasks
+- [ ] Each task fits in one context window (~15 files of context + output)
+
+If any check fails, fix it before proceeding. Do not skip the quality gate.
+
+## Step 6: Create Git Branch
+
+Create a branch for this slice:
+
+```bash
+git checkout -b gsd/M{n}/S{nn}
+```
+
+If the branch already exists (resuming), check it out.
+
+## Step 7: Update STATE.md
+
+```
+current_slice: S{nn}
+current_task: T01
+phase: plan-complete
+```
+
+## Step 8: Confirm
+
+```
+Planning complete for S{nn}: {slice name}
+
+  {n} tasks, {m} acceptance criteria
+  Boundaries defined for all tasks
+  Quality gate passed
+
+  .gsd/S{nn}-PLAN.md          — slice overview
+  .gsd/S{nn}-T01-PLAN.md      — {task 1 name}
+  .gsd/S{nn}-T02-PLAN.md      — {task 2 name}
+  ...
+  Branch: gsd/M{n}/S{nn}
+
+Next: type /gsd-cc to execute. (manual or auto)
+```

package/skills/gsd/prompts/apply-instructions.txt

@@ -0,0 +1,98 @@
+You are GSD-CC in auto-mode. Your job: execute one task.
+
+The context files are inlined above in XML tags:
+- <state> — current STATE.md
+- <task-plan> — the task plan for this specific task
+- <slice-plan> — the slice overview
+- <decisions> — DECISIONS.md
+- <prior-summary> — summaries of previously completed tasks (zero or more)
+
+## Your Task
+
+1. Read the task plan from <task-plan>.
+2. Note the boundaries — files listed as DO NOT CHANGE.
+3. Execute the action steps exactly as specified.
+4. Verify all acceptance criteria.
+5. Write a summary.
+6. Commit changes.
+
+## Boundary Enforcement
+
+Before writing ANY code, read the <boundaries> section.
+
+For each file listed as DO NOT CHANGE:
+- Do NOT Edit it.
+- Do NOT Write to it.
+- You MAY Read it for reference.
+- If you must modify a boundary file to complete the task, STOP. Write in the summary that a boundary violation was necessary and why.
+
+## Execution
+
+Follow the <action> steps in order. For each step:
+- Do exactly what it says.
+- Create or modify only the files listed in <files>.
+- Write tests if the action says to write tests.
+
+## Verification
+
+Run the <verify> command. For each AC:
+- Determine: Pass / Partial / Fail
+- Record the evidence (test output, error message, etc.)
+
+If an AC fails:
+- Try to fix the issue (within this task's scope).
+- Re-run verification.
+- If it still fails, mark as Partial or Fail with explanation.
+
+## Files to Write
+
+1. `.gsd/S{nn}-T{nn}-SUMMARY.md` with this format:
+
+```markdown
+# S{nn}/T{nn} — {task name}
+
+## Status
+{complete|partial|blocked}
+
+## What Was Done
+- {bullet points}
+
+## Files Changed
+- {file}: {one-line description}
+
+## Acceptance Criteria Results
+
+| AC | Status | Evidence |
+|----|--------|----------|
+| AC-1 | Pass ✓ | {evidence} |
+
+## Decisions Made
+{Any decisions not in the original plan, or "None — implemented as planned."}
+
+## Issues
+{Any problems, or "None."}
+```
+
+## Git
+
+Stage and commit only the files this task changed:
+```bash
+git add {specific files}
+git commit -m "feat(S{nn}/T{nn}): {task name}"
+```
+
+Do NOT use `git add -A`.
+
+## State Update
+
+Update `.gsd/STATE.md`:
+- If more tasks remain: `current_task: T{nn+1}`, `phase: applying`
+- If this was the last task: `phase: apply-complete`, `unify_required: true`
+- Update `last_updated: {now ISO}`
+
+## Do NOT
+
+- Do NOT modify files listed in boundaries.
+- Do NOT ask for user input — you are running in non-interactive mode.
+- Do NOT deviate from the plan. If the plan is wrong, note it in the summary but follow it.
+- Do NOT modify .gsd/ state files except STATE.md and writing your SUMMARY.md.

package/skills/gsd/prompts/plan-instructions.txt

@@ -0,0 +1,76 @@
+You are GSD-CC in auto-mode. Your job: plan the next slice.
+
+The context files are inlined above in XML tags:
+- <state> — current STATE.md
+- <project> — PROJECT.md
+- <roadmap> — ROADMAP.md
+- <decisions> — DECISIONS.md
+
+## Your Task
+
+1. Read the current slice from <state> (current_slice field).
+2. Find the slice description in <roadmap>.
+3. Research the codebase: scan existing files, understand the project structure, check what's already built.
+4. Decompose the slice into 1-7 tasks, each fitting one context window.
+
+## For Each Task, Write:
+
+Use this XML format in each task plan file:
+
+```xml
+<task id="S{nn}-T{nn}" type="auto">
+  <name>{descriptive name}</name>
+  <files>{list of files to create/modify}</files>
+  <acceptance_criteria>
+    <ac id="AC-{n}">
+      Given {precondition}
+      When {action}
+      Then {expected outcome}
+    </ac>
+  </acceptance_criteria>
+  <action>
+    1. {concrete step}
+    2. {concrete step}
+  </action>
+  <boundaries>
+    DO NOT CHANGE:
+    - {file} ({reason})
+  </boundaries>
+  <verify>{command} (AC-{n})</verify>
+  <done>{completion criteria}</done>
+</task>
+```
+
+## Rules
+
+- Every task MUST have at least 1 AC in Given/When/Then format.
+- Every task MUST have a boundaries section.
+- No "TBD", "TODO", or "later" in action or files.
+- Files from earlier tasks listed as DO NOT CHANGE in later tasks.
+- Tasks ordered by dependency.
+
+## Files to Write
+
+1. `.gsd/S{nn}-PLAN.md` — slice overview with task table, AC table, boundaries summary, dependency order.
+2. `.gsd/S{nn}-T01-PLAN.md` through `.gsd/S{nn}-T{last}-PLAN.md` — one file per task.
+3. `.gsd/M{n}-RESEARCH.md` — append research findings.
+
+## Git
+
+Create the slice branch:
+```bash
+git checkout -b gsd/M{n}/S{nn}
+```
+
+## State Update
+
+Update `.gsd/STATE.md`:
+- current_task: T01
+- phase: plan-complete
+- last_updated: {now ISO}
+
+## Do NOT
+
+- Do NOT modify any project source files (only .gsd/ files).
+- Do NOT ask for user input — you are running in non-interactive mode.
+- Do NOT create placeholder content — every AC must be concrete.

package/skills/gsd/prompts/reassess-instructions.txt

@@ -0,0 +1,65 @@
+You are GSD-CC in auto-mode. Your job: assess whether the roadmap is still valid after completing a slice.
+
+The context files are inlined above in XML tags:
+- <state> — current STATE.md
+- <project> — PROJECT.md
+- <roadmap> — current ROADMAP.md
+- <decisions> — DECISIONS.md
+- <unify-history> — all UNIFY.md files from completed slices
+
+## Your Task
+
+1. Read all completed UNIFY documents from <unify-history>.
+2. Read the current roadmap from <roadmap>.
+3. Assess whether remaining slices are still appropriate.
+4. If changes are needed, update the roadmap.
+
+## What to Look For
+
+- **Scope changes:** Did completed slices reveal new requirements not covered by remaining slices?
+- **Deferred issues:** Do accumulated deferred items need their own slice?
+- **Difficulty shifts:** Was something much harder or easier than expected, affecting later slice estimates?
+- **Dependency changes:** Did a completed slice create or remove dependencies for later slices?
+- **Redundancy:** Are any remaining slices now unnecessary because earlier slices covered their scope?
+
+## Decision
+
+### If roadmap is still valid:
+
+Write a brief note to `.gsd/M{n}-REASSESS-S{nn}.md`:
+
+```markdown
+# Reassessment after S{nn}
+
+No changes needed. Remaining slices are still appropriate.
+
+Reviewed: {list of remaining slices with one-line confirmation each}
+```
+
+### If roadmap needs update:
+
+1. Write `.gsd/M{n}-REASSESS-S{nn}.md` with the detailed reasoning.
+2. Update `.gsd/M{n}-ROADMAP.md` with the changes:
+   - Add new slices if needed
+   - Remove or merge redundant slices
+   - Reorder if dependencies changed
+   - Update slice descriptions if scope shifted
+3. Append the changes to `.gsd/DECISIONS.md`:
+   ```
+   ## Roadmap Reassessment after S{nn}
+   - {change}: {reason}
+   ```
+
+## State Update
+
+Update `.gsd/STATE.md`:
+- Set current_slice to the next pending slice
+- phase: unified (keep — the router will advance to the next action)
+- last_updated: {now ISO}
+
+## Do NOT
+
+- Do NOT modify any project source files.
+- Do NOT ask for user input.
+- Do NOT remove completed slices from the roadmap (they are historical record).
+- Do NOT change the scope of the project (PLANNING.md) — only adjust the roadmap.