@juicesharp/rpiv-pi 0.4.0

package/skills/resume-handoff/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: resume-handoff
+description: Resume work from a handoff document. Reads handoff, verifies current state, and continues implementation. Use at the start of a new session to pick up where you left off.
+argument-hint: [handoff-path]
+---
+
+# Resume work from a handoff document
+
+You are tasked with resuming work from a handoff document through an interactive process. These handoffs contain critical context, learnings, and next steps from previous work sessions that need to be understood and continued.
+
+## Initial Response
+
+When this command is invoked:
+
+1. **If the path to a handoff document was provided**:
+   - If a handoff document path was provided as a parameter, skip the default message
+   - Immediately read the handoff document FULLY using the Read tool
+   - Immediately read any research or plan documents that it links to under `thoughts/shared/plans` or `thoughts/shared/research` or `thoughts/shared/solutions`. Read these critical files DIRECTLY using the Read tool - do NOT invoke skills for this initial reading phase.
+   - Begin the analysis process by ingesting relevant context from the handoff document, reading additional files it mentions
+   - Then propose a course of action to the user and confirm, or ask for clarification on direction.
+
+2. **If no parameters provided**, respond with:
+```
+I'll help you resume work from a handoff document. Let me find the available handoffs.
+
+Which handoff would you like to resume from?
+
+Tip: You can invoke this command directly with a handoff path: `/skill:resume-handoff thoughts/shared/handoffs/YYYY-MM-DD_HH-MM-SS_description.md`
+```
+
+Then wait for the user's input.
+
+## Process Steps
+
+### Step 1: Read and Analyze Handoff
+
+1. **Read handoff document completely**:
+   - Use the Read tool WITHOUT limit/offset parameters
+   - Extract all sections:
+     - Task(s) and their statuses
+     - Recent changes
+     - Learnings
+     - Artifacts
+     - Action items and next steps
+     - Other notes
+
+2. **Spawn focused research agents**:
+   After reading all critical handoff/plan/research documents directly, spawn parallel general-purpose agents via the Agent tool to verify current codebase state and gather additional context:
+
+   ```
+   Task 1 - Gather artifact context:
+   Read all artifacts mentioned in the handoff.
+   1. Read feature documents listed in "Artifacts"
+   2. Read implementation plans referenced
+   3. Read any research documents mentioned
+   4. Extract key requirements and decisions
+   Use tools: Read
+   Return: Summary of artifact contents and key decisions
+   ```
+
+3. **Wait for ALL agents to complete** before proceeding
+
+4. **Verify current state**:
+   - Read files from "Learnings" section completely to validate patterns still apply
+   - Read files from "Recent changes" to verify modifications are still present
+   - Use git log or git diff if needed to check commit history since handoff
+   - Re-read implementation files mentioned to confirm current state matches handoff expectations
+   - Read any new related files discovered during research
+
+### Step 2: Synthesize and Present Analysis
+
+1. **Present comprehensive analysis**:
+   ```
+   I've analyzed the handoff from [date] by [researcher]. Here's the current situation:
+
+   **Original Tasks:**
+   - [Task 1]: [Status from handoff] → [Current verification]
+   - [Task 2]: [Status from handoff] → [Current verification]
+
+   **Key Learnings Validated:**
+   - [Learning with file:line reference] - [Still valid/Changed]
+   - [Pattern discovered] - [Still applicable/Modified]
+
+   **Recent Changes Status:**
+   - [Change 1] - [Verified present/Missing/Modified]
+   - [Change 2] - [Verified present/Missing/Modified]
+
+   **Artifacts Reviewed:**
+   - [Document 1]: [Key takeaway]
+   - [Document 2]: [Key takeaway]
+
+   **Recommended Next Actions:**
+   Based on the handoff's action items and current state:
+   1. [Most logical next step based on handoff]
+   2. [Second priority action]
+   3. [Additional tasks discovered]
+
+   **Potential Issues Identified:**
+   - [Any conflicts or regressions found]
+   - [Missing dependencies or broken code]
+
+   ```
+
+   Use the `ask_user_question` tool to confirm the approach. Question: "[Summary of recommended next action]. Proceed?". Header: "Resume". Options: "Proceed (Recommended)" (Begin with [recommended action 1]); "Adjust approach" (Change the order or scope of next steps); "Re-analyze" (The codebase has changed — re-verify state first).
+
+### Step 3: Create Action Plan
+
+1. **Create a task list**:
+   - Convert action items from handoff into todos
+   - Add any new tasks discovered during analysis
+   - Prioritize based on dependencies and handoff guidance
+
+2. **Present the plan**:
+   ```
+   I've created a task list based on the handoff and current analysis:
+
+   [Show todo list]
+
+   Ready to begin with the first task: [task description]?
+   ```
+
+### Step 4: Begin Implementation
+
+1. **Start with the first approved task**
+2. **Reference learnings from handoff** throughout implementation
+3. **Apply patterns and approaches documented** in the handoff
+4. **Update progress** as tasks are completed
+
+## Guidelines
+
+1. **Be Thorough in Analysis**:
+   - Read the entire handoff document first
+   - Verify ALL mentioned changes still exist
+   - Check for any regressions or conflicts
+   - Read all referenced artifacts
+
+2. **Be Interactive**:
+   - Present findings before starting work
+   - Get buy-in on the approach
+   - Allow for course corrections
+   - Adapt based on current state vs handoff state
+
+3. **Leverage Handoff Wisdom**:
+   - Pay special attention to "Learnings" section
+   - Apply documented patterns and approaches
+   - Avoid repeating mistakes mentioned
+   - Build on discovered solutions
+
+4. **Track Continuity**:
+   - Keep the task list updated to maintain task continuity
+   - Reference the handoff document in commits
+   - Document any deviations from original plan
+   - Consider creating a new handoff when done
+
+5. **Validate Before Acting**:
+   - Never assume handoff state matches current state
+   - Verify all file references still exist by reading them
+   - Check for breaking changes since handoff using git log/diff or by reading modified files
+   - Confirm patterns mentioned in "Learnings" are still valid by examining current code
+   - Compare handoff timestamps with current git commits to assess how much has changed
+
+## Common Scenarios
+
+### Scenario 1: Clean Continuation
+- All changes from handoff are present
+- No conflicts or regressions
+- Clear next steps in action items
+- Proceed with recommended actions
+
+### Scenario 2: Diverged Codebase
+- Some changes missing or modified
+- New related code added since handoff
+- Need to reconcile differences
+- Adapt plan based on current state
+
+### Scenario 3: Incomplete Handoff Work
+- Tasks marked as "in_progress" in handoff
+- Need to complete unfinished work first
+- May need to re-understand partial implementations
+- Focus on completing before new work
+
+### Scenario 4: Stale Handoff
+- Significant time has passed
+- Major refactoring has occurred
+- Original approach may no longer apply
+- Need to re-evaluate strategy
+
+## Example Interaction Flow
+
+```
+User: /skill:resume-handoff thoughts/shared/handoffs/2025-01-08_14-30-15_webhook-validation.md
+Assistant: Let me read and analyze that handoff document...
+
+[Reads handoff completely]
+[Spawns research agents]
+[Waits for completion]
+[Reads identified files]
+
+I've analyzed the handoff from [date]. Here's the current situation...
+
+[Presents analysis]
+
+Shall I proceed with implementing the webhook validation fix, or would you like to adjust the approach?
+
+User: Yes, proceed with the webhook validation
+Assistant: [Creates todo list and begins implementation]
+```

