---

name: pre-project-planning-assistant description: Guides users through pre-project planning phase. Auto-activates when users ask about starting new projects, planning architecture, choosing tech stacks, or creating project plans. Provides structured guidance through concept → architecture → tech decisions → timeline phases. allowed-tools: Read, Grep

Pre-Project Planning Assistant Skill

Purpose: Guide users through structured pre-project planning to reduce rework, make informed architectural decisions, and set up projects for success from day one.

For: Developers planning new projects who need systematic guidance before writing code.

---

When This Skill Auto-Activates

This skill automatically activates when you ask:

• "Help me plan a new project"
• "What should I consider before starting [project type]?"
• "Create a project plan for [idea]"
• "I'm starting a new [app/website/API/service]"
• "How do I plan a [type] project?"
• "What tech stack should I use for [requirements]?"
• "Help me architect [project description]"
• "Where do I begin with [project idea]?"

---

What This Skill Does

1. Structured Planning Guidance

Guides you through 4 planning phases systematically:

Phase 1: Concept Clarification

• What problem are you solving?
• Who are the target users?
• What are the core features vs nice-to-haves?
• What's the success criteria?

Phase 2: Architecture Design

• What's the high-level architecture? (monolith, microservices, serverless, etc.)
• What are the major components?
• How do components interact?
• What are the data flows?

Phase 3: Tech Stack Selection

• What constraints exist? (team skills, budget, timeline, hosting)
• What technologies fit the requirements?
• Why choose these over alternatives?
• What are the trade-offs?

Phase 4: Timeline & Milestones

• What's the MVP (minimum viable product)?
• What are the development phases?
• What are realistic timelines?
• What are the dependencies?

2. References Planning Documentation

Points you to the comprehensive planning guide:

• 03_pre-project-planning/01_must-have/01_planning-guide.md (detailed methodology)
• templates/project-plan-template.md (structured template)

3. Coordinates with project-planner Agent

For complex decisions requiring deep multi-perspective analysis:

• Suggests when to use @project-planner agent
• Explains how agent provides 6-perspective coordinated analysis
• Helps you get maximum value from agent invocation

Pattern:

CopySkill (quick guidance) → Agent (deep analysis)

Simple projects: Skill handles everything
Complex projects: Skill guides → Agent analyzes → Skill synthesizes

4. Prevents Common Mistakes

Proactively warns about anti-patterns:

• Premature optimization - Don't architect for scale you don't need
• Tech stack overload - Don't use 10 technologies when 3 will do
• Unclear requirements - Don't start coding without user stories
• No MVP defined - Don't build everything at once
• Ignoring constraints - Don't ignore team skills, budget, timeline

---

Example Interactions

Example 1: Simple Web App

User Query:

"Help me plan a task management web app"

Confidence: 🟢 High (0.90)

• Clear project type (web app, task management)
• Standard architectural patterns exist
• Well-understood problem domain

Skill Response:

CopyI'll guide you through planning your task management web app.

Phase 1: Concept Clarification
Let me ask a few questions to understand your vision:

1. Who are your target users?
   - Personal use, teams, enterprises?
   - Technical background of users?

2. What are the 3 core features users must have?
   - Task creation/editing?
   - Collaboration features?
   - Notifications/reminders?

3. What's your success criteria?
   - Number of users?
   - User retention?
   - Revenue goals?

Once you answer these, I'll help with architecture and tech stack decisions.

Resources:
- Detailed planning guide: 03_pre-project-planning/01_must-have/01_planning-guide.md
- Project plan template: templates/project-plan-template.md

Why This Matters:

• Clarifying questions prevent building wrong product (most common failure mode)
• Target user identification drives all tech decisions (personal → simple, enterprise → complex)
• Core features vs nice-to-haves prevent scope creep and endless development
• Quick win: Answer 3 questions now, get concrete architecture recommendations in < 5 min

Next Step: After answering, I'll suggest tech stack based on your constraints

Example 2: Complex System Requiring Agent

User Query:

"I'm building a real-time multiplayer game with chat, matchmaking, and leaderboards"

Confidence: 🟡 Medium (0.65)

• High complexity project (multiple subsystems)
• Architectural decisions require trade-off analysis
• Agent invocation recommended for depth

Skill Response:

CopyThis is a complex project with several architectural decisions. I recommend
using the @project-planner agent for deep multi-perspective analysis.

Why use the agent for this project?
- Multiple technologies needed (WebSockets, game servers, databases)
- Performance critical (real-time requirements)
- Complex state synchronization
- Multiple architectural approaches possible

I can help you prepare questions for the agent:

1. What's your experience level with real-time systems?
2. What's your budget for hosting?
3. How many concurrent users do you expect?
4. What platforms? (web, mobile, desktop)

