gm-copilot-cli 2.0.14 → 2.0.15

package/agents/gm.md

@@ -24,10 +24,10 @@ YOU ARE gm, an immutable programming state machine. You do not think in prose. Y
 
 **STATE TRANSITION RULES**:
 - States: `PLAN → EXECUTE → EMIT → VERIFY → COMPLETE`
-- PLAN: no tool calls yet. Exit condition: every possible unknown named as a mutable.
-- EXECUTE: run every possible code execution needed, each under 15 seconds, each densely packed with every possible related hypothesis. Never one idea per run. Assigns witnessed values to mutables. Exit condition: zero unresolved mutables.
-- EMIT: write all files. Exit condition: every possible gate checklist mutable `resolved=true` simultaneously.
-- VERIFY: run real system end to end, witness output. Exit condition: `witnessed_execution=true`.
+- PLAN: Use `planning` skill to construct `./.prd` with complete dependency graph. No tool calls yet. Exit condition: `.prd` written with all unknowns named as items, every possible edge case captured, dependencies mapped.
+- EXECUTE: Run every possible code execution needed, each under 15 seconds, densely packed with every possible hypothesis. Launch ≤3 parallel gm:gm subagents per wave. Assigns witnessed values to mutables. Exit condition: zero unresolved mutables.
+- EMIT: Write all files. Exit condition: every possible gate checklist mutable `resolved=true` simultaneously.
+- VERIFY: Run real system end to end, witness output. Exit condition: `witnessed_execution=true`.
 - COMPLETE: `gate_passed=true` AND `user_steps_remaining=0`. Absolute barrier—no partial completion.
 - If EXECUTE exits with unresolved mutables: re-enter EXECUTE with a broader script, never add a new stage.
 
@@ -53,7 +53,7 @@ Scope: Where and how code runs. Governs tool selection and execution context.
 
 All execution in plugin:gm:dev or plugin:browser:execute. Every hypothesis proven by execution before changing files. Know nothing until execution proves it.
 
-**CODE YOUR HYPOTHESES**: Test every possible hypothesis by writing code. Each execution run must be under 15 seconds and must intelligently test every possible related idea—never one idea per run. Run every possible execution needed, but each one must be densely packed with every possible related hypothesis. File existence, schema validity, output format, error conditions, edge cases—group every possible related unknown together. The goal is every possible hypothesis per run.
+**CODE YOUR HYPOTHESES**: Test every possible hypothesis by writing code in plugin:gm:dev or plugin:browser:execute. Each execution run must be under 15 seconds and must intelligently test every possible related idea—never one idea per run. Run every possible execution needed, but each one must be densely packed with every possible related hypothesis. File existence, schema validity, output format, error conditions, edge cases—group every possible related unknown together. The goal is every possible hypothesis per run. Use `agent-browser` skill for cross-client UI testing and browser-based hypothesis validation. Use plugin:gm:dev global scope for live state inspection and REPL debugging.
 
 **DEFAULT IS CODE, NOT BASH**: `plugin:gm:dev` is the primary execution tool. Bash is a last resort for operations that cannot be done in code (git, npm publish, docker). If you find yourself writing a bash command, stop and ask: can this be done in plugin:gm:dev? The answer is almost always yes.
 
@@ -67,18 +67,24 @@ All execution in plugin:gm:dev or plugin:browser:execute. Every hypothesis prove
 - Bash for code exploration (grep, find, cat, head, tail, ls on source files) - blocked, use codesearch instead
 - Bash for running scripts, node, bun, npx - blocked, use plugin:gm:dev instead
 - Bash for reading/writing files - blocked, use plugin:gm:dev fs operations instead
+- Puppeteer, playwright, playwright-core for browser automation - blocked, use `agent-browser` skill instead
 
 **REQUIRED TOOL MAPPING**:
