gsd-cc 0.1.0

package/skills/gsd/seed/types/client/loadout.md

@@ -0,0 +1,31 @@
+# Client — Recommended Tools
+
+## Frameworks
+- **Next.js** / **Astro** — static + dynamic pages
+- **Hugo** / **11ty** — pure static site generators
+- **WordPress** — if client needs self-service CMS
+
+## Styling
+- **Tailwind CSS** — utility-first, rapid prototyping
+- **shadcn/ui** — pre-built components
+- **Framer Motion** — animations
+
+## CMS (if needed)
+- **Sanity** — headless, developer-friendly
+- **Contentful** — established headless CMS
+- **Tina** — Git-based, visual editing
+
+## Hosting
+- **Vercel** — zero-config, free tier
+- **Netlify** — alternative with form handling
+- **Cloudflare Pages** — edge deployment
+
+## Analytics & SEO
+- **Google Analytics** / **Plausible** — traffic tracking
+- **Google Search Console** — SEO monitoring
+- **next-sitemap** — automated sitemap generation
+
+## Conversion
+- **Calendly** — booking embeds
+- **Formspree** / **Getform** — form backends
+- **Stripe** — payments (if needed)

package/skills/gsd/seed/types/utility/config.md

@@ -0,0 +1,27 @@
+# Utility — Configuration
+
+rigor: tight
+sections: 6
+demeanor: focused-efficient
+timeout_multiplier: 0.5
+max_turns_multiplier: 0.6
+
+## Required Sections (6)
+
+1. Problem Statement
+2. Scope Guard
+3. User & Distribution
+4. Dependencies
+5. Interface
+6. Done Criteria
+
+## Optional Sections
+
+None. Every section is required for utilities.
+
+## Philosophy
+
+Utilities do one thing well. The best utility fits in one file, has zero
+dependencies, and can be explained in one sentence. Actively resist scope
+creep. If the description needs more than one sentence, it might be an
+application. Complete ideation in a single focused session.

package/skills/gsd/seed/types/utility/guide.md

@@ -0,0 +1,49 @@
+# Utility — Conversation Guide
+
+## 1/6 — Problem Statement
+
+**Explore:** What does this tool do? One sentence. If it takes more than one sentence, it might not be a utility.
+
+**Suggest:** Push for brevity: "It takes X and produces Y." If the description is getting complex, ask: "Is this actually an application?" Utilities resist expansion.
+
+**Skip-Condition:** Never skip.
+
+## 2/6 — Scope Guard
+
+**Explore:** One file or multiple? One function or a system? What does this explicitly NOT do? Where's the boundary?
+
+**Suggest:** Actively resist expansion. If the user says "and it could also..." — stop them. "That sounds like a separate tool. Let's keep this one focused." The best utilities do one thing well.
+
+**Skip-Condition:** Never skip.
+
+## 3/6 — User & Distribution
+
+**Explore:** Who uses this — just you, your team, the community? How is it distributed — npm package, local script, MCP server?
+
+**Suggest:** Personal tools need less documentation. Shared tools need a README and clear interface. npm packages need proper packaging.
+
+**Skip-Condition:** Never skip.
+
+## 4/6 — Dependencies
+
+**Explore:** What does this depend on? External APIs, npm packages, system tools? Can you minimize dependencies?
+
+**Suggest:** Fewer deps = less maintenance. If a dependency is heavy, consider lighter alternatives. Zero-dep utilities are the gold standard.
+
+**Skip-Condition:** Never skip.
+
+## 5/6 — Interface
+
+**Explore:** How is it invoked? CLI args, stdin, function call, MCP tool? What's the input format? What's the output format?
+
+**Suggest:** Define the contract: "Input: X (format), Output: Y (format), Errors: Z." If you can't define the interface cleanly, the scope might be too broad.
+
+**Skip-Condition:** Never skip.
+
+## 6/6 — Done Criteria
+
+**Explore:** What are 3-5 test cases that prove this works? Can you define them now? If you can't, the scope might be too vague.
+
+**Suggest:** Write them as: "Given X, expect Y." If every test case is different, the tool might be doing too many things. 3 test cases is the sweet spot.
+
+**Skip-Condition:** Never skip.

package/skills/gsd/seed/types/utility/loadout.md

