Mastra Code Setup

Mastra Code Setup

Using planning-with-files with Mastra Code.

Overview

Mastra Code auto-discovers skills from .mastracode/skills/ directories. It also has built-in Claude Code compatibility, so it reads .claude/skills/ too — but the dedicated .mastracode/ integration gives you native hooks support.

Installation

Method 1: Workspace Installation (Recommended)

Share the skill with your entire team by adding it to your repository:

# In your project repository
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files

# Copy the Mastra Code skill to your repo
cp -r /tmp/planning-with-files/.mastracode .

# Commit to share with team
git add .mastracode/
git commit -m "Add planning-with-files skill for Mastra Code"
git push

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

Now everyone on your team using Mastra Code will have access to the skill.

Method 2: Personal Installation

Install just for yourself:

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

# Copy skill to your personal Mastra Code skills folder
mkdir -p ~/.mastracode/skills
cp -r /tmp/planning-with-files/.mastracode/skills/planning-with-files ~/.mastracode/skills/

# Copy hooks (required for plan enforcement)
# If you already have ~/.mastracode/hooks.json, merge the entries manually
cp /tmp/planning-with-files/.mastracode/hooks.json ~/.mastracode/hooks.json

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

Note: If you already have a ~/.mastracode/hooks.json, do not overwrite it. Instead, merge the PreToolUse, PostToolUse, and Stop entries from the skill's hooks.json into your existing file.

Verification

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

Restart your Mastra Code session. The skill auto-activates when you work on complex tasks.

How It Works

Hooks (via hooks.json)

Mastra Code uses a separate hooks.json file for lifecycle hooks. This is different from Claude Code, which defines hooks in SKILL.md frontmatter. Mastra Code reads hooks from:

1. .mastracode/hooks.json (project-level, highest priority)
2. ~/.mastracode/hooks.json (global)

This integration includes a pre-configured hooks.json with all three hooks:

Auto-Activation

The skill activates when you:

• Mention "complex task" or "multi-step project"
• Ask to "plan out" or "break down" work
• Request help organizing or tracking progress
• Start research tasks requiring >5 tool calls

The Three Files

Once activated, the skill creates:

Claude Code Compatibility

Mastra Code reads from .claude/skills/ as a fallback. If you already have planning-with-files installed for Claude Code, it will work — but the dedicated .mastracode/ installation gives you:

• Native hooks via hooks.json (PreToolUse, PostToolUse, Stop)
• Correct script path resolution for Mastra Code directories
• No path conflicts with Claude Code plugin root

Session Recovery

When your context fills up and you run /clear, the skill can recover your previous session.

Run manually:

# Linux/macOS
python3 ~/.mastracode/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"

# Windows PowerShell
python "$env:USERPROFILE\.mastracode\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)

Team Workflow

Workspace Skills (Recommended)

With workspace installation (.mastracode/skills/):

• Everyone on team has the skill
• Consistent planning across projects
• Version controlled with your repo
• Changes sync via git

Personal Skills

With personal installation (~/.mastracode/skills/):

• Use across all your projects
• Keep it even if you switch teams
• Not shared with teammates

Troubleshooting

Skill Not Activating?

1. Verify the file exists: ls ~/.mastracode/skills/planning-with-files/SKILL.md
2. Restart Mastra Code — skills are scanned on startup
3. Use trigger phrases: "plan out", "break down", "organize", "track progress"

Hooks Not Running?

Mastra Code reads hooks from hooks.json, not from SKILL.md frontmatter. Verify:

1. Check that .mastracode/hooks.json exists in your project root (workspace install) or ~/.mastracode/hooks.json (personal install)
2. Verify the file contains PreToolUse, PostToolUse, and Stop entries
3. Restart Mastra Code after adding or modifying hooks.json

Already Using Claude Code?

No conflict. Mastra Code checks .mastracode/skills/ first, then falls back to .claude/skills/. You can have both installed.

Support

• GitHub Issues: https://github.com/OthmanAdi/planning-with-files/issues
• Mastra Code Docs: https://code.mastra.ai/configuration
• Author: @OthmanAdi

See Also

• Quick Start Guide
• Workflow Diagram
• Manus Principles
• Real Examples