# Planning With Files

Persistent file-based planning for multi-step AI-agent work.

- Repository: https://github.com/OthmanAdi/planning-with-files (27809 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g -a claude-code -y`
Codex: `npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g -a codex -y`
Cursor: `npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g -a cursor -y`
Gemini CLI: `npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add OthmanAdi/planning-with-files`

## Description

Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; Kiro skill instructions and steering state read selected project planning context. Recovery reads project planning files and their timestamps only, not agent transcript stores. This adapter registers no Stop hook, never requests continuation, and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Planning with Files (Kiro)

Work like **Manus**: use persistent markdown as your **working memory on disk** while the model context behaves like volatile RAM. Deep background: [references/manus-principles.md](references/manus-principles.md).

Kiro complements this with:

- **Agent Skills** (this file), progressive disclosure when the task matches the description.  
- **Steering**, after bootstrap, `.kiro/steering/planning-context.md` uses `inclusion: auto` and `#[[file:.kiro/plan/…]]` live references ([Steering docs](https://kiro.dev/docs/steering/)).

**Hooks are not bundled:** project-level hooks affect every chat in the workspace. Prefer this skill + steering + the reminder block below.

---

## STEP 0, Bootstrap (once per workspace)

From the **workspace root**:

```bash
sh .kiro/skills/planning-with-files/assets/scripts/bootstrap.sh
```

Windows (PowerShell):

```powershell
pwsh -ExecutionPolicy RemoteSigned -File .kiro/skills/planning-with-files/assets/scripts/bootstrap.ps1
```

Creates:

- `.kiro/plan/task_plan.md`, `findings.md`, `progress.md`
- `.kiro/steering/planning-context.md` (auto + `#[[file:.kiro/plan/…]]`)

Idempotent: existing files are not overwritten.

**Import as a workspace skill (optional):** Kiro → *Agent Steering & Skills* → *Import a skill* → choose this `planning-with-files` folder ([Skills docs](https://kiro.dev/docs/skills/)).

---

## STEP 1, Persistent reminder (after skill activation)

Append the following block to the **end of your reply**, and repeat it at the **end of subsequent replies** while this planning session is active:

> `[Planning Active]` Before each turn, read `.kiro/plan/task_plan.md` and `.kiro/plan/progress.md` to restore context.

---

## STEP 2, Read plan every turn (while active)

1. Read `.kiro/plan/task_plan.md`, goal, phases, status  
2. Read `.kiro/plan/progress.md`, recent actions  
3. Use `.kiro/plan/findings.md` for research and decisions  

If `.kiro/plan/` is missing, run STEP 0.

---

The rest: https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.kiro/skills/planning-with-files/SKILL.md