gm-copilot-cli 2.0.132 → 2.0.133

package/copilot-profile.md

@@ -1,6 +1,6 @@
 ---
 name: gm
-version: 2.0.132
+version: 2.0.133
 description: State machine agent with hooks, skills, and automated git enforcement
 author: AnEntrypoint
 repository: https://github.com/AnEntrypoint/gm-copilot-cli

package/manifest.yml

@@ -1,5 +1,5 @@
 name: gm
-version: 2.0.132
+version: 2.0.133
 description: State machine agent with hooks, skills, and automated git enforcement
 author: AnEntrypoint
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-copilot-cli",
-  "version": "2.0.132",
+  "version": "2.0.133",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "author": "AnEntrypoint",
   "license": "MIT",

package/skills/planning/SKILL.md

@@ -1,335 +1,70 @@
 ---
 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.
+description: PRD construction for work planning. Compulsory in PLAN phase. Builds .prd file as frozen dependency graph of every possible work item before execution begins. Triggers on any new task, multi-step work, or when gm enters PLAN state.
 allowed-tools: Write
 ---
 
-# Work Planning with PRD Construction
+# PRD Construction
 
-## Overview
+## Purpose
 
-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.
+The `.prd` is the single source of truth for remaining work. It is a frozen dependency graph created in PLAN phase before any execution. It captures every possible item — steps, substeps, edge cases, corner cases, dependencies, transitive dependencies, unknowns, assumptions to validate, decisions, trade-offs, factors, variables, acceptance criteria, scenarios, failure paths, recovery paths, integration points, state transitions, race conditions, concurrency concerns, input variations, output validations, error conditions, boundary conditions, configuration variants, environment differences, platform concerns, backwards compatibility, data migration, rollback paths, monitoring checkpoints, verification steps.
 
-**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.
+Longer is better. Missing items means missing work. Err towards every possible item.
 
-## When to Use This Skill
+## File Rules
 
-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
+Path: exactly `./.prd` in current working directory. No variants (.prd-rename, .prd-temp, .prd-backup), no subdirectories, no path transformations, no extensions. Valid JSON.
 
-**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
+## Item Schema
 
 ```json
 {
-  "id": "1",
-  "subject": "imperative verb describing outcome",
+  "id": "descriptive-kebab-id",
+  "subject": "Imperative verb describing outcome",
   "status": "pending",
-  "description": "detailed requirement",
-  "blocking": ["2", "3"],
-  "blockedBy": ["4"],
+  "description": "What must be true when this is done",
+  "blocking": ["ids-this-prevents"],
+  "blockedBy": ["ids-that-must-finish-first"],
   "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"
+  "category": "feature|bug|refactor|docs|infra",
+  "acceptance": ["measurable criteria"],
+  "edge_cases": ["known complications"]
 }
 ```
 
-## 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).
+**Subject**: imperative form — "Fix auth bug", "Add webhook support", "Consolidate templates". Never "Bug: auth" or "New feature".
 
-## Best Practices
+**Blocking/blockedBy**: bidirectional. If A blocks B, then B blockedBy A. Every dependency explicit.
 
-### Cover All Scenarios
-Don't under-estimate work. If you think it's 3 items, list 8. Missing items cause restarts.
+**Status**: `pending` → `in_progress` → `completed`. No other values.
 
-### Name Dependencies Clearly
-- `blocking`: What does THIS item prevent?
-- `blockedBy`: What must complete before THIS?
-- Bidirectional: If A blocks B, then B blockedBy A
+**Effort**: `small` (one attempt, <15min), `medium` (2 rounds, <45min), `large` (multiple rounds, 1h+).
 
-### Use Consistent Categories
-- `feature`: New capability
-- `bug`: Fix broken behavior
-- `refactor`: Improve structure without changing behavior
-- `docs`: Documentation
-- `infra`: Build, CI, deployment
+## Construction
 