@@ -0,0 +1,20 @@
+# Utility — Recommended Tools
+
+## Runtime
+- **Node.js** — default for JS/TS utilities
+- **Bun** — fast alternative, built-in test runner
+- **Bash** — for simple system scripts
+
+## Libraries
+- **commander** / **yargs** — CLI argument parsing
+- **zod** — input validation
+- **chalk** — colored terminal output
+
+## Testing
+- **Vitest** / **Jest** — unit tests
+- **Bun test** — zero-config if using Bun
+
+## Distribution
+- **npm** — public packages
+- **npx** — zero-install execution
+- **Homebrew** — macOS CLI distribution

package/skills/gsd/seed/types/workflow/config.md

@@ -0,0 +1,28 @@
+# Workflow — Configuration
+
+rigor: standard
+sections: 8
+demeanor: systematic-pragmatic
+timeout_multiplier: 1.0
+max_turns_multiplier: 1.0
+
+## Required Sections (6)
+
+1. Trigger & Purpose
+2. Steps & Flow
+3. Tools & Permissions
+4. Error Handling
+5. State Management
+6. Testing Strategy
+
+## Optional Sections (2)
+
+7. Distribution
+8. Integration with Other Skills
+
+## Philosophy
+
+Workflows orchestrate Claude Code — commands, hooks, skills, MCP servers.
+They need clear triggers, predictable flow, and solid error handling.
+Focus on what fires when, what tools are needed, and what happens when
+things go wrong. Keep the scope per-workflow tight.

package/skills/gsd/seed/types/workflow/guide.md

@@ -0,0 +1,65 @@
+# Workflow — Conversation Guide
+
+## 1/8 — Trigger & Purpose
+
+**Explore:** What kicks this off? A slash command, a hook, a schedule, a user action? What's the end result — what does "done" look like?
+
+**Suggest:** Slash commands for user-initiated, hooks for automatic triggers (pre-commit, post-file-edit), MCP for tool integration. Pick one primary trigger.
+
+**Skip-Condition:** Never skip.
+
+## 2/8 — Steps & Flow
+
+**Explore:** Walk me through it step by step. What happens first, then what? Are there decision points where the flow branches? Is it linear or does it loop?
+
+**Suggest:** Draw it as: "Step 1 → Step 2 → if X then Step 3a, else Step 3b → Done." Keep it under 10 steps. If more, consider splitting into multiple workflows.
+
+**Skip-Condition:** Never skip.
+
+## 3/8 — Tools & Permissions
+
+**Explore:** What Claude Code tools does this need? Read, Write, Edit, Bash, Glob, Grep? Any MCP servers? What permissions are required — and what should be explicitly excluded?
+
+**Suggest:** Start with the minimum set. Read + Glob for analysis workflows. Read + Write + Edit for modification workflows. Bash only when shell access is truly needed.
+
+**Skip-Condition:** Never skip.
+
+## 4/8 — Error Handling
+
+**Explore:** What can go wrong? File not found, permission denied, unexpected format, API timeout? What should happen in each case — retry, abort, ask the user?
+
+**Suggest:** For each error: decide between fail-fast (abort + clear message) and graceful degradation (skip + warn). Most workflows should fail-fast on critical errors and degrade on optional steps.
+
+**Skip-Condition:** Never skip.
+
+## 5/8 — State Management
+
+**Explore:** Does this workflow need to remember anything between runs? Intermediate results, configuration, progress tracking? Where does state live — files, environment variables?
+
+**Suggest:** If stateless works, prefer it. If state is needed: a single JSON or markdown file in `.gsd/` or a project-specific directory. Avoid complex state machines unless truly needed.
+
+**Skip-Condition:** Skip if the workflow is purely stateless (single run, no memory).
+
+## 6/8 — Testing Strategy
+
+**Explore:** How do you verify this works? Can you test it in isolation? What's a minimal test case? What would a regression look like?
+
+**Suggest:** Create a test fixture (sample files/state), run the workflow, check the output. For hooks: test with a dry-run flag. For commands: test with known input.
+
+**Skip-Condition:** Never skip.
+
+## 7/8 — Distribution
+
+**Explore:** Is this just for you, or should others be able to install it? If shared: how? npm package, GitHub repo, copy-paste into `.claude/`?
+
+**Suggest:** Personal: drop in `~/.claude/commands/` or `~/.claude/skills/`. Shared: npm package with an installer (like GSD-CC itself). For teams: document in project README.
+
+**Skip-Condition:** Skip if explicitly personal-only.
+
+## 8/8 — Integration with Other Skills
+
+**Explore:** Does this work with other Claude Code skills or commands? Does it read or write files that other workflows depend on? Any coordination needed?
+
+**Suggest:** If it reads/writes shared state (like `.gsd/STATE.md`), document the contract. If it triggers other commands, define the interface clearly.
+
+**Skip-Condition:** Skip if fully standalone.

