admin/trailofbits-skills-curated
1
0
Fork 0
mirror of https://github.com/trailofbits/skills-curated synced 2026-06-21 14:12:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1 from trailofbits/add-planning-with-files

Browse Source 
Add planning-with-files plugin
This commit is contained in:
Dan Guido
2026-02-11 18:48:38 -05:00
committed by GitHub
parent e767c0f66a 853fd4ebe0
commit 2aa43776d1
12 changed files with 708 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude-plugin/marketplace.json
+10
View File
@@ -30,6 +30,16 @@
"url": "https://github.com/trailofbits"
},
"source": "./plugins/skill-extractor"
},
{
"name": "planning-with-files",
"version": "1.0.0",
"description": "File-based planning with persistent markdown files for complex multi-step tasks",
"author": {
"name": "OthmanAdi",
"url": "https://github.com/OthmanAdi"
},
"source": "./plugins/planning-with-files"
}
]
}
README.md
+1
View File
@@ -60,6 +60,7 @@ Once merged, the skill is available to all Trail of Bits employees and anyone el
| Plugin | Description |
|--------|-------------|
| [skill-extractor](plugins/skill-extractor/) | Extract reusable skills from work sessions |
| [planning-with-files](plugins/planning-with-files/) | File-based planning with persistent markdown for complex multi-step tasks |
## License
plugins/planning-with-files/.claude-plugin/plugin.json
+9
View File
@@ -0,0 +1,9 @@
{
"name": "planning-with-files",
"version": "1.0.0",
"description": "File-based planning with persistent markdown files for complex multi-step tasks",
"author": {
"name": "OthmanAdi",
"url": "https://github.com/OthmanAdi"
}
}
plugins/planning-with-files/README.md
+44
View File
@@ -0,0 +1,44 @@
# Planning with Files
File-based planning with persistent markdown files for complex multi-step tasks.
## Installation
```
/plugin install trailofbits/skills-curated/plugins/planning-with-files
```
## Usage
### /plan
Creates three planning files in your project root:
- `task_plan.md` -- phases, progress, decisions, error log
- `findings.md` -- research discoveries and technical decisions
- `progress.md` -- session log and test results
### /status
Shows a compact summary of your current task phases and progress.
## How It Works
The core idea: your context window is volatile RAM, the filesystem is persistent disk. Writing goals, decisions, and findings to markdown files prevents context drift during long tasks.
The key pattern is **read-before-decide**: re-reading `task_plan.md` before major decisions pushes goals back into the attention window, counteracting the "lost in the middle" effect that occurs after many tool calls.
The plugin includes a Stop hook that reports phase completion status when a session ends.
## What's Included
| Component | Purpose |
|-----------|---------|
| Skill | Core planning methodology and rules |
| `/plan` command | Create planning files from templates |
| `/status` command | Show phase summary |
| Stop hook | Report completion status on session end |
## Credits
Based on [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files), which implements context engineering principles from [Manus](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus). Restructured as a curated Claude Code plugin with multi-IDE bloat removed, expensive hooks dropped, and templates cleaned up.
plugins/planning-with-files/commands/plan.md
+42
View File
@@ -0,0 +1,42 @@
---
name: plan
description: "Create planning files (task_plan.md, findings.md, progress.md) for a new task"
allowed-tools:
- Read
- Write
- Glob
---
# /plan -- Create Planning Files
Create the three planning files for a new task.
## Steps
1. Check if planning files already exist in the project root:
- `task_plan.md`
- `findings.md`
- `progress.md`
2. If any exist, ask the user before overwriting. Show which files
were found and confirm they want to start fresh.
3. Ask the user: "What is the goal of this task?" Use their response
as the Goal in `task_plan.md`.
4. Create all three files using the templates from
`{baseDir}/skills/planning-with-files/references/templates.md`.
Fill in:
- The Goal section with the user's response
- The Session date in `progress.md` with today's date
- Phase titles if the user described their task in enough detail
5. Display a summary:
```
Planning files created:
- task_plan.md (phases and progress tracking)
- findings.md (research and decisions)
- progress.md (session log)
Current phase: Phase 1 - Requirements & Discovery
```
plugins/planning-with-files/commands/status.md
+45
View File
@@ -0,0 +1,45 @@
---
name: status
description: "Show current task plan status and phase summary"
allowed-tools:
- Read
- Glob
---
# /status -- Show Task Status
Read `task_plan.md` and display a compact phase summary.
## Steps
1. Check if `task_plan.md` exists in the project root. If not,
tell the user: "No task_plan.md found. Use /plan to create one."
2. Read `task_plan.md` and extract:
- The Goal
- Each phase title and its status
3. Display a compact summary using text markers:
```
Goal: [goal statement]
[done] Phase 1: Requirements & Discovery
[done] Phase 2: Planning & Structure
[current] Phase 3: Implementation
[pending] Phase 4: Testing & Verification
[pending] Phase 5: Delivery
Progress: 2/5 phases complete
```
Status mapping:
- `complete` -> `[done]`
- `in_progress` -> `[current]`
- `pending` -> `[pending]`
- Any phase with blockers noted -> `[blocked]`
4. If `findings.md` exists, also show a count of entries:
```
Findings: 3 research items, 2 decisions, 1 issue
```
plugins/planning-with-files/hooks/hooks.json
+9
View File
@@ -0,0 +1,9 @@
{
"hooks": [
{
"event": "Stop",
"command": "sh \"${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh\"",
"timeout": 10
}
]
}
plugins/planning-with-files/scripts/check-complete.sh
+47
View File
@@ -0,0 +1,47 @@
#!/bin/bash
set -euo pipefail
# Check if all phases in task_plan.md are complete.
# Always exits 0 — uses stdout for status reporting.
# Used by Stop hook to report task completion status.
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
TOTAL="${TOTAL:-0}"
# Check for **Status:** format first
COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
# Fallback: check for [complete] inline format
if [ "${COMPLETE:-0}" -eq 0 ] && [ "${IN_PROGRESS:-0}" -eq 0 ] && [ "${PENDING:-0}" -eq 0 ]; then
COMPLETE=$(grep -c "\[complete\]" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -c "\[in_progress\]" "$PLAN_FILE" || true)
PENDING=$(grep -c "\[pending\]" "$PLAN_FILE" || true)
fi
COMPLETE="${COMPLETE:-0}"
IN_PROGRESS="${IN_PROGRESS:-0}"
PENDING="${PENDING:-0}"
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
plugins/planning-with-files/skills/planning-with-files/SKILL.md
+193
View File
@@ -0,0 +1,193 @@
---
name: planning-with-files
description: |
Implements file-based planning for complex multi-step tasks. Creates
task_plan.md, findings.md, and progress.md as persistent working
memory. Use when starting tasks requiring >5 tool calls, multi-phase
projects, research, or any work where losing track of goals and
progress would be costly.
allowed-tools:
- Read
- Write
- Edit
- Glob
- Grep
---
# Planning with Files
Use persistent markdown files as working memory on disk.
## Quick Start
1. **Create planning files** -- use `/plan` or create manually from
[templates](references/templates.md)
2. **Create `task_plan.md`** with goal, phases, and key questions
3. **Create `findings.md`** for research and decisions
4. **Create `progress.md`** for session logging
5. **Re-read the plan before decisions** -- refreshes goals in attention
6. **Update after each phase** -- mark status, log errors
## When to Use
- Multi-step tasks (3+ phases)
- Research projects requiring many searches
- Building or creating projects with multiple files
- Tasks spanning many tool calls (>10)
- Any work where losing track of goals would be costly
- Tasks that may span multiple sessions
## When NOT to Use
- Simple questions or quick lookups
- Single-file edits with obvious scope
- Tasks completable in under 5 tool calls
- Conversational exchanges without implementation
## Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
Anything important gets written to disk.
```
After many tool calls, the original goal drifts out of the attention
window. Reading `task_plan.md` brings it back. This is the single
most important pattern in file-based planning.
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase completes |
| `findings.md` | Research, discoveries, decisions | After ANY discovery |
| `progress.md` | Session log, test results | Throughout the session |
All three files go in the **project root**, not the plugin directory.
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. This is
non-negotiable. The plan is your persistent memory.
### 2. The 2-Action Rule
After every 2 search, browse, or read operations, immediately save
key findings to `findings.md`. Multimodal content (images, browser
results, PDF contents) does not persist in context -- capture it as
text before it is lost.
### 3. Read Before Decide
Before any major decision, re-read `task_plan.md`. This pushes
goals and context back into the recent attention window, counteracting
the "lost in the middle" effect that occurs after ~50 tool calls.
```
[Original goal -- far away in context, forgotten]
...many tool calls...
[Recently read task_plan.md -- gets ATTENTION]
→ Now make the decision with goals fresh in context
```
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` -> `complete`
- Log any errors encountered in the Errors table
- Note files created or modified in `progress.md`
### 5. Log ALL Errors
Every error goes in `task_plan.md`. Include the attempt number and
resolution. This builds knowledge and prevents repeating failures.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
If an action failed, the next action must be different. Track what
you tried and mutate the approach.
```
if action_failed:
next_action != same_action
```
## 3-Strike Error Protocol
```
ATTEMPT 1: Diagnose & Fix
-> Read error carefully
-> Identify root cause
-> Apply targeted fix
ATTEMPT 2: Alternative Approach
-> Same error? Try a different method
-> Different tool? Different library?
-> NEVER repeat the 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 (with attempt log)
-> Share the specific error
-> Ask for guidance
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | Don't read it | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal content doesn't persist |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context is stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover full state |
## 5-Question Reboot Test
If you can answer these from your planning files, context 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` |
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log every error to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in plugin directory | Create files in project root |
## References
- [Templates](references/templates.md) -- starter templates for all
three planning files
- [Principles](references/principles.md) -- context engineering
principles behind this approach
- [Examples](references/examples.md) -- concrete examples and error
recovery patterns
plugins/planning-with-files/skills/planning-with-files/references/examples.md
+113
View File
@@ -0,0 +1,113 @@
# Examples
## Bug Fix Task
**User request:** "Fix the login bug in the authentication module"
### task_plan.md after Phase 3
```markdown
# Task Plan: Fix Login Bug
## Goal
Identify and fix the bug preventing successful login.
## Phases
### Phase 1: Understand the bug report
- [x] Review bug report details
- **Status:** complete
### Phase 2: Locate relevant code
- [x] Search for auth handler
- **Status:** complete
### Phase 3: Identify root cause
- [ ] Trace the TypeError
- **Status:** in_progress
### Phase 4: Implement fix
- [ ] Fix the async/await issue
- **Status:** pending
### Phase 5: Test and verify
- [ ] Run auth test suite
- **Status:** pending
## Key Questions
1. What error message appears?
2. Which file handles authentication?
3. What changed recently?
## Decisions Made
| Decision | Rationale |
|----------|-----------|
| Auth handler is in src/auth/login.ts | Grep found validateToken() here |
| Root cause: user object not awaited | TypeError trace pointed to line 42 |
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| TypeError: Cannot read property 'token' of undefined | 1 | Found: user object not awaited properly |
```
Key points:
- Phases are broken into discoverable steps
- Decisions record WHERE and WHY, not just WHAT
- The error table captures the actual trace, not a vague description
## Error Recovery Pattern
When something fails, don't hide it. Log it and change approach.
### Wrong approach
```
Action: Read config.json
Error: File not found
Action: Read config.json <- silent retry, same action
Action: Read config.json <- another retry, still same action
```
Three identical attempts, no learning, no progress.
### Correct approach
```
Action: Read config.json
Error: File not found
Update task_plan.md:
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| config.json not found | 1 | Will create default config |
Action: Write config.json (create with defaults)
Action: Read config.json
Success!
```
The error is logged, the approach mutates, and progress is made.
This is Rule 6 (Never Repeat Failures) in action.
## The Read-Before-Decide Pattern
This is the most important pattern in file-based planning.
```
[Many tool calls have happened...]
[Context is long, original goal is fading...]
-> Read task_plan.md <- brings goals back into attention
-> Now make the decision <- goals are fresh in context
```
When to apply:
- Before choosing between implementation approaches
- Before starting a new phase
- After a long sequence of search/read operations
- Whenever you feel uncertain about the current direction
The plan file is not just a record -- it is an active tool for
maintaining focus across long task sequences.
plugins/planning-with-files/skills/planning-with-files/references/principles.md
+84
View File
@@ -0,0 +1,84 @@
# Context Engineering Principles
The principles behind file-based planning, distilled from Manus's
context engineering approach.
## Filesystem as External Memory
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
Anything important gets written to disk. The context window is
temporary -- it resets, it fills up, it loses older content. Files
persist across sessions, have no size limit, and can be selectively
re-read when needed.
When compressing context (summarizing, dropping details), always
preserve pointers to the full data: keep URLs even if web content
is dropped, keep file paths when dropping document contents. Never
lose the ability to recover the original.
## Manipulate Attention Through Recitation
This is the key insight behind the entire approach.
After ~50 tool calls, models forget original goals. This is the
"lost in the middle" effect -- content at the start and end of the
context window gets attention, but the middle fades.
The fix: re-read `task_plan.md` before each major decision. This
pushes the goal and current state into the most recent part of the
context, where it gets maximum attention.
```
Start of context: [Original goal -- far away, low attention]
...many tool calls in the middle...
End of context: [Recently read task_plan.md -- HIGH attention]
```
This is why Manus can handle ~50 tool calls without losing track.
The plan file acts as a goal-refresh mechanism.
## Keep the Wrong Turns In
Leave failed attempts and error traces in the planning files.
Why:
- Failed actions with stack traces let the model implicitly update
its beliefs about what works
- Reduces repetition of the same mistakes
- Error recovery is one of the clearest signals of effective
agentic behavior
The error table in `task_plan.md` serves this purpose. Log every
failure with the attempt number and what you tried. The next attempt
should always be different.
## Avoid Repetitive Patterns
Repetitive action-observation pairs cause drift and hallucination.
When you notice yourself doing the same thing repeatedly:
- Vary your approach (different tool, different angle)
- Re-read the plan to check if you're still on track
- If stuck after 3 attempts, escalate to the user
## Context Offloading
Store full results on disk, keep only references in context.
Practical application:
- Write large search results or API responses to files
- Keep file paths and summaries in context
- Use `glob` and `grep` to find information later
- Load details only when needed (progressive disclosure)
This keeps the context window focused on the current task while
making all accumulated knowledge accessible through the filesystem.
## Source
Based on context engineering principles from
[Manus](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus).
plugins/planning-with-files/skills/planning-with-files/references/templates.md
+111
View File
@@ -0,0 +1,111 @@
# Planning File Templates
Starter templates for the three planning files. Copy to your project
root and fill in the bracketed sections.
## task_plan.md
```markdown
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
1. [Question to answer]
2. [Question to answer]
## Decisions Made
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| | | |
```
## findings.md
```markdown
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
| | |
## Resources
-
```
## progress.md
```markdown
# Progress Log
## Session: [DATE]
### Phase 1: [Title]
- **Status:** in_progress
- **Started:** [timestamp]
- Actions taken:
-
- Files created/modified:
-
### Phase 2: [Title]
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
```