docs: how to test the plugin locally (#119)

Author: omartinma

CONTRIBUTING.md

@@ -69,6 +69,101 @@ Add the new skill directory and files to the repository structure tree in `CLAUD
 - **Reference packages by full name** (e.g., `package:mocktail`, not just "mocktail").
 - **Show anti-patterns alongside correct patterns** when helpful, so readers understand both what to do and what to avoid.
 
+## Testing Locally
+
+Editing a skill or hook and pushing straight to a PR only tells you the files
+are valid, not that they work correctly. Load your working copy into a real Claude Code
+session and exercise it before you commit.
+
+### Prerequisites
+
+- **Claude Code CLI** installed (`npm install -g @anthropic-ai/claude-code`).
+- **Dart SDK** and **jq** on your `PATH` — the hooks need both.
+- **Very Good CLI** ≥ 1.3.0 (`dart pub global activate very_good_cli`) for the
+  Very Good CLI MCP server tools.
+
+See the README [Hooks](README.md#hooks) and [MCP Integration](README.md#mcp-integration)
+sections for the full prerequisite details.
+
+### Load your local copy
+
+From the repository root, launch Claude Code pointed at this directory:
+
+```bash
+claude --plugin-dir .
+```
+
+`--plugin-dir` loads the plugin for that session only, needs no install or
+marketplace, and overrides any marketplace-installed copy of the same plugin.
+`${CLAUDE_PLUGIN_ROOT}` (used throughout `hooks/hooks.json`) resolves to the
+directory you pass, so the hook script paths resolve correctly.
+
+### Verify each component loaded
+
+| Component | How to verify |
+| ----------- | --------------- |
+| **Skills** | Run `/help`. Skills appear namespaced as `/vgv-ai-flutter-plugin:<skill>` (e.g. `/vgv-ai-flutter-plugin:bloc`). Invoke one to confirm it triggers. |
+| **MCP servers** | Run `/mcp`. Confirm `dart` and `very-good-cli` both show connected. |
+| **Hooks** | Have Claude `Edit` or `Write` a `.dart` file and confirm `analyze.sh` and `format.sh` run. Launch without Very Good CLI to see the SessionStart warning fire. |
+
+### Iterate on changes
+
+After editing a `SKILL.md`, a hook script, or `.mcp.json`, **restart the
+`claude --plugin-dir .` session** to guarantee the change is picked up. Changes
+to `.claude-plugin/plugin.json` always require a restart. Edits to the hook
+`.sh` scripts take effect on the next matching tool call with no restart, since
+each hook runs the script fresh.
+
+### Rehearse the real install (optional)
+
+To mimic the marketplace install flow without pushing anything, register a
+throwaway local marketplace. Create `.claude-plugin/marketplace.json` in a temp
+directory with an **absolute** path to this repo:
+
+```jsonc
+// /tmp/vgv-test-marketplace/.claude-plugin/marketplace.json
+{
+  "plugins": [
+    {
+      "name": "vgv-ai-flutter-plugin",
+      "source": {
+        "type": "directory",
+        "path": "/ABSOLUTE/path/to/vgv-ai-flutter-plugin"
+      }
+    }
+  ]
+}
+```
+
+Then, inside a session:
+
+```text
+/plugin marketplace add /tmp/vgv-test-marketplace
+/plugin install vgv-ai-flutter-plugin
+```
+
+### Validate before you push
+
+Run the same check CI runs, from the repository root:
+
+```bash
+claude plugin validate .
+```
+
+This validates the manifest, skill frontmatter, hook JSON, MCP config, and file
+references. It is static, so it confirms structure but does not replace the live
+checks above.
+
+### Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --------------------------------------- | ------------------------------------------- | ------------------------------------------------------------- |
+| Skill missing from `/help` | Invalid frontmatter, or `name` doesn't match the folder | Run `claude plugin validate .` and fix the reported error |
+| MCP server "executable not found" | `dart` or `very_good` not on `PATH` | Install the SDK / activate the CLI, then verify with `which` |
+| Hook never fires | `jq` not installed, or script lacks `+x` / a shebang | Install `jq`; `chmod +x` the script and add `#!/bin/bash` |
+| `${CLAUDE_PLUGIN_ROOT}` not resolving | Session not launched via `--plugin-dir` (or restart pending) | Restart with `claude --plugin-dir .` from the repo root |
+| Local marketplace won't install | `source.path` is relative | Use an absolute path in `marketplace.json` |
+
 ## CI Checks
 
 Every pull request runs the following checks automatically: