{"owner":"OthmanAdi","repo":"planning-with-files","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","llms.txt"],"skills":{"AGENTS.md":"# AGENTS.md — planning-with-files agent reference card\n\nThis file is the canonical, session-portable reference for how every agent working in this repo must handle commits, releases, version bumps, CHANGELOG entries, and issue/PR communication.\n\n---\n\n## Commit rules\n\n- **Author**: OthmanAdi only for release/maintenance commits. NEVER add `Co-Authored-By:` trailers.\n- **Format**: Conventional Commits — `fix:`, `feat:`, `release:`, `docs:` prefixes.\n- **One release commit on top of the contributor commit(s), never a squash of the contributor's work.** `git merge --squash` rewrites the committer as whoever runs the local commit, which reassigns the contributor's authorship to OthmanAdi — this happened once (v2.40.1 cycle) and is exactly what this rule exists to prevent. Squashing is fine only for collapsing your OWN WIP commits before pushing.\n- No `--no-verify`. No force push to master except tag ref updates.\n- Contributors are credited in CHANGELOG `### Thanks` and `CONTRIBUTORS.md`, never in commit trailers.\n\n---\n\n## Release checklist (12 steps)\n\n1. `gh issue view N` and `gh pr view N` — read both in full.\n2. Verify the bug is real: find the exact file/line, grep for the pattern, confirm reporter is correct.\n3. `python -m pytest tests/ -q` — all tests pass before touching anything.\n4. Merge preserving contributor authorship: `git fetch origin pull/N/head:pr-N && git cherry-pick <pr-head-sha>`, or `gh pr merge --rebase`. Do NOT use `git merge --squash` — it collapses the contributor's commit and reassigns the `Author:` field to whoever runs the local commit, destroying their credit in `git log`.\n5. CHANGELOG — new version entry at top, `### Fixed`/`### Added`/`### Changed`, sachlich, no em-dashes.\n6. CONTRIBUTORS.md — add reporter/contributor, bump \"Total Contributors: N+\", update \"Last updated\" date.\n7. Version bump across all 18 tracked targets plus the local ClawHub staging target when present (see table below).\n8. README — update version badge and add row to releases table.\n9. `git commit`, `git tag vX.Y.Z`, `git push origin master`, `git push origin vX.Y.Z`.\n10. `gh release create vX.Y.Z --title \"vX.Y.Z - <short description>\" --notes \"<release notes>\"`.\n11. Post comment on PR and/or issue via `gh issue comment N --body \"...\"` (run through /humanizer first).\n12. `gh issue close N` if applicable.\n\n---\n\n## Version bump scope\n\nThe maintained release set has 19 entries: 18 tracked files plus the gitignored `clawhub-upload/SKILL.md` publish stage. Every present entry must use the same version string. `scripts/bump-version.py` reports the ClawHub stage as optional when it is absent from a fresh clone, but updates and validates it when present. Maintainer releases must rebuild and verify that stage separately before the manual upload.\n\n| File | Notes |\n|------|-------|\n| `skills/planning-with-files/SKILL.md` | Primary English |\n| `skills/planning-with-files-ar/SKILL.md` | Arabic |\n| `skills/planning-with-files-de/SKILL.md` | German |\n| `skills/planning-with-files-es/SKILL.md` | Spanish |\n| `skills/planning-with-files-zh/SKILL.md` | Simplified Chinese |\n| `skills/planning-with-files-zht/SKILL.md` | Traditional Chinese |\n| `.codebuddy/skills/planning-with-files/SKILL.md` | CodeBuddy IDE |\n| `.codex/skills/planning-with-files/SKILL.md` | Codex IDE |\n| `.cursor/skills/planning-with-files/SKILL.md` | Cursor IDE |\n| `.factory/skills/planning-with-files/SKILL.md` | Factory IDE |\n| `.hermes/skills/planning-with-files/SKILL.md` | Hermes adapter |\n| `.mastracode/skills/planning-with-files/SKILL.md` | Mastra Code |\n| `.opencode/skills/planning-with-files/SKILL.md` | OpenCode IDE |\n| `.pi/skills/planning-with-files/package.json` | npm package manifest |\n| `.agents/skills/planning-with-files/SKILL.md` | Agent Skills standard layout (Zed, Amp, Warp, Devin, Antigravity, Gemini CLI read this path natively; added v3.7.0) |\n| `clawhub-upload/SKILL.md` | Gitignored ClawHub marketplace staging; required for maintainer upload, optional in a fresh clone |\n| `.claude-plugin/plugin.json` | Plugin manifest |\n| `.claude-plugin/marketplace.json` | Marketplace metadata |\n| `CITATION.cff` | Citation file |\n\n**NOT bumped automatically**: `scripts/bump-version.py`'s `LAGGING_FILES` list currently excludes four files, not two — this table only tracked two until this correction:\n- `.continue/skills/planning-with-files/SKILL.md`, `.gemini/skills/planning-with-files/SKILL.md` — intentionally behind. Do not bump without an explicit scope decision.\n- `.pi/skills/planning-with-files/SKILL.md` — carries no `version` field at all; the Pi channel's version lives in `.pi/skills/planning-with-files/package.json` (the npm package `planning-with-files`), which since v3.9.0 IS part of the parity set and bumped by `bump-version.py`. Publishing to npm (`npm publish` from that folder) is a manual step after each release, like the ClawHub upload.\n- `.kiro/skills/planning-with-files/SKILL.md` — carries its own `-kiro`-suffixed scheme (e.g. `3.0.0-kiro`), bumped on Kiro-relevant changes rather than every canonical release.\n\nRecent CHANGELOG entries (v3.1.1–v3.1.3) already describe this 4-file exclusion as \"per AGENTS.md release scope\" — this section previously did not actually say so. It does now.\n\n---\n\n## CHANGELOG format\n\n```\n## [X.Y.Z] - YYYY-MM-DD\n\n### Fixed\n- Short description of what was wrong and how it was fixed.\n\n### Thanks\n- @handle — what they contributed (issue #N / PR #N)\n```\n\nRules:\n- Sachlich (matter-of-fact). No em-dashes. No hype.\n- Contributor line: first name or @handle, one sentence, issue/PR reference.\n- Run any prose through /humanizer before publishing anywhere public.\n\n---\n\n## CONTRIBUTORS.md format\n\n```markdown\n### Other Contributors\n\n**[Name](https://github.com/handle)** — [PR #N](link) / [Issue #N](link)\n- What they did (one bullet per contribution)\n- Impact or context\n```\n\n- Update \"Total Contributors: N+\" count.\n- Update \"Last updated: YYYY-MM-DD\" date.\n- Scope determines section: \"Other Contributors\" for single-issue fix, \"Major Contributions\" for larger work.\n\n---\n\n## Issue/PR comment style\n\nAfter a fix ships, comment on the issue or PR:\n\n- Address by `@handle`.\n- One sentence: fix confirmed in vX.Y.Z.\n- Specific: what the root cause was, what mechanism changed.\n- If they are now in CONTRIBUTORS.md, say so.\n- Run through /humanizer before posting.\n\nNOT acceptable in any public comment:\n- \"Great report!\"\n- \"Thank you so much!\"\n- Em-dashes (do not use — this style)\n- \"I'd like to\"\n- Performative warmth of any kind\n\n---\n\n## Release notes format (gh release create --notes)\n\n```\nWhat changed:\n\n- <Bug description> — <what the fix does>\n- <Feature description> — <how it works>\n\nThanks: @handle for reporting issue #N.\n```\n\n- Start with what changed, not who did it.\n- No em-dashes.\n- Thanks at the bottom.\n\n---\n\n## ClawHub distribution\n\n- ClawHub does NOT auto-sync with GitHub.\n- After every release: manually upload `clawhub-upload/SKILL.md` at clawhub.io.\n- SSL cert on clawhub.io may be expired — proceed through the browser warning.\n- skills.sh / `npx skills`: pulls from GitHub master automatically on next crawl.\n- Anthropic plugin marketplace: requires ClawHub upload to reflect the new version.\n\n---\n\n## Quick reference: what NOT to do\n\n- Do not add Co-Authored-By to any commit.\n- Do not bump `.continue` or `.gemini` without explicit instruction. `.kiro` has its own version scheme, and `.pi/skills/planning-with-files/SKILL.md` has no version field. The Pi npm version in `.pi/skills/planning-with-files/package.json` is part of the canonical parity set.\n- Do not `git merge --squash` a contributor PR — it reassigns their commit authorship. Use cherry-pick or `gh pr merge --rebase`.\n- Do not edit `task_plan.md` or `DESIGN.md` directly (user-owned contracts).\n- Do not log subagent returns into `task_plan.md` — use `progress.md`.\n- Do not use em-dashes in any user-facing prose.\n- Do not skip ClawHub upload after a release.\n","llms.txt":"# planning-with-files\n\n> Persistent file-based planning for AI coding agents and long-running agent tasks. The agent keeps task_plan.md, findings.md, and progress.md on disk so plans survive /clear, context loss, and crashes, with automatic session recovery, an opt-in deterministic completion gate, and multi-agent shared state. Manus-style. Installs across 60+ agents via the SKILL.md open standard.\n\n## Docs\n\n- [README](https://github.com/OthmanAdi/planning-with-files/blob/master/README.md): what it is, quick install, usage, and FAQ\n- [SKILL.md](https://github.com/OthmanAdi/planning-with-files/blob/master/skills/planning-with-files/SKILL.md): the canonical skill definition and install spec\n- [MIGRATION.md](https://github.com/OthmanAdi/planning-with-files/blob/master/MIGRATION.md): v2 to v3 migration and host capability tiers\n- [Benchmarks](https://github.com/OthmanAdi/planning-with-files/blob/master/docs/evals.md): evaluation methodology and results\n- [CITATION.cff](https://github.com/OthmanAdi/planning-with-files/blob/master/CITATION.cff): citation metadata\n\n## Key facts\n\n- Category: persistent planning for AI coding agents. Not a memory or retrieval system: it manages planning continuity for the active task.\n- Pattern: structured note-taking. Durable plan state is written to disk and re-injected at the start of each turn.\n- Evidence: 96.7% workflow-fidelity pass rate with the skill vs 6.7% without in the formal eval; a 217-test suite guards the mechanisms.\n- Differentiators: an opt-in completion gate, multi-agent shared state on disk, and a one-command install across 60+ agents.\n- Problem it solves: context rot and lost plans. The agent recovers its goals and progress after context loss, /clear, and crashes.\n- License: MIT.\n\n## FAQ\n\n### How do I stop my coding agent from losing its plan after /clear or a crash?\n\nKeep the plan on disk. planning-with-files writes task_plan.md, findings.md, and progress.md as durable files, re-injects the active plan at the start of each turn, and runs session recovery after /clear or a crash, so the plan survives /clear and context loss instead of dying with the window. In internal benchmark v1, a session killed mid-task resumed in 5.0 turns with the skill versus 13.3 for a raw agent with no planning method.\n\n### What is the difference between planning-with-files and an agent memory tool?\n\nAgent memory tools recall facts from past sessions. planning-with-files manages the active execution state of the task the agent is working on right now: phases, status, dependencies, and the completion check. It solves planning continuity, not retrieval, and the two are complementary.\n\n### How does this prevent context rot?\n\nContext rot is the drift that sets in as the context window fills and earlier instructions get crowded out. Because the plan is re-injected from disk at the start of each turn, the goals and phase status stay in the model's attention window however long the session runs. This is structured note-taking: durable state lives outside the window and is read back in when needed.\n\n### Which coding agents does this work with?\n\n60+ agents, including Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, and Pi, each via a one-command install. Distribution follows the Agent Skills standard: the repo ships the canonical SKILL.md plus an in-tree .agents/skills/ layout, so tools that read the standard path discover the current skill from a plain git clone.\n\n### How does this work with Claude Code's plan mode?\n\nThey are complementary stages, not alternatives. Plan mode designs the approach before execution; planning-with-files persists execution state on disk while the work runs. After accepting a plan-mode plan, write it into task_plan.md as phases, and from that point the files survive /clear, compaction, and session death, which transcript-bound plan-mode output does not.\n\n### What happens to the plan files after a task is complete?\n\nThey are working memory, not a tracked deliverable: gitignored by default and not archived automatically, so the next task overwrites the root plan. Anything worth keeping should be promoted into code, a commit, or a doc. A completion-triggered archive step is a welcome opt-in extension.\n\n### How much overhead does the skill add?\n\nSteady state, about 330 tokens re-injected per user turn. That is the cost of persistent planning for long-running agent tasks: automatic recovery, plan re-surfacing, and tamper detection run as mechanisms rather than habits the model may forget. For tasks under 5 tool calls, skip the skill entirely.\n"},"files":{"AGENTS.md":"# AGENTS.md — planning-with-files agent reference card\n\nThis file is the canonical, session-portable reference for how every agent working in this repo must handle commits, releases, version bumps, CHANGELOG entries, and issue/PR communication.\n\n---\n\n## Commit rules\n\n- **Author**: OthmanAdi only for release/maintenance commits. NEVER add `Co-Authored-By:` trailers.\n- **Format**: Conventional Commits — `fix:`, `feat:`, `release:`, `docs:` prefixes.\n- **One release commit on top of the contributor commit(s), never a squash of the contributor's work.** `git merge --squash` rewrites the committer as whoever runs the local commit, which reassigns the contributor's authorship to OthmanAdi — this happened once (v2.40.1 cycle) and is exactly what this rule exists to prevent. Squashing is fine only for collapsing your OWN WIP commits before pushing.\n- No `--no-verify`. No force push to master except tag ref updates.\n- Contributors are credited in CHANGELOG `### Thanks` and `CONTRIBUTORS.md`, never in commit trailers.\n\n---\n\n## Release checklist (12 steps)\n\n1. `gh issue view N` and `gh pr view N` — read both in full.\n2. Verify the bug is real: find the exact file/line, grep for the pattern, confirm reporter is correct.\n3. `python -m pytest tests/ -q` — all tests pass before touching anything.\n4. Merge preserving contributor authorship: `git fetch origin pull/N/head:pr-N && git cherry-pick <pr-head-sha>`, or `gh pr merge --rebase`. Do NOT use `git merge --squash` — it collapses the contributor's commit and reassigns the `Author:` field to whoever runs the local commit, destroying their credit in `git log`.\n5. CHANGELOG — new version entry at top, `### Fixed`/`### Added`/`### Changed`, sachlich, no em-dashes.\n6. CONTRIBUTORS.md — add reporter/contributor, bump \"Total Contributors: N+\", update \"Last updated\" date.\n7. Version bump across all 18 tracked targets plus the local ClawHub staging target when present (see table below).\n8. README — update version badge and add row to releases table.\n9. `git commit`, `git tag vX.Y.Z`, `git push origin master`, `git push origin vX.Y.Z`.\n10. `gh release create vX.Y.Z --title \"vX.Y.Z - <short description>\" --notes \"<release notes>\"`.\n11. Post comment on PR and/or issue via `gh issue comment N --body \"...\"` (run through /humanizer first).\n12. `gh issue close N` if applicable.\n\n---\n\n## Version bump scope\n\nThe maintained release set has 19 entries: 18 tracked files plus the gitignored `clawhub-upload/SKILL.md` publish stage. Every present entry must use the same version string. `scripts/bump-version.py` reports the ClawHub stage as optional when it is absent from a fresh clone, but updates and validates it when present. Maintainer releases must rebuild and verify that stage separately before the manual upload.\n\n| File | Notes |\n|------|-------|\n| `skills/planning-with-files/SKILL.md` | Primary English |\n| `skills/planning-with-files-ar/SKILL.md` | Arabic |\n| `skills/planning-with-files-de/SKILL.md` | German |\n| `skills/planning-with-files-es/SKILL.md` | Spanish |\n| `skills/planning-with-files-zh/SKILL.md` | Simplified Chinese |\n| `skills/planning-with-files-zht/SKILL.md` | Traditional Chinese |\n| `.codebuddy/skills/planning-with-files/SKILL.md` | CodeBuddy IDE |\n| `.codex/skills/planning-with-files/SKILL.md` | Codex IDE |\n| `.cursor/skills/planning-with-files/SKILL.md` | Cursor IDE |\n| `.factory/skills/planning-with-files/SKILL.md` | Factory IDE |\n| `.hermes/skills/planning-with-files/SKILL.md` | Hermes adapter |\n| `.mastracode/skills/planning-with-files/SKILL.md` | Mastra Code |\n| `.opencode/skills/planning-with-files/SKILL.md` | OpenCode IDE |\n| `.pi/skills/planning-with-files/package.json` | npm package manifest |\n| `.agents/skills/planning-with-files/SKILL.md` | Agent Skills standard layout (Zed, Amp, Warp, Devin, Antigravity, Gemini CLI read this path natively; added v3.7.0) |\n| `clawhub-upload/SKILL.md` | Gitignored ClawHub marketplace staging; required for maintainer upload, optional in a fresh clone |\n| `.claude-plugin/plugin.json` | Plugin manifest |\n| `.claude-plugin/marketplace.json` | Marketplace metadata |\n| `CITATION.cff` | Citation file |\n\n**NOT bumped automatically**: `scripts/bump-version.py`'s `LAGGING_FILES` list currently excludes four files, not two — this table only tracked two until this correction:\n- `.continue/skills/planning-with-files/SKILL.md`, `.gemini/skills/planning-with-files/SKILL.md` — intentionally behind. Do not bump without an explicit scope decision.\n- `.pi/skills/planning-with-files/SKILL.md` — carries no `version` field at all; the Pi channel's version lives in `.pi/skills/planning-with-files/package.json` (the npm package `planning-with-files`), which since v3.9.0 IS part of the parity set and bumped by `bump-version.py`. Publishing to npm (`npm publish` from that folder) is a manual step after each release, like the ClawHub upload.\n- `.kiro/skills/planning-with-files/SKILL.md` — carries its own `-kiro`-suffixed scheme (e.g. `3.0.0-kiro`), bumped on Kiro-relevant changes rather than every canonical release.\n\nRecent CHANGELOG entries (v3.1.1–v3.1.3) already describe this 4-file exclusion as \"per AGENTS.md release scope\" — this section previously did not actually say so. It does now.\n\n---\n\n## CHANGELOG format\n\n```\n## [X.Y.Z] - YYYY-MM-DD\n\n### Fixed\n- Short description of what was wrong and how it was fixed.\n\n### Thanks\n- @handle — what they contributed (issue #N / PR #N)\n```\n\nRules:\n- Sachlich (matter-of-fact). No em-dashes. No hype.\n- Contributor line: first name or @handle, one sentence, issue/PR reference.\n- Run any prose through /humanizer before publishing anywhere public.\n\n---\n\n## CONTRIBUTORS.md format\n\n```markdown\n### Other Contributors\n\n**[Name](https://github.com/handle)** — [PR #N](link) / [Issue #N](link)\n- What they did (one bullet per contribution)\n- Impact or context\n```\n\n- Update \"Total Contributors: N+\" count.\n- Update \"Last updated: YYYY-MM-DD\" date.\n- Scope determines section: \"Other Contributors\" for single-issue fix, \"Major Contributions\" for larger work.\n\n---\n\n## Issue/PR comment style\n\nAfter a fix ships, comment on the issue or PR:\n\n- Address by `@handle`.\n- One sentence: fix confirmed in vX.Y.Z.\n- Specific: what the root cause was, what mechanism changed.\n- If they are now in CONTRIBUTORS.md, say so.\n- Run through /humanizer before posting.\n\nNOT acceptable in any public comment:\n- \"Great report!\"\n- \"Thank you so much!\"\n- Em-dashes (do not use — this style)\n- \"I'd like to\"\n- Performative warmth of any kind\n\n---\n\n## Release notes format (gh release create --notes)\n\n```\nWhat changed:\n\n- <Bug description> — <what the fix does>\n- <Feature description> — <how it works>\n\nThanks: @handle for reporting issue #N.\n```\n\n- Start with what changed, not who did it.\n- No em-dashes.\n- Thanks at the bottom.\n\n---\n\n## ClawHub distribution\n\n- ClawHub does NOT auto-sync with GitHub.\n- After every release: manually upload `clawhub-upload/SKILL.md` at clawhub.io.\n- SSL cert on clawhub.io may be expired — proceed through the browser warning.\n- skills.sh / `npx skills`: pulls from GitHub master automatically on next crawl.\n- Anthropic plugin marketplace: requires ClawHub upload to reflect the new version.\n\n---\n\n## Quick reference: what NOT to do\n\n- Do not add Co-Authored-By to any commit.\n- Do not bump `.continue` or `.gemini` without explicit instruction. `.kiro` has its own version scheme, and `.pi/skills/planning-with-files/SKILL.md` has no version field. The Pi npm version in `.pi/skills/planning-with-files/package.json` is part of the canonical parity set.\n- Do not `git merge --squash` a contributor PR — it reassigns their commit authorship. Use cherry-pick or `gh pr merge --rebase`.\n- Do not edit `task_plan.md` or `DESIGN.md` directly (user-owned contracts).\n- Do not log subagent returns into `task_plan.md` — use `progress.md`.\n- Do not use em-dashes in any user-facing prose.\n- Do not skip ClawHub upload after a release.\n","llms.txt":"# planning-with-files\n\n> Persistent file-based planning for AI coding agents and long-running agent tasks. The agent keeps task_plan.md, findings.md, and progress.md on disk so plans survive /clear, context loss, and crashes, with automatic session recovery, an opt-in deterministic completion gate, and multi-agent shared state. Manus-style. Installs across 60+ agents via the SKILL.md open standard.\n\n## Docs\n\n- [README](https://github.com/OthmanAdi/planning-with-files/blob/master/README.md): what it is, quick install, usage, and FAQ\n- [SKILL.md](https://github.com/OthmanAdi/planning-with-files/blob/master/skills/planning-with-files/SKILL.md): the canonical skill definition and install spec\n- [MIGRATION.md](https://github.com/OthmanAdi/planning-with-files/blob/master/MIGRATION.md): v2 to v3 migration and host capability tiers\n- [Benchmarks](https://github.com/OthmanAdi/planning-with-files/blob/master/docs/evals.md): evaluation methodology and results\n- [CITATION.cff](https://github.com/OthmanAdi/planning-with-files/blob/master/CITATION.cff): citation metadata\n\n## Key facts\n\n- Category: persistent planning for AI coding agents. Not a memory or retrieval system: it manages planning continuity for the active task.\n- Pattern: structured note-taking. Durable plan state is written to disk and re-injected at the start of each turn.\n- Evidence: 96.7% workflow-fidelity pass rate with the skill vs 6.7% without in the formal eval; a 217-test suite guards the mechanisms.\n- Differentiators: an opt-in completion gate, multi-agent shared state on disk, and a one-command install across 60+ agents.\n- Problem it solves: context rot and lost plans. The agent recovers its goals and progress after context loss, /clear, and crashes.\n- License: MIT.\n\n## FAQ\n\n### How do I stop my coding agent from losing its plan after /clear or a crash?\n\nKeep the plan on disk. planning-with-files writes task_plan.md, findings.md, and progress.md as durable files, re-injects the active plan at the start of each turn, and runs session recovery after /clear or a crash, so the plan survives /clear and context loss instead of dying with the window. In internal benchmark v1, a session killed mid-task resumed in 5.0 turns with the skill versus 13.3 for a raw agent with no planning method.\n\n### What is the difference between planning-with-files and an agent memory tool?\n\nAgent memory tools recall facts from past sessions. planning-with-files manages the active execution state of the task the agent is working on right now: phases, status, dependencies, and the completion check. It solves planning continuity, not retrieval, and the two are complementary.\n\n### How does this prevent context rot?\n\nContext rot is the drift that sets in as the context window fills and earlier instructions get crowded out. Because the plan is re-injected from disk at the start of each turn, the goals and phase status stay in the model's attention window however long the session runs. This is structured note-taking: durable state lives outside the window and is read back in when needed.\n\n### Which coding agents does this work with?\n\n60+ agents, including Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, and Pi, each via a one-command install. Distribution follows the Agent Skills standard: the repo ships the canonical SKILL.md plus an in-tree .agents/skills/ layout, so tools that read the standard path discover the current skill from a plain git clone.\n\n### How does this work with Claude Code's plan mode?\n\nThey are complementary stages, not alternatives. Plan mode designs the approach before execution; planning-with-files persists execution state on disk while the work runs. After accepting a plan-mode plan, write it into task_plan.md as phases, and from that point the files survive /clear, compaction, and session death, which transcript-bound plan-mode output does not.\n\n### What happens to the plan files after a task is complete?\n\nThey are working memory, not a tracked deliverable: gitignored by default and not archived automatically, so the next task overwrites the root plan. Anything worth keeping should be promoted into code, a commit, or a doc. A completion-triggered archive step is a welcome opt-in extension.\n\n### How much overhead does the skill add?\n\nSteady state, about 330 tokens re-injected per user turn. That is the cost of persistent planning for long-running agent tasks: automatic recovery, plan re-surfacing, and tamper detection run as mechanisms rather than habits the model may forget. For tasks under 5 tool calls, skip the skill entirely.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md — planning-with-files agent reference card\n\nThis file is the canonical, session-portable reference for how every agent working in this repo must handle commits, releases, version bumps, CHANGELOG entries, and issue/PR communication.\n\n---\n\n## Commit rules\n\n- **Author**: OthmanAdi only for release/maintenance commits. NEVER add `Co-Authored-By:` trailers.\n- **Format**: Conventional Commits — `fix:`, `feat:`, `release:`, `docs:` prefixes.\n- **One release commit on top of the contributor commit(s), never a squash of the contributor's work.** `git merge --squash` rewrites the committer as whoever runs the local commit, which reassigns the contributor's authorship to OthmanAdi — this happened once (v2.40.1 cycle) and is exactly what this rule exists to prevent. Squashing is fine only for collapsing your OWN WIP commits before pushing.\n- No `--no-verify`. No force push to master except tag ref updates.\n- Contributors are credited in CHANGELOG `### Thanks` and `CONTRIBUTORS.md`, never in commit trailers.\n\n---\n\n## Release checklist (12 steps)\n\n1. `gh issue view N` and `gh pr view N` — read both in full.\n2. Verify the bug is real: find the exact file/line, grep for the pattern, confirm reporter is correct.\n3. `python -m pytest tests/ -q` — all tests pass before touching anything.\n4. Merge preserving contributor authorship: `git fetch origin pull/N/head:pr-N && git cherry-pick <pr-head-sha>`, or `gh pr merge --rebase`. Do NOT use `git merge --squash` — it collapses the contributor's commit and reassigns the `Author:` field to whoever runs the local commit, destroying their credit in `git log`.\n5. CHANGELOG — new version entry at top, `### Fixed`/`### Added`/`### Changed`, sachlich, no em-dashes.\n6. CONTRIBUTORS.md — add reporter/contributor, bump \"Total Contributors: N+\", update \"Last updated\" date.\n7. Version bump across all 18 tracked targets plus the local ClawHub staging target when present (see table below).\n8. README — update version badge and add row to releases table.\n9. `git commit`, `git tag vX.Y.Z`, `git push origin master`, `git push origin vX.Y.Z`.\n10. `gh release create vX.Y.Z --title \"vX.Y.Z - <short description>\" --notes \"<release notes>\"`.\n11. Post comment on PR and/or issue via `gh issue comment N --body \"...\"` (run through /humanizer first).\n12. `gh issue close N` if applicable.\n\n---\n\n## Version bump scope\n\nThe maintained release set has 19 entries: 18 tracked files plus the gitignored `clawhub-upload/SKILL.md` publish stage. Every present entry must use the same version string. `scripts/bump-version.py` reports the ClawHub stage as optional when it is absent from a fresh clone, but updates and validates it when present. Maintainer releases must rebuild and verify that stage separately before the manual upload.\n\n| File | Notes |\n|------|-------|\n| `skills/planning-with-files/SKILL.md` | Primary English |\n| `skills/planning-with-files-ar/SKILL.md` | Arabic |\n| `skills/planning-with-files-de/SKILL.md` | German |\n| `skills/planning-with-files-es/SKILL.md` | Spanish |\n| `skills/planning-with-files-zh/SKILL.md` | Simplified Chinese |\n| `skills/planning-with-files-zht/SKILL.md` | Traditional Chinese |\n| `.codebuddy/skills/planning-with-files/SKILL.md` | CodeBuddy IDE |\n| `.codex/skills/planning-with-files/SKILL.md` | Codex IDE |\n| `.cursor/skills/planning-with-files/SKILL.md` | Cursor IDE |\n| `.factory/skills/planning-with-files/SKILL.md` | Factory IDE |\n| `.hermes/skills/planning-with-files/SKILL.md` | Hermes adapter |\n| `.mastracode/skills/planning-with-files/SKILL.md` | Mastra Code |\n| `.opencode/skills/planning-with-files/SKILL.md` | OpenCode IDE |\n| `.pi/skills/planning-with-files/package.json` | npm package manifest |\n| `.agents/skills/planning-with-files/SKILL.md` | Agent Skills standard layout (Zed, Amp, Warp, Devin, Antigravity, Gemini CLI read this path natively; added v3.7.0) |\n| `clawhub-upload/SKILL.md` | Gitignored ClawHub marketplace staging; required for maintainer upload, optional in a fresh clone |\n| `.claude-plugin/plugin.json` | Plugin manifest |\n| `.claude-plugin/marketplace.json` | Marketplace metadata |\n| `CITATION.cff` | Citation file |\n\n**NOT bumped automatically**: `scripts/bump-version.py`'s `LAGGING_FILES` list currently excludes four files, not two — this table only tracked two until this correction:\n- `.continue/skills/planning-with-files/SKILL.md`, `.gemini/skills/planning-with-files/SKILL.md` — intentionally behind. Do not bump without an explicit scope decision.\n- `.pi/skills/planning-with-files/SKILL.md` — carries no `version` field at all; the Pi channel's version lives in `.pi/skills/planning-with-files/package.json` (the npm package `planning-with-files`), which since v3.9.0 IS part of the parity set and bumped by `bump-version.py`. Publishing to npm (`npm publish` from that folder) is a manual step after each release, like the ClawHub upload.\n- `.kiro/skills/planning-with-files/SKILL.md` — carries its own `-kiro`-suffixed scheme (e.g. `3.0.0-kiro`), bumped on Kiro-relevant changes rather than every canonical release.\n\nRecent CHANGELOG entries (v3.1.1–v3.1.3) already describe this 4-file exclusion as \"per AGENTS.md release scope\" — this section previously did not actually say so. It does now.\n\n---\n\n## CHANGELOG format\n\n```\n## [X.Y.Z] - YYYY-MM-DD\n\n### Fixed\n- Short description of what was wrong and how it was fixed.\n\n### Thanks\n- @handle — what they contributed (issue #N / PR #N)\n```\n\nRules:\n- Sachlich (matter-of-fact). No em-dashes. No hype.\n- Contributor line: first name or @handle, one sentence, issue/PR reference.\n- Run any prose through /humanizer before publishing anywhere public.\n\n---\n\n## CONTRIBUTORS.md format\n\n```markdown\n### Other Contributors\n\n**[Name](https://github.com/handle)** — [PR #N](link) / [Issue #N](link)\n- What they did (one bullet per contribution)\n- Impact or context\n```\n\n- Update \"Total Contributors: N+\" count.\n- Update \"Last updated: YYYY-MM-DD\" date.\n- Scope determines section: \"Other Contributors\" for single-issue fix, \"Major Contributions\" for larger work.\n\n---\n\n## Issue/PR comment style\n\nAfter a fix ships, comment on the issue or PR:\n\n- Address by `@handle`.\n- One sentence: fix confirmed in vX.Y.Z.\n- Specific: what the root cause was, what mechanism changed.\n- If they are now in CONTRIBUTORS.md, say so.\n- Run through /humanizer before posting.\n\nNOT acceptable in any public comment:\n- \"Great report!\"\n- \"Thank you so much!\"\n- Em-dashes (do not use — this style)\n- \"I'd like to\"\n- Performative warmth of any kind\n\n---\n\n## Release notes format (gh release create --notes)\n\n```\nWhat changed:\n\n- <Bug description> — <what the fix does>\n- <Feature description> — <how it works>\n\nThanks: @handle for reporting issue #N.\n```\n\n- Start with what changed, not who did it.\n- No em-dashes.\n- Thanks at the bottom.\n\n---\n\n## ClawHub distribution\n\n- ClawHub does NOT auto-sync with GitHub.\n- After every release: manually upload `clawhub-upload/SKILL.md` at clawhub.io.\n- SSL cert on clawhub.io may be expired — proceed through the browser warning.\n- skills.sh / `npx skills`: pulls from GitHub master automatically on next crawl.\n- Anthropic plugin marketplace: requires ClawHub upload to reflect the new version.\n\n---\n\n## Quick reference: what NOT to do\n\n- Do not add Co-Authored-By to any commit.\n- Do not bump `.continue` or `.gemini` without explicit instruction. `.kiro` has its own version scheme, and `.pi/skills/planning-with-files/SKILL.md` has no version field. The Pi npm version in `.pi/skills/planning-with-files/package.json` is part of the canonical parity set.\n- Do not `git merge --squash` a contributor PR — it reassigns their commit authorship. Use cherry-pick or `gh pr merge --rebase`.\n- Do not edit `task_plan.md` or `DESIGN.md` directly (user-owned contracts).\n- Do not log subagent returns into `task_plan.md` — use `progress.md`.\n- Do not use em-dashes in any user-facing prose.\n- Do not skip ClawHub upload after a release.\n","category":"root","tokens":1984},{"name":"llms.txt","path":"llms.txt","title":"llms.txt","content":"# planning-with-files\n\n> Persistent file-based planning for AI coding agents and long-running agent tasks. The agent keeps task_plan.md, findings.md, and progress.md on disk so plans survive /clear, context loss, and crashes, with automatic session recovery, an opt-in deterministic completion gate, and multi-agent shared state. Manus-style. Installs across 60+ agents via the SKILL.md open standard.\n\n## Docs\n\n- [README](https://github.com/OthmanAdi/planning-with-files/blob/master/README.md): what it is, quick install, usage, and FAQ\n- [SKILL.md](https://github.com/OthmanAdi/planning-with-files/blob/master/skills/planning-with-files/SKILL.md): the canonical skill definition and install spec\n- [MIGRATION.md](https://github.com/OthmanAdi/planning-with-files/blob/master/MIGRATION.md): v2 to v3 migration and host capability tiers\n- [Benchmarks](https://github.com/OthmanAdi/planning-with-files/blob/master/docs/evals.md): evaluation methodology and results\n- [CITATION.cff](https://github.com/OthmanAdi/planning-with-files/blob/master/CITATION.cff): citation metadata\n\n## Key facts\n\n- Category: persistent planning for AI coding agents. Not a memory or retrieval system: it manages planning continuity for the active task.\n- Pattern: structured note-taking. Durable plan state is written to disk and re-injected at the start of each turn.\n- Evidence: 96.7% workflow-fidelity pass rate with the skill vs 6.7% without in the formal eval; a 217-test suite guards the mechanisms.\n- Differentiators: an opt-in completion gate, multi-agent shared state on disk, and a one-command install across 60+ agents.\n- Problem it solves: context rot and lost plans. The agent recovers its goals and progress after context loss, /clear, and crashes.\n- License: MIT.\n\n## FAQ\n\n### How do I stop my coding agent from losing its plan after /clear or a crash?\n\nKeep the plan on disk. planning-with-files writes task_plan.md, findings.md, and progress.md as durable files, re-injects the active plan at the start of each turn, and runs session recovery after /clear or a crash, so the plan survives /clear and context loss instead of dying with the window. In internal benchmark v1, a session killed mid-task resumed in 5.0 turns with the skill versus 13.3 for a raw agent with no planning method.\n\n### What is the difference between planning-with-files and an agent memory tool?\n\nAgent memory tools recall facts from past sessions. planning-with-files manages the active execution state of the task the agent is working on right now: phases, status, dependencies, and the completion check. It solves planning continuity, not retrieval, and the two are complementary.\n\n### How does this prevent context rot?\n\nContext rot is the drift that sets in as the context window fills and earlier instructions get crowded out. Because the plan is re-injected from disk at the start of each turn, the goals and phase status stay in the model's attention window however long the session runs. This is structured note-taking: durable state lives outside the window and is read back in when needed.\n\n### Which coding agents does this work with?\n\n60+ agents, including Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, and Pi, each via a one-command install. Distribution follows the Agent Skills standard: the repo ships the canonical SKILL.md plus an in-tree .agents/skills/ layout, so tools that read the standard path discover the current skill from a plain git clone.\n\n### How does this work with Claude Code's plan mode?\n\nThey are complementary stages, not alternatives. Plan mode designs the approach before execution; planning-with-files persists execution state on disk while the work runs. After accepting a plan-mode plan, write it into task_plan.md as phases, and from that point the files survive /clear, compaction, and session death, which transcript-bound plan-mode output does not.\n\n### What happens to the plan files after a task is complete?\n\nThey are working memory, not a tracked deliverable: gitignored by default and not archived automatically, so the next task overwrites the root plan. Anything worth keeping should be promoted into code, a commit, or a doc. A completion-triggered archive step is a welcome opt-in extension.\n\n### How much overhead does the skill add?\n\nSteady state, about 330 tokens re-injected per user turn. That is the cost of persistent planning for long-running agent tasks: automatic recovery, plan re-surfacing, and tamper detection run as mechanisms rather than habits the model may forget. For tasks under 5 tool calls, skip the skill entirely.\n","category":"root","tokens":1149}]}