fix(mastra): add hooks.json, fix SKILL.md path var, correct docs

Mastra Code reads hooks from .mastracode/hooks.json, not SKILL.md
frontmatter. All three hooks (PreToolUse, PostToolUse, Stop) were
silently non-functional. Added hooks.json with proper Mastra format
including matchers and timeouts. Fixed MASTRACODE_SKILL_ROOT env var
(does not exist in Mastra Code). Corrected docs/mastra.md to accurately
describe the hooks.json system and fixed personal install instructions
to include the hooks file.

.mastracode/hooks.json

@@ -0,0 +1,27 @@
+{
+  "PreToolUse": [
+    {
+      "type": "command",
+      "command": "cat task_plan.md 2>/dev/null | head -30 || true",
+      "matcher": { "tool_name": "Write|Edit|Bash|Read|Glob|Grep" },
+      "timeout": 5000,
+      "description": "Read plan before tool use to keep goals in active context"
+    }
+  ],
+  "PostToolUse": [
+    {
+      "type": "command",
+      "command": "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'",
+      "matcher": { "tool_name": "Write|Edit" },
+      "description": "Remind agent to update plan status after file changes"
+    }
+  ],
+  "Stop": [
+    {
+      "type": "command",
+      "command": "sh .mastracode/skills/planning-with-files/scripts/check-complete.sh 2>/dev/null || sh ~/.mastracode/skills/planning-with-files/scripts/check-complete.sh 2>/dev/null || true",
+      "timeout": 10000,
+      "description": "Check all phases are complete before the agent stops"
+    }
+  ]
+}

.mastracode/skills/planning-with-files/SKILL.md

@@ -18,7 +18,8 @@ hooks:
     - hooks:
         - type: command
           command: |
-            SCRIPT_DIR="${MASTRACODE_SKILL_ROOT:-$HOME/.mastracode/skills/planning-with-files}/scripts"
+            SCRIPT_DIR="${HOME}/.mastracode/skills/planning-with-files/scripts"
+            [ -f "$SCRIPT_DIR/check-complete.sh" ] || SCRIPT_DIR=".mastracode/skills/planning-with-files/scripts"
 
             IS_WINDOWS=0
             if [ "${OS-}" = "Windows_NT" ]; then
@@ -43,7 +44,7 @@ hooks:
               sh "$SCRIPT_DIR/check-complete.sh"
             fi
 metadata:
-  version: "2.16.1"
+  version: "2.18.1"
 ---
 
 # Planning with Files

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.18.2] - 2026-02-26
+
+### Fixed
+
+- **Mastra Code hooks were silently doing nothing**
+  - Root cause: Mastra Code reads hooks from `.mastracode/hooks.json`, not from SKILL.md frontmatter. The existing integration had hooks defined only in SKILL.md (Claude Code format), which Mastra Code ignores entirely. All three hooks (PreToolUse, PostToolUse, Stop) were non-functional.
+  - Added `.mastracode/hooks.json` with proper Mastra Code format including `matcher`, `timeout`, and `description` fields
+  - Fixed `MASTRACODE_SKILL_ROOT` env var in SKILL.md Stop hook (variable does not exist in Mastra Code, replaced with `$HOME` fallback to local path)
+  - Bumped `.mastracode/skills/planning-with-files/SKILL.md` metadata version from 2.16.1 to 2.18.1
+  - Corrected `docs/mastra.md` to accurately describe hooks.json (removed false claim that Mastra Code uses the same hook system as Claude Code)
+  - Fixed personal installation instructions to include hooks.json copy step
+
+---
+
 ## [2.18.1] - 2026-02-26
 
 ### Fixed

README.md

@@ -58,10 +58,11 @@ Everyone who made this project better — bug reports, PRs, and integrations.
 <details>
 <summary><strong>📦 Releases & Session Recovery</strong></summary>
 
-### Current Version: v2.17.0
+### Current Version: v2.18.2
 
 | Version | Highlights |
 |---------|------------|
+| **v2.18.2** | Mastra Code hooks fix (hooks.json + docs accuracy) |
 | **v2.18.1** | Copilot garbled characters complete fix |
 | **v2.18.0** | BoxLite sandbox runtime integration |
 | **v2.17.0** | Mastra Code support + all IDE SKILL.md spec fixes |
@@ -152,7 +153,7 @@ A Claude Code plugin that transforms your workflow to use persistent markdown fi
 [![GitHub Copilot](https://img.shields.io/badge/GitHub%20Copilot-Hooks-000000)](https://docs.github.com/en/copilot/reference/hooks-configuration)
 [![Mastra Code](https://img.shields.io/badge/Mastra%20Code-Skills-00BCD4)](https://code.mastra.ai)
 [![BoxLite](https://img.shields.io/badge/BoxLite-Sandbox-6C3483)](https://boxlite.ai)
-[![Version](https://img.shields.io/badge/version-2.18.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
+[![Version](https://img.shields.io/badge/version-2.18.2-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
 [![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1)](https://getskillcheck.com)
 
 ## Quick Install
@@ -394,4 +395,4 @@ MIT License — feel free to use, modify, and distribute.
 
 ## Star History
 
-[![RepoStars](https://repostars.dev/api/embed?repo=OthmanAdi%2Fplanning-with-files&theme=copper)](https://repostars.dev/?repos=OthmanAdi%2Fplanning-with-files&theme=copper)
+<a href="https://repostars.dev/?repos=OthmanAdi%2Fplanning-with-files&theme=copper"><img src="https://repostars.dev/api/embed?repo=OthmanAdi%2Fplanning-with-files&theme=copper" width="100%" alt="Star History Chart" /></a>

docs/mastra.md

@@ -40,14 +40,20 @@ Install just for yourself:
 # Clone the repo
 git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
 
-# Copy to your personal Mastra Code skills folder
+# 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
 
 ```bash
@@ -60,15 +66,20 @@ Restart your Mastra Code session. The skill auto-activates when you work on comp
 
 ## How It Works
 
-### Hooks (Native Support)
+### Hooks (via hooks.json)
 
-Mastra Code supports the same hook system as Claude Code. This integration includes:
+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:
 
-| Hook | Trigger | What It Does |
+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:
+
+| Hook | Matcher | What It Does |
 |------|---------|--------------|
-| **PreToolUse** | Before Write, Edit, Bash, Read, Glob, Grep | Reads first 30 lines of `task_plan.md` — keeps goals in attention |
-| **PostToolUse** | After Write, Edit | Reminds you to update plan status |
-| **Stop** | When agent finishes | Runs completion check script |
+| **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 |
 
 ### Auto-Activation
 
@@ -94,8 +105,8 @@ Once activated, the skill creates:
 
 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 integration (PreToolUse, PostToolUse, Stop)
-- Correct script path resolution
+- Native hooks via `hooks.json` (PreToolUse, PostToolUse, Stop)
+- Correct script path resolution for Mastra Code directories
 - No path conflicts with Claude Code plugin root
 
 ---
@@ -147,7 +158,11 @@ With personal installation (`~/.mastracode/skills/`):
 
 ### Hooks Not Running?
 
-Check `.mastracode/hooks.json` for conflicts. The skill's hooks are defined in SKILL.md frontmatter and should work automatically.
+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?