pmp-gywd 3.3.0

package/commands/gywd/discuss-milestone.md

@@ -0,0 +1,47 @@
+---
+name: GYWD:discuss-milestone
+description: Gather context for next milestone through adaptive questioning
+---
+
+<objective>
+Help you figure out what to build in the next milestone through collaborative thinking.
+
+Purpose: After completing a milestone, explore what features you want to add, improve, or fix. Features first — scope and phases derive from what you want to build.
+Output: Context gathered, then routes to /gywd:new-milestone
+</objective>
+
+<execution_context>
+@~/.claude/get-your-work-done/workflows/discuss-milestone.md
+</execution_context>
+
+<context>
+**Load project state first:**
+@.planning/STATE.md
+
+**Load roadmap:**
+@.planning/ROADMAP.md
+
+**Load milestones (if exists):**
+@.planning/MILESTONES.md
+</context>
+
+<process>
+1. Verify previous milestone complete (or acknowledge active milestone)
+2. Present context from previous milestone (accomplishments, phase count)
+3. Follow discuss-milestone.md workflow with **ALL questions using AskUserQuestion**:
+   - Use AskUserQuestion: "What do you want to add, improve, or fix?" with feature categories
+   - Use AskUserQuestion to dig into features they mention
+   - Use AskUserQuestion to help them articulate what matters most
+   - Use AskUserQuestion for decision gate (ready / ask more / let me add context)
+4. Hand off to /gywd:new-milestone with gathered context
+
+**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
+</process>
+
+<success_criteria>
+
+- Project state loaded and presented
+- Previous milestone context summarized
+- Milestone scope gathered through adaptive questioning
+- Context handed off to /gywd:new-milestone
+  </success_criteria>

package/commands/gywd/discuss-phase.md

@@ -0,0 +1,60 @@
+---
+name: GYWD:discuss-phase
+description: Gather phase context through adaptive questioning before planning
+argument-hint: "[phase]"
+---
+
+<objective>
+Help the user articulate their vision for a phase through collaborative thinking.
+
+Purpose: Understand HOW the user imagines this phase working — what it looks like, what's essential, what's out of scope. You're a thinking partner helping them crystallize their vision, not an interviewer gathering technical requirements.
+
+Output: {phase}-CONTEXT.md capturing the user's vision for the phase
+</objective>
+
+<execution_context>
+@~/.claude/get-your-work-done/workflows/discuss-phase.md
+@~/.claude/get-your-work-done/templates/context.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+**Load project state first:**
+@.planning/STATE.md
+
+**Load roadmap:**
+@.planning/ROADMAP.md
+</context>
+
+<process>
+1. Validate phase number argument (error if missing or invalid)
+2. Check if phase exists in roadmap
+3. Check if CONTEXT.md already exists (offer to update if yes)
+4. Follow discuss-phase.md workflow with **ALL questions using AskUserQuestion**:
+   - Present phase from roadmap
+   - Use AskUserQuestion: "How do you imagine this working?" with interpretation options
+   - Use AskUserQuestion to follow their thread — probe what excites them
+   - Use AskUserQuestion to sharpen the core — what's essential for THIS phase
+   - Use AskUserQuestion to find boundaries — what's explicitly out of scope
+   - Use AskUserQuestion for decision gate (ready / ask more / let me add context)
+   - Create CONTEXT.md capturing their vision
+5. Offer next steps (research or plan the phase)
+
+**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
+
+User is the visionary, you are the builder:
+- Ask about vision, feel, essential outcomes
+- DON'T ask about technical risks (you figure those out)
+- DON'T ask about codebase patterns (you read the code)
+- DON'T ask about success metrics (too corporate)
+- DON'T interrogate about constraints they didn't mention
+</process>
+
+<success_criteria>
+
+- Phase validated against roadmap
+- Vision gathered through collaborative thinking (not interrogation)
+- CONTEXT.md captures: how it works, what's essential, what's out of scope
+- User knows next steps (research or plan the phase)
+</success_criteria>

