zhongwei/gh-unclecode-claude-code-tools-plugins-unclecode-cc-toolkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:03:52 +08:00
commit 0b586b3216
42 changed files with 5241 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
commands/pp-add.md Normal file
View File

@@ -0,0 +1,120 @@
# Add New Subproject
Create a new subproject in the project structure.
## Arguments
$ARGUMENTS
## Purpose
Add a new subproject with full file structure. Query should contain:
- Subproject name (folder name)
- Description/purpose
- Optionally: initial scope, dependencies
## Execution Instructions
### Step 1: Parse Query
Extract from query:
- `name`: Folder name (lowercase, no spaces)
- `title`: Human-readable title
- `description`: What this subproject does
- `dependencies`: Relationships to other subprojects
If query is empty or missing info, ask:
1. "Subproject folder name (e.g., 'api', 'frontend'):"
2. "Title (e.g., 'REST API Backend'):"
3. "Brief description:"
4. "Dependencies on other subprojects? (optional)"
### Step 2: Create Directory Structure
```bash
mkdir -p .context/project/{name}/prds .context/project/{name}/docs .context/project/{name}/archive
```
### Step 3: Copy and Process Templates
Copy subproject templates from `~/.claude/commands/pp-init-assets/templates/subproject/`:
```bash
# Copy all subproject templates
cp ~/.claude/commands/pp-init-assets/templates/subproject/*.md .context/project/{name}/
```
Then process placeholders:
- `{{SUBPROJECT_NAME}}` → name
- `{{SUBPROJECT_TITLE}}` → title
- `{{SUBPROJECT_DESCRIPTION}}` → description
- `{{DATE}}` → current date
- `{{SUBPROJECT_STATUS}}` → "Not Started"
- Other placeholders → "TBD" or empty
### Step 4: Update Root Files
**INDEX.md**: Add to subproject table
```markdown
| {name}/ | Planned | {description} |
```
**STATUS.md**: Add to subproject summary table
```markdown
| {name}/ | - | Not Started |
```
**CODEBASE.md**: Add to subproject refs
```markdown
- `{name}/CODEBASE.md` - {title} files
```
**CHANGELOG.md**: Add entry
```markdown
## {DATE} | Added Subproject: {name}
**Changes**:
- Created {name}/ subproject structure
**Context**:
- {description}
```
### Step 5: Confirm Creation
```
## Created Subproject: {name}/
**Title**: {title}
**Description**: {description}
**Files created**:
- {name}/INDEX.md
- {name}/STATUS.md
- {name}/TODO.md
- {name}/CHANGELOG.md
- {name}/PRINCIPLES.md
- {name}/CODEBASE.md
- {name}/LESSONS.md
**Updated**:
- Root INDEX.md
- Root STATUS.md
- Root CODEBASE.md
- Root CHANGELOG.md
To start working on this subproject, update STATUS.md to set it as active.
```
## Query Examples
```bash
# Full description
/pp-add api - REST API backend using FastAPI, handles auth and data
# Just name (will ask for details)
/pp-add mobile
# With dependencies
/pp-add frontend - React dashboard, depends on api for data
```

181
commands/pp-checkpoint.md Normal file
View File

@@ -0,0 +1,181 @@
# Save Session Checkpoint
Save current chat session state and prepare instructions for next session.
## Arguments
$ARGUMENTS
Optional query to specify what should happen next.
## Purpose
Called at the end of a chat session (or before hitting token limits) to:
1. Create ultra-compact summary of current session
2. Save "what to do next" instructions for new session
3. Link to full chat transcript (with warnings about size)
## Execution Instructions
### Step 1: Identify Current Session
```bash
# Get current working directory
pwd
# Convert to Claude projects path
# Example: /Users/unclecode/devs/project
# Becomes: ~/.claude/projects/-Users-unclecode-devs-project/
# Find most recent .jsonl file (exclude agent-* files)
ls -lt ~/.claude/projects/-Users-unclecode-devs-{converted-path}/*.jsonl | grep -v "agent-" | head -1
# Extract UUID from filename
# Example: 530170ff-52f5-4ad6-a333-22a09bd64773.jsonl
# UUID: 530170ff-52f5-4ad6-a333-22a09bd64773
```
### Step 2: Determine Active Subproject
Read `.context/project/INDEX.md` to identify active subproject.
### Step 3: Generate "What To Do Next"
**If user provided query:**
- Use their query as primary guidance
- Enhance with context from current state
**If NO query provided:**
- Analyze current state:
- Read `TODO.md` - what's pending
- Read last 2-3 `CHANGELOG.md` entries - what was just done
- Read `STATUS.md` - current focus
- Generate clear next actions
### Step 4: Create History Summary (Ultra-Compact)
**Location**: `.context/project/{active}/history/{uuid}-{YYYY-MM-DD}.md`
**Content** (token-efficient, ~200-400 tokens for main summary + warnings):
```markdown
# Chat Session {uuid}
**Date**: {YYYY-MM-DD HH:MM}
**Tokens Used**: ~{approximate} / 200k
## Key Achievements
- [T###] Task completed
- Major milestone reached
- Decision made
## Technical Decisions
- Technology choice with rationale
- Architecture decision
- Library/framework selected
## Files Created/Modified
- path/to/file.ext
- another/file.js
## What's Next
{Brief 1-2 line summary}
---
## Full Chat Transcript
**⚠️ IMPORTANT**: Full conversation available at:
`{full-path-to-jsonl-file}`
**WARNING**: This file is LARGE (~2-3MB, ~140k+ tokens). NEVER load it entirely.
**How to use it**:
- Use `grep` to search for specific topics
- Use `tail -n 100` for recent messages
- Use `head -n 100` for session start
- Use `sed -n 'START,ENDp'` for specific line ranges
- Parse JSON with `jq` for structured queries
**Example commands**:
```bash
# Search for specific topic
grep -i "your topic" {path-to-file}
# Get last 50 messages
tail -n 50 {path-to-file}
# Count total lines
wc -l {path-to-file}
```
```
**Important**: Keep main summary VERY compact. Transcript warnings go at end.
### Step 5: Create/Update NEXT.md (Minimal)
**Location**: `.context/project/{active}/NEXT.md`
**Content** (keep minimal, link to history for details):
```markdown
# Next Chat Session
## What To Do Next
{AI-generated guidance OR user's query}
Examples:
- User will fill knowledge base at webhook/maya_knowledge.md
- Begin T010: Node.js project setup
- Continue implementation of LLMService
- Review PRD and provide feedback
## Previous Session Context
**Session**: {uuid} ({YYYY-MM-DD})
See: [history/{uuid}-{YYYY-MM-DD}.md](history/{uuid}-{YYYY-MM-DD}.md)
## Current State
**Active Phase**: {from STATUS.md}
**Pending Tasks**: {high-priority tasks from TODO.md}
**Blockers**: {if any}
**Last Updated**: {files recently modified}
```
**Important**: Keep NEXT.md minimal. All detailed context (including full transcript warnings) goes in the history file.
### Step 6: Output Confirmation
Tell user:
```
✅ Checkpoint saved!
Files created/updated:
- .context/project/{active}/NEXT.md (instructions for next session)
- .context/project/{active}/history/{uuid}-{date}.md (session summary)
When starting next session:
1. Run `/pp-resume` to load context + next steps
2. Continue from where we left off
Session ID: {uuid}
```
## Notes
- Always create history/ directory if it doesn't exist
- NEXT.md is overwritten each time (always shows latest)
- History files are never overwritten (one per session)
- Keep summaries ultra-compact to save tokens
- Full transcript path is for rare cases when specific detail needed
## Error Handling
If unable to find session UUID:
- Inform user
- Still create NEXT.md with guidance
- Skip history file creation (not critical)
If active subproject unclear:
- Ask user which subproject
- Or use root .context/project/ as fallback

194
commands/pp-clean.md Normal file
View File

