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

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

@@ -0,0 +1,253 @@
+<workflow_structure>
+
+## Workflow Extensions
+
+Workflows define execution patterns - sequences of steps that GSD follows to accomplish tasks like planning, execution, or verification.
+
+## Required Frontmatter
+
+```yaml
+---
+name: workflow-name
+description: What this workflow accomplishes
+triggers:
+  - plan-phase          # Triggered by /gsd:plan-phase
+  - execute-plan        # Triggered during plan execution
+  - execute-phase       # Triggered by /gsd:execute-phase
+  - verify-phase        # Triggered by verification
+  - custom              # Custom trigger (called explicitly)
+replaces: built-in-name  # Optional: replace a built-in workflow
+requires: [reference-names]  # Optional: auto-load these references
+---
+```
+
+## Workflow Body Structure
+
+```xml
+<purpose>
+What this workflow accomplishes.
+</purpose>
+
+<when_to_use>
+Conditions that trigger this workflow.
+</when_to_use>
+
+<required_reading>
+@~/.claude/get-shit-done/references/some-reference.md
+@.planning/extensions/references/custom-reference.md
+</required_reading>
+
+<process>
+
+<step name="step_one" priority="first">
+First step description.
+
+Code examples:
+```bash
+command --here
+```
+
+Conditional logic:
+<if condition="some condition">
+What to do when condition is true.
+</if>
+</step>
+
+<step name="step_two">
+Second step description.
+</step>
+
+<step name="step_three">
+Third step description.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Criterion one
+- [ ] Criterion two
+- [ ] Criterion three
+</success_criteria>
+```
+
+## Step Attributes
+
+| Attribute | Values | Purpose |
+|-----------|--------|---------|
+| `name` | snake_case | Identifier for the step |
+| `priority` | first, second, last | Execution order hints |
+| `conditional` | if/when expression | Only run if condition met |
+| `parallel` | true/false | Can run with other parallel steps |
+
+## Conditional Logic
+
+Workflows can include conditional sections:
+
+```xml
+<if mode="yolo">
+Auto-approve behavior
+</if>
+
+<if mode="interactive">
+Confirmation-required behavior
+</if>
+
+<if exists=".planning/DISCOVERY.md">
+Behavior when discovery exists
+</if>
+
+<if config="workflow.research">
+Behavior when research is enabled in config
+</if>
+```
+
+## Context Loading
+
+Workflows specify what context to load:
+
+```xml
+<required_reading>
+@~/.claude/get-shit-done/references/deviation-rules.md
+</required_reading>
+
+<conditional_loading>
+**If plan has checkpoints:**
+@~/.claude/get-shit-done/workflows/execute-plan-checkpoints.md
+
+**If authentication error:**
+@~/.claude/get-shit-done/workflows/execute-plan-auth.md
+</conditional_loading>
+```
+
+## Output Specification
+
+Workflows should specify expected outputs:
+
+```xml
+<output>
+After completion, create:
+- `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
+
+Use template:
+@~/.claude/get-shit-done/templates/summary.md
+</output>
+```
+
+## Integration with GSD Commands
+
+To use a custom workflow from a GSD command:
+
+**Option 1: Replace built-in**
+Name your workflow same as built-in (e.g., `execute-plan.md`). GSD automatically uses yours.
+
+**Option 2: Explicit reference**
+In your command or another workflow:
+```xml
+<execution_context>
+@.planning/extensions/workflows/my-workflow.md
+</execution_context>
+```
+
+**Option 3: Spawn pattern**
+If workflow runs as subagent:
+```
+Task(prompt="Follow workflow: @~/.claude/gsd-extensions/workflows/my-workflow.md", ...)
+```
+
+## Example: Custom Planning Workflow
+
+```yaml
+---
+name: spike-first-planning
+description: Plan by spiking first, then formalizing
+triggers: [plan-phase]
+replaces: null  # Alternative to default, not replacement
+---
+```
+
+```xml
+<purpose>
+Alternative planning workflow that creates a spike implementation first,
+then derives formal plans from what worked.
+</purpose>
+
+<when_to_use>
+- Domain is unfamiliar
+- Requirements are fuzzy
+- You want to discover approach through doing
+</when_to_use>
+
+<process>
+
+<step name="create_spike_plan">
+Create a minimal spike plan:
+- Single task: "Spike: {phase goal}"
+- No formal structure
+- Goal is learning, not delivery
+</step>
+
+<step name="execute_spike">
+Execute the spike:
+- Time-boxed (1-2 hours)
+- Document discoveries
+- Note what worked and what didn't
+</step>
+
+<step name="derive_formal_plans">
+From spike learnings:
+- Extract the approach that worked
+- Formalize into proper PLAN.md files
+- Add verification and success criteria
+</step>
+
+<step name="cleanup_spike">
+- Archive spike artifacts
+- Proceed with formal execution
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Spike completed and learnings documented
+- [ ] Formal plans derived from spike
+- [ ] Ready for normal execution
+</success_criteria>
+```
+
+## Common Workflow Patterns
+
+**Sequential execution:**
+```xml
+<step name="a">...</step>
+<step name="b">Depends on step a results...</step>
+<step name="c">Depends on step b results...</step>
+```
+
+**Parallel steps:**
+```xml
+<step name="research_a" parallel="true">...</step>
+<step name="research_b" parallel="true">...</step>
+<step name="synthesize">Combines a and b...</step>
+```
+
+**Loop pattern:**
+```xml
+<step name="iterate">
+For each {item}:
+1. Process item
+2. Check result
+3. Continue or break
+
+Loop until condition met.
+</step>
+```
+
+**Decision gate:**
+```xml
+<step name="decision_gate">
+Present options via AskUserQuestion.
+Route to appropriate next step based on choice.
+</step>
+```
+
+</workflow_structure>

package/get-shit-done/skills/gsd-extend/templates/agent-template.md

@@ -0,0 +1,234 @@
+---
+name: agent-template
+description: Template for creating custom agent extensions
+used_by:
+  - create-agent
+placeholders:
+  - name
+  - description
+  - tools
+  - color
+  - spawn_from
+  - role
+  - expertise
+  - execution_flow
+  - output_format
+  - success_criteria
+---
+
+<template>
+
+```yaml
+---
+name: {name}
+description: {description}
+tools: [{tools}]
+color: {color}
+spawn_from: [{spawn_from}]
+---
+```
+
+```xml
+<role>
+{role}
+</role>
+
+<expertise>
+{expertise}
+</expertise>
+
+<execution_flow>
+
+{execution_flow}
+
+</execution_flow>
+
+<output_format>
+{output_format}
+</output_format>
+
+<success_criteria>
+{success_criteria}
+</success_criteria>
+```
+
+</template>
+
+<guidelines>
+
+## How to Fill This Template
+
+**{name}:** kebab-case identifier, role-based (e.g., `security-auditor`, `api-documenter`)
+
+**{description}:** One sentence describing what this agent does and when to spawn it
+
+**{tools}:** Array of tools this agent needs. Choose minimum necessary:
+- Read-only: `[Read, Grep, Glob]`
+- Code modification: `[Read, Write, Edit, Bash, Grep, Glob]`
+- Research: `[Read, Grep, Glob, WebFetch, WebSearch]`
+- Docs lookup: `[Read, mcp__context7__*]`
+
+**{color}:** Terminal output color: green, yellow, red, blue, cyan, magenta
+
+**{spawn_from}:** Array of operations that can spawn this agent:
+- `plan-phase`, `execute-plan`, `execute-phase`, `verify-phase`, `custom`
+
+**{role}:** 3-5 sentences defining:
+- What the agent is ("You are a...")
+- What it does
+- What triggers it
+- Its primary responsibility
+
+**{expertise}:** Domain knowledge the agent needs:
+- Key concepts
+- Patterns to look for
+- Best practices
+- Common issues
+
+**{execution_flow}:** Series of `<step>` elements defining how the agent works:
+- understand_context: Parse input
+- perform_task: Core work
+- produce_output: Generate results
+
+**{output_format}:** Structured format for agent's return value
+
+**{success_criteria}:** Markdown checklist of completion criteria
+
+</guidelines>
+
+<examples>
+
+## Good Example
+
+```yaml
+---
+name: performance-profiler
+description: Analyzes code for performance bottlenecks and optimization opportunities
+tools: [Read, Grep, Glob, Bash]
+color: yellow
+spawn_from: [verify-phase, custom]
+---
+```
+
+```xml
+<role>
+You are a performance profiler. You analyze code for performance bottlenecks
+and optimization opportunities.
+
+You are spawned during verification or on-demand to review code efficiency.
+
+Your job: Identify slow patterns, memory leaks, unnecessary computations, and
+provide actionable optimization recommendations.
+</role>
+
+<expertise>
+## Performance Analysis
+
+**Database queries:**
+- N+1 queries (use includes/joins)
+- Missing indexes on queried columns
+- Over-fetching (select only needed columns)
+
+**Memory:**
+- Large objects in memory
+- Memory leaks in closures
+- Unbounded arrays/caches
+
+**Computation:**
+- Redundant calculations
+- Missing memoization
+- Blocking operations in hot paths
+
+**Patterns to grep:**
+```bash
+# N+1 pattern
+grep -n "for.*await.*find" $FILE
+
+# Memory accumulation
+grep -n "push.*loop\|concat.*map" $FILE
+```
+</expertise>
+
+<execution_flow>
+
+<step name="identify_hot_paths">
+Find performance-critical code:
+- API route handlers
+- Data processing functions
+- Rendering logic
+- Frequently called utilities
+</step>
+
+<step name="analyze_patterns">
+For each hot path:
+1. Check for N+1 queries
+2. Look for redundant computations
+3. Identify memory accumulation
+4. Check async patterns
+</step>
+
+<step name="generate_recommendations">
+For each finding:
+- Severity (critical, high, medium, low)
+- Current code snippet
+- Recommended fix
+- Expected improvement
+</step>
+
+</execution_flow>
+
+<output_format>
+## PERFORMANCE_ANALYSIS
+
+**Files analyzed:** {count}
+**Issues found:** {count by severity}
+
+### Critical Issues
+
+| File | Line | Issue | Recommendation |
+|------|------|-------|----------------|
+| path | N | description | fix |
+
+### High Priority
+
+...
+
+### Optimization Opportunities
+
+1. {opportunity with expected impact}
+2. {opportunity}
+
+### Summary
+
+{Overall assessment and top 3 recommendations}
+</output_format>
+
+<success_criteria>
+- [ ] Hot paths identified
+- [ ] Each path analyzed for common issues
+- [ ] Findings categorized by severity
+- [ ] Recommendations are actionable
+- [ ] Expected improvements noted
+</success_criteria>
+```
+
+## Bad Example
+
+```yaml
+---
+name: helper
+description: Helps with stuff
+tools: [Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch]
+---
+```
+
+Problems:
+- Name is too generic
+- Description is vague
+- Too many tools (grants everything)
+- No spawn_from defined
+- No role or expertise
+- No execution flow
+- No output format
+
+</examples>

package/get-shit-done/skills/gsd-extend/templates/reference-template.md

@@ -0,0 +1,239 @@
+---
+name: reference-template
+description: Template for creating custom reference extensions
+used_by:
+  - create-reference
+placeholders:
+  - name
+  - description
+  - load_when
+  - auto_load_for
+  - topic
+  - overview
+  - core_concepts
+  - patterns
+  - anti_patterns
+  - quick_reference
+---
+
+<template>
+
+```yaml
+---
+name: {name}
+description: {description}
+load_when:
+  - {keywords}
+auto_load_for:
+  - {operations}
+---
+```
+
+```xml
+<{topic}>
+
+## Overview
+
+{overview}
+
+## Core Concepts
+
+{core_concepts}
+
+## Patterns
+
+{patterns}
+
+## Anti-Patterns
+
+{anti_patterns}
+
+## Quick Reference
+
+{quick_reference}
+
+</{topic}>
+```
+
+</template>
+
+<guidelines>
+
+## How to Fill This Template
+
+**{name}:** kebab-case identifier (e.g., `react-patterns`, `stripe-integration`)
+
+**{description}:** One sentence describing what knowledge this provides
+
+**{load_when}:** Array of keywords that trigger loading:
+- Technology names: `react`, `prisma`, `stripe`
+- Concepts: `authentication`, `payments`, `api`
+- File patterns: `*.tsx`, `route.ts`
+- `always` for universal loading (use sparingly)
+
+**{auto_load_for}:** Array of operations to auto-load for:
+- `plan-phase` - Load during planning
+- `execute-plan` - Load during execution
+- `verify-phase` - Load during verification
+- `[]` for no auto-loading
+
+**{topic}:** XML tag name matching the knowledge domain (e.g., `react_patterns`)
+
+**{overview}:** 2-3 sentences summarizing this knowledge area
+
+**{core_concepts}:** Key concepts explained with:
+- Subsections for each concept
+- Key points as bullets
+- Code examples where helpful
+
+**{patterns}:** Recommended approaches with:
+- When to use each pattern
+- Implementation examples
+- Common mistakes to avoid
+
+**{anti_patterns}:** What NOT to do with:
+- Problem description
+- Why it happens
+- Better approach
+
+**{quick_reference}:** Cheat sheet table of terms and definitions
+
+</guidelines>
+
+<examples>
+
+## Good Example
+
+```yaml
+---
+name: prisma-patterns
+description: Prisma ORM patterns and best practices for this project
+load_when:
+  - prisma
+  - database
+  - schema
+  - model
+  - db
+auto_load_for: []
+---
+```
+
+```xml
+<prisma_patterns>
+
+## Overview
+
+This project uses Prisma as the ORM. All database access goes through Prisma
+Client. Schema is in `prisma/schema.prisma`.
+
+## Core Concepts
+
+### Schema Organization
+
+Models are grouped by domain in schema.prisma:
+- User and auth models together
+- Content models together
+- System/config models at the end
+
+**Naming:**
+- Models: PascalCase singular (User, not Users)
+- Fields: camelCase
+- Relations: named descriptively (author, posts)
+
+### Migrations
+
+```bash
+# Development: push without migration
+npx prisma db push
+
+# Production: create migration
+npx prisma migrate dev --name description
+```
+
+## Patterns
+
+### Eager Loading
+
+**When to use:** Need related data in same request
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id },
+  include: {
+    posts: true,
+    profile: true,
+  },
+});
+```
+
+### Transaction
+
+**When to use:** Multiple writes that must succeed together
+
+```typescript
+await prisma.$transaction([
+  prisma.user.update({ ... }),
+  prisma.audit.create({ ... }),
+]);
+```
+
+## Anti-Patterns
+
+### N+1 Queries
+
+**Problem:** Fetching related data in a loop
+
+```typescript
+// BAD
+const users = await prisma.user.findMany();
+for (const user of users) {
+  const posts = await prisma.post.findMany({ where: { authorId: user.id } });
+}
+```
+
+**Better:**
+```typescript
+const users = await prisma.user.findMany({
+  include: { posts: true },
+});
+```
+
+### Raw Queries for Simple Operations
+
+**Problem:** Using $queryRaw when Prisma methods work
+
+**Better:** Use Prisma Client methods. They're type-safe and handle escaping.
+
+## Quick Reference
+
+| Operation | Method |
+|-----------|--------|
+| Find one | `findUnique`, `findFirst` |
+| Find many | `findMany` |
+| Create | `create`, `createMany` |
+| Update | `update`, `updateMany` |
+| Delete | `delete`, `deleteMany` |
+| Count | `count` |
+
+</prisma_patterns>
+```
+
+## Bad Example
+
+```yaml
+---
+name: database
+description: Database stuff
+load_when:
+  - always
+---
+```
+
+Problems:
+- Name too generic
+- Description vague
+- `always` load is wasteful
+- No actual content
+- No patterns or examples
+
+</examples>