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

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

@@ -0,0 +1,370 @@
+<template_structure>
+
+## Template Extensions
+
+Templates define consistent output structures for artifacts. They're used by workflows and agents to produce standardized documents.
+
+## Required Frontmatter
+
+```yaml
+---
+name: template-name
+description: What this template produces
+used_by:
+  - workflow-name      # Workflows that use this template
+  - agent-name         # Agents that use this template
+placeholders:
+  - name               # List of placeholders in template
+  - description        # Helps users understand what to provide
+  - date
+---
+```
+
+## Template Body Structure
+
+```xml
+<template>
+
+# {title}
+
+**Created:** {date}
+**Author:** {author}
+
+## Section One
+
+{section_one_content}
+
+## Section Two
+
+| Column A | Column B |
+|----------|----------|
+| {row1_a} | {row1_b} |
+| {row2_a} | {row2_b} |
+
+## Section Three
+
+{section_three_content}
+
+---
+*Generated by GSD*
+
+</template>
+
+<guidelines>
+
+## How to Fill This Template
+
+**{title}:** Short descriptive title
+
+**{date}:** ISO format (YYYY-MM-DD)
+
+**{section_one_content}:**
+- Include X, Y, Z
+- Format as bullets or prose
+- Length: 2-5 sentences
+
+...
+
+</guidelines>
+
+<examples>
+
+## Good Example
+
+```markdown
+# Authentication Implementation
+
+**Created:** 2025-01-26
+**Author:** Claude
+
+## Overview
+
+JWT-based authentication with refresh token rotation...
+```
+
+## Bad Example
+
+```markdown
+# Auth
+
+**Created:** today
+
+## Overview
+
+Did auth stuff.
+```
+
+The bad example is too vague and doesn't follow formatting guidelines.
+
+</examples>
+```
+
+## Placeholder Syntax
+
+Templates use curly braces for placeholders:
+
+```
+{placeholder_name}
+```
+
+Placeholders can have defaults:
+
+```
+{placeholder_name|default_value}
+```
+
+Placeholders can be conditional:
+
+```
+{?optional_section}
+Content that only appears if optional_section is provided.
+{/optional_section}
+```
+
+## Template Usage
+
+Templates are used via @-reference:
+
+```xml
+<output>
+Create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
+Use template: @~/.claude/gsd-extensions/templates/my-summary.md
+</output>
+```
+
+The executor:
+1. Loads template
+2. Fills placeholders with actual values
+3. Writes resulting document
+
+## Example: API Documentation Template
+
+```yaml
+---
+name: api-endpoint-doc
+description: Documentation template for API endpoints
+used_by:
+  - execute-plan
+placeholders:
+  - endpoint_path
+  - method
+  - description
+  - request_body
+  - response_body
+  - error_codes
+---
+```
+
+```xml
+<template>
+
+# {method} {endpoint_path}
+
+{description}
+
+## Request
+
+**Method:** {method}
+**Path:** {endpoint_path}
+**Authentication:** {auth_required|Required}
+
+### Headers
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| Authorization | {auth_required|Yes} | Bearer token |
+| Content-Type | Yes | application/json |
+
+### Body
+
+```json
+{request_body}
+```
+
+### Parameters
+
+{?path_params}
+**Path Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+{path_params}
+{/path_params}
+
+{?query_params}
+**Query Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+{query_params}
+{/query_params}
+
+## Response
+
+### Success (200)
+
+```json
+{response_body}
+```
+
+### Errors
+
+| Code | Description |
+|------|-------------|
+{error_codes}
+
+## Example
+
+### Request
+
+```bash
+curl -X {method} \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{request_body}' \
+  https://api.example.com{endpoint_path}
+```
+
+### Response
+
+```json
+{response_body}
+```
+
+</template>
+
+<guidelines>
+
+## Filling This Template
+
+**{endpoint_path}:** Full path including parameters (e.g., `/api/users/:id`)
+
+**{method}:** HTTP method (GET, POST, PUT, PATCH, DELETE)
+
+**{description}:** 1-2 sentences describing what the endpoint does
+
+**{request_body}:** JSON example of request body (or "N/A" for GET)
+
+**{response_body}:** JSON example of successful response
+
+**{error_codes}:** Table rows of error codes and descriptions
+
+</guidelines>
+```
+
+## Example: Phase Summary Template (Override)
+
+Override the built-in summary template:
+
+```yaml
+---
+name: summary
+description: Custom phase summary format for this project
+used_by:
+  - execute-plan
+placeholders:
+  - phase
+  - plan
+  - objective
+  - accomplishments
+  - decisions
+  - next_steps
+---
+```
+
+```xml
+<template>
+
+---
+phase: {phase}
+plan: {plan}
+completed: {date}
+duration: {duration}
+---
+
+# Phase {phase} Plan {plan}: {title}
+
+> {one_liner}
+
+## What We Built
+
+{accomplishments}
+
+## Technical Decisions
+
+| Decision | Why | Impact |
+|----------|-----|--------|
+{decisions}
+
+## Files Changed
+
+**Created:**
+{files_created}
+
+**Modified:**
+{files_modified}
+
+## What's Next
+
+{next_steps}
+
+## Verification
+
+- [x] All tasks complete
+- [x] Tests pass
+- [x] Code reviewed
+
+---
+*Plan completed {date}*
+
+</template>
+
+<guidelines>
+
+## Filling This Template
+
+**{one_liner}:** Substantive summary (not "Authentication implemented")
+- Good: "JWT auth with refresh rotation using jose library"
+- Bad: "Did auth"
+
+**{accomplishments}:** Bullet list of what was actually built
+- Be specific about functionality
+- Include relevant technical details
+
+**{decisions}:** Table of architectural/technical decisions made
+- Include WHY, not just WHAT
+- Note impact on future work
+
+</guidelines>
+```
+
+## Template Best Practices
+
+**1. Clear placeholders**
+Name placeholders descriptively. `{user_name}` not `{x}`.
+
+**2. Include guidelines**
+Template users need to know what goes in each placeholder.
+
+**3. Provide examples**
+Show good vs bad filled templates.
+
+**4. Use conditional sections**
+Templates should handle optional content gracefully.
+
+**5. Match existing patterns**
+If extending built-in templates, maintain similar structure.
+
+**6. Document usage**
+Note which workflows/agents use this template.
+
+## Template Discovery
+
+GSD discovers templates by:
+
+1. Checking `@` references in workflow/agent files
+2. Scanning template directories for matches
+
+Templates are NOT auto-loaded. They must be explicitly referenced.
+
+</template_structure>