-- Code exploration: `mcp__plugin_gm_code-search__search` (codesearch) - THE ONLY exploration tool. Natural language queries. No glob, no grep, no find, no explore agent, no Read for discovery.
+- Code exploration: `mcp__plugin_gm_code-search__search` (codesearch) - THE ONLY exploration tool. Semantic search 102 file types. Natural language queries with line numbers. No glob, no grep, no find, no explore agent, no Read for discovery.
 - Code execution: `mcp__plugin_gm_dev__execute` (plugin:gm:dev) - run JS/TS/Python/Go/Rust/etc
 - File operations: `mcp__plugin_gm_dev__execute` with fs module - read, write, stat files
 - Bash: `mcp__plugin_gm_dev__bash` - ONLY git, npm publish/pack, docker, system daemons
-- Browser: `plugin:browser:execute` - real UI workflows and integration tests
+- Browser: Use **`agent-browser` skill** instead of puppeteer/playwright - same power, cleaner syntax, built for AI agents
 
 **EXPLORATION DECISION TREE**: Need to find something in code?
 1. Use `mcp__plugin_gm_code-search__search` with natural language — always first
-2. If file path is already known → read via plugin:gm:dev fs.readFileSync
-3. No other options. Glob/Grep/Read/Explore/WebSearch are NOT exploration tools here.
+2. Try multiple queries (different keywords, phrasings) — searching faster/cheaper than CLI exploration
+3. Codesearch returns line numbers and context — all you need to Read via fs.readFileSync
+4. Only switch to CLI tools (grep, find) if codesearch fails after 5+ different queries for something known to exist
+5. If file path already known → read via plugin:gm:dev fs.readFileSync directly
+6. No other options. Glob/Grep/Read/Explore/WebSearch/puppeteer/playwright are NOT exploration or execution tools here.
+
+**CODESEARCH EFFICIENCY TIP**: Multiple semantic queries cost <$0.01 total and take <1 second each. A single CLI grep costs nothing but requires parsing results and may miss files. Use codesearch liberally — it's designed for this. Try:"What does this function do?" → "Where is error handling implemented?" → "Show database connection setup" → each returns ranked file locations.
 
 **BASH WHITELIST** (only acceptable bash uses):
 - `git` commands (status, add, commit, push, pull, log, diff)

package/copilot-profile.md

@@ -1,6 +1,6 @@
 ---
 name: gm
-version: 2.0.13
+version: 2.0.14
 description: Advanced Claude Code plugin with WFGY integration, MCP tools, and automated hooks
 author: AnEntrypoint
 repository: https://github.com/AnEntrypoint/gm-copilot-cli

package/manifest.yml

@@ -1,5 +1,5 @@
 name: gm
-version: 2.0.13
+version: 2.0.14
 description: Advanced Claude Code plugin with WFGY integration, MCP tools, and automated hooks
 author: AnEntrypoint
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-copilot-cli",
-  "version": "2.0.14",
+  "version": "2.0.15",
   "description": "Advanced Claude Code plugin with WFGY integration, MCP tools, and automated hooks",
   "author": "AnEntrypoint",
   "license": "MIT",

package/skills/agent-browser/SKILL.md

@@ -231,27 +231,282 @@ agent-browser eval -b "$(echo -n 'Array.from(document.querySelectorAll("a")).map
 - Nested quotes, arrow functions, template literals, or multiline -> use `eval --stdin <<'EVALEOF'`
 - Programmatic/generated scripts -> use `eval -b` with base64
 
-## Deep-Dive Documentation
+## Complete Command Reference
 
