get-shit-done-cc 1.0.0

package/get-shit-done/workflows/research-phase.md

@@ -0,0 +1,293 @@
+<purpose>
+Execute discovery/research at the appropriate depth level.
+Produces FINDINGS.md (for Level 2-3) that informs PLAN.md creation.
+
+Called from plan-phase.md's mandatory_discovery step with a depth parameter.
+</purpose>
+
+<depth_levels>
+**This workflow supports three depth levels:**
+
+| Level | Name         | Time      | Output                                     | When                                      |
+| ----- | ------------ | --------- | ------------------------------------------ | ----------------------------------------- |
+| 1     | Quick Verify | 2-5 min   | No file, proceed with verified knowledge   | Single library, confirming current syntax |
+| 2     | Standard     | 15-30 min | FINDINGS.md                                | Choosing between options, new integration |
+| 3     | Deep Dive    | 1+ hour   | Detailed FINDINGS.md with validation gates | Architectural decisions, novel problems   |
+
+**Depth is determined by plan-phase.md before routing here.**
+</depth_levels>
+
+<source_hierarchy>
+**MANDATORY: Context7 BEFORE WebSearch**
+
+Claude's training data is 6-18 months stale. Always verify.
+
+1. **Context7 MCP FIRST** - Current docs, no hallucination
+2. **Official docs** - When Context7 lacks coverage
+3. **WebSearch LAST** - For comparisons and trends only
+
+See ~/.claude/get-shit-done/templates/research-prompt.md `<source_hierarchy>` for full protocol.
+</source_hierarchy>
+
+<process>
+
+<step name="determine_depth">
+Check the depth parameter passed from plan-phase.md:
+- `depth=verify` → Level 1 (Quick Verification)
+- `depth=standard` → Level 2 (Standard Research)
+- `depth=deep` → Level 3 (Deep Dive)
+
+Route to appropriate level workflow below.
+</step>
+
+<step name="level_1_quick_verify">
+**Level 1: Quick Verification (2-5 minutes)**
+
+For: Single known library, confirming syntax/version still correct.
+
+**Process:**
+
+1. Resolve library in Context7:
+
+   ```
+   mcp__context7__resolve-library-id with libraryName: "[library]"
+   ```
+
+2. Fetch relevant docs:
+
+   ```
+   mcp__context7__get-library-docs with:
+   - context7CompatibleLibraryID: [from step 1]
+   - topic: [specific concern]
+   ```
+
+3. Verify:
+
+   - Current version matches expectations
+   - API syntax unchanged
+   - No breaking changes in recent versions
+
+4. **If verified:** Return to plan-phase.md with confirmation. No FINDINGS.md needed.
+
+5. **If concerns found:** Escalate to Level 2.
+
+**Output:** Verbal confirmation to proceed, or escalation to Level 2.
+</step>
+
+<step name="level_2_standard">
+**Level 2: Standard Research (15-30 minutes)**
+
+For: Choosing between options, new external integration.
+
+**Process:**
+
+1. **Identify what to research:**
+
+   - What options exist?
+   - What are the key comparison criteria?
+   - What's our specific use case?
+
+2. **Context7 for each option:**
+
+   ```
+   For each library/framework:
+   - mcp__context7__resolve-library-id
+   - mcp__context7__get-library-docs (mode: "code" for API, "info" for concepts)
+   ```
+
+3. **Official docs** for anything Context7 lacks.
+
+4. **WebSearch** for comparisons:
+
+   - "[option A] vs [option B] {current_year}"
+   - "[option] known issues"
+   - "[option] with [our stack]"
+
+5. **Cross-verify:** Any WebSearch finding → confirm with Context7/official docs.
+
+6. **Quality check:** Before finalizing findings, consult ~/.claude/get-shit-done/references/research-pitfalls.md to avoid common research gaps.
+
+7. **Create FINDINGS.md** using ~/.claude/get-shit-done/templates/research-prompt.md structure:
+
+   - Summary with recommendation
+   - Key findings per option
+   - Code examples from Context7
+   - Confidence level (should be MEDIUM-HIGH for Level 2)
+
+8. Return to plan-phase.md.
+
+**Output:** `.planning/phases/XX-name/FINDINGS.md`
+</step>
+
+<step name="level_3_deep_dive">
+**Level 3: Deep Dive (1+ hour)**
+
+For: Architectural decisions, novel problems, high-risk choices.
+
+**Process:**
+
+1. **Scope the research** using ~/.claude/get-shit-done/templates/research-prompt.md:
+
+   - Create RESEARCH.md with clear scope
+   - Define include/exclude boundaries
+   - List specific questions to answer
+
+2. **Exhaustive Context7 research:**
+
+   - All relevant libraries
+   - Related patterns and concepts
+   - Multiple topics per library if needed
+
+3. **Official documentation deep read:**
+
+   - Architecture guides
+   - Best practices sections
+   - Migration/upgrade guides
+   - Known limitations
+
+4. **WebSearch for ecosystem context:**
+
+   - How others solved similar problems
+   - Production experiences
+   - Gotchas and anti-patterns
+   - Recent changes/announcements
+
+5. **Cross-verify ALL findings:**
+
+   - Every WebSearch claim → verify with authoritative source
+   - Mark what's verified vs assumed
+   - Flag contradictions
+
+6. **Quality check:** Before finalizing findings, consult ~/.claude/get-shit-done/references/research-pitfalls.md to ensure comprehensive coverage and avoid common research gaps.
+
+7. **Create comprehensive FINDINGS.md:**
+
+   - Full structure from ~/.claude/get-shit-done/templates/research-prompt.md
+   - Quality report with source attribution
+   - Confidence by finding
+   - If LOW confidence on any critical finding → add validation checkpoints
+
+8. **Confidence gate:** If overall confidence is LOW, present options before proceeding.
+
+9. Return to plan-phase.md.
+
+**Output:** `.planning/phases/XX-name/FINDINGS.md` (comprehensive)
+</step>
+
+<step name="identify_unknowns">
+**For Level 2-3:** Define what we need to learn.
+
+Ask: What do we need to learn before we can plan this phase?
+
+- Technology choices?
+- Best practices?
+- API patterns?
+- Architecture approach?
+  </step>
+
+<step name="create_research_prompt">
+Use ~/.claude/get-shit-done/templates/research-prompt.md.
+Write to `.planning/phases/XX-name/RESEARCH.md`
+
+Include:
+
+- Clear research objective
+- Scoped include/exclude lists
+- Source preferences (official docs, Context7, current year)
+- Output structure for FINDINGS.md
+  </step>
+
+<step name="execute_research">
+Run the research prompt:
+- Use web search for current info
+- Use Context7 MCP for library docs
+- Prefer current year sources
+- Structure findings per template
+</step>
+
+<step name="create_findings">
+Write `.planning/phases/XX-name/FINDINGS.md`:
+- Summary with recommendation
+- Key findings with sources
+- Code examples if applicable
+- Metadata (confidence, dependencies, open questions, assumptions)
+</step>
+
+<step name="confidence_gate">
+After creating FINDINGS.md, check confidence level.
+
+If confidence is LOW:
+Use AskUserQuestion:
+
+- header: "Low Confidence"
+- question: "Research confidence is LOW: [reason]. How would you like to proceed?"
+- options:
+  - "Dig deeper" - Do more research before planning
+  - "Proceed anyway" - Accept uncertainty, plan with caveats
+  - "Pause" - I need to think about this
+
+If confidence is MEDIUM:
+Inline: "Research complete (medium confidence). [brief reason]. Proceed to planning?"
+
+If confidence is HIGH:
+Proceed directly, just note: "Research complete (high confidence)."
+</step>
+
+<step name="open_questions_gate">
+If FINDINGS.md has open_questions:
+
+Present them inline:
+"Open questions from research:
+
+- [Question 1]
+- [Question 2]
+
+These may affect implementation. Acknowledge and proceed? (yes / address first)"
+
+If "address first": Gather user input on questions, update findings.
+</step>
+
+<step name="offer_next">
+```
+Research complete: .planning/phases/XX-name/FINDINGS.md
+Recommendation: [one-liner]
+Confidence: [level]
+
+What's next?
+
+1. Discuss phase context (/gsd:discuss-phase [current-phase])
+2. Create phase plan (/gsd:plan-phase [current-phase])
+3. Refine research (dig deeper)
+4. Review findings
+
+```
+
+NOTE: FINDINGS.md is NOT committed separately. It will be committed with phase completion.
+</step>
+
+</process>
+
+<success_criteria>
+**Level 1 (Quick Verify):**
+- Context7 consulted for library/topic
+- Current state verified or concerns escalated
+- Verbal confirmation to proceed (no files)
+
+**Level 2 (Standard):**
+- Context7 consulted for all options
+- WebSearch findings cross-verified
+- FINDINGS.md created with recommendation
+- Confidence level MEDIUM or higher
+- Ready to inform PLAN.md creation
+
+**Level 3 (Deep Dive):**
+- RESEARCH.md exists with clear scope
+- Context7 exhaustively consulted
+- All WebSearch findings verified against authoritative sources
+- FINDINGS.md created with comprehensive analysis
+- Quality report with source attribution
+- If LOW confidence findings → validation checkpoints defined
+- Confidence gate passed
+- Ready to inform PLAN.md creation
+</success_criteria>
+```

package/get-shit-done/workflows/resume-project.md

@@ -0,0 +1,248 @@
+<trigger>
+Use this workflow when:
+- Starting a new session on an existing project
+- User says "continue", "what's next", "where were we", "resume"
+- Any planning operation when .planning/ already exists
+- User returns after time away from project
+</trigger>
+
+<purpose>
+Instantly restore full project context and present clear status.
+Enables seamless session continuity for fully autonomous workflows.
+
+"Where were we?" should have an immediate, complete answer.
+</purpose>
+
+<process>
+
+<step name="detect_existing_project">
+Check if this is an existing project:
+
+```bash
+ls .planning/STATE.md 2>/dev/null && echo "Project exists"
+ls .planning/ROADMAP.md 2>/dev/null && echo "Roadmap exists"
+ls .planning/PROJECT.md 2>/dev/null && echo "Project file exists"
+```
+
+**If STATE.md exists:** Proceed to load_state
+**If only ROADMAP.md/PROJECT.md exist:** Offer to reconstruct STATE.md
+**If .planning/ doesn't exist:** This is a new project - route to /gsd:new-project
+</step>
+
+<step name="load_state">
+Read and parse STATE.md:
+
+```bash
+cat .planning/STATE.md
+```
+
+Extract:
+
+- **Brief Summary**: What we're building (immutable reminder)
+- **Current Position**: Phase X of Y, Plan A of B, Status
+- **Progress**: Visual progress bar
+- **Decisions Made**: Key decisions that constrain future work
+- **Deferred Issues**: Open items awaiting attention
+- **Blockers/Concerns**: Issues carried forward
+- **Brief Alignment**: Are we on track?
+- **Session Continuity**: Where we left off, any resume files
+  </step>
+
+<step name="check_incomplete_work">
+Look for incomplete work that needs attention:
+
+```bash
+# Check for continue-here files (mid-plan resumption)
+ls .planning/phases/*/.continue-here*.md 2>/dev/null
+
+# Check for plans without summaries (incomplete execution)
+for plan in .planning/phases/*/*-PLAN.md; do
+  summary="${plan/PLAN/SUMMARY}"
+  [ ! -f "$summary" ] && echo "Incomplete: $plan"
+done 2>/dev/null
+```
+
+**If .continue-here file exists:**
+
+- This is a mid-plan resumption point
+- Read the file for specific resumption context
+- Flag: "Found mid-plan checkpoint"
+
+**If PLAN without SUMMARY exists:**
+
+- Execution was started but not completed
+- Flag: "Found incomplete plan execution"
+  </step>
+
+<step name="present_status">
+Present complete project status to user:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PROJECT STATUS                                               ║
+╠══════════════════════════════════════════════════════════════╣
+║  Building: [one-liner from Brief Summary]                     ║
+║                                                               ║
+║  Phase: [X] of [Y] - [Phase name]                            ║
+║  Plan:  [A] of [B] - [Status]                                ║
+║  Progress: [██████░░░░] XX%                                  ║
+║                                                               ║
+║  Last activity: [date] - [what happened]                     ║
+╚══════════════════════════════════════════════════════════════╝
+
+[If incomplete work found:]
+⚠️  Incomplete work detected:
+    - [.continue-here file or incomplete plan]
+
+[If deferred issues exist:]
+📋 [N] deferred issues awaiting attention
+
+[If blockers exist:]
+⚠️  Carried concerns:
+    - [blocker 1]
+    - [blocker 2]
+
+[If alignment is not ✓:]
+⚠️  Brief alignment: [status] - [assessment]
+```
+
+</step>
+
+<step name="determine_next_action">
+Based on project state, determine the most logical next action:
+
+**If .continue-here file exists:**
+→ Primary: Resume from checkpoint
+→ Option: Start fresh on current plan
+
+**If incomplete plan (PLAN without SUMMARY):**
+→ Primary: Complete the incomplete plan
+→ Option: Abandon and move on
+
+**If phase in progress, all plans complete:**
+→ Primary: Transition to next phase
+→ Option: Review completed work
+
+**If phase ready to plan:**
+→ Check if CONTEXT.md exists for this phase:
+
+- If CONTEXT.md missing:
+  → Primary: Discuss phase context (gather objectives, constraints, success indicators)
+  → Secondary: Plan directly (skip context gathering)
+- If CONTEXT.md exists:
+  → Primary: Plan the phase
+  → Option: Review roadmap
+
+**If phase ready to execute:**
+→ Primary: Execute next plan
+→ Option: Review the plan first
+</step>
+
+<step name="offer_options">
+Present contextual options based on project state:
+
+```
+What would you like to do?
+
+[Primary action based on state - e.g.:]
+1. Resume from checkpoint (/gsd:execute-plan .planning/phases/XX-name/.continue-here-02-01.md)
+   OR
+1. Execute next plan (/gsd:execute-plan .planning/phases/XX-name/02-02-PLAN.md)
+   OR
+1. Discuss Phase 3 context (/gsd:discuss-phase 3) [if CONTEXT.md missing]
+   OR
+1. Plan Phase 3 (/gsd:plan-phase 3) [if CONTEXT.md exists or discuss option declined]
+
+[Secondary options:]
+2. Review current phase status
+3. Check deferred issues ([N] open)
+4. Review brief alignment
+5. Something else
+```
+
+**Note:** When offering phase planning, check for CONTEXT.md existence first:
+
+```bash
+ls .planning/phases/XX-name/CONTEXT.md 2>/dev/null
+```
+
+If missing, suggest discuss-phase before plan. If exists, offer plan directly.
+
+Wait for user selection.
+</step>
+
+<step name="route_to_workflow">
+Based on user selection, route to appropriate workflow:
+
+- **Execute plan** → EXIT and invoke SlashCommand("/gsd:execute-plan [path]")
+- **Plan phase** → EXIT and invoke SlashCommand("/gsd:plan-phase [phase-number]")
+- **Transition** → ./transition.md
+- **Review issues** → Read ISSUES.md, present summary
+- **Review alignment** → Read PROJECT.md, compare to current state
+- **Something else** → Ask what they need
+
+Note: Commands are shown in the presented options so user can see what will run.
+</step>
+
+<step name="update_session">
+Before proceeding to routed workflow, update session continuity:
+
+Update STATE.md:
+
+```markdown
+## Session Continuity
+
+Last session: [now]
+Stopped at: Session resumed, proceeding to [action]
+Resume file: [updated if applicable]
+```
+
+This ensures if session ends unexpectedly, next resume knows the state.
+</step>
+
+</process>
+
+<reconstruction>
+If STATE.md is missing but other artifacts exist:
+
+"STATE.md missing. Reconstructing from artifacts..."
+
+1. Read PROJECT.md → Extract Brief Summary
+2. Read ROADMAP.md → Determine phases, find current position
+3. Scan \*-SUMMARY.md files → Extract decisions, issues, concerns
+4. Read ISSUES.md → Count deferred issues
+5. Check for .continue-here files → Session continuity
+
+Reconstruct and write STATE.md, then proceed normally.
+
+This handles cases where:
+
+- Project predates STATE.md introduction
+- File was accidentally deleted
+- Cloning repo without full .planning/ state
+  </reconstruction>
+
+<quick_resume>
+For users who want minimal friction:
+
+If user says just "continue" or "go":
+
+- Load state silently
+- Determine primary action
+- Execute immediately without presenting options
+
+"Continuing from [state]... [action]"
+
+This enables fully autonomous "just keep going" workflow.
+</quick_resume>
+
+<success_criteria>
+Resume is complete when:
+
+- [ ] STATE.md loaded (or reconstructed)
+- [ ] Incomplete work detected and flagged
+- [ ] Clear status presented to user
+- [ ] Contextual next actions offered
+- [ ] User knows exactly where project stands
+- [ ] Session continuity updated
+      </success_criteria>