Initial commit
This commit is contained in:
Zhongwei Li
15
.claude-plugin/plugin.json
Normal file
15
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,15 @@
|
|||||||
|
{
|
||||||
|
"name": "project-workflow",
|
||||||
|
"description": "Production-ready skill for project-workflow",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"author": {
|
||||||
|
"name": "Jeremy Dawes",
|
||||||
|
"email": "jeremy@jezweb.net"
|
||||||
|
},
|
||||||
|
"commands": [
|
||||||
|
"./commands"
|
||||||
|
],
|
||||||
|
"skills": [
|
||||||
|
"./"
|
||||||
|
]
|
||||||
|
}
|
||||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
# project-workflow
|
||||||
|
|
||||||
|
Production-ready skill for project-workflow
|
||||||
697
SKILL.md
Normal file
697
SKILL.md
Normal file
@@ -0,0 +1,697 @@
|
|||||||
|
# Project Workflow Skill
|
||||||
|
|
||||||
|
**Complete project lifecycle automation for Claude Code**
|
||||||
|
|
||||||
|
This skill provides 7 integrated slash commands that automate the entire project lifecycle from initial idea exploration through planning, execution, session management, and release safety checks.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The project-workflow skill saves **35-55 minutes per project lifecycle** by automating repetitive tasks and enforcing best practices for context management, planning documentation, and safe releases.
|
||||||
|
|
||||||
|
### What This Skill Does
|
||||||
|
|
||||||
|
- **Pre-Planning Research** - Validate ideas, research tech stacks, manage scope
|
||||||
|
- **Automated Planning** - Generate comprehensive IMPLEMENTATION_PHASES.md with verification criteria
|
||||||
|
- **Feature Addition** - Integrate new features into existing project plans
|
||||||
|
- **Session Management** - Handle context across multiple Claude Code sessions
|
||||||
|
- **Release Safety** - Comprehensive checks before publishing to GitHub
|
||||||
|
- **Interactive Guidance** - Navigate the workflow system with contextual help
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### Via Marketplace (Recommended)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Add the marketplace
|
||||||
|
/plugin marketplace add https://github.com/jezweb/claude-skills
|
||||||
|
|
||||||
|
# Install project-workflow skill
|
||||||
|
/plugin install project-workflow@claude-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
All 7 slash commands will be automatically available in Claude Code.
|
||||||
|
|
||||||
|
### Manual Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Clone the repository
|
||||||
|
git clone https://github.com/jezweb/claude-skills ~/claude-skills
|
||||||
|
|
||||||
|
# Copy commands to your Claude config
|
||||||
|
cp ~/claude-skills/skills/project-workflow/commands/*.md ~/.claude/commands/
|
||||||
|
```
|
||||||
|
|
||||||
|
## The 7 Commands
|
||||||
|
|
||||||
|
### 1. `/explore-idea` - Pre-Planning Exploration
|
||||||
|
|
||||||
|
**Purpose:** Collaborative exploration and validation BEFORE committing to implementation
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- You have a rough idea but haven't validated the approach
|
||||||
|
- Multiple tech options and unsure which fits best
|
||||||
|
- Want research/validation before detailed planning
|
||||||
|
- Need scope management to prevent feature creep
|
||||||
|
|
||||||
|
**What it does:**
|
||||||
|
1. Engages in free-flowing conversation to understand your vision
|
||||||
|
2. Conducts heavy research (Explore agents, WebSearch, MCP tools)
|
||||||
|
3. Validates tech stack and architectural decisions
|
||||||
|
4. Challenges assumptions and prevents scope creep
|
||||||
|
5. Creates PROJECT_BRIEF.md with validated decisions
|
||||||
|
6. Recommends: Proceed/Pause/Pivot
|
||||||
|
7. Seamlessly hands off to /plan-project if proceeding
|
||||||
|
|
||||||
|
**Time savings:** 10-15 minutes per project idea
|
||||||
|
|
||||||
|
**Example usage:**
|
||||||
|
```
|
||||||
|
User: /explore-idea
|
||||||
|
Claude: Let's explore your project idea! What are you thinking about building?
|
||||||
|
User: I want to build a chatbot with memory that runs on Cloudflare
|
||||||
|
Claude: [Conducts research on Cloudflare Durable Objects vs D1 for memory...]
|
||||||
|
Claude: [Validates approach, creates PROJECT_BRIEF.md]
|
||||||
|
Claude: Based on research, I recommend proceeding with Durable Objects for memory...
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. `/plan-project` - Generate Project Planning Docs
|
||||||
|
|
||||||
|
**Purpose:** Automate initial project planning for NEW projects
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- Starting a new project with clear requirements
|
||||||
|
- After /explore-idea when you've decided to proceed
|
||||||
|
- Need structured IMPLEMENTATION_PHASES.md for context-safe execution
|
||||||
|
|
||||||
|
**What it does:**
|
||||||
|
1. Checks for PROJECT_BRIEF.md (from /explore-idea) and uses it as context
|
||||||
|
2. Invokes project-planning skill to generate IMPLEMENTATION_PHASES.md
|
||||||
|
3. Creates SESSION.md for tracking progress
|
||||||
|
4. Creates initial git commit with planning docs
|
||||||
|
5. Shows formatted planning summary
|
||||||
|
6. Asks permission to start Phase 1
|
||||||
|
7. Optionally pushes to remote
|
||||||
|
|
||||||
|
**Time savings:** 5-7 minutes per new project
|
||||||
|
|
||||||
|
**Example usage:**
|
||||||
|
```
|
||||||
|
User: /plan-project
|
||||||
|
Claude: I found PROJECT_BRIEF.md from /explore-idea. Using it for context...
|
||||||
|
Claude: [Generates IMPLEMENTATION_PHASES.md with 8 phases]
|
||||||
|
Claude: [Creates SESSION.md]
|
||||||
|
Claude: [Git commit: "docs: Add project planning documentation"]
|
||||||
|
Claude: Ready to start Phase 1: Project Setup?
|
||||||
|
```
|
||||||
|
|
||||||
|
**Generated files:**
|
||||||
|
- `IMPLEMENTATION_PHASES.md` - Phased development plan with verification criteria
|
||||||
|
- `SESSION.md` - Session tracking and handoff protocol
|
||||||
|
- `DATABASE_SCHEMA.md` - If project uses a database
|
||||||
|
- `API_ENDPOINTS.md` - If project has an API
|
||||||
|
- `ARCHITECTURE.md` - System architecture overview
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. `/plan-feature` - Add Features to Existing Projects
|
||||||
|
|
||||||
|
**Purpose:** Add new features to existing projects by generating and integrating phases
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- Want to add a feature to an existing project
|
||||||
|
- Need to integrate new functionality into current plan
|
||||||
|
- Existing SESSION.md and IMPLEMENTATION_PHASES.md already exist
|
||||||
|
|
||||||
|
**What it does:**
|
||||||
|
1. Verifies prerequisites (SESSION.md + IMPLEMENTATION_PHASES.md exist)
|
||||||
|
2. Checks current phase status (warns if work in progress)
|
||||||
|
3. Gathers feature requirements (5 questions)
|
||||||
|
4. Generates new phases via project-planning skill
|
||||||
|
5. Integrates into IMPLEMENTATION_PHASES.md (handles phase renumbering)
|
||||||
|
6. Updates SESSION.md with new pending phases
|
||||||
|
7. Updates related docs (DATABASE_SCHEMA.md, API_ENDPOINTS.md if needed)
|
||||||
|
8. Creates git commit for feature planning
|
||||||
|
9. Shows formatted summary
|
||||||
|
|
||||||
|
**Time savings:** 7-10 minutes per feature addition
|
||||||
|
|
||||||
|
**Example usage:**
|
||||||
|
```
|
||||||
|
User: /plan-feature
|
||||||
|
Claude: Found existing planning docs. What feature do you want to add?
|
||||||
|
User: Add user authentication with Clerk
|
||||||
|
Claude: [Asks 5 clarifying questions about the feature]
|
||||||
|
Claude: [Generates 3 new phases for authentication]
|
||||||
|
Claude: [Integrates into existing IMPLEMENTATION_PHASES.md as Phases 9-11]
|
||||||
|
Claude: [Updates SESSION.md with new phases]
|
||||||
|
Claude: [Git commit: "docs: Add authentication feature phases"]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4. `/wrap-session` - End-of-Session Checkpoint
|
||||||
|
|
||||||
|
**Purpose:** Automate end-of-session workflow for safe handoffs
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- Context window getting full (>150k tokens)
|
||||||
|
- End of work session
|
||||||
|
- Before switching to different task
|
||||||
|
- Need to checkpoint progress
|
||||||
|
|
||||||
|
**What it does:**
|
||||||
|
1. Uses Task agent to analyze current session state
|
||||||
|
2. Updates SESSION.md with:
|
||||||
|
- Completed tasks
|
||||||
|
- Current phase progress
|
||||||
|
- Next Action (what to do when resuming)
|
||||||
|
- Blockers/issues encountered
|
||||||
|
3. Detects and updates relevant docs (CHANGELOG.md, ARCHITECTURE.md, etc.)
|
||||||
|
4. Creates structured git checkpoint commit
|
||||||
|
5. Outputs formatted handoff summary
|
||||||
|
6. Optionally pushes to remote
|
||||||
|
|
||||||
|
**Time savings:** 2-3 minutes per wrap-up
|
||||||
|
|
||||||
|
**Example usage:**
|
||||||
|
```
|
||||||
|
User: /wrap-session
|
||||||
|
Claude: [Analyzes session work via Task agent]
|
||||||
|
Claude: [Updates SESSION.md with progress]
|
||||||
|
Claude: [Git commit: "checkpoint: Complete Phase 3 - Database setup"]
|
||||||
|
Claude:
|
||||||
|
SESSION HANDOFF SUMMARY
|
||||||
|
=======================
|
||||||
|
Phase: 3/8 - Database Integration (100% complete)
|
||||||
|
Completed: D1 database setup, migrations, schema
|
||||||
|
Next Action: Start Phase 4 - API Endpoints (src/routes/api.ts)
|
||||||
|
Blockers: None
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 5. `/continue-session` - Start-of-Session Context Loading
|
||||||
|
|
||||||
|
**Purpose:** Automate start-of-session context loading for seamless resumption
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- Starting a new Claude Code session
|
||||||
|
- Continuing work from previous session
|
||||||
|
- After /wrap-session checkpoint
|
||||||
|
|
||||||
|
**What it does:**
|
||||||
|
1. Uses Explore agent to load session context (SESSION.md + planning docs)
|
||||||
|
2. Shows recent git history (last 5 commits)
|
||||||
|
3. Displays formatted session summary:
|
||||||
|
- Current phase and progress
|
||||||
|
- Last completed tasks
|
||||||
|
- Next Action
|
||||||
|
- Any blockers
|
||||||
|
4. Shows verification criteria if in "Verification" stage
|
||||||
|
5. Optionally opens "Next Action" file
|
||||||
|
6. Asks permission to continue or adjust direction
|
||||||
|
|
||||||
|
**Time savings:** 1-2 minutes per resume
|
||||||
|
|
||||||
|
**Example usage:**
|
||||||
|
```
|
||||||
|
User: /continue-session
|
||||||
|
Claude: [Loads SESSION.md via Explore agent]
|
||||||
|
Claude:
|
||||||
|
SESSION CONTEXT
|
||||||
|
===============
|
||||||
|
Phase: 4/8 - API Endpoints (20% complete)
|
||||||
|
Last Session: Completed /api/users GET endpoint
|
||||||
|
Next Action: Implement POST /api/users (src/routes/api.ts:45)
|
||||||
|
Blockers: None
|
||||||
|
|
||||||
|
Recent commits:
|
||||||
|
- checkpoint: Complete Phase 3 - Database setup
|
||||||
|
- feat: Add D1 migrations
|
||||||
|
|
||||||
|
Ready to implement POST /api/users?
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 6. `/workflow` - Interactive Workflow Guide
|
||||||
|
|
||||||
|
**Purpose:** Navigate the workflow system with contextual guidance
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- First time using project-workflow commands
|
||||||
|
- Unsure which command to use next
|
||||||
|
- Want to see workflow examples
|
||||||
|
- Need quick reference
|
||||||
|
|
||||||
|
**What it does:**
|
||||||
|
1. Shows overview of all 7 commands
|
||||||
|
2. Asks what you're trying to do
|
||||||
|
3. Provides context-aware guidance
|
||||||
|
4. Shows decision trees (when to use which command)
|
||||||
|
5. Offers to execute the appropriate command
|
||||||
|
6. Points to comprehensive documentation
|
||||||
|
|
||||||
|
**Example usage:**
|
||||||
|
```
|
||||||
|
User: /workflow
|
||||||
|
Claude:
|
||||||
|
PROJECT WORKFLOW GUIDE
|
||||||
|
======================
|
||||||
|
What would you like to do?
|
||||||
|
|
||||||
|
1. Start a new project
|
||||||
|
2. Add feature to existing project
|
||||||
|
3. End work session
|
||||||
|
4. Resume work session
|
||||||
|
5. Prepare for release
|
||||||
|
6. Just exploring
|
||||||
|
|
||||||
|
User: 1
|
||||||
|
Claude: For new projects, I recommend:
|
||||||
|
- Have clear requirements? → /plan-project
|
||||||
|
- Still validating idea? → /explore-idea
|
||||||
|
|
||||||
|
Which applies to you?
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 7. `/release` - Pre-Release Safety Checks
|
||||||
|
|
||||||
|
**Purpose:** Comprehensive safety checks before publishing to GitHub
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- Ready to push project to public GitHub
|
||||||
|
- Before creating GitHub release
|
||||||
|
- Want to ensure no secrets leaked
|
||||||
|
- Need to validate documentation completeness
|
||||||
|
|
||||||
|
**What it does:**
|
||||||
|
|
||||||
|
**Phase 1: Critical Safety (BLOCKERS)**
|
||||||
|
- Scans for secrets (API keys, tokens, passwords via gitleaks)
|
||||||
|
- Checks for personal artifacts (SESSION.md, planning/, screenshots/)
|
||||||
|
- Verifies git remote URL (pushing to correct repo)
|
||||||
|
|
||||||
|
**Phase 2: Documentation Validation (REQUIRED)**
|
||||||
|
- Checks LICENSE file exists (creates if missing)
|
||||||
|
- Validates README completeness (>100 words, key sections)
|
||||||
|
- Checks CONTRIBUTING.md (recommended for >500 LOC)
|
||||||
|
- Checks CODE_OF_CONDUCT (recommended for >1000 LOC)
|
||||||
|
|
||||||
|
**Phase 3: Configuration Validation**
|
||||||
|
- Validates .gitignore (essential patterns present)
|
||||||
|
- Checks package.json completeness (name, version, license, etc.)
|
||||||
|
- Verifies git branch (warns if on main/master)
|
||||||
|
|
||||||
|
**Phase 4: Quality Checks (NON-BLOCKING)**
|
||||||
|
- Tests build (if build script exists)
|
||||||
|
- Checks dependency vulnerabilities (npm audit)
|
||||||
|
- Warns about large files (>1MB)
|
||||||
|
|
||||||
|
**Phase 5: Release Readiness Report**
|
||||||
|
- Comprehensive report with blockers/warnings/recommendations
|
||||||
|
- Safe to release verdict
|
||||||
|
|
||||||
|
**Phase 6-8: Auto-Fix & Publish**
|
||||||
|
- Offers to fix issues (create LICENSE, update README, etc.)
|
||||||
|
- Creates release preparation commit
|
||||||
|
- Optional: Creates git tag and GitHub release
|
||||||
|
|
||||||
|
**Time savings:** 10-15 minutes per release
|
||||||
|
|
||||||
|
**Example usage:**
|
||||||
|
```
|
||||||
|
User: /release
|
||||||
|
Claude:
|
||||||
|
RELEASE SAFETY CHECK
|
||||||
|
====================
|
||||||
|
✓ No secrets detected
|
||||||
|
✓ No personal artifacts found
|
||||||
|
✓ Remote URL correct (github.com/user/repo)
|
||||||
|
✗ LICENSE file missing
|
||||||
|
✓ README.md complete
|
||||||
|
⚠ No CONTRIBUTING.md (recommended for 2000+ LOC)
|
||||||
|
✓ .gitignore valid
|
||||||
|
✓ package.json complete
|
||||||
|
|
||||||
|
VERDICT: BLOCKED - Create LICENSE file
|
||||||
|
Would you like me to create MIT LICENSE?
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Complete Workflow Examples
|
||||||
|
|
||||||
|
### Full Workflow (with Exploration)
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Rough idea → /explore-idea
|
||||||
|
→ [Creates PROJECT_BRIEF.md with validated tech stack]
|
||||||
|
|
||||||
|
2. Decision to proceed → /plan-project
|
||||||
|
→ [Reads PROJECT_BRIEF.md, creates IMPLEMENTATION_PHASES.md + SESSION.md]
|
||||||
|
|
||||||
|
3. Start Phase 1 → Work on implementation
|
||||||
|
|
||||||
|
4. Context getting full → /wrap-session
|
||||||
|
→ [Updates SESSION.md, git checkpoint]
|
||||||
|
|
||||||
|
5. New session → /continue-session
|
||||||
|
→ [Loads context, shows Next Action]
|
||||||
|
|
||||||
|
6. Need new feature → /plan-feature
|
||||||
|
→ [Adds phases to existing plan]
|
||||||
|
|
||||||
|
7. Continue wrap → resume cycle until done
|
||||||
|
|
||||||
|
8. Ready to publish → /release
|
||||||
|
→ [Safety checks, docs validation, GitHub release]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Quick Workflow (Clear Requirements)
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Clear requirements → /plan-project
|
||||||
|
→ [Creates planning docs]
|
||||||
|
|
||||||
|
2. Work on implementation
|
||||||
|
|
||||||
|
3. /wrap-session when context full
|
||||||
|
|
||||||
|
4. /continue-session to resume
|
||||||
|
|
||||||
|
5. /release when ready to publish
|
||||||
|
```
|
||||||
|
|
||||||
|
### Helper Workflows
|
||||||
|
|
||||||
|
```
|
||||||
|
Need guidance? → /workflow
|
||||||
|
→ [Interactive guide to commands]
|
||||||
|
|
||||||
|
Adding feature? → /plan-feature
|
||||||
|
→ [Generates and integrates new phases]
|
||||||
|
|
||||||
|
Ready to publish? → /release
|
||||||
|
→ [Safety checks + GitHub release]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Integration with Other Skills
|
||||||
|
|
||||||
|
The project-workflow skill works seamlessly with:
|
||||||
|
|
||||||
|
### project-planning Skill
|
||||||
|
- `/plan-project` and `/plan-feature` invoke this skill automatically
|
||||||
|
- Generates IMPLEMENTATION_PHASES.md with proper structure
|
||||||
|
- Creates DATABASE_SCHEMA.md, API_ENDPOINTS.md, etc.
|
||||||
|
|
||||||
|
### project-session-management Skill
|
||||||
|
- Provides the SESSION.md protocol used by `/wrap-session` and `/continue-session`
|
||||||
|
- Defines handoff format and context tracking
|
||||||
|
|
||||||
|
### Built-in Claude Code Agents
|
||||||
|
- `/wrap-session` uses **Task agent** to analyze session state
|
||||||
|
- `/continue-session` uses **Explore agent** to load context
|
||||||
|
- `/explore-idea` uses **Explore agent** for research
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Command Relationships
|
||||||
|
|
||||||
|
```
|
||||||
|
EXPLORATION PHASE
|
||||||
|
/explore-idea (optional)
|
||||||
|
↓
|
||||||
|
Creates PROJECT_BRIEF.md
|
||||||
|
↓
|
||||||
|
PLANNING PHASE
|
||||||
|
/plan-project (reads PROJECT_BRIEF.md if exists)
|
||||||
|
↓
|
||||||
|
Creates IMPLEMENTATION_PHASES.md + SESSION.md
|
||||||
|
↓
|
||||||
|
EXECUTION PHASE
|
||||||
|
Work on phases
|
||||||
|
↓
|
||||||
|
/wrap-session (when context full)
|
||||||
|
↓
|
||||||
|
Updates SESSION.md, git checkpoint
|
||||||
|
↓
|
||||||
|
/continue-session (new session)
|
||||||
|
↓
|
||||||
|
Loads SESSION.md, continues work
|
||||||
|
↓
|
||||||
|
/plan-feature (when need new features)
|
||||||
|
↓
|
||||||
|
Adds phases to IMPLEMENTATION_PHASES.md
|
||||||
|
↓
|
||||||
|
Continue wrap → resume cycle
|
||||||
|
↓
|
||||||
|
RELEASE PHASE
|
||||||
|
/release (when ready to publish)
|
||||||
|
↓
|
||||||
|
Safety checks → GitHub release
|
||||||
|
|
||||||
|
HELPER
|
||||||
|
/workflow (anytime)
|
||||||
|
↓
|
||||||
|
Interactive guidance
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Time Savings Breakdown
|
||||||
|
|
||||||
|
| Command | Time Saved | Tasks Automated |
|
||||||
|
|---------|------------|-----------------|
|
||||||
|
| `/explore-idea` | 10-15 min | Research, validation, scope management, tech stack evaluation |
|
||||||
|
| `/plan-project` | 5-7 min | Planning doc generation, git setup, phase structuring |
|
||||||
|
| `/plan-feature` | 7-10 min | Feature planning, phase integration, doc updates |
|
||||||
|
| `/wrap-session` | 2-3 min | SESSION.md updates, git checkpoint, handoff summary |
|
||||||
|
| `/continue-session` | 1-2 min | Context loading, git history review, next action display |
|
||||||
|
| `/workflow` | Instant | Navigation, decision trees, command selection |
|
||||||
|
| `/release` | 10-15 min | Secret scanning, doc validation, build testing, release creation |
|
||||||
|
|
||||||
|
**Total per project lifecycle:** 35-55 minutes
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
### For All Commands
|
||||||
|
- Claude Code CLI installed
|
||||||
|
- Git repository initialized (recommended)
|
||||||
|
|
||||||
|
### For Planning Commands (/plan-project, /plan-feature)
|
||||||
|
- Project description or requirements
|
||||||
|
- For `/plan-feature`: Existing SESSION.md and IMPLEMENTATION_PHASES.md
|
||||||
|
|
||||||
|
### For Session Commands (/wrap-session, /continue-session)
|
||||||
|
- SESSION.md file in project root (created by /plan-project)
|
||||||
|
- IMPLEMENTATION_PHASES.md (optional but recommended)
|
||||||
|
|
||||||
|
### For Release Command (/release)
|
||||||
|
- Git repository with commits
|
||||||
|
- package.json (for Node.js projects)
|
||||||
|
- Remote repository URL configured (for publishing)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Customizing Planning Templates
|
||||||
|
|
||||||
|
The planning commands invoke the `project-planning` skill, which can be customized by:
|
||||||
|
|
||||||
|
1. Installing the project-planning skill separately:
|
||||||
|
```bash
|
||||||
|
/plugin install project-planning@claude-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Modifying templates in `~/.claude/skills/project-planning/templates/`
|
||||||
|
|
||||||
|
### Customizing Session Protocol
|
||||||
|
|
||||||
|
The session management format can be customized by:
|
||||||
|
|
||||||
|
1. Installing the project-session-management skill:
|
||||||
|
```bash
|
||||||
|
/plugin install project-session-management@claude-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Modifying templates in `~/.claude/skills/project-session-management/templates/`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### /plan-project: "No project description provided"
|
||||||
|
**Solution:** Discuss your project with Claude first, or use `/explore-idea` to create PROJECT_BRIEF.md
|
||||||
|
|
||||||
|
### /plan-feature: "Prerequisites not met"
|
||||||
|
**Solution:** Ensure SESSION.md and IMPLEMENTATION_PHASES.md exist (run `/plan-project` first)
|
||||||
|
|
||||||
|
### /wrap-session: "No git repository found"
|
||||||
|
**Solution:** Initialize git: `git init`
|
||||||
|
|
||||||
|
### /continue-session: "SESSION.md not found"
|
||||||
|
**Solution:** Run `/plan-project` to create SESSION.md
|
||||||
|
|
||||||
|
### /release: "Secrets detected"
|
||||||
|
**Solution:** Review the flagged files, add sensitive files to .gitignore, remove from git history
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### 1. Use /explore-idea for New Ideas
|
||||||
|
- Don't skip research validation
|
||||||
|
- Let Claude challenge assumptions
|
||||||
|
- Create PROJECT_BRIEF.md before planning
|
||||||
|
|
||||||
|
### 2. Plan Before Implementing
|
||||||
|
- Run `/plan-project` at start of every project
|
||||||
|
- Review IMPLEMENTATION_PHASES.md before Phase 1
|
||||||
|
- Get planning docs in git early
|
||||||
|
|
||||||
|
### 3. Wrap Sessions Before Context Full
|
||||||
|
- Watch token usage (/context command)
|
||||||
|
- Wrap around 150k tokens
|
||||||
|
- Don't wait until maxed out (200k)
|
||||||
|
|
||||||
|
### 4. Resume with Context
|
||||||
|
- Always start new sessions with `/continue-session`
|
||||||
|
- Review git history shown
|
||||||
|
- Confirm Next Action before proceeding
|
||||||
|
|
||||||
|
### 5. Feature Planning
|
||||||
|
- Use `/plan-feature` instead of ad-hoc implementation
|
||||||
|
- Let it handle phase renumbering
|
||||||
|
- Keep IMPLEMENTATION_PHASES.md synchronized
|
||||||
|
|
||||||
|
### 6. Release Safely
|
||||||
|
- Run `/release` on feature branches first
|
||||||
|
- Fix all blockers before main branch
|
||||||
|
- Use auto-fix for LICENSE/README issues
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Advanced Usage
|
||||||
|
|
||||||
|
### Parallel Feature Planning
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Plan multiple features, then prioritize
|
||||||
|
/plan-feature # Add authentication
|
||||||
|
/plan-feature # Add payment processing
|
||||||
|
/plan-feature # Add email notifications
|
||||||
|
|
||||||
|
# Review IMPLEMENTATION_PHASES.md
|
||||||
|
# Reorder phases by priority
|
||||||
|
# Git commit the reorganized plan
|
||||||
|
```
|
||||||
|
|
||||||
|
### Release Workflow with Branches
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# On feature branch
|
||||||
|
/release # Check for issues
|
||||||
|
|
||||||
|
# Fix any blockers
|
||||||
|
git add .
|
||||||
|
git commit -m "fix: Address release blockers"
|
||||||
|
|
||||||
|
# Merge to main
|
||||||
|
git checkout main
|
||||||
|
git merge feature-branch
|
||||||
|
|
||||||
|
# Final release check
|
||||||
|
/release # Create GitHub release
|
||||||
|
```
|
||||||
|
|
||||||
|
### Continuous Session Management
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Day 1
|
||||||
|
/plan-project
|
||||||
|
# Work on Phase 1-2
|
||||||
|
/wrap-session
|
||||||
|
|
||||||
|
# Day 2
|
||||||
|
/continue-session
|
||||||
|
# Work on Phase 3-4
|
||||||
|
/wrap-session
|
||||||
|
|
||||||
|
# Day 3
|
||||||
|
/continue-session
|
||||||
|
# Need new feature
|
||||||
|
/plan-feature
|
||||||
|
# Work on new phases
|
||||||
|
/wrap-session
|
||||||
|
|
||||||
|
# Day 4
|
||||||
|
/continue-session
|
||||||
|
# Finish implementation
|
||||||
|
/release
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## FAQ
|
||||||
|
|
||||||
|
**Q: Can I use these commands without other skills?**
|
||||||
|
A: Yes, but `/plan-project` and `/plan-feature` work best with the `project-planning` skill installed.
|
||||||
|
|
||||||
|
**Q: Do I need to use all 7 commands?**
|
||||||
|
A: No. Use `/plan-project` + `/wrap-session` + `/continue-session` for minimum workflow. Add others as needed.
|
||||||
|
|
||||||
|
**Q: Can I modify the commands?**
|
||||||
|
A: Yes. Commands are .md files. Copy to ~/.claude/commands/ and edit.
|
||||||
|
|
||||||
|
**Q: What if I don't want to use git?**
|
||||||
|
A: Most commands work without git, but `/wrap-session`, `/continue-session`, and `/release` heavily integrate with git.
|
||||||
|
|
||||||
|
**Q: Can I use this with non-Cloudflare projects?**
|
||||||
|
A: Yes. The planning system is framework-agnostic. Works with any tech stack.
|
||||||
|
|
||||||
|
**Q: How do I see what's in SESSION.md?**
|
||||||
|
A: Ask Claude: "show me SESSION.md" or use `cat SESSION.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **project-planning** - Generates IMPLEMENTATION_PHASES.md (used by /plan-project)
|
||||||
|
- **project-session-management** - SESSION.md protocol (used by /wrap-session)
|
||||||
|
- **github-project-automation** - GitHub Actions, issue templates, CI/CD
|
||||||
|
- **open-source-contributions** - Contributing to open source projects
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Version History
|
||||||
|
|
||||||
|
**1.0.0** (2025-11-12)
|
||||||
|
- Initial release
|
||||||
|
- 7 integrated slash commands
|
||||||
|
- Plugin marketplace distribution
|
||||||
|
- Command bundling via plugin.json
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
- **Issues**: https://github.com/jezweb/claude-skills/issues
|
||||||
|
- **Documentation**: https://github.com/jezweb/claude-skills
|
||||||
|
- **Author**: Jeremy Dawes (jeremy@jezweb.net)
|
||||||
|
- **Website**: https://jezweb.com.au
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT License - See LICENSE file in repository
|
||||||
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
|
||||||
73
plugin.lock.json
Normal file
73
plugin.lock.json
Normal file
@@ -0,0 +1,73 @@
|
|||||||
|
{
|
||||||
|
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||||
|
"pluginId": "gh:jezweb/claude-skills:skills/project-workflow",
|
||||||
|
"normalized": {
|
||||||
|
"repo": null,
|
||||||
|
"ref": "refs/tags/v20251128.0",
|
||||||
|
"commit": "7850f6f6c293814d646b5819c1e662cfca722e7b",
|
||||||
|
"treeHash": "8893c8ba8496951cec40de700afaf7302d50e7110927dd13796cc35d01635473",
|
||||||
|
"generatedAt": "2025-11-28T10:19:05.696935Z",
|
||||||
|
"toolVersion": "publish_plugins.py@0.2.0"
|
||||||
|
},
|
||||||
|
"origin": {
|
||||||
|
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||||
|
"branch": "master",
|
||||||
|
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||||
|
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||||
|
},
|
||||||
|
"manifest": {
|
||||||
|
"name": "project-workflow",
|
||||||
|
"description": "Production-ready skill for project-workflow",
|
||||||
|
"version": "1.0.0"
|
||||||
|
},
|
||||||
|
"content": {
|
||||||
|
"files": [
|
||||||
|
{
|
||||||
|
"path": "README.md",
|
||||||
|
"sha256": "7f3bf2c0d639ebd804feac904037197b24730f78dd120834ef83c937aebceab2"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "SKILL.md",
|
||||||
|
"sha256": "11bd8374ed19871858a4dc454e728d3a8edf1f349fe994b6a70e4100592aa6dd"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": ".claude-plugin/plugin.json",
|
||||||
|
"sha256": "ffb6b13781ef308e71f168cfcbd18e7c2aee99def7484c50fb62610a564d5f13"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/plan-feature.md",
|
||||||
|
"sha256": "1e574874b5315d6e48ec07f5c9e5e44dc548d5f6da66f931664a9327e10e4a11"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/explore-idea.md",
|
||||||
|
"sha256": "db6f74f72f69dfc3bffa734e56f4ec18470a70145bd492a3746d23d61f70058d"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/wrap-session.md",
|
||||||
|
"sha256": "6e0b963dd71062a74b5e177643504dc723fa8d71f93665356856c753fd537fc6"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/workflow.md",
|
||||||
|
"sha256": "b3cbeeb5d987d98da882bd01de01dd5623153f6610c6e67236adde6831ad2e0e"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/release.md",
|
||||||
|
"sha256": "a10ba062d6d51e282593b80013b4390c1819ab961556225b2e287809f57be6f5"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/plan-project.md",
|
||||||
|
"sha256": "a014e2b76b4c60741c7cb377ddb2d4c8f27c4b7740291da729a685d7eb25901c"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/continue-session.md",
|
||||||
|
"sha256": "5791185f1211735913989a5e130d775731745f4d6cdd4cafa4d0ac7bb7bd9686"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"dirSha256": "8893c8ba8496951cec40de700afaf7302d50e7110927dd13796cc35d01635473"
|
||||||
|
},
|
||||||
|
"security": {
|
||||||
|
"scannedAt": null,
|
||||||
|
"scannerVersion": null,
|
||||||
|
"flags": []
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user