Compare commits

...
116 Commits
Author SHA1 Message Date
OthmanAdi a65b183e7d fix(i18n): migrate Chinese variants to CLAUDE_SKILL_DIR + bump to v2.30.0
- planning-with-files-zh: CLAUDE_PLUGIN_ROOT -> CLAUDE_SKILL_DIR (was 2.24.0)
- planning-with-files-zht: CLAUDE_PLUGIN_ROOT -> CLAUDE_SKILL_DIR (was 2.28.0)
- Same 3-level fallback chain as main skill
- All body references updated (session-catchup, templates, table)
2026-04-03 08:30:33 +02:00
OthmanAdi 057fab5d6a fix: bump plugin and marketplace metadata to v2.30.0
plugin.json and marketplace.json were stuck at 2.23.0 (7 releases behind).
Users installing via /plugin install were getting outdated versions
missing session recovery, security fixes, and analytics templates.

Fixes #117
2026-04-03 08:24:04 +02:00
OthmanAdi d39468ba9c fix: add analytics templates to skill directory + fix stale CLAUDE_PLUGIN_ROOT reference
- Copy analytics_task_plan.md and analytics_findings.md into
  skills/planning-with-files/templates/ so --template analytics works
  after npx skills add (was only in root templates/, unreachable)
- Fix one remaining CLAUDE_PLUGIN_ROOT reference in SKILL.md line 63
2026-04-03 01:37:39 +02:00
OthmanAdi 91b6d89af3 docs: restructure README for branch-based IDE support
- Replace inline IDE tables with branch reference table
- Add Branches section listing all active branches
- Update File Structure to reflect cleaned master
- Update version references to v2.30.0
- Simplify Sandbox Runtimes section
2026-04-03 01:34:45 +02:00
OthmanAdi 9334586e0b refactor: move IDE-specific configs to dedicated branches
Remove all IDE-specific directories from master. Each IDE's configuration
now lives on its own branch for independent maintenance:

  ide/cursor, ide/codex, ide/continue, ide/gemini, ide/opencode,
  ide/codebuddy, ide/factory, ide/pi-agent, ide/kiro, ide/mastra,
  ide/copilot

Master branch now contains only:
- Core skill (skills/planning-with-files/)
- Chinese variants (skills/planning-with-files-zh/, -zht/)
- Plugin manifest (.claude-plugin/)
- Templates, scripts, docs, tests, examples

Removed scripts/sync-ide-folders.py (no IDE folders to sync on master).

All IDE SKILL.md versions bumped to 2.30.0 on their branches.
2026-04-03 01:33:35 +02:00
OthmanAdi 65a7331968 fix(skill): migrate from CLAUDE_PLUGIN_ROOT to CLAUDE_SKILL_DIR
Replace ${CLAUDE_PLUGIN_ROOT} with ${CLAUDE_SKILL_DIR} in main SKILL.md
for reliable path resolution across all install methods.

- Stop hook: 3-level fallback (CLAUDE_SKILL_DIR -> CLAUDE_PLUGIN_ROOT -> hardcoded)
- Session catchup: uses CLAUDE_SKILL_DIR for script path
- Templates: uses CLAUDE_SKILL_DIR for template path
- Default fallback updated to .claude/skills/ (npx skills add location)
- Bump version to 2.30.0

