Planning With Files
Keep multi-step agent work honest by mirroring goals in task_plan.md and evidence in notes.md instead of losing context in chat.
Overview
planning-with-files is a journey-wide agent skill that structures work with task_plan.md and notes.md loops—usable whenever a solo builder needs visible phases before committing agent effort.
Install
npx skills add https://github.com/jimmyzhouj/planning-with-files --skill planning-with-filesWhat is this skill?
- Repeating loop: Read task_plan.md → work → update notes.md → edit plan status
- Phased checklists with explicit current phase in every plan file
- Works for research summaries and bug-fix investigations alike
- Creates durable artifacts (task_plan.md, notes.md, deliverable markdown) beside the repo
- Reduces goal drift by re-reading the plan each loop
- Example research flow uses 4 phased loops from plan creation through delivery
- Bug-fix example includes explicit phased checklist in task_plan.md
Adoption & trust: 1 installs on skills.sh; trending (+100% hot-view momentum).
What problem does it solve?
Long agent tasks dissolve into chat history with no single source of truth for goals, open questions, or what phase you are actually in.
Who is it for?
Solo builders running research, fixes, or feature work across many agent turns who want lightweight PM without Notion or Jira.
Skip if: One-liner edits with an already-approved spec and no need for persisted phase tracking, or teams that mandate a single external ticket system as the only plan source.
When should I use this skill?
Starting any multi-step agent task where goals, phases, and findings should persist in task_plan.md and notes.md rather than chat only.
What do I get? / Deliverables
You finish with on-disk plan and notes files plus a named deliverable, with phases checked off so the next session or skill can pick up cleanly.
- task_plan.md with phases and status
- notes.md or equivalent capture file
- Final deliverable markdown or fix as named in the plan
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Draft task_plan.md with key questions before web research on a market topic, storing sources in notes.md.
Phase a landing-page or MVP scope doc so you do not build features absent from the checked plan.
Track bug-fix phases from repro through patch while re-reading the plan each agent loop.
Run a four-loop research synthesis that ends in a deliverable summary markdown file.
Document incident investigation steps and findings in notes.md while updating status in task_plan.md.
How it compares
Use instead of improvising in chat when you want filesystem plans like a mini runbook, not a heavyweight Gantt template pack.
Common Questions / FAQ
Who is planning-with-files for?
Indie and solo builders using Claude Code, Cursor, or Codex who want repeatable planning artifacts on disk for multi-step agent jobs.
When should I use planning-with-files?
Use it in Idea for scoped research plans, Validate to lock scope before building, Build for features and bug fixes, Ship for launch checklists, Grow for content or analytics deep dives, and Operate when iterating on incidents—all via the same task_plan.md loop.
Is planning-with-files safe to install?
It is primarily markdown read/write in your repo; still review the skill source and the Security Audits panel on this page before automating writes in production branches.
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