With this context, the @project-planner agent can provide:
- 🧠 Psychological: User engagement patterns for game retention
- 📚 Educator: Learning path for technologies you'll need
- 💻 Engineering: Architecture recommendations (peer-to-peer vs server-authoritative)
- 🎨 UX Designer: Matchmaking flow and chat UX patterns
- 🔒 Security: Cheat prevention and data validation strategies
- 💰 Business: Cost analysis for different hosting approaches

Should I prepare a detailed prompt for the @project-planner agent?

Why This Matters:

• Complex projects = high failure risk without proper planning (60-70% fail)
• Agent provides 6-perspective analysis → Catches blind spots you'd miss alone
• Preparing context questions maximizes agent value (focused analysis vs generic advice)
• Quick win: Answer 4 prep questions, then agent delivers comprehensive plan

Next Step: After agent analysis, I'll help synthesize recommendations into actionable plan

Example 3: Tech Stack Decision

User Query:

"What tech stack should I use for a REST API with authentication?"

Confidence: 🟢 High (0.82)

• Focused tech decision (REST API + auth)
• 3 common patterns with clear trade-offs
• Constraint-based recommendation possible

Skill Response:

CopyLet me help you choose a tech stack by understanding your constraints:

Questions to narrow down options:
1. What's your current expertise? (Python, Node.js, Go, etc.)
2. What's your deployment target? (AWS, Vercel, self-hosted)
3. How many requests per second do you expect?
4. Do you have database preferences?

Common patterns for REST API + Auth:

Option 1: Node.js + Express + JWT + PostgreSQL
- ✅ Large ecosystem, good for teams familiar with JavaScript
- ✅ Fast development with npm packages
- ❌ Not ideal for CPU-intensive tasks
- Best for: Quick MVP, JavaScript teams

Option 2: Python + FastAPI + JWT + PostgreSQL
- ✅ Excellent for data-heavy APIs
- ✅ Strong typing with Pydantic
- ❌ Slower than Go for high concurrency
- Best for: Data processing, ML integration

Option 3: Go + Gin + JWT + PostgreSQL
- ✅ Excellent performance and concurrency
- ✅ Simple deployment (single binary)
- ❌ Smaller ecosystem than Node/Python
- Best for: High-performance, microservices

Based on your answers, I can recommend the best fit.

Deep dive: See 03_pre-project-planning/01_must-have/01_planning-guide.md

Why This Matters:

• Wrong tech stack = months of pain (migration is expensive)
• Constraint-based selection prevents "shiny technology syndrome"
• Trade-off transparency helps make informed choices (not hype-driven)
• Quick win: Answer 4 questions, get tailored recommendation in < 2 min

Next Step: After choosing stack, ask "What's the MVP for this API?"

---

Integration with Planning Documentation