package/skills/gsd/seed/types/workflow/loadout.md

@@ -0,0 +1,21 @@
+# Workflow — Recommended Tools
+
+## Claude Code Features
+- **Skills** (SKILL.md) — for persistent, auto-triggered behaviors
+- **Commands** (commands/) — for slash-command invocations
+- **Hooks** (settings.json) — for event-driven automation
+- **MCP Servers** — for tool integration
+
+## Markdown Authoring
+- **YAML frontmatter** — skill metadata (name, description, allowed-tools)
+- **Structured sections** — clear step-by-step instructions
+
+## Shell
+- **Bash** — for auto-loop scripts and system integration
+- **jq** — JSON parsing in shell scripts
+- **curl** — API calls from scripts
+
+## Testing
+- **Manual test fixtures** — sample files + expected output
+- **Bash assertions** — `[[ -f expected.md ]]` style checks
+- **Dry-run flags** — non-destructive test modes

package/skills/gsd/status/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: gsd-cc-status
+description: >
+  Show project progress, AC status, token usage, and auto-mode state.
+  Use when user says /gsd-cc-status, /gsd-cc status, or asks about project
+  progress, costs, or current state.
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# /gsd-cc-status — Project Status
+
+You show a clear, concise overview of where the project stands. No actions — just information and one suggested next step.
+
+## Step 1: Read State
+
+1. Read `.gsd/STATE.md`
+2. Read `.gsd/type.json`
+3. Use `Glob` to find all:
+   - `S*-PLAN.md` files (planned slices)
+   - `S*-UNIFY.md` files (unified slices)
+   - `S*-T*-SUMMARY.md` files (completed tasks)
+4. Read `.gsd/COSTS.jsonl` if it exists
+5. Check if `.gsd/auto.lock` exists
+
+## Step 2: Build Milestone Overview
+
+For each slice in the roadmap:
+
+| Indicator | Meaning |
+|-----------|---------|
+| `[done]` | UNIFY.md exists |
+| `[T{nn}/T{total}]` | Some tasks have summaries, execution in progress |
+| `[planned]` | PLAN.md exists but no summaries yet |
+| `[pending]` | No PLAN.md yet |
+
+Display:
+
+```
+M001 — {milestone name}
+
+  S01 {slice name}        [done]     {x}/{y} AC  ✓ unified
+  S02 {slice name}        [done]     {x}/{y} AC  ✓ unified
+  S03 {slice name}        [T02/T04]  {x}/{y} AC  running
+  S04 {slice name}        [planned]
+  S05 {slice name}        [pending]
+```
+
+## Step 3: Current Position
+
+```
+Current: S{nn} / T{nn} — {task name}
+Phase:   {phase from STATE.md}
+Type:    {project type} / {rigor}
+```
+
+## Step 4: AC Summary
+
+If any slices have been executed, show aggregate AC stats:
+
+```
+Acceptance Criteria:
+  Total:   {n} defined
+  Passed:  {n} ✓
+  Partial: {n} ⚠
+  Failed:  {n} ✗
+```
+
+Read AC results from UNIFY.md files (for completed slices) and SUMMARY.md files (for in-progress slice).
+
+## Step 5: Token Usage (if available)
+
+If `.gsd/COSTS.jsonl` exists, parse it and show:
+
+```
+Token Usage:
+  Input:  {total}k tokens
+  Output: {total}k tokens
+  By phase: plan {n}% · apply {n}% · unify {n}%
+  By slice: S01 {n}% · S02 {n}% · S03 {n}%
+```
+
+Use `Bash` to parse COSTS.jsonl:
+
+```bash
+cat .gsd/COSTS.jsonl | python3 -c "
+import sys, json
+lines = [json.loads(l) for l in sys.stdin if l.strip()]
+inp = sum(l.get('usage',{}).get('input_tokens',0) for l in lines)
+out = sum(l.get('usage',{}).get('output_tokens',0) for l in lines)
+print(f'Input: {inp/1000:.0f}k tokens')
+print(f'Output: {out/1000:.0f}k tokens')
+"
+```
+
+If python3 is not available, skip the detailed breakdown and just show line count.
+
+If COSTS.jsonl doesn't exist: "Token usage: not tracked (manual mode)"
+
+## Step 6: Auto-Mode Status
+
+If `.gsd/auto.lock` exists:
+
+```
+Auto-mode: ACTIVE
+  Current: {unit from lock}
+  Phase:   {phase from lock}
+  Started: {timestamp from lock}
+  PID:     {pid from lock}
+```
+
+Check if the PID is still running:
+```bash
+kill -0 {pid} 2>/dev/null && echo "running" || echo "stale"
+```
+
+If stale: "Auto-mode: STALE (process not running, lock file remains)"
+
+If no lock file: "Auto-mode: inactive"
+
+## Step 7: Suggest Next Action
+
+Based on the current state, suggest ONE next action (same logic as `/gsd-cc` router, but presented as a suggestion, not a command):
+
+```
+Next: {suggested action}
+```
+
+## Output Format
+
+Combine all sections into a single, clean output:
+
+```
+GSD-CC Status
+─────────────
+
+M001 — {milestone name}
+
+  S01 {name}        [done]     4/4 AC  ✓ unified
+  S02 {name}        [T02/T04]  1/3 AC  running
+  S03 {name}        [pending]
+
+Current: S02 / T02 — {task name}
+Phase:   applying
+Type:    application / deep
+
+Acceptance Criteria: 5/7 passed, 1 partial, 1 pending
+
+Token Usage:
+  142k input / 38k output
+  By phase: plan 22% · apply 68% · unify 10%
+
+Auto-mode: inactive
+
+Next: Continue with S02/T02.
+```
+
+Keep it compact. No explanations, no walls of text. Just the facts.