@@ -0,0 +1,194 @@
# Clean Project Files
Clean up temporary files and archive useful markdown.
## Arguments
$ARGUMENTS
## Purpose
After tasks/updates, clean up the project:
1. **Delete** truly temporary files (test outputs, scratch, debug logs)
2. **Archive** potentially useful markdown (drafts, notes, old versions)
3. Keep project directory clean while preserving history
## Execution Instructions
### Step 1: Scan for Files to Clean
Look in project root and common locations for:
**Temporary files (to DELETE):**
- `*_test.md`, `test_*.md`
- `scratch*.md`, `temp*.md`, `tmp*.md`
- `debug*.md`, `*_debug.md`
- `*.log` (unless in logs/ folder)
- `output*.md`, `*_output.md`
- Files with `DELETE` or `TEMP` in name
**Potentially useful markdown (to ARCHIVE):**
- `draft_*.md`, `*_draft.md`
- `notes_*.md`, `*_notes.md`
- `research_*.md`
- `old_*.md`, `*_old.md`, `*_backup.md`
- `v1_*.md`, `*_v1.md` (old versions)
- Any `.md` file in root that's not part of standard structure
- User-created markdown during session
### Step 2: Parse Optional Query
If query provided, focus on:
- Specific pattern: `/pp-clean test files`
- Specific folder: `/pp-clean webhook/`
- Specific action: `/pp-clean archive only` or `/pp-clean delete only`
### Step 3: Show Preview
```
## Cleanup Preview
### To DELETE (temporary files)
- scratch_booking.md
- test_output.md
- debug_log.md
### To ARCHIVE (move to .context/project/archive/)
- draft_system_prompt.md
- research_notes.md
- old_booking_flow.md
### No Action
- (files that look fine)
---
Proceed with cleanup? (yes/no/edit)
```
If user says "edit", allow them to:
- Move items between delete/archive
- Skip specific files
- Add files to clean
### Step 4: Execute Cleanup
**Delete temporary files:**
```bash
rm {temp_files}
```
**Archive useful markdown:**
```bash
# Create dated archive subfolder if multiple files
mkdir -p .context/project/archive/cleanup_{date}
mv {markdown_files} .context/project/archive/cleanup_{date}/
```
Or if single file:
```bash
mv {file} .context/project/archive/{file}
```
### Step 5: Update CHANGELOG
Add entry to appropriate CHANGELOG:
```markdown
## {DATE} | Cleanup
**Deleted**:
- scratch_booking.md
- test_output.md
**Archived**:
- draft_system_prompt.md → archive/cleanup_{date}/
- research_notes.md → archive/cleanup_{date}/
**Context**:
- Post-task cleanup
- {query context if provided}
```
### Step 6: Confirm Completion
```
## Cleanup Complete
**Deleted**: 3 temporary files
**Archived**: 2 markdown files → archive/cleanup_{date}/
Project directory is clean.
```
## Auto-Trigger Integration
This cleanup logic should also run:
- After `/pp-update` completes
- After major task completion
- Before commits (optional)
When auto-triggered, still show preview and get confirmation.
## Query Examples
```bash
# General cleanup
/pp-clean
# Focus on specific pattern
/pp-clean test files
# Focus on specific folder
/pp-clean webhook/
# Archive only (no deletions)
/pp-clean archive only
# Delete only (no archiving)
/pp-clean delete only
# With context
/pp-clean after completing booking flow
```
## Safety Rules
1. **Always show preview first**
2. **Always get confirmation**
3. **Never delete .md files that might be useful** - archive them
4. **Never touch:**
- `.context/project/` structure files
- Files in `prds/`, `docs/` folders
- `.env`, config files
- Source code files
5. **Log everything** in CHANGELOG
## File Patterns Reference
### Safe to DELETE
```
*_test.md, test_*.md
scratch*.md, temp*.md, tmp*.md
debug*.md, *_debug.md
output*.md, *_output.md
*.log (loose logs)
*DELETE*, *TEMP*
```
### Should ARCHIVE
```
draft_*.md, *_draft.md
notes_*.md, *_notes.md
research_*.md
old_*.md, *_old.md, *_backup.md
v[0-9]_*.md, *_v[0-9].md
Loose .md files not in structure
```
### Never Touch
```
.context/project/**/*.md (structure files)
prds/*.md, docs/*.md
README.md, CLAUDE.md
.env, *.json, *.py, *.js, etc.
```

129
commands/pp-edit.md Normal file
View File

@@ -0,0 +1,129 @@
# Edit Project Progress Files
Quick, natural language edits to project planning files.
## Arguments
$ARGUMENTS
Query describing what to edit.
## Purpose
Make direct edits to PP files using natural language without manually finding and editing files.
## Execution Instructions
### Step 1: Parse Edit Query
Extract from query:
1. **Target file** (INDEX.md, WORKFLOW.md, PRINCIPLES.md, STATUS.md, TODO.md, etc.)
2. **Action** (add, update, remove, change)
3. **Content** (what to add/change/remove)
4. **Location** (root or subproject)
**Query patterns:**
- "add X to Y" → append content
- "update X in Y to Z" → replace content
- "remove X from Y" → delete content
- "change X to Y" → replace content
### Step 2: Identify File Location
**Root files** (in `.context/project/`):
- INDEX.md
- WORKFLOW.md
- PRINCIPLES.md
- LESSONS.md
**Subproject files** (in `.context/project/{subproject}/`):
- STATUS.md
- TODO.md
- CHANGELOG.md
- CODEBASE.md
- LESSONS.md
- PRINCIPLES.md (if exists)
If query doesn't specify subproject and file is subproject-level:
- Read INDEX.md to get active subproject
- Apply edit to active subproject's file
### Step 3: Validate Target
Check if target file exists:
```bash
ls .context/project/{target_file}
# or
ls .context/project/{subproject}/{target_file}
```
If file doesn't exist, inform user and ask if they want to create it.
### Step 4: Apply Edit
**For "add" operations:**
- Append content to appropriate section
- Maintain markdown formatting
- Add to end of file or specific section if mentioned
**For "update/change" operations:**
- Find existing content
- Replace with new content
- Preserve formatting
**For "remove" operations:**
- Find and delete content
- Clean up extra blank lines
### Step 5: Confirm Changes
Show diff or summary:
```
## Edit Applied
**File**: .context/project/PRINCIPLES.md
**Action**: Added new principle
**Content added**:
> Always use TypeScript strict mode
**Location**: End of file
File updated successfully.
```
## Query Examples
```bash
# Add to root files
/pp-edit add "Daily standup at 9am" to WORKFLOW.md
/pp-edit update PRINCIPLES.md to include "Use functional programming patterns"
# Update INDEX.md
/pp-edit change active subproject to backend
/pp-edit add high-level TODO "Launch MVP by March 15"
# Edit subproject files (uses active subproject)
/pp-edit add task "T050: Implement password reset" to TODO.md
/pp-edit update STATUS.md working section with "API endpoints complete"
/pp-edit remove "T010: Initial setup" from TODO.md
# Edit specific subproject
/pp-edit add "Use Redis for caching" to backend PRINCIPLES.md
/pp-edit update frontend STATUS.md blocked section with "Waiting for API completion"
```
## Smart Parsing
If query is ambiguous, ask clarifying questions:
- "Which file? (INDEX.md, WORKFLOW.md, PRINCIPLES.md, STATUS.md, TODO.md)"
- "Which subproject? (main, backend, frontend)"
- "Where in the file? (beginning, end, specific section)"
## Notes
- Always preserve existing content unless explicitly asked to replace
- Maintain markdown formatting and structure
- If adding to structured files (TODO.md, CHANGELOG.md), follow existing format
- Show what changed so user can verify
- Suggest commit after edit: "Ready to commit? Run: /pp-update"

270
commands/pp-fetch-docs.md Normal file
View File

@@ -0,0 +1,270 @@
# Fetch API Documentation
Fetch and cache API documentation in AI-readable markdown format.
## Arguments
$ARGUMENTS
Library name, URL, or package identifier (e.g., "openai", "stripe", "https://docs.stripe.com")
## Purpose
Download and cache API documentation locally for quick reference across all projects. Docs are stored globally in the plugin directory and available in all chat sessions.
## Storage Location
**Global (available across all projects):**
```
~/.claude/plugins/marketplaces/unclecode-tools/plugins/unclecode-cc-toolkit/api-docs/
```
## Execution Instructions
### Step 1: Parse Input
Extract from query:
- **Library name** (e.g., "openai", "stripe", "nextjs")
- **URL** (if provided, e.g., "https://docs.stripe.com")
- **Version** (optional, e.g., "openai@4.0")
Normalize library name:
- Remove special characters
- Convert to lowercase
- Remove version suffix for directory name
### Step 2: Check if Docs Exist
Check for existing documentation:
```bash
ls ~/.claude/plugins/marketplaces/unclecode-tools/plugins/unclecode-cc-toolkit/api-docs/{library}/
```
**If directory exists:**
- List what's there: `ls -lah api-docs/{library}/`
- Show last modified date
- Ask user:
```
## Documentation Exists
**Library**: {library}
**Location**: api-docs/{library}/
**Last Updated**: {date from stat}
**Files**: {file count} files, {total size}
Documentation already cached. Would you like to:
1. Use existing docs (skip)
2. Update/re-fetch docs
3. View what's cached
```
Wait for user response.
**If doesn't exist:**
- Proceed to Step 3
### Step 3: Fetch Documentation
Try these methods in order:
#### Method 1: Context7 API
**If library name provided (no URL):**
```bash
# Search for library
curl -X GET "https://context7.com/api/v1/search?query={library}" \
-H "Authorization: Bearer CONTEXT7_API_KEY"
# Get library ID from response
# Then fetch docs
curl -X GET "https://context7.com/api/v1/{library_id}/docs?type=txt&tokens=5000" \
-H "Authorization: Bearer CONTEXT7_API_KEY"
```
**Note**: Free tier available (no API key needed but rate-limited)
Save response to: `api-docs/{library}/context7-docs.md`
If successful, skip to Step 4.
#### Method 2: llms.txt
**If URL provided OR Context7 doesn't have it:**
1. Extract domain from URL
2. Try to fetch `{domain}/llms.txt`:
```bash
curl -s https://{domain}/llms.txt
```
3. If llms.txt exists:
- Parse the file (contains list of markdown doc URLs)
- Fetch each markdown URL listed
- Save each to: `api-docs/{library}/{filename}.md`
If successful, skip to Step 4.
#### Method 3: Web Scraping
**If neither Context7 nor llms.txt available:**
1. Fetch the docs page HTML
2. Convert HTML to markdown using a clean method:
- Extract main content (remove nav, footer, ads)
- Convert to markdown
- Clean up formatting
3. Save to: `api-docs/{library}/scraped-docs.md`
Add note at top of file:
```markdown
<!-- Scraped from {URL} on {date} -->
<!-- May need manual review for accuracy -->
```
### Step 4: Create Metadata File
Create `api-docs/{library}/metadata.json`:
```json
{
"library": "library-name",
"source": "context7|llms.txt|web-scraped",
"sourceUrl": "original-url",
"fetchedAt": "2025-01-23T10:30:00Z",
"fileCount": 3,
"totalSize": "250KB",
"version": "4.0.0" (if specified)
}
```
### Step 5: Create Index
If multiple files were fetched, create `api-docs/{library}/INDEX.md`:
```markdown
# {Library} API Documentation
**Fetched from**: {source}
**Date**: {date}
**Version**: {version if known}
## Files
- [context7-docs.md](./context7-docs.md) - Main documentation
- [api-reference.md](./api-reference.md) - API reference
- [guides.md](./guides.md) - Usage guides
## Quick Links
{Parse and list major sections/topics}
```
### Step 6: Confirm Success
Show summary:
```
## Documentation Fetched Successfully
**Library**: {library}
**Source**: {Context7 | llms.txt | Web}
**Location**: ~/.claude/plugins/.../api-docs/{library}/
**Files Saved**: {count} files ({total size})
### What's Available:
{List files with brief description}
### Usage:
These docs are now available globally across all projects.
To reference in your code:
- Ask Claude to "check {library} docs"
- Use /pp-triage for debugging with library context
- Docs automatically available in all future sessions
### Next Steps:
- View docs: cat api-docs/{library}/INDEX.md
- Update later: /pp-fetch-docs {library} (will prompt to update)
```
## Query Examples
```bash
# Fetch by library name (tries Context7 first)
/pp-fetch-docs openai
/pp-fetch-docs stripe
/pp-fetch-docs nextjs
# Fetch by URL (tries llms.txt, then scrapes)
/pp-fetch-docs https://docs.stripe.com
/pp-fetch-docs https://platform.openai.com/docs
# Fetch specific version
/pp-fetch-docs openai@4.0
/pp-fetch-docs react@18
# Update existing docs
/pp-fetch-docs openai
> "Documentation exists. Update? (yes/no)"
> yes
> (re-fetches and overwrites)
```
## Error Handling
**If all methods fail:**
```
## Unable to Fetch Documentation
**Library**: {library}
**Attempted**:
- ❌ Context7: Library not found
- ❌ llms.txt: Not available at {domain}
- ❌ Web scraping: {error reason}
### Suggestions:
1. Check library name spelling
2. Provide full URL to documentation
3. Try alternative library name (e.g., "@openai/sdk" vs "openai")
4. Manually download docs and save to:
~/.claude/plugins/.../api-docs/{library}/docs.md
Would you like me to:
- Search for alternative library names?
- Try a different URL?
- Help you manually organize docs?
```
## Notes
- Docs are **global** - stored in plugin directory, not project-specific
- Available across ALL projects and chat sessions
- Context7 preferred (most up-to-date, version-specific)
- llms.txt is official standard (website-published)
- Web scraping is last resort (may need cleanup)
- Update anytime by re-running command
- Large docs may be split into multiple files for better organization
## API Keys (Optional)
For Context7 higher rate limits:
- Get free API key: https://context7.com/dashboard
- Set environment variable: `export CONTEXT7_API_KEY="your-key"`
- Plugin will auto-detect and use it
## Best Practices
**When to fetch:**
- Starting a new project with specific APIs
- Learning a new library
- Need up-to-date reference (re-fetch to update)
- Debugging issues (fresh docs help)
**Storage management:**
- Each library typically: 100-500KB
- Plugin directory has no size limit
- Delete old docs: `rm -rf api-docs/{library}/`
- View all cached: `ls api-docs/`

