Planning With Files
Structure multi-step agent work with on-disk task_plan.md and notes.md so loops stay aligned with goals across research, fixes, and deliverables.
Overview
Planning with Files is a journey-wide agent skill that keeps multi-step work on track by maintaining task_plan.md and notes.md on disk—usable whenever a solo builder needs to commit goals to files before the agent execut
Install
npx skills add https://github.com/sickn33/antigravity-awesome-skills --skill planning-with-filesWhat is this skill?
- Creates task_plan.md with goals, phased checklists, key questions, and current status
- Uses a read-plan → execute → write notes → update-plan loop on every iteration
- Separates scratch notes (notes.md) from the plan so synthesis and delivery stay traceable
- Examples cover research summaries and bug-fix workflows with explicit phase gates
- Works with any agent task that benefits from persistent files instead of chat-only memory
- Documented 4-loop pattern: create plan → research → synthesize → deliver
- Example plans use explicit phased checklists with in-progress status lines
Adoption & trust: 655 installs on skills.sh; 40.1k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
Long agent sessions lose the original goal, skip steps, and leave no audit trail when everything stays in chat.
Who is it for?
Solo builders running research, writing, or bug-fix workflows where the agent must revisit goals between tool calls.
Skip if: One-shot edits with a single obvious action or jobs where an approved spec and task list already exist and you only need execution.
When should I use this skill?
Starting any multi-step agent task where goals, phases, or deliverables should survive across loops and tool calls.
What do I get? / Deliverables
You get a phased plan, captured notes, and a named deliverable file with status updated each loop so the next agent turn picks up from disk, not guesswork.
- task_plan.md with goals, phases, and status
- notes.md or equivalent scratch capture file
- Final deliverable markdown or code per the plan
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Phase a morning-exercise research job with key questions and source notes before writing the summary.
Break a prototype into phased deliverables so validation work does not outrun the stated goal.
Track authentication bug investigation phases while storing findings in notes.md.
Document repro, fix, and verify steps in the plan while closing phases after each test pass.
Run a structured incident or improvement task with status lines the agent reloads each session.
How it compares
Use instead of ad-hoc “remember the plan” chat prompts when you want filesystem-backed task state.
Common Questions / FAQ
Who is planning-with-files for?
It is for solo and indie builders who delegate multi-step work to coding agents and want plans and notes saved as markdown files in the repo or project folder.
When should I use planning-with-files?
Use it during Idea research (gather sources into notes.md), Validate scoping (phase a prototype plan), Build implementation (track fix phases), Ship debugging (document repro and fix steps), and Operate incidents (structured response plans)—whenever the task has phases worth pers
Is planning-with-files safe to install?
It mainly guides file read/write patterns; review the Security Audits panel on this Prism page and restrict repo access if plans may contain sensitive business data.
SKILL.md
READMESKILL.md - Planning With Files
# Examples: Planning with Files in Action ## Example 1: Research Task **User Request:** "Research the benefits of morning exercise and write a summary" ### Loop 1: Create Plan ```bash Write task_plan.md ``` ```markdown # Task Plan: Morning Exercise Benefits Research ## Goal Create a research summary on the benefits of morning exercise. ## Phases - [ ] Phase 1: Create this plan ✓ - [ ] Phase 2: Search and gather sources - [ ] Phase 3: Synthesize findings - [ ] Phase 4: Deliver summary ## Key Questions 1. What are the physical health benefits? 2. What are the mental health benefits? 3. What scientific studies support this? ## Status **Currently in Phase 1** - Creating plan ``` ### Loop 2: Research ```bash Read task_plan.md # Refresh goals WebSearch "morning exercise benefits" Write notes.md # Store findings Edit task_plan.md # Mark Phase 2 complete ``` ### Loop 3: Synthesize ```bash Read task_plan.md # Refresh goals Read notes.md # Get findings Write morning_exercise_summary.md Edit task_plan.md # Mark Phase 3 complete ``` ### Loop 4: Deliver ```bash Read task_plan.md # Verify complete Deliver morning_exercise_summary.md ``` --- ## Example 2: Bug Fix Task **User Request:** "Fix the login bug in the authentication module" ### task_plan.md ```markdown # Task Plan: Fix Login Bug ## Goal Identify and fix the bug preventing successful login. ## Phases - [x] Phase 1: Understand the bug report ✓ - [x] Phase 2: Locate relevant code ✓ - [ ] Phase 3: Identify root cause (CURRENT) - [ ] Phase 4: Implement fix - [ ] Phase 5: Test and verify ## Key Questions 1. What error message appears? 2. Which file handles authentication? 3. What changed recently? ## Decisions Made - Auth handler is in src/auth/login.ts - Error occurs in validateToken() function ## Errors Encountered - [Initial] TypeError: Cannot read property 'token' of undefined → Root cause: user object not awaited properly ## Status **Currently in Phase 3** - Found root cause, preparing fix ``` --- ## Example 3: Feature Development **User Request:** "Add a dark mode toggle to the settings page" ### The 3-File Pattern in Action **task_plan.md:** ```markdown # Task Plan: Dark Mode Toggle ## Goal Add functional dark mode toggle to settings. ## Phases - [x] Phase 1: Research existing theme system ✓ - [x] Phase 2: Design implementation approach ✓ - [ ] Phase 3: Implement toggle component (CURRENT) - [ ] Phase 4: Add theme switching logic - [ ] Phase 5: Test and polish ## Decisions Made - Using CSS custom properties for theme - Storing preference in localStorage - Toggle component in SettingsPage.tsx ## Status **Currently in Phase 3** - Building toggle component ``` **notes.md:** ```markdown # Notes: Dark Mode Implementation ## Existing Theme System - Located in: src/styles/theme.ts - Uses: CSS custom properties - Current themes: light only ## Files to Modify 1. src/styles/theme.ts - Add dark theme colors 2. src/components/SettingsPage.tsx - Add toggle 3. src/hooks/useTheme.ts - Create new hook 4. src/App.tsx - Wrap with ThemeProvider ## Color Decisions - Dark background: #1a1a2e - Dark surface: #16213e - Dark text: #eaeaea ``` **dark_mode_implementation.md:** (deliverable) ```markdown # Dark Mode Implementation ## Changes Made ### 1. Added dark theme colors File: src/styles/theme.ts ... ### 2. Created useTheme hook File: src/hooks/useTheme.ts ... ``` --- ## Example 4: Error Recovery Pattern When something fails, DON'T hide it: ### Before (Wrong) ``` Action: Read config.json Error: File not found Action: Read config.json # Silent retry Action: Read config.json # Another retry ``` ### After (Correct) ``` Action: Read config.json Error: File not found # Update task_plan.md: ## Errors Encountered - config.json not found → Will create default config Action: Write config.json (default config) Action: Read config.json Success! ``` --- ## The Read-Before-Decide Pattern