Compare commits

...
1 Commits
Author SHA1 Message Date
OthmanAdi 72220d51b6 fix: remove ALL non-standard fields from SKILL.md - match Anthropic official format (v2.5.0)
Only 3 fields allowed:
- name
- description
- license

Removed:
- version (not supported)
- user-invocable (not supported)
- allowed-tools (not supported)
- hooks (not supported in SKILL.md)

This matches the exact format used by official Anthropic skills.
2026-01-20 12:00:02 +01:00
2 changed files with 14 additions and 125 deletions
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "2.4.1",
"version": "2.5.0",
"description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Use when starting complex tasks, multi-step projects, research tasks, or when you want structured output.",
"author": {
"name": "OthmanAdi",
+13 -124
View File
@@ -1,79 +1,23 @@
---
name: planning-with-files
version: "2.4.1"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
- WebFetch
- WebSearch
hooks:
PreToolUse:
- matcher: "Write|Edit|Bash|Read|Glob|Grep"
hooks:
- type: command
command: "cat task_plan.md 2>/dev/null | head -30 || true"
PostToolUse:
- matcher: "Write|Edit"
hooks:
- type: command
command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
Stop:
- hooks:
- type: command
command: |
if command -v pwsh &> /dev/null && [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OS" == "Windows_NT" ]]; then
pwsh -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.ps1" 2>/dev/null || powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.ps1" 2>/dev/null || bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"
else
bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"
fi
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
license: MIT
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## FIRST: Check for Previous Session (v2.2.0)
**Before starting work**, check for unsynced context from a previous session:
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
```
If catchup report shows unsynced context:
1. Run `git diff --stat` to see actual code changes
2. Read current planning files
3. Update planning files based on catchup + git diff
4. Then proceed with task
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
1. **Create `task_plan.md`** — Use templates/task_plan.md as reference
2. **Create `findings.md`** — Use templates/findings.md as reference
3. **Create `progress.md`** — Use templates/progress.md as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
## The Core Pattern
```
@@ -113,68 +57,18 @@ After completing any phase:
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
ATTEMPT 1: Diagnose & Fix
→ Read error carefully
→ Identify root cause
→ Apply targeted fix
ATTEMPT 2: Alternative Approach
→ Same error? Try different method
→ Different tool? Different library?
→ NEVER repeat exact same failing action
ATTEMPT 3: Broader Rethink
→ Question assumptions
→ Search for solutions
→ Consider updating the plan
AFTER 3 FAILURES: Escalate to User
→ Explain what you tried
→ Share the specific error
→ Ask for guidance
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## When to Use This Pattern
**Use for:**
@@ -182,7 +76,6 @@ If you can answer these, your context management is solid:
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
@@ -191,24 +84,20 @@ If you can answer these, your context management is solid:
## Templates
Copy these templates to start:
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
- templates/task_plan.md — Phase tracking
- templates/findings.md — Research storage
- templates/progress.md — Session logging
## Scripts
Helper scripts for automation:
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py` — Recover context from previous session (v2.2.0)
- scripts/init-session.sh — Initialize all planning files
- scripts/check-complete.sh — Verify all phases complete
- scripts/session-catchup.py — Recover context from previous session
## Advanced Topics
- **Manus Principles:** See [reference.md](reference.md)
- **Real Examples:** See [examples.md](examples.md)
- **Manus Principles:** See reference.md
- **Real Examples:** See examples.md
## Anti-Patterns