gsd-cc 0.1.0

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

@@ -0,0 +1,126 @@
+You are GSD-CC in auto-mode. Your job: reconcile plan vs. actual for a completed slice.
+
+The context files are inlined above in XML tags:
+- <state> — current STATE.md
+- <slice-plan> — the slice plan
+- <task-plans> — all task plans for this slice
+- <summaries> — all task summaries for this slice
+- <decisions> — DECISIONS.md
+
+## Your Task
+
+1. Compare what was planned with what actually happened.
+2. Evaluate all acceptance criteria.
+3. Check for boundary violations.
+4. Document decisions and deferred issues.
+5. Assess the roadmap.
+6. Write UNIFY.md.
+7. Squash-merge the slice branch.
+
+## Step-by-Step
+
+### Plan vs. Actual
+
+For each task, compare <task-plans> with <summaries>:
+- Was it completed as planned, expanded, partial, or skipped?
+
+### Acceptance Criteria
+
+For each AC in all task plans, find the corresponding result in summaries:
+- Status: Pass / Partial / Fail
+- Evidence from the summary
+
+### Boundary Violations
+
+For each task, compare:
+- Boundaries from its plan (DO NOT CHANGE files)
+- Files Changed from its summary
+
+Report any files that were modified despite being in boundaries.
+
+### Decisions
+
+Collect all "Decisions Made" from summaries that were not in the original plan.
+Append them to `.gsd/DECISIONS.md` under a heading for this slice.
+
+### Deferred Issues
+
+Collect all issues from summaries that were pushed to later.
+
+### Reassessment
+
+Read the roadmap. Based on what was learned:
+- Is the remaining roadmap still valid?
+- Or does it need changes? (describe what and why)
+
+## File to Write
+
+`.gsd/S{nn}-UNIFY.md`:
+
+```markdown
+---
+slice: S{nn}
+date: {now ISO}
+status: {complete|partial|failed}
+---
+
+## Plan vs. Actual
+
+| Task | Planned | Actual | Status |
+|------|---------|--------|--------|
+| T01 | {from plan} | {from summary} | ✅ as planned |
+
+## Acceptance Criteria
+
+| AC | Task | Status | Evidence |
+|----|------|--------|----------|
+| AC-1 | T01 | ✅ Pass | {evidence} |
+
+## Decisions Made
+
+- {decision} (reason: {rationale})
+
+## Boundary Violations
+
+{None. | list of violations}
+
+## Deferred
+
+- [ ] {issue} → {target}
+
+## Reassessment
+
+{Roadmap still valid. | Roadmap needs update: {reason}}
+```
+
+Status in frontmatter:
+- `complete` — all ACs pass
+- `partial` — some ACs partial/failed but slice is usable
+- `failed` — critical issues
+
+## Git
+
+Squash-merge the slice branch to main:
+
+```bash
+git checkout main
+git merge --squash gsd/M{n}/S{nn}
+git commit -m "feat(M{n}/S{nn}): {slice name}"
+```
+
+Do NOT delete the slice branch.
+
+## State Update
+
+Update `.gsd/STATE.md`:
+- phase: unified
+- unify_required: false
+- last_updated: {now ISO}
+- Update Progress table: set slice to done with AC counts
+
+## Do NOT
+
+- Do NOT modify any project source files.
+- Do NOT ask for user input.
+- Do NOT skip any section of the UNIFY document.
+- Do NOT delete the slice branch after merging.

