### Run Quickstart Example

Source: https://github.com/othmanadi/planning-with-files/blob/master/examples/boxlite/README.md

Execute the main Python quickstart script to load planning-with-files as a ClaudeBox Skill and run a planning session within a BoxLite VM.

```bash
python quickstart.py
```

--------------------------------

### Install planning-with-files via AdaL Plugin Marketplace

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/adal.md

Add the marketplace and install the planning-with-files plugin. This is the recommended one-time setup.

```bash
# Add the marketplace (one-time setup)
/plugin marketplace add OthmanAdi/planning-with-files

# Browse and install via dialog
/plugin

# Or install directly
/plugin install planning-with-files@planning-with-files
```

--------------------------------

### Install planning-with-files Skill from GitHub

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/gemini.md

Install the planning-with-files skill directly from its GitHub repository using the Gemini CLI. This is the recommended installation method.

```bash
gemini skills install https://github.com/OthmanAdi/planning-with-files --path .gemini/skills/planning-with-files
```

--------------------------------

### Install planning-with-files via ClawHub

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/openclaw.md

Use this command to install the skill directly from the ClawHub marketplace. This is the recommended installation method.

```bash
claw install othmanadi/planning-with-files
```

--------------------------------

### Install Planning Skill (Default Language)

Source: https://github.com/othmanadi/planning-with-files/blob/master/README.md

Use this command to install the 'planning-with-files' skill for the default language. This is the primary installation method.

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

--------------------------------

### Quick Install Plugin

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/installation.md

Use this command for a quick and recommended installation of the plugin via the Claude Code marketplace.

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

--------------------------------

### Install planning-with-files using .cursor directory

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/cursor.md

Recommended installation method. Copies skill files, hooks config, and hook scripts to your project.

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.cursor .cursor
```

--------------------------------

### Manually Install planning-with-files Skill (Workspace-level)

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/gemini.md

Manually install the planning-with-files skill for workspace-level access. This is useful for project-specific installations.

```bash
# In your project directory
mkdir -p .gemini/skills

# Copy skill
cp -r /path/to/planning-with-files/.gemini/skills/planning-with-files .gemini/skills/
```

--------------------------------

### Quick Install planning-with-files Globally for OpenCode

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/opencode.md

Installs the planning-with-files skill globally into your OpenCode configuration directory. Ensure you have git installed.

```bash
mkdir -p ~/.config/opencode/skills
cd ~/.config/opencode/skills
git clone https://github.com/OthmanAdi/planning-with-files.git
```

--------------------------------

### Quick Start: planning-with-files in BoxLite

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/boxlite.md

Minimal example to load the planning-with-files skill into a ClaudeBox session and execute a planning task. The skill's SKILL.md is loaded, and planning files persist across sessions.

```python
import asyncio
from pathlib import Path
from claudebox import ClaudeBox, Skill

# Load the SKILL.md content from the installed skill
SKILL_MD = Path.home() / ".claude" / "skills" / "planning-with-files" / "SKILL.md"

PLANNING_SKILL = Skill(
    name="planning-with-files",
    description="Manus-style file-based planning with persistent markdown",
    files={
        "/root/.claude/skills/planning-with-files/SKILL.md": SKILL_MD.read_text()
    }
)

async def main():
    async with ClaudeBox(
        session_id="my-project",
        skills=[PLANNING_SKILL]
    ) as box:
        result = await box.code(
            "Plan and implement a user authentication feature for the Express API"
        )
        print(result.response)