248
commands/pp-help.md Normal file
View File

@@ -0,0 +1,248 @@
# Project Progress System - Help Guide
Complete guide for using the Project Progress (PP) system.
## Arguments
$ARGUMENTS
Optional: Specify topic for focused help (e.g., `/pp-help init`, `/pp-help workflow`)
## Overview
The Project Progress system helps you track development with:
- **Subproject-based organization** (main, backend, frontend, etc.)
- **Structured documentation** (STATUS, TODO, CHANGELOG, CODEBASE)
- **Session continuity** (checkpoint and resume between chats)
- **AI-optimized format** (easy for Claude to understand context)
---
## Quick Start
### For New Projects
```bash
# Interactive mode (recommended for first time)
/pp-init
# Or quiet mode (instant setup with "main" subproject)
/pp-init --quiet
```
### For Existing Projects
```bash
# Migrate existing project (uses AI agents to discover structure)
/pp-migrate
```
---
## File Structure
```
.context/project/
├── INDEX.md # Project overview + active subproject + high-level TODOs
├── WORKFLOW.md # How to use this system
├── PRINCIPLES.md # Project principles
├── LESSONS.md # Lessons learned
│
└── {subproject}/ # e.g., "main", "backend", "frontend"
├── STATUS.md # Current status, what's working/blocked
├── TODO.md # Detailed task list
├── CHANGELOG.md # Change history
├── CODEBASE.md # File inventory
├── LESSONS.md # Subproject-specific lessons
├── PRINCIPLES.md # (optional) Subproject-specific principles
├── prds/ # Product requirement documents
├── docs/ # Documentation
├── archive/ # Archived items
└── history/ # Session checkpoints
```
---
## Core Commands
### Start New Session
```bash
/pp-resume # Load all context, continue work
/pp-resume [direction] # Resume with specific focus
```
### Update Documentation
```bash
/pp-update # Interactive: ask what changed
/pp-update completed T010, T011 # Quick update with description
```
### Session Management
```bash
/pp-checkpoint # Save session, prepare for next chat
/pp-checkpoint [instructions] # Save with specific next-session instructions
```
### View Status
```bash
/pp-status # Full project status
/pp-status tasks # Focus on tasks only
/pp-status blockers # Focus on blockers
```
### Manage Structure
```bash
/pp-add [checkpoint] # Add a checkpoint
/pp-remove [checkpoint] # Remove a checkpoint
/pp-clean # Clean temporary files
```
### Utilities
```bash
/pp-version # Show plugin version
/pp-help # This help guide
```
---
## Typical Workflow
### 1. First Session (New Project)
```bash
# Initialize structure
/pp-init
# Work on your project...
# (code, debug, build features)
# Before ending session
/pp-update added initial setup files
/pp-checkpoint Continue with user authentication
```
### 2. Next Session
```bash
# Load context
/pp-resume
# Claude shows: "Ready to continue with user authentication"
# Work on tasks...
# Update as you go
/pp-update completed T015, added auth service
# End session
/pp-checkpoint Implement password reset flow
```
### 3. Check Status Anytime
```bash
/pp-status
```
Shows:
- Active subproject
- In-progress tasks
- Pending tasks
- Blockers
- Recent changes
---
## File Purpose Guide
| File | When to Update | Purpose |
|------|----------------|---------|
| **INDEX.md** (root) | Switch active subproject, add high-level TODOs | Project overview + status |
| **WORKFLOW.md** | Never (system guide) | How to use PP system |
| **PRINCIPLES.md** | Add project-wide principles | Methodology & rules |
| **STATUS.md** (subproject) | State changes | Current status, working/blocked |
| **TODO.md** | Add/complete tasks | Task tracking |
| **CHANGELOG.md** | After changes | Change history with context |
| **CODEBASE.md** | Add/modify files | File inventory |
| **LESSONS.md** | After debugging | Problems → solutions |
---
## Best Practices
### Task Management (TODO.md)
```markdown
- [ ] T001: Task description
- [>] T002: In-progress task (currently working)
- [x] T003: Completed task
- [-] T004: Cancelled task
```
### Changelog Format
```markdown
## 2025-01-15 | Commit: abc123
**Changes**: Added user authentication
**Usage**: `POST /api/auth/login` with email/password
**Context**: Using JWT with 24h expiry
```
### Status Clarity
Keep STATUS.md current:
- What's working
- What's blocked (and why)
- Current focus (1-3 items)
- Next actions
---
## Multiple Subprojects
```bash
# Initialize with multiple subprojects
/pp-init Full-stack app with backend (FastAPI), frontend (React), and mobile (React Native). Starting with backend.
```
Creates:
```
.context/project/
├── INDEX.md
├── WORKFLOW.md
├── PRINCIPLES.md
└── backend/
└── (STATUS, TODO, CHANGELOG, etc.)
└── frontend/
└── (STATUS, TODO, CHANGELOG, etc.)
└── mobile/
└── (STATUS, TODO, CHANGELOG, etc.)
```
Switch active subproject by editing INDEX.md or using `/pp-update`.
---
## Getting Help
**By Topic:**
```bash
/pp-help init # Help with initialization
/pp-help workflow # Workflow guide
/pp-help commands # Command reference
```
**Troubleshooting:**
- Structure missing? Run `/pp-init` or `/pp-migrate`
- Commands not working? Check `/pp-version`
- Need to update? Reinstall plugin
**Support:**
- GitHub: https://github.com/unclecode/claude-code-tools
- Issues: https://github.com/unclecode/claude-code-tools/issues
---
## Version
Run `/pp-version` to check your installed version.

65
commands/pp-init-assets/templates/root/INDEX.md Normal file
View File

@@ -0,0 +1,65 @@
# {{PROJECT_NAME}} - Project Index
**Project**: {{PROJECT_DESCRIPTION}}
**Created**: {{DATE}}
**Last Updated**: {{DATE}}
---
## Active Subproject
**{{ACTIVE_SUBPROJECT}}**
See `{{ACTIVE_SUBPROJECT}}/STATUS.md` for detailed status.
---
## Quick Start (New Session)
1. Read this INDEX.md (root overview + current state)
2. Read WORKFLOW.md (understand the system)
3. Go to active subproject folder: `{{ACTIVE_SUBPROJECT}}/`
4. Read subproject's STATUS.md, TODO.md, and other files
---
## Project-Level TODO (High-Level)
**Major Milestones & Cross-Subproject Tasks:**
- [ ] {{TODO_ITEM_1}}
- [ ] {{TODO_ITEM_2}}
- [ ] {{TODO_ITEM_3}}
*For detailed tasks, see subproject TODO.md files*
---
## Subprojects
| Subproject | Status | Phase | Description |
|------------|--------|-------|-------------|
{{SUBPROJECT_TABLE}}
---
## Subproject Status Summary
{{SUBPROJECT_STATUS_TABLE}}
---
## File Inheritance
Root files (WORKFLOW.md, PRINCIPLES.md) apply to all subprojects.
Subproject files extend/override root when needed.
**Reading order:**
1. Root level files (WORKFLOW, PRINCIPLES)
2. Subproject files (STATUS, TODO, CODEBASE, etc.)
---
## Environment
{{ENVIRONMENT}}

22
commands/pp-init-assets/templates/root/LESSONS.md Normal file
View File