package/commands/gywd/execute-plan.md

@@ -0,0 +1,161 @@
+---
+name: GYWD:execute-plan
+description: Execute a PLAN.md file (supports partial execution with --tasks)
+argument-hint: "[path-to-PLAN.md] [--tasks 1-3 or --tasks 2,4,5]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+  - SlashCommand
+---
+
+<objective>
+Execute a PLAN.md file with per-task atomic commits, create SUMMARY.md, update project state.
+
+Commit strategy:
+- Each task → 1 commit immediately after completion (feat/fix/test/refactor)
+- Plan completion → 1 metadata commit (docs: SUMMARY + STATE + ROADMAP)
+
+Uses intelligent segmentation:
+- Plans without checkpoints → spawn subagent for full autonomous execution
+- Plans with verify checkpoints → segment execution, pause at checkpoints
+- Plans with decision checkpoints → execute in main context
+  </objective>
+
+<execution_context>
+@~/.claude/get-your-work-done/workflows/execute-phase.md
+@~/.claude/get-your-work-done/templates/summary.md
+@~/.claude/get-your-work-done/references/checkpoints.md
+@~/.claude/get-your-work-done/references/tdd.md
+</execution_context>
+
+<context>
+Plan path and options: $ARGUMENTS
+
+**Argument parsing:**
+- Path: First argument (required) - path to PLAN.md
+- --tasks: Optional task filter
+  - Range format: `--tasks 1-3` (tasks 1, 2, 3)
+  - List format: `--tasks 2,4,5` (specific tasks)
+  - Single: `--tasks 3` (just task 3)
+
+**Examples:**
+- `/gywd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md`
+- `/gywd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md --tasks 1-3`
+- `/gywd:execute-plan --tasks 4,5` (uses current plan from STATE.md)
+
+**Load project state first:**
+@.planning/STATE.md
+
+**Load workflow config:**
+@.planning/config.json
+</context>
+
+<process>
+1. Parse arguments:
+   - Extract plan path (or auto-detect from STATE.md)
+   - Parse --tasks flag if present:
+     - `--tasks 1-3` → [1, 2, 3]
+     - `--tasks 2,4,5` → [2, 4, 5]
+     - `--tasks 3` → [3]
+   - If no --tasks flag: execute all tasks
+
+2. Check .planning/ directory exists (error if not - user should run /gywd:new-project)
+
+3. Verify plan exists
+
+4. If --tasks specified (partial execution):
+   - Show: "Partial execution: Tasks {list}"
+   - Skip tasks not in the list
+   - Mark partial completion in STATE.md
+   - Create partial SUMMARY.md with note about which tasks were executed
+   - DO NOT mark plan as complete unless all tasks done
+
+5. If no --tasks (full execution):
+   - Check if SUMMARY.md already exists (plan already executed?)
+
+6. Load workflow config for mode (interactive/yolo)
+
+7. Follow execute-phase.md workflow:
+   - Parse plan and determine execution strategy (A/B/C)
+   - Execute tasks (via subagent or main context as appropriate)
+   - Handle checkpoints and deviations
+   - Create SUMMARY.md
+   - Update STATE.md
+   - Commit changes
+</process>
+
+<execution_strategies>
+**Strategy A: Fully Autonomous** (no checkpoints)
+
+- Spawn subagent to execute entire plan
+- Subagent creates SUMMARY.md and commits
+- Main context: orchestration only (~5% usage)
+
+**Strategy B: Segmented** (has verify-only checkpoints)
+
+- Execute in segments between checkpoints
+- Subagent for autonomous segments
+- Main context for checkpoints
+- Aggregate results → SUMMARY → commit
+
+**Strategy C: Decision-Dependent** (has decision checkpoints)
+
+- Execute in main context
+- Decision outcomes affect subsequent tasks
+- Quality maintained through small scope (2-3 tasks per plan)
+  </execution_strategies>
+
+<deviation_rules>
+During execution, handle discoveries automatically:
+
+1. **Auto-fix bugs** - Fix immediately, document in Summary
+2. **Auto-add critical** - Security/correctness gaps, add and document
+3. **Auto-fix blockers** - Can't proceed without fix, do it and document
+4. **Ask about architectural** - Major structural changes, stop and ask user
+5. **Log enhancements** - Nice-to-haves, log to ISSUES.md, continue
+
+Only rule 4 requires user intervention.
+</deviation_rules>
+
+<commit_rules>
+**Per-Task Commits:**
+
+After each task completes:
+1. Stage only files modified by that task
+2. Commit with format: `{type}({phase}-{plan}): {task-name}`
+3. Types: feat, fix, test, refactor, perf, chore
+4. Record commit hash for SUMMARY.md
+
+**Plan Metadata Commit:**
+
+After all tasks complete:
+1. Stage planning artifacts only: PLAN.md, SUMMARY.md, STATE.md, ROADMAP.md
+2. Commit with format: `docs({phase}-{plan}): complete [plan-name] plan`
+3. NO code files (already committed per-task)
+
+**NEVER use:**
+- `git add .`
+- `git add -A`
+- `git add src/` or any broad directory
+
+**Always stage files individually.**
+
+See ~/.claude/get-your-work-done/references/git-integration.md for full commit strategy.
+</commit_rules>
+
+<success_criteria>
+
+- [ ] All tasks executed
+- [ ] Each task committed individually (feat/fix/test/refactor)
+- [ ] SUMMARY.md created with substantive content and commit hashes
+- [ ] STATE.md updated (position, decisions, issues, session)
+- [ ] ROADMAP updated (plan count, phase status)
+- [ ] Metadata committed with docs({phase}-{plan}): complete [plan-name] plan
+- [ ] User informed of next steps
+      </success_criteria>