asyncio.run(main())
```

--------------------------------

### Original Start Command

Source: https://context7.com/othmanadi/planning-with-files/llms.txt

An alternative invocation for starting a planning session, identical in behavior to the `:plan` command.

```bash
/planning-with-files:start
```

--------------------------------

### Manual setup for planning-with-files

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/cursor.md

Manual steps to set up the skill files, hooks configuration, and hook scripts in your project.

```bash
1. Copy .cursor/skills/planning-with-files/ to your project
2. Copy .cursor/hooks.json to your project
3. Copy .cursor/hooks/ directory to your project
```

--------------------------------

### Verify Skill Installation Directory

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/troubleshooting.md

Check if the planning-with-files skill is correctly installed by listing its contents in the expected directories.

```bash
ls ~/.claude/skills/planning-with-files/
```

```bash
ls .claude/plugins/planning-with-files/
```

--------------------------------

### Quick Install planning-with-files for a Project in OpenCode

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/opencode.md

Installs the planning-with-files skill locally within a specific project directory for OpenCode. This is useful for project-specific configurations.

```bash
mkdir -p .opencode/skills
cd .opencode/skills
git clone https://github.com/OthmanAdi/planning-with-files.git
```

--------------------------------

### Manually install skills only

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/windows.md

Install only the skills from the planning-with-files repository by cloning and copying them to the Claude skills directory.

```powershell
git clone https://github.com/OthmanAdi/planning-with-files.git
Copy-Item -Recurse planning-with-files\skills\ $env:USERPROFILE\.claude\skills\
```

--------------------------------

### Install ClaudeBox and Set Token

Source: https://github.com/othmanadi/planning-with-files/blob/master/examples/boxlite/README.md

Install the ClaudeBox library and set the necessary OAuth token for authentication. This is a prerequisite for running BoxLite examples.

```bash
pip install claudebox
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
```

--------------------------------

### Global Installation of Planning-with-files

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/continue.md

Clone the repository and copy the skill and prompt files into your global Continue directory. Restart Continue to apply changes.

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
mkdir -p ~/.continue/skills ~/.continue/prompts
cp -r planning-with-files/.continue/skills/planning-with-files ~/.continue/skills/
cp planning-with-files/.continue/prompts/planning-with-files.prompt ~/.continue/prompts/
```

--------------------------------

### Manual Workspace Installation of planning-with-files

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/openclaw.md

Clone the repository and copy the skill files to your workspace's skills directory. This method is useful for development or when direct ClawHub installation is not preferred.

```bash
# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git

# Copy the skill files to your workspace
mkdir -p skills/planning-with-files
cp -r planning-with-files/clawhub-upload/* skills/planning-with-files/

# Clean up
rm -rf planning-with-files
```

--------------------------------

### Install planning-with-files Skill

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/kiro.md

Clone the repository and copy the skill folder into your project's .kiro/skills directory.

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
mkdir -p .kiro/skills
cp -r planning-with-files/.kiro/skills/planning-with-files ./.kiro/skills/
```

--------------------------------

### Manually Install planning-with-files Skill (User-level)

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/gemini.md

Manually install the planning-with-files skill for user-level access. This involves cloning the repository and copying the skill files to the user's Gemini skills directory.

```bash
# Clone the repository
git clone https://github.com/OthmanAdi/planning-with-files.git

# Copy to Gemini skills folder
cp -r planning-with-files/.gemini/skills/planning-with-files ~/.gemini/skills/
```

--------------------------------

### Manual Local Skills Install (macOS/Linux)

Source: https://context7.com/othmanadi/planning-with-files/llms.txt

Manually installs the Planning with Files skill locally on macOS or Linux systems.

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

--------------------------------

### Project-level Installation of Planning-with-files

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/continue.md

Clone the repository and copy the .continue directory into your project root for project-level integration. Restart Continue to apply changes.

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.continue .continue
```

--------------------------------

### Global Install via npx

Source: https://context7.com/othmanadi/planning-with-files/llms.txt

Installs the Planning with Files skill globally for all supported IDEs. Use the appropriate command for your desired language.

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

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

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

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

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

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

--------------------------------

### Global Installation of planning-with-files

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/openclaw.md

Install the skill to your local OpenClaw skills directory, making it available globally. This involves cloning the repo and copying files to `~/.openclaw/skills/`.

```bash
# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git

# Copy to global OpenClaw skills
mkdir -p ~/.openclaw/skills/planning-with-files
cp -r planning-with-files/clawhub-upload/* ~/.openclaw/skills/planning-with-files/

# Clean up
rm -rf planning-with-files
```

--------------------------------

### Install Plugin using --plugin-dir

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/installation.md

Clone the repository and then use the --plugin-dir flag to specify the plugin's location during runtime.

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
claude --plugin-dir ./planning-with-files
```

--------------------------------

### Install Hooks for planning-with-files Skill (Project-level)

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/gemini.md

Install the hook configuration and scripts for the planning-with-files skill at the project level. This merges the hooks with existing settings.

```bash
# Copy settings.json (merges with existing settings)
cp /path/to/planning-with-files/.gemini/settings.json .gemini/settings.json