-| Reference | When to Use |
-|-----------|-------------|
-| [references/commands.md](references/commands.md) | Full command reference with all options |
-| [references/snapshot-refs.md](references/snapshot-refs.md) | Ref lifecycle, invalidation rules, troubleshooting |
-| [references/session-management.md](references/session-management.md) | Parallel sessions, state persistence, concurrent scraping |
-| [references/authentication.md](references/authentication.md) | Login flows, OAuth, 2FA handling, state reuse |
-| [references/video-recording.md](references/video-recording.md) | Recording workflows for debugging and documentation |
-| [references/proxy-support.md](references/proxy-support.md) | Proxy configuration, geo-testing, rotating proxies |
+### Core Navigation & Lifecycle
+```bash
+agent-browser open <url>              # Navigate (aliases: goto, navigate)
+agent-browser close                   # Close browser (aliases: quit, exit)
+agent-browser back                    # Go back
+agent-browser forward                 # Go forward
+agent-browser reload                  # Reload page
+```
+
+### Snapshots & Element References
+```bash
+agent-browser snapshot                # Accessibility tree with semantic refs
+agent-browser snapshot -i             # Interactive elements with @e refs
+agent-browser snapshot -i -C          # Include cursor-interactive divs (onclick, pointer)
+agent-browser snapshot -s "#sel"      # Scope snapshot to CSS selector
+agent-browser snapshot --json         # JSON output for parsing
+```
+
+### Interaction - Click, Fill, Type, Select
+```bash
+agent-browser click <sel>             # Click element
+agent-browser click <sel> --new-tab   # Open link in new tab
+agent-browser dblclick <sel>          # Double-click
+agent-browser focus <sel>             # Focus element
+agent-browser type <sel> <text>       # Type into element (append)
+agent-browser fill <sel> <text>       # Clear and fill
+agent-browser select <sel> <val>      # Select dropdown option
+agent-browser check <sel>             # Check checkbox
+agent-browser uncheck <sel>           # Uncheck checkbox
+agent-browser press <key>             # Press key (Enter, Tab, Control+a, etc.) (alias: key)
+```
+
+### Keyboard & Text Input
+```bash
+agent-browser keyboard type <text>    # Type with real keystrokes (no selector, uses focus)
+agent-browser keyboard inserttext <text>  # Insert text without triggering key events
+agent-browser keydown <key>           # Hold key down
+agent-browser keyup <key>             # Release key
+```
+
+### Mouse & Drag
+```bash
+agent-browser hover <sel>             # Hover element
+agent-browser drag <src> <tgt>        # Drag and drop
+agent-browser mouse move <x> <y>      # Move mouse to coordinates
+agent-browser mouse down [button]     # Press mouse button (left/right/middle)
+agent-browser mouse up [button]       # Release mouse button
+agent-browser mouse wheel <dy> [dx]   # Scroll wheel
+```
+
+### Scrolling & Viewport
+```bash
+agent-browser scroll <dir> [px]       # Scroll (up/down/left/right, optional px)
+agent-browser scrollintoview <sel>    # Scroll element into view (alias: scrollinto)
+agent-browser set viewport <w> <h>    # Set viewport size (e.g., 1920 1080)
+agent-browser set device <name>       # Emulate device (e.g., "iPhone 14")
+```
+
+### Get Information
+```bash
+agent-browser get text <sel>          # Get text content
+agent-browser get html <sel>          # Get innerHTML
+agent-browser get value <sel>         # Get input value
+agent-browser get attr <sel> <attr>   # Get attribute value
+agent-browser get title               # Get page title
+agent-browser get url                 # Get current URL
+agent-browser get count <sel>         # Count matching elements
+agent-browser get box <sel>           # Get bounding box {x, y, width, height}
+agent-browser get styles <sel>        # Get computed CSS styles
+```
+
+### Check State
+```bash
+agent-browser is visible <sel>        # Check if visible
+agent-browser is enabled <sel>        # Check if enabled (not disabled)
+agent-browser is checked <sel>        # Check if checked (checkbox/radio)
+```
+
+### File Operations
+```bash
+agent-browser upload <sel> <files>    # Upload files to file input
+agent-browser screenshot [path]       # Screenshot to temp or custom path
+agent-browser screenshot --full       # Full page screenshot
+agent-browser screenshot --annotate   # Annotated with numbered element labels
+agent-browser pdf <path>              # Save as PDF
+```
+
+### Semantic Locators (Alternative to Selectors)
+```bash
+agent-browser find role <role> <action> [value]       # By ARIA role
+agent-browser find text <text> <action>               # By text content
+agent-browser find label <label> <action> [value]     # By form label
+agent-browser find placeholder <ph> <action> [value]  # By placeholder text
+agent-browser find alt <text> <action>                # By alt text
+agent-browser find title <text> <action>              # By title attribute
+agent-browser find testid <id> <action> [value]       # By data-testid
+agent-browser find first <sel> <action> [value]       # First matching element
+agent-browser find last <sel> <action> [value]        # Last matching element
+agent-browser find nth <n> <sel> <action> [value]     # Nth matching element
+
+# Role examples: button, link, textbox, combobox, checkbox, radio, heading, list, etc.
+# Actions: click, fill, type, hover, focus, check, uncheck, text
+# Options: --name <name> (filter by accessible name), --exact (exact text match)
+```
 
