get-shit-done-cc 1.9.13 → 1.10.0-experimental.0

package/get-shit-done/references/ui-principles.md

@@ -0,0 +1,258 @@
+---
+name: ui-principles
+description: Professional UI/UX design principles for high-quality interfaces
+load_when:
+  - design
+  - ui
+  - frontend
+  - component
+  - layout
+  - mockup
+auto_load_for: []
+---
+
+<ui_principles>
+
+## Overview
+
+Professional UI design principles that ensure high-quality, polished interfaces. These are non-negotiable standards—not suggestions.
+
+## Visual Hierarchy
+
+### Establish Clear Priority
+
+Every screen has one primary action. Make it obvious.
+
+**Weight hierarchy:**
+1. Primary action (bold, prominent, singular)
+2. Secondary actions (visible but subdued)
+3. Tertiary actions (discoverable but not competing)
+
+**Size signals importance:**
+- Headings > body text > captions
+- Primary buttons > secondary > tertiary
+- Key metrics > supporting data
+
+### Whitespace Is Not Empty
+
+Whitespace is a design element. It:
+- Groups related items
+- Separates unrelated items
+- Creates breathing room
+- Signals quality
+
+**Minimum spacing guidelines:**
+- Between unrelated sections: 32-48px
+- Between related items: 16-24px
+- Internal padding: 12-16px
+- Touch targets: 44px minimum
+
+## Typography
+
+### Establish a Type Scale
+
+Use a consistent mathematical scale. Example (1.25 ratio):
+```
+12px - Caption/small
+14px - Body small
+16px - Body (base)
+20px - H4
+24px - H3
+32px - H2
+40px - H1
+```
+
+### Font Weights
+
+Limit to 2-3 weights maximum:
+- Regular (400) - Body text
+- Medium (500) - Emphasis, labels
+- Bold (700) - Headings, key actions
+
+### Line Height
+
+- Body text: 1.5-1.6
+- Headings: 1.2-1.3
+- Captions: 1.4
+
+### Maximum Line Width
+
+Body text: 60-75 characters. Longer lines reduce readability.
+
+## Color
+
+### Build a Palette
+
+**Semantic colors:**
+- Primary: Brand/action color
+- Secondary: Supporting accent
+- Success: #22C55E range (green)
+- Warning: #F59E0B range (amber)
+- Error: #EF4444 range (red)
+- Info: #3B82F6 range (blue)
+
+**Neutral scale:**
+Build 9-11 shades from near-white to near-black:
+```
+50  - Backgrounds, subtle borders
+100 - Hover states, dividers
+200 - Disabled states
+300 - Borders
+400 - Placeholder text
+500 - Secondary text
+600 - Body text (dark mode)
+700 - Body text (light mode)
+800 - Headings
+900 - High contrast text
+950 - Near black
+```
+
+### Contrast Requirements
+
+- Body text: 4.5:1 minimum (WCAG AA)
+- Large text (18px+): 3:1 minimum
+- Interactive elements: 3:1 against background
+
+## Layout
+
+### Grid Systems
+
+Use a consistent grid:
+- 4px base unit for spacing
+- 8px increments for larger spacing
+- 12-column grid for responsive layouts
+
+### Responsive Breakpoints
+
+```
+sm:  640px   - Mobile landscape
+md:  768px   - Tablets
+lg:  1024px  - Small desktops
+xl:  1280px  - Standard desktops
+2xl: 1536px  - Large displays
+```
+
+### Content Width
+
+- Maximum content width: 1200-1440px
+- Prose/reading: 680-720px
+- Forms: 480-560px
+
+## Components
+
+### Buttons
+
+**States (all buttons must have):**
+- Default
+- Hover
+- Active/pressed
+- Focus (visible outline)
+- Disabled
+- Loading (if applicable)
+
+**Sizing:**
+- Small: 32px height, 12px horizontal padding
+- Medium: 40px height, 16px horizontal padding
+- Large: 48px height, 24px horizontal padding
+
+### Form Inputs
+
+**States:**
+- Default
+- Hover
+- Focus (prominent ring)
+- Error (red border + message)
+- Disabled
+- Read-only
+
+**Guidelines:**
+- Labels above inputs (not inside)
+- Helper text below inputs
+- Error messages replace helper text
+- Required indicator: asterisk after label
+
+### Cards
+
+**Structure:**
+- Optional media (top or left)
+- Content area with consistent padding
+- Optional footer for actions
+- Subtle shadow or border
+
+**Guidelines:**
+- Consistent border radius (8px is standard)
+- Don't overload with actions
+- Group related cards visually
+
+## Interaction
+
+### Feedback
+
+Every action needs feedback:
+- Button click: Visual press state
+- Form submission: Loading state → success/error
+- Navigation: Active state indication
+- Background processes: Progress indication
+
+### Transitions
+
+**Duration:**
+- Micro interactions: 100-150ms
+- UI transitions: 200-300ms
+- Page transitions: 300-500ms
+
+**Easing:**
+- Entering: ease-out
+- Exiting: ease-in
+- Moving: ease-in-out
+
+### Loading States
+
+Never leave users wondering:
+- Skeleton screens for content loading
+- Spinners for brief waits
+- Progress bars for longer operations
+- Disable interactive elements during submission
+
+## Anti-Patterns
+
+### Visual Noise
+
+**Problem:** Too many colors, borders, shadows competing
+**Fix:** Reduce to essentials. When in doubt, remove.
+
+### Inconsistent Spacing
+
+**Problem:** Random margins and padding throughout
+**Fix:** Use spacing scale religiously (4, 8, 12, 16, 24, 32, 48...)
+
+### Orphan Elements
+
+**Problem:** Single items floating with no visual relationship
+**Fix:** Group related elements. Use proximity and shared styling.
+
+### Weak Hierarchy
+
+**Problem:** Everything looks equally important
+**Fix:** Make primary action 2x more prominent. Reduce secondary elements.
+
+### Over-Decoration
+
+**Problem:** Gradients, shadows, borders, rounded corners all at once
+**Fix:** Pick 1-2 decorative elements per component max.
+
+## Professional Polish Checklist
+
+- [ ] Consistent spacing throughout
+- [ ] Type scale followed exactly
+- [ ] Color palette limited and purposeful
+- [ ] All interactive states designed
+- [ ] Proper contrast ratios
+- [ ] Touch targets 44px+
+- [ ] Loading states for all async operations
+- [ ] Error states for all forms
+- [ ] Focus states visible for keyboard navigation
+- [ ] No orphan elements
+- [ ] Clear visual hierarchy
+
+</ui_principles>