package/commands/gywd/extract-decisions.md

@@ -0,0 +1,325 @@
+---
+name: GYWD:extract-decisions
+description: Extract decision graph from codebase history
+argument-hint: "[--depth shallow|deep] [--since <date>] [--path <dir>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - Grep
+  - Task
+---
+
+<objective>
+Parse git history, PR descriptions, code comments, and documentation to extract a **decision graph** - a structured representation of WHY code exists, not just WHAT it does.
+
+This is the foundation for decision-aware AI assistance.
+</objective>
+
+<philosophy>
+Code is not text. Code is crystallized decisions.
+
+Every line represents:
+- A decision made with context we may have lost
+- Trade-offs that were considered
+- Alternatives that were rejected
+- Constraints that were respected
+
+By extracting these decisions explicitly, we enable:
+- "Why does this exist?" queries with real answers
+- Change impact analysis based on decision dependencies
+- Drift detection between intent and implementation
+- AI suggestions that respect decision coherence
+</philosophy>
+
+<decision_schema>
+Each extracted decision follows this structure:
+
+```yaml
+decision:
+  id: "DEC-001"
+  title: "Use Result<T,E> pattern for error handling"
+  type: "architectural|implementation|convention|constraint"
+
+  # When and who
+  date: "2024-03-15"
+  author: "@developer"
+  source: "commit:abc123|pr:47|comment:file.ts:42|doc:ARCHITECTURE.md"
+
+  # The decision itself
+  choice: "Adopted Result pattern from utils/result.ts"
+  context: "Needed error propagation without exceptions in async code"
+
+  # What was considered
+  alternatives:
+    - option: "try-catch blocks"
+      rejected_because: "Verbose, loses type information"
+    - option: "null returns"
+      rejected_because: "Ambiguous, null means multiple things"
+
+  trade_offs:
+    - gain: "Type-safe error handling"
+      cost: "More verbose call sites"
+    - gain: "Explicit error paths"
+      cost: "Learning curve for new developers"
+
+  # Confidence in extraction
+  confidence: 94  # percent
+  confidence_factors:
+    - "Explicitly documented in PR description (+40)"
+    - "Consistent usage across codebase (+30)"
+    - "Author comment explaining rationale (+24)"
+
+  # What this affects
+  affects:
+    files: ["src/services/*.ts", "src/utils/result.ts"]
+    decisions: ["DEC-003", "DEC-007"]  # downstream
+    depends_on: ["DEC-000"]  # upstream
+
+  # Metadata
+  status: "active|superseded|reverted"
+  superseded_by: null
+  tags: ["error-handling", "typescript", "patterns"]
+```
+</decision_schema>
+
+<extraction_sources>
+## Source Priority (highest to lowest confidence)
+
+### 1. Explicit Documentation (90-100% confidence)
+- Architecture Decision Records (ADRs)
+- DECISIONS.md or similar files
+- Inline comments with "Decision:", "Why:", "Rationale:"
+- PR descriptions with explicit reasoning
+
+### 2. Commit Messages (60-85% confidence)
+- Commits starting with "feat:", "refactor:", "fix:"
+- Commit bodies explaining reasoning
+- Breaking change annotations
+- References to issues/discussions
+
+### 3. Code Patterns (40-70% confidence)
+- Consistent usage implying convention
+- Deviation from language defaults
+- Custom abstractions that replace standard patterns
+- Configuration choices
+
+### 4. Temporal Inference (30-50% confidence)
+- Refactoring patterns (A→B→C evolution)
+- Reverted commits (tried and rejected)
+- File co-evolution (always changed together)
+</extraction_sources>
+
+<process>
+## Phase 1: Source Collection
+
+1. **Parse arguments:**
+   - `--depth shallow`: Last 100 commits only
+   - `--depth deep`: Full history (default)
+   - `--since <date>`: Start from date
+   - `--path <dir>`: Focus on specific directory
+
+2. **Gather explicit sources:**
+   ```bash
+   # Find ADRs and decision docs
+   find . -name "*.md" | xargs grep -l -i "decision\|rationale\|why we"
+
+   # Find annotated comments
+   grep -r "Decision:\|Why:\|Rationale:\|DECISION:" --include="*.ts" --include="*.js" --include="*.py"
+   ```
+
+3. **Parse git history:**
+   ```bash
+   # Commits with context
+   git log --format="%H|%an|%ad|%s" --date=short
+
+   # PR merge commits
+   git log --merges --format="%H|%s|%b"
+
+   # Refactoring commits
+   git log --grep="refactor" --format="%H|%s|%b"
+   ```
+
+## Phase 2: Decision Extraction
+
+For each source, use LLM to extract structured decisions:
+
+**Prompt template:**
+```
+Analyze this [commit/PR/comment/doc] and extract any decisions made.
+
+Source:
+{content}
+
+For each decision found, provide:
+1. What was decided
+2. Why (context, constraints, goals)
+3. What alternatives were considered (if mentioned)
+4. What trade-offs were accepted (if mentioned)
+5. Confidence level in this extraction (1-100)
+
+Focus on:
+- Architectural choices (patterns, structures, dependencies)
+- Convention choices (naming, organization, style)
+- Technology choices (libraries, tools, frameworks)
+- Constraint choices (what we deliberately don't do)
+```
+
+## Phase 3: Graph Construction
+
+1. **Link decisions:**
+   - Parse "affects" from file paths
+   - Detect decision dependencies (A required B)
+   - Find supersession chains (A replaced by B)
+
+2. **Calculate aggregate confidence:**
+   - Multiple sources confirming = higher confidence
+   - Contradictory sources = flag for review
+   - No sources but strong pattern = inferred decision
+
+3. **Identify gaps:**
+   - Code with no traceable decisions
+   - Decisions with no code (orphaned)
+   - Conflicting decisions
+
+## Phase 4: Output Generation
+
+Create `.planning/decisions/` structure:
+
+```
+.planning/decisions/
+├── DECISIONS.md          # Human-readable summary
+├── decision-graph.json   # Machine-readable graph
+├── confidence-report.md  # Extraction quality metrics
+└── gaps.md              # Identified gaps for review
+```
+</process>
+
+<output_format>
+## DECISIONS.md Structure
+
+```markdown
+# Decision Graph: {project-name}
+
+**Extracted:** {date}
+**Commits analyzed:** {count}
+**Decisions found:** {count}
+**Average confidence:** {percent}
+
+---
+
+## Architectural Decisions
+
+### DEC-001: Result Pattern for Error Handling [94%]
+
+**Decided:** 2024-03-15 by @developer
+**Source:** PR #47, commit abc123
+
+**Choice:** Use `Result<T,E>` pattern from `utils/result.ts`
+
+**Context:**
+> Needed error propagation without exceptions. Async code made try-catch unwieldy.
+
+**Alternatives Considered:**
+| Option | Rejected Because |
+|--------|------------------|
+| try-catch | Verbose, loses type info |
+| null returns | Ambiguous semantics |
+
+**Trade-offs:**
+- ✅ Type-safe errors
+- ✅ Explicit error paths
+- ⚠️ Verbose call sites
+- ⚠️ Learning curve
+
+**Affects:** 47 files in src/services/, src/utils/
+
+---
+
+### DEC-002: ...
+
+---
+
+## Convention Decisions
+
+### DEC-010: ...
+
+---
+
+## Inferred Decisions (Lower Confidence)
+
+These decisions were inferred from patterns, not explicit sources.
+Review recommended.
+
+### DEC-050: Barrel exports in each module [45%]
+
+**Inferred from:** Consistent pattern across 23 modules
+**No explicit source found**
+
+---
+
+## Decision Gaps
+
+The following code areas have no traceable decisions:
+
+| Path | Lines | Risk |
+|------|-------|------|
+| src/legacy/ | 2,400 | High - no history |
+| src/utils/crypto.ts | 180 | Medium - security-sensitive |
+
+---
+
+## Graph Statistics
+
+- Total decisions: 67
+- Architectural: 12
+- Implementation: 34
+- Convention: 15
+- Constraint: 6
+
+- High confidence (>80%): 23
+- Medium confidence (50-80%): 31
+- Low confidence (<50%): 13
+
+- Decision chains (A→B→C): 8
+- Superseded decisions: 5
+- Reverted decisions: 2
+```
+</output_format>
+
+<integration>
+## How Decision Graph Integrates with GYWD
+
+### During Planning (/gywd:plan-phase)
+- Load relevant decisions for the phase
+- Ensure plan respects existing decisions
+- Flag when plan conflicts with decisions
+- Suggest decisions to document
+
+### During Execution (/gywd:execute-plan)
+- Validate changes against decision constraints
+- Auto-document new decisions from commits
+- Detect decision drift
+
+### During Review (/gywd:challenge)
+- Adversarial agents reference decisions
+- "This violates DEC-012" as concrete feedback
+- Decision coherence scoring
+
+### Queries
+- `/gywd:why <file/function>` → Trace to decisions
+- `/gywd:impact <decision>` → Show downstream effects
+- `/gywd:conflicts` → Find contradictory decisions
+</integration>
+
+<success_criteria>
+- [ ] Parses git history for decision signals
+- [ ] Extracts ADRs and explicit documentation
+- [ ] Infers decisions from code patterns
+- [ ] Calculates confidence scores
+- [ ] Links decisions into graph structure
+- [ ] Creates queryable DECISIONS.md
+- [ ] Identifies gaps for review
+- [ ] Generates machine-readable JSON
+</success_criteria>