Related: #32
2026-04-03 01:27:03 +02:00
OthmanAdi bb3a21ab0d docs: update CONTRIBUTORS, CHANGELOG, README for v2.29.0 2026-03-24 20:00:46 +01:00
Ahmad Othman Ammar Adi. 02a4ad6034 feat(templates): add analytics workflow template (#115)
feat(templates): add analytics workflow template
2026-03-24 19:57:14 +01:00
Matt Van Horn c7f89340d6 feat(templates): add analytics workflow template
Add domain-specific planning templates for data analytics and
exploration workflows. The existing 5-phase template assumes a
software development cycle - analytics sessions need different
phases (Data Discovery, Exploratory Analysis, Hypothesis Testing,
Synthesis) and different tracking structures (Data Sources,
Hypothesis Log, Query Results, Statistical Findings).

New files:
- templates/analytics_task_plan.md: 4-phase analytics plan
- templates/analytics_findings.md: data source and hypothesis tracking

Modified files:
- scripts/init-session.sh: add --template/-t flag
- scripts/init-session.ps1: add -Template parameter

Usage: ./init-session.sh --template analytics
Default behavior is unchanged when flag is omitted.

Relates to #103
2026-03-24 10:18:00 -07:00
OthmanAdi 3b6c3ce356 Release v2.28.0: Traditional Chinese (zh-TW) skill variant
- Bump planning-with-files-zht version to 2.28.0
- Fix missing trailing newline in zht SKILL.md
- Add @waynelee2048 to CONTRIBUTORS.md (PR #113)
- Update contributor count and last-updated date
2026-03-22 17:03:03 +01:00
Ahmad Othman Ammar Adi. 77129ad356 Merge pull request #113 from waynelee2048/feat/add-traditional-chinese-skill
feat(i18n): add Traditional Chinese (zh-TW) skill variant
2026-03-22 16:28:57 +01:00
Wayne LeeandClaude Opus 4.6 7f67b35de7 feat(i18n): translate all script messages to Traditional Chinese
Translate embedded templates and output messages in init-session,
check-complete, and session-catchup scripts to Traditional Chinese
for consistent localization across the zht skill variant.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-22 23:25:39 +08:00
Wayne LeeandClaude Opus 4.6 2fd41e4494 docs: add Traditional Chinese install command to README
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-22 23:15:18 +08:00
Wayne LeeandClaude Opus 4.6 0eaa8aeb18 feat(i18n): add Traditional Chinese (zh-TW) skill variant
Add planning-with-files-zht with fully translated SKILL.md, templates,
and scripts for Traditional Chinese (Taiwan) users.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-22 23:12:41 +08:00
OthmanAdi 4206e0e5e8 docs: update CONTRIBUTORS, CHANGELOG, README for v2.27.0
- Add @EListenX (Yi Chenxi) to Major Contributions in CONTRIBUTORS.md
- Add v2.27.0 entry to CHANGELOG.md (Kiro Agent Skill support)
- Update README version table, Kiro badge, and platform description
- Update last-updated date to March 20, 2026
2026-03-20 23:23:17 +01:00
OthmanAdi 6dc9e3f44a feat(kiro): add Agent Skill layout under .kiro/skills/ (#112)
Adds full Kiro Agent Skill support with proper .kiro/skills/ layout,
bootstrap scripts, steering integration, and planning templates.
Replaces the old .kiro/scripts/ and .kiro/steering/ approach.
Also updates docs/kiro.md and sync-ide-folders.py skip list.

Contributed by Yi Chenxi (@EListenX)
2026-03-20 23:19:32 +01:00
OthmanAdi bedf1a291a docs: bump version to v2.26.2 for YAML frontmatter fix 2026-03-20 16:37:15 +01:00
OthmanAdi 3ff59de625 fix: replace --- with === in hook commands to prevent YAML frontmatter breakage
The literal '---' inside the UserPromptSubmit hook command was parsed as
a YAML document separator, corrupting the skill description and causing
PreToolUse:Write hook errors. Changed to '=== recent progress ===' in
all 11 affected files.
2026-03-20 16:34:30 +01:00
OthmanAdi d2b75b8177 docs: bump version to v2.26.1 for session catchup fix 2026-03-20 15:24:21 +01:00
OthmanAdi 66a0cb510f test: add automated session recovery test (11 assertions)
Tests hook output, path sanitization, UTF-8 encoding, and separator
handling without requiring interactive /clear. Run with:
  bash tests/test_clear_recovery.sh
2026-03-20 15:15:55 +01:00
OthmanAdi 9aee747eb0 fix: session catchup after /clear — path sanitization + content injection (#106)
Two root causes found:

1. Path sanitization bug: On Windows, Git Bash passes /c/Users/... but
   Claude Code stores sessions under C--Users-... The script converted
   to -c-Users-... which never matched. Added normalize_path() that
   converts Git Bash paths to Windows paths before sanitizing.

2. Hook was advisory, not actionable: UserPromptSubmit hook only said
   "read task_plan.md" — after /clear the agent has no context and may
   ignore text advice. Now the hook dumps actual content: first 50 lines
   of task_plan.md + last 20 lines of progress.md. The agent gets the
   plan state injected directly, no tool calls needed.

Also fixed: UTF-8 encoding for session file parsing on Windows (cp1252
default caused UnicodeDecodeError on non-ASCII content).

Changes synced to all IDE variants via sync-ide-folders.py.
2026-03-20 09:35:41 +01:00
v-yichenxi 402d929564 feat(kiro): add Kiro Agent Skill and align Mastra/Cursor hooks (v2.23.1)
IDE hook follow-up (v2.23.0 gaps):

- Mastra Code: hooks.json is the hook source — add UserPromptSubmit, refresh PostToolUse.
- Cursor: .cursor/hooks/ — add user-prompt-submit, update post-tool-use and stop scripts.

Kiro workspace skill:

- Add .kiro/skills/planning-with-files/ (SKILL.md, references, templates, scripts).
- Bootstrap creates .kiro/plan and auto steering planning-context.md (#[[file:]]).
- Add session-catchup.py; check-complete/bootstrap for sh and PowerShell.
- Remove duplicate .kiro/scripts and always-on steering; sync script skips .kiro.
- Update docs/kiro.md and README (Kiro = Agent Skill + Steering).
2026-03-20 11:40:00 +08:00
OthmanAdi bd8602d851 fix: bump version references to v2.26.0 (v2.24.0 and v2.25.0 already taken) 2026-03-20 00:56:40 +01:00
OthmanAdi ab7d76121d feat: IDE audit — Gemini/Factory/Copilot hooks, consolidate 4 redundant IDEs
v2.24.0 — Full IDE support audit and cleanup:

New features:
- Gemini CLI: add hooks (settings.json + 5 scripts: SessionStart, BeforeTool,
  AfterTool, BeforeModel, SessionEnd). BeforeModel is unique to Gemini — injects
  plan awareness before every model call.
- FactoryAI Droid: add hooks to SKILL.md frontmatter (was skills-only, now has
  all 4 lifecycle events) + add scripts.
- GitHub Copilot: add errorOccurred hook for automatic error logging to plan.

Bug fixes:
- Continue: fix .prompt file — was entirely in Chinese, now English
- Pi Agent: fix package.json repo URL (was ttttmr/, now OthmanAdi/)
- Mastra Code: sync drifted check-complete.sh and session-catchup.py to canonical
- CodeBuddy/Codex: remove duplicate assets/templates/ directories

Consolidation:
- Remove .adal/, .agent/ (Antigravity), .kilocode/, .openclaw/ directories.
  These IDEs implement the standard Agent Skills spec with no hooks — install
  via `npx skills add` which handles IDE-specific placement automatically.
- README: restructure IDE table into Enhanced (hooks) vs Standard (Agent Skills)
- sync-ide-folders.py: remove entries for consolidated IDEs

Net: -4,609 lines (removed duplication, added real value)
2026-03-20 00:53:33 +01:00
Ahmad Othman Ammar Adi. ecb29a65c9 Update README.md 2026-03-19 23:00:41 +01:00
Ahmad Othman Ammar Adi. b085f4ded0 Update README.md 2026-03-19 22:59:42 +01:00
OthmanAdi 6bcb6c438a docs: add Chinese install line to Quick Install section 2026-03-19 22:50:25 +01:00
OthmanAdi 75fcdaa6f6 feat: add full Chinese localization (planning-with-files-zh)
Complete Chinese version of the planning skill for Claude Code:
- Chinese SKILL.md with all instructions, rules, and patterns
- Chinese templates (task_plan.md, findings.md, progress.md)
- Chinese /plan-zh command
- Shared scripts (language-agnostic)
- Install: npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g

Reverts the inline Chinese trigger words from PR #108 in the English
SKILL.md description. The proper Chinese localization is now a separate
skill with its own full implementation.

Inspired by @kevinaimonster (PR #108).
2026-03-19 22:46:52 +01:00
kevinaimonster 795f58c770 feat: add Chinese trigger words to SKILL.md description (PR #108)
Adds Chinese trigger words to the canonical SKILL.md description field. This will be extended into a full Chinese localization in the next commit.

Thanks @kevinaimonster for the inspiration.
2026-03-19 22:38:03 +01:00
OthmanAdi fcca0fce0b style: shorten openclaw-github-repo-commander description to match table style 2026-03-19 22:28:28 +01:00
Da Wei 8d876e87b7 feat: add openclaw-github-repo-commander to Community Built (PR #107)
Adds @wd041216-bit's OpenClaw GitHub repo management workflow to the Community Built section.

Thanks @wd041216-bit
2026-03-19 22:27:35 +01:00
沙士喻 279fa27560 fix: restore Codex session-catchup fallback (PR #109)
Restores the Codex-specific fallback in session-catchup.py that was overwritten by the v2.23.0 sync. When running from a Codex skill path, the script now skips cleanly instead of silently scanning Claude storage.

Changes:
- Fix root cause in canonical session-catchup.py (not just Codex copy)
- Sync fix across all 7 IDE copies
- Add regression test to prevent future overwrites

Thanks @YSAA1
2026-03-19 22:14:52 +01:00
OthmanAdi f54a290c31 fix: patch Mastra Code hooks.json and Cursor hook scripts (v2.23.1)
Fixes gaps in v2.23.0 where two IDEs with their own hook systems
were not updated:

1. Mastra Code: hooks.json is the actual hook source, not SKILL.md.
   Added UserPromptSubmit hook, updated PostToolUse message.

2. Cursor: .cursor/hooks/ scripts are the actual hook source.
   Created user-prompt-submit.sh/ps1 for session recovery.
   Updated post-tool-use.sh/ps1 with progress.md reminder.
   Updated stop.sh/ps1 with completion re-entry guidance.

Also removed accidentally committed docs/article-v2.md from tracking.
2026-03-16 00:13:55 +01:00
OthmanAdi 09ee8e4ec6 fix: session catchup, progress tracking, and post-completion workflow (v2.23.0)
Fixes #106. Three root causes identified and fixed:

1. Session catchup not working after /clear: Added UserPromptSubmit hook
   to all 7 IDE SKILL.md files. When task_plan.md exists, injects a
   directive to read all planning files before proceeding. Fires on every
   user message, ensuring context recovery after /clear or compaction.

2. Progress not updating consistently: PostToolUse hook message now leads
   with "Update progress.md" instead of only mentioning task_plan.md.
   Added plan existence guard to avoid noise when no plan is active.

3. Post-plan additions not tracked: check-complete scripts now output
   re-entry guidance when all phases are complete. Copilot agent-stop
   scripts now return continuation context instead of empty JSON.
   Added Critical Rule #7 (Continue After Completion) to SKILL.md body.

Applied across: 7 IDE SKILL.md files, 16 synced check-complete scripts,
4 Copilot hook scripts, CHANGELOG, plugin.json, marketplace.json.
2026-03-16 00:08:20 +01:00
Ahmad Othman Ammar Adi 57d13d7bd4 Add skills.sh one-liner installer for 40+ agent compatibility 2026-03-14 10:22:21 +01:00
OthmanAdi 74ad69e01d fix: sync OpenClaw and Continue SKILL.md to v2.22.0
- Updated .openclaw/skills/planning-with-files/SKILL.md from 2.16.1 to 2.22.0
- Updated .continue/skills/planning-with-files/SKILL.md from 2.16.1 to 2.22.0
- Added Security Boundary section to both (prevents prompt injection via task_plan.md)
- Added anti-pattern: "Write web content to task_plan.md" -> "Write external content to findings.md only"
- Added clawhub-upload/, clawhub-changelog.txt, skill-submission-targets.txt to .gitignore
2026-03-12 00:04:36 +01:00
OthmanAdi 7b55095bce docs: polish evals.md wording 2026-03-06 18:20:36 +01:00
OthmanAdi 6ecbe15838 docs: add real timing and token metrics to evals.md
Captured from task completion notifications during the eval run.
with_skill avg: 19,926 tokens / 115s
without_skill avg: 11,899 tokens / 98s
+68% tokens, +17% time — the cost of structured 3-file output.
2026-03-06 09:09:19 +01:00
OthmanAdi ade3ecec9f docs: add formal benchmark results, article, and README verification badges (v2.22.0)
Evaluated planning-with-files using Anthropic's skill-creator framework:
- 10 parallel subagents (5 with_skill + 5 without_skill), 5 task types
- 30 objectively verifiable assertions
- with_skill: 96.7% pass rate (29/30) vs 6.7% (2/30) without_skill
- 3 blind A/B comparisons: with_skill wins 3/3, avg 10.0/10 vs 6.8/10

Also documents the v2.21.0 security fix (WebFetch/WebSearch removed from
allowed-tools, Security Boundary section added) with full technical context
on why the PreToolUse hook created an indirect prompt injection amplification
vector and how the fix resolves it.

Added:
- docs/evals.md: full methodology, assertions, results, benchmark data
- docs/article.md: technical write-up for publication
- README.md: Benchmark Results section + 3 verification badges
- CHANGELOG.md: v2.22.0 entry
2026-03-06 09:06:44 +01:00
OthmanAdi 5f1a6d2f9c fix: update marketplace.json version to 2.21.0
marketplace.json was stuck at 2.0.0, preventing the plugin marketplace
from picking up the security fix.
2026-03-05 18:29:26 +01:00
OthmanAdi ee02cc5af8 security: remove WebFetch/WebSearch from allowed-tools, add Security Boundary (v2.21.0)
Fixes Gen Agent Trust Hub FAIL and reduces Snyk W011 risk score.

Root cause: WebFetch + WebSearch in allowed-tools created a toxic flow —
untrusted web content could be written to files, then amplified on every
tool call via the PreToolUse hook re-reading task_plan.md.

Changes:
- Remove WebFetch and WebSearch from allowed-tools in all 7 IDE SKILL.md
  variants (Claude Code, Cursor, Kilocode, CodeBuddy, Codex, OpenCode,
  Mastra Code) — this skill is a planning tool, not a web research tool
- Add Security Boundary section to SKILL.md: external content must go to
  findings.md only, never task_plan.md; treat all web content as untrusted
- Add inline security note to examples.md WebSearch line across all 14
  IDE variants
- Bump version to 2.21.0 across all versioned files
2026-03-05 18:13:03 +01:00
OthmanAdi 24442f5c8c docs: add CHANGELOG for v2.20.0 and expand @tt-a1i contributor entry
- Add v2.20.0 changelog covering PR #99 and PR #100 (docs consistency, Codex catchup fix)
- Expand @tt-a1i entry in CONTRIBUTORS.md to include all three PRs (#92, #99, #100) with full detail
2026-03-04 20:19:58 +01:00
Ahmad Othman Ammar Adi. c411434de7 fix: docs consistency, examples naming, sync CLI help behavior (#99)
Fix docs path issues, examples naming, and sync CLI help behavior
2026-03-04 20:17:57 +01:00
Ahmad Othman Ammar Adi. d5dee9b4f6 fix(codex): avoid silent failure when session-catchup scans Claude path (#100)
Codex catchup: avoid Claude-path silent failure
2026-03-04 20:17:41 +01:00
OthmanAdi 23e1c15309 chore: add CHANGELOG entry for v2.19.0 and update contributor date
- Add v2.19.0 changelog entry for PR #92 (Codex broken links fix by @tt-a1i)
- Update CONTRIBUTORS.md last-updated date to March 4, 2026
2026-03-04 20:08:41 +01:00
tt-a1i 50dff177f2 Codex: avoid scanning Claude session path in catchup 2026-03-04 10:16:28 +08:00
tt-a1i dbfe812adc Fix docs links and sync tooling consistency 2026-03-04 10:12:13 +08:00
OthmanAdi b9da30cc2a docs: add tt-a1i and msuadOf to CONTRIBUTORS.md 2026-03-03 11:43:17 +01:00
Ahmad Othman Ammar Adi. cbf4de43b8 Merge pull request #92 from tt-a1i/fix/codex-skill-reference-links
fix(codex): correct broken Advanced Topics links in planning-with-files SKILL
2026-03-03 11:39:53 +01:00
tt-a1i ada9ff4212 fix(codex): correct planning-with-files advanced-topic links 2026-03-03 15:59:56 +08:00
Ahmad Othman Ammar Adi. 8004498f35 docs: replace documentation table in README with link to docs/ folder 2026-02-28 13:58:24 +01:00
Ahmad Othman Ammar Adi. 6e9d9360e4 docs: replace contributors table in README with link to CONTRIBUTORS.md 2026-02-28 13:29:41 +01:00
Ahmad Othman Ammar Adi. e42a251cea docs: add 11 missing contributors from merged PRs 2026-02-28 01:11:16 +01:00
Ahmad Othman Ammar Adi. 17029df2f0 docs: add raykuo998 to contributors (PR #86, PR #88) 2026-02-28 01:08:22 +01:00
Ahmad Othman Ammar Adi. d8e7837d2b docs: add v2.18.3 changelog entry (Windows hook fixes by raykuo998) 2026-02-28 01:08:21 +01:00
Ahmad Othman Ammar Adi. 65e0fcf42d fix: Stop hook multiline YAML command not parsed by Git Bash on Windows
fix: Stop hook fails on Windows — multiline YAML command not parsed by Git Bash
2026-02-28 01:07:08 +01:00
Ahmad Othman Ammar Adi. 5f41ac00fe Merge pull request #88 from raykuo998/fix/check-complete-ps1-parsing 2026-02-27 10:48:27 +01:00
guo-feng-rui 7cfa786e35 fix: check-complete.ps1 fails to parse on PowerShell due to special characters
PowerShell's parser fails on three categories of special characters inside
double-quoted strings in check-complete.ps1:

1. UTF-8 em-dash (U+2014) in comments — misinterpreted as code tokens
2. Square brackets [planning-with-files] — parsed as array index syntax
3. Parentheses ($COMPLETE/$TOTAL) and phase(s) — parsed as subexpressions

Fix: replace double-quoted Write-Host strings with single-quoted strings
and string concatenation, and replace em-dashes with ASCII double-hyphens.

Applied to all 12 tool variant copies (adal, codebuddy, codex, continue,
gemini, kiro, mastracode, openclaw, opencode, pi, scripts, skills).

Verified on Windows 11 with PowerShell 5.1 — all scenarios pass.

Closes #87
2026-02-27 16:17:24 +08:00
guo-feng-rui 6cc1584671 fix: restore mastracode relative-path fallback for project-local installs
The original mastracode variant had a two-step path resolution that fell
back to a project-relative path if the $HOME-based path didn't exist.
This was dropped in the previous commit. Restore it to preserve support
for project-local mastracode installations.
2026-02-27 12:09:35 +08:00
guo-feng-rui f2f05478bb fix: Stop hook fails on Windows — multiline YAML command not parsed by Git Bash
The Stop hook used a YAML multiline block (command: |) with a 25-line bash
script for OS detection and script dispatch. On Windows, Claude Code passes
hook commands through Git Bash, which fails to parse the multiline content —
the SCRIPT_DIR=... variable assignment is interpreted as a command name rather
than a shell assignment, producing:

  bash: SCRIPT_DIR=/c/Users/.../scripts: No such file or directory
  sh: /check-complete.sh: No such file or directory

Replace the multiline block with a single-line command that:
1. Sets SD variable inline (works in all sh-compatible shells)
2. Tries powershell.exe first (covers Windows)
3. Falls back to sh (covers Linux/macOS)

This eliminates the OS-detection logic entirely — the fallback chain handles
platform differences implicitly. Applied to all 7 tool variants (claude,
cursor, codex, codebuddy, kilocode, mastracode, opencode).
2026-02-27 12:04:16 +08:00
OthmanAdi acfd2f0c74 fix(mastra): add hooks.json, fix SKILL.md path var, correct docs
Mastra Code reads hooks from .mastracode/hooks.json, not SKILL.md
frontmatter. All three hooks (PreToolUse, PostToolUse, Stop) were
silently non-functional. Added hooks.json with proper Mastra format
including matchers and timeouts. Fixed MASTRACODE_SKILL_ROOT env var
(does not exist in Mastra Code). Corrected docs/mastra.md to accurately
describe the hooks.json system and fixed personal install instructions
to include the hooks file.
2026-02-26 19:43:46 +01:00
OthmanAdi 931bb545ab fix: stretch Star History chart to full width 2026-02-26 19:01:16 +01:00
OthmanAdi 15e33d261a fix(copilot): complete PS1 encoding fix - Get-Content UTF8 + no-BOM (Issue #82)
v2.16.1 fixed the output pipe encoding but missed the read side.
Get-Content without -Encoding in PS5 reads files with the system ANSI
code page (Windows-1252), corrupting non-ASCII characters in
task_plan.md and SKILL.md before they reach the output pipe.

Changes to pre-tool-use.ps1, session-start.ps1, agent-stop.ps1:
- All Get-Content calls: added -Encoding UTF8
- [System.Text.Encoding]::UTF8 replaced with
  [System.Text.UTF8Encoding]::new($false) — UTF-8 without BOM,
  preventing stray 0xEF 0xBB 0xBF preamble in JSON output

Closes #82
2026-02-26 18:59:05 +01:00
OthmanAdi 6e8f128a79 feat: BoxLite sandbox runtime integration (Issue #84)
Adds documentation and examples for running planning-with-files
inside BoxLite micro-VM sandboxes via ClaudeBox.

- docs/boxlite.md: full integration guide covering ClaudeBox Skill
  API, persistent sessions, hooks behavior inside the VM, snapshots,
  session recovery, and troubleshooting
- examples/boxlite/quickstart.py: working Python example using
  ClaudeBox's Skill object to inject planning-with-files into a VM
- examples/boxlite/README.md: example context and requirements
- README: new Sandbox Runtimes section (BoxLite is infrastructure,
  not an IDE - kept separate from the 16-platform IDE table)
- README: BoxLite badge, Documentation table entry, version bump
  to 2.18.0, file structure updated
- CHANGELOG: v2.18.0 entry with full details
- CONTRIBUTORS: @DorianZheng added for Issue #84

BoxLite loads via pip install claudebox - no .boxlite/ folder needed
since ClaudeBox uses a Python Skill object, not file-system discovery.

Closes #84
2026-02-26 18:45:54 +01:00
OthmanAdi 7a0d05145a chore: untrack orphaned draft files
WIKI_HOME_PAGE.md and DISCUSSION_2_CONTENT.md were leftover
scaffolding — wiki draft never published and old discussion
post content. Removed from tracking, added to .gitignore.
2026-02-25 23:34:16 +01:00
OthmanAdi d1ee93c567 release: v2.17.0
Bump plugin manifest to 2.17.0 so Claude Code pulls fresh on reinstall.
Update CHANGELOG, README version badge, and releases table.
2026-02-25 21:22:31 +01:00
OthmanAdi f45b39a967 fix: bump canonical SKILL.md metadata.version to 2.16.1
PR #83 correctly moved version to metadata.version but left
the stale 2.10.0 value. All IDE files had 2.16.1, canonical
was the only one still showing 2.10.0.
2026-02-25 21:15:26 +01:00
OthmanAdi af533413ca fix(skill-metadata): apply PR #83 description fix to Group C IDEs
Gemini, AdaL, Agent, Factory, Pi — no allowed-tools or version fields,
description-only update to match canonical trigger terms.
Pi name (pi-planning-with-files) and Agent license field preserved.
2026-02-25 21:06:13 +01:00
OthmanAdi 461fc525de fix(skill-metadata): apply PR #83 spec fixes to Group B IDEs
Continue, OpenClaw — no allowed-tools field so that fix doesn't apply.
- Removed top-level version field
- Updated description with trigger terms
- Added metadata.version: "2.16.1" in correct block YAML location
OpenClaw: inline JSON metadata expanded to proper block YAML,
  openclaw.os array preserved exactly.
2026-02-25 21:03:33 +01:00
OthmanAdi 8104801106 fix(skill-metadata): apply PR #83 spec fixes to Group A IDEs
Codex, Cursor, Kilocode, CodeBuddy, OpenCode — all had:
- allowed-tools as invalid YAML list → fixed to comma-separated string
- version at top-level frontmatter → moved to metadata.version
- description missing trigger terms → updated to match canonical

Each file's IDE-specific SCRIPT_DIR env var preserved exactly.
Version bumped to 2.16.1 (current release) across all.
2026-02-25 20:55:24 +01:00
OthmanAdi a8ce293833 feat: add Mastra Code support (platform #16)
- Created .mastracode/skills/planning-with-files/ with full hooks integration
  (PreToolUse, PostToolUse, Stop — native Mastra Code hook support)
- SKILL.md ships with PR #83 fixes pre-applied: comma-separated allowed-tools,
  metadata.version in standard location, enriched trigger terms
- Includes references, scripts (cross-platform), and templates
- Added docs/mastra.md installation guide (workspace + personal methods)
- Updated README: IDE table, badge, file structure, docs table, platform count
2026-02-25 20:28:49 +01:00
OthmanAdi d604849947 docs: add @popey as contributor, switch to RepoStars widget
- Added @popey to contributors table for skill metadata fixes (PR #83)
- Replaced star-history.com chart with RepoStars copper theme embed
2026-02-25 20:04:46 +01:00
Ahmad Othman Ammar Adi. 0f2a9cfba4 Merge pull request #83 from popey/improve/skill-review-optimization
feat: improve skill metadata and description for better discoverability
2026-02-25 20:01:14 +01:00
OthmanAdi d8d5002736 fix(copilot-hooks): resolve garbled characters on Windows and non-ASCII systems
PowerShell scripts (all 4):
- Add $OutputEncoding and [Console]::OutputEncoding = UTF8 before any output
- Fixes diamond replacement characters (◆) caused by PowerShell 5.x
  defaulting to UTF-16LE stdout — Copilot reads stdout as UTF-8, causing
  the byte mismatch that produces garbled output on Windows systems

Bash scripts (session-start.sh, pre-tool-use.sh):
- Use json.dumps(..., ensure_ascii=False) instead of default ensure_ascii=True
- Preserves UTF-8 characters (CJK, emojis, accented letters) in task_plan.md
  context instead of converting them to raw \uXXXX escape sequences

README:
- Move Contributors from ugly bottom section into collapsible near top
- Add full contributors table with all PR authors since v2.8.0
- Add @Hexiaopi for Issue #82 bug report
- Update version badge and releases table to v2.16.1

CHANGELOG: add [2.16.1] entry

Fixes #82 — reported by @Hexiaopi
2026-02-25 19:32:00 +01:00
Alan PopeandClaude Opus 4.6 428728f5f2 feat: improve skill metadata and description for better discoverability
Changes to planning-with-files skill:

| Area | Before | After |
|------|--------|-------|
| Description score | 0% (blocked) | 100% |
| Content score | 0% (blocked) | 100% |
| allowed-tools format | YAML list (invalid) | comma-separated string (valid) |
| metadata.version | missing | added (2.10.0) |
| trigger terms | limited | added "plan out", "break down", "organize", "track progress" |

- Fixed `allowed-tools` from YAML list to string format (was causing validation failure)
- Moved `version` from top-level frontmatter to `metadata.version` (standard location)
- Enriched description with natural trigger terms for better skill matching
- No changes to skill behaviour, templates, scripts, or content

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-24 19:44:05 +00:00
OthmanAdi d4b699ccf1 Release v2.16.0: GitHub Copilot hooks support
Added GitHub Copilot hooks integration (PR #80 by @lincolnwan)
Updated version badge and changelog
2026-02-22 21:36:20 +01:00
Ahmad Othman Ammar Adi. dde2a69913 Merge pull request #80 from lincolnwan/feature/add-copilot-hooks
Create github copilot plugin with hooks
2026-02-22 21:34:40 +01:00
Lin Wan d69eda6b31 create github copilot plugin 2026-02-22 15:03:55 +01:00
OthmanAdi 6a9effe7d7 docs: add link to experimental isolated-planning branch 2026-02-21 01:17:05 +01:00
OthmanAdi bc642b9bf6 docs: move @gydx6 to CONTRIBUTORS.md (proper location) 2026-02-21 00:37:04 +01:00
OthmanAdi f3c07ea4c7 docs: add @gydx6 to contributors, bump version to v2.15.1 2026-02-21 00:28:13 +01:00
Noob_996 3a8547ff24 fix: prevent false-positive catchup in skill-distributed scripts
Fixes session-catchup false positives in all 9 skill-distributed copies.

Changes:
- Added early return when no planning files exist in project
- Added early return when no planning update found in session
- Removed fallback branch that emitted unsynced context incorrectly

Thank you @gydx6 for the thorough bug report, detailed analysis, and clean fix across all affected files.

Fixes #78
2026-02-21 00:25:44 +01:00
Ahmad Othman Ammar Adi. 4292f000a1 Update README.md 2026-02-09 22:15:26 +01:00
OthmanAdi 245726ee5b Move closed issues/PRs badges to top section 2026-02-09 22:13:13 +01:00
OthmanAdi 70fc70b682 Add closed issues and PRs badges 2026-02-09 22:11:50 +01:00
OthmanAdi ec84b78408 Add contributors section with @codelyc 2026-02-09 22:10:13 +01:00
shmilyu e18d267d24 Add opencode scripts for planning-with-files skill (#76)
Change-Id: Id10167a8d7496f9abe615ec8038143d5d8f558a4
2026-02-09 22:07:14 +01:00
OthmanAdi cb5f10ba5f Make community builds section open by default
Show community forks and contributions immediately without requiring click to expand
2026-02-08 16:14:44 +01:00
OthmanAdi 9fc3f3ff28 Update README for v2.15.0 release
- Added /plan:status command to commands table
- Updated version badge and release table
- Listed v2.15.0 highlights: status command + OpenCode fix
2026-02-08 16:06:50 +01:00
OthmanAdi 0c1ddd21c3 Fix OpenCode compatibility - detect IDE and show helpful message
OpenCode uses different session storage (.json at ~/.local/share/opencode/) than Claude Code (.jsonl at ~/.claude/projects/). Session catchup now detects the IDE and provides a clear workaround message instead of silently failing.

- Added IDE detection (checks env vars and directory structure)
- OpenCode users get helpful message to manually read planning files
- Claude Code functionality unchanged
- Updated OpenCode docs with known limitations section

Fixes #74
2026-02-08 16:05:59 +01:00
jonthebeef a233b1b430 Add /plan:status command for quick progress check
Adds visual status display with emoji icons, phase progress tracking, and error logging count. Thanks @jonthebeef for this thoughtful contribution!
2026-02-08 16:03:28 +01:00
OthmanAdi 61e6165e2f Move Supported IDEs to top collapsible section
- Moved to top with other collapsible sections
- Removed duplicate from original location
2026-02-06 15:17:32 +01:00
OthmanAdi 4e5084cde4 Make Supported IDEs section collapsible
- Added collapsible details/summary wrapper
- Header shows platform count (14 Platforms)
- Full table and legacy note preserved inside
2026-02-06 15:14:26 +01:00
OthmanAdi 0361bf17c4 Fix IDE-specific path references in SKILL.md files
- OpenCode: Replace CLAUDE_PLUGIN_ROOT with OPENCODE_SKILL_ROOT
- Kilocode: Replace CLAUDE_PLUGIN_ROOT with KILOCODE_SKILL_ROOT
- Cursor: Replace CLAUDE_PLUGIN_ROOT with CURSOR_SKILL_ROOT
- Update docs/opencode.md with oh-my-opencode configuration guide
- Add troubleshooting section for skill loading conflicts

Fixes #73
2026-02-06 15:10:12 +01:00
OthmanAdi abc11dd858 Consolidate Versions and Session Recovery into collapsible section
- New collapsible 'Releases & Session Recovery' section at top
- Shows key version highlights in compact table
- Session recovery info condensed with pro tip
- Removed duplicate sections from bottom of README
- Cleaner, more scannable layout
2026-02-06 14:57:01 +01:00
OthmanAdi c7e3b71bb8 Move Community Forks up and make both sections collapsible
- Thank You section now collapsible with attention-grabbing header
- Community Forks moved to top, collapsible with engaging header
- Added @ mention for RioTheGreat-ai
- Linked 'Open an issue' directly to issues page
2026-02-06 14:53:27 +01:00
Ahmad Othman Ammar Adi. 8adf37c6f8 Merge pull request #72 from RioTheGreat-ai/master 2026-02-06 13:35:16 +01:00
Ahmad Othman Ammar Adi. eb27664be1 Merge pull request #70 from codelyc/master 2026-02-06 13:34:36 +01:00
RioLabs ab208d9d92 Add AgentFund to community forks/extensions 2026-02-06 04:13:27 +00:00
codelyc 7082c7f41f fix: update codebuddy paths and codex usage docs
Change-Id: I28fb0e5f6a88427370ff1bd079c4951311be5815
2026-02-05 10:59:44 +08:00
OthmanAdi 8a49fdb03a Reorder README: prioritize value proposition and core concepts
Move Why This Skill, The Problem, The Solution, Manus Principles,
Usage, Key Rules, and When to Use sections above the fold.
Move IDE tables, Documentation, Session Recovery, and Versions
to the reference section at the bottom.
Remove redundant Kilo Code Support section (already in Supported IDEs table).
2026-02-04 23:40:44 +01:00
OthmanAdi 7f73508511 Add sync script for IDE folders, fix drift across 6 IDEs (fixes #53, #47)
Added scripts/sync-ide-folders.py — a maintainer tool that syncs shared
files (templates, scripts, references) from the canonical source
(skills/planning-with-files/) to all 13 IDE-specific folders.

Features:
- Preserves each IDE's unique structure and SKILL.md frontmatter
- Handles all structural variations (flat refs, subdir refs, asset dirs)
- Supports --dry-run (preview) and --verify (CI drift detection)
- Covers .cursor, .gemini, .codex, .openclaw, .kilocode, .adal, .pi,
  .continue, .codebuddy, .factory, .agent, .opencode, .kiro

First sync fixed drift in 6 IDE folders:
- .adal, .continue, .pi: updated session-catchup.py
- .continue: updated examples.md, reference.md
- .codebuddy: added missing templates/
- .gemini, .openclaw: added missing session-catchup.py

Thanks to @back1ply for proposing the deduplication approach (#53)
and @snowbedding for requesting Anthropic-style structure (#47).
2026-02-04 23:22:44 +01:00
OthmanAdi 0225360606 Rename .moltbot/ to .openclaw/, fix clawdhub-publish leak, add .gitignore entries
- Renamed .moltbot/ directory to .openclaw/ to match the OpenClaw rebrand
  (PR #65 only renamed docs/moltbot.md but missed the IDE directory)
- Updated SKILL.md metadata from moltbot to openclaw
- Removed accidentally committed clawdhub-publish/scripts/ from tracking
- Added clawdhub-publish/ and .claude/ to .gitignore
- Added .openclaw/ to README directory tree
2026-02-04 22:16:31 +01:00
OthmanAdi 0b033eb025 Add Cursor hooks support — preToolUse, postToolUse, stop (fixes #61)
Cursor now supports hooks natively via .cursor/hooks.json. Added:
- hooks.json config with preToolUse, postToolUse, and stop hooks
- Hook scripts in bash (.sh) and PowerShell (.ps1)
- hooks.windows.json for native PowerShell users
- Rewrote docs/cursor.md — removed "hooks don't work" limitation,
  documented full hook support including auto-continuation via stop hook
- Updated README Cursor format from "Skills" to "Skills + Hooks"

The stop hook is the highlight: it checks task_plan.md completion and
uses Cursor's followup_message to auto-continue the agent if phases
are incomplete (capped at 3 retries via loop_limit).

Thanks to @sulsDotK for reporting that Cursor now supports hooks.
2026-02-04 22:03:37 +01:00
OthmanAdi 9ec4d413b6 Fix incorrect plugin install command in README (fixes #59)
Changed from the non-existent `claude plugins install` command to the
correct slash command format: `/plugin marketplace add` followed by
`/plugin install`. Matches docs/installation.md and docs/troubleshooting.md.
2026-02-04 21:37:09 +01:00
OthmanAdi b96b42a9e5 Fix stop hook error, docs inconsistency, add Plan Cascade (fixes #68, #69)
- check-complete.sh/.ps1: Always exit 0 — incomplete task is a normal
  state, not an error. Uses stdout for informational status reporting.
  Fixes stop hook error in Claude Code. (#68)
- README.md, docs/quickstart.md: Clarify that the AI creates planning
  files (not the user manually). Align all docs on workflow. (#69)
- README.md: Add Plan Cascade by @Taoidle to Community Forks (#63)
- Updated all 21 check-complete script copies across IDE folders
2026-02-04 21:30:07 +01:00
OthmanAdi 16fd096f4f Fix check-complete scripts and kilocode docs (fixes #45, #62)
- check-complete.sh/.ps1: Add fallback for [complete] inline bracket
  status format in addition to existing **Status:** bold format
- Updated all 21 script copies across IDE folders
- docs/kilocode.md: Remove all references to non-existent
  .kilocode/rules/ directory (migrated to skills/ in v2.10.0)
- README.md: Update Kilo Code section to reference .kilocode/skills/
2026-02-04 21:22:53 +01:00
OthmanAdi 727fdfb72c Release v2.14.0 - Pi Agent support, Codex fix, OpenClaw docs
- Add Pi Agent integration (PR #67 by @ttttmr)
- Fix Codex skill path references (PR #66 by @codelyc)
- Update Moltbot docs to OpenClaw (PR #65 by @AZLabsAI, fixes #64)
- Update version badge to v2.14.0
- Update README: OpenClaw branding, version table
- Update CHANGELOG with v2.14.0 entry
2026-02-04 20:31:07 +01:00
Ahmad Othman Ammar Adi. b8274d23f8 Merge pull request #67 from ttttmr/master
Add Pi Agent support
2026-02-04 17:44:48 +01:00
Ahmad Othman Ammar Adi. 60e06093be Merge pull request #66 from codelyc/master
Fix codex skill path references
2026-02-04 17:40:52 +01:00
Ahmad Othman Ammar Adi. 7230d7f9d3 Merge pull request #65 from AZLabsAI/fix/moltbot-docs-openclaw-rename
docs: update moltbot.md to use OpenClaw naming and paths
2026-02-04 17:38:58 +01:00
linyuchiandClaude Sonnet 4.5 672e2515c2 Fix codex skill path references
- Update SKILL.md to use correct paths (~/.codex/skills/planning-with-files/)
- Replace CLAUDE_PLUGIN_ROOT references with absolute paths
- Add missing template files (findings.md, progress.md, task_plan.md)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Change-Id: I5b59bc1f54473f8af8c884b7c0cc1683de93a7ad
2026-02-04 19:32:31 +08:00
ttttmr 1089d65c60 Add Pi Agent support 2026-02-04 19:26:21 +08:00
TH33_ORACL3andCursor 28e89aae11 docs: rename moltbot.md to openclaw.md
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-03 19:21:37 +02:00
TH33_ORACL3andCursor cbf393a516 docs: update moltbot.md to use OpenClaw naming and paths
The product has been renamed from Moltbot to OpenClaw. This commit updates:

- Title and website link (molt.bot → openclaw.ai)
- Skills directory paths (~/.clawdbot/ → ~/.openclaw/)
- Config file path (moltbot.json → openclaw.json)
- CLI commands (moltbot → openclaw)
- All references to the product name

Fixes #64

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-03 19:20:33 +02:00
OthmanAdi c1a24568cd Update version badge to v2.13.0 2026-01-27 22:22:58 +01:00
160 changed files with 4699 additions and 13864 deletions
-175
View File
@@ -1,175 +0,0 @@
---
name: planning-with-files
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
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
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Templates
Copy these templates to start:
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
## Scripts
Helper scripts for automation (execute via bash):
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py` — Recover context from previous session
To use scripts:
```bash
bash scripts/init-session.sh
bash scripts/check-complete.sh
python scripts/session-catchup.py $(pwd)
```
## Advanced Topics
- **Manus Principles:** See [references/reference.md](references/reference.md)
- **Real Examples:** See [references/examples.md](references/examples.md)
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| Use TodoWrite for persistence | Create task_plan.md file |
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in skill directory | Create files in your project |
@@ -1,202 +0,0 @@
# 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
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -1,218 +0,0 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -1,42 +0,0 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
}
@@ -1,44 +0,0 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
fi
@@ -1,34 +0,0 @@
#!/bin/bash
set -euo pipefail
missing=0
require_file() {
local path="$1"
if [ ! -f "$path" ]; then
echo "Missing: $path"
missing=1
fi
}
require_file ".continue/prompts/planning-with-files.prompt"
require_file ".continue/skills/planning-with-files/SKILL.md"
require_file ".continue/skills/planning-with-files/examples.md"
require_file ".continue/skills/planning-with-files/reference.md"
require_file ".continue/skills/planning-with-files/scripts/init-session.sh"
require_file ".continue/skills/planning-with-files/scripts/init-session.ps1"
require_file ".continue/skills/planning-with-files/scripts/check-complete.sh"
require_file ".continue/skills/planning-with-files/scripts/check-complete.ps1"
require_file ".continue/skills/planning-with-files/scripts/session-catchup.py"
if [ "$missing" -ne 0 ]; then
exit 1
fi
case ".continue/prompts/planning-with-files.prompt" in
*.prompt) ;;
*) echo "Prompt file must end with .prompt"; exit 1 ;;
esac
echo "Continue integration files look OK."
@@ -1,278 +0,0 @@
#!/usr/bin/env python3
"""
Session Catchup Script for planning-with-files
Session-agnostic scanning: finds the most recent planning file update across
ALL sessions, then collects all conversation from that point forward through
all subsequent sessions until now.
Usage: python3 session-catchup.py [project-path]
"""
import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
def get_project_dir(project_path: str) -> Path:
"""Convert project path to Claude's storage path format."""
sanitized = project_path.replace('/', '-')
if not sanitized.startswith('-'):
sanitized = '-' + sanitized
sanitized = sanitized.replace('_', '-')
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def get_session_first_timestamp(session_file: Path) -> Optional[str]:
"""Get the timestamp of the first message in a session."""
try:
with open(session_file, 'r') as f:
for line in f:
try:
data = json.loads(line)
ts = data.get('timestamp')
if ts:
return ts
except:
continue
except:
pass
return None
def scan_for_planning_update(session_file: Path) -> Tuple[int, Optional[str]]:
"""
Quickly scan a session file for planning file updates.
Returns (line_number, filename) of last update, or (-1, None) if none found.
"""
last_update_line = -1
last_update_file = None
try:
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
if '"Write"' not in line and '"Edit"' not in line:
continue
try:
data = json.loads(line)
if data.get('type') != 'assistant':
continue
content = data.get('message', {}).get('content', [])
if not isinstance(content, list):
continue
for item in content:
if item.get('type') != 'tool_use':
continue
tool_name = item.get('name', '')
if tool_name not in ('Write', 'Edit'):
continue
file_path = item.get('input', {}).get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = line_num
last_update_file = pf
break
except json.JSONDecodeError:
continue
except Exception:
pass
return last_update_line, last_update_file
def extract_messages_from_session(session_file: Path, after_line: int = -1) -> List[Dict]:
"""
Extract conversation messages from a session file.
If after_line >= 0, only extract messages after that line.
If after_line < 0, extract all messages.
"""
result = []
try:
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
if after_line >= 0 and line_num <= after_line:
continue
try:
msg = json.loads(line)
except json.JSONDecodeError:
continue
msg_type = msg.get('type')
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
if content and isinstance(content, str):
# Skip system/command messages
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({
'role': 'user',
'content': content,
'line': line_num,
'session': session_file.stem[:8]
})
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Bash':
cmd = tool_input.get('command', '')[:80]
tool_uses.append(f"Bash: {cmd}")
elif tool_name == 'AskUserQuestion':
tool_uses.append("AskUserQuestion")
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'tools': tool_uses,
'line': line_num,
'session': session_file.stem[:8]
})
except Exception:
pass
return result
def main():
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
project_dir = get_project_dir(project_path)
if not project_dir.exists():
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 2:
return
# Skip the current session (most recently modified = index 0)
previous_sessions = sessions[1:]
# Find the most recent planning file update across ALL previous sessions
# Sessions are sorted newest first, so we scan in order
update_session = None
update_line = -1
update_file = None
update_session_idx = -1
for idx, session in enumerate(previous_sessions):
line, filename = scan_for_planning_update(session)
if line >= 0:
update_session = session
update_line = line
update_file = filename
update_session_idx = idx
break
if not update_session:
# No planning file updates found in any previous session
return
# Collect ALL messages from the update point forward, across all sessions
all_messages = []
# 1. Get messages from the session with the update (after the update line)
messages_from_update_session = extract_messages_from_session(update_session, after_line=update_line)
all_messages.extend(messages_from_update_session)
# 2. Get ALL messages from sessions between update_session and current
# These are sessions[1:update_session_idx] (newer than update_session)
intermediate_sessions = previous_sessions[:update_session_idx]
# Process from oldest to newest for correct chronological order
for session in reversed(intermediate_sessions):
messages = extract_messages_from_session(session, after_line=-1) # Get all messages
all_messages.extend(messages)
if not all_messages:
return
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Last planning update: {update_file} in session {update_session.stem[:8]}...")
sessions_covered = update_session_idx + 1
if sessions_covered > 1:
print(f"Scanning {sessions_covered} sessions for unsynced context")
print(f"Unsynced messages: {len(all_messages)}")
print("\n--- UNSYNCED CONTEXT ---")
# Show up to 100 messages
MAX_MESSAGES = 100
if len(all_messages) > MAX_MESSAGES:
print(f"(Showing last {MAX_MESSAGES} of {len(all_messages)} messages)\n")
messages_to_show = all_messages[-MAX_MESSAGES:]
else:
messages_to_show = all_messages
current_session = None
for msg in messages_to_show:
# Show session marker when it changes
if msg.get('session') != current_session:
current_session = msg.get('session')
print(f"\n[Session: {current_session}...]")
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
print("\n--- RECOMMENDED ---")
print("1. Run: git diff --stat")
print("2. Read: task_plan.md, progress.md, findings.md")
print("3. Update planning files based on above context")
print("4. Continue with task")
if __name__ == '__main__':
main()
@@ -1,95 +0,0 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -1,114 +0,0 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -1,132 +0,0 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
-127
View File
@@ -1,127 +0,0 @@
---
name: planning-with-files
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
license: MIT
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## Core Principle
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## Quick Start
Before ANY complex task, create these three files:
1. **task_plan.md** — Track phases and progress
2. **findings.md** — Store research and discoveries
3. **progress.md** — Session log and test results
See references/ for starting templates.
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
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
```
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Templates
- references/task_plan.md — Phase tracking template
- references/findings.md — Research storage template
- references/progress.md — Session logging template
## Advanced Topics
- **Manus Principles:** See references.md for complete context engineering patterns
- **Real Examples:** See examples.md for practical implementations
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
---
**This pattern is why Manus went from launch to $2B acquisition in 8 months.**
@@ -1,202 +0,0 @@
# 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
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -1,218 +0,0 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -1,95 +0,0 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -1,114 +0,0 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -1,132 +0,0 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
+1 -1
View File
@@ -9,7 +9,7 @@
"name": "planning-with-files",
"source": "./",
"description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Now with hooks integration.",
"version": "2.0.0"
"version": "2.30.0"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "2.11.0",
"version": "2.30.0",
"description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Works with Claude Code, Kiro, Clawd CLI, Gemini CLI, Cursor, Continue, and 11+ AI coding assistants.",
"author": {
"name": "OthmanAdi",
@@ -1,248 +0,0 @@
---
name: planning-with-files
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
- WebFetch
- WebSearch
hooks:
PreToolUse:
- matcher: "Write|Edit|Bash|Read|Glob|Grep"
hooks:
- type: command
command: "cat task_plan.md 2>/dev/null | head -30 || true"
PostToolUse:
- matcher: "Write|Edit"
hooks:
- type: command
command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
Stop:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
IS_WINDOWS=1
else
UNAME_S="$(uname -s 2>/dev/null || echo '')"
case "$UNAME_S" in
CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
esac
fi
if [ "$IS_WINDOWS" -eq 1 ]; then
if command -v pwsh >/dev/null 2>&1; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
else
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
fi
else
sh "$SCRIPT_DIR/check-complete.sh"
fi
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## FIRST: Check for Previous Session (v2.2.0)
**Before starting work**, check for unsynced context from a previous session:
```bash
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
```
```powershell
# Windows PowerShell
python "$env:USERPROFILE\.codebuddy\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
```
If catchup report shows unsynced context:
1. Run `git diff --stat` to see actual code changes
2. Read current planning files
3. Update planning files based on catchup + git diff
4. Then proceed with task
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
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
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Templates
Copy these templates to start:
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
## Scripts
Helper scripts for automation:
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py` — Recover context from previous session (v2.2.0)
## Advanced Topics
- **Manus Principles:** See [reference.md](reference.md)
- **Real Examples:** See [examples.md](examples.md)
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| Use TodoWrite for persistence | Create task_plan.md file |
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in skill directory | Create files in your project |
@@ -1,95 +0,0 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -1,114 +0,0 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -1,132 +0,0 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
@@ -1,202 +0,0 @@
# 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
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -1,218 +0,0 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -1,42 +0,0 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
}
@@ -1,44 +0,0 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
fi
@@ -1,120 +0,0 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -1,120 +0,0 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
-248
View File
@@ -1,248 +0,0 @@
---
name: planning-with-files
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
- WebFetch
- WebSearch
hooks:
PreToolUse:
- matcher: "Write|Edit|Bash|Read|Glob|Grep"
hooks:
- type: command
command: "cat task_plan.md 2>/dev/null | head -30 || true"
PostToolUse:
- matcher: "Write|Edit"
hooks:
- type: command
command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
Stop:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
IS_WINDOWS=1
else
UNAME_S="$(uname -s 2>/dev/null || echo '')"
case "$UNAME_S" in
CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
esac
fi
if [ "$IS_WINDOWS" -eq 1 ]; then
if command -v pwsh >/dev/null 2>&1; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
else
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
fi
else
sh "$SCRIPT_DIR/check-complete.sh"
fi
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## FIRST: Check for Previous Session (v2.2.0)
**Before starting work**, check for unsynced context from a previous session:
```bash
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
```
```powershell
# Windows PowerShell
python "$env:USERPROFILE\.codex\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
```
If catchup report shows unsynced context:
1. Run `git diff --stat` to see actual code changes
2. Read current planning files
3. Update planning files based on catchup + git diff
4. Then proceed with task
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
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
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Templates
Copy these templates to start:
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
## Scripts
Helper scripts for automation:
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py` — Recover context from previous session (v2.2.0)
## Advanced Topics
- **Manus Principles:** See [reference.md](reference.md)
- **Real Examples:** See [examples.md](examples.md)
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| Use TodoWrite for persistence | Create task_plan.md file |
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in skill directory | Create files in your project |
@@ -1,95 +0,0 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -1,114 +0,0 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -1,132 +0,0 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
@@ -1,202 +0,0 @@
# 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
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -1,218 +0,0 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -1,42 +0,0 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
}
@@ -1,44 +0,0 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
fi
@@ -1,120 +0,0 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -1,120 +0,0 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
@@ -1,34 +0,0 @@
---
name: planning-with-files
description: 启动“Planning with Files”三文件工作流(task_plan.md / findings.md / progress.md)
invokable: true
---
你将采用“Planning with Files”模式来完成接下来的工作:把计划、发现与进度持久化到 3 个 Markdown 文件里,以避免上下文漂移与遗忘。
## 目标
- 在项目根目录确保存在:task_plan.md、findings.md、progress.md
- 所有关键决策、研究结论、错误与修复路径必须写入文件
- 每完成一个阶段就更新 task_plan.md 的状态
## 工作步骤
1. 检查项目根目录是否已有 task_plan.md / findings.md / progress.md
2. 如果不存在,先创建它们(可直接运行初始化脚本,或在 IDE 里新建同名文件):
- macOS/Linux:bash .continue/skills/planning-with-files/scripts/init-session.sh
- Windows:powershell -ExecutionPolicy Bypass -File .continue/skills/planning-with-files/scripts/init-session.ps1
3. 读取 task_plan.md,补全:
- Goal(1 句话)
- Phases(3-7 个阶段,带 Status: pending / in_progress / complete)
- Key Questions(需要回答的关键问题)
4. 执行任务时遵守:
- 每 2 次“查看/搜索/浏览”后,立刻把发现写入 findings.md
- 每次重要决策前,先读取 task_plan.md 刷新目标
- 任何错误都记录在 task_plan.md 的 Errors Encountered,并写清楚尝试次数与解决方式
5. 持续把本次会话的行动与验证结果写入 progress.md(包括命令、测试、输出)
## 输出要求
- 你的回答优先引用这些文件中的最新内容(而不是依赖聊天记忆)
- 任务结束前,确保所有阶段均为 complete(或明确说明未完成原因与后续)
@@ -1,83 +0,0 @@
---
name: planning-with-files
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## FIRST: Check for Previous Session (v2.2.0)
Before starting work, check for unsynced context from a previous session:
```bash
python3 .continue/skills/planning-with-files/scripts/session-catchup.py "$(pwd)" || python .continue/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
```
If catchup report shows unsynced context:
1. Run `git diff --stat` to see actual code changes
2. Read current planning files
3. Update planning files based on catchup + git diff
4. Then proceed with task
## Quick Start
Before any complex task:
1. Create `task_plan.md`, `findings.md`, `progress.md` in your project root
2. If they don't exist yet, initialize them using:
- macOS/Linux: `bash .continue/skills/planning-with-files/scripts/init-session.sh`
- Windows: `powershell -ExecutionPolicy Bypass -File .continue/skills/planning-with-files/scripts/init-session.ps1`
3. Re-read `task_plan.md` before major decisions
4. Update `task_plan.md` after each phase completes
5. Write discoveries to `findings.md` (especially after web/search/image/PDF viewing)
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After any discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`.
### 2. The 2-Action Rule
After every 2 view/browser/search operations, save key findings to text files.
### 3. Read Before Decide
Before major decisions, read `task_plan.md` to refresh goals.
### 4. Update After Act
After completing any phase, update statuses and log errors in `task_plan.md`.
### 5. Log ALL Errors
Every error goes in the plan file so you don't repeat it.
### 6. Never Repeat Failures
If an action failed, the next action must be different.
## References
- [reference.md](reference.md)
- [examples.md](examples.md)
@@ -1,202 +0,0 @@
# 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
Always read your plan before major decisions:
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -1,218 +0,0 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After any discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- Single-action execution: one tool call per turn
- Plan is required: always know goal, current phase, remaining phases
- Files are memory: context is volatile; filesystem is persistent
- Never repeat failures: if action failed, next action must be different
- Communication is a tool: message types include info, ask, result
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -1,42 +0,0 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
}
@@ -1,44 +0,0 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
fi
@@ -1,120 +0,0 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -1,120 +0,0 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
@@ -1,203 +0,0 @@
#!/usr/bin/env python3
"""
Session Catchup Script for planning-with-files
Analyzes the previous session to find unsynced context after the last
planning file update. Designed to run on SessionStart.
Usage: python3 session-catchup.py [project-path]
"""
import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from datetime import datetime
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
def get_project_dir(project_path: str) -> Path:
"""Convert project path to Claude's storage path format."""
sanitized = project_path.replace('/', '-')
if not sanitized.startswith('-'):
sanitized = '-' + sanitized
sanitized = sanitized.replace('_', '-')
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
"""
last_update_line = -1
last_update_file = None
for msg in messages:
msg_type = msg.get('type')
if msg_type == 'assistant':
content = msg.get('message', {}).get('content', [])
if isinstance(content, list):
for item in content:
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
if msg['_line_num'] <= after_line:
continue
msg_type = msg.get('type')
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
if content and isinstance(content, str):
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Bash':
cmd = tool_input.get('command', '')[:80]
tool_uses.append(f"Bash: {cmd}")
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'tools': tool_uses,
'line': msg['_line_num']
})
return result
def main():
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
project_dir = get_project_dir(project_path)
has_planning_files = any(
Path(project_path, f).exists() for f in PLANNING_FILES
)
if not project_dir.exists():
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if not target_session:
return
messages = parse_session_messages(target_session)
last_update_line, last_update_file = find_last_planning_update(messages)
if last_update_line < 0:
messages_after = extract_messages_after(messages, len(messages) - 30)
else:
messages_after = extract_messages_after(messages, last_update_line)
if not messages_after:
return
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
if last_update_line >= 0:
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
else:
print("No planning file updates found in previous session")
print("\n--- UNSYNCED CONTEXT ---")
for msg in messages_after[-15:]:
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
print("\n--- RECOMMENDED ---")
print("1. Run: git diff --stat")
print("2. Read: task_plan.md, progress.md, findings.md")
print("3. Update planning files based on above context")
print("4. Continue with task")
if __name__ == '__main__':
main()
-248
View File
@@ -1,248 +0,0 @@
---
name: planning-with-files
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
- WebFetch
- WebSearch
hooks:
PreToolUse:
- matcher: "Write|Edit|Bash|Read|Glob|Grep"
hooks:
- type: command
command: "cat task_plan.md 2>/dev/null | head -30 || true"
PostToolUse:
- matcher: "Write|Edit"
hooks:
- type: command
command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
Stop:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
IS_WINDOWS=1
else
UNAME_S="$(uname -s 2>/dev/null || echo '')"
case "$UNAME_S" in
CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
esac
fi
if [ "$IS_WINDOWS" -eq 1 ]; then
if command -v pwsh >/dev/null 2>&1; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
else
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
fi
else
sh "$SCRIPT_DIR/check-complete.sh"
fi
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## FIRST: Check for Previous Session (v2.2.0)
**Before starting work**, check for unsynced context from a previous session:
```bash
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
```
```powershell
# Windows PowerShell
python "$env:USERPROFILE\.cursor\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
```
If catchup report shows unsynced context:
1. Run `git diff --stat` to see actual code changes
2. Read current planning files
3. Update planning files based on catchup + git diff
4. Then proceed with task
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
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
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Templates
Copy these templates to start:
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
## Scripts
Helper scripts for automation:
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py` — Recover context from previous session (v2.2.0)
## Advanced Topics
- **Manus Principles:** See [reference.md](reference.md)
- **Real Examples:** See [examples.md](examples.md)
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| Use TodoWrite for persistence | Create task_plan.md file |
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in skill directory | Create files in your project |
@@ -1,202 +0,0 @@
# 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
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -1,218 +0,0 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -1,95 +0,0 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -1,114 +0,0 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -1,132 +0,0 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
@@ -1,152 +0,0 @@
---
name: planning-with-files
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## Core Principle
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## Quick Start
Before ANY complex task, create these three files:
1. **task_plan.md** — Track phases and progress
2. **findings.md** — Store research and discoveries
3. **progress.md** — Session log and test results
See [templates/](./templates/) for starting templates.
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
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
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
## Advanced Topics
- **Manus Principles:** See [references.md](./references.md)
- **Real Examples:** See [examples.md](./examples.md)
---
**This pattern is why Manus went from launch to $2B acquisition in 8 months.**
@@ -1,202 +0,0 @@
# 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
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -1,218 +0,0 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -1,95 +0,0 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -1,114 +0,0 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -1,132 +0,0 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
-176
View File
@@ -1,176 +0,0 @@
---
name: planning-with-files
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## Important: Where Files Go
- **Templates** are in this skill's `templates/` folder
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
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
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Templates
Copy these templates to start:
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
## Scripts
Helper scripts for automation:
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
## Advanced Topics
- **Manus Principles:** See [references/reference.md](references/reference.md)
- **Real Examples:** See [references/examples.md](references/examples.md)
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in skill directory | Create files in your project |
@@ -1,202 +0,0 @@
# 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
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -1,218 +0,0 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -1,42 +0,0 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
}
@@ -1,44 +0,0 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
fi
@@ -1,120 +0,0 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -1,120 +0,0 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
@@ -1,95 +0,0 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -1,114 +0,0 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -1,132 +0,0 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
+11
View File
@@ -21,6 +21,17 @@ notes.md
!examples/**/*.md
!**/templates/*.md
# ClawHub publish/upload folders (managed separately)
clawdhub-publish/
clawhub-upload/
clawhub-changelog.txt
skill-submission-targets.txt
# Claude session files
.claude/
# Keep the skill folder clean
*.log
*.tmp
WIKI_HOME_PAGE.md
DISCUSSION_2_CONTENT.md
@@ -1,248 +0,0 @@
---
name: planning-with-files
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
- WebFetch
- WebSearch
hooks:
PreToolUse:
- matcher: "Write|Edit|Bash|Read|Glob|Grep"
hooks:
- type: command
command: "cat task_plan.md 2>/dev/null | head -30 || true"
PostToolUse:
- matcher: "Write|Edit"
hooks:
- type: command
command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
Stop:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
IS_WINDOWS=1
else
UNAME_S="$(uname -s 2>/dev/null || echo '')"
case "$UNAME_S" in
CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
esac
fi
if [ "$IS_WINDOWS" -eq 1 ]; then
if command -v pwsh >/dev/null 2>&1; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
else
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
fi
else
sh "$SCRIPT_DIR/check-complete.sh"
fi
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## FIRST: Check for Previous Session (v2.2.0)
**Before starting work**, check for unsynced context from a previous session:
```bash
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
```
```powershell
# Windows PowerShell
python "$env:USERPROFILE\.kilocode\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
```
If catchup report shows unsynced context:
1. Run `git diff --stat` to see actual code changes
2. Read current planning files
3. Update planning files based on catchup + git diff
4. Then proceed with task
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
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
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Templates
Copy these templates to start:
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
## Scripts
Helper scripts for automation:
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py` — Recover context from previous session (v2.2.0)
## Advanced Topics
- **Manus Principles:** See [reference.md](reference.md)
- **Real Examples:** See [examples.md](examples.md)
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| Use TodoWrite for persistence | Create task_plan.md file |
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in skill directory | Create files in your project |
@@ -1,202 +0,0 @@
# 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
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -1,218 +0,0 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -1,95 +0,0 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -1,114 +0,0 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -1,132 +0,0 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
-42
View File
@@ -1,42 +0,0 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
}
-44
View File
@@ -1,44 +0,0 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
fi
-120
View File
@@ -1,120 +0,0 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
-120
View File
@@ -1,120 +0,0 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
-71
View File
@@ -1,71 +0,0 @@
# Planning Rules
Critical rules for effective file-based planning.
## Rule 1: Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
## Rule 2: The 2-Action Rule
After every 2 view/browser/search operations, IMMEDIATELY save key findings to `findings.md`.
This prevents visual/multimodal information from being lost.
## Rule 3: Read Before Decide
Before major decisions, read `task_plan.md`. This keeps goals in your attention window.
## Rule 4: Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
## Rule 5: Log ALL Errors
Every error goes in the plan file with this format:
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
## Rule 6: Never Repeat Failures
If an action failed, the next action must be different. Track what you tried and mutate the approach.
## The 3-Strike Error Protocol
```
ATTEMPT 1: Diagnose & Fix
→ Read error carefully
→ Identify root cause
→ Apply targeted fix
ATTEMPT 2: Alternative Approach
→ Same error? Try different method
→ 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
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
-88
View File
@@ -1,88 +0,0 @@
# Planning File Templates
Copy these templates to your project root when starting complex tasks.
## task_plan.md Template
```markdown
# Task Plan
## Goal
[One sentence describing the end state]
## Current Phase
Phase X: [Name] - [Status]
## Phases
### Phase 1: [Name]
**Status:** pending | in_progress | complete
- [ ] Step 1
- [ ] Step 2
### Phase 2: [Name]
**Status:** pending
- [ ] Step 1
- [ ] Step 2
## Key Questions
- Question 1?
- Question 2?
## Decisions Made
| Decision | Rationale | Date |
|----------|-----------|------|
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
```
## findings.md Template
```markdown
# Findings
## Requirements
- Requirement 1
- Requirement 2
## Research Findings
### [Topic 1]
- Finding 1
- Finding 2
## Technical Decisions
| Decision | Options Considered | Chosen | Why |
|----------|-------------------|--------|-----|
## Resources
- [Resource 1](url)
- [Resource 2](url)
```
## progress.md Template
```markdown
# Progress Log
## Session: [Date]
**Phase:** [Current phase]
**Start Time:** [Time]
### Actions Taken
1. Action 1
2. Action 2
### Files Modified
- `file1.js` — Added feature X
- `file2.py` — Fixed bug Y
### Test Results
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
### Error Log
| Time | Error | Attempt | Resolution |
|------|-------|---------|------------|
```
-43
View File
@@ -1,43 +0,0 @@
# Planning with Files Workflow
Use persistent markdown files as your "working memory on disk" — the Manus pattern that made a $2B acquisition.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## Required Files
Create these three files in your project root before starting complex tasks:
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Quick Start
1. **Create `task_plan.md`** with goal, phases, and status tracking
2. **Create `findings.md`** for research and technical decisions
3. **Create `progress.md`** for session logging
4. **Re-read plan before decisions** — keeps goals in attention
5. **Update after each phase** — mark complete, log errors
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
@@ -1,180 +0,0 @@
---
name: planning-with-files
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
homepage: https://github.com/OthmanAdi/planning-with-files
user-invocable: true
metadata: {"moltbot":{"os":["darwin","linux","win32"]}}
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## Important: Where Files Go
- **Templates** are in this skill's `templates/` folder
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
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
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Templates
Copy these templates to start:
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
## Scripts
Helper scripts for automation:
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
## Advanced Topics
- **Manus Principles:** See [references/reference.md](references/reference.md)
- **Real Examples:** See [references/examples.md](references/examples.md)
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in skill directory | Create files in your project |
@@ -1,202 +0,0 @@
# 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
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -1,218 +0,0 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -1,42 +0,0 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
}
@@ -1,44 +0,0 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
fi
@@ -1,120 +0,0 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -1,120 +0,0 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
@@ -1,95 +0,0 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -1,114 +0,0 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -1,132 +0,0 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
@@ -1,248 +0,0 @@
---
name: planning-with-files
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
- WebFetch
- WebSearch
hooks:
PreToolUse:
- matcher: "Write|Edit|Bash|Read|Glob|Grep"
hooks:
- type: command
command: "cat task_plan.md 2>/dev/null | head -30 || true"
PostToolUse:
- matcher: "Write|Edit"
hooks:
- type: command
command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
Stop:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
IS_WINDOWS=1
else
UNAME_S="$(uname -s 2>/dev/null || echo '')"
case "$UNAME_S" in
CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
esac
fi
if [ "$IS_WINDOWS" -eq 1 ]; then
if command -v pwsh >/dev/null 2>&1; then
pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
else
powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
sh "$SCRIPT_DIR/check-complete.sh"
fi
else
sh "$SCRIPT_DIR/check-complete.sh"
fi
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## FIRST: Check for Previous Session (v2.2.0)
**Before starting work**, check for unsynced context from a previous session:
```bash
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
```
```powershell
# Windows PowerShell
python "$env:USERPROFILE\.opencode\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
```
If catchup report shows unsynced context:
1. Run `git diff --stat` to see actual code changes
2. Read current planning files
3. Update planning files based on catchup + git diff
4. Then proceed with task
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
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
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Templates
Copy these templates to start:
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
## Scripts
Helper scripts for automation:
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py` — Recover context from previous session (v2.2.0)
## Advanced Topics
- **Manus Principles:** See [reference.md](reference.md)
- **Real Examples:** See [examples.md](examples.md)
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| Use TodoWrite for persistence | Create task_plan.md file |
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in skill directory | Create files in your project |
@@ -1,202 +0,0 @@
# 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
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -1,218 +0,0 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -1,95 +0,0 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -1,114 +0,0 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -1,132 +0,0 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
+339
View File
@@ -2,6 +2,345 @@
All notable changes to this project will be documented in this file.
## [2.30.0] - 2026-04-03
### Changed
- **Migrate from `${CLAUDE_PLUGIN_ROOT}` to `${CLAUDE_SKILL_DIR}`** in main SKILL.md
- Stop hook, session-catchup path, and templates path now use `${CLAUDE_SKILL_DIR}` (added in Claude Code v2.1.69)
- 3-level fallback chain for backward compatibility: `CLAUDE_SKILL_DIR` -> `CLAUDE_PLUGIN_ROOT` -> hardcoded path
- Default fallback path updated from `.claude/plugins/planning-with-files` to `.claude/skills/planning-with-files` (matches `npx skills add` install location)
- Fixes path resolution failures on Windows and Linux (related to #32)
### Restructured
- **IDE-specific configurations moved to dedicated branches**
- Master branch now contains only the core skill, templates, scripts, and docs
- Each IDE has its own branch: `ide/cursor`, `ide/copilot`, `ide/gemini`, `ide/kiro`, `ide/codex`, `ide/mastra`, `ide/codebuddy`, `ide/factory`, `ide/opencode`, `ide/continue`, `ide/pi-agent`
- README updated with branch reference table
- Reduces master branch clutter and makes per-IDE maintenance independent
---
## [2.29.0] - 2026-03-24
### Added
- **Analytics workflow template** (PR #115 by @mvanhorn, addresses #103)
- New `--template analytics` flag on `init-session.sh` and `init-session.ps1`
- `templates/analytics_task_plan.md` with 4 analytics-specific phases: Data Discovery, Exploratory Analysis, Hypothesis Testing, Synthesis
- `templates/analytics_findings.md` with Data Sources table, Hypothesis Log, Query Results, and Statistical Findings sections
- Analytics-specific `progress.md` generates a Query Log table instead of Test Results
- Default behavior unchanged; existing users are not affected
### Usage
```bash
./scripts/init-session.sh --template analytics my-project
```
### Thanks
- @mvanhorn (Matt Van Horn) for implementing the analytics template that @sedlukha requested in #103
---
## [2.28.0] - 2026-03-22
### Added
- **Traditional Chinese (zh-TW) skill variant** (PR #113 by @waynelee2048)
- Fully translated SKILL.md, templates, and scripts under `skills/planning-with-files-zht/`
- Localized hooks, check-complete, init-session, and session-catchup scripts
### Thanks
- @waynelee2048 for the Traditional Chinese translation
---
## [2.27.0] - 2026-03-20
### Added
- **Kiro Agent Skill support** (PR #112 by @EListenX)
- Full `.kiro/skills/planning-with-files/` layout with SKILL.md, bootstrap scripts, templates, references
- Bootstrap creates `.kiro/plan/` for planning files and `.kiro/steering/planning-context.md` with `#[[file:]]` live references
- Includes session-catchup.py and check-complete scripts adapted for Kiro's `.kiro/plan/` path
- Replaces the old `.kiro/scripts/` and `.kiro/steering/` approach with proper Agent Skill format
### Changed
- Updated `scripts/sync-ide-folders.py` to skip `.kiro` (Kiro uses its own skill layout)
- Rewrote `docs/kiro.md` to reflect new Agent Skill approach
### Thanks
- @EListenX (Yi Chenxi) for the thorough Kiro integration with proper Agent Skill format
---
## [2.23.0] - 2026-03-16
### Fixed
- **Session catchup not working after `/clear`** (Issue #106 by @tony-stark-eth)
- Root cause: No hook fired on session start to remind the agent about existing planning files. After `/clear`, the agent started fresh with no awareness of the active plan.
- Added `UserPromptSubmit` hook across all 7 IDE SKILL.md files. When `task_plan.md` exists, the hook injects a directive to read all three planning files before proceeding. This fires on every user message, ensuring the agent always knows about active plans even after `/clear` or context compaction.
- Strengthened SKILL.md "FIRST" section: now explicitly says to read all three files immediately, not just run session catchup.
- **Progress not updating consistently** (Issue #106)
- Root cause: `PostToolUse` hook message only mentioned `task_plan.md`, never `progress.md`. The agent was never reminded to log what it did.
- Changed PostToolUse message across all 7 IDE SKILL.md files and both Copilot hook scripts to lead with "Update progress.md with what you just did."
- Added `if [ -f task_plan.md ]` guard so the reminder only fires when a plan is active.
- **Post-plan additions not tracked** (Issue #106)
- Root cause: When all phases were complete, `check-complete` scripts reported "ALL PHASES COMPLETE" with no guidance about continuing. The agent had no reason to add new work to the plan.
- Updated `check-complete.sh` and `check-complete.ps1`: completion message now says "If the user has additional work, add new phases to task_plan.md before starting."
- Updated Copilot `agent-stop` scripts to output continuation context even when all phases are complete (previously returned empty `{}`).
- Added Critical Rule #7 ("Continue After Completion") to canonical SKILL.md body.
### Changed
- Version bumped to 2.23.0 across all 7 IDE SKILL.md files, plugin.json, and marketplace.json
### Thanks
- @tony-stark-eth for the detailed bug report covering all three symptoms (Issue #106)
---
## [2.22.0] - 2026-03-06
### Added
- **Formal benchmark results** — skill evaluated using Anthropic's skill-creator framework
- 10 parallel subagents, 5 diverse task types, 30 objectively verifiable assertions
- with_skill: **96.7% pass rate** (29/30); without_skill: 6.7% (2/30) — delta: +90 percentage points
- 3 blind A/B comparisons: with_skill wins 3/3 (100%), avg score 10.0/10 vs 6.8/10
- Full methodology in [docs/evals.md](docs/evals.md)
- **Technical article** — [docs/article.md](docs/article.md): full write-up of the security analysis, fix, and eval methodology
- **README badges** — Benchmark (96.7% pass rate), A/B Verified (3/3 wins), Security Verified
- **README Benchmark Results section** — key numbers visible at a glance
### Changed
- `marketplace.json` version corrected to track current release (was stuck at 2.0.0)
## [2.21.0] - 2026-03-05
### Security
- **Remove `WebFetch` and `WebSearch` from `allowed-tools`** — fixes Gen Agent Trust Hub FAIL and reduces Snyk W011 risk score
- The planning-with-files skill is a file-management and planning skill; web access is not part of its core scope
- The PreToolUse hook re-reads `task_plan.md` before every tool call, creating an amplification vector when web-sourced content is written to plan files. Removing these tools from the skill's declared scope breaks the toxic flow
- Applied across all 7 IDE variants that declared `allowed-tools`: Claude Code, Cursor, Kilocode, CodeBuddy, Codex, OpenCode, Mastra Code
- **Add Security Boundary section to SKILL.md** — explicit guidance that web/search results must go to `findings.md` only (not `task_plan.md`), and all external content must be treated as untrusted
- **Add security note to examples.md** — the web research example now includes an inline comment reinforcing the trust boundary
## [2.20.0] - 2026-03-04
### Fixed
- **Codex session-catchup silent failure** (PR #100 by @tt-a1i, fixes #94)
- `session-catchup.py` in the Codex variant was silently scanning `~/.claude/projects` even when running from a Codex context, where sessions live under `~/.codex/sessions` in a different format
- Now detects the Codex runtime from `__file__` path and prints a clear fallback message instead of a silent no-op
- **Docs broken links** (PR #99 by @tt-a1i, fixes #95)
- `docs/opencode.md` linked to `.opencode/INSTALL.md` which does not exist — corrected to `docs/installation.md`
- `docs/factory.md` See Also links used `../skills/planning-with-files/` paths — corrected to `../.factory/skills/planning-with-files/`
- **Examples used stale `notes.md` filename** (PR #99 by @tt-a1i, fixes #96)
- All `examples.md` files across 16 IDE copies referenced `notes.md` which was renamed to `findings.md` — updated consistently everywhere
- **`sync-ide-folders.py --help` ran a sync instead of printing usage** (PR #99 by @tt-a1i, fixes #98)
- Replaced manual `sys.argv` parsing with `argparse` — `--help` now exits cleanly with usage information
### Changed
- **OpenCode README support label corrected** (PR #99 by @tt-a1i, fixes #97)
- Changed from `Full Support` to `Partial Support` with a note about session catchup limitations — aligns README with what `docs/opencode.md` actually says
### Thanks
- @tt-a1i for the full consistency sweep (PR #99, PR #100)
---
## [2.19.0] - 2026-03-04
### Fixed
- **Codex Advanced Topics broken links** (PR #92 by @tt-a1i, fixes #91)
- Corrected two dead links in `.codex/skills/planning-with-files/SKILL.md`
- `reference.md` → `references/reference.md`
- `examples.md` → `references/examples.md`
### Thanks
- @tt-a1i for identifying and fixing the broken Codex links (PR #92)
---
## [2.18.3] - 2026-02-28
### Fixed
- **Stop hook multiline YAML command fails under Git Bash on Windows** (PR #86 by @raykuo998)
- Root cause: YAML `command: |` multiline blocks are not reliably parsed by Git Bash on Windows. The shell received the first line (`SCRIPT_DIR=...`) as a command name rather than a variable assignment, crashing the hook before it could do anything.
- Replaced 25-line OS detection scripts with a single-line implicit platform fallback chain: `powershell.exe` first, `sh` as fallback. Applied to all 7 SKILL.md variants with Stop hooks.
- Added `-NoProfile` to PowerShell invocation for faster startup
- **`check-complete.ps1` completely failing on PowerShell 5.1** (PR #88 by @raykuo998)
- Root cause: Special characters inside double-quoted `Write-Host` strings (`[`, `(`, em-dash) caused parse errors in Windows PowerShell 5.1
- Replaced double-quoted strings with single-quoted strings plus explicit concatenation for variable interpolation. Applied to all 12 platform copies.
### Thanks
- @raykuo998 for both Windows compatibility fixes (PR #86, PR #88)
---
## [2.18.2] - 2026-02-26
### Fixed
- **Mastra Code hooks were silently doing nothing**
- Root cause: Mastra Code reads hooks from `.mastracode/hooks.json`, not from SKILL.md frontmatter. The existing integration had hooks defined only in SKILL.md (Claude Code format), which Mastra Code ignores entirely. All three hooks (PreToolUse, PostToolUse, Stop) were non-functional.
- Added `.mastracode/hooks.json` with proper Mastra Code format including `matcher`, `timeout`, and `description` fields
- Fixed `MASTRACODE_SKILL_ROOT` env var in SKILL.md Stop hook (variable does not exist in Mastra Code, replaced with `$HOME` fallback to local path)
- Bumped `.mastracode/skills/planning-with-files/SKILL.md` metadata version from 2.16.1 to 2.18.1
- Corrected `docs/mastra.md` to accurately describe hooks.json (removed false claim that Mastra Code uses the same hook system as Claude Code)
- Fixed personal installation instructions to include hooks.json copy step
---
## [2.18.1] - 2026-02-26
### Fixed
- **Copilot hooks garbled characters — still broken after v2.16.1** (Issue #82, confirmed by @Hexiaopi)
- Root cause: `Get-Content` in all PS1 scripts had no `-Encoding` parameter — PowerShell 5.x reads files using the system ANSI code page (Windows-1252) by default, corrupting any non-ASCII character in `task_plan.md` or `SKILL.md` before it reaches the output pipe. The v2.16.1 fix was correct but fixed only the output side, not the read side.
- Secondary fix: `[System.Text.Encoding]::UTF8` returns UTF-8 with BOM — replaced with `[System.Text.UTF8Encoding]::new($false)` (UTF-8 without BOM) in all four PS1 scripts to prevent JSON parsers from receiving a stray `0xEF 0xBB 0xBF` preamble
- Fixed files: `pre-tool-use.ps1`, `session-start.ps1`, `agent-stop.ps1`, `post-tool-use.ps1`
- Bash scripts were already correct from v2.16.1
### Thanks
- @Hexiaopi for confirming the issue persisted after v2.16.1 (Issue #82)
---
## [2.18.0] - 2026-02-26
### Added
- **BoxLite sandbox runtime integration** (Issue #84 by @DorianZheng)
- New `docs/boxlite.md` guide for running planning-with-files inside BoxLite micro-VM sandboxes via ClaudeBox
- New `examples/boxlite/quickstart.py` — working Python example using ClaudeBox's Skill API to inject planning-with-files into a VM
- New `examples/boxlite/README.md` — example context and requirements
- README: new "Sandbox Runtimes" section (BoxLite is infrastructure, not an IDE — kept separate from the 16-platform IDE table)
- README: BoxLite badge and Documentation table entry added
- BoxLite loads via ClaudeBox (`pip install claudebox`) using its Python Skill object — no `.boxlite/` folder needed
### Thanks
- @DorianZheng for the BoxLite integration proposal (Issue #84)
---
## [2.17.0] - 2026-02-25
### Added
- **Mastra Code support** — new `.mastracode/skills/planning-with-files/` integration with native hooks (PreToolUse, PostToolUse, Stop), full scripts, templates, and installation guide (platform #16)
### Fixed
- **Skill metadata spec compliance** — applied PR #83 fixes across all 12 IDE-specific SKILL.md files:
- `allowed-tools` YAML list → comma-separated string (Codex, Cursor, Kilocode, CodeBuddy, OpenCode)
- `version` moved from top-level to `metadata.version` across all applicable files
- Description updated with trigger terms ("plan out", "break down", "organize", "track progress") in all IDEs
- Version bumped to 2.16.1 everywhere, including canonical `skills/planning-with-files/SKILL.md`
- OpenClaw inline JSON metadata expanded to proper block YAML
### Thanks
- @popey for the PR #83 spec fixes that identified the issues
---
## [2.16.1] - 2026-02-25
### Fixed
- **Copilot hooks garbled characters on Windows** (Issue #82, reported by @Hexiaopi)
- PowerShell scripts now set `$OutputEncoding` and `[Console]::OutputEncoding` to UTF-8 before any output — fixes garbled diamond characters (◆) caused by PowerShell 5.x defaulting to UTF-16LE stdout
- Bash scripts now use `json.dumps(..., ensure_ascii=False)` — preserves UTF-8 characters (emojis, accented letters, CJK) in `task_plan.md` instead of converting them to raw `XXXX` escape sequences
### Thanks
- @Hexiaopi for reporting the garbled characters issue (Issue #82)
---
## [2.16.0] - 2026-02-22
### Added
- **GitHub Copilot Support** (PR #80 by @lincolnwan)
- Native GitHub Copilot hooks integration (early 2026 hooks feature)
- Created `.github/hooks/planning-with-files.json` configuration
- Added full hook scripts in `.github/hooks/scripts/`
- Cross-platform support (bash + PowerShell)
- Added `docs/copilot.md` installation guide
- Added GitHub Copilot badge to README
- This brings total supported platforms to 15
### Thanks
- @lincolnwan for GitHub Copilot hooks support (PR #80)
---
## [2.14.0] - 2026-02-04
### Added
- **Pi Agent Support** (PR #67 by @ttttmr)
- Full Pi Agent (pi.dev) integration
- Created `.pi/skills/planning-with-files/` skill bundle
- Added `package.json` for NPM installation (`pi install npm:pi-planning-with-files`)
- Full templates, scripts, and references included
- Cross-platform support (macOS, Linux, Windows)
- Added `docs/pi-agent.md` installation guide
- Added Pi Agent badge to README
- Note: Hooks are Claude Code-specific and not supported in Pi Agent
### Fixed
- **Codex Skill Path References** (PR #66 by @codelyc)
- Replaced broken `CLAUDE_PLUGIN_ROOT` references with correct Codex paths (`~/.codex/skills/planning-with-files/`)
- Added missing template files to `.codex/skills/planning-with-files/templates/`
### Changed
- **OpenClaw Docs Update** (PR #65 by @AZLabsAI, fixes #64)
- Renamed `docs/moltbot.md` to `docs/openclaw.md`
- Updated all paths from `~/.clawdbot/` to `~/.openclaw/`
- Updated CLI commands from `moltbot` to `openclaw`
- Updated website link from `molt.bot` to `openclaw.ai`
- Updated README: Moltbot badge and references updated to OpenClaw
- Version badge updated to v2.14.0
### Thanks
- @ttttmr for Pi Agent integration (PR #67)
- @codelyc for Codex path fix (PR #66)
- @AZLabsAI for OpenClaw docs update (PR #65)
---
## [2.11.0] - 2026-01-26
### Added

Some files were not shown because too many files have changed in this diff Show More