From afd3595afafbdc6eedb207187da5ed47ada167af Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:25:25 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 15 + README.md | 3 + SKILL.md | 697 +++++++++++++++++ commands/continue-session.md | 277 +++++++ commands/explore-idea.md | 517 +++++++++++++ commands/plan-feature.md | 420 ++++++++++ commands/plan-project.md | 335 ++++++++ commands/release.md | 1420 ++++++++++++++++++++++++++++++++++ commands/workflow.md | 542 +++++++++++++ commands/wrap-session.md | 241 ++++++ plugin.lock.json | 73 ++ 11 files changed, 4540 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 SKILL.md create mode 100644 commands/continue-session.md create mode 100644 commands/explore-idea.md create mode 100644 commands/plan-feature.md create mode 100644 commands/plan-project.md create mode 100644 commands/release.md create mode 100644 commands/workflow.md create mode 100644 commands/wrap-session.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..0999447 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -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": [ + "./" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..4f55b2a --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# project-workflow + +Production-ready skill for project-workflow diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..3bbbd0d --- /dev/null +++ b/SKILL.md @@ -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 diff --git a/commands/continue-session.md b/commands/continue-session.md new file mode 100644 index 0000000..c7b7e67 --- /dev/null +++ b/commands/continue-session.md @@ -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 diff --git a/commands/explore-idea.md b/commands/explore-idea.md new file mode 100644 index 0000000..75071e5 --- /dev/null +++ b/commands/explore-idea.md @@ -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 diff --git a/commands/plan-feature.md b/commands/plan-feature.md new file mode 100644 index 0000000..78fb30b --- /dev/null +++ b/commands/plan-feature.md @@ -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 +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 diff --git a/commands/plan-project.md b/commands/plan-project.md new file mode 100644 index 0000000..ada8669 --- /dev/null +++ b/commands/plan-project.md @@ -0,0 +1,335 @@ +# Plan Project + +Automate initial project planning: gather requirements, generate planning docs, create SESSION.md, and prepare for Phase 1. + +--- + +## Your Task + +Follow these steps to take a project from description to ready-to-code state. + +### 0. Check for PROJECT_BRIEF.md (Optional) + +**If PROJECT_BRIEF.md exists** in project root or planning/ directory: + +```bash +ls PROJECT_BRIEF.md planning/PROJECT_BRIEF.md 2>/dev/null +``` + +**If found:** +- Read PROJECT_BRIEF.md first +- Extract validated scope, tech stack, and constraints +- Use as context for project-planning skill invocation +- Skip redundant questions (tech stack and scope decisions already validated in brief) + +**Note**: PROJECT_BRIEF.md is created by the `/explore-idea` command during pre-planning exploration. It contains research findings and validated decisions that streamline the planning process. + +**If not found:** +- Continue normally to step 1 +- project-planning skill will handle all requirements gathering + +### 1. Invoke project-planning Skill + +**If project description is vague or incomplete**, ask 1-2 clarifying questions first: +- "What's the core functionality? (e.g., task manager, blog, analytics dashboard)" +- "Any specific tech requirements beyond the default stack?" + +**Then invoke the project-planning skill** with the project description: +- The skill will handle all clarifying questions (auth, data model, features, scope) +- The skill will generate appropriate planning docs (IMPLEMENTATION_PHASES.md + others as needed) +- Wait for skill to complete and output planning docs + +**Note**: Do NOT ask the same questions the skill will ask. Let the skill handle requirements gathering. + +### 2. Verify Planning Docs Exist + +Check that these files were created: +- `docs/IMPLEMENTATION_PHASES.md` (required) +- Other docs as generated (DATABASE_SCHEMA.md, API_ENDPOINTS.md, etc.) + +Run: +```bash +ls docs/IMPLEMENTATION_PHASES.md +``` + +**If IMPLEMENTATION_PHASES.md doesn't exist:** +- Output: "❌ Planning failed. IMPLEMENTATION_PHASES.md not found." +- Output: "The project-planning skill should have created this file. Try running the skill manually." +- Stop here + +### 3. Create SESSION.md + +**Read IMPLEMENTATION_PHASES.md** to extract phases: +```bash +# Extract project name, phase count, and phase details +``` + +**Create SESSION.md** in project root using this template: + +```markdown +# Session State + +**Current Phase**: Phase 1 +**Current Stage**: Implementation +**Last Checkpoint**: [none yet] ([date]) +**Planning Docs**: `docs/IMPLEMENTATION_PHASES.md`[, `docs/DATABASE_SCHEMA.md`][, other docs...] + +--- + +## Phase 1: [Phase Name] 🔄 +**Type**: [Type] | **Started**: [date] +**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-1` + +**Progress**: +- [ ] [First task from IMPLEMENTATION_PHASES.md] +- [ ] [Second task] +- [ ] [Third task] + +**Next Action**: [Concrete first action from phase tasks] + +**Key Files**: +- [List key files from phase] + +**Known Issues**: None + +## Phase 2: [Phase Name] ⏸️ +**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-2` + +## Phase 3: [Phase Name] ⏸️ +**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-3` + +[... list all remaining phases with ⏸️ status ...] +``` + +**Verify SESSION.md created:** +```bash +ls SESSION.md +``` + +### 4. Create Initial Git Commit (If Not Already Committed) + +**Check if planning docs are committed:** +```bash +git status --short docs/ SESSION.md +``` + +**If uncommitted planning docs exist:** + +Stage all planning docs: +```bash +git add docs/ SESSION.md +``` + +Check if this is initial commit: +```bash +git log --oneline | wc -l +``` + +**Create structured commit:** + +Extract from IMPLEMENTATION_PHASES.md: +- Total number of phases +- Estimated total hours +- Phase names + +**If this is first commit** (count = 0): +```bash +git commit -m "$(cat <<'EOF' +Initial project planning + +Generated planning documentation: +- IMPLEMENTATION_PHASES.md ([N] phases, ~[X] hours) +[- DATABASE_SCHEMA.md] +[- API_ENDPOINTS.md] +[- ARCHITECTURE.md] +[- other docs...] +- SESSION.md (session tracking) + +Next: Start Phase 1 - [Phase 1 Name] + +🤖 Generated with [Claude Code](https://claude.com/claude-code) + +Co-Authored-By: Claude +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 +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 diff --git a/commands/release.md b/commands/release.md new file mode 100644 index 0000000..54d1847 --- /dev/null +++ b/commands/release.md @@ -0,0 +1,1420 @@ +# Release + +Safely prepare project for public GitHub release by sanitizing files, checking documentation, and validating configuration. + +--- + +## Your Task + +Follow these steps to ensure project is safe to publish publicly. Run comprehensive safety checks before pushing to GitHub or creating public release. + +### Pre-Phase 0: GitHub Repository Setup (Optional) + +This phase ensures you have a GitHub repository configured before running safety checks. If you already have a remote repository, this phase will be skipped automatically. + +#### 0a. Check GitHub CLI + +**Check if gh CLI is installed**: + +```bash +which gh +``` + +**If gh NOT installed**: +``` +ℹ️ GitHub CLI (gh) not installed + +GitHub CLI provides easy repository creation and management. + +Install it? (y/n/skip) + +Install options: +- macOS: brew install gh +- Linux: See https://github.com/cli/cli/blob/trunk/docs/install_linux.md +- Windows: winget install --id GitHub.cli + +Or choose 'skip' to set up repository manually. +``` + +**If user chooses 'skip' or 'n'**: +``` +ℹ️ Skipping GitHub CLI setup + +You'll need to create the repository manually if it doesn't exist. +Proceeding to safety checks... +``` + +Continue to Phase 1. + +**If gh IS installed or user installs it**: +``` +✅ GitHub CLI installed +``` + +Continue to 0b. + +--- + +#### 0b. Check GitHub Authentication + +**Check if authenticated**: + +```bash +gh auth status +``` + +**If NOT authenticated**: +``` +⚠️ Not authenticated with GitHub + +Authenticate now? (y/n) +``` + +**If yes**: +```bash +gh auth login +``` + +Follow the interactive prompts to authenticate. + +**After authentication**: +``` +✅ Authenticated with GitHub +``` + +**If no**: +``` +ℹ️ Skipping authentication + +You won't be able to create repositories automatically. +Proceeding to safety checks... +``` + +Continue to Phase 1. + +--- + +#### 0c. Check Git Remote Configuration + +**Check if git remote exists**: + +```bash +git remote -v +``` + +**If NO remote configured**: +``` +⚠️ No git remote configured + +This project doesn't have a GitHub repository set up yet. + +Options: +1. Create new GitHub repository (recommended) +2. Add existing remote URL manually +3. Skip (set up later) + +Your choice (1/2/3): +``` + +**If choice 1 (Create new repo)**: + +Continue to 0d (Create Repository). + +**If choice 2 (Manual setup)**: +``` +Enter remote URL (e.g., https://github.com/username/repo.git): +``` + +After user provides URL: +```bash +git remote add origin [user-provided-url] +``` + +Output: +``` +✅ Remote added: origin → [url] +``` + +Continue to 0e (Verify Repository). + +**If choice 3 (Skip)**: +``` +ℹ️ Skipping remote setup + +⚠️ Note: You'll need a remote repository to release publicly. +Set it up manually later with: + git remote add origin [URL] + +Proceeding to safety checks... +``` + +Continue to Phase 1. + +**If remote ALREADY configured**: +``` +✅ Remote configured: origin → [URL] +``` + +Continue to 0e (Verify Repository). + +--- + +#### 0d. Create New GitHub Repository + +**Extract project details**: + +```bash +# Try to get project name from various sources +# 1. From package.json +node -p "require('./package.json').name" 2>/dev/null + +# 2. From current directory name if package.json fails +basename "$(pwd)" + +# 3. Get description if available +node -p "require('./package.json').description" 2>/dev/null +``` + +**Propose repository creation**: +``` +Creating new GitHub repository + +Project name: [detected-name] +Description: [detected-description or "No description"] + +Repository settings: +``` + +**Ask for visibility**: +``` +Repository visibility: +1. Public (recommended for open source) +2. Private + +Your choice (1/2): +``` + +**Ask if description needs editing** (if one was detected): +``` +Use detected description? (y/n) +"[detected-description]" +``` + +If no: +``` +Enter description (or leave blank): +``` + +**Confirm before creating**: +``` +Ready to create repository: + +Name: [name] +Description: [description] +Visibility: [public/private] +Owner: [your-github-username] + +Create repository? (y/n) +``` + +**If yes**: + +```bash +# Create repository and set as remote in one command +gh repo create [name] --[public/private] --source=. --remote=origin --description "[description]" +``` + +**If creation succeeds**: +``` +✅ Repository created: https://github.com/[user]/[name] +✅ Remote configured: origin → https://github.com/[user]/[name].git +``` + +Continue to Phase 1. + +**If creation fails**: +``` +❌ Repository creation failed: [error message] + +Common causes: +- Repository name already exists +- Invalid repository name (use lowercase, hyphens, underscores only) +- Network connectivity issues +- GitHub authentication expired + +Options: +1. Try different name +2. Add existing remote manually +3. Skip and set up later + +Your choice (1/2/3): +``` + +Handle choice accordingly (retry with new name, manual setup, or skip). + +--- + +#### 0e. Verify Repository Exists on GitHub + +**If remote is configured, verify it actually exists**: + +```bash +# Extract repo info from remote URL +git remote get-url origin + +# Try to view the repository +gh repo view 2>&1 +``` + +**If repository EXISTS**: +``` +✅ GitHub repository verified: [repo-url] +``` + +Continue to Phase 1. + +**If repository DOES NOT exist**: +``` +⚠️ Remote configured but repository doesn't exist on GitHub + +Remote URL: [url from git remote] +Status: Repository not found (404) + +This usually happens when: +- Remote URL was added but repo never created +- Repository was deleted +- Remote URL contains a typo + +Options: +1. Create repository at this URL (if you own it) +2. Change to different remote URL +3. Skip (set up manually later) + +Your choice (1/2/3): +``` + +**If choice 1 (Create at URL)**: + +Extract repo name from URL and create: +```bash +# Parse owner/repo from URL +# Example: https://github.com/username/repo.git → username/repo + +gh repo create [parsed-name] --[public/private] --source=. +``` + +**After creation**: +``` +✅ Repository created: [url] +``` + +Continue to Phase 1. + +**If choice 2 (Change URL)**: +``` +Enter new remote URL: +``` + +After user provides URL: +```bash +git remote set-url origin [new-url] +``` + +Re-run verification (go back to start of 0e). + +**If choice 3 (Skip)**: +``` +⚠️ Proceeding without verified GitHub repository + +Note: Some features may not work (GitHub releases, etc.) + +Proceeding to safety checks... +``` + +Continue to Phase 1. + +--- + +**Pre-Phase 0 Summary** (shown before Phase 1 starts): + +``` +═══════════════════════════════════════════════ + REPOSITORY SETUP COMPLETE +═══════════════════════════════════════════════ + +[✅/ℹ️] GitHub CLI: [installed/not installed] +[✅/ℹ️] Authentication: [authenticated/skipped] +[✅/⚠️] Remote: [configured/not configured] +[✅/⚠️] Repository: [verified/created/skipped] + +Repository: [url or "Not configured"] + +═══════════════════════════════════════════════ + +Proceeding to safety checks... + +═══════════════════════════════════════════════ +``` + +--- + +### Phase 1: Critical Safety Checks (BLOCKERS) + +These checks MUST pass before release. If any fail, STOP and require manual fixes. + +#### 1. Scan for Secrets + +**Check for secrets in current files**: + +```bash +# Check if gitleaks is installed +which gitleaks +``` + +**If gitleaks installed**: +```bash +# Scan current files for secrets +gitleaks detect --no-git --source=. --verbose +``` + +**If gitleaks NOT installed**: +``` +⚠️ gitleaks not installed. Skipping automated secrets detection. + +To install: brew install gitleaks +Or: wget https://github.com/gitleaks/gitleaks/releases/latest/download/gitleaks_[version]_linux_x64.tar.gz + +Proceeding with manual checks... +``` + +**Manual secret checks** (if gitleaks not available): + +Check these files for secrets: +```bash +# Check .env files +find . -name ".env*" -o -name "*.env" | grep -v node_modules + +# Check wrangler.toml for API keys +grep -i "api_key\|token\|secret\|password" wrangler.toml 2>/dev/null + +# Check config files +find . -name "config.ts" -o -name "config.js" -o -name "*.config.*" | head -20 +``` + +**Common secret patterns to look for**: +- API keys: `api_key = "sk_..."` +- Tokens: `token = "ghp_..."` +- Passwords: `password = "..."` +- Private keys: `-----BEGIN PRIVATE KEY-----` + +**If secrets found**: +``` +❌ BLOCKER: Secrets detected in files + +Files with potential secrets: +[List files] + +STOP: Do NOT proceed with release. + +Actions required: +1. Remove secrets from files +2. Move to environment variables or secrets management +3. Verify not committed to git history: git log -S "secret_value" +4. If in git history: git filter-branch or BFG Repo-Cleaner required + +Run /release again after fixing. +``` + +**If no secrets found**: +``` +✅ No secrets detected in current files +``` + +--- + +#### 2. Check Personal Artifacts + +**Check for personal/session files**: + +```bash +# Check for SESSION.md +ls SESSION.md 2>/dev/null + +# Check for planning directory +ls -d planning/ 2>/dev/null + +# Check for screenshots directory +ls -d screenshots/ 2>/dev/null + +# Check for temporary test files +find . -name "test-*.js" -o -name "test-*.ts" -o -name "*.test.local.*" | head -10 +``` + +**If personal artifacts found**: +``` +⚠️ Personal artifacts detected: + +[List files found] + +These files contain your session/planning data and should NOT be published. + +Options: +1. Remove them (recommended for clean public repo) +2. Add to .gitignore and keep locally +3. Keep them (if you want public planning docs) + +Your choice (1/2/3): +``` + +**If choice 1 (Remove)**: +```bash +# Confirm removal +echo "Remove these files? (y/n)" +``` + +If yes: +```bash +# Remove files +rm -f SESSION.md +rm -rf planning/ +rm -rf screenshots/ +find . -name "test-*.js" -delete +find . -name "test-*.ts" -delete + +# Stage deletions +git add -A +``` + +Output: +``` +✅ Personal artifacts removed +``` + +**If choice 2 (Add to .gitignore)**: +```bash +# Add to .gitignore +echo "" >> .gitignore +echo "# Personal artifacts (not for public release)" >> .gitignore +echo "SESSION.md" >> .gitignore +echo "planning/" >> .gitignore +echo "screenshots/" >> .gitignore +echo "test-*.js" >> .gitignore +echo "test-*.ts" >> .gitignore + +git add .gitignore +``` + +Output: +``` +✅ Personal artifacts added to .gitignore +``` + +**If choice 3 (Keep)**: +``` +ℹ️ Keeping personal artifacts. They will be published. + +Note: SESSION.md and planning/ may confuse other users. +Consider adding a note to README explaining they're example workflow artifacts. +``` + +**If no personal artifacts found**: +``` +✅ No personal artifacts detected +``` + +--- + +#### 3. Verify Remote URL + +**Check git remote**: + +```bash +git remote -v +``` + +**Verify**: +- Remote URL is YOUR repository, not someone else's +- Not pushing to upstream of a fork (unless intended) + +**If remote looks incorrect**: +``` +⚠️ Remote URL verification: + +Current remote: +origin [URL from git remote -v] + +Is this YOUR repository where you want to publish? (y/n) +``` + +**If no**: +``` +❌ BLOCKER: Incorrect remote URL + +Actions required: +1. Set correct remote: git remote set-url origin [your-repo-url] +2. Verify: git remote -v +3. Run /release again + +STOP: Do NOT proceed with release. +``` + +**If yes**: +``` +✅ Remote URL verified +``` + +--- + +### Phase 2: Documentation Validation + +These checks are REQUIRED but not blockers (can proceed with warnings). + +#### 4. LICENSE Check + +**Check for LICENSE file**: + +```bash +ls LICENSE LICENSE.md LICENSE.txt 2>/dev/null +``` + +**If LICENSE missing**: +``` +❌ REQUIRED: LICENSE file missing + +Without a license, your code is NOT open source (all rights reserved by default). + +Would you like to add a license? (y/n) +``` + +**If yes**: +``` +Which license? + +1. MIT (permissive, most popular) +2. Apache 2.0 (permissive, patent grant) +3. GPL-3.0 (copyleft, derivatives must be open source) +4. BSD-3-Clause (permissive, similar to MIT) +5. I'll add it manually + +Your choice (1-5): +``` + +**If choice 1-4**: Create LICENSE file with chosen license text (use standard templates) + +**After creating**: +```bash +git add LICENSE +``` + +Output: +``` +✅ LICENSE created (MIT) +``` + +**If LICENSE exists**: +```bash +# Detect license type +head -5 LICENSE +``` + +Output: +``` +✅ LICENSE present ([detected type: MIT/Apache/GPL/etc.]) +``` + +--- + +#### 5. README Check + +**Check README completeness**: + +```bash +# Check if README exists +ls README.md 2>/dev/null + +# Count words +wc -w README.md 2>/dev/null +``` + +**If README missing**: +``` +❌ REQUIRED: README.md missing + +A README is essential for public projects. + +Create basic README template? (y/n) +``` + +**If yes**: Create basic README template with project name, description, installation, usage, license sections. + +**If README exists but < 100 words**: +``` +⚠️ README exists but very short ([X] words) + +Consider adding: +- Project description +- Installation instructions +- Usage examples +- License information +``` + +**If README exists and >= 100 words**: + +Check for basic sections: +```bash +# Check for key sections +grep -i "## Install\|## Usage\|## License" README.md +``` + +**If missing sections**: +``` +⚠️ README missing recommended sections: + +Missing: +[- Installation instructions (## Installation)] +[- Usage examples (## Usage)] +[- License mention (## License)] + +Recommendation: Add these sections for better documentation +``` + +**If all sections present**: +``` +✅ README complete (>100 words, key sections present) +``` + +--- + +#### 6. CONTRIBUTING.md Check (Recommended) + +**Check project size**: +```bash +# Count lines of code (exclude node_modules, dist, etc.) +find . -name "*.ts" -o -name "*.js" -o -name "*.tsx" -o -name "*.jsx" | \ + grep -v node_modules | grep -v dist | grep -v build | \ + xargs wc -l 2>/dev/null | tail -1 +``` + +**If > 500 lines of code**: + +Check for CONTRIBUTING.md: +```bash +ls CONTRIBUTING.md 2>/dev/null +``` + +**If missing**: +``` +ℹ️ CONTRIBUTING.md missing (recommended for projects >500 LOC) + +This file helps contributors understand how to contribute. + +Create CONTRIBUTING.md template? (y/n) +``` + +**If yes**: Create basic CONTRIBUTING.md template. + +**If < 500 lines of code**: +``` +✅ Project small enough to skip CONTRIBUTING.md +``` + +**If CONTRIBUTING.md exists**: +``` +✅ CONTRIBUTING.md present +``` + +--- + +#### 7. CODE_OF_CONDUCT Check (Recommended) + +**Check project size**: +```bash +# Same LOC count as above +``` + +**If > 1000 lines of code**: + +Check for CODE_OF_CONDUCT: +```bash +ls CODE_OF_CONDUCT.md 2>/dev/null +``` + +**If missing**: +``` +ℹ️ CODE_OF_CONDUCT.md missing (recommended for larger projects) + +Create Contributor Covenant template? (y/n) +``` + +**If yes**: Create standard Contributor Covenant template. + +**If < 1000 lines of code**: +``` +✅ Project small enough to skip CODE_OF_CONDUCT +``` + +**If CODE_OF_CONDUCT exists**: +``` +✅ CODE_OF_CONDUCT present +``` + +--- + +### Phase 3: Configuration Validation + +#### 8. .gitignore Check + +**Check if .gitignore exists**: +```bash +ls .gitignore 2>/dev/null +``` + +**If missing**: +``` +⚠️ .gitignore missing + +Create .gitignore with common patterns? (y/n) +``` + +**If yes**: Create .gitignore with common patterns for detected project type. + +**If .gitignore exists**: + +Check for common patterns: +```bash +# Check for essential patterns +grep -E "node_modules|\.env|\.log|dist/|build/" .gitignore +``` + +**If missing essential patterns**: +``` +⚠️ .gitignore missing recommended patterns: + +Missing: +[- node_modules/ (dependencies)] +[- .env* (secrets)] +[- *.log (logs)] +[- dist/ or build/ (build artifacts)] + +Add missing patterns? (y/n) +``` + +**If yes**: Append missing patterns to .gitignore. + +**If all patterns present**: +``` +✅ .gitignore valid (essential patterns present) +``` + +--- + +#### 9. Package Files Check + +**Detect project type**: +```bash +ls package.json pyproject.toml setup.py go.mod Cargo.toml 2>/dev/null +``` + +**If Node.js (package.json)**: + +Check required fields: +```bash +# Extract key fields +node -p "const pkg=require('./package.json'); + JSON.stringify({ + name: pkg.name, + version: pkg.version, + description: pkg.description, + license: pkg.license, + repository: pkg.repository + }, null, 2)" +``` + +**If missing fields**: +``` +⚠️ package.json missing recommended fields: + +Missing: +[- name] +[- version] +[- description] +[- license] +[- repository] + +Recommendation: Add these fields for npm compatibility +``` + +**If Python (pyproject.toml or setup.py)**: + +Check for basic metadata. + +**If Go (go.mod)**: + +Check module path. + +**If all fields present**: +``` +✅ package.json complete (all required fields present) +``` + +--- + +#### 10. Branch Verification + +**Check current branch**: +```bash +git branch --show-current +``` + +**If on main/master**: +``` +⚠️ You're on main/master branch + +Recommendation: Create a release-prep branch for these changes. + +Create release-prep branch? (y/n) +``` + +**If yes**: +```bash +git checkout -b release-prep +``` + +Output: +``` +✅ Switched to release-prep branch +``` + +**If on feature/release branch**: +``` +✅ On feature branch ([branch name]) +``` + +--- + +### Phase 4: Quality Checks (Non-Blocking) + +These checks provide warnings but don't block release. + +#### 11. Build Test + +**Detect build command**: +```bash +# Check package.json for build script +grep "\"build\":" package.json 2>/dev/null + +# Or check for common build files +ls tsconfig.json vite.config.ts webpack.config.js 2>/dev/null +``` + +**If build command detected**: +``` +Testing build... (this may take a minute) +``` + +```bash +npm run build 2>&1 +``` + +**If build succeeds**: +``` +✅ Build succeeds +``` + +**If build fails**: +``` +⚠️ Build failed + +Error: [build error output] + +Recommendation: Fix build errors before release. + +Continue anyway? (y/n) +``` + +**If no build command**: +``` +ℹ️ No build command detected (skipping build test) +``` + +--- + +#### 12. Dependency Vulnerabilities + +**If Node.js project**: +```bash +npm audit --audit-level=high +``` + +**If vulnerabilities found**: +``` +⚠️ Dependency vulnerabilities detected: + +[npm audit output] + +Recommendation: Run `npm audit fix` to resolve. + +Continue anyway? (y/n) +``` + +**If no vulnerabilities**: +``` +✅ No critical dependency vulnerabilities +``` + +**If not Node.js**: +``` +ℹ️ Dependency vulnerability check not applicable +``` + +--- + +#### 13. Large Files Warning + +**Scan for large files (>1MB)**: +```bash +find . -type f -size +1M | grep -v node_modules | grep -v .git | grep -v dist | grep -v build +``` + +**If large files found**: +``` +⚠️ Large files detected (>1MB): + +[List files with sizes] + +Recommendation: Consider: +- Using Git LFS for binaries +- Moving to external storage (R2, S3) +- Adding to .gitignore if build artifacts + +Continue anyway? (y/n) +``` + +**If no large files**: +``` +✅ No large files detected +``` + +--- + +### Phase 5: Release Readiness Report + +**Output comprehensive report**: + +``` +═══════════════════════════════════════════════ + RELEASE READINESS REPORT +═══════════════════════════════════════════════ + +🔐 SECURITY (Blockers) +[✅/❌] No secrets detected +[✅/⚠️/❌] Personal artifacts [removed/ignored/kept] +[✅/❌] Remote URL verified + +📄 DOCUMENTATION +[✅/❌] LICENSE ([type]) +[✅/⚠️/❌] README ([complete/incomplete/missing]) +[✅/ℹ️] CONTRIBUTING.md ([present/not needed]) +[✅/ℹ️] CODE_OF_CONDUCT ([present/not needed]) + +⚙️ CONFIGURATION +[✅/⚠️/❌] .gitignore ([valid/incomplete/missing]) +[✅/⚠️] package.json ([complete/incomplete]) +[✅/⚠️] On [branch name] ([good/use feature branch]) + +🧪 QUALITY (Non-Blocking) +[✅/⚠️/ℹ️] Build [succeeds/fails/not applicable] +[✅/⚠️/ℹ️] Dependencies [no vulnerabilities/vulnerabilities/not applicable] +[✅/⚠️] Large files [none/detected] + +═══════════════════════════════════════════════ + +BLOCKERS: [N] +WARNINGS: [N] +RECOMMENDATIONS: [N] + +SAFE TO RELEASE: [✅ YES / ⚠️ YES (with warnings) / ❌ NO] + +═══════════════════════════════════════════════ +``` + +**If blockers**: +``` +❌ Cannot release: [N] blockers must be fixed + +Fix blockers and run /release again. +``` + +STOP here. Do not proceed. + +**If warnings but no blockers**: +``` +⚠️ Can release with warnings + +Warnings: +[List warnings] + +Recommendation: Fix warnings before release. + +Proceed anyway? (y/n) +``` + +**If no blockers or warnings**: +``` +✅ Ready to release! + +All checks passed. Safe to proceed with release. +``` + +--- + +### Phase 6: Offer to Fix Issues + +For each fixable issue, offer auto-fix: + +**Missing LICENSE**: +``` +Create LICENSE? (y/n) +[If yes: Create chosen license file] +``` + +**Incomplete README**: +``` +Add missing README sections? (y/n) +[If yes: Open README for editing, show template sections to add] +``` + +**Missing .gitignore patterns**: +``` +Add recommended .gitignore patterns? (y/n) +[If yes: Append patterns] +``` + +**Personal artifacts**: +``` +Remove/ignore personal artifacts? (y/n) +[If yes: Remove or add to .gitignore] +``` + +**On main branch**: +``` +Create release-prep branch? (y/n) +[If yes: git checkout -b release-prep] +``` + +--- + +### Phase 7: Git Preparation + +**Check for uncommitted changes**: +```bash +git status --short +``` + +**If changes exist**: +``` +You have uncommitted changes from release preparation: + +[git status output] + +Create release preparation commit? (y/n) +``` + +**If yes**: +```bash +git add -A + +git commit -m "$(cat <<'EOF' +chore: prepare for release + +Release preparation changes: +- [LICENSE created (MIT) OR LICENSE verified] +- [README sections added OR README verified] +- [.gitignore patterns added OR .gitignore verified] +- [Personal artifacts removed OR Personal artifacts ignored] +- [Other changes...] + +Security: No secrets detected +Documentation: Complete +Configuration: Valid + +Ready for public release + +🤖 Generated with [Claude Code](https://claude.com/claude-code) + +Co-Authored-By: Claude +EOF +)" +``` + +Output: +``` +✅ Release preparation commit created +``` + +**Offer to create git tag**: +``` +Create version tag? (y/n) + +Version number (e.g., v1.0.0): +``` + +**If yes**: +```bash +git tag [version] +``` + +Output: +``` +✅ Tag created: [version] +``` + +**Offer to push**: +``` +Push to remote (branch + tags)? (y/n) +``` + +**If yes**: +```bash +git push origin [branch-name] +git push origin --tags +``` + +Output: +``` +✅ Pushed to remote: origin/[branch-name] +✅ Tags pushed +``` + +**If no uncommitted changes**: +``` +ℹ️ No uncommitted changes to commit +``` + +--- + +### Phase 8: GitHub Release (Optional) + +**Check if gh CLI available**: +```bash +which gh +``` + +**If gh CLI available**: +``` +Create GitHub release? (y/n) + +This will create a public release on GitHub with release notes. +``` + +**If yes**: +``` +Version tag (e.g., v1.0.0): [use tag from Phase 7 or ask for new one] +Release title (e.g., "Initial Release" or "v1.0.0 - Feature Name"): +``` + +**Generate release notes from recent commits**: +```bash +# Get commits since last tag (or all if no previous tags) +git log --oneline --no-merges $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD +``` + +**Show draft release notes**: +``` +─────────────────────────────────────────────── +DRAFT RELEASE NOTES +─────────────────────────────────────────────── + +## What's New + +[Auto-generated from commit messages] + +## Installation + +```bash +npm install [package-name] +# or +git clone [repo-url] +``` + +## Documentation + +See [README.md](README.md) for full documentation. + +─────────────────────────────────────────────── + +Edit release notes? (y/n) +``` + +**If yes**: Open for editing. + +**Create release**: +```bash +gh release create [tag] \ + --title "[title]" \ + --notes "[release notes]" \ + [--draft] \ + [--prerelease] +``` + +Output: +``` +✅ GitHub release created: [URL] +``` + +**If gh CLI not available**: +``` +ℹ️ GitHub CLI not installed + +To create release manually: +1. Go to: https://github.com/[user]/[repo]/releases/new +2. Tag version: [tag] +3. Release title: [title] +4. Description: [release notes from above] + +Or install gh CLI: brew install gh +``` + +--- + +### Phase 9: Final Summary + +**Output final summary**: + +``` +═══════════════════════════════════════════════ + RELEASE COMPLETE ✅ +═══════════════════════════════════════════════ + +📦 PACKAGE: [Project Name] +🏷️ VERSION: [tag] +🌐 REMOTE: [repo URL] + +CHANGES MADE: +[✅ LICENSE created (MIT)] +[✅ README verified] +[✅ Personal artifacts removed] +[✅ .gitignore updated] +[✅ Release commit created] +[✅ Tag created: [version]] +[✅ Pushed to origin/[branch]] +[✅ GitHub release created] + +─────────────────────────────────────────────── +NEXT STEPS +─────────────────────────────────────────────── + +1. If on feature branch: Create PR to merge to main + gh pr create --title "Release [version]" + +2. After merge: Create GitHub release (if not done) + gh release create [version] + +3. If npm package: Publish to npm + npm publish + +4. Share your release! + - Post on social media + - Add to README badges + - Announce in relevant communities + +═══════════════════════════════════════════════ + +🎉 Your project is ready for public release! + +═══════════════════════════════════════════════ +``` + +--- + +## Error Handling + +**Not a git repository**: +``` +❌ Not a git repository + +Run /release in a git repository. + +Initialize git? (y/n) +``` + +If yes: `git init` + +--- + +**No remote configured**: +``` +⚠️ No git remote configured + +Add remote URL: +git remote add origin [URL] + +Then run /release again. +``` + +--- + +**Git push fails**: +``` +⚠️ Push failed: [error message] + +Common fixes: +- Set upstream: git push -u origin [branch] +- Check permissions: gh auth status +- Verify remote: git remote -v + +Fix the issue and push manually, or run /release again. +``` + +--- + +**GitHub release creation fails**: +``` +⚠️ GitHub release creation failed: [error] + +Create manually: https://github.com/[user]/[repo]/releases/new + +Or: gh auth login (authenticate GitHub CLI) +``` + +--- + +**Build test fails**: +``` +⚠️ Build failed + +This is not a blocker, but recommended to fix before release. + +Continue anyway? (y/n) +``` + +--- + +## Success Criteria + +✅ No secrets detected in files +✅ Personal artifacts handled (removed or gitignored) +✅ Remote URL verified +✅ LICENSE file present +✅ README complete (>100 words, key sections) +✅ .gitignore valid +✅ User has clear next steps +✅ User knows exact release status (blockers, warnings, recommendations) +✅ User can proceed with confidence + +--- + +## Notes + +**Purpose**: Safety checks before public release, not a substitute for security audits + +**Philosophy**: Prevent embarrassing mistakes (secrets leak, missing LICENSE, poor documentation) + +**Integration**: Works alongside existing `open-source-contributions` skill (which focuses on contributing TO other projects, not releasing YOUR projects) + +**Scope**: GitHub releases (not npm publish, PyPI, Docker, etc. - those are separate workflows) + +--- + +**Version**: 1.0.0 +**Last Updated**: 2025-11-07 diff --git a/commands/workflow.md b/commands/workflow.md new file mode 100644 index 0000000..1e6898d --- /dev/null +++ b/commands/workflow.md @@ -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 diff --git a/commands/wrap-session.md b/commands/wrap-session.md new file mode 100644 index 0000000..c48a518 --- /dev/null +++ b/commands/wrap-session.md @@ -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 +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 diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..7ec12ba --- /dev/null +++ b/plugin.lock.json @@ -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": [] + } +} \ No newline at end of file