-## Ready-to-Use Templates
+### Waiting
+```bash
+agent-browser wait <selector>         # Wait for element to be visible
+agent-browser wait <ms>               # Wait for time in milliseconds
+agent-browser wait --text "Welcome"   # Wait for text to appear
+agent-browser wait --url "**/dash"    # Wait for URL pattern
+agent-browser wait --load networkidle # Wait for load state (load, domcontentloaded, networkidle)
+agent-browser wait --fn "window.ready === true"  # Wait for JS condition
+```
 
-| Template | Description |
-|----------|-------------|
-| [templates/form-automation.sh](templates/form-automation.sh) | Form filling with validation |
-| [templates/authenticated-session.sh](templates/authenticated-session.sh) | Login once, reuse state |
-| [templates/capture-workflow.sh](templates/capture-workflow.sh) | Content extraction with screenshots |
+### JavaScript Evaluation
+```bash
+agent-browser eval <js>               # Run JavaScript in browser
+agent-browser eval -b "<base64>"      # Base64-encoded JS (avoid shell escaping)
+agent-browser eval --stdin <<'EOF'    # JS from stdin (heredoc, recommended for complex code)
+```
 
+### Browser Environment
 ```bash
-./templates/form-automation.sh https://example.com/form
-./templates/authenticated-session.sh https://app.example.com/login
-./templates/capture-workflow.sh https://example.com ./output
+agent-browser set geo <lat> <lng>     # Set geolocation
+agent-browser set offline [on|off]    # Toggle offline mode
+agent-browser set headers <json>      # Set HTTP headers
+agent-browser set credentials <u> <p> # HTTP basic auth
+agent-browser set media [dark|light]  # Emulate color scheme (prefers-color-scheme)
 ```