@@ -0,0 +1,22 @@
# Lessons Learned (Root)
Shared learnings applicable to all subprojects. Subprojects have their own LESSONS.md.
---
## Format
```
### [TAG] Short Title
**Problem**: What went wrong
**Investigation**: What was tried
**Root Cause**: Why it happened
**Solution**: How it was fixed
**Keywords**: searchable terms
```
Tags: [BUG], [CONFIG], [API], [LOGIC], [INTEGRATION]
---
<!-- Add lessons that apply to multiple subprojects below -->

154
commands/pp-init-assets/templates/root/PRINCIPLES.md Normal file
View File

@@ -0,0 +1,154 @@
# Principles & Rules (Root)
Base methodology and rules for all subprojects. Subprojects can extend/override.
---
## Core Philosophy
**Small, Smart, Strong**
- Small changes, well-tested
- Smart solutions, not over-engineered
- Strong foundations before features
---
## Debugging Methodology
### Inverted Confidence Rule
**Code I wrote this session**: 20% confidence it's correct
- Assume I made a mistake
- Prove it works before moving on
- Test thoroughly
**Existing code**: 80% confidence it's correct
- Assume it works as intended
- Prove it's broken before touching it
- Respect that it was tested/debugged
### Debugging Decision Tree
```
Bug appears
├─ Is there NEW code involved?
│ └─ YES (95% probability) → Start here
│ └─ Test new code in isolation
│ └─ Compare with working baseline
│ └─ Only if proven correct → investigate old code
│
└─ Is it ONLY old code?
└─ Verify nothing changed
└─ Check environment, dependencies, inputs
```
### Before Blaming Existing Code
1. Why would this have worked before if it's broken?
2. What changed between working and not working?
3. Is there any NEW code in the path?
If answer to #3 is YES → investigate new code FIRST.
---
## Feature Addition Approach
1. **Understand first** - Read existing code, understand patterns
2. **Plan before coding** - Explain changes, get confirmation
3. **Minimal changes** - Don't refactor unrelated code
4. **Test incrementally** - Small steps, verify each
5. **Document** - Update TODO, CHANGELOG, relevant docs
---
## Code Change Rules
1. **Focus on explicit request** - Don't add unrequested changes
2. **Root cause analysis** - For non-trivial bugs, explain before fixing
3. **Explain fundamental changes** - Before implementing, discuss
4. **Don't over-commit** - Test before suggesting commit
5. **Stay doubtful** - Don't assume it works, verify
---
## Error Handling
- Technical issues → Inform user, explain what's being checked
- Unexpected inputs → Handle gracefully or escalate
- Escalate early if uncertain
---
## Testing Approach
1. Unit test new functions
2. Integration test with mocked APIs
3. End-to-end test with real systems
4. Log everything during testing
5. Verify before marking task complete
---
# Rules (Dos & Don'ts)
Hard rules for Claude behavior. Added by user based on observed issues.
**Never remove rules. Only add.**
Format: `R###: Rule description` + Context
---
## General Behavior
**R001**: Do not add "co-author" or Claude Code references in commit messages
Context: User preference, keep commits clean
**R002**: Do not say "you're absolutely right" or similar excessive validation
Context: Maintain objectivity, don't sugar coat
**R003**: Do not assume task is done and suggest commit without testing
Context: Stay doubtful, verify before declaring success
**R004**: Do not start implementation without confirmation when user explains feature
Context: User wants to see proposed changes first, then approve
**R005**: When explaining changes, wait for confirmation before coding
Context: Avoid wasted work on wrong approach
**R006**: Always show major file content for review before writing
Context: User is system designer, needs to approve before files are created
**R007**: Commit after completing each small, logical change
Context: Git history becomes a book telling the story of how the app was built. Each commit is a chapter. Keeps history clean and reviewable.
---
## Code & Architecture
**R010**: Do not create new files unless absolutely necessary
Context: Prefer editing existing files
**R011**: Do not refactor unrelated code when fixing a bug
Context: Focus on explicit request only
**R012**: Do not introduce security vulnerabilities (injection, XSS, etc.)
Context: Standard security practice
---
## Documentation
**R020**: Update project docs (TODO, CHANGELOG, STATUS) after changes
Context: Maintain context for future sessions
**R021**: Log debugging experiences in LESSONS.md
Context: Don't repeat past debugging efforts
---
<!--
Add new rules below. Use next available R### number.
Subproject-specific rules go in subproject's PRINCIPLES.md
-->

141
commands/pp-init-assets/templates/root/WORKFLOW.md Normal file
View File

@@ -0,0 +1,141 @@
# Project Workflow
How to work with this project management system.
---
## For New Chat Session
```
1. Read INDEX.md → understand project, current state, active subproject
2. Read WORKFLOW.md → understand system (this file)
3. Read PRINCIPLES.md → understand project principles
4. Go to active subproject folder (listed in INDEX.md)
5. Read subproject's STATUS.md, TODO.md, CODEBASE.md, CHANGELOG.md
6. Read subproject PRINCIPLES.md (if exists, overrides root)
7. Read LESSONS.md → avoid past mistakes
```
---
## After Making Changes
*All updates happen in the active subproject folder:*
1. **Update TODO.md** - Mark tasks done/in-progress
2. **Update CHANGELOG.md** - Log what changed with usage examples
3. **Update STATUS.md** - If system state changed
4. **Update LESSONS.md** - If debugging insight gained
5. **Update CODEBASE.md** - If files added/modified
6. **Update root INDEX.md** - If switching active subproject or adding high-level TODOs
7. **Commit** - Message references TODO ID
---
## File Update Guidelines
### TODO.md
- `[ ]` pending
- `[>]` in progress
- `[x]` completed
- `[-]` cancelled
- Format: `[status] T###: Description`
- Group by phase/PRD
### CHANGELOG.md
- Newest first (reverse chronological)
- Format: `## YYYY-MM-DD | Commit: <hash>`
- Include: Changes, Usage (examples/commands), Context
- Archive when >50 entries
### STATUS.md
- Keep current, not historical
- Sections: Working, Blocked, Current Focus, Recent Decisions
- Short bullet points
### LESSONS.md
- Format: Problem → Investigation → Root Cause → Solution
- Tag by category: [BUG], [CONFIG], [API], [LOGIC]
- Include searchable keywords
### CODEBASE.md
- Update after adding/modifying files
- One-line descriptions
- Group by component/purpose
---
## When to Create New PRD
- New phase starting
- Significant new feature
- Major refactor
PRD naming: `###_short_name.md` (e.g., `001_initial_setup.md`)
---
## When to Archive
**CHANGELOG.md**:
- When >50 entries or file getting very long
- Move older entries to `archive/CHANGELOG_YYYY_MM.md`
- Update archive index table in CHANGELOG.md with:
- Archive filename
- Date range
- Topic summary
- Keep index in main file for reference
**PRDs**:
- Completed PRDs → move to archive/
- Keep reference in INDEX.md
**Outdated docs**:
- Move to archive/ with date suffix
---
## Commit Message Format
```
<type>: <short description>
[T###] <todo item completed>
[T###] <another if multiple>
<optional details>
```
Types: feat, fix, docs, refactor, test
Example:
```
feat: Add user authentication
[T010] Create auth service
[T011] Add login endpoint
Using JWT with 24h expiry
```
---
## File Inheritance
Root files apply to all subprojects. Subproject files extend/override.
**Reading order:**
1. Root level files (base)
2. Subproject files (extends/overrides)
Example: Root PRINCIPLES.md has base rules, subproject PRINCIPLES.md adds specific rules.
---
## Principles Reference
Before debugging or adding features, check:
1. PRINCIPLES.md - methodology (root + subproject)
2. LESSONS.md - past solutions (root + subproject)
Don't repeat past mistakes.

44
commands/pp-init-assets/templates/subproject/CHANGELOG.md Normal file
View File

