@riotprompt/riotplan 1.0.4 → 1.0.5

package/dist/mcp/prompts/explore_idea.md

@@ -0,0 +1,187 @@
+# Explore Idea
+
+## Purpose
+
+Guide collaborative exploration of a new idea without premature commitment. This prompt helps capture initial thinking, constraints, and questions before moving to formal planning.
+
+## When to Use
+
+- User mentions a new concept or feature
+- Starting to think about a problem
+- Not ready to commit to a full plan yet
+- Want to capture thoughts and gather evidence
+
+## Workflow
+
+### 1. Create the Idea
+
+Ask the user for:
+- A short code/identifier (kebab-case)
+- Initial description of the concept
+
+Create the idea:
+```
+riotplan_idea_create({
+  code: "feature-name",
+  description: "Initial concept description"
+})
+```
+
+### 2. Explore Together
+
+Ask open-ended questions:
+- "What's driving this idea?"
+- "What constraints should we consider?"
+- "What questions need answering?"
+- "Do you have any evidence (docs, diagrams, examples)?"
+
+As the user responds, capture their thinking in TWO ways:
+
+**FIRST: Capture the full narrative (preserve the raw conversation)**
+
+When the user provides detailed responses, especially voice transcriptions or long explanations, capture the FULL TEXT as narrative:
+
+```
+riotplan_idea_add_narrative({
+  content: "[User's complete response, verbatim or paraphrased if spoken]",
+  source: "voice",  // or "typing", "paste", "import"
+  context: "User explaining document type requirements"
+})
+```
+
+**THEN: Extract structured information**
+
+After capturing the narrative, extract key points into structured categories:
+
+**For thoughts/notes:**
+```
+riotplan_idea_add_note({
+  note: "User's thought or observation"
+})
+```
+
+**For constraints:**
+```
+riotplan_idea_add_constraint({
+  constraint: "Must work on mobile"
+})
+```
+
+**For questions:**
+```
+riotplan_idea_add_question({
+  question: "How will this integrate with existing API?"
+})
+```
+
+**For evidence:**
+```
+riotplan_idea_add_evidence({
+  evidencePath: "./path/to/diagram.png",
+  description: "Architecture diagram showing current state"
+})
+```
+
+**Why Both?**
+- Narrative preserves full context and nuance
+- Structured data makes information actionable
+- Timeline shows both the conversation and the decisions
+
+### 3. Decide Next Steps
+
+After exploration, ask:
+- "Does this feel worth pursuing?"
+- "Are we ready to explore different approaches?" (→ shaping)
+- "Should we set this aside for now?" (→ kill)
+
+**If ready to shape:**
+```
+riotplan_shaping_start()
+```
+
+**If not viable:**
+```
+riotplan_idea_kill({
+  reason: "Not feasible due to X"
+})
+```
+
+**If needs more time:**
+Just leave it in idea stage. Can return later.
+
+## Key Principles
+
+1. **No Commitment**: Ideas don't obligate execution
+2. **Cheap Thinking**: Capture thoughts without formality
+3. **Evidence Gathering**: Collect supporting materials
+4. **Question-Driven**: Surface unknowns early
+
+## Example Conversation
+
+**User**: "I'm thinking about adding real-time notifications"
+
+**AI**: "Let's explore that idea. I'll create a lightweight idea to capture your thinking."
+
+*Creates idea*
+
+**AI**: "What's driving this? What problem does it solve?"
+
+**User**: "Users miss important updates. They have to refresh constantly. It's frustrating for them and we're getting complaints. I think we need some kind of push notification system but I'm not sure if it should be in-app only or also email."
+
+*Captures narrative first:*
+```
+riotplan_idea_add_narrative({
+  content: "Users miss important updates. They have to refresh constantly. It's frustrating for them and we're getting complaints. I think we need some kind of push notification system but I'm not sure if it should be in-app only or also email.",
+  source: "typing",
+  context: "User explaining the problem driving this idea"
+})
+```
+
+*Then adds structured note:*
+```
+riotplan_idea_add_note({
+  note: "Problem: Users missing updates, forced to refresh manually. Considering push notifications (in-app vs email unclear)"
+})
+```
+
+**AI**: "What constraints should we consider?"
+
+**User**: "Must work on mobile. Can't require WebSockets everywhere. Also need to keep costs reasonable."
+
+*Captures narrative and extracts constraints*
+
+**AI**: "Good constraints. Any questions we need to answer?"
+
+**User**: "How do we handle offline users? What's the latency requirement?"
+
+*Adds questions*
+
+**AI**: "Do you have any examples or diagrams of how this might work?"
+
+**User**: "Here's a diagram from a similar system" [attaches image]
+
+*Adds evidence*
+
+**AI**: "This is taking shape. Ready to explore different approaches for implementation?"
+
+**User**: "Yes, let's look at options"
+
+*Transitions to shaping*
+
+## Anti-Patterns
+
+❌ Don't immediately jump to solutions
+❌ Don't create detailed plans yet
+❌ Don't pressure for commitment
+❌ Don't skip evidence gathering
+
+✅ Do ask open questions
+✅ Do capture all thinking
+✅ Do surface constraints early
+✅ Do gather supporting materials
+
+## Transition Criteria
+
+**To Shaping**: User wants to explore implementation approaches
+**To Kill**: Idea not viable or not worth pursuing
+**Stay in Idea**: Need more time to think, not ready yet

