agemon 0.1.0 → 6.3.0

package/assets/skills/team-lead/agemon-plan-rfc/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: agemon-plan-rfc
+description: Plan and draft RFCs (Request for Comments) for major features or architectural changes. Use when user wants to propose a significant feature, system redesign, or cross-cutting change that requires stakeholder alignment before implementation. Triggers on phrases like "RFC", "proposal", "major feature", "architectural change", "need buy-in", or when user describes a feature too large for a single ticket. Guides through structured questioning to produce a complete RFC draft in Notion.
+---
+
+# RFC Planning Skill
+
+Guide the user through planning an RFC by exploring the codebase, asking clarifying
+questions for each section, and drafting a complete RFC document to Notion.
+
+## Input
+
+The user provides a freeform feature description. Example:
+
+> "I've been building AlgoJuke, an AI-powered playlist generator backed by the user's
+> Tidal music library and Tidal search, and an ingestion pipeline which interprets
+> lyrics for the tracks in the user's library so it can make recommendations which fit
+> a theme / mood.
+>
+> I'd like to turn it into a personal radio station that interleaves your favourite
+> music (+ recommendations based on your mood and natural language input) with
+> excerpts / summaries from articles that are interesting to you, that you've
+> bookmarked via the Readwise API with voiceover using ElevenLabs."
+
+## Workflow
+
+### Step 1: Enter Plan Mode
+
+Call `EnterPlanMode` to begin planning. All exploration and questioning happens in plan
+mode.
+
+### Step 2: Explore Context
+
+Before asking questions, silently gather context:
+
+1. **Read existing specs**: Search `specs/*/spec.md` for related features
+2. **Explore architecture**: Identify key services, data flows, integrations
+3. **Check prior art**: Look for similar patterns in the codebase
+4. **Note dependencies**: What existing systems would this touch?
+
+Do NOT output exploration results verbatim. Synthesize into understanding.
+
+### Step 3: Section-by-Section Questioning
+
+For each RFC section, ask **up to 5 clarifying questions** based on:
+
+- Gaps in the user's description
+- Ambiguities that affect scope
+- Technical constraints discovered during exploration
+- Stakeholder concerns to anticipate
+
+Present questions as a numbered list. User can answer in shorthand.
+
+#### Section Order
+
+Work through sections in this order (skip none):
+
+1. **Summary** — Confirm the one-paragraph pitch
+2. **Motivation** — Why now? What's the business driver?
+3. **Goals and Non-Goals** — Scope boundaries, success criteria
+4. **User's Explanation** — How users experience this
+5. **Engineer's Explanation** — Technical approach, system interactions
+6. **Drawbacks** — What could go wrong? What are we trading off?
+7. **Rationale and Alternatives** — Why this approach over others?
+8. **Cost and Operations** — Infrastructure, LLM costs, operational burden
+9. **Prior Art** — Similar systems, lessons learned
+10. **Unresolved Questions** — What needs resolution during RFC review?
+11. **Future Possibilities** — Natural extensions, long-term vision
+
+#### Questioning Pattern
+
+For each section:
+
+```
+## {Section Name}
+
+Based on your description and what I found in the codebase:
+
+- {Relevant context from exploration}
+
+Questions:
+
+1. {Question addressing a gap}
+2. {Question about scope/boundary}
+3. {Question about technical constraint}
+4. {Question anticipating stakeholder concern}
+5. {Question about success/failure criteria}
+
+Answer in shorthand (e.g., "1: yes, 2: via Readwise API, 3: out of scope").
+```
+
+After user answers, summarize what will go in that section. Confirm before moving on.
+
+### Step 4: Build Plan Document
+
+As sections are confirmed, accumulate them in the plan file (NOT the final RFC yet).
+
+Structure:
+
+```
+# RFC Plan: {Title}
+
+## Status
+- [x] Summary confirmed
+- [x] Motivation confirmed
+- [ ] Goals and Non-Goals — in progress
+- [ ] ...
+
+## Summary
+{Confirmed content}
+
+## Motivation
+{Confirmed content}
+
+...
+```
+
+### Step 5: Exit Plan Mode
+
+When all sections are confirmed, call `ExitPlanMode` with the complete plan.
+
+Present a final summary:
+
+- RFC title
+- Key decisions made
+- Sections completed
+- Ready to write to Notion
+
+### Step 6: Write to Notion (After Acceptance)
+
+On plan acceptance, create the RFC in Notion:
+
+```
+mcp__notion__create_page with:
+- database_id: 2e7258b8-ba0c-80d1-a580-cbab6bca3ddd
+- properties:
+  - Title: {RFC title}
+  - Status: "Draft"
+  - Created: {ISO date}
+- content: {Full RFC markdown}
+```
+
+Output the Notion URL for the user to share with stakeholders.
+
+### Step 7: Suggest Next Steps
+
+After RFC creation:
+
+```
+RFC created: {Notion URL}
+
+Next steps:
+1. Share with stakeholders for review
+2. Address comments in Notion
+3. Once approved, run '/breakdown-rfc {notion-url}' to create tickets
+```
+
+## RFC Template
+
+The final RFC should follow this structure:
+
+```
+# RFC: {Title}
+
+## 📝 Summary
+
+{One paragraph explanation}
+
+## 💪 Motivation
+
+{Why are we doing this? Use cases? Expected outcome?}
+
+## 🎯 Goals and Non-Goals
+
+**Goals:**
+
+- {Goal 1}
+- {Goal 2}
+
+**Non-Goals:**
+
+- {Explicitly out of scope}
+
+**Success Criteria:**
+
+- {Measurable outcome}
+
+## 🙋 User's Explanation
+
+{Explain as if teaching a user. New concepts, UX, impact on existing features.}
+
+## 👷 Engineer's Explanation
+
+{Technical design. System interactions. Corner cases with examples.}
+
+## ⚠️ Drawbacks
+
+{Why should we NOT do this? Tradeoffs? New challenges?}
+
+## 🤔 Rationale and Alternatives
+
+{Why this design? Alternatives considered? Impact of not doing this?}
+
+## 💸 Cost and Operations
+
+{Infrastructure costs, LLM call estimates, operational complexity, deployment targets.}
+
+## 🌸 Prior Art
+
+{Similar systems, lessons learned, good and bad examples.}
+
+## ❓ Unresolved Questions
+
+{What to resolve during RFC review? Out of scope follow-ups?}
+
+## 🚀 Future Possibilities
+
+{Natural extensions, long-term vision, related ideas for later.}
+```
+
+## Question Bank by Section
+
+Reference questions to draw from (select most relevant, don't ask all):
+
+### Summary
+
+- Can you distill this to one sentence: "We will {action} so that {outcome}"?
+- What's the elevator pitch for stakeholders who have 30 seconds?
+- Is there a working title that captures the essence?
+
+### Motivation
+
+- What's the business driver? Revenue, retention, competitive pressure?
+- What user pain point does this address?
+- Why now vs. 6 months from now?
+- What happens if we don't do this?
+- Is there a specific user request or feedback driving this?
+
+### Goals and Non-Goals
+
+- What's the minimum viable version of this feature?
+- What should we explicitly NOT build in v1?
+- How will we measure success? (metrics, user feedback, etc.)
+- What's the failure mode we're most worried about?
+- Are there phasing considerations (v1, v2, future)?
+
+### User's Explanation
+
+- How does a user discover this feature?
+- What's the primary interaction flow?
+- How does this change existing workflows?
+- Are there new concepts users need to learn?
+- What's the "aha moment" for users?
+
+### Engineer's Explanation
+
+- What existing services/components does this touch?
+- What new services or data stores are needed?
+- How does data flow through the system?
+- What are the critical integration points?
+- What's the most technically risky part?
+
+### Drawbacks
+
+- What's the biggest technical risk?
+- What user experience tradeoffs are we making?
+- What maintenance burden does this add?
+- Could this break existing functionality?
+- What's the worst-case failure scenario?
+
+### Rationale and Alternatives
+
+- What other approaches did you consider?
+- Why is this approach better than {alternative}?
+- Is there an off-the-shelf solution we're rejecting?
+- What would a simpler version look like?
+- What would we do with 10x the resources?
+
+### Cost and Operations
+
+- What new infrastructure is required?
+- Are there new vendor dependencies?
+- What's the estimated LLM cost per user/query?
+- How does this affect deployment targets (BYOC, etc.)?
+- What monitoring/alerting do we need?
+
+### Prior Art
+
+- Are there similar features in competing products?
+- Have we built something similar before?
+- Are there open-source implementations to learn from?
+- What industry patterns apply here?
+- What cautionary tales should we heed?
+
+### Unresolved Questions
+
+- What technical spikes are needed before committing?
+- What stakeholder input is still needed?
+- Are there security/compliance reviews required?
+- What's blocked on external dependencies?
+- What decisions can be deferred to implementation?
+
+### Future Possibilities
+
+- What's the obvious v2 of this feature?
+- What adjacent features does this enable?
+- How does this fit the product roadmap?
+- What would we build if this succeeds wildly?
+- Are there platform/API implications?
+
+## Notes
+
+- Stay in plan mode throughout questioning — no file writes until acceptance
+- Questions should build on previous answers — don't ask in isolation
+- If user seems fatigued, offer to batch remaining sections with reasonable defaults
+- Codebase exploration informs questions but isn't shared verbatim
+- RFC quality depends on question quality — invest in understanding the feature