# Copy hook scripts
cp -r /path/to/planning-with-files/.gemini/hooks .gemini/hooks
```

--------------------------------

### Install Planning Skill (Chinese Simplified)

Source: https://github.com/othmanadi/planning-with-files/blob/master/README.md

Install the 'planning-with-files' skill for Simplified Chinese. This command ensures the skill is available with the correct identifier for Chinese users.

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

--------------------------------

### Clone Planning Skill (Unix/Linux/macOS)

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/kilocode.md

Clone the planning-with-files repository to your local machine. This is the first step for project-level installation.

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
```

--------------------------------

### Manual Local Skills Install (Windows PowerShell)

Source: https://context7.com/othmanadi/planning-with-files/llms.txt

Manually installs the Planning with Files skill locally on Windows using 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\"
```

--------------------------------

### Verify planning-with-files Skill Installation

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/gemini.md

Verify that the planning-with-files skill has been installed correctly by listing all available skills. This can be done via the CLI or within an interactive Gemini session.

```bash
# List all skills
gemini skills list

# Should show:
# - planning-with-files: Implements Manus-style file-based planning...

```

```bash
/skills list
```

--------------------------------

### Install Planning Skill (Arabic)

Source: https://github.com/othmanadi/planning-with-files/blob/master/README.md

Install the 'planning-with-files' skill specifically for Arabic language support. Ensure you use the correct skill name for the desired language.

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

--------------------------------

### Install Planning Skill (Spanish)

Source: https://github.com/othmanadi/planning-with-files/blob/master/README.md

Install the 'planning-with-files' skill for Spanish language support. Use this command to add the skill with its Spanish identifier.

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

--------------------------------

### Manually install plugin via Git clone

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/windows.md

Manually install the planning-with-files plugin by cloning the repository into the Claude plugins directory.

```powershell
# Create plugins directory
mkdir -p $env:USERPROFILE\.claude\plugins

# Clone the repository
git clone https://github.com/OthmanAdi/planning-with-files.git $env:USERPROFILE\.claude\plugins\planning-with-files
```

--------------------------------

### Install Planning with Files Skill via Pi

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/pi-agent.md

Use this command to install the planning-with-files skill directly using npm within the Pi Agent.

```bash
pi install npm:pi-planning-with-files
```

--------------------------------

### Install planning-with-files Skill (Personal)

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/antigravity.md

Clone the skill repository and copy the planning-with-files skill to your personal Antigravity skills folder for individual use.

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files

mkdir -p ~/.gemini/antigravity/skills
cp -r /tmp/planning-with-files/.agent/skills/planning-with-files ~/.gemini/antigravity/skills/

rm -rf /tmp/planning-with-files
```

--------------------------------

### Install Planning Skill (Chinese Traditional)

Source: https://github.com/othmanadi/planning-with-files/blob/master/README.md

Install the 'planning-with-files' skill for Traditional Chinese. This command adds the skill with its specific identifier for Traditional Chinese users.

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

--------------------------------

### Install Planning Skill (German)

Source: https://github.com/othmanadi/planning-with-files/blob/master/README.md

Install the 'planning-with-files' skill for German language support. This command adds the skill with a language-specific identifier.

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

--------------------------------

### Example Task Plan Phases

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/quickstart.md

Define your task into 3-7 phases in `task_plan.md`. Each phase should have a clear objective and status.

```markdown
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Research existing solutions
- **Status:** in_progress

### Phase 2: Implementation
- [ ] Write core code
- **Status:** pending
```

--------------------------------

### Install Hooks for planning-with-files Skill (User-level)

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/gemini.md

Install the hook configuration and scripts for the planning-with-files skill at the user level, applying them to all projects. This merges the hooks with existing user settings.

```bash
# Copy to user settings (applies to all projects)
cp /path/to/planning-with-files/.gemini/settings.json ~/.gemini/settings.json
cp -r /path/to/planning-with-files/.gemini/hooks ~/.gemini/hooks
```

--------------------------------

### Manual Installation of Planning with Files Skill

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/pi-agent.md

Steps for manually cloning the repository and copying the skill to the Pi Agent's skills directory.

```bash
# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git
# Copy the skill
mkdir -p ~/.pi/agent/skills
cp -r planning-with-files/.pi/skills/planning-with-files .pi/skills/
```