package/skills/revise/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: revise
+description: Update existing implementation plans based on feedback. Makes surgical edits while preserving structure and quality. Use when plans need adjustments after review or during implementation.
+argument-hint: "[plan-path] [feedback]"
+allowed-tools: Edit, Read, Bash(git *), Glob, Grep, Agent
+---
+
+# Iterate Implementation Plan
+
+You are tasked with updating existing implementation plans based on user feedback. You should be skeptical, thorough, and ensure changes are grounded in actual codebase reality.
+
+## Initial Response
+
+When this command is invoked:
+
+1. **Parse the input to identify**:
+   - Plan file path (e.g., `thoughts/shared/plans/2025-10-16_09-00-00_feature.md`)
+   - Requested changes/feedback
+
+2. **Handle different input scenarios**:
+
+   **If NO plan file provided**:
+   ```
+   I'll help you iterate on an existing implementation plan.
+
+   Which plan would you like to update? Please provide the path to the plan file (e.g., `thoughts/shared/plans/2025-10-16_09-00-00_feature.md`).
+
+   Tip: You can list recent plans with `ls -lt thoughts/shared/plans/ | head`
+   ```
+   Wait for user input, then re-check for feedback.
+
+   **If plan file provided but NO feedback**:
+   ```
+   I've found the plan at [path]. What changes would you like to make?
+
+   For example:
+   - "Add a phase for migration handling"
+   - "Update the success criteria to include performance tests"
+   - "Adjust the scope to exclude feature X"
+   - "Split Phase 2 into two separate phases"
+   ```
+   Wait for user input.
+
+   **If BOTH plan file AND feedback provided**:
+   - Proceed immediately to Step 1
+   - No preliminary questions needed
+
+## Process Steps
+
+### Step 1: Read and Understand Current Plan
+
+1. **Read the existing plan file COMPLETELY**:
+   - Use the Read tool WITHOUT limit/offset parameters
+   - Understand the current structure, phases, and scope
+   - Note the success criteria and implementation approach
+
+2. **Understand the requested changes**:
+   - Parse what the user wants to add/modify/remove
+   - Identify if changes require codebase research
+   - Determine scope of the update
+
+### Step 2: Research If Needed
+
+**Only spawn research tasks if the changes require new technical understanding.**
+
+If the user's feedback requires understanding new code patterns or validating assumptions:
+
+1. **Spawn parallel agents for research** using the Agent tool:
+   **For code investigation:**
+   - Use the **codebase-locator** agent to find relevant files
+   - Use the **codebase-analyzer** agent to understand implementation details
+   - Use the **codebase-pattern-finder** agent to find similar patterns
+
+   **For historical context:**
+   - Use the **thoughts-locator** agent to find related research or decisions in thoughts/
+   - Use the **thoughts-analyzer** agent to extract insights from documents
+
+   **Be EXTREMELY specific about directories**:
+   - Include full path context in prompts
+
+2. **Read any new files identified by research**:
+   - Read them FULLY into the main context
+   - Cross-reference with the plan requirements
+
+3. **Wait for ALL agents to complete** before proceeding
+
+### Step 3: Present Understanding and Approach
+
+Before making changes, confirm your understanding:
+
+```
+Based on your feedback, I understand you want to:
+- [Change 1 with specific detail]
+- [Change 2 with specific detail]
+
+My research found:
+- [Relevant code pattern or constraint]
+- [Important discovery that affects the change]
+
+I plan to update the plan by:
+1. [Specific modification to make]
+2. [Another modification]
+
+Does this align with your intent?
+```
+
+Use the `ask_user_question` tool to confirm before editing. Question: "[Summary of planned modifications]. Proceed with these edits?". Header: "Changes". Options: "Proceed (Recommended)" (Apply the planned changes to the existing plan); "Adjust approach" (Modify what will be changed before editing); "Show me first" (Show the exact text changes before applying).
+
+### Step 4: Update the Plan
+
+1. **Make focused, precise edits** to the existing plan:
+   - Use the Edit tool for surgical changes
+   - NEVER use Write tool - plan files already exist, use Edit tool only
+   - Maintain the existing structure unless explicitly changing it
+   - Keep all file:line references accurate
+   - Update success criteria if needed
+
+2. **Ensure consistency**:
+   - If adding a new phase, ensure it follows the existing pattern
+   - If modifying scope, update "What We're NOT Doing" section
+   - If changing approach, update "Implementation Approach" section
+   - Maintain the distinction between automated vs manual success criteria
+   - If the plan has YAML frontmatter, update `last_updated` to today's date and `last_updated_by` to your name
+
+3. **Preserve quality standards**:
+   - Include specific file paths and line numbers for new content
+   - Write measurable success criteria
+   - Use project's build/test commands (`make`, `npm`, etc.) for automated verification
+   - Keep language clear and actionable
+
+### Step 5: Sync and Review
+
+1. **Present the changes made**:
+   ```
+   I've updated the plan at `thoughts/shared/plans/[filename].md`
+
+   Changes made:
+   - [Specific change 1]
+   - [Specific change 2]
+
+   The updated plan now:
+   - [Key improvement]
+   - [Another improvement]
+
+   Would you like any further adjustments?
+   ```
+
+2. **Be ready to iterate further** based on feedback
+
+## Important Guidelines
+
+1. **Be Skeptical**:
+   - Don't blindly accept change requests that seem problematic
+   - Question vague feedback - ask for clarification
+   - Use AskUserQuestion tool for structured clarification when there are multiple valid approaches
+   - Verify technical feasibility with code research
+   - Point out potential conflicts with existing plan phases
+
+2. **Be Surgical**:
+   - Make precise edits, not wholesale rewrites
+   - Preserve good content that doesn't need changing
+   - Only research what's necessary for the specific changes
+   - Don't over-engineer the updates
+
+3. **Be Thorough**:
+   - Read the entire existing plan before making changes
+   - Research code patterns if changes require new technical understanding
+   - Ensure updated sections maintain quality standards
+   - Verify success criteria are still measurable
+
+4. **Be Interactive**:
+   - Confirm understanding before making changes
+   - Show what you plan to change before doing it
+   - Allow course corrections
+   - Don't disappear into research without communicating
+
+5. **Track Progress**:
+   - Update todos as you complete research
+   - Mark tasks complete when done
+
+6. **No Open Questions**:
+   - If the requested change raises questions, ASK
+   - Research or get clarification immediately
+   - Do NOT update the plan with unresolved questions
+   - Every change must be complete and actionable
+
+## Success Criteria Guidelines
+
+When updating success criteria, always maintain the two-category structure:
+
+1. **Automated Verification** (can be run by execution agents):
+   - Commands that can be run: `make test`, `npm run lint`, etc.
+   - Specific files that should exist
+   - Code compilation/type checking
+
+2. **Manual Verification** (requires human testing):
+   - UI/UX functionality
+   - Performance under real conditions
+   - Edge cases that are hard to automate
+   - User acceptance criteria
+
+## Agent Invocation Best Practices
+
+When spawning research agents:
+
+1. **Only spawn if truly needed** - don't research for simple changes
+2. **Spawn multiple agents in parallel** for efficiency using the Agent tool
+3. **Each agent should be focused** on a specific area
+4. **Provide detailed instructions** including:
+   - Exactly what to search for
+   - Which directories to focus on
+   - What information to extract
+   - Expected output format
+5. **Request specific file:line references** in responses
+6. **Wait for all agents to complete** before synthesizing
+7. **Verify agent results** - if something seems off, spawn follow-up agents
+
+## Example Interaction Flows
+
+**Scenario 1: User provides everything upfront**
+```
+User: /skill:revise thoughts/shared/plans/2025-10-16_09-00-00_feature.md - add phase for error handling
+Assistant: [Reads plan, researches error handling patterns, updates plan]
+```
+
+**Scenario 2: User provides just plan file**
+```
+User: /skill:revise thoughts/shared/plans/2025-10-16_09-00-00_feature.md
+Assistant: I've found the plan. What changes would you like to make?
+User: Split Phase 2 into two phases - one for backend, one for frontend
+Assistant: [Proceeds with update]
+```
+
+**Scenario 3: User provides no arguments**
+```
+User: /skill:revise
+Assistant: Which plan would you like to update? Please provide the path...
+User: thoughts/shared/plans/2025-10-16_09-00-00_feature.md
+Assistant: I've found the plan. What changes would you like to make?
+User: Add more specific success criteria
+Assistant: [Proceeds with update]
+```

