SuperCharge Claude Code v1.0.0 - Complete Customization Package
Features: - 30+ Custom Skills (cognitive, development, UI/UX, autonomous agents) - RalphLoop autonomous agent integration - Multi-AI consultation (Qwen) - Agent management system with sync capabilities - Custom hooks for session management - MCP servers integration - Plugin marketplace setup - Comprehensive installation script Components: - Skills: always-use-superpowers, ralph, brainstorming, ui-ux-pro-max, etc. - Agents: 100+ agents across engineering, marketing, product, etc. - Hooks: session-start-superpowers, qwen-consult, ralph-auto-trigger - Commands: /brainstorm, /write-plan, /execute-plan - MCP Servers: zai-mcp-server, web-search-prime, web-reader, zread - Binaries: ralphloop wrapper Installation: ./supercharge.sh
This commit is contained in:
uroma
52
skills/planning-with-files/docs/codex.md
Normal file
52
skills/planning-with-files/docs/codex.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# Codex IDE Support
|
||||
|
||||
## Overview
|
||||
|
||||
planning-with-files works with Codex as a personal skill in `~/.codex/skills/`.
|
||||
|
||||
## Installation
|
||||
|
||||
See [.codex/INSTALL.md](../.codex/INSTALL.md) for detailed installation instructions.
|
||||
|
||||
### Quick Install
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.codex/skills
|
||||
cd ~/.codex/skills
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
```
|
||||
|
||||
## Usage with Superpowers
|
||||
|
||||
If you have [obra/superpowers](https://github.com/obra/superpowers) installed:
|
||||
|
||||
```bash
|
||||
~/.codex/superpowers/.codex/superpowers-codex use-skill planning-with-files
|
||||
```
|
||||
|
||||
## Usage without Superpowers
|
||||
|
||||
Add to your `~/.codex/AGENTS.md`:
|
||||
|
||||
```markdown
|
||||
## Planning with Files
|
||||
|
||||
<IMPORTANT>
|
||||
For complex tasks (3+ steps, research, projects):
|
||||
1. Read skill: `cat ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md`
|
||||
2. Create task_plan.md, findings.md, progress.md in your project directory
|
||||
3. Follow 3-file pattern throughout the task
|
||||
</IMPORTANT>
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
ls -la ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md
|
||||
```
|
||||
|
||||
## Learn More
|
||||
|
||||
- [Installation Guide](installation.md)
|
||||
- [Quick Start](quickstart.md)
|
||||
- [Workflow Diagram](workflow.md)
|
||||
144
skills/planning-with-files/docs/cursor.md
Normal file
144
skills/planning-with-files/docs/cursor.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Cursor IDE Setup
|
||||
|
||||
How to use planning-with-files with Cursor IDE.
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1: Copy rules directory
|
||||
|
||||
```bash
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
cp -r planning-with-files/.cursor .cursor
|
||||
```
|
||||
|
||||
### Option 2: Manual setup
|
||||
|
||||
Create `.cursor/rules/planning-with-files.mdc` in your project with the content from this repo.
|
||||
|
||||
---
|
||||
|
||||
## Important Limitations
|
||||
|
||||
> **Note:** Hooks (PreToolUse, PostToolUse, Stop, SessionStart) are **Claude Code specific** and will NOT work in Cursor.
|
||||
|
||||
### What works in Cursor:
|
||||
|
||||
- Core 3-file planning pattern
|
||||
- Templates (task_plan.md, findings.md, progress.md)
|
||||
- All planning rules and guidelines
|
||||
- The 2-Action Rule
|
||||
- The 3-Strike Error Protocol
|
||||
- Read vs Write Decision Matrix
|
||||
|
||||
### What doesn't work in Cursor:
|
||||
|
||||
- SessionStart hook (no startup notification)
|
||||
- PreToolUse hook (no automatic plan re-reading)
|
||||
- PostToolUse hook (no automatic reminders)
|
||||
- Stop hook (no automatic completion verification)
|
||||
|
||||
---
|
||||
|
||||
## Manual Workflow for Cursor
|
||||
|
||||
Since hooks don't work in Cursor, you'll need to follow the pattern manually:
|
||||
|
||||
### 1. Create planning files first
|
||||
|
||||
Before any complex task:
|
||||
```
|
||||
Create task_plan.md, findings.md, and progress.md using the planning-with-files templates.
|
||||
```
|
||||
|
||||
### 2. Re-read plan before decisions
|
||||
|
||||
Periodically ask:
|
||||
```
|
||||
Please read task_plan.md to refresh the goals before continuing.
|
||||
```
|
||||
|
||||
### 3. Update files after phases
|
||||
|
||||
After completing work:
|
||||
```
|
||||
Update task_plan.md to mark this phase complete.
|
||||
Update progress.md with what was done.
|
||||
```
|
||||
|
||||
### 4. Verify completion manually
|
||||
|
||||
Before finishing:
|
||||
```
|
||||
Check task_plan.md - are all phases marked complete?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cursor Rules File
|
||||
|
||||
The `.cursor/rules/planning-with-files.mdc` file contains all the planning guidelines formatted for Cursor's rules system.
|
||||
|
||||
### File location
|
||||
|
||||
```
|
||||
your-project/
|
||||
├── .cursor/
|
||||
│ └── rules/
|
||||
│ └── planning-with-files.mdc
|
||||
├── task_plan.md
|
||||
├── findings.md
|
||||
├── progress.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Activating rules
|
||||
|
||||
Cursor automatically loads rules from `.cursor/rules/` when you open a project.
|
||||
|
||||
---
|
||||
|
||||
## Templates
|
||||
|
||||
The templates in `skills/planning-with-files/templates/` work in Cursor:
|
||||
|
||||
- `task_plan.md` - Phase tracking template
|
||||
- `findings.md` - Research storage template
|
||||
- `progress.md` - Session logging template
|
||||
|
||||
Copy them to your project root when starting a new task.
|
||||
|
||||
---
|
||||
|
||||
## Tips for Cursor Users
|
||||
|
||||
1. **Pin the planning files:** Keep task_plan.md open in a split view for easy reference.
|
||||
|
||||
2. **Add to .cursorrules:** You can also add planning guidelines to your project's `.cursorrules` file.
|
||||
|
||||
3. **Use explicit prompts:** Since there's no auto-detection, be explicit:
|
||||
```
|
||||
This is a complex task. Let's use the planning-with-files pattern.
|
||||
Start by creating task_plan.md with the goal and phases.
|
||||
```
|
||||
|
||||
4. **Check status regularly:** Without the Stop hook, manually verify completion before finishing.
|
||||
|
||||
---
|
||||
|
||||
## Migrating from Cursor to Claude Code
|
||||
|
||||
If you want full hook support, consider using Claude Code CLI:
|
||||
|
||||
1. Install Claude Code
|
||||
2. Run `/plugin install planning-with-files@planning-with-files`
|
||||
3. All hooks will work automatically
|
||||
|
||||
Your existing planning files (task_plan.md, etc.) are compatible with both.
|
||||
|
||||
---
|
||||
|
||||
## Need Help?
|
||||
|
||||
Open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues).
|
||||
168
skills/planning-with-files/docs/installation.md
Normal file
168
skills/planning-with-files/docs/installation.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# Installation Guide
|
||||
|
||||
Complete installation instructions for planning-with-files.
|
||||
|
||||
## Quick Install (Recommended)
|
||||
|
||||
```bash
|
||||
/plugin marketplace add OthmanAdi/planning-with-files
|
||||
/plugin install planning-with-files@planning-with-files
|
||||
```
|
||||
|
||||
That's it! The skill is now active.
|
||||
|
||||
---
|
||||
|
||||
## Installation Methods
|
||||
|
||||
### 1. Claude Code Plugin (Recommended)
|
||||
|
||||
Install directly using the Claude Code CLI:
|
||||
|
||||
```bash
|
||||
/plugin marketplace add OthmanAdi/planning-with-files
|
||||
/plugin install planning-with-files@planning-with-files
|
||||
```
|
||||
|
||||
**Advantages:**
|
||||
- Automatic updates
|
||||
- Proper hook integration
|
||||
- Full feature support
|
||||
|
||||
---
|
||||
|
||||
### 2. Manual Installation
|
||||
|
||||
Clone or copy this repository into your project's `.claude/plugins/` directory:
|
||||
|
||||
#### Option A: Clone into plugins directory
|
||||
|
||||
```bash
|
||||
mkdir -p .claude/plugins
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git .claude/plugins/planning-with-files
|
||||
```
|
||||
|
||||
#### Option B: Add as git submodule
|
||||
|
||||
```bash
|
||||
git submodule add https://github.com/OthmanAdi/planning-with-files.git .claude/plugins/planning-with-files
|
||||
```
|
||||
|
||||
#### Option C: Use --plugin-dir flag
|
||||
|
||||
```bash
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
claude --plugin-dir ./planning-with-files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Legacy Installation (Skills Only)
|
||||
|
||||
If you only want the skill without the full plugin structure:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
cp -r planning-with-files/skills/* ~/.claude/skills/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. One-Line Installer (Skills Only)
|
||||
|
||||
Extract just the skill directly into your current directory:
|
||||
|
||||
```bash
|
||||
curl -L https://github.com/OthmanAdi/planning-with-files/archive/master.tar.gz | tar -xzv --strip-components=2 "planning-with-files-master/skills/planning-with-files"
|
||||
```
|
||||
|
||||
Then move `planning-with-files/` to `~/.claude/skills/`.
|
||||
|
||||
---
|
||||
|
||||
## Verifying Installation
|
||||
|
||||
After installation, verify the skill is loaded:
|
||||
|
||||
1. Start a new Claude Code session
|
||||
2. You should see: `[planning-with-files] Ready. Auto-activates for complex tasks, or invoke manually with /planning-with-files`
|
||||
3. Or type `/planning-with-files` to manually invoke
|
||||
|
||||
---
|
||||
|
||||
## Updating
|
||||
|
||||
### Plugin Installation
|
||||
|
||||
```bash
|
||||
/plugin update planning-with-files@planning-with-files
|
||||
```
|
||||
|
||||
### Manual Installation
|
||||
|
||||
```bash
|
||||
cd .claude/plugins/planning-with-files
|
||||
git pull origin master
|
||||
```
|
||||
|
||||
### Skills Only
|
||||
|
||||
```bash
|
||||
cd ~/.claude/skills/planning-with-files
|
||||
git pull origin master
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Uninstalling
|
||||
|
||||
### Plugin
|
||||
|
||||
```bash
|
||||
/plugin uninstall planning-with-files@planning-with-files
|
||||
```
|
||||
|
||||
### Manual
|
||||
|
||||
```bash
|
||||
rm -rf .claude/plugins/planning-with-files
|
||||
```
|
||||
|
||||
### Skills Only
|
||||
|
||||
```bash
|
||||
rm -rf ~/.claude/skills/planning-with-files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Claude Code:** v2.1.0 or later (for full hook support)
|
||||
- **Older versions:** Core functionality works, but hooks may not fire
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Notes
|
||||
|
||||
### Windows
|
||||
|
||||
See [docs/windows.md](windows.md) for Windows-specific installation notes.
|
||||
|
||||
### Cursor
|
||||
|
||||
See [docs/cursor.md](cursor.md) for Cursor IDE installation.
|
||||
|
||||
### Codex
|
||||
|
||||
See [docs/codex.md](codex.md) for Codex IDE installation.
|
||||
|
||||
### OpenCode
|
||||
|
||||
See [docs/opencode.md](opencode.md) for OpenCode IDE installation.
|
||||
|
||||
---
|
||||
|
||||
## Need Help?
|
||||
|
||||
If installation fails, check [docs/troubleshooting.md](troubleshooting.md) or open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues).
|
||||
233
skills/planning-with-files/docs/kilocode.md
Normal file
233
skills/planning-with-files/docs/kilocode.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# Kilo Code Support
|
||||
|
||||
Planning with Files is fully supported on Kilo Code through native integration.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Open your project in Kilo Code
|
||||
2. Rules load automatically from global (`~/.kilocode/rules/`) or project (`.kilocode/rules/`) directories
|
||||
3. Start a complex task — Kilo Code will automatically create planning files
|
||||
|
||||
## Installation
|
||||
|
||||
### Quick Install (Project-Level)
|
||||
|
||||
Clone or copy the skill to your project's `.kilocode/skills/` directory:
|
||||
|
||||
**Unix/Linux/macOS:**
|
||||
```bash
|
||||
# Option A: Clone the repository
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
|
||||
# Copy the skill to Kilo Code's skills directory
|
||||
mkdir -p .kilocode/skills
|
||||
cp -r planning-with-files/skills/planning-with-files .kilocode/skills/planning-with-files
|
||||
|
||||
# Copy the rules file (optional, but recommended)
|
||||
mkdir -p .kilocode/rules
|
||||
cp planning-with-files/.kilocode/rules/planning-with-files.md .kilocode/rules/planning-with-files.md
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
# Option A: Clone the repository
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
|
||||
# Copy the skill to Kilo Code's skills directory
|
||||
New-Item -ItemType Directory -Force -Path .kilocode\skills
|
||||
Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files .kilocode\skills\planning-with-files
|
||||
|
||||
# Copy the rules file (optional, but recommended)
|
||||
New-Item -ItemType Directory -Force -Path .kilocode\rules
|
||||
Copy-Item -Force planning-with-files\.kilocode\rules\planning-with-files.md .kilocode\rules\planning-with-files.md
|
||||
|
||||
# Copy PowerShell scripts (optional, but recommended)
|
||||
Copy-Item -Force planning-with-files\scripts\init-session.ps1 .kilocode\skills\planning-with-files\scripts\init-session.ps1
|
||||
Copy-Item -Force planning-with-files\scripts\check-complete.ps1 .kilocode\skills\planning-with-files\scripts\check-complete.ps1
|
||||
```
|
||||
|
||||
### Manual Installation (Project-Level)
|
||||
|
||||
Copy the skill directory to your project:
|
||||
|
||||
**Unix/Linux/macOS:**
|
||||
```bash
|
||||
# From the cloned repository
|
||||
mkdir -p .kilocode/skills
|
||||
cp -r planning-with-files/skills/planning-with-files .kilocode/skills/planning-with-files
|
||||
|
||||
# Copy the rules file (optional, but recommended)
|
||||
mkdir -p .kilocode/rules
|
||||
cp planning-with-files/.kilocode/rules/planning-with-files.md .kilocode/rules/planning-with-files.md
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
# From the cloned repository
|
||||
New-Item -ItemType Directory -Force -Path .kilocode\skills
|
||||
Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files .kilocode\skills\planning-with-files
|
||||
|
||||
# Copy the rules file (optional, but recommended)
|
||||
New-Item -ItemType Directory -Force -Path .kilocode\rules
|
||||
Copy-Item -Force planning-with-files\.kilocode\rules\planning-with-files.md .kilocode\rules\planning-with-files.md
|
||||
|
||||
# Copy PowerShell scripts (optional, but recommended)
|
||||
Copy-Item -Force planning-with-files\scripts\init-session.ps1 .kilocode\skills\planning-with-files\scripts\init-session.ps1
|
||||
Copy-Item -Force planning-with-files\scripts\check-complete.ps1 .kilocode\skills\planning-with-files\scripts\check-complete.ps1
|
||||
```
|
||||
|
||||
### Global Installation (User-Level)
|
||||
|
||||
To make the skill available across all projects:
|
||||
|
||||
**Unix/Linux/macOS:**
|
||||
```bash
|
||||
# Copy to global skills directory
|
||||
mkdir -p ~/.kilocode/skills
|
||||
cp -r planning-with-files/skills/planning-with-files ~/.kilocode/skills/planning-with-files
|
||||
|
||||
# Copy the rules file (optional, but recommended)
|
||||
mkdir -p ~/.kilocode/rules
|
||||
cp planning-with-files/.kilocode/rules/planning-with-files.md ~/.kilocode/rules/planning-with-files.md
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
# Copy to global skills directory (replace YourUsername with your actual username)
|
||||
New-Item -ItemType Directory -Force -Path C:\Users\YourUsername\.kilocode\skills
|
||||
Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files C:\Users\YourUsername\.kilocode\skills\planning-with-files
|
||||
|
||||
# Copy the rules file (optional, but recommended)
|
||||
New-Item -ItemType Directory -Force -Path C:\Users\YourUsername\.kilocode\rules
|
||||
Copy-Item -Force planning-with-files\.kilocode\rules\planning-with-files.md C:\Users\YourUsername\.kilocode\rules\planning-with-files.md
|
||||
|
||||
# Copy PowerShell scripts (optional, but recommended)
|
||||
Copy-Item -Force planning-with-files\scripts\init-session.ps1 C:\Users\YourUsername\.kilocode\skills\planning-with-files\scripts\init-session.ps1
|
||||
Copy-Item -Force planning-with-files\scripts\check-complete.ps1 C:\Users\YourUsername\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
|
||||
```
|
||||
|
||||
### Verifying Installation
|
||||
|
||||
After installation, verify the skill is loaded:
|
||||
|
||||
1. **Restart Kilo Code** (if needed)
|
||||
2. Ask the agent: "Do you have access to the planning-with-files skill?"
|
||||
3. The agent should confirm the skill is loaded
|
||||
4. Rules also load automatically from `~/.kilocode/rules/planning-with-files.md` (global) or `.kilocode/rules/planning-with-files.md` (project)
|
||||
|
||||
**Testing PowerShell Scripts (Windows):**
|
||||
|
||||
After installation, you can test the PowerShell scripts:
|
||||
|
||||
```powershell
|
||||
# Test init-session.ps1
|
||||
.\.kilocode\skills\planning-with-files\scripts\init-session.ps1
|
||||
|
||||
# Test check-complete.ps1
|
||||
.\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
|
||||
```
|
||||
|
||||
The scripts should create `task_plan.md`, `findings.md`, and `progress.md` files in your project root.
|
||||
|
||||
### File Structure
|
||||
|
||||
The installation consists of the skill directory and the rules file:
|
||||
|
||||
**Skill Directory:**
|
||||
|
||||
```
|
||||
~/.kilocode/skills/planning-with-files/ (Global)
|
||||
OR
|
||||
.kilocode/skills/planning-with-files/ (Project)
|
||||
├── SKILL.md # Skill definition
|
||||
├── examples.md # Real-world examples
|
||||
├── reference.md # Advanced reference
|
||||
├── templates/ # Planning file templates
|
||||
│ ├── task_plan.md
|
||||
│ ├── findings.md
|
||||
│ └── progress.md
|
||||
└── scripts/ # Utility scripts
|
||||
├── init-session.sh # Unix/Linux/macOS
|
||||
├── check-complete.sh # Unix/Linux/macOS
|
||||
├── init-session.ps1 # Windows (PowerShell)
|
||||
└── check-complete.ps1 # Windows (PowerShell)
|
||||
```
|
||||
|
||||
**Rules File:**
|
||||
|
||||
```
|
||||
~/.kilocode/rules/planning-with-files.md (Global)
|
||||
OR
|
||||
.kilocode/rules/planning-with-files.md (Project)
|
||||
```
|
||||
|
||||
**Important**: The `name` field in `SKILL.md` must match the directory name (`planning-with-files`).
|
||||
|
||||
## File Locations
|
||||
|
||||
| Type | Global Location | Project Location |
|
||||
|------|-----------------|------------------|
|
||||
| **Rules** | `~/.kilocode/rules/planning-with-files.md` | `.kilocode/rules/planning-with-files.md` |
|
||||
| **Skill** | `~/.kilocode/skills/planning-with-files/SKILL.md` | `.kilocode/skills/planning-with-files/SKILL.md` |
|
||||
| **Templates** | `~/.kilocode/skills/planning-with-files/templates/` | `.kilocode/skills/planning-with-files/templates/` |
|
||||
| **Scripts (Unix/Linux/macOS)** | `~/.kilocode/skills/planning-with-files/scripts/*.sh` | `.kilocode/skills/planning-with-files/scripts/*.sh` |
|
||||
| **Scripts (Windows PowerShell)** | `~/.kilocode/skills/planning-with-files/scripts/*.ps1` | `.kilocode/skills/planning-with-files/scripts/*.ps1` |
|
||||
| **Your Files** | `task_plan.md`, `findings.md`, `progress.md` in project root |
|
||||
|
||||
## Quick Commands
|
||||
|
||||
**For Global Installation:**
|
||||
|
||||
**Unix/Linux/macOS:**
|
||||
```bash
|
||||
# Initialize planning files
|
||||
~/.kilocode/skills/planning-with-files/scripts/init-session.sh
|
||||
|
||||
# Verify task completion
|
||||
~/.kilocode/skills/planning-with-files/scripts/check-complete.sh
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
# Initialize planning files
|
||||
$env:USERPROFILE\.kilocode\skills\planning-with-files\scripts\init-session.ps1
|
||||
|
||||
# Verify task completion
|
||||
$env:USERPROFILE\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
|
||||
```
|
||||
|
||||
**For Project Installation:**
|
||||
|
||||
**Unix/Linux/macOS:**
|
||||
```bash
|
||||
# Initialize planning files
|
||||
./.kilocode/skills/planning-with-files/scripts/init-session.sh
|
||||
|
||||
# Verify task completion
|
||||
./.kilocode/skills/planning-with-files/scripts/check-complete.sh
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
# Initialize planning files
|
||||
.\.kilocode\skills\planning-with-files\scripts\init-session.ps1
|
||||
|
||||
# Verify task completion
|
||||
.\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
|
||||
```
|
||||
|
||||
## Migrating from Cursor/Windsurf
|
||||
|
||||
Planning files are fully compatible. Simply copy your `task_plan.md`, `findings.md`, and `progress.md` files to your new project.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
**For Global Installation:**
|
||||
- [Examples](~/.kilocode/skills/planning-with-files/examples.md) - Real-world examples
|
||||
- [Reference](~/.kilocode/skills/planning-with-files/reference.md) - Advanced reference documentation
|
||||
- [PowerShell Scripts](~/.kilocode/skills/planning-with-files/scripts/) - Utility scripts for Windows
|
||||
|
||||
**For Project Installation:**
|
||||
- [Examples](.kilocode/skills/planning-with-files/examples.md) - Real-world examples
|
||||
- [Reference](.kilocode/skills/planning-with-files/reference.md) - Advanced reference documentation
|
||||
- [PowerShell Scripts](.kilocode/skills/planning-with-files/scripts/) - Utility scripts for Windows
|
||||
70
skills/planning-with-files/docs/opencode.md
Normal file
70
skills/planning-with-files/docs/opencode.md
Normal file
@@ -0,0 +1,70 @@
|
||||
# OpenCode IDE Support
|
||||
|
||||
## Overview
|
||||
|
||||
planning-with-files works with OpenCode as a personal or project skill.
|
||||
|
||||
## Installation
|
||||
|
||||
See [.opencode/INSTALL.md](../.opencode/INSTALL.md) for detailed installation instructions.
|
||||
|
||||
### Quick Install (Global)
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/opencode/skills
|
||||
cd ~/.config/opencode/skills
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
```
|
||||
|
||||
### Quick Install (Project)
|
||||
|
||||
```bash
|
||||
mkdir -p .opencode/skills
|
||||
cd .opencode/skills
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
```
|
||||
|
||||
## Usage with Superpowers Plugin
|
||||
|
||||
If you have [obra/superpowers](https://github.com/obra/superpowers) OpenCode plugin:
|
||||
|
||||
```
|
||||
Use the use_skill tool with skill_name: "planning-with-files"
|
||||
```
|
||||
|
||||
## Usage without Superpowers
|
||||
|
||||
Manually read the skill file when starting complex tasks:
|
||||
|
||||
```bash
|
||||
cat ~/.config/opencode/skills/planning-with-files/planning-with-files/SKILL.md
|
||||
```
|
||||
|
||||
## oh-my-opencode Compatibility
|
||||
|
||||
If using oh-my-opencode, ensure planning-with-files is not in the `disabled_skills` array:
|
||||
|
||||
**~/.config/opencode/oh-my-opencode.json:**
|
||||
```json
|
||||
{
|
||||
"disabled_skills": []
|
||||
}
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
**Global:**
|
||||
```bash
|
||||
ls -la ~/.config/opencode/skills/planning-with-files/planning-with-files/SKILL.md
|
||||
```
|
||||
|
||||
**Project:**
|
||||
```bash
|
||||
ls -la .opencode/skills/planning-with-files/planning-with-files/SKILL.md
|
||||
```
|
||||
|
||||
## Learn More
|
||||
|
||||
- [Installation Guide](installation.md)
|
||||
- [Quick Start](quickstart.md)
|
||||
- [Workflow Diagram](workflow.md)
|
||||
162
skills/planning-with-files/docs/quickstart.md
Normal file
162
skills/planning-with-files/docs/quickstart.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# Quick Start Guide
|
||||
|
||||
Follow these 5 steps to use the planning-with-files pattern.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create Your Planning Files
|
||||
|
||||
**When:** Before starting any work on a complex task
|
||||
|
||||
**Action:** Create all three files using the templates:
|
||||
|
||||
```bash
|
||||
# Option 1: Use the init script (if available)
|
||||
./scripts/init-session.sh
|
||||
|
||||
# Option 2: Copy templates manually
|
||||
cp templates/task_plan.md task_plan.md
|
||||
cp templates/findings.md findings.md
|
||||
cp templates/progress.md progress.md
|
||||
```
|
||||
|
||||
**Update:** Fill in the Goal section in `task_plan.md` with your task description.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Plan Your Phases
|
||||
|
||||
**When:** Right after creating the files
|
||||
|
||||
**Action:** Break your task into 3-7 phases in `task_plan.md`
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
### Phase 1: Requirements & Discovery
|
||||
- [ ] Understand user intent
|
||||
- [ ] Research existing solutions
|
||||
- **Status:** in_progress
|
||||
|
||||
### Phase 2: Implementation
|
||||
- [ ] Write core code
|
||||
- **Status:** pending
|
||||
```
|
||||
|
||||
**Update:**
|
||||
- `task_plan.md`: Define your phases
|
||||
- `progress.md`: Note that planning is complete
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Work and Document
|
||||
|
||||
**When:** Throughout the task
|
||||
|
||||
**Action:** As you work, update files:
|
||||
|
||||
| What Happens | Which File to Update | What to Add |
|
||||
|--------------|---------------------|-------------|
|
||||
| You research something | `findings.md` | Add to "Research Findings" |
|
||||
| You view 2 browser/search results | `findings.md` | **MUST update** (2-Action Rule) |
|
||||
| You make a technical decision | `findings.md` | Add to "Technical Decisions" with rationale |
|
||||
| You complete a phase | `task_plan.md` | Change status: `in_progress` → `complete` |
|
||||
| You complete a phase | `progress.md` | Log actions taken, files modified |
|
||||
| An error occurs | `task_plan.md` | Add to "Errors Encountered" table |
|
||||
| An error occurs | `progress.md` | Add to "Error Log" with timestamp |
|
||||
|
||||
**Example workflow:**
|
||||
```
|
||||
1. Research → Update findings.md
|
||||
2. Research → Update findings.md (2nd time - MUST update now!)
|
||||
3. Make decision → Update findings.md "Technical Decisions"
|
||||
4. Implement code → Update progress.md "Actions taken"
|
||||
5. Complete phase → Update task_plan.md status to "complete"
|
||||
6. Complete phase → Update progress.md with phase summary
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Re-read Before Decisions
|
||||
|
||||
**When:** Before making major decisions (automatic with hooks in Claude Code)
|
||||
|
||||
**Action:** The PreToolUse hook automatically reads `task_plan.md` before Write/Edit/Bash operations
|
||||
|
||||
**Manual reminder (if not using hooks):** Before important choices, read `task_plan.md` to refresh your goals
|
||||
|
||||
**Why:** After many tool calls, original goals can be forgotten. Re-reading brings them back into attention.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Complete and Verify
|
||||
|
||||
**When:** When you think the task is done
|
||||
|
||||
**Action:** Verify completion:
|
||||
|
||||
1. **Check `task_plan.md`**: All phases should have `**Status:** complete`
|
||||
2. **Check `progress.md`**: All phases should be logged with actions taken
|
||||
3. **Run completion check** (if using hooks, this happens automatically):
|
||||
```bash
|
||||
./scripts/check-complete.sh
|
||||
```
|
||||
|
||||
**If not complete:** The Stop hook (or script) will prevent stopping. Continue working until all phases are done.
|
||||
|
||||
**If complete:** Deliver your work! All three planning files document your process.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: When to Update Which File
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ task_plan.md │
|
||||
│ Update when: │
|
||||
│ • Starting task (create it first!) │
|
||||
│ • Completing a phase (change status) │
|
||||
│ • Making a major decision (add to Decisions table) │
|
||||
│ • Encountering an error (add to Errors table) │
|
||||
│ • Re-reading before decisions (automatic via hook) │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ findings.md │
|
||||
│ Update when: │
|
||||
│ • Discovering something new (research, exploration) │
|
||||
│ • After 2 view/browser/search operations (2-Action!) │
|
||||
│ • Making a technical decision (with rationale) │
|
||||
│ • Finding useful resources (URLs, docs) │
|
||||
│ • Viewing images/PDFs (capture as text immediately!) │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ progress.md │
|
||||
│ Update when: │
|
||||
│ • Starting a new phase (log start time) │
|
||||
│ • Completing a phase (log actions, files modified) │
|
||||
│ • Running tests (add to Test Results table) │
|
||||
│ • Encountering errors (add to Error Log with timestamp)│
|
||||
│ • Resuming after a break (update 5-Question Check) │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
| Don't | Do Instead |
|
||||
|-------|------------|
|
||||
| Start work without creating `task_plan.md` | Always create the plan file first |
|
||||
| Forget to update `findings.md` after 2 browser operations | Set a reminder: "2 view/browser ops = update findings.md" |
|
||||
| Skip logging errors because you fixed them quickly | Log ALL errors, even ones you resolved immediately |
|
||||
| Repeat the same failed action | If something fails, log it and try a different approach |
|
||||
| Only update one file | The three files work together - update them as a set |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- See [examples/README.md](../examples/README.md) for complete walkthrough examples
|
||||
- See [workflow.md](workflow.md) for the visual workflow diagram
|
||||
- See [troubleshooting.md](troubleshooting.md) if you encounter issues
|
||||
240
skills/planning-with-files/docs/troubleshooting.md
Normal file
240
skills/planning-with-files/docs/troubleshooting.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# Troubleshooting
|
||||
|
||||
Common issues and their solutions.
|
||||
|
||||
---
|
||||
|
||||
## Templates not found in cache (after update)
|
||||
|
||||
**Issue:** After updating to a new version, `/planning-with-files` fails with "template files not found in cache" or similar errors.
|
||||
|
||||
**Why this happens:** Claude Code caches plugin files, and the cache may not refresh properly after an update.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
### Solution 1: Clean reinstall (Recommended)
|
||||
|
||||
```bash
|
||||
/plugin uninstall planning-with-files@planning-with-files
|
||||
/plugin marketplace add OthmanAdi/planning-with-files
|
||||
/plugin install planning-with-files@planning-with-files
|
||||
```
|
||||
|
||||
### Solution 2: Clear Claude Code cache
|
||||
|
||||
Restart Claude Code completely (close and reopen terminal/IDE).
|
||||
|
||||
### Solution 3: Manual cache clear
|
||||
|
||||
```bash
|
||||
# Find and remove cached plugin
|
||||
rm -rf ~/.claude/cache/plugins/planning-with-files
|
||||
```
|
||||
|
||||
Then reinstall the plugin.
|
||||
|
||||
**Note:** This was fixed in v2.1.2 by adding templates at the repo root level.
|
||||
|
||||
---
|
||||
|
||||
## Planning files created in wrong directory
|
||||
|
||||
**Issue:** When using `/planning-with-files`, the files (`task_plan.md`, `findings.md`, `progress.md`) are created in the skill installation directory instead of your project.
|
||||
|
||||
**Why this happens:** When the skill runs as a subagent, it may not inherit your terminal's current working directory.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
### Solution 1: Specify your project path when invoking
|
||||
|
||||
```
|
||||
/planning-with-files - I'm working in /path/to/my-project/, create all files there
|
||||
```
|
||||
|
||||
### Solution 2: Add context before invoking
|
||||
|
||||
```
|
||||
I'm working on the project at /path/to/my-project/
|
||||
```
|
||||
Then run `/planning-with-files`.
|
||||
|
||||
### Solution 3: Create a CLAUDE.md in your project root
|
||||
|
||||
```markdown
|
||||
# Project Context
|
||||
|
||||
All planning files (task_plan.md, findings.md, progress.md)
|
||||
should be created in this directory.
|
||||
```
|
||||
|
||||
### Solution 4: Use the skill directly without subagent
|
||||
|
||||
```
|
||||
Help me plan this task using the planning-with-files approach.
|
||||
Create task_plan.md, findings.md, and progress.md here.
|
||||
```
|
||||
|
||||
**Note:** This was fixed in v2.0.1. The skill instructions now explicitly specify that planning files should be created in your project directory, not the skill installation folder.
|
||||
|
||||
---
|
||||
|
||||
## Files not persisting between sessions
|
||||
|
||||
**Issue:** Planning files seem to disappear or aren't found when resuming work.
|
||||
|
||||
**Solution:** Make sure the files are in your project root, not in a temporary location.
|
||||
|
||||
Check with:
|
||||
```bash
|
||||
ls -la task_plan.md findings.md progress.md
|
||||
```
|
||||
|
||||
If files are missing, they may have been created in:
|
||||
- The skill installation folder (`~/.claude/skills/planning-with-files/`)
|
||||
- A temporary directory
|
||||
- A different working directory
|
||||
|
||||
---
|
||||
|
||||
## Hooks not triggering
|
||||
|
||||
**Issue:** The PreToolUse hook (which reads task_plan.md before actions) doesn't seem to run.
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Check Claude Code version:**
|
||||
```bash
|
||||
claude --version
|
||||
```
|
||||
Hooks require Claude Code v2.1.0 or later for full support.
|
||||
|
||||
2. **Verify skill installation:**
|
||||
```bash
|
||||
ls ~/.claude/skills/planning-with-files/
|
||||
```
|
||||
or
|
||||
```bash
|
||||
ls .claude/plugins/planning-with-files/
|
||||
```
|
||||
|
||||
3. **Check that task_plan.md exists:**
|
||||
The PreToolUse hook runs `cat task_plan.md`. If the file doesn't exist, the hook silently succeeds (by design).
|
||||
|
||||
4. **Check for YAML errors:**
|
||||
Run Claude Code with debug mode:
|
||||
```bash
|
||||
claude --debug
|
||||
```
|
||||
Look for skill loading errors.
|
||||
|
||||
---
|
||||
|
||||
## SessionStart hook not showing message
|
||||
|
||||
**Issue:** The "Ready" message doesn't appear when starting Claude Code.
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. SessionStart hooks require Claude Code v2.1.0+
|
||||
2. The hook only fires once per session
|
||||
3. If you've already started a session, restart Claude Code
|
||||
|
||||
---
|
||||
|
||||
## PostToolUse hook not running
|
||||
|
||||
**Issue:** The reminder message after Write/Edit doesn't appear.
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. PostToolUse hooks require Claude Code v2.1.0+
|
||||
2. The hook only fires after successful Write/Edit operations
|
||||
3. Check the matcher pattern: it's set to `"Write|Edit"` only
|
||||
|
||||
---
|
||||
|
||||
## Skill not auto-detecting complex tasks
|
||||
|
||||
**Issue:** Claude doesn't automatically use the planning pattern for complex tasks.
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Manually invoke:**
|
||||
```
|
||||
/planning-with-files
|
||||
```
|
||||
|
||||
2. **Trigger words:** The skill auto-activates based on its description. Try phrases like:
|
||||
- "complex multi-step task"
|
||||
- "research project"
|
||||
- "task requiring many steps"
|
||||
|
||||
3. **Be explicit:**
|
||||
```
|
||||
This is a complex task that will require >5 tool calls.
|
||||
Please use the planning-with-files pattern.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stop hook blocking completion
|
||||
|
||||
**Issue:** Claude won't stop because the Stop hook says phases aren't complete.
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Check task_plan.md:** All phases should have `**Status:** complete`
|
||||
|
||||
2. **Manual override:** If you need to stop anyway:
|
||||
```
|
||||
Override the completion check - I want to stop now.
|
||||
```
|
||||
|
||||
3. **Fix the status:** Update incomplete phases to `complete` if they're actually done.
|
||||
|
||||
---
|
||||
|
||||
## YAML frontmatter errors
|
||||
|
||||
**Issue:** Skill won't load due to YAML errors.
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Check indentation:** YAML requires spaces, not tabs
|
||||
2. **Check the first line:** Must be exactly `---` with no blank lines before it
|
||||
3. **Validate YAML:** Use an online YAML validator
|
||||
|
||||
Common mistakes:
|
||||
```yaml
|
||||
# WRONG - tabs
|
||||
hooks:
|
||||
PreToolUse:
|
||||
|
||||
# CORRECT - spaces
|
||||
hooks:
|
||||
PreToolUse:
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Windows-specific issues
|
||||
|
||||
See [docs/windows.md](windows.md) for Windows-specific troubleshooting.
|
||||
|
||||
---
|
||||
|
||||
## Cursor-specific issues
|
||||
|
||||
See [docs/cursor.md](cursor.md) for Cursor IDE troubleshooting.
|
||||
|
||||
---
|
||||
|
||||
## Still stuck?
|
||||
|
||||
Open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues) with:
|
||||
|
||||
- Your Claude Code version (`claude --version`)
|
||||
- Your operating system
|
||||
- The command you ran
|
||||
- What happened vs what you expected
|
||||
- Any error messages
|
||||
139
skills/planning-with-files/docs/windows.md
Normal file
139
skills/planning-with-files/docs/windows.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# Windows Setup
|
||||
|
||||
Windows-specific installation and usage notes.
|
||||
|
||||
---
|
||||
|
||||
## Installation on Windows
|
||||
|
||||
### Via winget (Recommended)
|
||||
|
||||
Claude Code supports Windows Package Manager:
|
||||
|
||||
```powershell
|
||||
winget install Anthropic.ClaudeCode
|
||||
```
|
||||
|
||||
Then install the skill:
|
||||
|
||||
```
|
||||
/plugin marketplace add OthmanAdi/planning-with-files
|
||||
/plugin install planning-with-files@planning-with-files
|
||||
```
|
||||
|
||||
### Manual Installation
|
||||
|
||||
```powershell
|
||||
# Create plugins directory
|
||||
mkdir -p $env:USERPROFILE\.claude\plugins
|
||||
|
||||
# Clone the repository
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git $env:USERPROFILE\.claude\plugins\planning-with-files
|
||||
```
|
||||
|
||||
### Skills Only
|
||||
|
||||
```powershell
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
Copy-Item -Recurse planning-with-files\skills\* $env:USERPROFILE\.claude\skills\
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Path Differences
|
||||
|
||||
| Unix/macOS | Windows |
|
||||
|------------|---------|
|
||||
| `~/.claude/skills/` | `%USERPROFILE%\.claude\skills\` |
|
||||
| `~/.claude/plugins/` | `%USERPROFILE%\.claude\plugins\` |
|
||||
| `.claude/plugins/` | `.claude\plugins\` |
|
||||
|
||||
---
|
||||
|
||||
## Shell Script Compatibility
|
||||
|
||||
The helper scripts (`init-session.sh`, `check-complete.sh`) are bash scripts.
|
||||
|
||||
### Option 1: Use Git Bash
|
||||
|
||||
If you have Git for Windows installed, run scripts in Git Bash:
|
||||
|
||||
```bash
|
||||
./scripts/init-session.sh
|
||||
```
|
||||
|
||||
### Option 2: Use WSL
|
||||
|
||||
```bash
|
||||
wsl ./scripts/init-session.sh
|
||||
```
|
||||
|
||||
### Option 3: Manual alternative
|
||||
|
||||
Instead of running scripts, manually create the files:
|
||||
|
||||
```powershell
|
||||
# Copy templates to current directory
|
||||
Copy-Item templates\task_plan.md .
|
||||
Copy-Item templates\findings.md .
|
||||
Copy-Item templates\progress.md .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hook Commands
|
||||
|
||||
The hooks use Unix-style commands. On Windows with Claude Code:
|
||||
|
||||
- Hooks run in a Unix-compatible shell environment
|
||||
- Commands like `cat`, `head`, `echo` work automatically
|
||||
- No changes needed to the skill configuration
|
||||
|
||||
---
|
||||
|
||||
## Common Windows Issues
|
||||
|
||||
### Path separators
|
||||
|
||||
If you see path errors, ensure you're using the correct separator:
|
||||
|
||||
```powershell
|
||||
# Windows
|
||||
$env:USERPROFILE\.claude\skills\
|
||||
|
||||
# Not Unix-style
|
||||
~/.claude/skills/
|
||||
```
|
||||
|
||||
### Line endings
|
||||
|
||||
If templates appear corrupted, check line endings:
|
||||
|
||||
```powershell
|
||||
# Convert to Windows line endings if needed
|
||||
(Get-Content template.md) | Set-Content -Encoding UTF8 template.md
|
||||
```
|
||||
|
||||
### Permission errors
|
||||
|
||||
Run PowerShell as Administrator if you get permission errors:
|
||||
|
||||
```powershell
|
||||
# Right-click PowerShell → Run as Administrator
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Terminal Recommendations
|
||||
|
||||
For best experience on Windows:
|
||||
|
||||
1. **Windows Terminal** - Modern terminal with good Unicode support
|
||||
2. **Git Bash** - Unix-like environment on Windows
|
||||
3. **WSL** - Full Linux environment
|
||||
|
||||
---
|
||||
|
||||
## Need Help?
|
||||
|
||||
Open an issue at [github.com/OthmanAdi/planning-with-files/issues](https://github.com/OthmanAdi/planning-with-files/issues).
|
||||
209
skills/planning-with-files/docs/workflow.md
Normal file
209
skills/planning-with-files/docs/workflow.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# Workflow Diagram
|
||||
|
||||
This diagram shows how the three files work together and how hooks interact with them.
|
||||
|
||||
---
|
||||
|
||||
## Visual Workflow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ TASK START │
|
||||
│ User requests a complex task (>5 tool calls expected) │
|
||||
└────────────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────┐
|
||||
│ STEP 1: Create task_plan.md │
|
||||
│ (NEVER skip this step!) │
|
||||
└───────────────┬───────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────┐
|
||||
│ STEP 2: Create findings.md │
|
||||
│ STEP 3: Create progress.md │
|
||||
└───────────────┬───────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────────┐
|
||||
│ WORK LOOP (Iterative) │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────┐ │
|
||||
│ │ PreToolUse Hook (Automatic) │ │
|
||||
│ │ → Reads task_plan.md before │ │
|
||||
│ │ Write/Edit/Bash operations │ │
|
||||
│ │ → Refreshes goals in attention │ │
|
||||
│ └──────────────┬───────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────────┐ │
|
||||
│ │ Perform work (tool calls) │ │
|
||||
│ │ - Research → Update findings.md │ │
|
||||
│ │ - Implement → Update progress.md │ │
|
||||
│ │ - Make decisions → Update both │ │
|
||||
│ └──────────────┬───────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────────┐ │
|
||||
│ │ PostToolUse Hook (Automatic) │ │
|
||||
│ │ → Reminds to update task_plan.md │ │
|
||||
│ │ if phase completed │ │
|
||||
│ └──────────────┬───────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────────┐ │
|
||||
│ │ After 2 view/browser operations: │ │
|
||||
│ │ → MUST update findings.md │ │
|
||||
│ │ (2-Action Rule) │ │
|
||||
│ └──────────────┬───────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────────┐ │
|
||||
│ │ After completing a phase: │ │
|
||||
│ │ → Update task_plan.md status │ │
|
||||
│ │ → Update progress.md with details │ │
|
||||
│ └──────────────┬───────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────────┐ │
|
||||
│ │ If error occurs: │ │
|
||||
│ │ → Log in task_plan.md │ │
|
||||
│ │ → Log in progress.md │ │
|
||||
│ │ → Document resolution │ │
|
||||
│ └──────────────┬───────────────────────┘ │
|
||||
│ │ │
|
||||
│ └──────────┐ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────┐ │
|
||||
│ │ More work to do? │ │
|
||||
│ └──────┬───────────────┘ │
|
||||
│ │ │
|
||||
│ YES ───┘ │
|
||||
│ │ │
|
||||
│ └──────────┐ │
|
||||
│ │ │
|
||||
└─────────────────────────┘ │
|
||||
│
|
||||
NO │
|
||||
│ │
|
||||
▼ │
|
||||
┌──────────────────────────────────────┐
|
||||
│ Stop Hook (Automatic) │
|
||||
│ → Checks if all phases complete │
|
||||
│ → Verifies task_plan.md status │
|
||||
└──────────────┬───────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────┐
|
||||
│ All phases complete? │
|
||||
└──────────────┬───────────────────────┘
|
||||
│
|
||||
┌──────────┴──────────┐
|
||||
│ │
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ TASK COMPLETE │ │ Continue work │
|
||||
│ Deliver files │ │ (back to loop) │
|
||||
└─────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Interactions
|
||||
|
||||
### Hooks
|
||||
|
||||
| Hook | When It Fires | What It Does |
|
||||
|------|---------------|--------------|
|
||||
| **SessionStart** | When Claude Code session begins | Notifies skill is ready |
|
||||
| **PreToolUse** | Before Write/Edit/Bash operations | Reads `task_plan.md` to refresh goals |
|
||||
| **PostToolUse** | After Write/Edit operations | Reminds to update phase status |
|
||||
| **Stop** | When Claude tries to stop | Verifies all phases are complete |
|
||||
|
||||
### The 2-Action Rule
|
||||
|
||||
After every 2 view/browser/search operations, you MUST update `findings.md`.
|
||||
|
||||
```
|
||||
Operation 1: WebSearch → Note results
|
||||
Operation 2: WebFetch → MUST UPDATE findings.md NOW
|
||||
Operation 3: Read file → Note findings
|
||||
Operation 4: Grep search → MUST UPDATE findings.md NOW
|
||||
```
|
||||
|
||||
### Phase Completion
|
||||
|
||||
When a phase is complete:
|
||||
|
||||
1. Update `task_plan.md`:
|
||||
- Change status: `in_progress` → `complete`
|
||||
- Mark checkboxes: `[ ]` → `[x]`
|
||||
|
||||
2. Update `progress.md`:
|
||||
- Log actions taken
|
||||
- List files created/modified
|
||||
- Note any issues encountered
|
||||
|
||||
### Error Handling
|
||||
|
||||
When an error occurs:
|
||||
|
||||
1. Log in `task_plan.md` → Errors Encountered table
|
||||
2. Log in `progress.md` → Error Log with timestamp
|
||||
3. Document the resolution
|
||||
4. Never repeat the same failed action
|
||||
|
||||
---
|
||||
|
||||
## File Relationships
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ task_plan.md │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Goal: What you're trying to achieve │ │
|
||||
│ │ Phases: 3-7 steps with status tracking │ │
|
||||
│ │ Decisions: Major choices made │ │
|
||||
│ │ Errors: Problems encountered │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ PreToolUse hook reads this │
|
||||
│ before every Write/Edit/Bash │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────┼────────────────────┐
|
||||
│ │ │
|
||||
▼ │ ▼
|
||||
┌─────────────────┐ │ ┌─────────────────┐
|
||||
│ findings.md │ │ │ progress.md │
|
||||
│ │ │ │ │
|
||||
│ Research │◄───────────┘ │ Session log │
|
||||
│ Discoveries │ │ Actions taken │
|
||||
│ Tech decisions │ │ Test results │
|
||||
│ Resources │ │ Error log │
|
||||
└─────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The 5-Question Reboot Test
|
||||
|
||||
If you can answer these questions, your context management is solid:
|
||||
|
||||
| Question | Answer Source |
|
||||
|----------|---------------|
|
||||
| Where am I? | Current phase in `task_plan.md` |
|
||||
| Where am I going? | Remaining phases in `task_plan.md` |
|
||||
| What's the goal? | Goal statement in `task_plan.md` |
|
||||
| What have I learned? | `findings.md` |
|
||||
| What have I done? | `progress.md` |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Quick Start Guide](quickstart.md) - Step-by-step tutorial
|
||||
- [Troubleshooting](troubleshooting.md) - Common issues and solutions
|
||||
Reference in New Issue
Block a user