+
+### Cookies & Storage
+```bash
+agent-browser cookies                 # Get all cookies
+agent-browser cookies set <name> <val> # Set cookie
+agent-browser cookies clear           # Clear cookies
+agent-browser storage local           # Get all localStorage
+agent-browser storage local <key>     # Get specific key
+agent-browser storage local set <k> <v>  # Set value
+agent-browser storage local clear     # Clear all localStorage
+agent-browser storage session         # Same for sessionStorage
+agent-browser storage session <key>   # Get sessionStorage key
+agent-browser storage session set <k> <v>  # Set sessionStorage
+agent-browser storage session clear   # Clear sessionStorage
+```
+
+### Network & Interception
+```bash
+agent-browser network route <url>              # Intercept requests
+agent-browser network route <url> --abort      # Block requests
+agent-browser network route <url> --body <json>  # Mock response with JSON
+agent-browser network unroute [url]            # Remove routes
+agent-browser network requests                 # View tracked requests
+agent-browser network requests --filter api    # Filter by keyword
+```
+
+### Tabs & Windows
+```bash
+agent-browser tab                     # List active tabs
+agent-browser tab new [url]           # Open new tab (optionally with URL)
+agent-browser tab <n>                 # Switch to tab n
+agent-browser tab close [n]           # Close tab (current or specific)
+agent-browser window new              # Open new window
+```
+
+### Frames
+```bash
+agent-browser frame <sel>             # Switch to iframe by selector
+agent-browser frame main              # Switch back to main frame
+```
+
+### Dialogs
+```bash
+agent-browser dialog accept [text]    # Accept alert/confirm (with optional prompt text)
+agent-browser dialog dismiss          # Dismiss dialog
+```
+
+### State Persistence (Auth, Sessions)
+```bash
+agent-browser state save <path>       # Save authenticated session
+agent-browser state load <path>       # Load session state
+agent-browser state list              # List saved state files
+agent-browser state show <file>       # Show state summary
+agent-browser state rename <old> <new> # Rename state
+agent-browser state clear [name]      # Clear specific session
+agent-browser state clear --all       # Clear all states
+agent-browser state clean --older-than <days>  # Delete old states
+```
+
+### Debugging & Analysis
+```bash
+agent-browser highlight <sel>        # Highlight element visually
+agent-browser console                # View console messages (log, error, warn)
+agent-browser console --clear        # Clear console
+agent-browser errors                 # View JavaScript errors
+agent-browser errors --clear         # Clear errors
+agent-browser trace start [path]     # Start DevTools trace
+agent-browser trace stop [path]      # Stop and save trace
+agent-browser profiler start         # Start Chrome DevTools profiler
+agent-browser profiler stop [path]   # Stop and save .json profile
+```
+
+### Visual Debugging
+```bash
+agent-browser --headed open <url>     # Headless=false, show visual browser
+agent-browser record start <file.webm> # Record session
+agent-browser record stop             # Stop recording
+```
+
+### Comparisons & Diffs
+```bash
+agent-browser diff snapshot                              # Compare current vs last snapshot
+agent-browser diff snapshot --baseline before.txt        # Compare current vs saved snapshot
+agent-browser diff snapshot --selector "#main" --compact # Scoped diff
+agent-browser diff screenshot --baseline before.png      # Visual pixel diff
+agent-browser diff screenshot --baseline b.png -o d.png  # Save diff to custom path
+agent-browser diff screenshot --baseline b.png -t 0.2    # Color threshold 0-1
+agent-browser diff url https://v1.com https://v2.com     # Compare two URLs
+agent-browser diff url https://v1.com https://v2.com --screenshot  # With visual diff
+agent-browser diff url https://v1.com https://v2.com --selector "#main"  # Scoped
+```
+
+### Sessions & Parallelism
+```bash
+agent-browser --session <name> <cmd>  # Run in named session (isolated instance)
+agent-browser session list            # List active sessions
+agent-browser session show            # Show current session
+# Example: agent-browser --session agent1 open site.com
+#          agent-browser --session agent2 open other.com
+```
+
+### Browser Connection
+```bash
+agent-browser connect <port>          # Connect via Chrome DevTools Protocol
+agent-browser --auto-connect open <url>  # Auto-discover running Chrome
+agent-browser --cdp 9222 <cmd>        # Explicit CDP port
+```
+
+### Setup & Installation
+```bash
+agent-browser install                 # Download Chromium browser
+agent-browser install --with-deps     # Also install system dependencies (Linux)
+```
+
+### Advanced: Local Files & Protocols
+```bash
+agent-browser --allow-file-access open file:///path/to/file.pdf
+agent-browser --allow-file-access open file:///path/to/page.html
+```
+
+### Advanced: iOS/Mobile Testing
+```bash
+agent-browser device list             # List available iOS simulators
+agent-browser -p ios --device "iPhone 16 Pro" open <url>  # Launch on device
+agent-browser -p ios snapshot -i      # Snapshot on iOS
+agent-browser -p ios tap @e1          # Tap (alias for click)
+agent-browser -p ios swipe up         # Mobile gestures
+agent-browser -p ios screenshot mobile.png
+agent-browser -p ios close            # Close simulator
+# Requires: macOS, Xcode, Appium (npm install -g appium && appium driver install xcuitest)
+```
+
+## Key Patterns for Agents
+
+**Always use agent-browser instead of puppeteer, playwright, or playwright-core** — it has the same capabilities with simpler syntax and better integration with AI agents.
+
+**Multi-step workflows**:
+1. `agent-browser open <url>`
+2. `agent-browser snapshot -i` (get refs)
+3. `agent-browser fill @e1 "value"`
+4. `agent-browser click @e2`
+5. `agent-browser wait --load networkidle` (after navigation)
+6. `agent-browser snapshot -i` (re-snapshot for new refs)
+
+**Debugging complex interactions**: Use `agent-browser --headed open <url>` to see visual browser, then `agent-browser highlight @e1` to verify element targeting.
+
+**Ground truth verification**: Combine `agent-browser eval` for JavaScript inspection with `agent-browser screenshot` for visual confirmation.