--------------------------------

### Verify Project Installation of planning-with-files Skill

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/opencode.md

Checks if the planning-with-files skill's main markdown file is correctly installed in the project-specific OpenCode skills directory.

```bash
ls -la .opencode/skills/planning-with-files/planning-with-files/SKILL.md
```

--------------------------------

### Install planning-with-files Skill for oh-my-opencode

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/opencode.md

Copies the planning-with-files skill files to the global OpenCode skills directory, preparing it for use with oh-my-opencode.

```bash
mkdir -p ~/.config/opencode/skills/planning-with-files
cp -r .opencode/skills/planning-with-files/* ~/.config/opencode/skills/planning-with-files/
```

--------------------------------

### Verify Global Installation of planning-with-files Skill

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/opencode.md

Checks if the planning-with-files skill's main markdown file is correctly installed in the global OpenCode skills directory.

```bash
ls -la ~/.config/opencode/skills/planning-with-files/planning-with-files/SKILL.md
```

--------------------------------

### Release Notes Format Example

Source: https://github.com/othmanadi/planning-with-files/blob/master/AGENTS.md

Example structure for release notes used with `gh release create --notes`, focusing on changes and acknowledgments.

```markdown
What changed:

- <Bug description> — <what the fix does>
- <Feature description> — <how it works>

Thanks: @handle for reporting issue #N.
```

--------------------------------

### Install Mastra Code Skill Personally

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/mastra.md

This method installs the planning-with-files skill into your personal Mastra Code configuration. It involves cloning the repository, copying the skill and hooks.json to your user's Mastra Code directories. Be cautious when merging hooks.json if you already have a configuration.

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files

mkdir -p ~/.mastracode/skills
cp -r /tmp/planning-with-files/.mastracode/skills/planning-with-files ~/.mastracode/skills/

cp /tmp/planning-with-files/.mastracode/hooks.json ~/.mastracode/hooks.json

rm -rf /tmp/planning-with-files
```

--------------------------------

### Install Codex Skill and Hooks Personally

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/codex.md

This script installs the planning-with-files skill and hooks for personal use by copying them to your ~/.codex directory. Remember to manually merge hooks.json if you have existing global hooks.

```bash
# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files

# Copy the skill
mkdir -p ~/.codex/skills
cp -r /tmp/planning-with-files/.codex/skills/planning-with-files ~/.codex/skills/