-### 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.
+1. Enumerate every possible unknown as a work item.
+2. Map every possible dependency (blocking/blockedBy).
+3. Group independent items into parallel waves (max 3 per wave).
+4. Capture every possible edge case as either a separate item or an edge_case field.
+5. Write `./.prd` to disk.
+6. **FREEZE** — no additions or reorganizations after creation. Only mutation: removing finished items.
 
-### Estimate Effort Realistically
-- `small`: Coding + testing in 1 attempt
-- `medium`: May need 2 rounds of refinement
-- `large`: Multiple rounds, unexpected issues likely
+## Execution
 
-## Stop Hook Enforcement
+1. Find all `pending` items with empty `blockedBy`.
+2. Launch ≤3 parallel subagents (`subagent_type: gm:gm`) per wave.
+3. Each subagent completes one item, verifies via witnessed execution.
+4. On completion: remove item from `.prd`, write updated file.
+5. Check for newly unblocked items. Launch next wave.
+6. Continue until `.prd` is empty.
 
-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.
+Never execute independent items sequentially. Never launch more than 3 at once.
 
-This forces disciplined work closure: every PRD must reach empty state or explicitly pause with documented reason.
+## Completion
 
-## Integration with gm Agent
+`.prd` must be empty at COMPLETE — zero pending, zero in_progress items. The stop hook blocks session end when items remain. Empty `.prd` = all work done.
 
-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
+## Do Not Use
 
-This creates structured, auditable work flow for complex projects.
+Skip this skill if the task is trivially single-step (under 5 minutes, no dependencies, no unknowns).