package/skills/planning/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: planning
+description: PRD construction for work planning. Use this skill in PLAN phase to build .prd file with complete dependency graph of all items, edge cases, and subtasks before execution begins.
+allowed-tools: Write
+---
+
+# Work Planning with PRD Construction
+
+## Overview
+
+This skill constructs `./.prd` (Product Requirements Document) files for structured work tracking. The PRD is a **single source of truth** that captures every possible item to complete, organized as a dependency graph for parallel execution.
+
+**CRITICAL**: The PRD must be created in PLAN phase before any work begins. It blocks all other work until complete. It is frozen after creation—only items may be removed as they complete. No additions or reorganizations after plan is created.
+
+## When to Use This Skill
+
+Use `planning` skill when:
+- Starting a new task or initiative
+- User requests multiple items/features/fixes that need coordination
+- Work has dependencies, parallellizable items, or complex stages
+- You need to track progress across multiple independent work streams
+
+**Do NOT use** if task is trivial (single item under 5 minutes).
+
+## PRD Structure
+
+Each PRD contains:
+- **items**: Array of work items with dependencies
+- **completed**: Empty list (populated as items finish)
+- **metadata**: Total estimates, phases, notes
+
+### Item Fields
+
+```json
+{
+  "id": "1",
+  "subject": "imperative verb describing outcome",
+  "status": "pending",
+  "description": "detailed requirement",
+  "blocking": ["2", "3"],
+  "blockedBy": ["4"],
+  "effort": "small|medium|large",
+  "category": "feature|bug|refactor|docs",
+  "notes": "contextual info"
+}
+```
+
+### Key Rules
+
+**Subject**: Use imperative form - "Fix auth bug", "Add webhook support", "Consolidate templates", not "Bug: auth", "New feature", etc.
+
+**Blocking/Blocked By**: Map dependency graph
+- If item 2 waits for item 1: `"blockedBy": ["1"]`
+- If item 1 blocks items 2 & 3: `"blocking": ["2", "3"]`
+
+**Status**: Only three values
+- `pending` - not started
+- `in_progress` - currently working
+- `completed` - fully done
+
+**Effort**: Estimate relative scope
+- `small`: 1-2 items in 15 min
+- `medium`: 3-5 items in 30-45 min
+- `large`: 6+ items or 1+ hours
+
+## Complete Item Template
+
+Use this when planning complex work:
+
+```json
+{
+  "id": "task-name-1",
+  "subject": "Consolidate duplicate template builders",
+  "status": "pending",
+  "description": "Extract shared generatePackageJson() and buildHooksMap() logic from cli-adapter.js and extension-adapter.js into TemplateBuilder methods. Current duplication causes maintenance burden.",
+  "category": "refactor",
+  "effort": "medium",
+  "blocking": ["task-name-2"],
+  "blockedBy": [],
+  "acceptance": [
+    "Single generatePackageJson() method in TemplateBuilder",
+    "Both adapters call TemplateBuilder methods",
+    "All 9 platforms generate identical package.json structure",
+    "No duplication in adapter code"
+  ],
+  "edge_cases": [
+    "Platforms without package.json (JetBrains IDE)",
+    "Custom fields for CLI vs extension platforms"
+  ],
+  "verification": "All 9 build outputs pass validation, adapters <150 lines each"
+}
+```
+
+## Comprehensive Planning Checklist
+
+When creating PRD, cover:
+
+### Requirements
+- [ ] Main objective clearly stated
+- [ ] Success criteria defined
+- [ ] User-facing changes vs internal
+- [ ] Backwards compatibility implications
+- [ ] Data migration needed?
+
+### Edge Cases
+- [ ] Empty inputs/missing files
+- [ ] Large scale (1000s of items?)
+- [ ] Concurrent access patterns
+- [ ] Timeout/hang scenarios
+- [ ] Recovery from failures
+
+### Dependencies
+- [ ] External services/APIs required?
+- [ ] Third-party library versions
+- [ ] Environment setup (DB, redis, etc)
+- [ ] Breaking changes from upgrades?
+
+### Acceptance Criteria
+- [ ] Code changed meets goal
+- [ ] Tests pass (if applicable)
+- [ ] Performance requirements met
+- [ ] Security concerns addressed
+- [ ] Documentation updated
+
+### Integration Points
+- [ ] Does it touch other systems?
+- [ ] API compatibility impacts?
+- [ ] Database schema changes?
+- [ ] Message queue formats?
+- [ ] Configuration propagation?
+
+### Error Handling
+- [ ] What fails gracefully?
+- [ ] What fails hard?
+- [ ] Recovery mechanisms?
+- [ ] Fallback options?
+- [ ] User notification strategy?
+
+## PRD Lifecycle
+
+### Creation Phase
+1. Enumerate **every possible unknown** as work item
+2. Map dependencies (blocking/blockedBy)
+3. Group parallelizable items into waves
+4. Verify all edge cases captured
+5. Write `./.prd` to disk
+6. **FREEZE** - no modifications except item removal
+
+### Execution Phase
+1. Read `.prd`
+2. Find all `pending` items with no `blockedBy`
+3. Launch ≤3 parallel workers (gm:gm subagents) per wave
+4. As items complete, update status to `completed`
+5. Remove completed items from `.prd` file
+6. Launch next wave when previous completes
+7. Continue until `.prd` is empty
+
+### Completion Phase
+- `.prd` file is empty (all items removed)
+- All work committed and pushed
+- Tests passing
+- No remaining `pending` or `in_progress` items
+
+## File Location
+
+**CRITICAL**: PRD must be at exactly `./.prd` (current working directory root).
+
+- ✅ `/home/user/plugforge/.prd`
+- ❌ `/home/user/plugforge/.prd-temp`
+- ❌ `/home/user/plugforge/build/.prd`
+- ❌ `/home/user/plugforge/.prd.json`
+
+No variants, no subdirectories, no extensions. Absolute path must resolve to `cwd + .prd`.
+
+## JSON Format
+
+PRD files are **valid JSON** for easy parsing and manipulation.
+
+```json
+{
+  "project": "plugforge",
+  "created": "2026-02-24",
+  "objective": "Unify agent tooling and planning infrastructure",
+  "items": [
+    {
+      "id": "1",
+      "subject": "Update agent-browser skill documentation",
+      "status": "pending",
+      "description": "Add complete command reference with all 100+ commands",
+      "blocking": ["2"],
+      "blockedBy": [],
+      "effort": "small",
+      "category": "docs"
+    },
+    {
+      "id": "2",
+      "subject": "Create planning skill for PRD construction",
+      "status": "pending",
+      "description": "New skill that creates .prd files with dependency graphs",
+      "blocking": ["3"],
+      "blockedBy": ["1"],
+      "effort": "medium",
+      "category": "feature"
+    },
+    {
+      "id": "3",
+      "subject": "Update gm.md agent instructions",
+      "status": "pending",
+      "description": "Reference new skills, emphasize codesearch over cli tools",
+      "blocking": [],
+      "blockedBy": ["2"],
+      "effort": "medium",
+      "category": "docs"
+    }
+  ],
+  "completed": []
+}
+```
+
+## Execution Guidelines
+
+**Wave Orchestration**: Maximum 3 subagents per wave (gm:gm agents via Task tool).
+
+```
+Wave 1: Items 1, 2, 3 (all pending, no dependencies)
+  └─ 3 subagents launched in parallel
+
+Wave 2: Items 4, 5 (depend on Wave 1 completion)
+  └─ Items 6, 7 (wait for Wave 2)
+
+Wave 3: Items 6, 7
+  └─ 2 subagents (since only 2 items)
+
+Wave 4: Item 8 (depends on Wave 3)
+  └─ Completes work
+```
+
+After each wave completes:
+1. Remove finished items from `.prd`
+2. Write `.prd` (now shorter)
+3. Check for newly unblocked items
+4. Launch next wave
+
+## Example: Multi-Platform Builder Updates
+
+```json
+{
+  "project": "plugforge",
+  "objective": "Add hooks support to 5 CLI platforms",
+  "items": [
+    {
+      "id": "hooks-cc",
+      "subject": "Add hooks to gm-cc platform",
+      "status": "pending",
+      "blocking": ["test-hooks"],
+      "blockedBy": [],
+      "effort": "small"
+    },
+    {
+      "id": "hooks-gc",
+      "subject": "Add hooks to gm-gc platform",
+      "status": "pending",
+      "blocking": ["test-hooks"],
+      "blockedBy": [],
+      "effort": "small"
+    },
+    {
+      "id": "hooks-oc",
+      "subject": "Add hooks to gm-oc platform",
+      "status": "pending",
+      "blocking": ["test-hooks"],
+      "blockedBy": [],
+      "effort": "small"
+    },
+    {
+      "id": "test-hooks",
+      "subject": "Test all 5 platforms with hooks",
+      "status": "pending",
+      "blocking": [],
+      "blockedBy": ["hooks-cc", "hooks-gc", "hooks-oc"],
+      "effort": "large"
+    }
+  ]
+}
+```
+
+**Execution**:
+- Wave 1: Launch 3 subagents for `hooks-cc`, `hooks-gc`, `hooks-oc` in parallel
+- After all 3 complete, launch `test-hooks`
+
+This cuts wall-clock time from 45 min (sequential) to ~15 min (parallel).
+
+## Best Practices
+
+### Cover All Scenarios
+Don't under-estimate work. If you think it's 3 items, list 8. Missing items cause restarts.
+
+### Name Dependencies Clearly
+- `blocking`: What does THIS item prevent?
+- `blockedBy`: What must complete before THIS?
+- Bidirectional: If A blocks B, then B blockedBy A
+
+### Use Consistent Categories
+- `feature`: New capability
+- `bug`: Fix broken behavior
+- `refactor`: Improve structure without changing behavior
+- `docs`: Documentation
+- `infra`: Build, CI, deployment
+
+### Track Edge Cases Separately
+Even if an item seems small, if it has edge cases, call them out. They often take 50% of the time.
+
+### Estimate Effort Realistically
+- `small`: Coding + testing in 1 attempt
+- `medium`: May need 2 rounds of refinement
+- `large`: Multiple rounds, unexpected issues likely
+
+## Stop Hook Enforcement
+
+When session ends, a **stop hook** checks if `.prd` exists and has `pending` or `in_progress` items. If yes, session is blocked. You cannot leave work incomplete.
+
+This forces disciplined work closure: every PRD must reach empty state or explicitly pause with documented reason.
+
+## Integration with gm Agent
+
+The gm agent (immutable state machine) reads `.prd` in PLAN phase:
+1. Verifies `.prd` exists and has valid JSON
+2. Extracts items with `status: pending`
+3. Finds items with no `blockedBy` constraints
+4. Launches ≤3 gm:gm subagents per wave
+5. Each subagent completes one item
+6. On completion, PRD is updated (item removed)
+7. Process repeats until `.prd` is empty
+
+This creates structured, auditable work flow for complex projects.

package/tools.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "description": "Advanced Claude Code plugin with WFGY integration, MCP tools, and automated hooks",
   "tools": [
     {