package/skills/gsd/templates/PLAN.xml

@@ -0,0 +1,65 @@
+<!--
+  GSD-CC Task Plan Template
+
+  Usage: Copy this template for each task as .gsd/S{nn}-T{nn}-PLAN.md
+
+  Fields:
+  - id:   Slice + Task identifier (e.g. S01-T02)
+  - type: "manual" (user present) or "auto" (auto-loop dispatch)
+  - name: Short descriptive name for the task
+
+  Rules:
+  - Every task MUST have at least one <ac> in acceptance_criteria
+  - Every <ac> MUST use Given/When/Then format
+  - Every task MUST have a <boundaries> section (can state "none")
+  - <verify> MUST reference at least one AC by id
+  - No "TBD", "TODO", or "later" in <action> or <files>
+  - If a task doesn't fit in one context window, split it into two tasks
+-->
+
+<task id="S01-T01" type="auto">
+  <name>{{TASK_NAME}}</name>
+
+  <files>
+    <!-- Files this task will create or modify -->
+    {{FILE_1}}
+    {{FILE_2}}
+  </files>
+
+  <acceptance_criteria>
+    <ac id="AC-1">
+      Given {{PRECONDITION}}
+      When {{ACTION}}
+      Then {{EXPECTED_OUTCOME}}
+    </ac>
+    <ac id="AC-2">
+      Given {{PRECONDITION}}
+      When {{ACTION}}
+      Then {{EXPECTED_OUTCOME}}
+    </ac>
+  </acceptance_criteria>
+
+  <action>
+    <!-- Step-by-step instructions for what to build -->
+    1. {{STEP_1}}
+    2. {{STEP_2}}
+    3. Write tests covering AC-1 and AC-2
+  </action>
+
+  <boundaries>
+    <!-- Files that MUST NOT be changed by this task -->
+    DO NOT CHANGE:
+    - {{FILE_OWNED_BY_OTHER_TASK}} (read-only, owned by T{{nn}})
+    - {{LOCKED_FILE}} (no modifications without approval)
+  </boundaries>
+
+  <verify>
+    <!-- How to verify acceptance criteria are met -->
+    {{VERIFY_COMMAND}} (AC-1, AC-2)
+  </verify>
+
+  <done>
+    <!-- Definition of done — what must be true when this task is complete -->
+    {{COMPLETION_CRITERIA}}
+  </done>
+</task>

package/skills/gsd/templates/PLANNING.md

