pmp-gywd 3.3.0

package/commands/gywd/consider-issues.md

@@ -0,0 +1,202 @@
+---
+name: GYWD:consider-issues
+description: Review deferred issues with codebase context, close resolved ones, identify urgent ones
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - Edit
+  - AskUserQuestion
+  - SlashCommand
+---
+
+<objective>
+Review all open issues from ISSUES.md with current codebase context. Identify which issues are resolved (can close), which are now urgent (should address), and which can continue waiting.
+
+This prevents issue pile-up by providing a triage mechanism with codebase awareness.
+</objective>
+
+<context>
+@.planning/ISSUES.md
+@.planning/STATE.md
+@.planning/ROADMAP.md
+</context>
+
+<process>
+
+<step name="verify">
+**Verify issues file exists:**
+
+If no `.planning/ISSUES.md`:
+```
+No issues file found.
+
+This means no enhancements have been deferred yet (Rule 5 hasn't triggered).
+
+Nothing to review.
+```
+Exit.
+
+If ISSUES.md exists but has no open issues (only template or empty "Open Enhancements"):
+```
+No open issues to review.
+
+All clear - continue with current work.
+```
+Exit.
+</step>
+
+<step name="parse">
+**Parse all open issues:**
+
+Extract from "## Open Enhancements" section:
+- ISS number (ISS-001, ISS-002, etc.)
+- Brief description
+- Discovered phase/date
+- Type (Performance/Refactoring/UX/Testing/Documentation/Accessibility)
+- Description details
+- Effort estimate
+
+Build list of issues to analyze.
+</step>
+
+<step name="analyze">
+**For each open issue, perform codebase analysis:**
+
+1. **Check if still relevant:**
+   - Search codebase for related code/files mentioned in issue
+   - If code no longer exists or was significantly refactored: likely resolved
+
+2. **Check if accidentally resolved:**
+   - Look for commits/changes that may have addressed this
+   - Check if the enhancement was implemented as part of other work
+
+3. **Assess current urgency:**
+   - Is this blocking upcoming phases?
+   - Has this become a pain point mentioned in recent summaries?
+   - Is this now affecting code we're actively working on?
+
+4. **Check natural fit:**
+   - Does this align with an upcoming phase in the roadmap?
+   - Would addressing it now touch the same files as current work?
+
+**Categorize each issue:**
+- **Resolved** - Can be closed (code changed, no longer applicable)
+- **Urgent** - Should address before continuing (blocking or causing problems)
+- **Natural fit** - Good candidate for upcoming phase X
+- **Can wait** - Keep deferred, no change in status
+</step>
+
+<step name="report">
+**Present categorized report:**
+
+```
+# Issue Review
+
+**Analyzed:** [N] open issues
+**Last reviewed:** [today's date]
+
+## Resolved (can close)
+
+### ISS-XXX: [description]
+**Reason:** [Why it's resolved - code changed, implemented elsewhere, no longer applicable]
+**Evidence:** [What you found - file changes, missing code, etc.]
+
+[Repeat for each resolved issue, or "None" if none resolved]
+
+---
+
+## Urgent (should address now)
+
+### ISS-XXX: [description]
+**Why urgent:** [What changed - blocking next phase, causing active problems, etc.]
+**Recommendation:** Insert plan before Phase [X] / Add to current phase
+**Effort:** [Quick/Medium/Substantial]
+
+[Repeat for each urgent issue, or "None - all issues can wait" if none urgent]
+
+---
+
+## Natural Fit for Upcoming Work
+
+### ISS-XXX: [description]
+**Fits with:** Phase [X] - [phase name]
+**Reason:** [Same files, same subsystem, natural inclusion]
+
+[Repeat for each, or "None" if no natural fits]
+
+---
+
+## Can Wait (no change)
+
+### ISS-XXX: [description]
+**Status:** Still valid, not urgent, keep deferred
+
+[Repeat for each, or list ISS numbers if many]
+```
+</step>
+
+<step name="offer_actions">
+**Offer batch actions:**
+
+Based on analysis, present options:
+
+```
+## Actions
+
+What would you like to do?
+```
+
+Use AskUserQuestion with appropriate options based on findings:
+
+**If resolved issues exist:**
+- "Close resolved issues" - Move to Closed Enhancements section
+- "Review each first" - Show details before closing
+
+**If urgent issues exist:**
+- "Insert urgent phase" - Create phase to address urgent issues (/gywd:insert-phase)
+- "Add to current plan" - Include in next plan being created
+- "Defer anyway" - Keep as-is despite urgency
+
+**If natural fits exist:**
+- "Note for phase planning" - Will be picked up during /gywd:plan-phase
+- "Add explicit reminder" - Update issue with "Include in Phase X"
+
+**Always include:**
+- "Done for now" - Exit without changes
+</step>
+
+<step name="execute_actions">
+**Execute selected actions:**
+
+**If closing resolved issues:**
+1. Read current ISSUES.md
+2. For each resolved issue:
+   - Remove from "## Open Enhancements"
+   - Add to "## Closed Enhancements" with resolution note:
+     ```
+     ### ISS-XXX: [description]
+     **Resolved:** [date] - [reason]
+     ```
+3. Write updated ISSUES.md
+4. Update STATE.md deferred issues count
+
+**If inserting urgent phase:**
+- Display the command for user to run after clearing: `/gywd:insert-phase [after-phase] Address urgent issues ISS-XXX, ISS-YYY`
+
+**If noting for phase planning:**
+- Update issue's "Suggested phase" field with specific phase number
+- These will be picked up by /gywd:plan-phase workflow
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] All open issues analyzed against current codebase
+- [ ] Each issue categorized (resolved/urgent/natural-fit/can-wait)
+- [ ] Clear reasoning provided for each categorization
+- [ ] Actions offered based on findings
+- [ ] ISSUES.md updated if user takes action
+- [ ] STATE.md updated if issue count changes
+</success_criteria>