@@ -0,0 +1,44 @@
# {{SUBPROJECT_NAME}} Changelog
{{SUBPROJECT_NAME}}-specific changes. See root CHANGELOG for cross-project changes.
Reverse chronological. Newest first.
---
## Archived Changelogs
| Archive | Period | Topics |
|---------|--------|--------|
| (none yet) | - | - |
---
## {{DATE}} | Subproject Created
**Changes**:
- Created {{SUBPROJECT_NAME}}/ subproject structure
- Initial files added
**Context**:
- {{CREATION_CONTEXT}}
---
<!--
Template:
## YYYY-MM-DD | Commit: <hash>
**Tasks Completed**:
- [T###] Description
**Changes**:
- What was added/modified/removed
**Usage**:
- How to use what was added
**Context**:
- Why, decisions made
-->

33
commands/pp-init-assets/templates/subproject/CODEBASE.md Normal file
View File

@@ -0,0 +1,33 @@
# {{SUBPROJECT_NAME}} Codebase Map
{{SUBPROJECT_NAME}}-specific files. See root CODEBASE.md for shared files.
---
## Existing Files
| File | Description |
|------|-------------|
{{EXISTING_FILES}}
---
## To Be Created
| File | Description |
|------|-------------|
{{TO_CREATE_FILES}}
---
## Dependencies
| File | Source | Description |
|------|--------|-------------|
{{FILE_DEPENDENCIES}}
---
<!--
Update after creating/modifying subproject-specific files
-->

45
commands/pp-init-assets/templates/subproject/INDEX.md Normal file
View File

@@ -0,0 +1,45 @@
# {{SUBPROJECT_NAME}} - {{SUBPROJECT_TITLE}}
**Subproject**: {{SUBPROJECT_DESCRIPTION}}
**Status**: {{SUBPROJECT_STATUS}}
**Created**: {{DATE}}
---
## Quick Start
1. Read root INDEX.md and PRINCIPLES.md first (base context)
2. Read this INDEX.md
3. Read STATUS.md (current state)
4. Read TODO.md (pending tasks)
5. Read PRINCIPLES.md (subproject-specific rules)
---
## Scope
{{SCOPE}}
---
## File Map
| File | Purpose |
|------|---------|
| INDEX.md | This overview |
| STATUS.md | Current state |
| TODO.md | Task tracking |
| CHANGELOG.md | Subproject changes |
| PRINCIPLES.md | Subproject-specific rules |
| CODEBASE.md | Subproject-specific files |
| LESSONS.md | Subproject-specific lessons |
---
## Dependencies
{{DEPENDENCIES}}
---
<!-- Expand as work begins -->

22
commands/pp-init-assets/templates/subproject/LESSONS.md Normal file
View File

@@ -0,0 +1,22 @@
# {{SUBPROJECT_NAME}} Lessons Learned
{{SUBPROJECT_NAME}}-specific debugging experiences. See root LESSONS.md for shared lessons.
---
## Format
```
### [TAG] Short Title
**Problem**: What went wrong
**Investigation**: What was tried
**Root Cause**: Why it happened
**Solution**: How it was fixed
**Keywords**: searchable terms
```
Tags: [BUG], [CONFIG], [API], [LOGIC], [INTEGRATION]
---
<!-- Add subproject-specific lessons below -->

22
commands/pp-init-assets/templates/subproject/PRINCIPLES.md Normal file
View File

@@ -0,0 +1,22 @@
# {{SUBPROJECT_NAME}} Principles & Rules
{{SUBPROJECT_NAME}}-specific methodology and rules. Extends root PRINCIPLES.md.
---
## {{SUBPROJECT_NAME}}-Specific Principles
{{PRINCIPLES}}
---
## {{SUBPROJECT_NAME}}-Specific Rules
{{RULES}}
---
<!--
Add subproject-specific rules below.
Use R### numbering in reserved range for this subproject
-->

34
commands/pp-init-assets/templates/subproject/STATUS.md Normal file
View File

@@ -0,0 +1,34 @@
# {{SUBPROJECT_NAME}} Status
**Last Updated**: {{DATE}}
**Status**: {{SUBPROJECT_STATUS}}
---
## What's Working
{{WORKING}}
---
## What's Not Working / Blocked
{{BLOCKED}}
---
## Current Focus
{{FOCUS}}
---
## Environment
{{ENVIRONMENT}}
---
## Next Actions
{{NEXT_ACTIONS}}

26
commands/pp-init-assets/templates/subproject/TODO.md Normal file
View File

@@ -0,0 +1,26 @@
# {{SUBPROJECT_NAME}} TODO
**Format**: `[status] T###: Description`
- `[ ]` pending
- `[>]` in progress
- `[x]` completed
- `[-]` cancelled
---
## Phase 1
{{PHASE_1_TASKS}}
---
## Future Phases
{{FUTURE_TASKS}}
---
## Notes
- T### IDs are permanent, never reuse
- Reference T### in commit messages and CHANGELOG

164
commands/pp-init.md Normal file
View File

@@ -0,0 +1,164 @@
# Initialize Project Management Structure
Generate a multi-subproject management structure in `.context/project/`.
**Note**: For small projects needing only one subproject, use the name **"main"** as the default.
## Arguments
$ARGUMENTS
## Assets Location
Template files are in `~/.claude/commands/pp-init-assets/templates/`:
- `root/` - Root level templates (WORKFLOW.md, PRINCIPLES.md, etc.)
- `subproject/` - Subproject templates
## Execution Instructions
### Step 1: Parse Arguments
Check for mode:
- `--quiet` or `-q` → Quiet mode
- Contains text (not flags) → Description mode
- Empty → Interactive mode
### Step 2: Create Directory Structure
```bash
# Create root directories
mkdir -p .context/project/prds .context/project/docs .context/project/archive
# Create subproject directories (for each subproject)
mkdir -p .context/project/{subproject}/prds
mkdir -p .context/project/{subproject}/docs
mkdir -p .context/project/{subproject}/archive
mkdir -p .context/project/{subproject}/history
```
**Note**: The `history/` directory stores ultra-compact session summaries created by `/pp-checkpoint`.
### Step 3: Copy Fixed Templates
These files are copied as-is (no placeholders to fill):
```bash
# Copy WORKFLOW.md, PRINCIPLES.md, and LESSONS.md (fully populated)
cp ~/.claude/commands/pp-init-assets/templates/root/WORKFLOW.md .context/project/
cp ~/.claude/commands/pp-init-assets/templates/root/PRINCIPLES.md .context/project/
cp ~/.claude/commands/pp-init-assets/templates/root/LESSONS.md .context/project/
```
**Note**: Root level only has WORKFLOW, PRINCIPLES, LESSONS. All tracking files (STATUS, TODO, CHANGELOG, CODEBASE) live in subprojects.
### Step 4: Process Template Files
For files with `{{PLACEHOLDER}}` markers:
1. Read template from assets
2. Replace placeholders with collected data
3. Write to destination
**Root templates to process:**
- INDEX.md (combines project overview + active subproject + high-level TODOs + status summary)
**Subproject templates to process (for each subproject):**
- INDEX.md
- STATUS.md
- TODO.md
- CHANGELOG.md
- PRINCIPLES.md (optional - only if different from root)
- CODEBASE.md
- LESSONS.md
### Step 5: Mode-Specific Behavior
#### Quiet Mode (`--quiet`)
1. Create structure with 1 default subproject named "main"
2. Copy fixed templates
3. Process other templates with minimal placeholders:
- `{{DATE}}` → current date
- `{{PROJECT_NAME}}` → "Project"
- `{{SUBPROJECT_NAME}}` → "main"
- Other placeholders → leave as "TBD" or empty tables
4. No questions asked
#### Description Mode (text provided)
1. Parse description for:
- Project name
- Subproject names (look for patterns like "with X, Y, Z subprojects")
- Active subproject (look for "starting with" or first mentioned)
- Technologies mentioned
2. Ask clarifying questions only if critical info missing
3. Generate with parsed data
#### Interactive Mode (no arguments)
Ask these questions:
1. "What is the project name?"
2. "Brief description (one line):"
3. "List subprojects (comma-separated, e.g., 'frontend, backend, mobile'):"
4. "Which subproject is active first?"
5. "Key technologies? (optional)"
6. "Any environment details? (optional)"
Then generate with collected data.
## Placeholder Reference
### Root Level (INDEX.md)
| Placeholder | Description |
|-------------|-------------|
| `{{DATE}}` | Current date (YYYY-MM-DD) |
| `{{PROJECT_NAME}}` | Project name |
| `{{PROJECT_DESCRIPTION}}` | One-line description |
| `{{ACTIVE_SUBPROJECT}}` | Name of active subproject |
| `{{TODO_ITEM_1}}` | High-level TODO item 1 |
| `{{TODO_ITEM_2}}` | High-level TODO item 2 |
| `{{TODO_ITEM_3}}` | High-level TODO item 3 |
| `{{SUBPROJECT_TABLE}}` | Markdown table of subprojects with status/phase/description |
| `{{SUBPROJECT_STATUS_TABLE}}` | Compact status summary of all subprojects |
| `{{ENVIRONMENT}}` | Environment details |
### Subproject Level
| Placeholder | Description |
|-------------|-------------|
| `{{SUBPROJECT_NAME}}` | Subproject folder name |
| `{{SUBPROJECT_TITLE}}` | Human-readable title |
| `{{SUBPROJECT_DESCRIPTION}}` | What this subproject does |
| `{{SUBPROJECT_STATUS}}` | Current status |
| `{{SCOPE}}` | Bullet list of scope items |
| `{{WORKING}}` | What's currently working |
| `{{BLOCKED}}` | What's blocked |
| `{{FOCUS}}` | Current focus items |
| `{{NEXT_ACTIONS}}` | Next action items |
| `{{PHASE_1_TASKS}}` | Initial tasks |
| `{{FUTURE_TASKS}}` | Future phase tasks |
| `{{PRINCIPLES}}` | Subproject-specific principles |
| `{{RULES}}` | Subproject-specific rules |
| `{{EXISTING_FILES}}` | Existing file table rows |
| `{{TO_CREATE_FILES}}` | Files to create table rows |
| `{{FILE_DEPENDENCIES}}` | File dependencies table rows |
| `{{CREATION_CONTEXT}}` | Why subproject was created |
## After Generation
1. Show created structure (tree view)
2. List files that need customization
3. Suggest: "Fill in placeholders marked 'TBD', then create your first PRD"
## Examples
```bash
# Quiet mode - minimal structure
/pp-init --quiet
# With description
/pp-init E-commerce platform with frontend (React), backend (FastAPI), and mobile (React Native). Starting with backend.
# Interactive
/pp-init
```

262
commands/pp-migrate-v2.md Normal file
View File

@@ -0,0 +1,262 @@
# Migrate PP v1.0 to v1.1+ Structure
**TEMPORARY COMMAND**: Upgrades old Project Planning structure (v1.0.0) to new structure (v1.1.0+).
## Arguments
None
## Purpose
Migrate existing PP projects from old structure (with root STATUS.md, CODEBASE.md, CHANGELOG.md) to new simplified structure (with combined INDEX.md).
**Use this if you have projects using the old PP structure that need upgrading.**
## What Changes
### Old Structure (v1.0.0):
```
.context/project/
├── INDEX.md (old format)
├── STATUS.md ← will be archived
├── CODEBASE.md ← will be archived
├── CHANGELOG.md ← will be archived
├── WORKFLOW.md (old)
└── subproject/
```
### New Structure (v1.1.0+):
```
.context/project/
├── INDEX.md ← NEW (combines INDEX + STATUS + high-level TODOs)
├── WORKFLOW.md ← UPDATED
├── PRINCIPLES.md
├── LESSONS.md
└── subproject/ ← UNCHANGED
```
## Execution Instructions
### Step 1: Detect Old Structure
Check if this is an old PP structure:
```bash
ls .context/project/STATUS.md
```
**If STATUS.md doesn't exist:**
- Inform user: "Project already using new structure or not initialized. Nothing to migrate."
- Exit
**If STATUS.md exists:**
- Proceed to Step 2
### Step 2: Read Old Files
Read and extract data from old files:
**From STATUS.md:**
- Active subproject (section: "## Active Subproject")
- Subproject summary table (section: "## Subproject Summary")
- Overall progress (if any)
- Cross-project dependencies (if any)
- Recent decisions (if any)
**From INDEX.md (old):**
- Project name
- Project description
- Created date
- Subprojects table
- Environment info
**From CODEBASE.md:**
- Check if it had any important root-level file listings
- (Usually empty or minimal in old structure)
**From CHANGELOG.md:**
- Check if it had any cross-project entries
- (Usually empty or minimal in old structure)
### Step 3: Create New INDEX.md
Generate new INDEX.md using the template from `pp-init-assets/templates/root/INDEX.md`:
**Populate with extracted data:**
- `{{PROJECT_NAME}}` - from old INDEX.md
- `{{PROJECT_DESCRIPTION}}` - from old INDEX.md
- `{{DATE}}` - original created date from old INDEX.md
- `{{ACTIVE_SUBPROJECT}}` - from old STATUS.md
- `{{SUBPROJECT_TABLE}}` - from old INDEX.md
- `{{SUBPROJECT_STATUS_TABLE}}` - from old STATUS.md
- `{{ENVIRONMENT}}` - from old INDEX.md
- `{{TODO_ITEM_1}}`, `{{TODO_ITEM_2}}`, `{{TODO_ITEM_3}}` - set to "TBD" or extract from context
**Save to:** `.context/project/INDEX.md` (overwrite old INDEX.md)
### Step 4: Update WORKFLOW.md
Replace old WORKFLOW.md with new version:
```bash
cp ~/.claude/commands/pp-init-assets/templates/root/WORKFLOW.md .context/project/WORKFLOW.md
```
### Step 5: Archive Old Files
Move old root-level files to archive:
```bash
mkdir -p .context/project/archive/v1.0-migration-$(date +%Y%m%d)
mv .context/project/STATUS.md .context/project/archive/v1.0-migration-*/
mv .context/project/CODEBASE.md .context/project/archive/v1.0-migration-*/
mv .context/project/CHANGELOG.md .context/project/archive/v1.0-migration-*/
```
**Create archive README:**
Create `.context/project/archive/v1.0-migration-{date}/README.md`:
```markdown
# v1.0 Structure Archive
These files were archived during migration from PP v1.0.0 to v1.1.0+ on {date}.
## Archived Files
- STATUS.md - Replaced by combined INDEX.md
- CODEBASE.md - Moved to subproject level only
- CHANGELOG.md - Moved to subproject level only
## What Changed
v1.1.0+ simplified the root structure:
- Root now has only: INDEX.md, WORKFLOW.md, PRINCIPLES.md, LESSONS.md
- All detailed tracking (STATUS, TODO, CHANGELOG, CODEBASE) lives in subprojects
- INDEX.md now combines project overview + active subproject + status summary
## Data Preservation
All data from these files was extracted and merged into the new INDEX.md.
Nothing was lost during migration.
```
### Step 6: Verify Subprojects Unchanged
Confirm that subproject directories remain intact:
```bash
ls .context/project/{subproject}/
```
**Subprojects should still have:**
- STATUS.md
- TODO.md
- CHANGELOG.md
- CODEBASE.md
- etc.
**No changes needed** - subproject structure is the same in both versions.
### Step 7: Show Summary
Display migration summary:
```
## PP Structure Migration Complete
**Old Structure**: v1.0.0
**New Structure**: v1.1.0+
**Date**: {YYYY-MM-DD HH:MM}
### Changes Made:
✅ Created new INDEX.md (combines INDEX + STATUS + high-level TODOs)
✅ Updated WORKFLOW.md to new version
✅ Archived old files:
- STATUS.md → archive/v1.0-migration-{date}/
- CODEBASE.md → archive/v1.0-migration-{date}/
- CHANGELOG.md → archive/v1.0-migration-{date}/
### What Stayed the Same:
✓ All subproject directories unchanged
✓ All subproject files (STATUS, TODO, CHANGELOG, CODEBASE) intact
✓ Project data preserved in new INDEX.md
✓ PRINCIPLES.md, LESSONS.md unchanged
### New Root Structure:
.context/project/
├── INDEX.md ← NEW (combined)
├── WORKFLOW.md ← UPDATED
├── PRINCIPLES.md
├── LESSONS.md
└── {subprojects}/ ← UNCHANGED
### Next Steps:
1. Review new INDEX.md to verify data accuracy
2. Check active subproject is correct
3. Continue using PP commands as normal
4. Old files safely archived if you need to reference them
---
**Note**: This migration is one-way. The old files are archived, not deleted.
You can always reference them in the archive/ folder.
```
## Error Handling
**If .context/project/ doesn't exist:**
```
No PP structure found. Run /pp-init first to create project structure.
```
**If STATUS.md doesn't exist:**
```
Project already using new structure (v1.1.0+) or not fully initialized.
If you have subprojects but no root STATUS.md, you're likely already upgraded.
Nothing to migrate.
```
**If migration fails mid-way:**
```
Migration encountered an error. Your files are safe:
- Original files still in place
- Partial changes may exist
Recommendation:
1. Check .context/project/ directory
2. Manually review what was changed
3. Restore from backup if needed
4. Report issue to plugin maintainer
```
## Safety Features
- **Non-destructive**: Old files archived, not deleted
- **Backup created**: Archive folder with timestamp
- **Verification**: Checks structure before starting
- **Detailed logging**: Shows exactly what changed
## Usage Example
```bash
# In a project with old PP structure
cd /path/to/project
# Run migration
/pp-migrate-v2
# Result: Upgraded to new structure
# Old files safely archived
```
## Notes
- **Temporary command**: Will be removed in future versions once most projects are migrated
- **One-time operation**: Only need to run once per project
- **Idempotent**: Safe to run multiple times (detects if already migrated)
- **Subprojects untouched**: Only root structure changes
- **Data preserved**: Nothing is lost, everything merged into new INDEX.md
## Version History
- Created for v1.1.0 → v1.1.0+ migration
- To be deprecated in v2.0.0

175
commands/pp-migrate.md Normal file
View File

@@ -0,0 +1,175 @@
# Migrate Existing Project to Project Planning Structure
Convert an existing project (with scattered markdown/docs) to use `.context/project/` structure.
**Note**: For small projects needing only one subproject, use the name **"main"** as the default.
## Arguments
$ARGUMENTS
## Overview
This command:
1. Launches explorer agents to scan and understand your project
2. Discovers existing markdown files, subprojects, and current state
3. Creates `.context/project/` structure with pre-filled content
4. Optionally moves existing files to proper locations
## Execution Instructions
### Step 1: Initial Scan with Explorer Agents
Launch 5 parallel explorer agents to gather project information:
**Agent 1: Markdown Discovery**
```
Find all markdown files in the project. For each file:
- Path
- Title/purpose (from content)
- Type: documentation, decision log, notes, readme, spec, etc.
Report as structured list.
```
**Agent 2: Project Structure Analysis**
```
Analyze the codebase structure:
- Main directories and their purposes
- Identify potential subprojects/modules (e.g., frontend/, backend/, api/)
- Key technologies used
- Entry points and main files
Report the logical structure.
```
**Agent 3: Current State Discovery**
```
Find indicators of current project state:
- TODOs in code comments
- README status sections
- Any existing tracking files
- Recent git commits (last 10) for context
- Package.json, requirements.txt, etc. for dependencies
Report what's working, what's in progress.
```
**Agent 4: Configuration & Environment**
```
Find configuration details:
- Environment files (.env.example, config files)
- Build/deployment configs
- API endpoints or external services
- Database schemas if present
Report environment setup.
```
**Agent 5: Documentation Quality**
```
Assess existing documentation:
- Is there a main README?
- API docs?
- Architecture docs?
- Are docs up to date or stale?
Report documentation gaps and strengths.
```
### Step 2: Synthesize Findings
After agents complete:
1. Combine all findings
2. Identify:
- Project name (from package.json, README, or directory)
- Subprojects (from structure analysis)
- Current state (from state discovery)
- Existing files to migrate
- Documentation gaps
### Step 3: Ask Clarifying Questions
Present findings and ask:
1. "I found these potential subprojects: [list]. Is this correct? Any to add/remove?"
2. "Which subproject should be active/primary?"
3. "I found [N] markdown files. Should I organize them into the new structure?"
4. "Any additional context about the project I should know?"
### Step 4: Generate Structure with Content
Create `.context/project/` structure using `pp-init-assets/templates/` but:
**Pre-fill root INDEX.md instead of placeholders:**
- **INDEX.md**: Use discovered project name, description from README, list actual subprojects, set active subproject, add discovered high-level TODOs, fill subproject status table
- **WORKFLOW.md**: Copy as-is
- **PRINCIPLES.md**: Copy as-is
- **LESSONS.md**: Copy as-is
**For each subproject:**
- **INDEX.md**: Subproject overview
- **TODO.md**: Convert discovered TODOs from code into task list
- **STATUS.md**: Actual status from analysis
- **CODEBASE.md**: Files in that subproject
- **CHANGELOG.md**: Initialize with recent git history summary for that subproject
- **PRINCIPLES.md**: Only if subproject has specific principles (usually skip)
- **LESSONS.md**: Copy from root template
### Step 5: Migration Plan (Requires Confirmation)
Present migration plan:
```
Files to move:
- docs/api-spec.md → .context/project/{subproject}/docs/
- DECISIONS.md → .context/project/{subproject}/docs/
- old-notes.md → .context/project/archive/
Files to keep in place:
- README.md (root)
- CONTRIBUTING.md (root)
```
Ask: "Should I proceed with moving these files? (y/n)"
If yes, execute moves.
If no, skip migration, just create structure.
### Step 6: Final Report
Show:
1. Created structure (tree view)
2. Files that were migrated
3. Suggested next steps:
- Review generated STATUS.md for accuracy
- Add any missing TODOs
- Create first PRD for current work
## Templates Reference
Uses same templates as `/pp-init` from:
`~/.claude/commands/pp-init-assets/templates/`
But fills content from discovered information instead of placeholders.
## Examples
```bash
# Basic migration
/pp-migrate
# With context hint
/pp-migrate This is a Facebook ads automation project with webhook server and analytics dashboard
# Skip file migration
/pp-migrate --no-move
```
## Flags
- `--no-move`: Create structure but don't move existing files
- `--dry-run`: Show what would be done without making changes
## Notes
- Always backs up files before moving (copies to archive first)
- Preserves git history by using `git mv` when possible
- If `.context/project/` already exists, asks before overwriting

122
commands/pp-remove.md Normal file
View File

@@ -0,0 +1,122 @@
# Remove Subproject
Remove a subproject from the project structure.
## Arguments
$ARGUMENTS
## Purpose
Safely remove a subproject. This will:
1. Archive the subproject folder (not delete)
2. Update root files to remove references
3. Log the removal
## Execution Instructions
### Step 1: Parse Query
Extract subproject name from query.
If empty, list available subprojects and ask which to remove.
### Step 2: Verify Subproject Exists
```bash
ls .context/project/{name}/INDEX.md
```
If not found, show error: "Subproject '{name}' not found."
### Step 3: Check if Active
Read `.context/project/STATUS.md` to check if this is the active subproject.
If active, ask: "This is the active subproject. Which subproject should become active instead?"
### Step 4: Confirm Removal
Show warning:
```
## Removing Subproject: {name}/
This will:
- Archive {name}/ to archive/{name}_{date}/
- Remove from INDEX.md subproject table
- Remove from STATUS.md summary
- Remove from CODEBASE.md refs
- Add removal entry to CHANGELOG.md
Files will NOT be deleted, just archived.
Proceed? (yes/no)
```
Wait for confirmation.
### Step 5: Archive Subproject
```bash
mv .context/project/{name} .context/project/archive/{name}_{date}
```
### Step 6: Update Root Files
**INDEX.md**: Remove from subproject table
**STATUS.md**:
- Remove from subproject summary table
- If was active, update active subproject
**CODEBASE.md**: Remove from subproject refs
**CHANGELOG.md**: Add entry
```markdown
## {DATE} | Removed Subproject: {name}
**Changes**:
- Archived {name}/ to archive/{name}_{date}/
- Removed from project structure
**Context**:
- {reason if provided}
- Files preserved in archive
```
### Step 7: Confirm Removal
```
## Removed Subproject: {name}/
**Archived to**: archive/{name}_{date}/
**Active subproject**: {new_active}
Updated:
- Root INDEX.md
- Root STATUS.md
- Root CODEBASE.md
- Root CHANGELOG.md
To restore, move from archive back to project root.
```
## Query Examples
```bash
# With name
/pp-remove old-api
# With reason
/pp-remove old-api - replaced by new api design
# Interactive (will list and ask)
/pp-remove
```
## Safety Notes
- Never deletes files, only archives
- Always asks for confirmation
- Logs removal in CHANGELOG
- Can be restored by moving from archive

123
commands/pp-resume.md Normal file
View File

@@ -0,0 +1,123 @@
# Resume Project Session
Start a new chat session with full project context loaded.
## Arguments
$ARGUMENTS
## Purpose
This is the FIRST command to run when starting a new chat session. It:
1. Loads all project context into memory
2. Understands current state
3. Prepares to continue work
4. Optionally focuses on specific direction from query
## Execution Instructions
### Step 1: Verify Project Exists
```bash
ls .context/project/INDEX.md
```
If not found, inform user: "No project structure found. Run `/pp-init` first."
### Step 2: Read Root Context
Read these files in order:
1. `.context/project/INDEX.md` - Project overview, subprojects, active subproject, high-level status
2. `.context/project/WORKFLOW.md` - How this system works
3. `.context/project/PRINCIPLES.md` - Methodology and rules
4. `.context/project/LESSONS.md` - Past learnings
### Step 3: Read Active Subproject Context
From INDEX.md, identify active subproject, then read:
1. `.context/project/{active}/STATUS.md`
2. `.context/project/{active}/TODO.md`
3. `.context/project/{active}/CODEBASE.md`
4. `.context/project/{active}/LESSONS.md`
5. `.context/project/{active}/PRINCIPLES.md` (if exists - overrides root)
### Step 4: Read Recent Changes
Read last 3-5 entries from:
- `.context/project/{active}/CHANGELOG.md`
### Step 5: Process Optional Query
If query provided:
- Parse for direction (e.g., "continue booking flow", "fix the API bug")
- Focus context on relevant TODO items
- Identify relevant LESSONS if debugging
### Step 6: Check for Next Session Instructions (NEW)
**After loading all standard files**, check for continuation instructions:
```bash
ls .context/project/{active}/NEXT.md
```
**If NEXT.md exists:**
1. Read `.context/project/{active}/NEXT.md`
2. Extract history file path from NEXT.md
3. Read that history file for previous session context
4. Note the full chat transcript path (but DO NOT load it)
**If NEXT.md does NOT exist:**
- Skip this step, proceed to summary
### Step 7: Generate Resume Summary
Output a compact summary:
```
## Session Resumed: {PROJECT_NAME}
**Active**: {subproject}/ - {current phase}
**Status**: {brief status}
{IF NEXT.md exists:}
### Instructions from Previous Session
{content from NEXT.md "What To Do Next" section}
**Previous Session**: {date} - {brief summary from history file}
### Current Focus
{from STATUS.md current focus}
### In Progress
{tasks marked [>] from TODO.md}
### Recent Changes
{last 2-3 changelog entries, one line each}
### Key Context
{if query provided, relevant context for that direction}
---
Ready to continue. {If NEXT.md exists: "Following previous session's plan." else: "What would you like to work on?"}
```
## Query Examples
```bash
# General resume - load everything
/pp-resume
# With direction - focus on specific area
/pp-resume continue the booking flow implementation
/pp-resume fix the WhatsApp routing bug
/pp-resume review yesterday's changes
```
## Important Notes
- This command is READ-ONLY (no file modifications)
- After this, Claude has full project context
- User can immediately start working
- If query mentions something not in TODO, suggest adding it

117
commands/pp-status.md Normal file
View File

@@ -0,0 +1,117 @@
# Project Status Summary
Show compact status of the entire project.
## Arguments
$ARGUMENTS
## Purpose
Quick overview of project state without loading full context. Shows:
- Active subproject and its focus
- All subprojects status
- In-progress tasks
- Recent changes
- Any blockers
## Execution Instructions
### Step 1: Read Status Files
Read these files:
- `.context/project/INDEX.md` (get active subproject + project summary)
- `.context/project/{active}/STATUS.md`
- `.context/project/{active}/TODO.md`
- `.context/project/{active}/CHANGELOG.md` (last 2-3 entries)
### Step 2: Parse Optional Query
If query provided, focus on:
- Specific subproject: `/pp-status maya`
- Specific aspect: `/pp-status tasks` or `/pp-status blockers`
### Step 3: Generate Compact Summary
Output format:
```
## Project Status: {PROJECT_NAME}
### Active: {subproject}/
**Phase**: {current phase}
**Focus**: {one-line current focus}
### In Progress
{tasks marked [>], one line each with T### ID}
### Pending (Next Up)
{next 3-5 pending tasks}
### Subprojects
| Name | Status | Phase |
|------|--------|-------|
{table from root STATUS.md}
### Blockers
{any blocked items from STATUS.md, or "None"}
### Recent Activity
{last 2-3 changelog entries, date + one-line summary}
---
Last updated: {date from STATUS.md}
```
### Step 4: Subproject-Specific Status
If query specifies a subproject:
```
## Subproject Status: {name}/
**Phase**: {phase}
**Status**: {status}
### What's Working
{bullet list}
### What's Blocked
{bullet list or "Nothing blocked"}
### Current Focus
{numbered list}
### Tasks
**In Progress**: {count}
**Pending**: {count}
**Completed**: {count}
### Next Actions
{from STATUS.md}
```
## Query Examples
```bash
# Full project status
/pp-status
# Specific subproject
/pp-status maya
# Focus on tasks only
/pp-status tasks
# Focus on blockers
/pp-status blockers
```
## Output Notes
- Keep it COMPACT - fits in one screen
- Use tables for multiple items
- One line per item max
- Show counts, not full lists
- Highlight blockers prominently
- This is READ-ONLY (no modifications)

246
commands/pp-triage.md Normal file
View File

@@ -0,0 +1,246 @@
# Triage Issue or Feature Request
Root cause investigation and solution design for issues, bugs, or feature requests.
## Arguments
$ARGUMENTS
Description of the issue or feature. Can include error messages, URLs, or attach screenshots.
## Purpose
Deep investigation to find ROOT CAUSES, not just symptoms. Uses triage-agent for systematic analysis.
**Philosophy:** Don't just treat the rash, find the root cause (diet, stress, etc.) and fix both.
## Execution Instructions
### Step 1: Collect Issue Information
From user query, gather:
- **Issue description** (what's happening)
- **Error messages** (if any)
- **Steps to reproduce** (if provided)
- **Expected vs actual behavior**
- **Screenshots/links** (if attached)
- **Affected area** (frontend, backend, API, etc.)
If critical info missing, ask clarifying questions:
- "What error message do you see?"
- "When does this happen?"
- "Which part of the system is affected?"
### Step 2: Read PP Context First
**IMPORTANT**: Before launching agent, gather context from PP files:
Read these files:
1. `.context/project/INDEX.md` - Identify active subproject
2. `.context/project/{active}/CODEBASE.md` - Understand file structure
3. `.context/project/{active}/STATUS.md` - Current state, known issues
4. `.context/project/{active}/CHANGELOG.md` (last 5-10 entries) - Recent changes
5. `.context/project/{active}/LESSONS.md` - Past solutions
6. `.context/project/PRINCIPLES.md` - Project principles
This context is passed to the agent so it doesn't re-explore everything.
### Step 3: Launch Triage Agent
Spawn the triage-agent with:
- Issue description
- PP context (from Step 2)
- Specific focus area (if mentioned)
```
Use Task tool with subagent_type: "triage-agent"
Prompt: Investigate this issue using PP context:
Issue: {user's issue description}
PP Context:
- Active subproject: {from INDEX.md}
- Codebase structure: {from CODEBASE.md}
- Current status: {from STATUS.md}
- Recent changes: {from CHANGELOG.md}
- Past lessons: {from LESSONS.md}
- Principles: {from PRINCIPLES.md}
Find ROOT CAUSE and provide solution or debugging plan.
```
### Step 4: Agent Investigation
The triage-agent will:
1. Start with PP context (not from scratch)
2. Investigate code systematically
3. Find root cause (causation, not just correlation)
4. Determine if cause is clear or needs debugging
5. Provide solution OR debugging technique
6. Format findings as structured report
### Step 5: Present Report
Agent returns report in this format:
```markdown
## Triage Report: {Issue Title}
**Date**: {YYYY-MM-DD HH:MM}
**Subproject**: {subproject name}
**Severity**: {Critical / High / Medium / Low}
---
### Issue Summary
{Brief description of reported issue}
---
### Root Cause Analysis
**Symptom**: {What appears to be happening}
**Investigation Path**:
1. {Step 1 of investigation}
2. {Step 2 of investigation}
3. {Step 3 of investigation}
**Root Cause**: {The actual underlying cause}
**Why This Matters**: {Explanation of causation, not just correlation}
---
### Solution
{IF ROOT CAUSE IS CLEAR}:
**Recommended Fix**:
1. {Step 1}
2. {Step 2}
3. {Step 3}
**Files to Modify**:
- `path/to/file.ext` - {what to change}
- `another/file.js` - {what to change}
**Implementation Notes**:
- {Important consideration 1}
- {Important consideration 2}
{IF ROOT CAUSE IS UNCLEAR}:
**Debugging Strategy**:
1. **Add logging**:
- In `file.ext` line X: log variable Y
- In `file2.js` line Z: log state before/after
2. **Test hypothesis**:
- {Hypothesis 1}: Test by {method}
- {Hypothesis 2}: Test by {method}
3. **Narrow down**:
- {Approach to isolate the issue}
**Next Steps**:
1. {Action item 1}
2. {Action item 2}
3. {Re-run /pp-triage after gathering data}
---
### Related Context
**Recent Changes That May Be Related**:
- {CHANGELOG entry if relevant}
**Past Similar Issues**:
- {LESSONS.md entry if relevant}
**Affected Components**:
- {Component 1}
- {Component 2}
---
### Recommended Documentation Updates
**Add to LESSONS.md**:
```
## {Date} | {Issue Title}
**Problem**: {Brief problem}
**Root Cause**: {Cause}
**Solution**: {Solution}
**Tag**: [BUG] or [FEATURE] or [CONFIG]
```
**Update STATUS.md**:
- If blocking: Add to "Blocked" section
- If in progress: Add to "Current Focus"
---
### Confidence Level
**Root Cause Certainty**: {High / Medium / Low}
**Solution Confidence**: {High / Medium / Low}
{If low confidence, explain why and what additional info is needed}
```
### Step 6: Offer Follow-Up Actions
After presenting report, offer:
```
## Next Steps
Would you like me to:
1. Implement the recommended fix?
2. Add debugging logs as suggested?
3. Update LESSONS.md with this finding?
4. Create a TODO task for this fix?
5. Something else?
```
## Query Examples
```bash
# Bug report
/pp-triage Getting 500 errors on /api/users endpoint when user has no profile
# Feature request
/pp-triage Need to add email notifications when order status changes
# Performance issue
/pp-triage Dashboard loads slowly with more than 100 items
# With error message
/pp-triage TypeError: Cannot read property 'name' of undefined in UserProfile component
# With screenshot
/pp-triage [attach screenshot] Login button not working on mobile
```
## Notes
- Triage agent has access to all PP files for context
- Agent focuses on ROOT CAUSE, not symptoms
- If multiple possible causes, agent ranks by likelihood
- Report is designed to be saved in docs/ or archive/ for reference
- Always offer to update LESSONS.md with findings
- Principle: Fix the cause (diet) not just the symptom (rash)
## Agent Behavior
The triage-agent is trained to:
- Read PP context FIRST (don't re-explore)
- Think systematically (hypothesis → test → conclude)
- Find causation, not correlation
- Provide actionable solutions
- Suggest debugging when uncertain
- Be honest about confidence level
- Format output for easy scanning and future reference

116
commands/pp-update.md Normal file
View File

@@ -0,0 +1,116 @@
# Update Project Documentation
Update project files after making changes.
## Arguments
$ARGUMENTS
## Purpose
Run after making code changes to keep project documentation in sync. Updates:
- TODO.md (mark tasks done/in-progress)
- CHANGELOG.md (log changes)
- STATUS.md (if state changed)
- CODEBASE.md (if files added/modified)
- LESSONS.md (if debugging insights gained)
## Execution Instructions
### Step 1: Identify Active Subproject
Read `.context/project/INDEX.md` to get active subproject.
### Step 2: Parse Query
Query should describe what was done:
- "completed T010, T011" → Mark tasks done
- "added webhook/llm_service.py" → Update CODEBASE
- "fixed the routing bug" → Update CHANGELOG, possibly LESSONS
- "changed booking flow approach" → Update CHANGELOG with context
If no query, ask: "What changes did you make? (tasks completed, files added, bugs fixed)"
### Step 3: Determine What to Update
Based on query, identify which files need updates:
| Query Pattern | Files to Update |
|---------------|-----------------|
| "completed T###" | TODO.md, CHANGELOG.md |
| "added/created file" | CODEBASE.md, CHANGELOG.md |
| "fixed bug" | CHANGELOG.md, possibly LESSONS.md |
| "changed approach" | CHANGELOG.md, possibly STATUS.md |
| "working on T###" | TODO.md (mark in-progress) |
### Step 4: Collect Additional Info
Ask for any missing info:
- For CHANGELOG: "Brief description of what changed?"
- For CHANGELOG: "Any usage examples to include?"
- For LESSONS: "What was the root cause and solution?"
### Step 5: Make Updates
Update files in this order:
1. TODO.md - Mark tasks
2. CODEBASE.md - Add files
3. LESSONS.md - Add learnings
4. CHANGELOG.md - Log everything
5. STATUS.md - Update state if needed
### Step 6: Confirm Updates
Show summary:
```
## Updated Project Docs
**TODO.md**: Marked T010, T011 as completed
**CODEBASE.md**: Added webhook/llm_service.py
**CHANGELOG.md**: Added entry for LLM service implementation
Ready to commit? Run: git add . && git commit
```
### Step 7: Trigger Cleanup Check
After confirming updates, automatically check for cleanup:
1. Scan for temporary/draft files (see `/pp-clean` for patterns)
2. If files found, show preview:
```
## Cleanup Check
Found files to clean:
- DELETE: scratch_test.md, debug_output.md
- ARCHIVE: draft_notes.md
Run cleanup? (yes/no/skip)
```
3. If user confirms, execute cleanup per `/pp-clean` logic
4. If user skips, remind: "Run `/pp-clean` later to tidy up"
This keeps project clean after each update cycle.
## Query Examples
```bash
# After completing tasks
/pp-update completed T010 and T011, added llm_service.py
# After fixing a bug
/pp-update fixed the referral data extraction bug
# After changing approach
/pp-update changed booking flow to conversational style
# General update (will ask questions)
/pp-update
```
## Update Both Levels
- If change affects only subproject → update subproject files
- If change affects multiple subprojects → update root files too
- CHANGELOG goes in subproject unless it's cross-project

75
commands/pp-version.md Normal file
View File

@@ -0,0 +1,75 @@
# Project Progress Plugin Version
Show the current version of the unclecode-cc-toolkit plugin.
## Arguments
None
## Purpose
Display plugin version information to verify installation and updates.
## Execution Instructions
### Step 1: Read Plugin Manifest
Read the plugin manifest file:
```bash
cat ~/.claude/plugins/marketplaces/unclecode-tools/plugins/unclecode-cc-toolkit/.claude-plugin/plugin.json
```
### Step 2: Extract Version
Parse JSON and extract the `version` field.
### Step 3: Display Version Info
Output format:
```
## unclecode-cc-toolkit Plugin
**Version**: {version}
**Name**: unclecode-cc-toolkit
**Description**: {description from manifest}
**Repository**: https://github.com/unclecode/claude-code-tools
**Author**: unclecode
---
To update to the latest version:
1. /plugin uninstall unclecode-cc-toolkit
2. /plugin install unclecode-cc-toolkit@unclecode/claude-code-tools
3. Restart Claude Code
```
## Example
```bash
/pp-version
```
Output:
```
## unclecode-cc-toolkit Plugin
**Version**: 1.1.0
**Name**: unclecode-cc-toolkit
**Description**: Comprehensive Claude Code toolkit...
**Repository**: https://github.com/unclecode/claude-code-tools
**Author**: unclecode
---
To update to the latest version:
1. /plugin uninstall unclecode-cc-toolkit
2. /plugin install unclecode-cc-toolkit@unclecode/claude-code-tools
3. Restart Claude Code
```
## Notes
- If plugin.json not found, inform user plugin may not be installed correctly
- Show installation instructions if needed