9.9 KiB
Plan Project
Automate initial project planning: gather requirements, generate planning docs, create SESSION.md, and prepare for Phase 1.
Your Task
Follow these steps to take a project from description to ready-to-code state.
0. Check for PROJECT_BRIEF.md (Optional)
If PROJECT_BRIEF.md exists in project root or planning/ directory:
ls PROJECT_BRIEF.md planning/PROJECT_BRIEF.md 2>/dev/null
If found:
- Read PROJECT_BRIEF.md first
- Extract validated scope, tech stack, and constraints
- Use as context for project-planning skill invocation
- Skip redundant questions (tech stack and scope decisions already validated in brief)
Note: PROJECT_BRIEF.md is created by the /explore-idea command during pre-planning exploration. It contains research findings and validated decisions that streamline the planning process.
If not found:
- Continue normally to step 1
- project-planning skill will handle all requirements gathering
1. Invoke project-planning Skill
If project description is vague or incomplete, ask 1-2 clarifying questions first:
- "What's the core functionality? (e.g., task manager, blog, analytics dashboard)"
- "Any specific tech requirements beyond the default stack?"
Then invoke the project-planning skill with the project description:
- The skill will handle all clarifying questions (auth, data model, features, scope)
- The skill will generate appropriate planning docs (IMPLEMENTATION_PHASES.md + others as needed)
- Wait for skill to complete and output planning docs
Note: Do NOT ask the same questions the skill will ask. Let the skill handle requirements gathering.
2. Verify Planning Docs Exist
Check that these files were created:
docs/IMPLEMENTATION_PHASES.md(required)- Other docs as generated (DATABASE_SCHEMA.md, API_ENDPOINTS.md, etc.)
Run:
ls docs/IMPLEMENTATION_PHASES.md
If IMPLEMENTATION_PHASES.md doesn't exist:
- Output: "❌ Planning failed. IMPLEMENTATION_PHASES.md not found."
- Output: "The project-planning skill should have created this file. Try running the skill manually."
- Stop here
3. Create SESSION.md
Read IMPLEMENTATION_PHASES.md to extract phases:
# Extract project name, phase count, and phase details
Create SESSION.md in project root using this template:
# Session State
**Current Phase**: Phase 1
**Current Stage**: Implementation
**Last Checkpoint**: [none yet] ([date])
**Planning Docs**: `docs/IMPLEMENTATION_PHASES.md`[, `docs/DATABASE_SCHEMA.md`][, other docs...]
---
## Phase 1: [Phase Name] 🔄
**Type**: [Type] | **Started**: [date]
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-1`
**Progress**:
- [ ] [First task from IMPLEMENTATION_PHASES.md]
- [ ] [Second task]
- [ ] [Third task]
**Next Action**: [Concrete first action from phase tasks]
**Key Files**:
- [List key files from phase]
**Known Issues**: None
## Phase 2: [Phase Name] ⏸️
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-2`
## Phase 3: [Phase Name] ⏸️
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-3`
[... list all remaining phases with ⏸️ status ...]
Verify SESSION.md created:
ls SESSION.md
4. Create Initial Git Commit (If Not Already Committed)
Check if planning docs are committed:
git status --short docs/ SESSION.md
If uncommitted planning docs exist:
Stage all planning docs:
git add docs/ SESSION.md
Check if this is initial commit:
git log --oneline | wc -l
Create structured commit:
Extract from IMPLEMENTATION_PHASES.md:
- Total number of phases
- Estimated total hours
- Phase names
If this is first commit (count = 0):
git commit -m "$(cat <<'EOF'
Initial project planning
Generated planning documentation:
- IMPLEMENTATION_PHASES.md ([N] phases, ~[X] hours)
[- DATABASE_SCHEMA.md]
[- API_ENDPOINTS.md]
[- ARCHITECTURE.md]
[- other docs...]
- SESSION.md (session tracking)
Next: Start Phase 1 - [Phase 1 Name]
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
If not first commit:
git commit -m "$(cat <<'EOF'
Add project planning documentation
Generated planning docs:
- IMPLEMENTATION_PHASES.md ([N] phases, ~[X] hours)
[- DATABASE_SCHEMA.md]
[- API_ENDPOINTS.md]
[- other docs...]
- SESSION.md (session tracking)
Next: Start Phase 1 - [Phase 1 Name]
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
If no changes to commit:
- Output: "ℹ️ Planning docs already committed."
- Skip to step 5
5. Output Planning Summary
Display a formatted summary of what was created:
═══════════════════════════════════════════════
PROJECT PLANNING COMPLETE
═══════════════════════════════════════════════
📋 Project: [Project Name from IMPLEMENTATION_PHASES.md]
📦 Stack: [Frontend + Backend + Database from docs]
⏱️ Estimated: [Total hours] (~[human minutes] human time)
───────────────────────────────────────────────
PLANNING DOCS CREATED:
───────────────────────────────────────────────
✅ IMPLEMENTATION_PHASES.md ([N] phases)
✅ SESSION.md (progress tracker)
[✅ DATABASE_SCHEMA.md] (if created)
[✅ API_ENDPOINTS.md] (if created)
[✅ ARCHITECTURE.md] (if created)
[... other docs if created ...]
───────────────────────────────────────────────
PHASES OVERVIEW:
───────────────────────────────────────────────
Phase 1: [Name] ([Type], [X] hours) 🔄 ← CURRENT
Phase 2: [Name] ([Type], [X] hours) ⏸️
Phase 3: [Name] ([Type], [X] hours) ⏸️
[... list all phases with emoji status ...]
───────────────────────────────────────────────
NEXT ACTION (Phase 1):
───────────────────────────────────────────────
[Concrete next action from SESSION.md]
File: [file path if applicable]
Task: [specific action to take]
───────────────────────────────────────────────
KEY FILES TO KNOW:
───────────────────────────────────────────────
• SESSION.md - Track progress, current state
• docs/IMPLEMENTATION_PHASES.md - Full phase details
[• docs/[other docs]] (if applicable)
═══════════════════════════════════════════════
6. Ask Permission to Start Phase 1
Ask user:
Ready to start Phase 1: [Phase Name]?
Options:
1. Yes - proceed with Phase 1 Next Action
2. Review first - I want to review planning docs
3. Adjust - I want to refine some phases
Your choice (1/2/3):
If choice 1 (Yes):
- Output: "Starting Phase 1: [Phase Name]"
- Read Next Action from SESSION.md
- Begin executing the Next Action
- Use appropriate tools (Write, Edit, Bash, etc.)
If choice 2 (Review first):
- Output: "Planning docs are in docs/ directory. Review and let me know when ready to start."
- Wait for user instructions
If choice 3 (Adjust):
- Output: "What would you like to adjust?"
- Wait for user feedback
- Offer to regenerate planning docs or manually edit
7. Optional: Push to Remote
After user starts Phase 1 or reviews docs, ask:
Push planning docs to remote? (y/n)
If yes:
git push
If push succeeds:
- Output: "✅ Planning docs pushed to remote"
If push fails:
- Output: "❌ Push failed. Run
git pushmanually when ready."
Error Handling
project-planning skill invocation fails:
- Output: "❌ Failed to invoke project-planning skill"
- Output: "Try running: Use the project-planning skill to plan this project"
- Stop
IMPLEMENTATION_PHASES.md not created:
- Output: "❌ Planning docs not found"
- Suggest: "project-planning skill should have created them. Check for errors."
- Stop
SESSION.md creation fails:
- Output: "⚠️ SESSION.md creation failed: [error]"
- Output: "You can create it manually or try again."
- Stop
Git commit fails:
- Output: "⚠️ Git commit failed: [error message]"
- Output: "Fix git issue and commit manually, or continue without commit."
- Ask: "Continue without commit? (y/n)"
Git push fails:
- Output: "⚠️ Push failed: [error message]"
- Output: "You can run
git pushmanually later." - Continue (not critical)
No git repository:
- Output: "⚠️ Not a git repository. Initialize with
git init? (y/n)" - If yes: Run
git init && git add . && git commit -m "Initial commit" - If no: Continue without git
Project description too vague:
- Output: "❌ Project description unclear"
- Ask 1-2 clarifying questions before invoking skill:
- "What's the core functionality?"
- "Any specific tech requirements?"
IMPLEMENTATION_PHASES.md exists but empty:
- Output: "❌ IMPLEMENTATION_PHASES.md is empty"
- Suggest: "project-planning skill may have failed. Check output for errors."
- Stop
Success Criteria
✅ project-planning skill invoked successfully ✅ IMPLEMENTATION_PHASES.md created with validated phases ✅ SESSION.md created with Phase 1 as current ✅ Planning docs committed to git (if git repo exists) ✅ User has clear "Next Action" to start Phase 1 ✅ User knows where to find all planning docs