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
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
|
||||
Reference in New Issue
Block a user