package/dist/mcp/prompts/shape_approach.md

@@ -0,0 +1,187 @@
+# Shape Approach
+
+## Purpose
+
+Collaboratively explore and compare different approaches to solving a problem before committing to detailed planning. This is where tradeoffs are surfaced and decisions are made.
+
+## When to Use
+
+- Transitioning from idea to concrete planning
+- Multiple valid approaches exist
+- Significant tradeoffs to consider
+- Need to align on direction before building
+
+## Workflow
+
+### 1. Start Shaping
+
+Transition from idea:
+```
+riotplan_shaping_start()
+```
+
+### 2. Identify Approaches
+
+Ask the user:
+- "What approaches could we take?"
+- "What have you seen work elsewhere?"
+- "What are the obvious options?"
+
+For each approach, capture:
+- Name (clear, descriptive)
+- Description (what it is, how it works)
+- Tradeoffs (pros and cons)
+- Assumptions (what must be true)
+
+```
+riotplan_shaping_add_approach({
+  name: "REST API with Polling",
+  description: "Traditional REST endpoints with client-side polling every 30s",
+  tradeoffs: [
+    "Pro: Simple, well understood by team",
+    "Pro: Works with existing infrastructure",
+    "Con: Higher latency (up to 30s)",
+    "Con: More server load from constant polling"
+  ],
+  assumptions: [
+    "30s latency is acceptable",
+    "Server can handle polling load"
+  ]
+})
+```
+
+### 3. Gather Feedback
+
+As you discuss approaches, capture the user's thinking:
+
+```
+riotplan_shaping_add_feedback({
+  feedback: "Concerned about polling load. We have 10k active users. That's 333 requests/second just for notifications."
+})
+```
+
+### 4. Add Evidence
+
+Encourage evidence-based decision making:
+- Performance benchmarks
+- Architecture diagrams
+- Code examples
+- Similar systems
+- Research papers
+
+```
+riotplan_shaping_add_evidence({
+  evidencePath: "./benchmarks/polling-vs-websocket.md",
+  description: "Performance comparison from similar scale system",
+  relatedTo: "REST API with Polling"
+})
+```
+
+### 5. Compare Approaches
+
+When ready to decide:
+```
+riotplan_shaping_compare()
+```
+
+This shows all approaches side-by-side with their tradeoffs.
+
+### 6. Select Approach
+
+Once aligned:
+```
+riotplan_shaping_select({
+  approach: "Server-Sent Events (SSE)",
+  reason: "Balances real-time updates with infrastructure simplicity. Team has SSE experience. Lower server load than polling."
+})
+```
+
+### 7. Transition to Built
+
+After selection, transition to build detailed plan:
+```
+riotplan_transition({
+  stage: "built",
+  reason: "Approach selected and validated"
+})
+```
+
+Now generate the detailed plan based on the shaped approach.
+
+## Key Principles
+
+1. **Multiple Options**: Always consider alternatives
+2. **Explicit Tradeoffs**: Surface pros and cons
+3. **Evidence-Based**: Use data, not opinions
+4. **Collaborative**: User drives decisions
+5. **No Premature Detail**: Stay high-level
+
+## Example Conversation
+
+**User**: "Let's explore approaches for real-time notifications"
+
+**AI**: "I'll start the shaping process. What approaches should we consider?"
+
+**User**: "Polling, WebSockets, or Server-Sent Events"
+
+**AI**: "Good options. Let's capture each with tradeoffs."
+
+*Adds three approaches with tradeoffs*
+
+**AI**: "Looking at these, what's your initial reaction?"
+
+**User**: "Polling feels wasteful. WebSockets might be overkill. SSE is interesting but I'm not sure about browser support."
+
+*Adds feedback*
+
+**AI**: "Do you have any evidence about SSE browser support?"
+
+**User**: "Let me check... here's caniuse data" [attaches link]
+
+*Adds evidence*
+
+**AI**: "SSE has 97% browser support. Given your concerns about polling waste and WebSocket complexity, SSE seems like a middle ground. Want to compare them side-by-side?"
+
+**User**: "Yes"
+
+*Shows comparison*
+
+**AI**: "Which approach feels right?"
+
+**User**: "SSE. It's simpler than WebSockets and more efficient than polling."
+
+*Selects approach*
+
+**AI**: "Great. Ready to build a detailed plan based on SSE?"
+
+**User**: "Yes"
+
+*Transitions to built, generates plan*
+
+## Anti-Patterns
+
+❌ Don't present only one approach
+❌ Don't hide tradeoffs
+❌ Don't make decisions for the user
+❌ Don't skip evidence gathering
+❌ Don't rush to detailed planning
+
+✅ Do explore multiple options
+✅ Do surface all tradeoffs
+✅ Do let user drive selection
+✅ Do gather supporting evidence
+✅ Do take time to align
+
+## Transition Criteria
+
+**To Built**: Approach selected, ready for detailed planning
+**Back to Idea**: Need to rethink the core concept
+**Stay in Shaping**: More approaches to explore, more evidence needed
+
+## Tips
+
+- Aim for 2-4 approaches (not too few, not overwhelming)
+- Be honest about tradeoffs (every approach has downsides)
+- Use evidence to resolve debates
+- Document why alternatives were rejected
+- Capture assumptions explicitly