@@ -0,0 +1,63 @@
+---
+project: {{PROJECT_NAME}}
+type: {{application|workflow|utility|client|campaign}}
+rigor: {{deep|standard|tight|creative}}
+created: {{ISO_DATE}}
+---
+
+## Vision
+
+<!-- One paragraph: what is this project and why does it exist? -->
+{{VISION}}
+
+## Users
+
+<!-- Who uses this? What are their roles and goals? -->
+{{USERS}}
+
+## Requirements
+
+### v1 — Must Have
+
+<!-- Core features for the first working version -->
+- {{REQUIREMENT_1}}
+- {{REQUIREMENT_2}}
+- {{REQUIREMENT_3}}
+
+### v2 — Nice to Have
+
+<!-- Features that can wait for a second iteration -->
+- {{REQUIREMENT_4}}
+- {{REQUIREMENT_5}}
+
+### Out of Scope
+
+<!-- Explicitly excluded — prevents scope creep -->
+- {{EXCLUSION_1}}
+- {{EXCLUSION_2}}
+
+## Tech Stack
+
+<!-- Chosen technologies and why -->
+| Layer | Choice | Reason |
+|-------|--------|--------|
+| {{LAYER}} | {{TECH}} | {{REASON}} |
+
+## Architecture Decisions
+
+<!-- Key decisions made during ideation -->
+- {{DECISION_1}}: {{RATIONALE}}
+- {{DECISION_2}}: {{RATIONALE}}
+
+## Phase Breakdown
+
+<!-- High-level phases before detailed roadmapping -->
+1. **{{PHASE_1_NAME}}** — {{PHASE_1_DESCRIPTION}}
+2. **{{PHASE_2_NAME}}** — {{PHASE_2_DESCRIPTION}}
+3. **{{PHASE_3_NAME}}** — {{PHASE_3_DESCRIPTION}}
+
+## Open Questions
+
+<!-- Anything unresolved that needs to be decided during DISCUSS phase -->
+- {{QUESTION_1}}
+- {{QUESTION_2}}

package/skills/gsd/templates/STATE.md

@@ -0,0 +1,41 @@
+---
+milestone: M001
+current_slice: S01
+current_task: T01
+phase: seed
+loop_position: 0
+unify_required: false
+rigor: standard
+project_type: application
+auto_mode: false
+last_updated: {{ISO_DATE}}
+---
+
+## Progress
+
+| Slice | Status | AC Passed | Unified |
+|-------|--------|-----------|---------|
+| S01   | pending | 0/0      | no      |
+
+## Acceptance Criteria Tracking
+
+<!-- Updated by /gsd-cc-apply after each task -->
+
+| AC    | Slice | Task | Status  | Evidence |
+|-------|-------|------|---------|----------|
+
+## Boundaries Active
+
+<!-- Copied from current slice plan, enforced by /gsd-cc-apply -->
+
+## Decisions This Slice
+
+<!-- Appended by /gsd-cc-discuss and during execution -->
+
+## Deferred
+
+<!-- Issues pushed to later slices -->
+
+## Blocked
+
+<!-- Tasks that cannot proceed — reason and dependency -->

package/skills/gsd/templates/UNIFY.md

@@ -0,0 +1,43 @@
+---
+slice: {{SLICE_ID}}
+date: {{ISO_DATE}}
+status: {{complete|partial|failed}}
+---
+
+## Plan vs. Actual
+
+| Task | Planned | Actual | Status |
+|------|---------|--------|--------|
+| T01  | {{PLANNED_DESCRIPTION}} | {{ACTUAL_DESCRIPTION}} | {{STATUS_EMOJI}} as planned / expanded / partial / skipped |
+| T02  | {{PLANNED_DESCRIPTION}} | {{ACTUAL_DESCRIPTION}} | {{STATUS_EMOJI}} |
+
+## Acceptance Criteria
+
+| AC   | Status | Evidence |
+|------|--------|----------|
+| AC-1 | {{PASS/PARTIAL/FAIL}} | {{TEST_OUTPUT_OR_EVIDENCE}} |
+| AC-2 | {{PASS/PARTIAL/FAIL}} | {{TEST_OUTPUT_OR_EVIDENCE}} |
+
+## Decisions Made
+
+<!-- Decisions made during execution that were not in the original plan -->
+- {{DECISION_1}} (reason: {{WHY}})
+- {{DECISION_2}} (reason: {{WHY}})
+
+## Boundary Violations
+
+<!-- Did any task modify files listed in another task's DO NOT CHANGE? -->
+<!-- "None." if all boundaries were respected -->
+{{NONE_OR_LIST}}
+
+## Deferred
+
+<!-- Issues discovered during execution, pushed to future slices -->
+- [ ] {{ISSUE_1}} → {{TARGET_SLICE}}
+- [ ] {{ISSUE_2}} → later
+
+## Reassessment
+
+<!-- Does the rest of the roadmap still make sense given what was learned? -->
+<!-- One of: "Roadmap still valid." / "Roadmap needs update: {{REASON}}" -->
+{{REASSESSMENT_VERDICT}}