docs/mastra.md
Using planning-with-files with Mastra Code.
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.
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.
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.
ls -la ~/.mastracode/skills/planning-with-files/SKILL.md
Restart your Mastra Code session. The skill auto-activates when you work on complex tasks.
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:
.mastracode/hooks.json (project-level, highest priority)~/.mastracode/hooks.json (global)This integration includes a pre-configured hooks.json with all three hooks:
| Hook | Matcher | What It Does |
|---|---|---|
| PreToolUse | Write, Edit, Bash, Read, Glob, Grep | Reads first 30 lines of task_plan.md to keep goals in attention |
| PostToolUse | Write, Edit | Reminds you to update plan status after file changes |
| Stop | (all) | Runs check-complete.sh to verify all phases are done |
The skill activates when you:
Once activated, the skill creates:
| File | Purpose | Location |
|---|---|---|
task_plan.md | Phases, progress, decisions | Your project root |
findings.md | Research, discoveries | Your project root |
progress.md | Session log, test results | Your project root |
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:
hooks.json (PreToolUse, PostToolUse, Stop)When your context fills up and you run /clear, the skill restores selected context from project planning files. Automatic recovery does not inspect Mastra or other host transcript stores. Local session records are available only through the explicit commands below.
Run manually:
# Linux/macOS
python3 ~/.mastracode/skills/planning-with-files/scripts/session-catchup.py --metadata "$(pwd)"
# Windows PowerShell
python "$env:USERPROFILE\.mastracode\skills\planning-with-files\scripts\session-catchup.py" --metadata (Get-Location)
These explicit commands read same-project local session records and emit aggregate counts only. Use --replay only for a deliberate bounded nonce-framed replay. Bare invocation and automatic hooks do not inspect agent session stores.
With workspace installation (.mastracode/skills/):
With personal installation (~/.mastracode/skills/):
ls ~/.mastracode/skills/planning-with-files/SKILL.mdMastra Code reads hooks from hooks.json, not from SKILL.md frontmatter. Verify:
.mastracode/hooks.json exists in your project root (workspace install) or ~/.mastracode/hooks.json (personal install)No conflict. Mastra Code checks .mastracode/skills/ first, then falls back to .claude/skills/. You can have both installed.