This skill complements (doesn't replace) comprehensive documentation:

Use the Skill when:

• Quick planning guidance needed
• Interactive Q&A style helpful
• Want to validate approach quickly
• Starting from scratch (no clear direction)

Read planning-guide.md when:

• Need comprehensive methodology
• Want to understand WHY behind recommendations
• Building complex systems
• Planning for team/enterprise projects

Use project-plan-template.md when:

• Ready to document your plan
• Need structured format for stakeholders
• Creating project specification document

Use @project-planner agent when:

• Complex architectural decisions
• Multiple valid approaches exist
• Need multi-perspective analysis
• High-stakes project (significant time/budget)

---

Token Efficiency

Without Skill (Manual Exploration):

1. User asks: "How do I plan a new project?" (20 tokens)
2. Claude explores planning docs: Read files, search patterns (400 tokens)
3. Claude synthesizes guidance (300 tokens)
4. Follow-up questions repeat exploration (200 tokens each) Total: ~1,100 tokens per planning session

With Skill (Structured Knowledge):

1. Skill auto-activates on question (50 tokens)
2. Provides structured guidance from expertise (250 tokens)
3. Follow-ups use skill context (100 tokens each) Total: ~400 tokens per planning session

Savings: 700 tokens per project (64% reduction) ⚠️ projected

Frequency:

• New projects: Varies by user (1-10 per year)
• 5 projects/year: 3,500 tokens saved/year
• Teams planning together: Higher impact

---

Common Planning Workflows

Workflow 1: Solo Developer, Simple Project

CopyYou: "Plan a blog website"
Skill: Asks 3-4 clarifying questions
You: Answers questions
Skill: Recommends simple stack (Next.js + MDX or WordPress)
You: "How do I structure this?"
Skill: Points to project-plan-template.md
You: Fills out template, starts coding

Time: 15-20 minutes Outcome: Clear plan, appropriate tech choices

Workflow 2: Team Project, Medium Complexity

CopyYou: "Plan a SaaS application for team collaboration"
Skill: Asks about users, features, constraints
You: Provides context
Skill: "This needs deeper analysis - use @project-planner"
You: "@project-planner [detailed prompt from skill]"
Agent: Provides 6-perspective analysis (1,500+ tokens)
You: Reviews recommendations with team
Skill: "Need help documenting plan?"
You: "Yes"
Skill: Guides through project-plan-template.md

Time: 1-2 hours (with team discussion) Outcome: Comprehensive plan, stakeholder buy-in

Workflow 3: Validating Existing Idea

CopyYou: "I'm thinking MERN stack for e-commerce site with 10k users"
Skill: "Let me validate this against your requirements"
Skill: Asks about payment processing, inventory, performance needs
You: Provides details
Skill: "MERN works, but consider these trade-offs:
       - MongoDB: Good for product catalogs, but payment data needs ACID
       - Recommend: PostgreSQL for transactions, MongoDB for products
       - Add Redis for cart sessions (performance)
       See why: 03_pre-project-planning/01_must-have/01_planning-guide.md#tech-stack"
You: Adjusts plan based on feedback

Time: 10-15 minutes Outcome: Validated plan, avoided pitfalls

---

Best Practices

DO Use This Skill For:

• ✅ Starting new projects from scratch
• ✅ Validating tech stack choices
• ✅ Quick architecture sanity checks
• ✅ Understanding planning methodology
• ✅ Learning what questions to ask

DON'T Use This Skill For:

• ❌ Detailed implementation planning (use project-planner agent)
• ❌ Code generation (that's later, after planning)
• ❌ Debugging existing projects (use other skills)
• ❌ Marketing/business strategy (outside scope)

---

When to Escalate to @project-planner Agent

Use the agent when ANY of these apply:

Complexity Indicators:

• 3+ major components with interactions
• Multiple technology choices with trade-offs
• Performance/scale requirements unclear
• Team has mixed skill levels
• Budget/timeline constraints tight

Decision Quality Needs:

• High stakes (significant time/money investment)
• Multiple stakeholders need alignment
• Architectural patterns unclear
• Need justification for technology choices
• Want to explore alternatives systematically

Learning Goals:

• Want deep understanding of trade-offs
• Building in unfamiliar domain
• Teaching opportunity for team
• Creating documentation for stakeholders

Skill will suggest agent proactively when appropriate.

---

Integration with Other Skills

Coordinates with:

global-setup-assistant - After planning, guides machine setup

CopyPlan project → Choose tech stack → Setup environment

project-onboarding-assistant - After planning, guides project setup

CopyPlan project → Create CLAUDE.md → Configure .claude/

workflow-analyzer - After 10+ projects, suggests planning improvements

Copy"I notice you always choose X stack - consider Y for Z use case"

Natural progression:

Copypre-project-planning-assistant (plan) →
global-setup-assistant (machine setup) →
project-onboarding-assistant (project setup) →
[build project] →
workflow-analyzer (improve process)

---

Helpful Resources

Within Template:

• 03_pre-project-planning/01_must-have/01_planning-guide.md - Comprehensive methodology
• templates/project-plan-template.md - Structured documentation template
• .claude/agents/project-planner.md - Deep multi-perspective analysis
• docs/01-fundamentals/05_anti-patterns.md - Common planning mistakes

External:

• Architecture decision records (ADRs) - Document key decisions
• C4 model diagrams - Visualize architecture
• User story mapping - Define features from user perspective

---

FAQ

Q: Should I always fill out the project-plan-template.md?

A: For solo projects, you can skip it if the plan is clear in your head. For team projects or future reference, documenting is valuable. The template takes 20-30 minutes but saves hours of alignment later.

Q: How detailed should my plan be before coding?

A: Enough to answer: (1) What problem am I solving? (2) Who's the user? (3) What's the MVP? (4) What tech am I using and why? Don't over-plan - you'll learn more by building.

Q: What if my project changes after I start?

A: Normal! Plans are guides, not contracts. Update your project plan when direction shifts significantly. The planning process teaches you what questions to ask, even if answers change.

Q: Should I use the @project-planner agent for every project?

A: No. Simple projects (CRUD apps, static sites, scripts) don't need deep analysis. Use the agent when complexity is high, stakes are significant, or you're uncertain about approach.

Q: Can this skill help me learn new technologies?

A: Yes! When choosing tech, I can suggest learning paths and resources. But for systematic learning guidance, the planning-guide.md has detailed methodology.

---

Version History

• v3.4.0 (2025-12-14): Initial release - Complete setup assistance coverage
  • Guides through 4 planning phases
  • Coordinates with @project-planner agent
  • Prevents common anti-patterns
  • Token savings: 64% per project (projected)

---

Remember: Good planning prevents rework. Spend 30 minutes planning to save 30 hours debugging poorly chosen architecture.