pmp-gywd 3.3.0

package/commands/gywd/insert-phase.md

@@ -0,0 +1,227 @@
+---
+name: GYWD:insert-phase
+description: Insert urgent work as decimal phase (e.g., 72.1) between existing phases
+argument-hint: <after> <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases.
+
+Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.
+
+Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.
+</objective>
+
+<execution_context>
+@.planning/ROADMAP.md
+@.planning/STATE.md
+</execution_context>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- First argument: integer phase number to insert after
+- Remaining arguments: phase description
+
+Example: `/gywd:insert-phase 72 Fix critical auth bug`
+→ after = 72
+→ description = "Fix critical auth bug"
+
+Validation:
+
+```bash
+if [ $# -lt 2 ]; then
+  echo "ERROR: Both phase number and description required"
+  echo "Usage: /gywd:insert-phase <after> <description>"
+  echo "Example: /gywd:insert-phase 72 Fix critical auth bug"
+  exit 1
+fi
+```
+
+Parse first argument as integer:
+
+```bash
+after_phase=$1
+shift
+description="$*"
+
+# Validate after_phase is an integer
+if ! [[ "$after_phase" =~ ^[0-9]+$ ]]; then
+  echo "ERROR: Phase number must be an integer"
+  exit 1
+fi
+```
+
+</step>
+
+<step name="load_roadmap">
+Load the roadmap file:
+
+```bash
+if [ -f .planning/ROADMAP.md ]; then
+  ROADMAP=".planning/ROADMAP.md"
+else
+  echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
+  exit 1
+fi
+```
+
+Read roadmap content for parsing.
+</step>
+
+<step name="verify_target_phase">
+Verify that the target phase exists in the roadmap:
+
+1. Search for "### Phase {after_phase}:" heading
+2. If not found:
+
+   ```
+   ERROR: Phase {after_phase} not found in roadmap
+   Available phases: [list phase numbers]
+   ```
+
+   Exit.
+
+3. Verify phase is in current milestone (not completed/archived)
+   </step>
+
+<step name="find_existing_decimals">
+Find existing decimal phases after the target phase:
+
+1. Search for all "### Phase {after_phase}.N:" headings
+2. Extract decimal suffixes (e.g., for Phase 72: find 72.1, 72.2, 72.3)
+3. Find the highest decimal suffix
+4. Calculate next decimal: max + 1
+
+Examples:
+
+- Phase 72 with no decimals → next is 72.1
+- Phase 72 with 72.1 → next is 72.2
+- Phase 72 with 72.1, 72.2 → next is 72.3
+
+Store as: `decimal_phase="${after_phase}.${next_decimal}"`
+</step>
+
+<step name="generate_slug">
+Convert the phase description to a kebab-case slug:
+
+```bash
+slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+```
+
+Phase directory name: `{decimal-phase}-{slug}`
+Example: `72.1-fix-critical-auth-bug`
+</step>
+
+<step name="create_phase_directory">
+Create the phase directory structure:
+
+```bash
+phase_dir=".planning/phases/${decimal_phase}-${slug}"
+mkdir -p "$phase_dir"
+```
+
+Confirm: "Created directory: $phase_dir"
+</step>
+
+<step name="update_roadmap">
+Insert the new phase entry into the roadmap:
+
+1. Find insertion point: immediately after Phase {after_phase}'s content (before next phase heading or "---")
+2. Insert new phase heading with (INSERTED) marker:
+
+   ```
+   ### Phase {decimal_phase}: {Description} (INSERTED)
+
+   **Goal:** [Urgent work - to be planned]
+   **Depends on:** Phase {after_phase}
+   **Plans:** 0 plans
+
+   Plans:
+   - [ ] TBD (run /gywd:plan-phase {decimal_phase} to break down)
+
+   **Details:**
+   [To be added during planning]
+   ```
+
+3. Write updated roadmap back to file
+
+The "(INSERTED)" marker helps identify decimal phases as urgent insertions.
+
+Preserve all other content exactly (formatting, spacing, other phases).
+</step>
+
+<step name="update_project_state">
+Update STATE.md to reflect the inserted phase:
+
+1. Read `.planning/STATE.md`
+2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+   ```
+   - Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
+   ```
+
+If "Roadmap Evolution" section doesn't exist, create it.
+
+Add note about insertion reason if appropriate.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {decimal_phase} inserted after Phase {after_phase}:
+- Description: {description}
+- Directory: .planning/phases/{decimal-phase}-{slug}/
+- Status: Not planned yet
+- Marker: (INSERTED) - indicates urgent work
+
+Roadmap updated: {roadmap-path}
+Project state updated: .planning/STATE.md
+
+---
+
+## ▶ Next Up
+
+**Phase {decimal_phase}: {description}** — urgent insertion
+
+`/gywd:plan-phase {decimal_phase}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review insertion impact: Check if Phase {next_integer} dependencies still make sense
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+
+- Don't use this for planned work at end of milestone (use /gywd:add-phase)
+- Don't insert before Phase 1 (decimal 0.1 makes no sense)
+- Don't renumber existing phases
+- Don't modify the target phase content
+- Don't create plans yet (that's /gywd:plan-phase)
+- Don't commit changes (user decides when to commit)
+  </anti_patterns>
+
+<success_criteria>
+Phase insertion is complete when:
+
+- [ ] Phase directory created: `.planning/phases/{N.M}-{slug}/`
+- [ ] Roadmap updated with new phase entry (includes "(INSERTED)" marker)
+- [ ] Phase inserted in correct position (after target phase, before next integer phase)
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] Decimal number calculated correctly (based on existing decimals)
+- [ ] User informed of next steps and dependency implications
+      </success_criteria>

package/commands/gywd/list-phase-assumptions.md

@@ -0,0 +1,50 @@
+---
+name: GYWD:list-phase-assumptions
+description: Surface Claude's assumptions about a phase approach before planning
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+---
+
+<objective>
+Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
+
+Purpose: Help users see what Claude thinks BEFORE planning begins - enabling course correction early when assumptions are wrong.
+Output: Conversational output only (no file creation) - ends with "What do you think?" prompt
+</objective>
+
+<execution_context>
+@~/.claude/get-your-work-done/workflows/list-phase-assumptions.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. Follow list-phase-assumptions.md workflow:
+   - Analyze roadmap description
+   - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
+   - Present assumptions clearly
+   - Prompt "What do you think?"
+4. Gather feedback and offer next steps
+</process>
+
+<success_criteria>
+
+- Phase validated against roadmap
+- Assumptions surfaced across five areas
+- User prompted for feedback
+- User knows next steps (discuss context, plan phase, or correct assumptions)
+  </success_criteria>

package/commands/gywd/map-codebase.md

@@ -0,0 +1,84 @@
+---
+name: GYWD:map-codebase
+description: Analyze codebase with parallel Explore agents to produce .planning/codebase/ documents
+argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+<objective>
+Analyze existing codebase using parallel Explore agents to produce structured codebase documents.
+
+This command spawns multiple Explore agents to analyze different aspects of the codebase in parallel, each with fresh context.
+
+Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+</objective>
+
+<execution_context>
+@~/.claude/get-your-work-done/workflows/map-codebase.md
+@~/.claude/get-your-work-done/templates/codebase/stack.md
+@~/.claude/get-your-work-done/templates/codebase/architecture.md
+@~/.claude/get-your-work-done/templates/codebase/structure.md
+@~/.claude/get-your-work-done/templates/codebase/conventions.md
+@~/.claude/get-your-work-done/templates/codebase/testing.md
+@~/.claude/get-your-work-done/templates/codebase/integrations.md
+@~/.claude/get-your-work-done/templates/codebase/concerns.md
+</execution_context>
+
+<context>
+Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
+
+**Load project state if exists:**
+Check for .planning/STATE.md - loads context if project already initialized
+
+**This command can run:**
+- Before /gywd:new-project (brownfield codebases) - creates codebase map first
+- After /gywd:new-project (greenfield codebases) - updates codebase map as code evolves
+- Anytime to refresh codebase understanding
+</context>
+
+<when_to_use>
+**Use map-codebase for:**
+- Brownfield projects before initialization (understand existing code first)
+- Refreshing codebase map after significant changes
+- Onboarding to an unfamiliar codebase
+- Before major refactoring (understand current state)
+- When STATE.md references outdated codebase info
+
+**Skip map-codebase for:**
+- Greenfield projects with no code yet (nothing to map)
+- Trivial codebases (<5 files)
+</when_to_use>
+
+<process>
+1. Check if .planning/codebase/ already exists (offer to refresh or skip)
+2. Create .planning/codebase/ directory structure
+3. Spawn 4 parallel Explore agents to analyze codebase:
+   - Agent 1: Stack + Integrations (technology focus)
+   - Agent 2: Architecture + Structure (organization focus)
+   - Agent 3: Conventions + Testing (quality focus)
+   - Agent 4: Concerns (issues focus)
+4. Wait for all agents to complete, collect findings
+5. Write 7 codebase documents using templates:
+   - STACK.md - Languages, frameworks, key dependencies
+   - ARCHITECTURE.md - System design, patterns, data flow
+   - STRUCTURE.md - Directory layout, module organization
+   - CONVENTIONS.md - Code style, naming, patterns
+   - TESTING.md - Test structure, coverage, practices
+   - INTEGRATIONS.md - APIs, databases, external services
+   - CONCERNS.md - Technical debt, risks, issues
+6. Offer next steps (typically: /gywd:new-project or /gywd:plan-phase)
+</process>
+
+<success_criteria>
+- [ ] .planning/codebase/ directory created
+- [ ] All 7 codebase documents written
+- [ ] Documents follow template structure
+- [ ] Parallel agents completed without errors
+- [ ] User knows next steps
+</success_criteria>

package/commands/gywd/memory.md

@@ -0,0 +1,159 @@
+---
+name: GYWD:memory
+description: Multi-session memory - persist learned patterns and preferences
+argument-hint: "[show|add|clear] [optional: pattern or preference]"
+---
+
+<objective>
+Manage persistent memory across sessions. GYWD learns your patterns, preferences, and project-specific rules that carry forward between sessions.
+
+Memory types:
+- **Preferences**: Coding style, library choices, naming conventions
+- **Patterns**: Repeated solutions, common fixes, architectural decisions
+- **Rules**: Project-specific constraints ("always use TypeScript", "never modify legacy/")
+
+This allows Claude to remember what worked well and avoid repeating mistakes.
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Subcommands:**
+- `show` - Display all stored memories (default)
+- `add <type> <content>` - Add a new memory
+- `clear [type]` - Clear memories (all or by type)
+- `learn` - Auto-extract patterns from recent work
+
+**Memory storage:** `.planning/MEMORY.md`
+</context>
+
+<process>
+## show (default)
+
+1. Read `.planning/MEMORY.md` if exists
+2. Display formatted memory:
+   ```
+   ## Project Memory
+
+   ### Preferences
+   - Use TypeScript with strict mode
+   - Prefer functional components over class components
+   - Always include JSDoc comments for public APIs
+
+   ### Patterns
+   - Error handling: Use Result<T, E> pattern from utils/result.ts
+   - API calls: Always wrap in try-catch with retry logic
+   - Tests: One test file per module, co-located
+
+   ### Rules
+   - Never modify files in legacy/ directory
+   - All new files must have corresponding .test.ts
+   - Commits must pass CI before merge
+
+   ---
+   *3 preferences, 3 patterns, 3 rules stored*
+   ```
+
+## add <type> <content>
+
+1. Parse type: preference|pattern|rule
+2. Parse content (rest of arguments)
+3. Add to appropriate section in MEMORY.md
+4. Confirm: "Added {type}: {content}"
+
+Examples:
+- `/gywd:memory add preference Use pnpm instead of npm`
+- `/gywd:memory add pattern Always create index.ts barrel files`
+- `/gywd:memory add rule Never use console.log in production code`
+
+## clear [type]
+
+1. If type specified: Clear only that section
+2. If no type: Confirm, then clear all
+3. Output: "Cleared {count} {type} memories"
+
+## learn
+
+1. Read recent SUMMARY.md files (last 3-5)
+2. Analyze for:
+   - Repeated decisions
+   - Consistent patterns
+   - Explicit rules mentioned
+3. Suggest memories to add:
+   ```
+   ## Learned Patterns
+
+   Based on recent work, I noticed:
+
+   1. **Pattern detected**: You consistently use early returns
+      Add as pattern? [Y/n]
+
+   2. **Preference detected**: All components use React.FC type
+      Add as preference? [Y/n]
+
+   3. **Rule detected**: Tests always include edge cases
+      Add as rule? [Y/n]
+   ```
+4. Add confirmed patterns to MEMORY.md
+
+</process>
+
+<memory_format>
+MEMORY.md structure:
+```markdown
+# Project Memory
+
+Last updated: {date}
+
+## Preferences
+
+Style and tooling choices that should be consistent.
+
+- {preference 1}
+- {preference 2}
+
+## Patterns
+
+Repeated solutions and approaches.
+
+- {pattern 1}
+- {pattern 2}
+
+## Rules
+
+Hard constraints that must be followed.
+
+- {rule 1}
+- {rule 2}
+
+---
+*Auto-loaded at session start via STATE.md*
+```
+</memory_format>
+
+<integration>
+**How memories are used:**
+
+1. At session start (/gywd:resume-work):
+   - Load MEMORY.md
+   - Apply as context for all planning/execution
+
+2. During planning (/gywd:plan-phase):
+   - Check patterns for relevant solutions
+   - Apply preferences to design decisions
+   - Enforce rules as constraints
+
+3. During execution:
+   - Validate work against rules
+   - Apply patterns automatically
+   - Follow preferences consistently
+</integration>
+
+<success_criteria>
+- [ ] show displays all memories organized by type
+- [ ] add correctly appends to appropriate section
+- [ ] clear removes specified or all memories
+- [ ] learn extracts patterns from summaries
+- [ ] Memories persist across sessions
+- [ ] Format is readable and maintainable
+</success_criteria>

package/commands/gywd/new-milestone.md

@@ -0,0 +1,59 @@
+---
+name: GYWD:new-milestone
+description: Create a new milestone with phases for an existing project
+argument-hint: "[milestone name, e.g., 'v2.0 Features']"
+---
+
+<objective>
+Create a new milestone for an existing project with defined phases.
+
+Purpose: After completing a milestone (or when ready to define next chunk of work), creates the milestone structure in ROADMAP.md with phases, updates STATE.md, and creates phase directories.
+Output: New milestone in ROADMAP.md, updated STATE.md, phase directories created
+</objective>
+
+<execution_context>
+@~/.claude/get-your-work-done/workflows/create-milestone.md
+@~/.claude/get-your-work-done/templates/roadmap.md
+</execution_context>
+
+<context>
+Milestone name: $ARGUMENTS (optional - will prompt if not provided)
+
+**Load project state first:**
+@.planning/STATE.md
+
+**Load roadmap:**
+@.planning/ROADMAP.md
+
+**Load milestones (if exists):**
+@.planning/MILESTONES.md
+</context>
+
+<process>
+1. Load project context (STATE.md, ROADMAP.md, MILESTONES.md)
+2. Calculate next milestone version and starting phase number
+3. If milestone name provided in arguments, use it; otherwise prompt
+4. Gather phases (per depth setting: quick 3-5, standard 5-8, comprehensive 8-12):
+   - If called from /gywd:discuss-milestone, use provided context
+   - Otherwise, prompt for phase breakdown
+5. Detect research needs for each phase
+6. Confirm phases (respect config.json gate settings)
+7. Follow create-milestone.md workflow:
+   - Update ROADMAP.md with new milestone section
+   - Create phase directories
+   - Update STATE.md for new milestone
+   - Git commit milestone creation
+8. Offer next steps (discuss first phase, plan first phase, review)
+</process>
+
+<success_criteria>
+
+- Next phase number calculated correctly (continues from previous milestone)
+- Phases defined per depth setting (quick: 3-5, standard: 5-8, comprehensive: 8-12)
+- Research flags assigned for each phase
+- ROADMAP.md updated with new milestone section
+- Phase directories created
+- STATE.md reset for new milestone
+- Git commit made
+- User knows next steps
+  </success_criteria>