package/skills/validate/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: validate
+description: Verify that an implementation plan was correctly executed. Runs success criteria checks and generates validation reports. Use after implementation is complete.
+argument-hint: [plan-path]
+allowed-tools: Read, Bash(git *), Bash(make *), Glob, Grep, Agent
+---
+
+# Validate Plan
+
+You are tasked with validating that an implementation plan was correctly executed, verifying all success criteria and identifying any deviations or issues.
+
+## Initial Setup
+
+When invoked:
+1. **Determine context** - Are you in an existing conversation or starting fresh?
+   - If existing: Review what was implemented in this session
+   - If fresh: Need to discover what was done through git and codebase analysis
+
+2. **Locate the plan**:
+   - If plan path provided, use it
+   - Otherwise, search recent commits for plan references or ask user
+
+3. **Gather implementation evidence**:
+   ```bash
+   # Check recent commits
+   git log --oneline -n 20
+   git diff HEAD~N..HEAD  # Where N covers implementation commits
+
+   # Run comprehensive checks
+   cd $(git rev-parse --show-toplevel) && make check test
+   ```
+
+## Validation Process
+
+### Step 1: Context Discovery
+
+If starting fresh or need more context:
+
+   **If the injected git context shows "not a git repo":**
+   - Skip git-based evidence gathering (git log, git diff)
+   - Validate via file inspection, automated test commands, and plan checklist
+   - Note in report: "Git history unavailable — validation based on file inspection only"
+
+1. **Read the implementation plan** completely
+2. **Identify what should have changed**:
+   - List all files that should be modified
+   - Note all success criteria (automated and manual)
+   - Identify key functionality to verify
+
+3. **Spawn parallel research agents** to verify implementation:
+
+   Use the Agent tool to spawn general-purpose sub-agents to validate the implementation:
+   - **general-purpose** agent — Verify implementation details match plan specifications (analyzer role)
+   - **general-purpose** agent — Verify implementation follows established codebase patterns (pattern-finder role)
+
+   Example agent prompts:
+   - "Analyze [component] and verify it implements [plan requirement] correctly"
+   - "Find patterns similar to [new code] and check if conventions are followed"
+
+   Also gather evidence directly:
+   ```bash
+   # Check recent commits
+   git log --oneline -n 20
+   git diff HEAD~N..HEAD  # Where N covers implementation commits
+
+   # Run comprehensive checks
+   cd $(git rev-parse --show-toplevel) && make check test
+   ```
+
+### Step 2: Systematic Validation
+
+For each phase in the plan:
+
+1. **Check completion status**:
+   - Look for checkmarks in the plan (- [x])
+   - Verify the actual code matches claimed completion
+
+2. **Run automated verification**:
+   - Execute each command from "Automated Verification"
+   - Document pass/fail status
+   - If failures, investigate root cause
+
+3. **Assess manual criteria**:
+   - List what needs manual testing
+   - Provide clear steps for user verification
+
+4. **Think deeply about edge cases**:
+   - Were error conditions handled?
+   - Are there missing validations?
+   - Could the implementation break existing functionality?
+
+### Step 3: Generate Validation Report
+
+Create comprehensive validation summary:
+
+```markdown
+## Validation Report: [Plan Name]
+
+### Implementation Status
+✓ Phase 1: [Name] - Fully implemented
+✓ Phase 2: [Name] - Fully implemented
+⚠️ Phase 3: [Name] - Partially implemented (see issues)
+
+### Automated Verification Results
+✓ Build passes: `make build`
+✓ Tests pass: `make test`
+✗ Linting issues: `make lint` (3 warnings)
+
+### Code Review Findings
+
+#### Matches Plan:
+- Database migration correctly adds [table]
+- API endpoints implement specified methods
+- Error handling follows plan
+
+#### Deviations from Plan:
+- Used different variable names in [file:line]
+- Added extra validation in [file:line] (improvement)
+
+#### Potential Issues:
+- Missing index on foreign key could impact performance
+- No rollback handling in migration
+
+### Manual Testing Required:
+1. UI functionality:
+   - [ ] Verify [feature] appears correctly
+   - [ ] Test error states with invalid input
+
+2. Integration:
+   - [ ] Confirm works with existing [component]
+   - [ ] Check performance with large datasets
+
+### Recommendations:
+- Address linting warnings before merge
+- Consider adding integration test for [scenario]
+- Document new API endpoints
+```
+
+## Working with Existing Context
+
+If you were part of the implementation:
+- Review the conversation history
+- Check your todo list for what was completed
+- Focus validation on work done in this session
+- Be honest about any shortcuts or incomplete items
+
+## Important Guidelines
+
+1. **Be thorough but practical** - Focus on what matters
+2. **Run all automated checks** - Don't skip verification commands
+3. **Document everything** - Both successes and issues
+4. **Think critically** - Question if the implementation truly solves the problem
+5. **Consider maintenance** - Will this be maintainable long-term?
+
+## Validation Checklist
+
+Always verify:
+- [ ] All phases marked complete are actually done
+- [ ] Automated tests pass
+- [ ] Code follows existing patterns
+- [ ] No regressions introduced
+- [ ] Error handling is robust
+- [ ] Documentation updated if needed
+- [ ] Manual test steps are clear
+
+## Relationship to Other Skills
+
+Recommended workflow:
+1. `/skill:implement` - Execute the implementation
+2. `/skill:commit` - Create atomic commits for changes
+3. `/skill:validate` - Verify implementation correctness
+
+The validation works best after commits are made, as it can analyze the git history to understand what was implemented.
+
+Remember: Good validation catches issues before they reach production. Be constructive but thorough in identifying gaps or improvements.