Initial commit
This commit is contained in:
Zhongwei Li
277
commands/continue-session.md
Normal file
277
commands/continue-session.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# Continue Session
|
||||
|
||||
Quickly continue work by loading context from SESSION.md, showing current state, and continuing from "Next Action".
|
||||
|
||||
---
|
||||
|
||||
## Your Task
|
||||
|
||||
Follow these steps to load session context and resume work efficiently.
|
||||
|
||||
### 1. Load Session Context (Use Explore Agent)
|
||||
|
||||
Use the Task tool with subagent_type="Explore" and description "Load session context for resuming work" to gather:
|
||||
- Find and read SESSION.md
|
||||
- Find and read IMPLEMENTATION_PHASES.md (focus on current phase section)
|
||||
- Extract current phase number and name
|
||||
- Extract current stage (Implementation/Verification/Debugging)
|
||||
- Extract last checkpoint hash and date
|
||||
- Extract "Next Action" (file + line + what to do)
|
||||
- Extract known issues
|
||||
- Extract progress (completed and pending tasks)
|
||||
- Get list of planning docs mentioned in SESSION.md
|
||||
- Run `git log --oneline -5` for recent commits
|
||||
- Run `git status` for uncommitted changes
|
||||
|
||||
**If SESSION.md doesn't exist:**
|
||||
- Output: "❌ No SESSION.md found. Is this a new project?"
|
||||
- Suggest: "Run project-planning skill to set up session management."
|
||||
- Stop here
|
||||
|
||||
**If IMPLEMENTATION_PHASES.md doesn't exist:**
|
||||
- Output: "⚠️ Warning: No IMPLEMENTATION_PHASES.md found."
|
||||
- Output: "Continuing with SESSION.md only. Some context may be limited."
|
||||
- Continue anyway
|
||||
|
||||
### 2. Check for Uncommitted Changes
|
||||
|
||||
If `git status` shows uncommitted changes:
|
||||
- Output warning:
|
||||
```
|
||||
⚠️ WARNING: Uncommitted changes detected!
|
||||
|
||||
Uncommitted files:
|
||||
[list files from git status]
|
||||
|
||||
These changes weren't checkpointed. Continue anyway? (y/n)
|
||||
```
|
||||
|
||||
**If user says no:**
|
||||
- Output: "Stopping. Run /wrap-session to checkpoint changes first."
|
||||
- Stop here
|
||||
|
||||
**If user says yes:**
|
||||
- Output: "⚠️ Proceeding with uncommitted changes. Remember to checkpoint later."
|
||||
- Continue
|
||||
|
||||
### 3. Show Recent Git History
|
||||
|
||||
Output formatted git history:
|
||||
|
||||
```
|
||||
📜 Recent Commits (last 5):
|
||||
|
||||
[hash] [commit message line 1]
|
||||
[hash] [commit message line 1]
|
||||
[hash] [commit message line 1]
|
||||
[hash] [commit message line 1]
|
||||
[hash] [commit message line 1]
|
||||
|
||||
Current checkpoint: [hash from SESSION.md] ([date])
|
||||
```
|
||||
|
||||
### 4. Display Session Summary
|
||||
|
||||
Output formatted summary:
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════
|
||||
WELCOME BACK TO [PROJECT NAME]
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
📋 Current Phase: Phase [N] - [Phase Name] ([Status emoji])
|
||||
📍 Current Stage: [Implementation/Verification/Debugging]
|
||||
💾 Last Checkpoint: [hash] ([date])
|
||||
|
||||
───────────────────────────────────────────────
|
||||
PROGRESS THIS PHASE:
|
||||
───────────────────────────────────────────────
|
||||
|
||||
✅ [completed task]
|
||||
✅ [completed task]
|
||||
✅ [completed task]
|
||||
🔄 [current pending task] ← CURRENT
|
||||
⏸️ [future pending task]
|
||||
⏸️ [future pending task]
|
||||
|
||||
───────────────────────────────────────────────
|
||||
KNOWN ISSUES:
|
||||
───────────────────────────────────────────────
|
||||
|
||||
• [issue 1]
|
||||
• [issue 2]
|
||||
[or "None" if no issues]
|
||||
|
||||
───────────────────────────────────────────────
|
||||
NEXT ACTION:
|
||||
───────────────────────────────────────────────
|
||||
|
||||
[Concrete next action from SESSION.md]
|
||||
File: [file path]
|
||||
Line: [line number] (if applicable)
|
||||
Task: [specific action to take]
|
||||
|
||||
───────────────────────────────────────────────
|
||||
PLANNING DOCS AVAILABLE:
|
||||
───────────────────────────────────────────────
|
||||
|
||||
✅ SESSION.md (loaded)
|
||||
✅ IMPLEMENTATION_PHASES.md (current phase loaded)
|
||||
• [other docs from SESSION.md] (available)
|
||||
|
||||
═══════════════════════════════════════════════
|
||||
```
|
||||
|
||||
### 5. Stage-Specific Context
|
||||
|
||||
**If current stage is "Verification":**
|
||||
- Read current phase verification criteria from IMPLEMENTATION_PHASES.md
|
||||
- Output:
|
||||
```
|
||||
───────────────────────────────────────────────
|
||||
VERIFICATION CHECKLIST (Current Phase):
|
||||
───────────────────────────────────────────────
|
||||
|
||||
[ ] [verification item 1]
|
||||
[ ] [verification item 2]
|
||||
[ ] [verification item 3]
|
||||
|
||||
Check these items before marking phase complete.
|
||||
───────────────────────────────────────────────
|
||||
```
|
||||
|
||||
**If current stage is "Debugging":**
|
||||
- Emphasize known issues
|
||||
- Output:
|
||||
```
|
||||
🐛 Currently debugging. Focus on resolving known issues above.
|
||||
```
|
||||
|
||||
**If current stage is "Implementation":**
|
||||
- No special output (normal flow)
|
||||
|
||||
### 6. Load Additional Planning Docs (Optional)
|
||||
|
||||
Check if SESSION.md references other planning docs (ARCHITECTURE.md, API_ENDPOINTS.md, DATABASE_SCHEMA.md, etc.)
|
||||
|
||||
If any are referenced, ask:
|
||||
```
|
||||
Additional planning docs available:
|
||||
• ARCHITECTURE.md
|
||||
• API_ENDPOINTS.md
|
||||
• [others...]
|
||||
|
||||
Would you like me to load any of these? (Enter doc names or 'none'):
|
||||
```
|
||||
|
||||
**If user specifies docs:**
|
||||
- Read the specified docs
|
||||
- Output: "✅ Loaded [doc list]"
|
||||
|
||||
**If user says "none":**
|
||||
- Output: "Continuing with loaded context only."
|
||||
|
||||
### 7. Offer to Open "Next Action" File
|
||||
|
||||
Extract file path from "Next Action".
|
||||
|
||||
Ask user:
|
||||
```
|
||||
Next Action file: [file path]
|
||||
|
||||
Would you like me to open this file? (y/n)
|
||||
```
|
||||
|
||||
**If yes:**
|
||||
- Use Read tool to open the file
|
||||
- If line number specified, focus on that area (offset/limit)
|
||||
- Output: "✅ Opened [file] at line [line]"
|
||||
|
||||
**If no:**
|
||||
- Output: "File not opened. You can request it when ready."
|
||||
|
||||
### 8. Offer to Proceed with Next Action
|
||||
|
||||
Ask user:
|
||||
```
|
||||
Ready to proceed with Next Action?
|
||||
|
||||
Next Action: [action description]
|
||||
|
||||
Options:
|
||||
1. Yes - proceed with this action
|
||||
2. No - I'll tell you what to do instead
|
||||
3. Context only - just keep loaded context, don't execute yet
|
||||
|
||||
Your choice (1/2/3):
|
||||
```
|
||||
|
||||
**If choice 1 (Yes):**
|
||||
- Output: "Proceeding with: [Next Action]"
|
||||
- Begin executing the Next Action
|
||||
- Use appropriate tools (Edit, Write, Bash, etc.)
|
||||
|
||||
**If choice 2 (No):**
|
||||
- Output: "What would you like to do instead?"
|
||||
- Wait for user to specify new direction
|
||||
- Update SESSION.md "Next Action" if user provides new task
|
||||
|
||||
**If choice 3 (Context only):**
|
||||
- Output: "Context loaded. Ready when you are."
|
||||
- Wait for user instructions
|
||||
|
||||
### 9. Final Confirmation
|
||||
|
||||
Output:
|
||||
```
|
||||
✨ Session resumed successfully!
|
||||
|
||||
Current context loaded:
|
||||
• Phase [N] progress
|
||||
• Next Action ready
|
||||
• [X] planning docs loaded
|
||||
|
||||
Ready to continue work.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**SESSION.md doesn't exist:**
|
||||
- Output: "❌ No SESSION.md found. Is this a new project?"
|
||||
- Suggest: "Run project-planning skill or create SESSION.md manually."
|
||||
- Stop
|
||||
|
||||
**IMPLEMENTATION_PHASES.md missing:**
|
||||
- Warning only, continue with SESSION.md
|
||||
- Output: "⚠️ IMPLEMENTATION_PHASES.md not found. Limited context available."
|
||||
|
||||
**Next Action is vague or missing:**
|
||||
- Output: "⚠️ Next Action is unclear or missing in SESSION.md."
|
||||
- Output: "Please update SESSION.md with specific: [file] + [line] + [action]"
|
||||
- Offer to help: "Would you like me to help you define the Next Action? (y/n)"
|
||||
|
||||
**File from Next Action doesn't exist:**
|
||||
- Output: "⚠️ File [path] from Next Action not found."
|
||||
- Ask: "Has it been moved or renamed? Should I search for it? (y/n)"
|
||||
|
||||
**Git commands fail:**
|
||||
- Output: "⚠️ Git history unavailable. Continuing without it."
|
||||
- Show SESSION.md context only
|
||||
|
||||
**Phase number mismatch:**
|
||||
- If SESSION.md phase doesn't match IMPLEMENTATION_PHASES.md:
|
||||
- Output: "⚠️ Phase mismatch detected between SESSION.md and IMPLEMENTATION_PHASES.md"
|
||||
- Output: "Using SESSION.md as source of truth."
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ User has full context of where they left off
|
||||
✅ Current phase progress is crystal clear
|
||||
✅ Next Action is specific and ready to execute
|
||||
✅ User can immediately continue work or adjust direction
|
||||
✅ All relevant planning docs are accessible
|
||||
✅ Recent git history provides continuity
|
||||
517
commands/explore-idea.md
Normal file
517
commands/explore-idea.md
Normal file
@@ -0,0 +1,517 @@
|
||||
# Explore Idea
|
||||
|
||||
Collaborative exploration and brainstorming for new project ideas. Validates scope, researches approaches, and creates decision-ready brief.
|
||||
|
||||
---
|
||||
|
||||
## Your Task
|
||||
|
||||
You are a product discovery partner helping the user explore a project idea BEFORE formal planning begins. Your goal is to:
|
||||
|
||||
1. **Understand the vision** through natural conversation
|
||||
2. **Research extensively** to find approaches, examples, and validate feasibility
|
||||
3. **Challenge assumptions** and prevent scope creep
|
||||
4. **Create decision artifact** (PROJECT_BRIEF.md) for handoff to /plan-project
|
||||
|
||||
**Critical**: This is collaborative exploration, NOT a questionnaire. Adapt your questions based on what the user shares.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Initial Understanding (Conversational)
|
||||
|
||||
**Start with**: "Let's explore this idea together. Tell me what you're thinking..."
|
||||
|
||||
**Listen for**:
|
||||
- Core problem/opportunity
|
||||
- Rough idea of solution
|
||||
- Tech preferences (if any)
|
||||
- Examples they've seen
|
||||
- Audience (individuals, SMEs, enterprise)
|
||||
- Context (exploring, learning, MVP, POC)
|
||||
|
||||
**Follow the conversation naturally**. If user provides rich detail, don't ask redundant questions. If vague, probe gently with open-ended questions.
|
||||
|
||||
**Key principle**: You're a thought partner, not an interviewer.
|
||||
|
||||
**Typical flow**:
|
||||
- User describes idea (1-3 sentences or detailed explanation)
|
||||
- You acknowledge and ask 1-2 clarifying questions if needed
|
||||
- User responds
|
||||
- You synthesize understanding: "Got it! So you want to [restate] for [audience] to [solve problem]. Let me research some approaches..."
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Research & Validation (Heavy Lifting)
|
||||
|
||||
**Use Explore subagent** for parallel research tasks. Don't make user wait - go do the research.
|
||||
|
||||
### Technical Research
|
||||
|
||||
**For each technology/pattern mentioned**, research:
|
||||
|
||||
```
|
||||
Use Explore subagent to research [technology/pattern]:
|
||||
- Check Context7 MCP for official docs and current patterns
|
||||
- Find GitHub examples and working templates
|
||||
- Identify common pitfalls and known issues
|
||||
- Verify package versions and stability
|
||||
- Check if our skills repo has relevant skills
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Use Explore to research "MCP servers on Cloudflare Workers":
|
||||
- Context7: /websites/developers_cloudflare-workers (official patterns)
|
||||
- GitHub: anthropics/anthropic-quickstarts (MCP examples)
|
||||
- Skills: Check ~/.claude/skills/ for cloudflare-worker-base, typescript-mcp, fastmcp
|
||||
- Verify: @modelcontextprotocol/sdk versions, Wrangler compatibility
|
||||
```
|
||||
|
||||
### Competitive Research (when relevant)
|
||||
|
||||
**Use WebSearch** to find:
|
||||
- Similar tools/apps in market
|
||||
- How others solved this problem
|
||||
- What worked and what failed
|
||||
- Market gaps and opportunities
|
||||
- User feedback on existing solutions
|
||||
|
||||
**Example**:
|
||||
```
|
||||
WebSearch: "web scraping MCP servers", "Cloudflare Workers web scraper"
|
||||
- Find 3-5 comparable solutions
|
||||
- Extract key features and limitations
|
||||
- Identify differentiation opportunities
|
||||
```
|
||||
|
||||
### Stack Validation
|
||||
|
||||
- Check if user's preferred stack is appropriate for requirements
|
||||
- Identify if simpler alternatives exist
|
||||
- Research integration patterns for third-party services
|
||||
- Validate scalability and cost implications
|
||||
|
||||
**Be honest**: If preferred stack is problematic, present tradeoffs:
|
||||
> "Your preferred stack is Cloudflare Workers, which is great for this. However, [requirement X] needs [Y], which adds complexity. Options: [A] use Durable Objects (adds cost), [B] use external service (simpler), [C] simplify requirement. Thoughts?"
|
||||
|
||||
### Synthesis
|
||||
|
||||
**Present findings conversationally**, not as giant report:
|
||||
|
||||
✅ **Good**:
|
||||
> "I researched MCP servers on Cloudflare. Good news: there are 13+ official examples, and the @modelcontextprotocol/sdk works great with Workers. The pattern is straightforward - a TypeScript Worker with methods that auto-translate to MCP tools. For web scraping, I found Firecrawl's API is way easier than building custom scraping (they handle rendering, rate limits, etc.). Want me to show you a simple example?"
|
||||
|
||||
❌ **Bad**:
|
||||
> "Research Results:
|
||||
> 1. MCP Server Documentation: [giant dump]
|
||||
> 2. Web Scraping Options: [5 paragraphs]
|
||||
> 3. ..."
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Scope Management (Challenge Assumptions)
|
||||
|
||||
**Critical role**: Prevent feature creep and validate "should we build this"
|
||||
|
||||
### Core Questions to Explore
|
||||
|
||||
**Do you need to build this?**
|
||||
- Could existing tool work with minor adaptation?
|
||||
- Is this a learning project or production product?
|
||||
- Build vs buy vs adapt decision
|
||||
|
||||
**What's the MVP?**
|
||||
- What's the absolute minimum to validate the idea?
|
||||
- Which features are "nice to have" vs essential?
|
||||
- Can we defer 50% of planned features to Phase 2?
|
||||
|
||||
**Build vs integrate?**
|
||||
- For each major capability, is there a service/API?
|
||||
- Is integration cost < build cost?
|
||||
- Does building in-house provide strategic value?
|
||||
|
||||
**Complexity tradeoffs**
|
||||
- Is added complexity worth the benefit?
|
||||
- Can we achieve 80% value with 20% complexity?
|
||||
- What breaks if we simplify?
|
||||
|
||||
### Use AskUserQuestion for Decision Points
|
||||
|
||||
**When multiple valid approaches exist**:
|
||||
|
||||
```json
|
||||
{
|
||||
"questions": [{
|
||||
"question": "For auth, which approach fits your needs?",
|
||||
"header": "Auth approach",
|
||||
"multiSelect": false,
|
||||
"options": [
|
||||
{"label": "Clerk (managed)", "description": "$20/month. Full user management, social auth, webhooks. Easiest."},
|
||||
{"label": "Auth.js (open source)", "description": "Self-hosted, flexible, requires D1 adapter. More setup."},
|
||||
{"label": "Custom JWT", "description": "Just verify tokens, no user management UI. Minimal but limited."},
|
||||
{"label": "No auth needed", "description": "Public tool, no user accounts."}
|
||||
]
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**When scope decision needed**:
|
||||
|
||||
```json
|
||||
{
|
||||
"questions": [{
|
||||
"question": "This could be built as full CRM or simple contact manager. Which fits your timeline?",
|
||||
"header": "Scope",
|
||||
"multiSelect": false,
|
||||
"options": [
|
||||
{"label": "Simple (contacts + notes)", "description": "2-3 days. Core functionality only."},
|
||||
{"label": "Medium (+ tasks + deals)", "description": "1-2 weeks. Basic pipeline management."},
|
||||
{"label": "Full CRM (+ automation)", "description": "3-4 weeks. Email sequences, reporting, etc."},
|
||||
{"label": "Not sure yet", "description": "Let's start simple and add features incrementally."}
|
||||
]
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### When to Suggest "Don't Build"
|
||||
|
||||
Be honest when appropriate:
|
||||
|
||||
**Existing solution covers 80%+ of use case**:
|
||||
> "I found [Tool X] does exactly this for $10/month. Building custom would take 20+ hours and you'd need to maintain it. Unless there's a specific reason to build (learning, customization needs, data privacy), I'd recommend just using [Tool X]. Thoughts?"
|
||||
|
||||
**Maintenance burden >> value delivered**:
|
||||
> "This would work, but it requires [complex infrastructure]. For occasional use, the maintenance overhead isn't worth it. Could you achieve the same goal with [simpler alternative]?"
|
||||
|
||||
**Scope is unrealistic for timeline/resources**:
|
||||
> "This is a 6-month project for a team. For solo development, I'd recommend: [A] build just [core feature], [B] use [existing platform] and extend it, or [C] partner with someone who has this infrastructure already."
|
||||
|
||||
**Delivery**: Frame as recommendation, not mandate. User has final say.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Create PROJECT_BRIEF.md
|
||||
|
||||
**When**: After conversation converges on validated approach (usually 5-10 message exchanges)
|
||||
|
||||
**Location**: Project root (or planning/ if user prefers)
|
||||
|
||||
**Structure**:
|
||||
|
||||
```markdown
|
||||
# Project Brief: [Name]
|
||||
|
||||
**Created**: [Date]
|
||||
**Status**: Ready for Planning | Needs Validation | On Hold
|
||||
|
||||
---
|
||||
|
||||
## Vision (1-2 sentences)
|
||||
[Core purpose and value proposition]
|
||||
|
||||
## Problem/Opportunity
|
||||
[What pain point or opportunity drives this project]
|
||||
|
||||
## Target Audience
|
||||
- **Primary users**: [who they are + their key needs]
|
||||
- **Scale**: [initial: X users/requests | 6-month projection: Y]
|
||||
- **Context**: [Exploring/Learning/MVP/POC/Production]
|
||||
|
||||
## Core Functionality (MVP)
|
||||
1. **[Feature 1]** - [Why essential for MVP]
|
||||
2. **[Feature 2]** - [Why essential for MVP]
|
||||
3. **[Feature 3]** - [Why essential for MVP]
|
||||
|
||||
**Out of Scope for MVP** (defer to Phase 2):
|
||||
- [Deferred feature 1] - [Why deferring]
|
||||
- [Deferred feature 2] - [Why deferring]
|
||||
|
||||
## Tech Stack (Validated)
|
||||
- **Frontend**: [Choice + rationale]
|
||||
- **Backend**: [Choice + rationale]
|
||||
- **Database**: [Choice + rationale]
|
||||
- **Auth**: [Choice + rationale]
|
||||
- **Hosting**: [Choice + rationale]
|
||||
|
||||
**Key Dependencies**:
|
||||
- **[Service 1]**: [Why needed + integration approach]
|
||||
- **[Service 2]**: [Why needed + integration approach]
|
||||
|
||||
## Research Findings
|
||||
|
||||
### Similar Solutions Reviewed
|
||||
- **[Tool/app 1]**: [Strengths, weaknesses, our differentiation]
|
||||
- **[Tool/app 2]**: [Strengths, weaknesses, our differentiation]
|
||||
|
||||
### Technical Validation
|
||||
- **[Finding 1]**: [Implication for our approach]
|
||||
- **[Finding 2]**: [Implication for our approach]
|
||||
|
||||
### Known Challenges
|
||||
- **[Challenge 1]**: [Mitigation approach]
|
||||
- **[Challenge 2]**: [Mitigation approach]
|
||||
|
||||
## Scope Validation
|
||||
|
||||
**Why Build This?**: [Clear rationale vs alternatives]
|
||||
|
||||
**Why This Approach?**: [Why chosen tech stack vs alternatives]
|
||||
|
||||
**What Could Go Wrong?**: [Top 2-3 risks + mitigation plans]
|
||||
|
||||
## Estimated Effort
|
||||
- **MVP**: [X hours / ~Y minutes human time with Claude Code]
|
||||
- **Rough breakdown**: Setup [X]h, Backend [Y]h, UI [Z]h, Integration [W]h
|
||||
|
||||
## Success Criteria (MVP)
|
||||
- [ ] [Measurable outcome 1]
|
||||
- [ ] [Measurable outcome 2]
|
||||
- [ ] [Measurable outcome 3]
|
||||
|
||||
## Next Steps
|
||||
|
||||
**If proceeding**:
|
||||
1. Run `/plan-project` to generate IMPLEMENTATION_PHASES.md
|
||||
2. Review and refine phases
|
||||
3. Start Phase 1
|
||||
|
||||
**If pausing**:
|
||||
- [What needs validation before proceeding]
|
||||
- [Timeline for revisiting]
|
||||
|
||||
**If not building**:
|
||||
- [Recommended alternative approach]
|
||||
- [Why alternative is better fit]
|
||||
|
||||
---
|
||||
|
||||
**Research References**:
|
||||
- [Link to Context7 doc or skill used]
|
||||
- [Link to GitHub example]
|
||||
- [Link to article/tutorial]
|
||||
```
|
||||
|
||||
**Write the file** using the Write tool.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Handoff Decision
|
||||
|
||||
**Present brief** and recommendation:
|
||||
|
||||
```
|
||||
✅ I've created PROJECT_BRIEF.md summarizing our exploration.
|
||||
|
||||
Based on research and scope analysis, I recommend:
|
||||
[Choose one]:
|
||||
✅ **Proceed** - Validated approach, reasonable scope, no major blockers
|
||||
⏸️ **Validate first** - Need to confirm [X] before committing
|
||||
🚫 **Consider alternative** - [Existing solution Y] is better fit
|
||||
|
||||
Rationale: [2-3 sentences explaining recommendation]
|
||||
|
||||
---
|
||||
|
||||
What would you like to do?
|
||||
|
||||
1. **Proceed to planning** - Run /plan-project to generate implementation phases
|
||||
2. **Refine the brief** - Discuss further, adjust scope or approach
|
||||
3. **Park this idea** - Save brief for later, not ready to commit
|
||||
4. **Pivot** - Explore different approach or subset of features
|
||||
|
||||
Your choice:
|
||||
```
|
||||
|
||||
### Handle User Response
|
||||
|
||||
**If choice 1 (Proceed to planning)**:
|
||||
```
|
||||
Great! I'll run /plan-project now. The planning skill will use PROJECT_BRIEF.md as context to generate detailed implementation phases.
|
||||
|
||||
Ready to proceed?
|
||||
```
|
||||
|
||||
If user confirms, invoke `/plan-project` slash command.
|
||||
|
||||
**If choice 2 (Refine)**:
|
||||
```
|
||||
No problem! What would you like to adjust?
|
||||
- Scope (add/remove features)
|
||||
- Tech stack (different approach)
|
||||
- Timeline (more/less ambitious)
|
||||
- Something else
|
||||
|
||||
Let's discuss...
|
||||
```
|
||||
|
||||
Continue conversation, then update PROJECT_BRIEF.md.
|
||||
|
||||
**If choice 3 (Park)**:
|
||||
```
|
||||
Understood. I'll save PROJECT_BRIEF.md for future reference.
|
||||
|
||||
Want me to:
|
||||
- Move it to planning/ideas/ directory?
|
||||
- Add a note to a TODO.md or project tracking file?
|
||||
- Just leave it in root for now?
|
||||
```
|
||||
|
||||
**If choice 4 (Pivot)**:
|
||||
```
|
||||
Let's explore the alternative. What direction are you thinking?
|
||||
[Continue exploration with adjusted focus]
|
||||
```
|
||||
|
||||
May create new PROJECT_BRIEF.md or update existing one.
|
||||
|
||||
---
|
||||
|
||||
## Integration with /plan-project
|
||||
|
||||
**Seamless handoff**: When user runs `/plan-project` after `/explore-idea`, the planning command should:
|
||||
|
||||
1. Check for PROJECT_BRIEF.md in root or planning/
|
||||
2. If exists, read it first
|
||||
3. Extract validated scope, tech stack, constraints
|
||||
4. Use as context for project-planning skill invocation
|
||||
5. Skip redundant questions (stack, scope already decided)
|
||||
|
||||
**Note**: This requires minor update to /plan-project command (add Phase 0).
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**User provides extremely vague description**:
|
||||
- Output: "I'd love to explore this with you! To start, could you tell me a bit more about [the problem you're solving / who would use this / what you envision it doing]?"
|
||||
- Don't invoke research tools until you have basic clarity
|
||||
|
||||
**Research finds no good path**:
|
||||
- Be transparent: "I researched [X] and found [challenges/limitations]. Here are your options: [A, B, C]. My recommendation: [pause and validate X OR pivot to Y]. Honest assessment: [complexity/cost/time implications]."
|
||||
- Don't sugarcoat feasibility issues
|
||||
|
||||
**Scope keeps expanding during conversation**:
|
||||
- Gently redirect: "That's a great idea for the future! For the MVP, let's focus on [core capabilities]. We can add [expansion features] in Phase 2 or 3 once core is validated. Sound good?"
|
||||
- Track deferred features in "Out of Scope" section
|
||||
|
||||
**User wants to skip brief creation**:
|
||||
- Allow it: "No problem! We can jump straight to /plan-project. Just note that we'll need to answer some tech stack and scope questions there since we didn't document them."
|
||||
- Brief is helpful but not mandatory
|
||||
|
||||
**Tech stack conflicts with requirements**:
|
||||
- Research alternatives: "Your preferred stack is [X], but [requirement Y] is tricky with that approach. I found [alternative Z] handles this well. Tradeoff: [pros/cons]. Want me to explain in detail or proceed with [recommendation]?"
|
||||
- Present options with clear pros/cons
|
||||
|
||||
**User says "I don't know" to important questions**:
|
||||
- Offer guidance: "That's totally fine! Here's what I'd suggest based on similar projects: [recommendation]. We can adjust later if needed. Does that sound reasonable?"
|
||||
- Don't get stuck waiting for perfect answers
|
||||
|
||||
**Research takes longer than expected**:
|
||||
- Communicate: "Still researching [X]... checking [specific source] for [specific info]..."
|
||||
- Don't go silent for multiple minutes
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ User has clarity on what to build (or decided not to build)
|
||||
✅ Tech stack validated against requirements
|
||||
✅ Scope is realistic for MVP (feature creep prevented)
|
||||
✅ Known challenges identified with mitigation plans
|
||||
✅ PROJECT_BRIEF.md created (ready for /plan-project handoff)
|
||||
✅ User knows exactly what to do next
|
||||
✅ Research prevented wasted effort (found alternatives OR validated approach)
|
||||
✅ User feels heard and guided, not interrogated
|
||||
|
||||
---
|
||||
|
||||
## Tone & Style
|
||||
|
||||
**Conversational, not interrogative**
|
||||
- You're exploring together, not extracting requirements
|
||||
- "Let's figure this out" not "Answer these questions"
|
||||
|
||||
**Proactive with research**
|
||||
- Don't wait to be asked
|
||||
- "Let me go research that..." then do it
|
||||
|
||||
**Honest about feasibility**
|
||||
- If it's hard/expensive/slow, say so upfront
|
||||
- Frame as tradeoffs, not blockers
|
||||
|
||||
**Scope guardian**
|
||||
- Gently challenge feature creep
|
||||
- "Love that idea! Let's add it to Phase 2 so we can ship MVP faster"
|
||||
|
||||
**Recommendation-driven**
|
||||
- End with clear "here's what I think you should do and why"
|
||||
- User can disagree, but provide guidance
|
||||
|
||||
**Flexible**
|
||||
- Adapt to user's style (detailed vs brief, technical vs non-technical)
|
||||
- Match their energy (excited vs cautious)
|
||||
|
||||
---
|
||||
|
||||
## Research Tool Usage
|
||||
|
||||
**Context7 MCP** - For official docs, SDK patterns, API references:
|
||||
- Cloudflare: `/websites/developers_cloudflare-workers`
|
||||
- Vercel AI SDK: `/websites/ai-sdk_dev`
|
||||
- React: `/websites/react_dev`
|
||||
- Tailwind: `/websites/tailwindcss`
|
||||
|
||||
**WebSearch** - For market research, examples, tutorials:
|
||||
- "similar tools to [X]"
|
||||
- "how to implement [pattern] with [stack]"
|
||||
- "[technology] examples github"
|
||||
|
||||
**Explore subagent** - For multi-file research, pattern analysis:
|
||||
- "Check if ~/.claude/skills/ has relevant skills"
|
||||
- "Find GitHub examples of [pattern]"
|
||||
- "Research common pitfalls with [technology]"
|
||||
|
||||
**AskUserQuestion** - For decision points with 2-4 clear options:
|
||||
- Auth approach
|
||||
- Database choice
|
||||
- Hosting platform
|
||||
- Scope size
|
||||
|
||||
**Read tool** - Check if related skills exist:
|
||||
- Read ~/.claude/skills/[relevant-skill]/README.md
|
||||
- Extract key patterns or templates
|
||||
|
||||
**Don't overuse tools**:
|
||||
- If user already provided clear info, don't re-research obvious things
|
||||
- Trust user's stated preferences unless there's clear conflict
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
**Difference from /plan-project**:
|
||||
- `/explore-idea`: PRE-commitment phase (figuring out WHAT and HOW)
|
||||
- `/plan-project`: POST-commitment phase (structuring VALIDATED idea into phases)
|
||||
|
||||
**When to use /explore-idea**:
|
||||
- ✅ User has rough idea but not validated approach
|
||||
- ✅ Multiple tech options and unsure which fits
|
||||
- ✅ Want research/validation before committing to build
|
||||
- ✅ Need scope management before detailed planning
|
||||
|
||||
**When to skip directly to /plan-project**:
|
||||
- ❌ User has crystal-clear requirements and validated stack
|
||||
- ❌ Small, obvious project (e.g., "add button to existing page")
|
||||
- ❌ User explicitly says "I've already researched, let's plan"
|
||||
|
||||
**Time investment**:
|
||||
- Expect 5-15 message exchanges (10-20 minutes)
|
||||
- Research phase: 3-7 minutes
|
||||
- Brief creation: 2-3 minutes
|
||||
- Total: ~15-30 minutes for thorough exploration
|
||||
|
||||
**Value**:
|
||||
- Prevents wasted effort on wrong approach
|
||||
- Validates feasibility before committing hours
|
||||
- Documents decisions for future reference
|
||||
- Creates smooth handoff to /plan-project
|
||||
420
commands/plan-feature.md
Normal file
420
commands/plan-feature.md
Normal file
@@ -0,0 +1,420 @@
|
||||
# Plan Feature
|
||||
|
||||
Add a new feature to an existing project by generating new phases and integrating them into IMPLEMENTATION_PHASES.md and SESSION.md.
|
||||
|
||||
---
|
||||
|
||||
## Your Task
|
||||
|
||||
Follow these steps to plan and integrate a new feature into an existing project.
|
||||
|
||||
### 1. Check Prerequisites
|
||||
|
||||
Check that planning docs exist:
|
||||
```bash
|
||||
ls SESSION.md docs/IMPLEMENTATION_PHASES.md
|
||||
```
|
||||
|
||||
**If SESSION.md doesn't exist:**
|
||||
- Output: "❌ No SESSION.md found. This command is for existing projects."
|
||||
- Suggest: "For new projects, use /plan-project instead."
|
||||
- Stop
|
||||
|
||||
**If IMPLEMENTATION_PHASES.md doesn't exist:**
|
||||
- Output: "❌ No IMPLEMENTATION_PHASES.md found."
|
||||
- Suggest: "Create baseline planning with /plan-project first."
|
||||
- Stop
|
||||
|
||||
Read SESSION.md to extract:
|
||||
- Current phase number and name
|
||||
- Current phase status (🔄 in progress, ✅ complete, ⏸️ pending)
|
||||
- Current stage (Implementation/Verification/Debugging)
|
||||
|
||||
Read IMPLEMENTATION_PHASES.md to extract:
|
||||
- All existing phases
|
||||
- Last phase number
|
||||
- Project tech stack
|
||||
|
||||
### 2. Check Current Phase Status
|
||||
|
||||
**If current phase is in progress (🔄):**
|
||||
|
||||
Output warning:
|
||||
```
|
||||
⚠️ WARNING: Phase [N] - [Name] is in progress.
|
||||
|
||||
Current phase status: [Stage]
|
||||
Progress: [Show task completion from SESSION.md]
|
||||
|
||||
Adding a new feature now may cause confusion. Options:
|
||||
|
||||
1. Finish current phase first (recommended)
|
||||
2. Add feature anyway (will append after current phases)
|
||||
3. Cancel and come back later
|
||||
|
||||
Your choice (1/2/3):
|
||||
```
|
||||
|
||||
**If choice 1 (Finish current phase):**
|
||||
- Output: "Complete Phase [N] first, then run /plan-feature again."
|
||||
- Stop
|
||||
|
||||
**If choice 2 (Add anyway):**
|
||||
- Output: "⚠️ Adding feature. New phases will start after Phase [last phase number]."
|
||||
- Continue
|
||||
|
||||
**If choice 3 (Cancel):**
|
||||
- Output: "Cancelled. Run /plan-feature when current phase is complete."
|
||||
- Stop
|
||||
|
||||
**If current phase is complete (✅) or paused (⏸️):**
|
||||
- Continue normally
|
||||
|
||||
### 3. Gather Feature Requirements
|
||||
|
||||
Ask clarifying questions about the feature:
|
||||
|
||||
```
|
||||
I'll help plan this feature. A few questions:
|
||||
|
||||
1. Feature Description: What does this feature do?
|
||||
(Be specific: "Add user profiles with avatar upload" vs "Add profiles")
|
||||
|
||||
2. Scope: Is this feature...
|
||||
- Small (1-2 phases, ~2-4 hours)
|
||||
- Medium (3-4 phases, ~6-10 hours)
|
||||
- Large (5+ phases, ~12+ hours)
|
||||
|
||||
3. Dependencies: Does this feature require...
|
||||
- New database tables/columns?
|
||||
- New API endpoints?
|
||||
- New UI components?
|
||||
- Third-party integrations?
|
||||
- All of the above?
|
||||
|
||||
4. Priority: When should this feature be built?
|
||||
- Immediately after current phase
|
||||
- After specific phase: [specify phase number]
|
||||
- At the end (append to existing phases)
|
||||
|
||||
5. Integration: Does this feature...
|
||||
- Modify existing functionality (may require changes to existing phases)?
|
||||
- Add completely new functionality (independent phases)?
|
||||
```
|
||||
|
||||
Wait for user answers.
|
||||
|
||||
### 4. Generate Feature Phases
|
||||
|
||||
**Invoke project-planning skill** to generate phases for this feature:
|
||||
- Provide feature description + requirements from user
|
||||
- Provide context of existing project (tech stack from IMPLEMENTATION_PHASES.md)
|
||||
- Request specific phase types needed (Database, API, UI, Integration)
|
||||
- Skill generates new phases following validation rules
|
||||
|
||||
**Skill output**: New phases in IMPLEMENTATION_PHASES.md format
|
||||
|
||||
**Verify phases generated:**
|
||||
- Check that phases follow context-safe sizing (≤8 files, 2-4 hours)
|
||||
- Check that phases have verification criteria
|
||||
- Check that phases have concrete tasks
|
||||
|
||||
### 5. Integrate into IMPLEMENTATION_PHASES.md
|
||||
|
||||
**Read existing IMPLEMENTATION_PHASES.md** completely.
|
||||
|
||||
**Determine insertion point** based on user's priority answer:
|
||||
- **Immediately after current**: Insert after current phase number
|
||||
- **After specific phase**: Insert after specified phase number
|
||||
- **At the end**: Append to end of document
|
||||
|
||||
**If inserting mid-document:**
|
||||
- Renumber all subsequent phases (e.g., if inserting after Phase 3, old Phase 4 becomes Phase 7 if adding 3 phases)
|
||||
- Update any cross-phase references
|
||||
|
||||
**Add feature separator** before new phases:
|
||||
```markdown
|
||||
---
|
||||
|
||||
## Feature: [Feature Name] (Added [YYYY-MM-DD])
|
||||
|
||||
[Feature description from user]
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
**Insert new phases** with proper formatting:
|
||||
- Match existing document style
|
||||
- Include all required sections (Type, Estimated Time, Files, Tasks, Verification Criteria, Exit Criteria)
|
||||
- Include file maps if phases are API/UI/Integration type
|
||||
- Number phases correctly
|
||||
|
||||
**Write updated IMPLEMENTATION_PHASES.md**
|
||||
|
||||
### 6. Update SESSION.md
|
||||
|
||||
**Read current SESSION.md** completely.
|
||||
|
||||
**Determine where to insert new phases** (matching IMPLEMENTATION_PHASES.md):
|
||||
- Same position as in IMPLEMENTATION_PHASES.md
|
||||
- Maintain phase number consistency
|
||||
|
||||
**Add new phases** to SESSION.md:
|
||||
- Set status as ⏸️ (pending) for all new phases
|
||||
- Use collapsed format (just header + spec reference)
|
||||
- Renumber existing phases if inserted mid-document
|
||||
|
||||
**Example insertion**:
|
||||
```markdown
|
||||
## Phase 3: Tasks API ✅
|
||||
**Completed**: 2025-11-07 | **Checkpoint**: abc1234
|
||||
**Summary**: CRUD endpoints with validation
|
||||
|
||||
## Phase 4: User Profiles Database ⏸️
|
||||
**Type**: Database | **Added**: 2025-11-07
|
||||
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-4`
|
||||
|
||||
## Phase 5: User Profiles API ⏸️
|
||||
**Type**: API | **Added**: 2025-11-07
|
||||
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-5`
|
||||
|
||||
## Phase 6: User Profiles UI ⏸️
|
||||
**Type**: UI | **Added**: 2025-11-07
|
||||
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-6`
|
||||
|
||||
## Phase 7: Task UI ⏸️
|
||||
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-7`
|
||||
[... existing phase, renumbered from Phase 4 ...]
|
||||
```
|
||||
|
||||
**Update "Next Action" if feature is immediate priority:**
|
||||
- If user chose "Immediately after current" and current phase is complete
|
||||
- Update Next Action to first task of first feature phase
|
||||
|
||||
**Write updated SESSION.md**
|
||||
|
||||
### 7. Update Related Docs (If Applicable)
|
||||
|
||||
**Check if feature requires doc updates:**
|
||||
|
||||
**If feature adds database tables:**
|
||||
- Ask: "Should I update DATABASE_SCHEMA.md with new tables? (y/n)"
|
||||
- If yes: Read DATABASE_SCHEMA.md, add schema definitions for new tables, write updated file
|
||||
|
||||
**If feature adds API endpoints:**
|
||||
- Ask: "Should I update API_ENDPOINTS.md with new routes? (y/n)"
|
||||
- If yes: Read API_ENDPOINTS.md, add endpoint documentation, write updated file
|
||||
|
||||
**If feature changes architecture:**
|
||||
- Ask: "Should I update ARCHITECTURE.md with new data flows? (y/n)"
|
||||
- If yes: Read ARCHITECTURE.md, update architecture diagrams/descriptions, write updated file
|
||||
|
||||
**If feature adds UI components:**
|
||||
- Ask: "Should I update UI_COMPONENTS.md with new components? (y/n)"
|
||||
- If yes: Read UI_COMPONENTS.md, add component documentation, write updated file
|
||||
|
||||
### 8. Create Git Commit for Feature Planning
|
||||
|
||||
**Stage changes:**
|
||||
```bash
|
||||
git add docs/IMPLEMENTATION_PHASES.md SESSION.md
|
||||
```
|
||||
|
||||
**If other docs were updated:**
|
||||
```bash
|
||||
git add docs/DATABASE_SCHEMA.md docs/API_ENDPOINTS.md docs/ARCHITECTURE.md docs/UI_COMPONENTS.md
|
||||
```
|
||||
|
||||
**Create structured commit:**
|
||||
|
||||
Extract from generated phases:
|
||||
- Number of new phases
|
||||
- Phase names and types
|
||||
- Total estimated hours
|
||||
|
||||
```bash
|
||||
git commit -m "$(cat <<'EOF'
|
||||
Add feature: [Feature Name]
|
||||
|
||||
Added [N] new phases for [feature description]:
|
||||
- Phase [X]: [Name] ([Type], [Y] hours)
|
||||
- Phase [X+1]: [Name] ([Type], [Y] hours)
|
||||
[... list all new phases ...]
|
||||
|
||||
Integration point: [After Phase N / End of plan]
|
||||
Estimated: [X] hours (~[Y] minutes human time)
|
||||
|
||||
Docs updated:
|
||||
- IMPLEMENTATION_PHASES.md (added phases)
|
||||
- SESSION.md (added pending phases)
|
||||
[- DATABASE_SCHEMA.md] (if updated)
|
||||
[- API_ENDPOINTS.md] (if updated)
|
||||
[- ARCHITECTURE.md] (if updated)
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
### 9. Output Feature Planning Summary
|
||||
|
||||
Display formatted summary:
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════
|
||||
FEATURE PLANNING COMPLETE
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
✨ Feature: [Feature Name]
|
||||
📦 Scope: [Small/Medium/Large] ([N] phases, [X] hours)
|
||||
|
||||
───────────────────────────────────────────────
|
||||
NEW PHASES ADDED:
|
||||
───────────────────────────────────────────────
|
||||
|
||||
Phase [X]: [Name] ([Type], [X] hours) ⏸️
|
||||
Phase [Y]: [Name] ([Type], [X] hours) ⏸️
|
||||
Phase [Z]: [Name] ([Type], [X] hours) ⏸️
|
||||
[... list all new phases ...]
|
||||
|
||||
───────────────────────────────────────────────
|
||||
INTEGRATION:
|
||||
───────────────────────────────────────────────
|
||||
|
||||
• Inserted: [After Phase N / End of plan]
|
||||
• Existing phases: [Renumbered from Phase X / Unchanged]
|
||||
• Total project phases: [N]
|
||||
|
||||
───────────────────────────────────────────────
|
||||
UPDATED DOCS:
|
||||
───────────────────────────────────────────────
|
||||
|
||||
✅ IMPLEMENTATION_PHASES.md
|
||||
✅ SESSION.md
|
||||
[✅ DATABASE_SCHEMA.md] (if updated)
|
||||
[✅ API_ENDPOINTS.md] (if updated)
|
||||
[✅ ARCHITECTURE.md] (if updated)
|
||||
[✅ UI_COMPONENTS.md] (if updated)
|
||||
|
||||
───────────────────────────────────────────────
|
||||
CURRENT STATUS:
|
||||
───────────────────────────────────────────────
|
||||
|
||||
Current Phase: Phase [N] - [Name] ([Status emoji])
|
||||
New feature phases: ⏸️ (pending)
|
||||
|
||||
Next Action: [Current Next Action from SESSION.md]
|
||||
|
||||
═══════════════════════════════════════════════
|
||||
```
|
||||
|
||||
### 10. Ask About Next Steps
|
||||
|
||||
Ask user:
|
||||
```
|
||||
Feature planning complete. What would you like to do?
|
||||
|
||||
Options:
|
||||
1. Continue with current phase (recommended if in progress)
|
||||
2. Start new feature immediately (skip ahead to feature phases)
|
||||
3. Review feature phases first
|
||||
4. Push to remote
|
||||
|
||||
Your choice (1/2/3/4):
|
||||
```
|
||||
|
||||
**If choice 1 (Continue current):**
|
||||
- Output: "Continuing with current work. Feature will be built later."
|
||||
- No action needed
|
||||
|
||||
**If choice 2 (Start feature immediately):**
|
||||
- Output: "⚠️ Skipping ahead to feature phases."
|
||||
- Ask: "Update SESSION.md to mark current phase as paused (⏸️) and start feature? (y/n)"
|
||||
- If yes:
|
||||
- Update SESSION.md: Change current phase to ⏸️, change first feature phase to 🔄
|
||||
- Expand first feature phase with task checklist
|
||||
- Set "Next Action" to first task of first feature phase
|
||||
- Output: "✅ SESSION.md updated. Starting [First Feature Phase Name]"
|
||||
|
||||
**If choice 3 (Review first):**
|
||||
- Output: "Review new phases in docs/IMPLEMENTATION_PHASES.md. Run /continue-session when ready."
|
||||
- Wait for user
|
||||
|
||||
**If choice 4 (Push to remote):**
|
||||
```bash
|
||||
git push
|
||||
```
|
||||
- Output: "✅ Feature planning pushed to remote" (if success)
|
||||
- Output: "❌ Push failed. Run `git push` manually when ready." (if failed)
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**SESSION.md doesn't exist:**
|
||||
- Output: "❌ No SESSION.md found. This command is for existing projects."
|
||||
- Suggest: "Use /plan-project for new projects."
|
||||
- Stop
|
||||
|
||||
**IMPLEMENTATION_PHASES.md doesn't exist:**
|
||||
- Output: "❌ No IMPLEMENTATION_PHASES.md found."
|
||||
- Suggest: "Run /plan-project to create baseline planning."
|
||||
- Stop
|
||||
|
||||
**Current phase is in progress and user cancels:**
|
||||
- Output: "Cancelled. Finish current phase first, then run /plan-feature."
|
||||
- Stop
|
||||
|
||||
**Feature description is vague:**
|
||||
- Output: "❌ Feature description unclear."
|
||||
- Ask: "Please describe what this feature does in 1-2 sentences."
|
||||
- Wait for clarification
|
||||
|
||||
**project-planning skill fails:**
|
||||
- Output: "❌ Failed to generate feature phases."
|
||||
- Suggest: "Describe phases manually and I'll integrate them."
|
||||
- Wait for user input
|
||||
|
||||
**Phase numbering conflict:**
|
||||
- Output: "⚠️ Phase numbering conflict detected."
|
||||
- Output: "Renumbering all phases to maintain sequence."
|
||||
- Show old → new phase number mapping
|
||||
- Continue with renumbering
|
||||
|
||||
**File conflict with existing phases:**
|
||||
- Output: "⚠️ Warning: Feature phase [N] modifies files used in existing Phase [X]."
|
||||
- Output: "Files: [list conflicting files]"
|
||||
- Output: "This may require refactoring. Review carefully."
|
||||
- Ask: "Continue anyway? (y/n)"
|
||||
|
||||
**Git commit fails:**
|
||||
- Output: "⚠️ Git commit failed: [error message]"
|
||||
- Output: "Fix git issue and commit manually."
|
||||
- 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)
|
||||
|
||||
**Related doc doesn't exist:**
|
||||
- Output: "⚠️ [Doc name] not found. Skipping update."
|
||||
- Continue with other docs
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ Existing planning docs verified
|
||||
✅ Current phase status checked
|
||||
✅ Feature requirements gathered (5 questions answered)
|
||||
✅ New phases generated with validation
|
||||
✅ IMPLEMENTATION_PHASES.md updated with new phases
|
||||
✅ SESSION.md updated with new pending phases
|
||||
✅ Phase numbering consistent across all docs
|
||||
✅ Related docs updated (if applicable)
|
||||
✅ Git commit created for feature planning
|
||||
✅ User has clear understanding of integration point
|
||||
✅ User can continue current work or start feature
|
||||
335
commands/plan-project.md
Normal file
335
commands/plan-project.md
Normal file
@@ -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
|
||||
1420
commands/release.md
Normal file
1420
commands/release.md
Normal file
File diff suppressed because it is too large
Load Diff
542
commands/workflow.md
Normal file
542
commands/workflow.md
Normal file
@@ -0,0 +1,542 @@
|
||||
# Workflow
|
||||
|
||||
Interactive guide to the Jezweb Workflow: 5 commands for complete project lifecycle automation.
|
||||
|
||||
---
|
||||
|
||||
## Your Task
|
||||
|
||||
Help the user understand and use the 5-command workflow system by providing interactive guidance based on their current context.
|
||||
|
||||
### Overview: The 5 Commands
|
||||
|
||||
Display this summary first:
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════
|
||||
JEZWEB WORKFLOW - 5 COMMANDS
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
1. /explore-idea → Research & validate ideas (PRE-planning)
|
||||
2. /plan-project → Generate planning docs (NEW projects)
|
||||
3. /wrap-session → Checkpoint progress (end of session)
|
||||
4. /continue-session → Load context (start of session)
|
||||
5. /plan-feature → Add features (EXISTING projects)
|
||||
|
||||
Complete Workflow:
|
||||
Idea → /explore-idea → /plan-project → Work → /wrap-session → /continue-session (cycle)
|
||||
|
||||
Quick Workflow (clear requirements):
|
||||
Idea → /plan-project → Work → /wrap-session → /continue-session (cycle)
|
||||
|
||||
Feature Addition:
|
||||
/plan-feature → Work → /wrap-session → /continue-session (cycle)
|
||||
|
||||
═══════════════════════════════════════════════
|
||||
```
|
||||
|
||||
### Step 1: Ask User's Context
|
||||
|
||||
Ask the user what they're trying to do:
|
||||
|
||||
```
|
||||
What are you trying to do?
|
||||
|
||||
1. Explore a new project idea (not sure about approach yet)
|
||||
2. Plan a new project (I know what I want)
|
||||
3. Add a feature to existing project
|
||||
4. Wrap my current session (context getting full)
|
||||
5. Resume work on a project
|
||||
6. Show me the complete workflow guide
|
||||
|
||||
Your choice (1-6):
|
||||
```
|
||||
|
||||
### Step 2: Provide Context-Aware Guidance
|
||||
|
||||
Based on the user's choice, provide specific guidance:
|
||||
|
||||
#### Choice 1: Explore New Idea
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════
|
||||
EXPLORING A NEW IDEA
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
You should use: /explore-idea
|
||||
|
||||
What it does:
|
||||
• Free-flowing conversation (not rigid questionnaire)
|
||||
• Heavy research (approaches, examples, alternatives)
|
||||
• Validates tech stack and feasibility
|
||||
• Challenges assumptions, prevents scope creep
|
||||
• Sometimes recommends NOT building
|
||||
• Creates PROJECT_BRIEF.md with validated decisions
|
||||
|
||||
When to use:
|
||||
✅ Rough idea but not validated approach
|
||||
✅ Multiple tech options, unsure which fits
|
||||
✅ Want research/validation before committing
|
||||
|
||||
When to skip:
|
||||
❌ Crystal-clear requirements (use /plan-project)
|
||||
|
||||
Output: PROJECT_BRIEF.md
|
||||
|
||||
Next step: /plan-project (reads the brief automatically)
|
||||
|
||||
Time saved: 10-15 minutes
|
||||
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
Ready to run /explore-idea? (y/n)
|
||||
```
|
||||
|
||||
If yes: Execute `/explore-idea`
|
||||
|
||||
---
|
||||
|
||||
#### Choice 2: Plan New Project
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════
|
||||
PLANNING A NEW PROJECT
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
You should use: /plan-project
|
||||
|
||||
What it does:
|
||||
• Checks for PROJECT_BRIEF.md (from /explore-idea)
|
||||
• Invokes project-planning skill
|
||||
• Generates IMPLEMENTATION_PHASES.md
|
||||
• Creates SESSION.md automatically
|
||||
• Creates git commit with planning docs
|
||||
• Asks permission to start Phase 1
|
||||
|
||||
Prerequisites:
|
||||
• Git repository (recommended)
|
||||
• Project description OR PROJECT_BRIEF.md
|
||||
|
||||
Output:
|
||||
• docs/IMPLEMENTATION_PHASES.md
|
||||
• SESSION.md
|
||||
• Other docs (DATABASE_SCHEMA.md, API_ENDPOINTS.md, etc.)
|
||||
|
||||
Next step: Start Phase 1, work through phases
|
||||
|
||||
Time saved: 5-7 minutes
|
||||
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
Do you have a PROJECT_BRIEF.md from /explore-idea? (y/n)
|
||||
```
|
||||
|
||||
If no: "That's fine! /plan-project will ask clarifying questions."
|
||||
|
||||
```
|
||||
Ready to run /plan-project? (y/n)
|
||||
```
|
||||
|
||||
If yes: Execute `/plan-project`
|
||||
|
||||
---
|
||||
|
||||
#### Choice 3: Add Feature
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════
|
||||
ADDING A FEATURE
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
First: Does this project have SESSION.md? (y/n)
|
||||
```
|
||||
|
||||
**If NO**:
|
||||
```
|
||||
❌ This project wasn't set up with the workflow.
|
||||
|
||||
Options:
|
||||
1. Run /plan-project to set up workflow for this project
|
||||
2. Manually create SESSION.md (see docs/JEZWEB_WORKFLOW.md)
|
||||
3. Just work without workflow
|
||||
|
||||
Your choice (1-3):
|
||||
```
|
||||
|
||||
**If YES**:
|
||||
```
|
||||
Great! Now, do you know HOW to build this feature? (y/n)
|
||||
```
|
||||
|
||||
**If NO (uncertain)**:
|
||||
```
|
||||
Recommendation: Have a conversation with me first.
|
||||
|
||||
Tell me about the feature, and I'll:
|
||||
• Research approaches and patterns
|
||||
• Present tradeoffs
|
||||
• Help you decide on approach
|
||||
|
||||
Then we'll run /plan-feature to formalize the plan.
|
||||
|
||||
What's the feature you want to add?
|
||||
```
|
||||
|
||||
[Continue conversational exploration, then offer /plan-feature]
|
||||
|
||||
**If YES (clear approach)**:
|
||||
```
|
||||
You should use: /plan-feature
|
||||
|
||||
What it does:
|
||||
• Verifies SESSION.md + IMPLEMENTATION_PHASES.md exist
|
||||
• Asks 5 questions about feature
|
||||
• Generates new phases
|
||||
• Integrates into IMPLEMENTATION_PHASES.md
|
||||
• Updates SESSION.md
|
||||
• Creates git commit
|
||||
|
||||
Output:
|
||||
• Updated IMPLEMENTATION_PHASES.md (new phases integrated)
|
||||
• Updated SESSION.md (new pending phases)
|
||||
• Updated related docs (if needed)
|
||||
|
||||
Time saved: 7-10 minutes
|
||||
|
||||
Ready to run /plan-feature? (y/n)
|
||||
```
|
||||
|
||||
If yes: Execute `/plan-feature`
|
||||
|
||||
---
|
||||
|
||||
#### Choice 4: Wrap Session
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════
|
||||
WRAPPING YOUR SESSION
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
You should use: /wrap-session
|
||||
|
||||
What it does:
|
||||
• Analyzes current session state
|
||||
• Updates SESSION.md with progress
|
||||
• Detects and updates relevant docs
|
||||
• Creates git checkpoint commit
|
||||
• Sets concrete "Next Action"
|
||||
|
||||
When to use:
|
||||
✅ Context window getting full (>80%)
|
||||
✅ Completed a phase
|
||||
✅ Stopping work for now
|
||||
✅ Hit a blocker
|
||||
|
||||
Output:
|
||||
• Updated SESSION.md
|
||||
• Git checkpoint commit
|
||||
• Handoff summary
|
||||
|
||||
Next step: Compact/clear context, then /continue-session
|
||||
|
||||
Time saved: 2-3 minutes
|
||||
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
Ready to run /wrap-session? (y/n)
|
||||
```
|
||||
|
||||
If yes: Execute `/wrap-session`
|
||||
|
||||
After completion:
|
||||
```
|
||||
Session wrapped! ✅
|
||||
|
||||
Next steps:
|
||||
1. Compact context: Type /compact
|
||||
OR clear context: Use clear button
|
||||
2. Resume: Run /continue-session when ready
|
||||
|
||||
Your Next Action is documented in SESSION.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Choice 5: Continue Session
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════
|
||||
RESUMING YOUR SESSION
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
You should use: /continue-session
|
||||
|
||||
What it does:
|
||||
• Loads SESSION.md and planning docs
|
||||
• Shows recent git history (last 5 commits)
|
||||
• Displays current phase and progress
|
||||
• Shows concrete "Next Action"
|
||||
• Offers to open relevant file
|
||||
|
||||
Prerequisites:
|
||||
• SESSION.md exists (created by /plan-project)
|
||||
• Previous session wrapped (via /wrap-session)
|
||||
|
||||
Output:
|
||||
• Session summary
|
||||
• Clear next steps
|
||||
|
||||
Time saved: 1-2 minutes
|
||||
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
Ready to run /continue-session? (y/n)
|
||||
```
|
||||
|
||||
If yes: Execute `/continue-session`
|
||||
|
||||
---
|
||||
|
||||
#### Choice 6: Show Complete Guide
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════
|
||||
COMPLETE WORKFLOW GUIDE
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
I've created comprehensive documentation at:
|
||||
|
||||
📖 docs/JEZWEB_WORKFLOW.md (~800 lines)
|
||||
|
||||
Contents:
|
||||
• Philosophy (why this workflow exists)
|
||||
• The 5 commands (deep dives)
|
||||
• Complete workflows (3 scenarios)
|
||||
• Decision trees (when to use what)
|
||||
• Real-world examples (annotated)
|
||||
• Troubleshooting (common issues)
|
||||
• Time savings (measured metrics)
|
||||
• Comparison to manual workflow
|
||||
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
Would you like me to:
|
||||
1. Open the complete guide (show full doc)
|
||||
2. Show decision trees (when to use which command)
|
||||
3. Show a specific workflow example
|
||||
4. Answer a specific question
|
||||
|
||||
Your choice (1-4):
|
||||
```
|
||||
|
||||
**If Choice 1**: Read and display docs/JEZWEB_WORKFLOW.md
|
||||
|
||||
**If Choice 2**: Show decision trees section from guide
|
||||
|
||||
**If Choice 3**: Ask which example (new project full flow, quick flow, or feature addition), then show that section
|
||||
|
||||
**If Choice 4**: "What's your question about the workflow?"
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Offer Related Actions
|
||||
|
||||
After providing guidance, offer related next steps:
|
||||
|
||||
**After showing /explore-idea guidance**:
|
||||
```
|
||||
Related commands:
|
||||
• After /explore-idea completes → Run /plan-project
|
||||
• Need to understand planning phase? → Ask about /plan-project
|
||||
```
|
||||
|
||||
**After showing /plan-project guidance**:
|
||||
```
|
||||
Related commands:
|
||||
• After planning complete → Work on Phase 1
|
||||
• When context full → Run /wrap-session
|
||||
• Need to understand session management? → Ask about /wrap-session
|
||||
```
|
||||
|
||||
**After showing /wrap-session guidance**:
|
||||
```
|
||||
Related commands:
|
||||
• After wrapping → Compact/clear context
|
||||
• To resume → Run /continue-session
|
||||
```
|
||||
|
||||
**After showing /continue-session guidance**:
|
||||
```
|
||||
Related commands:
|
||||
• After resuming → Continue with Next Action
|
||||
• When context full again → Run /wrap-session
|
||||
• Need to add feature? → Run /plan-feature
|
||||
```
|
||||
|
||||
**After showing /plan-feature guidance**:
|
||||
```
|
||||
Related commands:
|
||||
• After feature planned → Continue work
|
||||
• When context full → Run /wrap-session
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Decision Tree Helper
|
||||
|
||||
If user asks "which command should I use?" or seems uncertain:
|
||||
|
||||
Show this decision tree:
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════
|
||||
DECISION TREE: WHICH COMMAND?
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
What are you trying to do?
|
||||
|
||||
NEW PROJECT:
|
||||
├─ Rough idea, not sure about approach
|
||||
│ └─ /explore-idea → /plan-project
|
||||
│
|
||||
└─ Clear requirements, know what I want
|
||||
└─ /plan-project
|
||||
|
||||
EXISTING PROJECT:
|
||||
├─ Add new feature
|
||||
│ ├─ Not sure how → Conversation → /plan-feature
|
||||
│ └─ Clear approach → /plan-feature
|
||||
│
|
||||
├─ Continue working
|
||||
│ ├─ Context getting full → /wrap-session
|
||||
│ ├─ Resuming work → /continue-session
|
||||
│ └─ Just keep working (no command needed)
|
||||
│
|
||||
└─ Major architectural change
|
||||
└─ /explore-idea → Decide: New repo OR /plan-feature
|
||||
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
Does this help? Which path matches your situation?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Quick Reference Card
|
||||
|
||||
If user asks for "quick reference" or "cheat sheet":
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════
|
||||
WORKFLOW QUICK REFERENCE
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
COMMAND | WHEN TO USE | OUTPUT
|
||||
───────────────────────────────────────────────
|
||||
/explore-idea | Rough idea, need research | PROJECT_BRIEF.md
|
||||
/plan-project | New project, clear reqs | IMPLEMENTATION_PHASES.md, SESSION.md
|
||||
/wrap-session | Context full, end session | Updated SESSION.md, git commit
|
||||
/continue-session | Start session, load state | Session summary, Next Action
|
||||
/plan-feature | Add feature to project | Updated phases, SESSION.md
|
||||
|
||||
───────────────────────────────────────────────
|
||||
TYPICAL WORKFLOWS
|
||||
───────────────────────────────────────────────
|
||||
|
||||
Full: /explore-idea → /plan-project → Work → /wrap-session → /continue-session
|
||||
|
||||
Quick: /plan-project → Work → /wrap-session → /continue-session
|
||||
|
||||
Feature: /plan-feature → Work → /wrap-session → /continue-session
|
||||
|
||||
───────────────────────────────────────────────
|
||||
TIME SAVINGS
|
||||
───────────────────────────────────────────────
|
||||
|
||||
Exploration: 10-15 min saved
|
||||
Planning: 5-7 min saved
|
||||
Wrap cycle: 2-3 min saved (per wrap)
|
||||
Resume cycle: 1-2 min saved (per resume)
|
||||
Feature: 7-10 min saved
|
||||
|
||||
Total per project: 25-40 minutes saved
|
||||
|
||||
───────────────────────────────────────────────
|
||||
DOCS
|
||||
───────────────────────────────────────────────
|
||||
|
||||
📖 Complete guide: docs/JEZWEB_WORKFLOW.md
|
||||
📋 Commands README: commands/README.md
|
||||
🚀 Project README: README.md
|
||||
|
||||
═══════════════════════════════════════════════
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Error Handling
|
||||
|
||||
**If user asks about workflow but no commands installed**:
|
||||
```
|
||||
❌ Workflow commands not found in ~/.claude/commands/
|
||||
|
||||
To install:
|
||||
cd /path/to/claude-skills
|
||||
cp commands/*.md ~/.claude/commands/
|
||||
|
||||
Then commands will be available immediately.
|
||||
```
|
||||
|
||||
**If user asks about workflow for project without SESSION.md**:
|
||||
```
|
||||
ℹ️ This project wasn't set up with the workflow.
|
||||
|
||||
Options:
|
||||
1. Run /plan-project to set up workflow (creates SESSION.md)
|
||||
2. Manually create SESSION.md (see docs/JEZWEB_WORKFLOW.md for template)
|
||||
3. Continue without workflow
|
||||
|
||||
Which would you prefer?
|
||||
```
|
||||
|
||||
**If user is confused about which command to use**:
|
||||
```
|
||||
No problem! Let me help you figure it out.
|
||||
|
||||
Tell me about your situation:
|
||||
• Are you starting a new project or working on existing one?
|
||||
• Do you have SESSION.md in your project?
|
||||
• What are you trying to accomplish right now?
|
||||
|
||||
Based on your answers, I'll recommend the right command.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Success Criteria
|
||||
|
||||
✅ User understands when to use each command
|
||||
✅ User knows which command fits their current situation
|
||||
✅ User has access to complete documentation
|
||||
✅ User can execute the appropriate command
|
||||
✅ User understands how commands integrate
|
||||
✅ User knows where to find detailed examples
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
**Purpose of this command**: Interactive guidance, NOT a replacement for comprehensive docs
|
||||
|
||||
**For detailed info**: Point user to docs/JEZWEB_WORKFLOW.md
|
||||
|
||||
**For command details**: Point user to commands/README.md
|
||||
|
||||
**Keep it conversational**: Adapt to user's level of familiarity
|
||||
|
||||
**Always offer to execute**: Don't just explain, offer to run the command
|
||||
|
||||
---
|
||||
|
||||
**Version**: 1.0.0
|
||||
**Last Updated**: 2025-11-07
|
||||
241
commands/wrap-session.md
Normal file
241
commands/wrap-session.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# Wrap Session
|
||||
|
||||
Automate end-of-session workflow: update SESSION.md, create git checkpoint, and prepare for context clear.
|
||||
|
||||
---
|
||||
|
||||
## Your Task
|
||||
|
||||
Follow these steps to wrap up the current session and prepare for a clean handoff.
|
||||
|
||||
### 1. Analyze Current State (Use Task Agent)
|
||||
|
||||
Use the Task tool with description "Analyze session state for wrap-up" to gather:
|
||||
- Read SESSION.md completely
|
||||
- Run `git status` to see uncommitted changes
|
||||
- Run `git log -1 --oneline` to see last commit
|
||||
- Run `git diff --stat` to see what changed
|
||||
- Extract current phase number, name, and status
|
||||
- Extract current stage (Implementation/Verification/Debugging)
|
||||
- Extract "Next Action"
|
||||
- Extract "Known Issues"
|
||||
|
||||
If SESSION.md doesn't exist:
|
||||
- Stop and output: "❌ No SESSION.md found. Run project-planning skill first to set up session management."
|
||||
- Do not proceed further
|
||||
|
||||
### 2. Update SESSION.md
|
||||
|
||||
**Update the following sections:**
|
||||
|
||||
**a) Current Stage**
|
||||
- If tasks completed and ready for verification: Change to "Verification"
|
||||
- If verification done and ready for next phase: Keep as current
|
||||
- If debugging: Keep as "Debugging"
|
||||
|
||||
**b) Progress Section**
|
||||
- Mark any completed tasks with `[x]`
|
||||
- Add new tasks discovered during session
|
||||
- Reorder if priorities changed
|
||||
|
||||
**c) Known Issues**
|
||||
- Add any new issues discovered this session
|
||||
- Remove resolved issues
|
||||
- Update issue descriptions if changed
|
||||
|
||||
**d) Next Action**
|
||||
- Update to be concrete and specific:
|
||||
- Must include: file path + line number (if applicable) + specific action
|
||||
- Example: "Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47, handle validation and ownership check"
|
||||
- NOT vague like: "Continue working on API..."
|
||||
|
||||
**e) Last Checkpoint**
|
||||
- Update date to today (YYYY-MM-DD format)
|
||||
- Checkpoint hash will be updated after git commit (step 4)
|
||||
|
||||
**f) If Phase Complete**
|
||||
- Change phase status from 🔄 to ✅
|
||||
- Add "Completed" date
|
||||
- Add "Summary" with 2-3 line accomplishment description
|
||||
- Collapse phase section to 2-3 lines
|
||||
- Move to next phase:
|
||||
- Change next phase from ⏸️ to 🔄
|
||||
- Expand next phase with initial task list
|
||||
- Set new "Next Action"
|
||||
|
||||
### 3. Check for Doc Updates
|
||||
|
||||
**Analyze what changed** this session using git diff output.
|
||||
|
||||
**Ask user about updating these docs** (only if relevant changes detected):
|
||||
|
||||
**If phase completed:**
|
||||
- "Phase [N] complete! Should I add entry to CHANGELOG.md? (y/n)"
|
||||
|
||||
**If architecture changed** (new patterns, major refactoring):
|
||||
- "Architecture changes detected. Update ARCHITECTURE.md? (y/n)"
|
||||
|
||||
**If API endpoints added/modified:**
|
||||
- "API changes detected. Update API_ENDPOINTS.md? (y/n)"
|
||||
|
||||
**If database schema changed:**
|
||||
- "Schema changes detected. Update DATABASE_SCHEMA.md? (y/n)"
|
||||
|
||||
**If README needs updates** (new features, changed usage):
|
||||
- "User-facing changes detected. Update README.md? (y/n)"
|
||||
|
||||
**For each "yes":**
|
||||
- Read the relevant doc
|
||||
- Update with session changes
|
||||
- Confirm update was made
|
||||
|
||||
**Note:** Don't ask about docs that don't exist or aren't relevant to changes.
|
||||
|
||||
### 4. Create Git Checkpoint
|
||||
|
||||
**a) Stage all changes:**
|
||||
```bash
|
||||
git add .
|
||||
```
|
||||
|
||||
**b) Check if there are changes to commit:**
|
||||
```bash
|
||||
git status --short
|
||||
```
|
||||
|
||||
If no changes:
|
||||
- Output: "ℹ️ No changes to commit. SESSION.md updated, no checkpoint created."
|
||||
- Skip to step 5
|
||||
|
||||
**c) Determine checkpoint status:**
|
||||
- If phase complete: Status = "Complete"
|
||||
- If significant progress: Status = "In Progress"
|
||||
- If blocked/paused: Status = "Paused"
|
||||
- Otherwise: Status = "In Progress"
|
||||
|
||||
**d) Get phase info from SESSION.md:**
|
||||
- Phase number
|
||||
- Phase name
|
||||
- What was accomplished this session (from progress updates)
|
||||
- Files that changed (from git status)
|
||||
|
||||
**e) Create structured commit message:**
|
||||
|
||||
```bash
|
||||
git commit -m "$(cat <<'EOF'
|
||||
checkpoint: Phase [N] [Status] - [Brief Description]
|
||||
|
||||
Phase: [N] - [Phase Name]
|
||||
Status: [Complete/In Progress/Paused]
|
||||
Session: [1-2 sentence summary of what was accomplished]
|
||||
|
||||
Files Changed:
|
||||
- path/to/file.ts ([what changed])
|
||||
- path/to/file2.ts ([what changed])
|
||||
[... list all significant files]
|
||||
|
||||
Next: [Concrete next action from SESSION.md]
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
**f) Get commit hash:**
|
||||
```bash
|
||||
git log -1 --format="%h"
|
||||
```
|
||||
|
||||
**g) Update SESSION.md "Last Checkpoint" with new hash**
|
||||
|
||||
### 5. Output Handoff Summary
|
||||
|
||||
Display a formatted summary:
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════
|
||||
SESSION WRAP-UP COMPLETE
|
||||
═══════════════════════════════════════════════
|
||||
|
||||
📋 Phase: [N] - [Phase Name] ([Status emoji])
|
||||
📍 Stage: [Implementation/Verification/Debugging]
|
||||
|
||||
✅ Completed This Session:
|
||||
• [accomplishment 1]
|
||||
• [accomplishment 2]
|
||||
• [accomplishment 3]
|
||||
|
||||
🎯 Next Action:
|
||||
[Concrete next action from SESSION.md]
|
||||
|
||||
💾 Checkpoint: [hash] ([date])
|
||||
|
||||
📄 Docs Updated:
|
||||
• SESSION.md
|
||||
• [CHANGELOG.md] (if updated)
|
||||
• [other docs] (if updated)
|
||||
|
||||
═══════════════════════════════════════════════
|
||||
```
|
||||
|
||||
### 6. Ask About Git Push
|
||||
|
||||
Ask user: "Push checkpoint to remote? (y/n)"
|
||||
|
||||
**If yes:**
|
||||
```bash
|
||||
git push
|
||||
```
|
||||
|
||||
**If push succeeds:**
|
||||
- Output: "✅ Pushed to remote successfully"
|
||||
|
||||
**If push fails:**
|
||||
- Output: "❌ Push failed. Run `git push` manually when ready."
|
||||
|
||||
### 7. Final Message
|
||||
|
||||
Output:
|
||||
```
|
||||
✨ Session wrapped successfully!
|
||||
|
||||
Ready to clear context or continue working.
|
||||
|
||||
To resume: Run `/continue-session` in your next session.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**SESSION.md doesn't exist:**
|
||||
- Stop immediately
|
||||
- Output: "❌ No SESSION.md found. Create it first with project-planning skill."
|
||||
|
||||
**No IMPLEMENTATION_PHASES.md:**
|
||||
- Warning: "⚠️ No IMPLEMENTATION_PHASES.md found. Continuing with SESSION.md only."
|
||||
- Proceed without phase verification
|
||||
|
||||
**Git commit fails:**
|
||||
- Output error message
|
||||
- Output: "Fix git issue and try again, or commit manually."
|
||||
|
||||
**Git push fails:**
|
||||
- Output: "⚠️ Push failed. You can run `git push` manually later."
|
||||
- Continue (not critical)
|
||||
|
||||
**Docs update fails:**
|
||||
- Output: "⚠️ Failed to update [doc]. You can update it manually."
|
||||
- Continue with other updates
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ SESSION.md updated with current progress
|
||||
✅ Git checkpoint created with structured message
|
||||
✅ Relevant docs updated (if needed)
|
||||
✅ Clear "Next Action" for resuming
|
||||
✅ User knows exactly what to do next
|
||||
Reference in New Issue
Block a user