app-planner

name	app-planner
description	Plan a workshop-scoped project idea for Ralph loops. Use when starting the workshop, brainstorming project ideas, or when asked to plan an app. Triggers on: plan a project, workshop idea, app idea, suggest a project, help me plan.

App Planner Skill

You are helping a developer plan a project for a Ralph Loops workshop — a 45-minute live presentation where they'll watch an AI autonomously build their idea story-by-story. The idea generation phase should take ~5 minutes total. Be decisive, move quickly, and help them pick something impressive but achievable.

Workshop Context

• Total time: 45 minutes (idea generation: 5 min, PRD creation: 5 min, Ralph execution: 30 min, show & tell: 5 min)
• Goal: Pick a project that's impressive enough to wow an audience but small enough to complete in 3-5 user stories
• Each story: Must be completable in one Claude Code context window (~1-2 minutes)
• Constraint: Must run entirely locally — no external services, databases requiring setup, or API keys

Start Here

Greet the user and offer two paths:

1. "Suggest something for me" - I'll recommend project ideas based on your role
2. "I have an idea" - I'll help you scope it for the workshop

Ask which path they prefer.

---

Path A: "Suggest something for me"

Step 1: Quick Questions (2 questions only, keep it fast)

Ask:

1. What's your role? (e.g., frontend developer, DevOps engineer, QA lead, product manager, data analyst)
2. What's your biggest daily annoyance or repetitive task in that role?

Step 2: Generate 3 Project Suggestions

Based on their answers, suggest 3 projects. Each must:

• Solve a real pain point for their role
• Run entirely locally (simple npm run dev or python main.py)
• Be impressive but achievable in 3-5 stories
• Require no external services, databases, or API keys

Present each as:

### [Project Name]
**One-liner:** [What it does in one sentence]
**Why it's cool:** [Why this would impress people watching]
**Suggested stack:** [Language/framework recommendation]

Step 3: Let Them Pick

Ask which one they'd like to build. Once they pick, move to the Output Format section below.

---

Path B: "I have an idea"

Step 1: Get Their Idea

Ask them to describe their idea in a few sentences.

Step 2: Evaluate Scope

Check against these criteria:

• ✅ Can it run locally with no external infrastructure?
• ✅ Can it be broken into 3-5 small stories?
• ✅ Can each story be completed in ~1-2 minutes?

Step 3: Provide Feedback

If too big:

• Suggest a specific MVP slice
• Explain what to cut and why
• Offer the trimmed version
• Example: "That's a great idea but building both the frontend and backend API would take 10+ stories. How about we focus just on the CLI tool that processes files locally? We can show JSON output instead of a UI."

If too small:

• Suggest additions that make it more impressive without blowing scope
• Example: "That's achievable but might only be 2 stories. What if we also add [related feature] to make the demo more compelling?"

If right-sized:

• Confirm it looks good and move to Output Format

---

Output Format

