get-shit-done-cc 1.0.0

package/get-shit-done/templates/research-prompt.md

@@ -0,0 +1,133 @@
+# Research Prompt Template
+
+For phases requiring research before planning:
+
+```markdown
+---
+phase: XX-name
+type: research
+topic: [research-topic]
+---
+
+<session_initialization>
+Before beginning research, verify today's date:
+!`date +%Y-%m-%d`
+
+Use this date when searching for "current" or "latest" information.
+Example: If today is 2025-11-22, search for "2025" not "2024".
+</session_initialization>
+
+<research_objective>
+Research [topic] to inform [phase name] implementation.
+
+Purpose: [What decision/implementation this enables]
+Scope: [Boundaries]
+Output: FINDINGS.md with structured recommendations
+</research_objective>
+
+<research_scope>
+<include>
+- [Question to answer]
+- [Area to investigate]
+- [Specific comparison if needed]
+</include>
+
+<exclude>
+- [Out of scope for this research]
+- [Defer to implementation phase]
+</exclude>
+</research_scope>
+
+<research_protocol>
+
+**Source Priority:**
+1. **Context7 MCP** - For library/framework documentation (current, authoritative)
+2. **Official Docs** - For platform-specific or non-indexed libraries
+3. **WebSearch** - For comparisons, trends, community patterns (verify all findings)
+
+**Quality Checklist:**
+Before completing research, verify:
+- [ ] All claims have authoritative sources (Context7 or official docs)
+- [ ] Negative claims ("X is not possible") verified with official documentation
+- [ ] API syntax/configuration from Context7 or official docs (never WebSearch alone)
+- [ ] WebSearch findings cross-checked with authoritative sources
+- [ ] Recent updates/changelogs checked for breaking changes
+- [ ] Alternative approaches considered (not just first solution found)
+
+**Confidence Levels:**
+- HIGH: Context7 or official docs confirm
+- MEDIUM: WebSearch + Context7/official docs confirm
+- LOW: WebSearch only or training knowledge only (mark for validation)
+
+</research_protocol>
+
+
+<output_structure>
+Create `.planning/phases/XX-name/FINDINGS.md`:
+
+```markdown
+# [Topic] Research Findings
+
+## Summary
+[2-3 paragraph executive summary - what was researched, what was found, what's recommended]
+
+## Primary Recommendation
+[What to do and why - be specific and actionable]
+
+## Alternatives Considered
+[What else was evaluated and why not chosen]
+
+## Key Findings
+
+### [Category 1]
+- [Finding with source URL and relevance to our case]
+
+### [Category 2]
+- [Finding with source URL and relevance]
+
+## Code Examples
+[Relevant implementation patterns, if applicable]
+
+## Metadata
+
+<metadata>
+<confidence level="high|medium|low">
+[Why this confidence level - based on source quality and verification]
+</confidence>
+
+<sources>
+- [Primary authoritative sources used]
+</sources>
+
+<open_questions>
+[What couldn't be determined or needs validation during implementation]
+</open_questions>
+
+<validation_checkpoints>
+[If confidence is LOW or MEDIUM, list specific things to verify during implementation]
+</validation_checkpoints>
+</metadata>
+```
+</output_structure>
+
+<success_criteria>
+- All scope questions answered with authoritative sources
+- Quality checklist items completed
+- Clear primary recommendation
+- Low-confidence findings marked with validation checkpoints
+- Ready to inform PLAN.md creation
+</success_criteria>
+
+<guidelines>
+**When to use research prompts:**
+- Technology choice unclear
+- Best practices needed for unfamiliar domain
+- API/library investigation required
+- Architecture decision pending
+- Multiple valid approaches exist
+
+**When NOT to use:**
+- Established patterns (CRUD, auth with known library)
+- Implementation details (defer to execution)
+- Questions answerable from existing project context
+</guidelines>

package/get-shit-done/templates/roadmap.md

@@ -0,0 +1,196 @@
+# Roadmap Template
+
+Template for `.planning/ROADMAP.md`.
+
+## Initial Roadmap (v1.0 Greenfield)
+
+```markdown
+# Roadmap: [Project Name]
+
+## Overview
+
+[One paragraph describing the journey from start to finish]
+
+## Domain Expertise
+
+[Paths to domain skills that inform planning. These SKILL.md files serve as indexes - during phase planning, read them to find relevant references for each phase type.]
+
+- ~/.claude/skills/expertise/[domain]/SKILL.md
+[Add additional domains if project spans multiple (e.g., ISF shaders + macOS app)]
+
+Or: None
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [ ] **Phase 1: [Name]** - [One-line description]
+- [ ] **Phase 2: [Name]** - [One-line description]
+- [ ] **Phase 3: [Name]** - [One-line description]
+- [ ] **Phase 4: [Name]** - [One-line description]
+
+## Phase Details
+
+### Phase 1: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Nothing (first phase)
+**Research**: Unlikely (established patterns)
+**Plans**: [Number of plans, e.g., "3 plans" or "TBD"]
+
+Plans:
+- [ ] 01-01: [Brief description of first plan]
+- [ ] 01-02: [Brief description of second plan]
+- [ ] 01-03: [Brief description of third plan]
+
+### Phase 2: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 1
+**Research**: Likely (new integration)
+**Research topics**: [What needs investigating]
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 02-01: [Brief description]
+- [ ] 02-02: [Brief description]
+
+### Phase 2.1: Critical Fix (INSERTED)
+**Goal**: [Urgent work inserted between phases]
+**Depends on**: Phase 2
+**Plans**: 1 plan
+
+Plans:
+- [ ] 2.1-01: [Description]
+
+### Phase 3: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 2
+**Research**: Likely (external API)
+**Research topics**: [What needs investigating]
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 03-01: [Brief description]
+- [ ] 03-02: [Brief description]
+
+### Phase 4: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 3
+**Research**: Unlikely (internal patterns)
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 04-01: [Brief description]
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. [Name] | 0/3 | Not started | - |
+| 2. [Name] | 0/2 | Not started | - |
+| 3. [Name] | 0/2 | Not started | - |
+| 4. [Name] | 0/1 | Not started | - |
+```
+
+<guidelines>
+**Initial planning (v1.0):**
+- 3-6 phases total (more = scope creep)
+- Each phase delivers something coherent
+- Phases can have 1+ plans (split if >3 tasks or multiple subsystems)
+- Plans use naming: {phase}-{plan}-PLAN.md (e.g., 01-02-PLAN.md)
+- No time estimates (this isn't enterprise PM)
+- Progress table updated by execute workflow
+- Plan count can be "TBD" initially, refined during planning
+
+**Research flags:**
+- `Research: Likely` - External APIs, new libraries, architectural decisions
+- `Research: Unlikely` - Internal patterns, CRUD operations, established conventions
+- Include `Research topics:` when Likely
+- Flags are hints, not mandates - validate at planning time
+
+**After milestones ship:**
+- Collapse completed milestones in `<details>` tags
+- Add new milestone sections for upcoming work
+- Keep continuous phase numbering (never restart at 01)
+</guidelines>
+
+<status_values>
+- `Not started` - Haven't begun
+- `In progress` - Currently working
+- `Complete` - Done (add completion date)
+- `Deferred` - Pushed to later (with reason)
+</status_values>
+
+## Milestone-Grouped Roadmap (After v1.0 Ships)
+
+After completing first milestone, reorganize with milestone groupings:
+
+```markdown
+# Roadmap: [Project Name]
+
+## Milestones
+
+- ✅ **v1.0 MVP** - Phases 1-4 (shipped YYYY-MM-DD)
+- 🚧 **v1.1 [Name]** - Phases 5-6 (in progress)
+- 📋 **v2.0 [Name]** - Phases 7-10 (planned)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
+
+### Phase 1: [Name]
+**Goal**: [What this phase delivers]
+**Plans**: 3 plans
+
+Plans:
+- [x] 01-01: [Brief description]
+- [x] 01-02: [Brief description]
+- [x] 01-03: [Brief description]
+
+[... remaining v1.0 phases ...]
+
+</details>
+
+### 🚧 v1.1 [Name] (In Progress)
+
+**Milestone Goal:** [What v1.1 delivers]
+
+#### Phase 5: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 4
+**Plans**: 2 plans
+
+Plans:
+- [ ] 05-01: [Brief description]
+- [ ] 05-02: [Brief description]
+
+[... remaining v1.1 phases ...]
+
+### 📋 v2.0 [Name] (Planned)
+
+**Milestone Goal:** [What v2.0 delivers]
+
+[... v2.0 phases ...]
+
+## Progress
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 1. Foundation | v1.0 | 3/3 | Complete | YYYY-MM-DD |
+| 2. Features | v1.0 | 2/2 | Complete | YYYY-MM-DD |
+| 5. Security | v1.1 | 0/2 | Not started | - |
+```
+
+**Notes:**
+- Milestone emoji: ✅ shipped, 🚧 in progress, 📋 planned
+- Completed milestones collapsed in `<details>` for readability
+- Current/future milestones expanded
+- Continuous phase numbering (01-99)
+- Progress table includes milestone column

package/get-shit-done/templates/state.md

@@ -0,0 +1,226 @@
+# State Template
+
+Template for `.planning/STATE.md` - the project's living memory.
+
+---
+
+## File Template
+
+```markdown
+# Project State
+
+## Project Summary
+[IMMUTABLE - Copy verbatim from PROJECT.md on creation. Never edit this section.]
+
+**Building:** [One-liner from project vision]
+
+**Core requirements:**
+- [Requirement 1]
+- [Requirement 2]
+- [Requirement 3]
+
+**Constraints:**
+- [Key constraint 1]
+- [Key constraint 2]
+
+## Current Position
+
+Phase: [X] of [Y] ([Phase name])
+Plan: [A] of [B] in current phase
+Status: [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
+Last activity: [YYYY-MM-DD] - [What happened]
+
+Progress: [░░░░░░░░░░] 0%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: [N]
+- Average duration: [X] min
+- Total execution time: [X.X] hours
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| - | - | - | - |
+
+**Recent Trend:**
+- Last 5 plans: [durations]
+- Trend: [Improving / Stable / Degrading]
+
+*Updated after each plan completion*
+
+## Accumulated Context
+
+### Decisions Made
+
+| Phase | Decision | Rationale |
+|-------|----------|-----------|
+| - | - | - |
+
+### Deferred Issues
+
+[From ISSUES.md - list open items with phase of origin]
+
+None yet.
+
+### Blockers/Concerns Carried Forward
+
+[From prior "Next Phase Readiness" sections - issues that affect future work]
+
+None yet.
+
+## Project Alignment
+
+Last checked: [Date or "Project start"]
+Status: [✓ Aligned / ⚠️ Drift detected / ✗ Misaligned]
+Assessment: [One line summary]
+Drift notes: [Details if drift detected, otherwise "None"]
+
+## Session Continuity
+
+Last session: [YYYY-MM-DD HH:MM]
+Stopped at: [Description of last completed action]
+Resume file: [Path to .continue-here*.md if exists, otherwise "None"]
+```
+
+<purpose>
+STATE.md is the project's "short-term memory" that spans all phases and sessions.
+
+**Problem it solves:** Information is captured in summaries, issues, and decisions - but not systematically consumed. Each phase plans in isolation. Sessions start without knowing accumulated context.
+
+**Solution:** A single, small file that's:
+- Always read first (every workflow)
+- Always updated after work (every execution)
+- Contains digest of all accumulated wisdom
+- Enables instant context restoration
+</purpose>
+
+<lifecycle>
+
+**Creation:** After ROADMAP.md is created (during init)
+- Copy Project Summary from PROJECT.md (immutable after this)
+- Initialize empty accumulated context sections
+- Set position to "Phase 1 ready to plan"
+
+**Reading:** First step of EVERY workflow
+- progress: Present status to user
+- plan: Inform planning decisions
+- execute: Know current position
+- transition: Know what's complete
+
+**Writing:** After every significant action
+- execute: After SUMMARY.md created
+  - Update position (phase, plan, status)
+  - Extract decisions → add to table
+  - Extract new issues → update deferred list
+  - Extract concerns → add to blockers
+- transition: After phase marked complete
+  - Update progress bar
+  - Clear resolved blockers
+- alignment-check: After verification
+  - Update alignment status
+
+</lifecycle>
+
+<sections>
+
+### Project Summary (Immutable)
+Copied from PROJECT.md on project initialization. Never edited afterward.
+Provides constant reference to "what are we building" without re-reading full project doc.
+
+### Current Position
+Where we are right now:
+- Phase X of Y - which phase
+- Plan A of B - which plan within phase
+- Status - current state
+- Last activity - what happened most recently
+- Progress bar - visual indicator of overall completion
+
+Progress calculation: (completed plans) / (total plans across all phases) × 100%
+
+### Performance Metrics
+Track velocity to understand execution patterns:
+- Total plans completed
+- Average duration per plan
+- Per-phase breakdown
+- Recent trend (improving/stable/degrading)
+
+Updated after each plan completion.
+
+### Accumulated Context
+
+**Decisions Made:** Table of significant decisions with rationale.
+- Extracted from SUMMARY.md "Decisions Made" sections
+- Include phase number for traceability
+- These constrain future phases (e.g., "use jose not jsonwebtoken")
+
+**Deferred Issues:** Open items from ISSUES.md
+- Brief description with ISS-XXX number
+- Phase where discovered
+- Effort estimate if known
+- Helps phase planning identify what to address
+
+**Blockers/Concerns:** From "Next Phase Readiness" sections
+- Issues that affect future work
+- Prefix with originating phase
+- Cleared when addressed
+
+### Project Alignment
+Tracks whether work matches original requirements:
+- ✓ Aligned: On track
+- ⚠️ Drift: Scope creeping or diverging
+- ✗ Misaligned: Work doesn't serve project goals
+
+Updated after each phase completion.
+
+### Session Continuity
+Enables instant resumption:
+- When was last session
+- What was last completed
+- Is there a .continue-here file to resume from
+
+</sections>
+
+<size_constraint>
+Keep STATE.md under 150 lines.
+
+It's a DIGEST, not an archive. If accumulated context grows too large:
+- Summarize older phase decisions: "Phases 1-2: [key decisions]"
+- Reference ISSUES.md instead of listing all: "12 open issues - see ISSUES.md"
+- Keep only active blockers, archive resolved ones
+
+The goal is "read once, know everything" - if it's too long, that fails.
+</size_constraint>
+
+<guidelines>
+**When created:**
+- During project initialization (after ROADMAP.md)
+- Copy Project Summary from PROJECT.md (never edit this section after creation)
+- Initialize empty sections
+
+**When read:**
+- EVERY workflow starts by reading STATE.md
+- Provides instant context restoration
+- Shows current position and accumulated wisdom
+
+**When updated:**
+- After each plan execution (update position, extract decisions/issues/blockers)
+- After phase transitions (update progress bar, clear resolved blockers)
+- After alignment checks (update alignment status)
+
+**Size management:**
+- Keep under 150 lines total
+- Summarize older decisions if table grows large
+- Reference ISSUES.md instead of listing all issues
+- Keep only active blockers, archive resolved ones
+
+**Sections:**
+- Project Summary: Immutable project overview
+- Current Position: Where we are now (phase, plan, status)
+- Performance Metrics: Velocity tracking
+- Accumulated Context: Decisions, deferred issues, blockers
+- Project Alignment: Are we on track with original vision?
+- Session Continuity: Resume information
+</guidelines>