# Copy the hook scripts
mkdir -p ~/.codex/hooks
cp -r /tmp/planning-with-files/.codex/hooks/* ~/.codex/hooks/

# Copy hooks.json
# If you already have ~/.codex/hooks.json, merge the planning-with-files entries manually
cp /tmp/planning-with-files/.codex/hooks.json ~/.codex/hooks.json

# Clean up
rm -rf /tmp/planning-with-files
```

--------------------------------

### CHANGELOG Format Example

Source: https://github.com/othmanadi/planning-with-files/blob/master/AGENTS.md

Example structure for a CHANGELOG entry, including version, date, fixed issues, added features, changed functionality, and contributor acknowledgments.

```markdown
## [X.Y.Z] - YYYY-MM-DD

### Fixed
- Short description of what was wrong and how it was fixed.

### Thanks
- @handle — what they contributed (issue #N / PR #N)
```

--------------------------------

### Install Skills Manually

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/installation.md

Clone the repository and copy the skills into your ~/.claude/skills/ directory if you only need the skill functionality.

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/skills/* ~/.claude/skills/
```

--------------------------------

### Cursor Hooks Configuration Example

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/cursor.md

Illustrates the directory structure for Cursor hooks, including configuration, scripts, and skill files.

```treeview
your-project/
├── .cursor/
│   ├── hooks.json                  ← Hook configuration
│   ├── hooks/
│   │   ├── pre-tool-use.sh         ← Pre-tool-use script
│   │   ├── post-tool-use.sh        ← Post-tool-use script
│   │   ├── stop.sh                 ← Completion check script
│   │   ├── pre-tool-use.ps1        ← PowerShell versions
│   │   ├── post-tool-use.ps1
│   │   └── stop.ps1
│   └── skills/
│       └── planning-with-files/
│           ├── SKILL.md
│           ├── examples.md
│           ├── reference.md
│           └── templates/
├── task_plan.md                     ← Your planning files (created per task)
├── findings.md
├── progress.md
└── ...
```

--------------------------------

### Example of explicit prompt for complex tasks

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/adal.md

When starting complex tasks, be explicit in your prompts to AdaL, guiding it to use specific patterns like planning-with-files and outlining the initial steps.

```markdown
This is a complex task. Let's use the planning-with-files pattern.
Start by creating task_plan.md with the goal and phases.
```

--------------------------------

### Update Planning-with-files Plugin

Source: https://github.com/othmanadi/planning-with-files/blob/master/MIGRATION.md

Use these commands to update the plugin. Choose the marketplace or manual installation method.

```bash
# If installed via marketplace
/plugin update planning-with-files

# If installed manually
cd .claude/plugins/planning-with-files
git pull origin master
```

--------------------------------

### Example Complex Task Description for Skill Activation

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/antigravity.md

When starting a complex task, describe it using phrases that indicate multiple phases, database setup, API endpoints, testing, and documentation requirements to ensure the skill auto-activates.

```text
I'm building a user authentication system.
This is a multi-phase project requiring database
setup, API endpoints, testing, and documentation.
```

--------------------------------

### Install Claude Code via winget

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/windows.md

Use winget to install Claude Code on Windows. This is the recommended installation method.

```powershell
winget install Anthropic.ClaudeCode
```

--------------------------------

### Initialize Session with Script

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/quickstart.md

Use the init script to manually create planning files if not using the AI skill. Remember to fill in the Goal section in `task_plan.md` afterwards.

```bash
# Use the init script
./scripts/init-session.sh
# Then fill in the Goal section in task_plan.md
```

--------------------------------

### Uninstall Manually Installed Plugin

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/installation.md

Remove a manually installed plugin by deleting its directory from .claude/plugins.

```bash
rm -rf .claude/plugins/planning-with-files
```

--------------------------------

### Install planning-with-files Skill (Workspace)

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/antigravity.md

Clone the skill repository and copy it to your project's .agent directory for team-wide access. Commit the changes to share with your team.

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files

cp -r /tmp/planning-with-files/.agent .

git add .agent/
git commit -m "Add planning-with-files skill for Antigravity"
git push

rm -rf /tmp/planning-with-files
```

--------------------------------

### Install ClaudeBox

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/boxlite.md

Install the ClaudeBox Python package using pip. This is a prerequisite for using ClaudeBox with BoxLite.

```bash
pip install claudebox
```

--------------------------------

### Install planning-with-files via PowerShell (Windows)

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/adal.md

Clone the repository and copy the skill to the user's personal AdaL skills directory using PowerShell on Windows.

```powershell
git clone https://github.com/OthmanAdi/planning-with-files.git
Copy-Item -Recurse -Path "planning-with-files\.adal\skills\planning-with-files" -Destination "$env:USERPROFILE\.adal\skills\"
```

--------------------------------

### Install planning-with-files to project skills directory

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/adal.md

Clone the repository and copy the skill to the project's local AdaL skills directory. This is useful for team collaboration on specific projects.

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.adal/skills/planning-with-files .adal/skills/
```

--------------------------------

### CONTRIBUTORS.md Format Example

Source: https://github.com/othmanadi/planning-with-files/blob/master/AGENTS.md

Example format for the CONTRIBUTORS.md file, detailing other contributors with links to their GitHub profiles and contributions.

```markdown
### Other Contributors

**[Name](https://github.com/handle)** — [PR #N](link) / [Issue #N](link)
- What they did (one bullet per contribution)
- Impact or context
```

--------------------------------

### Update Skills Only Installation

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/installation.md

Update skills installed separately by pulling the latest changes from the repository's master branch.

```bash
cd ~/.claude/skills/planning-with-files
git pull origin master
```

--------------------------------

### Initialize Planning Files (Unix/Linux/macOS)

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/kilocode.md

Run the `init-session.sh` script from the global skills directory to initialize planning files for your current session.

```bash
~/.kilocode/skills/planning-with-files/scripts/init-session.sh
```

--------------------------------

### Install planning-with-files to personal skills directory

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/adal.md

Clone the repository and copy the skill to your personal AdaL skills directory. This allows for direct use and modification.

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.adal/skills/planning-with-files ~/.adal/skills/
```

--------------------------------

### Update Manually Installed Plugin

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/installation.md

Update a manually installed plugin by pulling the latest changes from the repository's master branch.

```bash
cd .claude/plugins/planning-with-files
git pull origin master
```

--------------------------------

### Initialize Planning Files (Unix/Linux/macOS)

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/kilocode.md

Use this script to initialize planning files for a new session on Unix-like systems.

```bash
# Initialize planning files
./.kilocode/skills/planning-with-files/scripts/init-session.sh
```

--------------------------------

### Initialize Planning Session Script

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/continue.md

Run this bash script from your project root to create the necessary planning files (task_plan.md, findings.md, progress.md) if they are missing.

```bash
bash .continue/skills/planning-with-files/scripts/init-session.sh
```

--------------------------------

### Verify Codex Installation and Hooks

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/codex.md

Run these commands to verify that Codex is installed, that codex_hooks is enabled, and that the skill and hook files are correctly placed in your ~/.codex directory.

```bash
codex --version
codex features list | rg '^codex_hooks\s'
ls -la ~/.codex/skills/planning-with-files/SKILL.md
ls -la ~/.codex/hooks.json ~/.codex/hooks/
```

--------------------------------

### Bootstrap Planning Files

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/kiro.md

Run the bootstrap script to create initial planning files and steering context. This script is idempotent.

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

```powershell
pwsh -ExecutionPolicy Bypass -File .kiro/skills/planning-with-files/assets/scripts/bootstrap.ps1
```

--------------------------------

### Verify Mastra Code Skill Installation

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/mastra.md

After installation, verify that the skill's main file exists in the expected location within your Mastra Code skills directory.

```bash
ls -la ~/.mastracode/skills/planning-with-files/SKILL.md
```

--------------------------------

### Start Planning Session

Source: https://context7.com/othmanadi/planning-with-files/llms.txt

Initiates a planning session with a task description. This command creates task_plan.md, findings.md, and progress.md, then begins Phase 1 execution.

```bash
/planning-with-files:plan

Task: Build a REST API endpoint for user authentication with JWT tokens.
Plan the implementation phases, identify the key files to create,
and list the dependencies needed.

# Expected output: agent creates task_plan.md, findings.md, progress.md
# in the current working directory, then starts Phase 1.
```

--------------------------------

### Run init-session.sh with WSL

Source: https://github.com/othmanadi/planning-with-files/blob/master/docs/windows.md

Execute the init-session.sh script using the Windows Subsystem for Linux (WSL).

```bash
wsl ./scripts/init-session.sh
```

--------------------------------

### Load and Run Planning-with-Files Skill in BoxLite

Source: https://context7.com/othmanadi/planning-with-files/llms.txt

This Python script demonstrates how to load the planning-with-files skill and use it within a ClaudeBox environment for task execution and file inspection. Ensure ClaudeBox is installed (`pip install claudebox`).

```python
import asyncio
from pathlib import Path
from claudebox import ClaudeBox, Skill

def load_skill() -> Skill:
    skill_base = Path.home() / ".claude" / "skills" / "planning-with-files"
    skill_md_path = skill_base / "SKILL.md"
    check_complete_path = skill_base / "scripts" / "check-complete.sh"

    files = {
        "/root/.claude/skills/planning-with-files/SKILL.md": skill_md_path.read_text(),
    }
    if check_complete_path.exists():
        files["/root/.claude/skills/planning-with-files/scripts/check-complete.sh"] = (
            check_complete_path.read_text()
        )

    return Skill(
        name="planning-with-files",
        description=(
            "Manus-style file-based planning. Creates task_plan.md, findings.md, "
            "and progress.md. Use for complex multi-step tasks requiring >5 tool calls."
        ),
        files=files,
    )

async def main():
    skill = load_skill()

    async with ClaudeBox(session_id="planning-demo", skills=[skill]) as box:
        result = await box.code(
            "/planning-with-files:plan\n\n"
            "Task: Build a REST API endpoint for user authentication with JWT tokens."
        )
        print(result.response)

        files_result = await box.code(
            "ls -la task_plan.md findings.md progress.md && head -20 task_plan.md"
        )
        print(files_result.response)

    # Workspace persists — reconnect later
    # async with ClaudeBox.reconnect("planning-demo") as box:
    #     result = await box.code("Read task_plan.md and continue with next phase.")

asyncio.run(main())
```