package/tools.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.132",
+  "version": "2.0.133",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "tools": [
     {

package/skills/process-management/SKILL.md

@@ -1,207 +0,0 @@
----
-name: process-management
-description: >-
-  PM2 process management for all running applications. Enforces: pre-check for
-  running processes before start, watch enabled, autorestart disabled, lifecycle
-  cleanup when done. Use for all servers, workers, agents, background processes.
-  Triggers: start server, run application, background process, pm2, keep alive,
-  process manager, daemon, monitor logs.
----
-
-# Process Management — PM2
-
-All applications MUST run through PM2. Direct invocations (node, bun, python) are forbidden for any process that produces output or has a lifecycle.
-
-## Installation (First Time Only)
-
-Check if PM2 is installed:
-
-```bash
-pm2 --version
-```
-
-If command not found, install globally:
-
-```bash
-npm install -g pm2
-```
-
-Verify installation:
-
-```bash
-pm2 --version        # should print version number
-pm2 ping             # should respond "pong"
-```
-
-## Pre-Start Check (MANDATORY)
-
-Before starting any process, check what is already running:
-
-```bash
-pm2 jlist
-```
-
-- `online` → already running, use `pm2 logs <name>` to observe
-- `stopped` → use `pm2 restart <name>`
-- Not in list → proceed to start
-
-Never start a duplicate process. Always check first.
-
-## Start a Process
-
-```bash
-# CLI (quick)
-pm2 start app.js --name myapp --watch --no-autorestart
-
-# With interpreter
-pm2 start script.py --interpreter python3 --name worker --watch --no-autorestart
-
-# From ecosystem config (preferred for reproducibility)
-pm2 start ecosystem.config.cjs
-```
-
-## Ecosystem Config (Standard Template)
-
-`autorestart: false` — process stops on crash, no automatic recovery
-`watch: true` — restarts on file changes in watched directories only
-
-```javascript
-// ecosystem.config.cjs
-module.exports = {
-  apps: [{
-    name: "myapp",
-    script: "src/index.js",
-    watch: ["src", "config"],
-    watch_delay: 1000,
-    autorestart: false,
-    ignore_watch: [
-      "node_modules",
-      ".git",
-      "logs",
-      "*.log",
-      ".pm2",
-      "public",
-      "uploads"
-    ],
-    watch_options: {
-      followSymlinks: false,
-      usePolling: false
-    },
-    log_date_format: "YYYY-MM-DD HH:mm:ss",
-    out_file: "./logs/out.log",
-    error_file: "./logs/error.log"
-  }]
-};
-```
-
-## Log Viewing
-
-```bash
-pm2 logs <name>                      # stream live (Ctrl+C to stop)
-pm2 logs <name> --lines 100          # last 100 lines then stream
-pm2 logs <name> --err                # errors only
-pm2 logs <name> --out                # stdout only
-pm2 logs <name> --nostream --lines 200  # dump without follow
-pm2 logs --json                      # structured JSON output
-pm2 flush                            # clear all log files
-```
-
-Log files: `~/.pm2/logs/<name>-out.log` / `<name>-error.log`
-Windows path: `C:\Users\<user>\.pm2\logs\`
-
-## Lifecycle Management
-
-```bash
-pm2 list                    # view all processes and status
-pm2 jlist                   # JSON output for scripting
-pm2 info <name>             # detailed process info
-pm2 stop <name>             # stop (keeps in list)
-pm2 restart <name>          # restart
-pm2 delete <name>           # stop + remove from list
-pm2 delete all              # remove all processes
-pm2 ping                    # check if PM2 daemon is alive
-```
-
-**When work is complete: always `pm2 delete <name>` to clean up orphaned processes.**
-
-Stopping a watched process: `pm2 stop` while watch is active restarts on next file change.
-To fully halt: `pm2 delete <name>` (removes it entirely).
-
-## Windows vs Linux
-
-### File Watching
-
-| Environment | Config |
-|---|---|
-| Linux native | `usePolling: false` (inotify kernel events) |
-| WSL watching `/mnt/c/...` | `usePolling: true, interval: 1000` |
-| Windows native | `usePolling: false` (ReadDirectoryChangesW) |
-| Network / NFS / Docker volumes | `usePolling: true, interval: 1000` |
-
-Linux inotify exhaustion fix (symptom: watch silently stops working):
-```bash
-echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
-```
-
-### Windows: npm Scripts and .cmd Wrappers
-
-PM2 cannot spawn `.cmd` shims (npm, npx, etc.) directly — they require `cmd.exe`.
-
-```javascript
-// ecosystem.config.cjs — Windows npm script
-{
-  name: "myapp",
-  script: "npm",
-  args: "start",
-  interpreter: "cmd",
-  interpreter_args: "/c"
-}
-```
-
-For globally installed CLIs, find the real `.js` entry point:
-```bash
-# Linux/macOS
-cat "$(which myapp)" | head -5
-
-# Windows PowerShell
-Get-Command myapp | Select-Object -ExpandProperty Source
-```
-Point `script` at the resolved `.js` file — never at the `.cmd` wrapper.
-
-### Terminal Suppression on Windows (CRITICAL)
-
-All code that spawns subprocesses MUST use `windowsHide: true` to prevent popup windows.
-
-```javascript
-// ❌ WRONG - will show popup windows on Windows
-spawn('node', ['script.js']);
-
-// ✅ CORRECT - hides windows, safe for all platforms
-spawn('node', ['script.js'], { windowsHide: true });
-```
-
-Applies to all subprocess execution:
-- `child_process.spawn()` → `{ windowsHide: true }`
-- `child_process.exec()` → `{ windowsHide: true }`
-- `child_process.execFile()` → `{ windowsHide: true }`
-- `child_process.fork()` → `{ silent: true }` (alternative for fork)
-
-PM2-started processes automatically hide windows. Code-spawned subprocesses must explicitly set this. Forgetting creates visible popups during automation—unacceptable UX.
-
-### Windows 11+ wmic Error
-
-PM2 uses `wmic` for process stats — removed in Windows 11+.
-Symptom: `Error: spawn wmic ENOENT` in `~/.pm2/pm2.log`.
-Fix: `npm install -g pm2@latest`. App processes continue working despite the error.
-
-### Persistence on Reboot
-
-| Platform | Method |
-|---|---|
-| Linux | `pm2 startup && pm2 save` (auto-detects systemd/upstart/openrc) |
-| Windows | [pm2-installer](https://github.com/jessety/pm2-installer) (Windows Service) |
-
-```bash
-pm2 save        # snapshot current process list to ~/.pm2/dump.pm2
-pm2 resurrect   # restore saved list after manual daemon restart
-```