package/get-shit-done/skills/gsd-extend/references/validation-rules.md

@@ -0,0 +1,140 @@
+<validation_rules>
+
+## Extension Validation
+
+All extensions are validated before activation. Invalid extensions are skipped with warning.
+
+## Common Validation Rules
+
+**1. YAML Frontmatter**
+
+Must be valid YAML between `---` markers:
+```yaml
+---
+name: kebab-case-name
+description: One sentence description
+# type-specific fields...
+---
+```
+
+**2. Required Fields by Type**
+
+| Type | Required Fields |
+|------|-----------------|
+| Workflow | name, description, triggers |
+| Agent | name, description, tools, spawn_from |
+| Reference | name, description, load_when |
+| Template | name, description, used_by |
+
+**3. Name Validation**
+
+- Must be kebab-case: `my-extension-name`
+- Must match filename (without .md)
+- No spaces or special characters
+- 3-50 characters
+
+**4. XML Structure**
+
+If extension uses XML tags:
+- Tags must be properly closed
+- Nesting must be balanced
+- No malformed tags
+
+## Type-Specific Validation
+
+### Workflows
+
+```yaml
+triggers:
+  - plan-phase        # valid
+  - execute-plan      # valid
+  - execute-phase     # valid
+  - verify-phase      # valid
+  - custom            # valid
+  - invalid-trigger   # INVALID
+```
+
+**Must have:**
+- At least one valid trigger
+- `<process>` section with `<step>` elements
+- `<success_criteria>` section
+
+### Agents
+
+```yaml
+tools:
+  - Read              # valid
+  - Write             # valid
+  - Edit              # valid
+  - Bash              # valid
+  - Grep              # valid
+  - Glob              # valid
+  - WebFetch          # valid
+  - WebSearch         # valid
+  - mcp__context7__*  # valid (MCP tools)
+  - InvalidTool       # INVALID
+```
+
+**Must have:**
+- At least one valid tool
+- `<role>` section
+- `<output_format>` section
+
+### References
+
+```yaml
+load_when:
+  - keyword           # valid - loads when keyword appears
+  - "*-auth-*"        # valid - glob pattern
+  - always            # valid - always loads (use sparingly)
+  - ""                # INVALID - empty keyword
+```
+
+**Must have:**
+- At least one load_when keyword
+- Content body (not empty)
+
+### Templates
+
+```yaml
+used_by:
+  - workflow-name     # should reference real workflow
+  - agent-name        # should reference real agent
+```
+
+**Must have:**
+- `<template>` section with actual template content
+- `<guidelines>` section explaining placeholders
+
+## Validation Commands
+
+```bash
+# Validate a single extension
+/gsd:extend validate {path}
+
+# Validate all extensions
+/gsd:extend validate --all
+```
+
+## Error Messages
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "Invalid YAML frontmatter" | Malformed YAML | Check indentation and syntax |
+| "Missing required field: {field}" | Field not present | Add the required field |
+| "Invalid trigger: {trigger}" | Unknown trigger name | Use valid trigger name |
+| "Invalid tool: {tool}" | Unknown tool name | Use valid tool name |
+| "Unbalanced XML tags" | Missing closing tag | Close all opened tags |
+| "Name doesn't match filename" | name: foo but file is bar.md | Make them match |
+
+## Self-Validation
+
+Extensions should self-validate by:
+
+1. Including comprehensive examples
+2. Testing with real usage
+3. Documenting edge cases
+
+Good extension authors test their extensions before sharing.
+
+</validation_rules>