{
  "id": "page:docs-reference-repos-othmanadi-planning-with-files-research",
  "_kind": "Page",
  "_file": "wiki/docs/reference-repos/othmanadi/planning-with-files/research.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/reference-repos/OthmanAdi/planning-with-files/research.md",
    "sourceKind": "repo-docs",
    "title": "OthmanAdi/planning-with-files",
    "displayName": "OthmanAdi/planning-with-files",
    "slug": "docs/reference-repos/othmanadi/planning-with-files/research",
    "articlePath": "wiki/docs/reference-repos/OthmanAdi/planning-with-files/research.md",
    "article": "\n# OthmanAdi/planning-with-files\n\n- **Full name**: OthmanAdi/planning-with-files\n- **Description**: Claude Code skill implementing Manus-style persistent markdown planning -- the workflow pattern behind the $2B acquisition\n- **Stars**: 18,574\n- **License**: MIT\n- **Last pushed**: 2026-04-09\n- **Topics**: agent, agent-skills, claude, claude-code, claude-skills, cursor, manus, manus-ai\n- **Fork**: No\n- **Source**: gh-search\n\n## Archetype\n\n**utility-with-skill** -- A single focused skill that implements persistent file-based planning (task_plan.md + findings.md + progress.md) as \"working memory on disk.\" Supports 16+ IDEs with hooks for plan re-reading before tool use and progress tracking after edits.\n\n## Structure\n\n```\nskills/planning-with-files/\n  SKILL.md              # Main skill definition with hooks\n  examples.md           # Usage examples\n  reference.md          # Reference documentation\n  scripts/              # Session catchup, completion check scripts\n  templates/            # task_plan.md, findings.md, progress.md templates\ncommands/               # Slash commands\ndocs/                   # Per-IDE installation guides (16+ platforms)\nexamples/               # Example projects\ntests/                  # Test suite\n.claude-plugin/         # Plugin manifest\n.codex/                 # Codex integration\n.cursor/                # Cursor integration\n.gemini/                # Gemini integration\n.kiro/                  # Kiro integration\n.factory/               # Factory AI integration\n.pi/                    # Pi integration\n```\n\n## Key Techniques\n\n1. **Filesystem as working memory** -- Context window = RAM (volatile), filesystem = disk (persistent). All important state written to markdown files\n2. **Three-file pattern** -- task_plan.md (phases/progress/decisions), findings.md (research/discoveries), progress.md (session log/test results)\n3. **Hook-driven plan persistence** -- PreToolUse hook re-reads plan before every tool call; PostToolUse hook prompts progress updates after edits; Stop hook checks completion\n4. **Session recovery** -- After /clear, automatically detects and recovers previous session context from IDE session stores\n5. **2-action rule** -- Never take more than 2 actions without re-reading the plan (keeps plan in attention window)\n6. **Phase-based decomposition** -- Complex tasks broken into sequential phases with status tracking\n7. **Multi-IDE support** -- Same core pattern adapted to 16+ IDEs via per-platform hook configurations\n\n---\n\n## Processes\n\n### 1. Persistent File-Based Planning (specializations/shared/file-based-planning)\n\nA cross-domain process for managing complex multi-step tasks using persistent markdown files as working memory.\n\n**Phases:**\n1. **Plan creation** -- Decompose task into phases, create task_plan.md with phase definitions, dependencies, and acceptance criteria\n2. **Research capture** -- As discoveries are made during execution, append to findings.md with timestamps\n3. **Phase execution loop** -- For each phase: re-read plan, execute phase tasks, update progress.md, mark phase complete in task_plan.md\n4. **Decision logging** -- At each decision point, log rationale in task_plan.md decisions section\n5. **Completion verification** -- Check all phases marked complete, all acceptance criteria met\n6. **Session handoff** -- If context fills, progress.md enables seamless continuation in fresh session\n\n**Key insight:** The \"filesystem as working memory\" pattern is complementary to babysitter's journal-based state. The plan files serve as human-readable state that survives context window resets, while babysitter's journal provides machine-readable replay.\n\n**Placement justification:** This is a cross-domain planning pattern applicable to any complex task (development, research, data analysis). Goes in specializations/shared/.\n\n## Plugin Ideas\n\n### 1. Plan Persistence Plugin (Category: Context & Memory)\n\nA babysitter plugin that automatically creates and maintains task_plan.md / findings.md / progress.md files alongside babysitter's internal journal, giving humans a readable view of run progress.\n\n**install.md**: Installs `on-iteration-start` and `on-iteration-end` hooks. On iteration start: reads existing plan files and injects summary into task context. On iteration end: updates progress.md with completed effects and findings.md with any new discoveries. Provides a `plan:status` command to render current plan state.\n\n### 2. Session Recovery Plugin (Category: Context & Memory)\n\nA babysitter plugin that enables seamless session recovery after context window clears. Detects previous session state from IDE-specific stores and plan files, generates a catchup report showing what happened since last sync.\n\n**install.md**: Installs a `session-start` hook that checks for existing plan files and IDE session data. If found, generates a catchup report and injects it into the new session context. Works across Claude Code, Codex, Cursor, and Gemini CLI session stores.\n\n## Library Mapping\n\n| Extractable Process | Library Status | Action | Existing Path | Target Placement |\n|-------------------|----------------|--------|---------------|------------------|\n| Persistent File-Based Planning | NEW | Cross-domain planning using filesystem as working memory with markdown state files | - | specializations/shared/persistent-file-based-planning.js |\n| Three-File Planning Pattern | NEW | Task organization via task_plan.md, findings.md, and progress.md with hook-driven updates | - | specializations/shared/three-file-planning-pattern.js |\n| Phase-Based Task Decomposition | NEW | Complex task breakdown into sequential phases with status tracking and acceptance criteria | - | specializations/shared/phase-based-task-decomposition.js |\n| Session Recovery from File State | NEW | Context window recovery using persistent markdown files and IDE session stores | - | specializations/shared/session-recovery-file-state.js |\n\n## Plugin Marketplace Mapping\n\n| Plugin Idea | Marketplace Status | Action | Existing Plugin | Target Placement |\n|-------------|-------------------|--------|-----------------|------------------|\n| Plan Persistence Integration | UPGRADE | Human-readable plan files alongside babysitter's internal journal | plugins/a5c/marketplace/blueprints/claude-mem/ | plugins/a5c/marketplace/blueprints/plan-persistence-integration/ |\n| Session Recovery Enhancement | UPGRADE | Enhanced session recovery across multiple IDE platforms | plugins/a5c/marketplace/blueprints/claude-mem/ | plugins/a5c/marketplace/blueprints/session-recovery-enhancement/ |\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-reference-repos",
      "to": "page:docs-reference-repos-othmanadi-planning-with-files-research",
      "kind": "contains_page"
    }
  ]
}