planning-with-files-manus-workflow

What this skill does

```markdown
---
name: planning-with-files-manus-workflow
description: Persistent markdown planning workflow for AI coding agents — the Manus-style 3-file pattern for context-aware, goal-tracking task execution.
triggers:
  - set up persistent planning files for my project
  - use manus style planning workflow
  - create task plan progress tracking files
  - help me plan complex tasks with markdown files
  - install planning with files skill
  - set up agent planning workflow like manus
  - use planning files to track my coding session
  - keep track of progress across context resets
---

# Planning with Files

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Persistent markdown planning for AI coding agents — the exact workflow pattern that powered Manus AI's $2B acquisition. Instead of relying on volatile context, this skill externalises memory to the filesystem using three structured markdown files that persist across sessions, context resets, and tool call chains.

## Core Concept

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

→ Anything important gets written to disk immediately.
```

## Installation

### Quickest (works with Claude Code, Cursor, Codex, Gemini CLI, 40+ agents)

```bash
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
```

### Claude Code Plugin (adds `/plan` autocomplete)

```
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
```

### Copy skill locally (removes prefix requirement)

**macOS/Linux:**
```bash
cp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/
```

**Windows (PowerShell):**
```powershell
Copy-Item -Recurse `
  -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-files\planning-with-files\*\skills\planning-with-files" `
  -Destination "$env:USERPROFILE\.claude\skills\"
```

## Commands

| Command | Shortcut | Description |
|---------|----------|-------------|
| `/planning-with-files:plan` | `/plan` | Start a new planning session |
| `/planning-with-files:status` | `/plan:status` | Show current planning progress |
| `/planning-with-files:start` | `/planning` | Original start command |

## The 3-File Pattern

For every complex task, create exactly **three files** in the project root:

```
task_plan.md    → Phases, goals, checkboxes, error log
findings.md     → Research results, discoveries, references
progress.md     → Session log, test results, current state
```

### `task_plan.md` — Master Plan

```markdown
# Task Plan: [Feature/Task Name]

## Goal
[One-paragraph description of what done looks like]

## Phases

### Phase 1: Research & Setup
- [ ] Understand existing codebase structure
- [ ] Identify affected modules
- [ ] Check for related tests

### Phase 2: Implementation
- [ ] Create new module `src/feature.py`
- [ ] Update `src/main.py` to integrate feature
- [ ] Add error handling

### Phase 3: Testing & Validation
- [ ] Write unit tests
- [ ] Run full test suite
- [ ] Verify edge cases

## Current Status
**Active Phase:** Phase 1
**Last Updated:** 2026-03-18

## Errors & Blockers
<!-- Log failures here so they aren't repeated -->
- [2026-03-18] Import error in `utils.py` — missing `requests` dep, fixed by adding to requirements.txt

## Notes
- API rate limit: 100 req/min
- Auth token stored in $API_TOKEN env var
```

### `findings.md` — Research Storage

```markdown
# Findings: [Task Name]

## Architecture Notes
- Entry point: `src/main.py:run()`
- Config loaded from `config/settings.yaml`
- Database: PostgreSQL via SQLAlchemy ORM

## API Behaviour
- POST /api/v1/items returns 201 with `{"id": "uuid", "status": "created"}`
- Rate limit headers: `X-RateLimit-Remaining`, `X-RateLimit-Reset`
- Auth: Bearer token in Authorization header

## Key Files
| File | Purpose |
|------|---------|
| `src/models.py` | SQLAlchemy models |
| `src/api/client.py` | HTTP client wrapper |
| `tests/conftest.py` | Pytest fixtures |

## Gotchas
- `session.commit()` must be called explicitly — no autocommit
- Timezone: all datetimes stored as UTC, displayed as local
```

### `progress.md` — Session Log

```markdown
# Progress Log: [Task Name]

## Session 2026-03-18

### Completed
- [x] Cloned repo, confirmed Python 3.11 environment
- [x] Read through `src/api/client.py` — documented in findings.md
- [x] Created skeleton for `src/feature.py`

### In Progress
- [ ] Implementing `FeatureProcessor.process()` method

### Test Results
```
pytest tests/test_feature.py -v
PASSED tests/test_feature.py::test_basic_flow
FAILED tests/test_feature.py::test_edge_case_empty_input
  AssertionError: expected ValueError, got None
```

### Next Session Start
1. Fix empty input edge case in `FeatureProcessor.process()`
2. Add integration test for API round-trip
```

## Python Implementation Pattern

When writing the actual agent logic or hooks, follow this pattern:

```python
from pathlib import Path
import datetime

PLAN_DIR = Path(".")  # or a subfolder like Path(".planning")

def get_plan_files():
    return {
        "plan":     PLAN_DIR / "task_plan.md",
        "findings": PLAN_DIR / "findings.md",
        "progress": PLAN_DIR / "progress.md",
    }

def initialize_planning(task_description: str) -> None:
    """Create the 3-file planning scaffold for a new task."""
    files = get_plan_files()
    today = datetime.date.today().isoformat()

    if not files["plan"].exists():
        files["plan"].write_text(f"""# Task Plan: {task_description}

## Goal
{task_description}

## Phases

### Phase 1: Research & Setup
- [ ] Understand existing codebase

### Phase 2: Implementation
- [ ] Implement solution

### Phase 3: Validation
- [ ] Test and verify

## Current Status
**Active Phase:** Phase 1
**Last Updated:** {today}

## Errors & Blockers

## Notes
""")

    if not files["findings"].exists():
        files["findings"].write_text(f"# Findings: {task_description}\n\n")

    if not files["progress"].exists():
        files["progress"].write_text(
            f"# Progress Log: {task_description}\n\n## Session {today}\n\n"
        )

    print(f"Planning files created in {PLAN_DIR.resolve()}")


def reread_plan() -> str:
    """Load the current plan — call this before every major decision."""
    plan_file = PLAN_DIR / "task_plan.md"
    if plan_file.exists():
        return plan_file.read_text()
    return "No task_plan.md found. Run initialize_planning() first."


def log_error(error_message: str) -> None:
    """Persist an error so it won't be repeated next session."""
    plan_file = PLAN_DIR / "task_plan.md"
    if not plan_file.exists():
        return
    today = datetime.date.today().isoformat()
    content = plan_file.read_text()
    entry = f"- [{today}] {error_message}\n"
    content = content.replace("## Errors & Blockers\n", f"## Errors & Blockers\n{entry}")
    plan_file.write_text(content)


def log_progress(entry: str) -> None:
    """Append a progress entry to progress.md."""
    progress_file = PLAN_DIR / "progress.md"
    today = datetime.date.today().isoformat()
    with progress_file.open("a") as f:
        f.write(f"\n- [{today}] {entry}\n")


def store_finding(section: str, content: str) -> None:
    """Append a finding to findings.md under a named section."""
    findings_file = PLAN_DIR / "findings.md"
    with findings_file.open("a") as f:
        f.write(f"\n## {section}\n{content}\n")


def check_completion() -> dict:
    """
    Parse task_plan.md and return completion stats.
    Returns: {"total": int, "done": int, "pending": list[str]}
    """
    plan_file = PLAN_DIR / "task_plan.md"
    if not plan_file.exists():
        return {"total": 0, "done": 0, "pending": []}

    lines = plan_file.read_text().splitlines()
    total, done, pending = 0, 0, []

    for line in lines:
        stripped = line.strip()
        if stripped.startswith("- ["):
            total += 1
            if stripped.startswith("