Planning with Files for Kiro

What it does

When your agent uses it

• Starting a research task or build that will take five or more tool calls
• Recovering context in a Kiro workspace after a long gap or suspected drift
• Keeping a durable plan, findings log and progress log inside the project

Example prompts

• “Set up file-based planning for this workspace and start a plan for the API migration.”
• “Catch me up on where we left off using the planning files.”
• “Log what we just learned about the rate limits in findings.”

Requirements

• A POSIX shell or PowerShell
• Python 3 for the session catch-up script
• Kiro, with read and write access to the workspace
• Compatibility (from SKILL.md): Requires a POSIX shell or PowerShell, Python 3 for session-catchup, and read/write access to the workspace. See Kiro Agent Skills — https://kiro.dev/docs/skills/
• Pre-approved tools (allowed-tools): shell, read, write

Workflow steps

4 steps, taken from the step headings in SKILL.md.

1. 1Bootstrap (once per workspace)
2. 2Persistent reminder (after skill activation)
3. 3Read plan every turn (while active)
4. 4Project-file catchup (after a long gap or suspected drift)

What it can do on your machine

Read from SKILL.md and the folder at commit 41f60ae. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • shell
  • read
  • write

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships script files (PowerShell, Shell and Python), which the agent can run.

  Shell commands in SKILL.md call:

  • sh
  • pwsh
  • python
  • git

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • kiro.dev

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Requires a POSIX shell or PowerShell, Python 3 for session-catchup, and read/write access to the workspace. See Kiro Agent Skills — https://kiro.dev/docs/skills/

  From compatibility in the SKILL.md frontmatter.

Context cost

Planning with Files for Kiro loads about 2.1k tokens when it runs, and up to ~3.8k if it reads all its reference files. Until then it costs about 128 tokens; SKILL.md has 746 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~128

When it runs · the whole SKILL.md, loaded when a task matches

~2.1k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~3.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from OthmanAdi/planning-with-files at commit 41f60ae, republished under its MIT licence (© OthmanAdi). 746 words, ~2,114 tokens.

name

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.

allowed-tools

shell, read, write

compatibility

Requires a POSIX shell or PowerShell, Python 3 for session-catchup, and read/write access to the workspace. See Kiro Agent Skills — https://kiro.dev/docs/skills/

license

MIT

metadata.version

3.0.1-kiro

metadata.integration

kiro

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

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

$(command -v python3 || command -v python) \
  .kiro/skills/planning-with-files/assets/scripts/session-catchup.py "$(pwd)"

python .kiro/skills/planning-with-files/assets/scripts/session-catchup.py (Get-Location)

sh .kiro/skills/planning-with-files/assets/scripts/check-complete.sh

pwsh -File .kiro/skills/planning-with-files/assets/scripts/check-complete.ps1

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

→ Anything important gets written to disk.

if action_failed:
    next_action != same_action

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

© OthmanAdi, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 12 other files (references, assets) in .kiro/skills/planning-with-files of OthmanAdi/planning-with-files.

• SKILL.md
• assets/scripts/bootstrap.ps1
• assets/scripts/bootstrap.sh
• assets/scripts/check-complete.ps1
• assets/scripts/check-complete.sh
• assets/scripts/session-catchup.py
• assets/templates/findings.md
• assets/templates/planning-context.md
• assets/templates/progress.md
• assets/templates/task_plan.md
• references/manus-principles.md
• references/planning-rules.md
• references/planning-templates.md

Open the folder on GitHubat commit 41f60ae