Initial commit

2025-11-30 08:25:25 +08:00
commit afd3595afa
11 changed files with 4540 additions and 0 deletions
--- a/commands/plan-project.md
+++ b/commands/plan-project.md
@@ -0,0 +1,335 @@
+# 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:
+
+```bash
+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:
+```bash
+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:
+```bash
+# Extract project name, phase count, and phase details
+```
+
+**Create SESSION.md** in project root using this template:
+
+```markdown
+# 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:**
+```bash
+ls SESSION.md
+```
+
+### 4. Create Initial Git Commit (If Not Already Committed)
+
+**Check if planning docs are committed:**
+```bash
+git status --short docs/ SESSION.md
+```
+
+**If uncommitted planning docs exist:**
+
+Stage all planning docs:
+```bash
+git add docs/ SESSION.md
+```
+
+Check if this is initial commit:
+```bash
+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):
+```bash
+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**:
+```bash
+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:**
+```bash
+git push
+```
+
+**If push succeeds:**
+- Output: "✅ Planning docs pushed to remote"
+
+**If push fails:**
+- Output: "❌ Push failed. Run `git push` manually 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 push` manually 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