package/dist/mcp/prompts/track_progress.md

@@ -0,0 +1,145 @@
+# Track Progress Workflow
+
+You are helping the user monitor plan progress, identify blockers, and maintain accurate status tracking throughout plan execution.
+
+## Your Task
+
+Follow this workflow to track progress using the riotplan MCP tools and resources available to you.
+
+## Step 1: Check Overall Status
+
+Use the `riotplan_status` tool to see high-level progress:
+
+```
+{
+  "path": "${path}",
+  "verbose": false
+}
+```
+
+This shows:
+- Completion percentage
+- Current step number
+- Active blockers and issues
+- Overall plan state
+
+Report this information to the user in a clear, concise format.
+
+## Step 2: Review Step Progress
+
+Use the `riotplan_step_list` tool to see all steps:
+
+```
+{
+  "path": "${path}",
+  "pending": false,
+  "all": true
+}
+```
+
+Or to see only remaining work:
+
+```
+{
+  "path": "${path}",
+  "pending": true
+}
+```
+
+This provides:
+- List of all steps with status
+- Which steps are completed, in progress, or pending
+- Step dependencies and ordering
+
+Present this information to the user, highlighting:
+- Completed steps (✅)
+- Current step (🔄)
+- Pending steps (⬜)
+- Any blocked steps (⏸️)
+
+## Step 3: Identify Issues
+
+Look for:
+- Blockers in the status output
+- Steps taking longer than expected
+- Any issues or notes in STATUS.md
+
+Inform the user about any problems found and suggest actions.
+
+## Step 4: Suggest Actions
+
+Based on the progress review, suggest to the user:
+- Which step to work on next
+- Whether any steps need to be added or split
+- If any blockers need to be addressed
+- Whether the plan needs adjustment
+
+## Important Guidelines
+
+- **Always use MCP tools** - Never shell out to CLI commands
+- **Be clear and concise** - Present status information in an easy-to-understand format
+- **Highlight issues** - Call attention to blockers or problems
+- **Suggest next steps** - Help the user understand what to do next
+- **Use resources** - Fetch status and steps resources for detailed information
+
+## Status Indicators
+
+When presenting status to the user, use these indicators:
+
+| Symbol | Status | Meaning |
+|--------|--------|---------|
+| ⬜ | Pending | Not yet started |
+| 🔄 | In Progress | Currently being worked on |
+| ✅ | Completed | Done and verified |
+| ❌ | Failed | Attempted but failed |
+| ⏸️ | Blocked | Waiting on dependency or external factor |
+| ⏭️ | Skipped | Intentionally skipped |
+
+## Handling Blockers
+
+When you identify a blocker:
+
+1. **Inform the User**
+   - Clearly explain what's blocking progress
+   - Note any dependencies or external factors
+   - Assess the impact on the overall plan
+
+2. **Suggest Actions**
+   - Can other steps proceed in parallel?
+   - What's needed to unblock?
+   - Should the plan be adjusted?
+
+3. **Document It**
+   - Help the user document the blocker in STATUS.md
+   - Track when it was identified and what's needed to resolve it
+
+## Adjusting Plans
+
+If requirements emerge or steps need adjustment:
+
+### Adding Steps
+Suggest using `riotplan_step_add`:
+
+```
+{
+  "path": "${path}",
+  "title": "New Step Title",
+  "after": 5
+}
+```
+
+### Splitting Large Steps
+If a step is too complex, suggest breaking it into smaller steps using `riotplan_step_add`.
+
+## Example Workflow
+
+Here's how you should execute this workflow:
+
+1. Call `riotplan_status` with path: "${path}"
+2. Present the status to the user clearly
+3. Call `riotplan_step_list` to show all steps
+4. Identify any issues or blockers
+5. Suggest next actions to the user
+6. If the user wants to adjust the plan, use `riotplan_step_add` or other tools
+
+Remember: Always use MCP tools, never shell commands.