package/commands/gywd/context.md

@@ -0,0 +1,93 @@
+---
+name: GYWD:context
+description: Show context budget visibility and usage analysis
+---
+
+<objective>
+Display context budget analysis to help users understand their context consumption and prevent the "context cliff" that kills productivity.
+
+Shows:
+- Current estimated context usage
+- Context breakdown by file type
+- Recommendations for optimization
+- Warning thresholds
+</objective>
+
+<process>
+1. Check if `.planning/` exists
+   - If not: Output "No GYWD project. Run /gywd:new-project first."
+
+2. Analyze context sources:
+
+   **Planning Files:**
+   - Count lines in .planning/*.md files
+   - Count lines in .planning/phases/**/*.md files
+   - Count lines in .planning/codebase/*.md (if exists)
+
+   **Estimate token usage:**
+   - Rough estimate: 1 line ≈ 10-15 tokens average
+   - Planning docs: Count total lines × 12
+   - Code context: If codebase mapped, count those lines × 10
+
+3. Calculate budget breakdown:
+   ```
+   Claude Code context window: ~200,000 tokens
+
+   Breakdown:
+   - System prompts & tools: ~15,000 tokens (reserved)
+   - Conversation history: Variable
+   - Available for project: ~185,000 tokens
+   ```
+
+4. Generate visual output:
+   ```
+   ## Context Budget Analysis
+
+   **Estimated Usage:**
+   [████████░░░░░░░░░░░░] 42% (~78,000 / 185,000 tokens)
+
+   **Breakdown:**
+   | Source | Lines | Est. Tokens | % |
+   |--------|-------|-------------|---|
+   | PROJECT.md | 45 | 540 | 0.3% |
+   | ROADMAP.md | 120 | 1,440 | 0.8% |
+   | STATE.md | 80 | 960 | 0.5% |
+   | Phase Plans | 450 | 5,400 | 2.9% |
+   | Codebase Maps | 2,100 | 21,000 | 11.4% |
+   | Code Files (est.) | 4,000 | 48,000 | 26.0% |
+
+   **Status:** ✅ Healthy
+
+   **Recommendations:**
+   - None needed at current usage
+   ```
+
+5. Show warnings if needed:
+   - 0-50%: ✅ Healthy - "Plenty of headroom"
+   - 50-70%: ⚠️ Moderate - "Consider summarizing older plans"
+   - 70-85%: 🟠 High - "Archive completed phases to reduce load"
+   - 85%+: 🔴 Critical - "Risk of context degradation. Archive now."
+
+6. If high usage, suggest actions:
+   - "Run /gywd:complete-milestone to archive"
+   - "Delete old SUMMARY.md files after review"
+   - "Consider running /gywd:digest instead of full codebase map"
+</process>
+
+<output_format>
+Clean, visual output with:
+- Progress bar showing usage
+- Table breakdown by source
+- Status indicator (emoji + text)
+- Actionable recommendations if needed
+
+Keep output concise - this is a quick check, not a report.
+</output_format>
+
+<success_criteria>
+- [ ] Shows estimated context usage percentage
+- [ ] Breaks down by source type
+- [ ] Provides clear status indicator
+- [ ] Gives actionable recommendations when needed
+- [ ] Executes quickly (< 5 seconds)
+</success_criteria>

package/commands/gywd/create-roadmap.md

@@ -0,0 +1,115 @@
+---
+name: GYWD:create-roadmap
+description: Create roadmap with phases for the project
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+  - Glob
+---
+
+<objective>
+Create project roadmap with phase breakdown.
+
+Roadmaps define what work happens in what order. Run after /gywd:new-project.
+</objective>
+
+<execution_context>
+@~/.claude/get-your-work-done/workflows/create-roadmap.md
+@~/.claude/get-your-work-done/templates/roadmap.md
+@~/.claude/get-your-work-done/templates/state.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/config.json
+</context>
+
+<process>
+
+<step name="validate">
+```bash
+# Verify project exists
+[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /gywd:new-project first."; exit 1; }
+```
+</step>
+
+<step name="check_existing">
+Check if roadmap already exists:
+
+```bash
+[ -f .planning/ROADMAP.md ] && echo "ROADMAP_EXISTS" || echo "NO_ROADMAP"
+```
+
+**If ROADMAP_EXISTS:**
+Use AskUserQuestion:
+- header: "Roadmap exists"
+- question: "A roadmap already exists. What would you like to do?"
+- options:
+  - "View existing" - Show current roadmap
+  - "Replace" - Create new roadmap (will overwrite)
+  - "Cancel" - Keep existing roadmap
+
+If "View existing": `cat .planning/ROADMAP.md` and exit
+If "Cancel": Exit
+If "Replace": Continue with workflow
+</step>
+
+<step name="create_roadmap">
+Follow the create-roadmap.md workflow starting from detect_domain step.
+
+The workflow handles:
+- Domain expertise detection
+- Phase identification
+- Research flags for each phase
+- Confirmation gates (respecting config mode)
+- ROADMAP.md creation
+- STATE.md initialization
+- Phase directory creation
+- Git commit
+</step>
+
+<step name="done">
+```
+Roadmap created:
+- Roadmap: .planning/ROADMAP.md
+- State: .planning/STATE.md
+- [N] phases defined
+
+---
+
+## ▶ Next Up
+
+**Phase 1: [Name]** — [Goal from ROADMAP.md]
+
+`/gywd:plan-phase 1`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gywd:discuss-phase 1` — gather context first
+- `/gywd:research-phase 1` — investigate unknowns
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<output>
+- `.planning/ROADMAP.md`
+- `.planning/STATE.md`
+- `.planning/phases/XX-name/` directories
+</output>
+
+<success_criteria>
+- [ ] PROJECT.md validated
+- [ ] ROADMAP.md created with phases
+- [ ] STATE.md initialized
+- [ ] Phase directories created
+- [ ] Changes committed
+</success_criteria>

package/commands/gywd/deps.md

@@ -0,0 +1,169 @@
+---
+name: GYWD:deps
+description: Visualize phase and task dependencies
+argument-hint: "[phase-number or 'all']"
+---
+
+<objective>
+Display dependency relationships between phases and tasks to:
+- Identify blocked work
+- Find parallelizable tasks
+- Understand critical path
+- Prevent out-of-order execution
+
+Helps users understand what can be done now vs. what must wait.
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+
+- No args or `all`: Show all phase dependencies
+- Phase number: Show task dependencies within that phase
+</context>
+
+<process>
+## Phase Dependencies (default or 'all')
+
+1. Read ROADMAP.md for all phases
+2. Read each phase's PLAN.md files for dependency declarations
+3. Build dependency graph:
+   - Look for "Dependencies:" sections
+   - Look for "Requires:" mentions
+   - Infer from ordering and context
+
+4. Generate visualization:
+   ```
+   ## Phase Dependencies
+
+   ```
+   [1] Foundation
+    ↓
+   [2] Authentication ←──┐
+    ↓                    │
+   [3] Core Features ────┤
+    ↓                    │
+   [4] API Layer ────────┘
+    ↓
+   [5] UI Components
+    ↓
+   [6] Testing
+    ↓
+   [7] Deployment
+   ```
+
+   ### Dependency Matrix
+
+   | Phase | Depends On | Blocks |
+   |-------|------------|--------|
+   | 1. Foundation | - | 2, 3 |
+   | 2. Auth | 1 | 4 |
+   | 3. Core | 1 | 4 |
+   | 4. API | 2, 3 | 5 |
+   | 5. UI | 4 | 6 |
+   | 6. Testing | 5 | 7 |
+   | 7. Deploy | 6 | - |
+
+   ### Parallelizable
+
+   Can run in parallel:
+   - Phase 2 (Auth) ↔ Phase 3 (Core Features)
+
+   ### Critical Path
+
+   Longest chain: 1 → 2 → 4 → 5 → 6 → 7 (6 phases)
+
+   ### Current Status
+
+   ✅ Phase 1: Complete
+   🔄 Phase 2: In progress
+   ⏳ Phase 3: Can start now (parallel with 2)
+   🔒 Phase 4: Blocked by 2, 3
+   ```
+
+## Task Dependencies (specific phase)
+
+1. Read the phase's PLAN.md
+2. Parse task list with dependency markers
+3. Build task dependency graph
+
+4. Generate visualization:
+   ```
+   ## Phase 3: Core Features - Task Dependencies
+
+   ```
+   [T1] Create data models
+    ↓
+   [T2] Implement repositories ←──┐
+    ↓                             │
+   [T3] Add business logic ───────┤
+    ↓                             │
+   [T4] Create service layer ─────┘
+    ↓
+   [T5] Write unit tests
+   ```
+
+   ### Task Status
+
+   | Task | Status | Depends On | Can Start? |
+   |------|--------|------------|------------|
+   | T1 | ✅ Done | - | - |
+   | T2 | ✅ Done | T1 | - |
+   | T3 | 🔄 Active | T1 | - |
+   | T4 | ⏳ Ready | T2, T3 | After T3 |
+   | T5 | 🔒 Blocked | T4 | No |
+
+   ### Parallelizable Tasks
+
+   - T2 ↔ T3 (both depend only on T1)
+
+   ### Next Available
+
+   After current work:
+   - T4 becomes unblocked when T3 completes
+   ```
+</process>
+
+<dependency_detection>
+**Explicit dependencies:**
+- "Depends on: Phase X" or "Requires: Task Y"
+- "After: ..." or "Blocked by: ..."
+- Numbered references in descriptions
+
+**Inferred dependencies:**
+- Sequential ordering in ROADMAP.md
+- References to outputs of other tasks
+- Logical prerequisites (can't test before implementing)
+- Import/usage patterns in code
+
+**Parallel opportunities:**
+- Tasks with same parent dependency
+- Phases with no shared requirements
+- Independent feature branches
+</dependency_detection>
+
+<output_format>
+Visual graph using ASCII art:
+- `↓` for direct dependency (A must complete before B)
+- `←──` for blocking relationship
+- `↔` for parallel opportunities
+
+Tables for detailed status:
+- Depends On: What must complete first
+- Blocks: What's waiting on this
+- Can Start?: Whether prerequisites are met
+
+Status indicators:
+- ✅ Complete
+- 🔄 In progress
+- ⏳ Ready (can start)
+- 🔒 Blocked
+</output_format>
+
+<success_criteria>
+- [ ] Parses dependencies from ROADMAP and PLANs
+- [ ] Generates visual dependency graph
+- [ ] Shows matrix of relationships
+- [ ] Identifies parallelizable work
+- [ ] Highlights critical path
+- [ ] Shows current blocked/unblocked status
+</success_criteria>

package/commands/gywd/digest.md

@@ -0,0 +1,138 @@
+---
+name: GYWD:digest
+description: Create a compact codebase digest for quick context refresh
+argument-hint: "[optional: focus-area]"
+---
+
+<objective>
+Generate a compact, focused codebase summary optimized for context efficiency.
+
+Unlike `/gywd:map-codebase` which creates comprehensive documentation, `/gywd:digest` creates a minimal summary focused on:
+- Key entry points
+- Critical patterns
+- Recent changes
+- Active areas
+
+Use when:
+- Resuming work after a break
+- Context is getting heavy
+- Need quick orientation
+- Working on specific area
+</objective>
+
+<context>
+Focus area: $ARGUMENTS (optional)
+
+If provided, digest focuses on that area of the codebase.
+Examples: "auth", "api", "frontend", "database"
+</context>
+
+<process>
+1. If focus area provided:
+   - Scope digest to relevant directories
+   - Include only related patterns
+
+2. Generate compact digest:
+
+   **Structure Analysis (3-5 lines max):**
+   ```
+   - Entry: src/index.ts → app.ts → routes/
+   - Core: src/services/ (business logic)
+   - Data: src/models/ + prisma/schema.prisma
+   ```
+
+   **Key Patterns (bullet points):**
+   ```
+   - Error handling: Result<T, E> pattern
+   - API responses: standardized via utils/response.ts
+   - Auth: JWT in headers, middleware validates
+   ```
+
+   **Recent Changes (from git):**
+   ```
+   Last 5 commits:
+   - feat: add user preferences
+   - fix: auth token refresh
+   - refactor: extract payment service
+   ```
+
+   **Active Files (most recently modified):**
+   ```
+   Hot files (last 24h):
+   - src/services/payment.ts
+   - src/routes/api/checkout.ts
+   - tests/payment.test.ts
+   ```
+
+3. Output format:
+   ```markdown
+   ## Codebase Digest
+
+   **Generated:** {timestamp}
+   **Focus:** {area or "Full codebase"}
+   **Size:** ~{estimated tokens} tokens
+
+   ---
+
+   ### Structure
+
+   {3-5 line overview}
+
+   ### Key Patterns
+
+   {5-8 bullet points}
+
+   ### Recent Activity
+
+   {Last 5 commits}
+
+   ### Hot Files
+
+   {Most active files}
+
+   ---
+
+   *Compact digest for quick context. Run /gywd:map-codebase for full documentation.*
+   ```
+
+4. Save to `.planning/DIGEST.md` (overwrites previous)
+
+5. Compare context size:
+   ```
+   Context comparison:
+   - Full codebase map: ~15,000 tokens
+   - This digest: ~800 tokens
+   - Savings: 94%
+   ```
+</process>
+
+<focus_areas>
+Common focus areas and what they include:
+
+| Focus | Directories | Patterns |
+|-------|-------------|----------|
+| auth | src/auth/, middleware/ | JWT, sessions, permissions |
+| api | src/routes/, src/controllers/ | Endpoints, validation |
+| data | src/models/, prisma/ | Schema, queries |
+| frontend | src/components/, src/pages/ | UI patterns, state |
+| testing | tests/, __tests__/ | Test patterns, mocks |
+</focus_areas>
+
+<output_format>
+Compact markdown optimized for:
+- Quick scanning (headers + bullets)
+- Minimal token usage
+- Essential information only
+- Easy refresh (just re-run command)
+
+Target size: 500-1000 tokens (vs 10,000+ for full map)
+</output_format>
+
+<success_criteria>
+- [ ] Generates in under 10 seconds
+- [ ] Output under 1000 tokens
+- [ ] Captures key patterns
+- [ ] Shows recent activity
+- [ ] Saves to DIGEST.md
+- [ ] Shows context savings
+</success_criteria>