package/get-shit-done/references/verification-patterns.md

@@ -600,7 +600,7 @@ Some things can't be verified programmatically. Flag these for human testing:
 
 For automation-first checkpoint patterns, server lifecycle management, CLI installation handling, and error recovery protocols, see:
 
-**@~/.claude/get-shit-done/references/checkpoints.md** → `<automation_reference>` section
+**@~/.claude/get-shit-done/references/checkpoint-execution.md** → `<automation_reference>` section
 
 Key principles:
 - Claude sets up verification environment BEFORE presenting checkpoints

package/get-shit-done/skills/gsd-extend/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: gsd-extend
+description: Create custom GSD approaches - complete methodologies with workflows, agents, references, and templates that work together. Use when users want to customize how GSD operates or add domain-specific execution patterns.
+---
+
+<essential_principles>
+
+## GSD Extension System
+
+GSD is extensible. Users can create custom **approaches** - complete methodologies that integrate with the GSD lifecycle.
+
+An approach might include:
+- **Workflow** - The execution pattern (required)
+- **References** - Domain knowledge loaded during execution
+- **Agent** - Specialized worker spawned by the workflow
+- **Templates** - Output formats for artifacts
+
+These components work together as a cohesive unit, not standalone pieces.
+
+## Extension Resolution Order
+
+```
+1. .planning/extensions/{type}/     (project-specific - highest priority)
+2. ~/.claude/gsd-extensions/{type}/ (global user extensions)
+3. ~/.claude/get-shit-done/{type}/  (built-in GSD - lowest priority)
+```
+
+Project extensions override global, global overrides built-in.
+
+## When to Create an Approach
+
+**Planning alternatives:**
+- Spike-first: Explore before formalizing
+- Research-heavy: Deep investigation before any code
+- Prototype-driven: Build throwaway code to learn
+
+**Execution patterns:**
+- TDD-strict: Enforce red-green-refactor cycle
+- Security-first: Audit before each commit
+- Performance-aware: Profile after each feature
+
+**Domain-specific:**
+- API development with OpenAPI-first workflow
+- Game development with playtest checkpoints
+- ML projects with experiment tracking
+
+**Quality gates:**
+- Accessibility review before UI completion
+- Documentation requirements per feature
+- Architecture review at phase boundaries
+
+</essential_principles>
+
+<routing>
+
+## Understanding User Intent
+
+Based on the user's message, route appropriately:
+
+**Creating new approaches:**
+- "create", "build", "add", "new approach/methodology/workflow"
+  → workflows/create-approach.md
+
+**Managing extensions:**
+- "list", "show", "what extensions" → workflows/list-extensions.md
+- "validate", "check" → workflows/validate-extension.md
+- "remove", "delete" → workflows/remove-extension.md
+
+**If intent is unclear:**
+
+Ask using AskUserQuestion:
+- header: "Action"
+- question: "What would you like to do?"
+- options:
+  - "Create an approach" - Build a custom methodology (workflow + supporting pieces)
+  - "List extensions" - See all installed extensions
+  - "Remove an extension" - Delete something you've created
+
+</routing>
+
+<quick_reference>
+
+## Approach Components
+
+| Component | Purpose | Required? |
+|-----------|---------|-----------|
+| Workflow | Orchestrates the approach | Yes |
+| References | Domain knowledge | Often |
+| Agent | Specialized worker | Sometimes |
+| Templates | Output formats | Sometimes |
+
+## Directory Structure
+
+```
+~/.claude/gsd-extensions/
+├── workflows/
+│   └── spike-first-planning.md
+├── references/
+│   └── spike-patterns.md
+├── agents/
+│   └── spike-evaluator.md
+└── templates/
+    └── spike-summary.md
+```
+
+All components of an approach share a naming convention (e.g., `spike-*`).
+
+## Scope Options
+
+- **Project** (`.planning/extensions/`) - This project only
+- **Global** (`~/.claude/gsd-extensions/`) - All projects
+
+</quick_reference>
+
+<reference_index>
+
+## Domain Knowledge
+
+All in `references/`:
+
+| Reference | Content |
+|-----------|---------|
+| extension-anatomy.md | How extensions work, lifecycle, integration |
+| workflow-structure.md | Workflow format with examples |
+| agent-structure.md | Agent format with examples |
+| reference-structure.md | Reference format with examples |
+| template-structure.md | Template format with examples |
+| validation-rules.md | Validation rules for all types |
+
+</reference_index>
+
+<workflows_index>
+
+## Workflows
+
+| Workflow | Purpose |
+|----------|---------|
+| create-approach.md | Create a complete methodology through conversation |
+| list-extensions.md | Discover all installed extensions |
+| validate-extension.md | Check extension for errors |
+| remove-extension.md | Delete an extension |
+
+</workflows_index>
+
+<success_criteria>
+
+Approach created successfully when:
+- [ ] All components exist and are wired together
+- [ ] Workflow references its supporting pieces correctly
+- [ ] Components pass validation
+- [ ] Approach is discoverable via list-extensions
+- [ ] User understands how to trigger the approach
+
+</success_criteria>