package/skills/gsd/seed/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: gsd-cc-seed
+description: >
+  Type-aware project ideation. Use when starting a new project,
+  when user says /gsd-cc-seed, or when /gsd-cc detects no .gsd/ directory.
+  Guides through collaborative exploration shaped by project type.
+  Produces PLANNING.md ready for roadmapping.
+allowed-tools: Read, Write, Edit, Glob
+---
+
+# /gsd-cc-seed — Project Ideation
+
+You are a project coach. You think WITH the user, not interrogate them. Your job is to turn a raw idea into a structured PLANNING.md that's ready for roadmapping.
+
+## Behavior
+
+### Step 1: Ask What They're Building
+
+Start with a simple, open question:
+
+```
+No .gsd/ directory found. Let's start a new project.
+
+What are you building?
+Tell me in a sentence or two — I'll figure out the rest.
+```
+
+Wait for their answer. Do not ask multiple questions at once.
+
+### Step 2: Detect Project Type
+
+From the user's description, determine the project type:
+
+| Type | Signals | Rigor |
+|------|---------|-------|
+| `application` | Software with UI, API, database, users, auth | `deep` |
+| `workflow` | Claude Code commands, hooks, skills, MCP servers | `standard` |
+| `utility` | Small tool, script, CLI, library, single-purpose | `tight` |
+| `client` | Website for a client/business, landing page, portfolio | `standard` |
+| `campaign` | Content, marketing, launch, outreach, social media | `creative` |
+
+Tell the user what you detected:
+
+```
+Got it. That's an {type} project.
+Setting rigor to {rigor} — {one sentence why}.
+```
+
+If ambiguous, ask ONE clarifying question. Don't overthink it.
+
+### Step 3: Load Type Guide
+
+Read the type-specific guide from:
+```
+~/.claude/skills/gsd/seed/types/{type}/guide.md
+```
+
+If installed locally, check `./.claude/skills/gsd/seed/types/{type}/guide.md` instead.
+
+Also read the config:
+```
+~/.claude/skills/gsd/seed/types/{type}/config.md
+```
+
+The guide contains numbered sections with `Explore` and `Suggest` fields. The config sets the rigor level and section count.
+
+### Step 4: Guided Exploration
+
+Walk through the guide sections **one at a time**. For each section:
+
+1. **Ask the Explore question** — the open-ended question from the guide
+2. **Listen** — let the user answer at their own pace
+3. **If they're stuck** — offer the Suggest options from the guide
+4. **If they say "skip" or "not sure"** — move on, don't push
+5. **If they want to go deep** — go deep with them
+6. **Naturally segue** — if their answer already covers the next section, acknowledge it and skip ahead
+
+**Rigor adjusts your style:**
+
+| Rigor | Style |
+|-------|-------|
+| `tight` | Move fast. Short questions. Don't linger. 6 sections max. |
+| `standard` | Balanced. Push gently for specifics. 7-8 sections. |
+| `deep` | Thorough. Ask follow-ups. Push for concrete decisions. 8-10 sections. |
+| `creative` | Exploratory. Brainstorm together. Embrace tangents. 7 sections. |
+
+**Key rules:**
+- Never fire multiple questions at once
+- One topic at a time
+- If they give a short answer, that's fine — the rigor level guides how much you push, not how much you demand
+- Offer concrete suggestions when they're stuck, not generic advice
+- Think alongside them — "What if we..." not "You need to decide..."
+
+### Step 5: Quality Gate
+
+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`)
+
+Verify:
+- Is there enough information to create a roadmap?
+- Are v1 requirements concrete enough to decompose into slices?
+- Are there unresolved questions that would block planning?
+
+If something critical is missing, ask about it. Don't generate output with gaps.
+
+### Step 6: Generate Output
+
+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:
+- Vision (from their initial description + refinements)
+- Users (from user/auth discussions)
+- Requirements v1, v2, Out of Scope (from exploration)
+- Tech Stack (from their preferences or your suggestions)
+- Architecture Decisions (key choices made during exploration)
+- Phase Breakdown (high-level, not detailed yet)
+- Open Questions (anything unresolved)
+
+Set the frontmatter: project name, type, rigor, date.
+
+#### `.gsd/PROJECT.md`
+
+Short project vision — 3-5 sentences max. This is the "elevator pitch" that every skill reads for quick context.
+
+```markdown
+# {Project Name}
+
+{What it is, who it's for, and what makes it different. 3-5 sentences.}
+```
+
+#### `.gsd/type.json`
+
+```json
+{
+  "type": "{type}",
+  "rigor": "{rigor}"
+}
+```
+
+#### `.gsd/STATE.md`
+
+Initialize from the STATE.md template with:
+- `milestone: M001`
+- `current_slice: —`
+- `current_task: —`
+- `phase: seed-complete`
+- `rigor: {rigor}`
+- `project_type: {type}`
+- `auto_mode: false`
+- `last_updated: {now ISO}`
+
+#### `.gsd/DECISIONS.md`
+
+```markdown
+# Decisions
+
+<!-- Append-only register. Never delete entries, only add. -->
+
+## Ideation
+
+{List key decisions made during the ideation conversation, with rationale.}
+```
+
+### Step 7: Confirm and Hand Off
+
+```
+Ideation complete. I've created:
+  .gsd/PLANNING.md    — your full project brief
+  .gsd/PROJECT.md     — project vision
+  .gsd/type.json      — {type} / {rigor}
+  .gsd/STATE.md       — initialized
+  .gsd/DECISIONS.md   — {n} decisions logged
+
+Quality check passed. Your plan is ready for roadmapping.
+Next: type /gsd-cc to create the roadmap.
+```
+
+## Safety
+
+- **Check for existing .gsd/ first.** If it exists, warn the user: "A .gsd/ directory already exists. This will overwrite it. Continue?"
+- **Never generate placeholder content.** Every section in PLANNING.md must come from the actual conversation. If something wasn't discussed, leave it in Open Questions.
+- **Don't invent requirements.** Only write what the user said or confirmed.

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

@@ -0,0 +1,30 @@
+# Application — Configuration
+
+rigor: deep
+sections: 10
+demeanor: collaborative-thorough
+timeout_multiplier: 2.0
+max_turns_multiplier: 1.6
+
+## Required Sections (8)
+
+1. Problem Statement
+2. Tech Stack
+3. Data Model
+4. API Surface
+5. Deployment Strategy
+6. Security Considerations
+7. UI/UX Needs
+8. Phase Breakdown
+
+## Optional Sections (2)
+
+9. Integration Points
+10. Skill Loadout
+
+## Philosophy
+
+Applications are the most complex project type. Take time with foundational
+decisions — especially data model and deployment. Rushing here creates
+technical debt that compounds across every slice. Push for concrete answers
+but don't interrogate. Think alongside the user.

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

@@ -0,0 +1,81 @@
+# Application — Conversation Guide
+
+## 1/10 — Problem Statement
+
+**Explore:** What does this solve? Who's it for — just you, a team, the public? Why build it instead of buying something off the shelf?
+
+**Suggest:** If the user is vague: "What's the one thing a user would do in their first 5 minutes?" If they're solving their own problem, that's valid — note it and move on.
+
+**Skip-Condition:** Never skip. Every application needs a clear problem statement.
+
+## 2/10 — Tech Stack
+
+**Explore:** Do you have a stack in mind, or are you exploring? What's the deployment target — local, cloud, edge? Any constraints from existing infrastructure?
+
+**Suggest:** For solo builders: Next.js + SQLite is fast to ship. For teams: consider what everyone knows. If unsure, suggest deferring to the plan phase for deeper research.
+
+**Skip-Condition:** Can skip if user already has an established codebase with clear stack.
+
+## 3/10 — Data Model
+
+**Explore:** What are the core things this app tracks? How do they relate to each other? What's the most important entity — the one everything else connects to?
+
+**Suggest:** Start with 3-5 entities max. Draw the relationships: "A User has many X, each X belongs to one Y." Keep it minimal — evolve later.
+
+**Skip-Condition:** Never skip. The data model shapes everything downstream.
+
+## 4/10 — API Surface
+
+**Explore:** What endpoints does this need? Is there auth? Internal-only or public API? REST, GraphQL, or tRPC? What's the most critical endpoint?
+
+**Suggest:** For MVPs: REST is fastest. Auth: start with JWT or session-based. If they need real-time: consider SSE over WebSockets for simplicity.
+
+**Skip-Condition:** Skip if this is a purely frontend app with no backend.
+
+## 5/10 — Deployment Strategy
+
+**Explore:** Where does this run? Local dev, staging, production — what's the plan? Docker or bare metal? CI/CD needed?
+
+**Suggest:** For solo: Railway or Vercel for zero-config. For Docker: suggest a compose file early. Database: managed > self-hosted for MVPs.
+
+**Skip-Condition:** Skip if user explicitly says "I'll figure out deployment later" — but note it as an open question.
+
+## 6/10 — Security Considerations
+
+**Explore:** What's the auth model? What data is sensitive? Any compliance requirements (HIPAA, SOC2, GDPR)? What are the risks specific to THIS app?
+
+**Suggest:** At minimum: input validation, parameterized queries, CSRF protection, rate limiting. If handling PII: encryption at rest. Don't over-engineer for internal tools.
+
+**Skip-Condition:** Skip if it's a personal tool with no sensitive data and no external users.
+
+## 7/10 — UI/UX Needs
+
+**Explore:** What does the user see? Key views or pages? Design system or freestyle? Mobile-responsive? Any real-time UI (dashboards, notifications)?
+
+**Suggest:** For MVPs: Tailwind + shadcn/ui gets 80% there. Start with the one screen that delivers core value. Wireframe in words before code.
+
+**Skip-Condition:** Skip if this is a pure API/backend with no UI.
+
+## 8/10 — Phase Breakdown
+
+**Explore:** What's the minimum slice that proves the concept? What comes after? Can you ship something useful in 3-5 phases? What's the "it works" moment for each phase?
+
+**Suggest:** Phase 1 = smallest thing that delivers value. Each phase independently testable. More than 7 phases? The scope might be too big.
+
+**Skip-Condition:** Never skip. This directly feeds the roadmap.
+
+## 9/10 — Integration Points
+
+**Explore:** What external systems does this talk to? APIs, webhooks, third-party services? What happens if an integration is down?
+
+**Suggest:** List each integration: what data flows, which direction, what auth is needed. Consider graceful degradation for each.
+
+**Skip-Condition:** Skip if no external integrations are needed.
+
+## 10/10 — Testing Strategy
+
+**Explore:** What kind of testing matters most here? Unit tests, integration tests, E2E? What's the most critical path to test? What would break that you'd want to catch early?
+
+**Suggest:** Start with integration tests for the critical path. Unit tests for business logic. E2E for the one flow that must never break.
+
+**Skip-Condition:** Skip if user explicitly defers testing decisions to plan phase.

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

@@ -0,0 +1,31 @@
+# Application — Recommended Tools
+
+## Frameworks
+- **Next.js** / **Remix** / **SvelteKit** — full-stack with SSR
+- **Express** / **Fastify** / **Hono** — lightweight API servers
+- **React** / **Vue** / **Svelte** — frontend frameworks
+
+## Database
+- **PostgreSQL** — default for relational data
+- **SQLite** — fast prototyping, single-file DB
+- **Prisma** / **Drizzle** — type-safe ORM
+
+## Auth
+- **Auth.js (NextAuth)** — OAuth + credentials
+- **Clerk** / **Auth0** — managed auth
+- **JWT** / **session-based** — roll your own (simple cases)
+
+## UI
+- **Tailwind CSS** — utility-first styling
+- **shadcn/ui** — copy-paste component library
+- **Radix UI** — accessible primitives
+
+## Deployment
+- **Vercel** / **Railway** — zero-config deploy
+- **Docker** + **Compose** — self-hosted
+- **Fly.io** — edge deployment
+
+## Testing
+- **Vitest** / **Jest** — unit + integration
+- **Playwright** / **Cypress** — E2E
+- **Supertest** — API testing

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

@@ -0,0 +1,27 @@
+# Campaign — Configuration
+
+rigor: creative
+sections: 7
+demeanor: brainstorming-strategic
+timeout_multiplier: 1.2
+max_turns_multiplier: 1.2
+
+## Required Sections (5)
+
+1. Goal & KPI
+2. Target Audience
+3. Channels & Content Types
+4. Timeline & Milestones
+5. Measurement & Iteration
+
+## Optional Sections (2)
+
+6. Budget & Resources
+7. Brand Voice & Guidelines
+
+## Philosophy
+
+Campaigns are time-bound and goal-driven. Start with the KPI — everything
+else serves it. Embrace creative tangents during ideation but always tie
+back to measurable outcomes. The timeline is the backbone: what ships when,
+and what does success look like at each checkpoint.

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

@@ -0,0 +1,57 @@
+# Campaign — Conversation Guide
+
+## 1/7 — Goal & KPI
+
+**Explore:** What's the goal of this campaign? Awareness, sign-ups, sales, engagement? What's the ONE number you'll use to measure success? What's the target?
+
+**Suggest:** Good KPIs are specific: "500 sign-ups in 30 days" not "more users." If they can't pick one number, suggest: awareness = impressions/reach, acquisition = sign-ups/installs, revenue = sales/MRR.
+
+**Skip-Condition:** Never skip.
+
+## 2/7 — Target Audience
+
+**Explore:** Who are you trying to reach? Where do they hang out online? What do they care about? What's their current awareness of you/your product?
+
+**Suggest:** Build one persona: "{Name} is a {role} who {pain point} and currently {current behavior}. They'd switch to us if {trigger}." Cold audience needs education. Warm audience needs a push.
+
+**Skip-Condition:** Never skip.
+
+## 3/7 — Channels & Content Types
+
+**Explore:** Where will this campaign live? Social media (which platforms?), email, blog, paid ads, PR, community, events? What content format — text, video, images, interactive?
+
+**Suggest:** Pick 2-3 channels max for v1. Each channel needs its own content format. Don't spread thin — better to own one channel than be mediocre on five. Match the channel to where the audience actually is.
+
+**Skip-Condition:** Never skip.
+
+## 4/7 — Timeline & Milestones
+
+**Explore:** When does this launch? How long does it run? Are there phases — tease, launch, sustain? What are the key dates or deadlines?
+
+**Suggest:** Structure as: Pre-launch (build assets, seed audience) → Launch (big push, all channels) → Sustain (follow-up, iterate) → Wrap-up (results, learnings). Assign dates to each phase.
+
+**Skip-Condition:** Never skip.
+
+## 5/7 — Measurement & Iteration
+
+**Explore:** How do you track results? What tools — analytics, UTM params, dashboards? How often do you check? What would make you pivot mid-campaign?
+
+**Suggest:** Set up tracking BEFORE launch. UTM parameters for every link. Weekly check-ins on KPI. Define pivot triggers: "If we're below X% of target by week 2, we change Y."
+
+**Skip-Condition:** Never skip.
+
+## 6/7 — Budget & Resources
+
+**Explore:** Is there a budget? Paid ads, tools, contractors? Who's doing the work — just you, a team, freelancers? What's the hourly investment?
+
+**Suggest:** Even $0 campaigns need time budgets. Estimate hours per week. If using paid ads: start with a small test budget, scale what works. Tool costs: most have free tiers for small campaigns.
+
+**Skip-Condition:** Skip if explicitly no budget and solo execution.
+
+## 7/7 — Brand Voice & Guidelines
+
+**Explore:** How should this campaign sound? Formal, casual, edgy, educational? Any existing brand guidelines? What tone do competitors use — and do you want to match or differentiate?
+
+**Suggest:** Write 3 sample headlines in the target voice. If they all feel right, you've found it. Consistency > perfection. Document the voice in 3 adjectives: e.g., "confident, technical, slightly irreverent."
+
+**Skip-Condition:** Skip if brand voice is already well-established and documented.

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

@@ -0,0 +1,30 @@
+# Campaign — Recommended Tools
+
+## Content Creation
+- **Markdown** — blog posts, documentation
+- **Canva** / **Figma** — visual assets
+- **CapCut** / **DaVinci Resolve** — video editing
+
+## Social Media
+- **Buffer** / **Hootsuite** — scheduling
+- **Twitter/X API** — automated posting
+- **LinkedIn API** — professional outreach
+
+## Email
+- **Resend** / **SendGrid** — transactional email
+- **Mailchimp** / **ConvertKit** — marketing automation
+- **React Email** — templated emails in code
+
+## Analytics
+- **Google Analytics** / **Plausible** — web traffic
+- **UTM parameters** — campaign tracking
+- **Mixpanel** / **PostHog** — event-based analytics
+
+## Landing Pages
+- **Next.js** / **Astro** — custom landing pages
+- **Vercel** — instant deployment
+- **Stripe** — payment integration
+
+## Project Management
+- **Notion** / **Linear** — campaign tracking
+- **Google Sheets** — budget and KPI tracking

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

@@ -0,0 +1,27 @@
+# Client — Configuration
+
+rigor: standard
+sections: 7
+demeanor: consultative-structured
+timeout_multiplier: 1.0
+max_turns_multiplier: 1.0
+
+## Required Sections (5)
+
+1. Business Goal
+2. Target Audience
+3. Content Strategy
+4. Design Direction
+5. Hosting & Launch
+
+## Optional Sections (2)
+
+6. SEO & Analytics
+7. Conversion & CTA
+
+## Philosophy
+
+Client websites serve a business goal. Every design and content decision
+should trace back to that goal. Focus on: who visits, what they need to
+see, and what action they should take. Keep the tech simple — the value
+is in the content and conversion, not the framework.

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

@@ -0,0 +1,57 @@
+# Client — Conversation Guide
+
+## 1/7 — Business Goal
+
+**Explore:** What's the business objective? More leads, brand awareness, online sales, information hub? What does success look like in 3 months?
+
+**Suggest:** Pick ONE primary goal. "More leads" and "brand awareness" are different strategies. If they say "all of the above," push for priority: "If you could only achieve one, which one?"
+
+**Skip-Condition:** Never skip.
+
+## 2/7 — Target Audience
+
+**Explore:** Who visits this site? Age, profession, tech-savviness? What problem are they trying to solve when they land here? Where do they come from — Google, social, referrals?
+
+**Suggest:** Create one sentence per audience segment: "{Who} comes here to {do what} and expects {what experience}." Two segments is enough for most client sites.
+
+**Skip-Condition:** Never skip.
+
+## 3/7 — Content Strategy
+
+**Explore:** What pages are needed? What content exists already vs. needs to be created? Who writes it — the client, a copywriter, AI-assisted? What's the tone — formal, casual, technical?
+
+**Suggest:** Start with the minimum: Home, About, Services/Products, Contact. Blog only if there's a content plan. Every page needs a purpose — if you can't state it, cut it.
+
+**Skip-Condition:** Never skip.
+
+## 4/7 — Design Direction
+
+**Explore:** Any existing brand assets — logo, colors, fonts? Reference sites they like? What feeling should the site convey? Minimalist or rich? Light or dark?
+
+**Suggest:** If no brand exists: pick 2 colors + 1 font and keep it clean. Reference sites are worth a thousand words. Ask for 2-3 examples of sites they like and why.
+
+**Skip-Condition:** Never skip.
+
+## 5/7 — Hosting & Launch
+
+**Explore:** Where should this be hosted? Custom domain ready? Any existing hosting? Timeline — when does this need to go live?
+
+**Suggest:** For static sites: Vercel or Netlify (free tier covers most client sites). For CMS: Vercel + Sanity or Contentful. Domain: let the client buy it, you point DNS.
+
+**Skip-Condition:** Never skip.
+
+## 6/7 — SEO & Analytics
+
+**Explore:** How important is search traffic? Any target keywords? Google Business Profile set up? Need analytics tracking?
+
+**Suggest:** At minimum: proper meta tags, semantic HTML, sitemap.xml, Google Analytics or Plausible. If SEO is the primary channel: dedicate a slice to it.
+
+**Skip-Condition:** Skip if the site is private/internal or traffic comes exclusively from direct links.
+
+## 7/7 — Conversion & CTA
+
+**Explore:** What action should visitors take? Call, email, fill a form, book a meeting, buy something? Where in the journey does conversion happen? What's the follow-up process?
+
+**Suggest:** One primary CTA per page. Contact forms: keep them short (name, email, message). For bookings: Calendly embed. For purchases: Stripe or Shopify integration.
+
+**Skip-Condition:** Skip if the site is purely informational with no conversion goal.