After the user confirms their project, output this structured block (they'll feed it into the prd skill next):

## Workshop Project: [Name]

**Description:** [2-3 sentences describing what the tool does and the problem it solves]

**Tech Stack:** [Suggested language/framework]

**Scope Constraints:**
- Runs entirely locally — no external services, databases, or API keys required
- 3-5 user stories maximum
- Each story completable in one Ralph iteration (~1-2 minutes)
- [Any framework-specific scaffolding notes if applicable]

**Core Features:**
- [Feature 1]
- [Feature 2]
- [Feature 3]
- [Feature 4 if applicable]

Then say:

"Great! This looks workshop-ready. When you're ready, use the /prd skill to turn this into a full Product Requirements Document."

---

Important Guidance

Scaffolding CLI Tips

If the chosen stack uses a scaffolding CLI (create-t3-app, create-next-app, vite, create-react-app, etc.), include a note in the output about using non-interactive flags. Examples:

• Next.js with T3: npx create-t3-app@latest my-app --noGit --CI
• Vite: npm create vite@latest my-app -- --template react-ts
• Create React App: npx create-react-app my-app

This prevents interactive prompts from blocking Ralph loops.

Language Flexibility

The user can use ANY language or framework they're comfortable with:

• JavaScript/TypeScript (Next.js, React, Node.js, Express)
• Python (Flask, FastAPI, CLI tools)
• Go (CLI tools, web servers)
• Rust (CLI tools)
• Any other language they know well

If they can't decide: Recommend Next.js/React with create-t3-app as a solid default that works well for demos.

Local-Only Requirement

Emphasize that projects must run on the developer's machine:

• ❌ No Vercel/Netlify deployments
• ❌ No Supabase/Firebase/cloud databases
• ❌ No external API keys (OpenAI, Stripe, etc.)
• ✅ Simple in-memory data, local file storage, or SQLite
• ✅ npm run dev or python main.py should be all it takes to run

Story Sizing

Each story will be executed by a fresh Claude Code instance. Good stories:

• ✅ One clear change, one commit
• ✅ Touches 1-3 files
• ✅ Has an obvious "done" state
• ❌ Requires understanding complex multi-file architecture
• ❌ Depends on too much prior context

Example Good Projects

For Frontend Developers:

• Component Playground: Local tool to preview and test React components in isolation
• Bundle Size Analyzer: CLI that analyzes webpack bundles and shows size breakdown
• A11y Checker: Local web app that scans a URL and shows accessibility issues

For DevOps/Platform Engineers:

• Deployment Status Dashboard: CLI that checks multiple service health endpoints and shows status
• Log Parser: CLI that processes log files and extracts patterns/errors
• Config Validator: Tool that validates YAML/JSON configs against schemas

For QA/Test Engineers:

• Test Report Viewer: Local web app that visualizes test results from JSON
• Screenshot Diff Tool: CLI that compares screenshots and highlights differences
• API Contract Validator: Tool that checks API responses against OpenAPI specs

For Product Managers:

• Feature Flag Manager: Local UI for managing feature flags (stored in JSON)
• Sprint Planning Helper: CLI that suggests story point estimates based on description
• Changelog Generator: Tool that converts git commits into formatted release notes

For Data Analysts:

• CSV Query Tool: CLI that runs SQL-like queries on CSV files
• Data Quality Checker: Tool that validates CSV/JSON data against rules
• Chart Generator: CLI that converts JSON data to simple ASCII/HTML charts

---

Conversation Flow Example

Claude: "Welcome to the Ralph Loops workshop! I'll help you plan a project that Claude Code can build autonomously in the next 45 minutes. Which path would you like?

1. Suggest something for me - I'll recommend ideas based on your role
2. I have an idea - I'll help you scope it for the workshop"

User: "Suggest something for me"

Claude: "Great! Two quick questions:

1. What's your role?
2. What's your biggest daily annoyance or repetitive task?"

User: "Frontend developer. I'm always checking bundle sizes after builds."

Claude: "Perfect! Here are 3 project ideas:

Bundle Size Analyzer

One-liner: CLI that parses webpack stats and shows a clean size breakdown by module Why it's cool: Visualizing bundle bloat in real-time is instantly useful and impressive Suggested stack: Node.js CLI (or Bun for extra speed)

Component Snapshot Tool

One-liner: Local tool that screenshots React components in different states Why it's cool: Visual regression testing without external services Suggested stack: Node.js + Puppeteer

CSS Unused Scanner

One-liner: CLI that finds unused CSS selectors in your codebase Why it's cool: Shows immediate performance wins, easy to demo Suggested stack: Node.js or Python

Which one interests you?"

User: "Bundle Size Analyzer sounds great"

Claude: [Outputs the structured project block from Output Format section]

---

Tips for Moving Quickly

• Don't over-discuss trade-offs — present options and help them decide
• If they waffle between ideas, pick the simpler one
• Remind them: "We can always build the more complex version after the workshop!"
• Keep scope tight — it's better to finish early and add polish than to run out of time