package/get-shit-done/skills/gsd-extend/references/agent-structure.md

@@ -0,0 +1,305 @@
+<agent_structure>
+
+## Agent Extensions
+
+Agents are specialized subagents spawned during GSD operations. They have specific expertise, limited tool access, and focused responsibilities.
+
+## Required Frontmatter
+
+```yaml
+---
+name: agent-name
+description: What this agent does and when to spawn it
+tools: [Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch]
+color: green  # Terminal output color
+spawn_from:
+  - plan-phase           # Spawnable from planning
+  - execute-plan         # Spawnable during execution
+  - execute-phase        # Spawnable from orchestrator
+  - verify-phase         # Spawnable during verification
+  - custom               # Spawnable via explicit Task call
+---
+```
+
+## Available Tools
+
+Choose tools based on agent responsibility:
+
+| Tool | Use For |
+|------|---------|
+| Read | Reading files for context |
+| Write | Creating new files |
+| Edit | Modifying existing files |
+| Bash | Running commands |
+| Grep | Searching file contents |
+| Glob | Finding files by pattern |
+| WebFetch | Fetching web content |
+| WebSearch | Searching the web |
+| mcp__context7__* | Library documentation lookup |
+
+**Principle:** Grant minimum tools needed. More tools = more context usage = lower quality.
+
+## Agent Body Structure
+
+```xml
+<role>
+You are a [specific role]. You [do what] when [triggered how].
+
+Your job: [primary responsibility]
+</role>
+
+<expertise>
+Domain knowledge relevant to this agent's specialty.
+
+- Key concept 1
+- Key concept 2
+- Key concept 3
+</expertise>
+
+<execution_flow>
+
+<step name="understand_context">
+Load and parse input context provided by spawner.
+</step>
+
+<step name="perform_task">
+Core task execution.
+</step>
+
+<step name="produce_output">
+Generate expected output format.
+</step>
+
+</execution_flow>
+
+<output_format>
+Structured format for agent's return value.
+
+## {SECTION_NAME}
+
+**Field:** value
+**Field:** value
+
+### Details
+
+{content}
+</output_format>
+
+<success_criteria>
+- [ ] Criterion one
+- [ ] Criterion two
+</success_criteria>
+```
+
+## Spawning Agents
+
+Agents are spawned via the Task tool:
+
+```
+Task(
+  prompt="<context>...</context>
+
+  Execute as agent: @~/.claude/gsd-extensions/agents/my-agent.md",
+  subagent_type="gsd-executor",  # or other base type
+  model="sonnet",
+  description="Brief description"
+)
+```
+
+**Important:** The `subagent_type` must be a registered type. Custom agents typically use an existing base type with additional instructions from the agent file.
+
+## Agent Communication Pattern
+
+Agents receive context from spawner:
+
+```xml
+<context>
+**Project:** @.planning/PROJECT.md
+**Phase:** {phase_number}
+**Specific input:** {data from spawner}
+</context>
+```
+
+Agents return structured results:
+
+```markdown
+## AGENT_COMPLETE
+
+**Status:** success | partial | blocked
+**Summary:** One-line result
+
+### Output
+
+{Structured output based on agent's output_format}
+
+### Issues (if any)
+
+- Issue 1
+- Issue 2
+```
+
+## Example: Security Auditor Agent
+
+```yaml
+---
+name: security-auditor
+description: Reviews code for security vulnerabilities during execution
+tools: [Read, Grep, Glob]
+color: red
+spawn_from: [execute-plan, verify-phase]
+---
+```
+
+```xml
+<role>
+You are a security auditor. You review code changes for security vulnerabilities
+before they're committed.
+
+Your job: Identify security issues in new or modified code, categorize by
+severity, and provide actionable remediation guidance.
+</role>
+
+<expertise>
+## Security Review Domains
+
+**Injection vulnerabilities:**
+- SQL injection (parameterize queries)
+- Command injection (validate/escape inputs)
+- XSS (sanitize output, use CSP)
+
+**Authentication/Authorization:**
+- Insecure credential storage (use proper hashing)
+- Missing authorization checks
+- Session management issues
+
+**Data exposure:**
+- Sensitive data in logs
+- Hardcoded secrets
+- Overly permissive CORS
+
+**Dependencies:**
+- Known vulnerable packages
+- Outdated dependencies
+</expertise>
+
+<execution_flow>
+
+<step name="identify_changes">
+Identify files modified in current task:
+
+```bash
+git diff --name-only HEAD~1
+```
+
+Filter for code files (.ts, .js, .py, etc.)
+</step>
+
+<step name="review_patterns">
+For each file, search for security anti-patterns:
+
+```bash
+# Hardcoded secrets
+grep -n "password\|secret\|api_key\|token" $FILE
+
+# SQL construction
+grep -n "query.*\+" $FILE
+
+# Dangerous functions
+grep -n "eval\|exec\|innerHTML" $FILE
+```
+</step>
+
+<step name="categorize_findings">
+For each finding:
+1. Verify it's actually a vulnerability (not false positive)
+2. Assign severity: critical, high, medium, low
+3. Provide remediation guidance
+</step>
+
+<step name="generate_report">
+Produce security review report.
+</step>
+
+</execution_flow>
+
+<output_format>
+## SECURITY_REVIEW
+
+**Files reviewed:** {count}
+**Issues found:** {count by severity}
+
+### Critical Issues
+
+| File | Line | Issue | Remediation |
+|------|------|-------|-------------|
+| path | N | description | fix |
+
+### High Issues
+
+...
+
+### Recommendations
+
+1. Recommendation
+2. Recommendation
+
+### Approved
+
+{yes/no - yes if no critical/high issues}
+</output_format>
+
+<success_criteria>
+- [ ] All modified files reviewed
+- [ ] Issues categorized by severity
+- [ ] Remediation guidance provided
+- [ ] Clear approve/reject decision
+</success_criteria>
+```
+
+## Agent Best Practices
+
+**1. Single responsibility**
+Each agent does one thing well. Don't combine security review with performance analysis.
+
+**2. Minimal tools**
+Grant only tools the agent needs. Security auditor doesn't need Write or WebSearch.
+
+**3. Structured output**
+Always use consistent output format. Spawner needs to parse results.
+
+**4. Fail gracefully**
+If agent can't complete, return partial results with clear status.
+
+**5. Be specific in role**
+Generic "helper" agents are useless. Specific expertise is valuable.
+
+## Registering Custom Agents
+
+For GSD to recognize custom agents as valid `subagent_type` values, they need to be registered in `~/.claude/settings.json`:
+
+```json
+{
+  "customAgents": [
+    {
+      "name": "security-auditor",
+      "path": "~/.claude/gsd-extensions/agents/security-auditor.md"
+    }
+  ]
+}
+```
+
+Alternatively, use existing `subagent_type` (like `general-purpose`) and load agent instructions via @-reference:
+
+```
+Task(
+  prompt="@~/.claude/gsd-extensions/agents/security-auditor.md
+
+  Review: {files}",
+  subagent_type="general-purpose",
+  model="sonnet"
+)
+```
+
+This is the recommended approach for custom agents.
+
+</agent_structure>