pure-point-guard 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pure-point-guard",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "description": "Pure Point Guard — local orchestration runtime for parallel CLI coding agents",
   "bin": {

package/skills/ppg-conductor/SKILL.md

@@ -38,7 +38,7 @@ After classifying the mode:
 2. Read the CLI command reference at `~/.claude/skills/ppg-conductor/references/commands.md`
 3. Decompose the user's request into concrete tasks (names + prompts)
 4. **Spawn immediately** — do not ask for confirmation. The user invoked `/ppg` which signals intent to run.
-5. Drive the full spawn -> poll -> aggregate -> merge loop
+5. Drive the full spawn -> poll -> aggregate -> present loop
 
 ## Core Principles
 
@@ -46,7 +46,8 @@ After classifying the mode:
 - **Always use `--no-open`** to suppress Terminal.app windows (you're driving programmatically, not watching panes)
 - **Poll every 5 seconds** — `ppg status --json` in a loop until all agents reach a terminal state
 - **One concern per worktree** — in batch mode, each task gets its own isolated worktree for clean merges
-- **Surface results before merging** — always show the user what agents produced before offering to merge
+- **Surface results and let the user decide next steps** — present what agents produced, then ask: create PRs, merge directly, review diffs, or do nothing
+- **Never auto-merge or auto-PR** — always stop after presenting results and wait for the user to choose
 - **Report failures clearly** — if an agent fails, show its ID, the error, and offer to re-spawn or skip
 - **Never auto-resolve merge conflicts** — escalate to the user with the conflict details
 - **Prompt quality matters** — each agent prompt must be self-contained with full context. The agent has no memory of this conversation.

package/skills/ppg-conductor/references/commands.md

@@ -42,6 +42,7 @@ ppg spawn --name <name> --prompt-file /path/to/prompt.md --json --no-open
 ```
 
 **Options:**
+
 | Flag | Description |
 |------|-------------|
 | `-n, --name <name>` | Worktree/task name (default: auto-generated ID) |
@@ -167,6 +168,77 @@ ppg aggregate <worktree-id> --json      # Specific worktree
 
 Results come from `.pg/results/<agentId>.md`. If no result file exists, falls back to tmux pane capture.
 
+## ppg pr
+
+Create a GitHub PR from a worktree's branch. Pushes the branch to origin and runs `gh pr create`.
+
+```bash
+ppg pr <wt-id> --json                          # Create PR (title = worktree name, body = agent results)
+ppg pr <wt-id> --title "Fix auth bug" --json   # Custom title
+ppg pr <wt-id> --body "Description" --json     # Custom body
+ppg pr <wt-id> --draft --json                  # Create as draft PR
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--title <text>` | PR title (default: worktree name) |
+| `--body <text>` | PR body (default: agent result file content) |
+| `--draft` | Create as draft PR |
+| `--json` | JSON output |
+
+**JSON output:**
+```json
+{
+  "success": true,
+  "worktreeId": "wt-abc123",
+  "branch": "ppg/fix-auth-bug",
+  "baseBranch": "main",
+  "prUrl": "https://github.com/user/repo/pull/42"
+}
+```
+
+**Errors:** `WORKTREE_NOT_FOUND`, `INVALID_ARGS` (gh not installed, push failed, PR creation failed)
+
+**Notes:**
+- Requires GitHub CLI (`gh`) to be installed and authenticated
+- Stores the PR URL in the manifest (`prUrl` field on the worktree entry)
+- Does NOT merge or clean up the worktree — the branch stays alive for the PR lifecycle
+
+## ppg reset
+
+Nuclear cleanup: kill all agents, remove all worktrees, wipe manifest entries. Includes safety checks.
+
+```bash
+ppg reset --json                    # Reset (refuses if unmerged/un-PR'd work exists)
+ppg reset --force --json            # Force reset even with unmerged work
+ppg reset --force --prune --json    # Force reset + git worktree prune
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Reset even if worktrees have completed work that hasn't been merged or PR'd |
+| `--prune` | Also run `git worktree prune` |
+| `--json` | JSON output |
+
+**JSON output:**
+```json
+{
+  "success": true,
+  "killed": ["ag-xyz12345", "ag-abc67890"],
+  "removed": ["wt-abc123", "wt-def456"],
+  "warned": ["fix-auth-bug"],
+  "pruned": false
+}
+```
+
+**Safety:** Without `--force`, refuses to reset if any worktree has completed agents but no PR URL and isn't merged. This prevents accidental loss of work.
+
+**Errors:** `NOT_INITIALIZED`, `AGENTS_RUNNING` (without `--force`, when unmerged work exists)
+
 ## ppg merge
 
 Merge a worktree's branch back into its base branch. Default strategy is squash.
@@ -195,6 +267,64 @@ ppg merge <wt-id> --force --json                   # Merge even if agents aren't
 
 Cleanup sequence: kill tmux window, teardown env, `git worktree remove --force`, `git branch -D ppg/<name>`, set manifest status `cleaned`.
 
+## ppg swarm
+
+Run a predefined swarm template — spawns multiple agents from `.pg/swarms/` with prompts from `.pg/prompts/`.
+
+```bash
+# Run a swarm template (creates new worktree, spawns all agents)
+ppg swarm code-review --var CONTEXT="Review the auth module" --json --no-open
+
+# Run a swarm against an existing worktree (e.g., review a PR's worktree)
+ppg swarm code-review --worktree wt-abc123 --var CONTEXT="Review PR #42" --json --no-open
+
+# Override worktree name
+ppg swarm code-review --name "auth-review" --var CONTEXT="Review auth changes" --json --no-open
+
+# Target by worktree name
+ppg swarm code-review --worktree feature-auth --var CONTEXT="Review auth feature" --json --no-open
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-w, --worktree <ref>` | Target existing worktree by ID, name, or branch |
+| `--var <KEY=value>` | Template variable (repeatable) |
+| `-n, --name <name>` | Override worktree name (default: swarm name) |
+| `-b, --base <branch>` | Base branch for new worktree(s) |
+| `--no-open` | Suppress Terminal.app windows |
+| `--json` | JSON output |
+
+**JSON output (shared strategy):**
+```json
+{
+  "success": true,
+  "swarm": "code-review",
+  "strategy": "shared",
+  "worktree": { "id": "wt-abc123", "name": "code-review", "branch": "ppg/code-review", "path": "/path/.worktrees/wt-abc123", "tmuxWindow": "ppg-repo:1" },
+  "agents": [
+    { "id": "ag-xyz12345", "tmuxTarget": "ppg-repo:1" },
+    { "id": "ag-abc67890", "tmuxTarget": "ppg-repo:2" }
+  ]
+}
+```
+
+**Errors:** `NOT_INITIALIZED`, `INVALID_ARGS` (missing template or prompt file), `WORKTREE_NOT_FOUND`
+
+## ppg list swarms
+
+List available swarm templates.
+
+```bash
+ppg list swarms --json
+```
+
+**JSON output:**
+```json
+{ "swarms": [{ "name": "code-review", "description": "Multi-perspective code review", "strategy": "shared", "agents": 3 }] }
+```
+
 ## ppg logs
 
 View an agent's tmux pane output.
@@ -253,6 +383,7 @@ ppg wait --all --interval 10 --json      # Poll every 10s (default: 5s)
 ```
 
 **Options:**
+
 | Flag | Description |
 |------|-------------|
 | `--all` | Wait for all agents across all worktrees |
@@ -273,6 +404,7 @@ ppg send <agent-id> "C-c" --keys         # Send raw tmux keys (e.g., Ctrl-C)
 ```
 
 **Options:**
+
 | Flag | Description |
 |------|-------------|
 | `--keys` | Send raw tmux key names instead of literal text |
@@ -290,6 +422,7 @@ ppg restart <agent-id> --agent codex --json           # Override agent type
 ```
 
 **Options:**
+
 | Flag | Description |
 |------|-------------|
 | `-p, --prompt <text>` | Override the original prompt |
@@ -310,6 +443,7 @@ ppg diff <wt-id> --name-only             # Changed file names only
 ```
 
 **Options:**
+
 | Flag | Description |
 |------|-------------|
 | `--stat` | Show diffstat summary |
@@ -330,6 +464,7 @@ ppg clean --prune                        # Also run git worktree prune
 ```
 
 **Options:**
+
 | Flag | Description |
 |------|-------------|
 | `--all` | Also clean failed worktrees |

package/skills/ppg-conductor/references/conductor.md

@@ -1,6 +1,6 @@
 # Conductor Loop Protocol
 
-The conductor loop has 5 phases: Spawn, Poll, Aggregate, Merge, Summary.
+The conductor loop has 5 phases: Spawn, Poll, Aggregate, Present, Summary.
 
 ## Phase 1: Spawn
 
@@ -21,7 +21,18 @@ ppg spawn --name "<name>" --prompt "<self-contained prompt>" --json --no-open
 
 **Store a tracking table** with: worktree ID, agent IDs, name, and branch for each spawned task.
 
-For swarm mode with different prompts, spawn the first agent (creates the worktree), then use `--worktree <wt-id>` for subsequent agents:
+**Swarm templates** — If a matching swarm template exists in `.pg/swarms/`, prefer `ppg swarm` over manual multi-spawn:
+```bash
+# Use a predefined swarm template (much simpler than manual spawning)
+ppg swarm code-review --var CONTEXT="Review the auth module" --json --no-open
+
+# Run a swarm against an existing worktree (e.g., review a PR's worktree)
+ppg swarm code-review --worktree wt-abc123 --var CONTEXT="Review PR #42" --json --no-open
+```
+
+Check available swarms: `ppg list swarms --json`
+
+For **custom swarm mode** (when no template matches), spawn the first agent (creates the worktree), then use `--worktree <wt-id>` for subsequent agents:
 ```bash
 # First agent — creates the worktree
 ppg spawn --name "review" --prompt "Focus on code quality..." --json --no-open
@@ -118,40 +129,42 @@ Returns:
 - For failed agents, show what went wrong
 - Keep individual results available for the user to drill into
 
-## Phase 4: Merge (Batch Mode Only)
+## Phase 4: Present Results
+
+**Stop here and let the user decide.** Do NOT auto-merge or auto-PR.
 
-Swarm mode typically skips merge — the output is advisory. Only merge in swarm mode if agents were explicitly asked to make code changes AND the user confirms.
+**For swarm mode:**
+- Present synthesized findings
+- The output is advisory — typically no further action needed
+- If agents made code changes, ask the user what to do with them
 
 **For batch mode:**
 
-Present a merge checklist:
+Present a results table:
 ```
-Ready to merge:
-  [1] fix-auth-bug (wt-abc123) — ppg/fix-auth-bug — completed
-  [2] add-dark-mode (wt-def456) — ppg/add-dark-mode — completed
+Completed:
+  [1] fix-auth-bug (wt-abc123) — ppg/fix-auth-bug
+  [2] add-dark-mode (wt-def456) — ppg/add-dark-mode
 
-Cannot merge:
-  [3] issue-15 (wt-ghi789) — ppg/issue-15 — failed
+Failed:
+  [3] issue-15 (wt-ghi789) — ppg/issue-15
 
-Which would you like to merge? (e.g., "1,2" or "all" or "none")
+What would you like to do?
+  - Create PRs: "pr 1,2" or "pr all"
+  - Merge directly: "merge 1,2" or "merge all"
+  - Review diffs first: "diff 1"
+  - Do nothing for now
 ```
 
-Wait for user confirmation, then merge each confirmed worktree:
-
+**When the user chooses PRs:**
 ```bash
-ppg merge <wt-id> --json
+ppg pr <wt-id> --json
 ```
+This pushes the branch and creates a GitHub PR. The worktree stays alive for the PR lifecycle.
 
-Returns:
-```json
-{
-  "success": true,
-  "worktreeId": "wt-abc123",
-  "branch": "ppg/fix-auth-bug",
-  "baseBranch": "main",
-  "strategy": "squash",
-  "cleaned": true
-}
+**When the user chooses direct merge:**
+```bash
+ppg merge <wt-id> --json
 ```
 
 **Merge conflict handling:**
@@ -160,11 +173,12 @@ Returns:
 - Offer options: "resolve manually", "skip this merge", "force merge"
 - **Never auto-resolve conflicts** — the user must decide
 
-**PR alternative:** If the user prefers PRs over direct merges, use `gh pr create` instead:
+**Cleanup after PRs are merged externally:**
 ```bash
-gh pr create --head ppg/<name> --title "<title>" --body "<description from agent results>"
+ppg reset --json        # Refuses if unmerged work exists
+ppg reset --force --json  # Force cleanup
+ppg clean --json        # Clean only terminal-state worktrees
 ```
-Do NOT run `ppg merge` if creating PRs — the worktree and branch need to stay alive.
 
 ## Phase 5: Summary
 

package/skills/ppg-conductor/references/modes.md

@@ -13,12 +13,24 @@
 
 **Spawn patterns:**
 
-Option A — Single spawn with `--count` (same prompt, N agents):
+Option A — **Swarm template** (preferred when a matching template exists):
+```
+# Check available swarm templates
+ppg list swarms --json
+
+# Run a predefined swarm
+ppg swarm code-review --var CONTEXT="Review the auth module" --json --no-open
+
+# Run against an existing worktree
+ppg swarm code-review --worktree <wt-id> --var CONTEXT="Review PR #42" --json --no-open
+```
+
+Option B — Single spawn with `--count` (same prompt, N agents):
 ```
 ppg spawn --name "security-review" --prompt "Review for security vulnerabilities..." --count 3 --json --no-open
 ```
 
-Option B — Sequential spawns into same worktree (different prompts per agent):
+Option C — Sequential spawns into same worktree (different prompts per agent):
 ```
 # First spawn creates the worktree
 ppg spawn --name "pr-review" --prompt "Review code quality and readability..." --json --no-open
@@ -27,7 +39,7 @@ ppg spawn --worktree <wt-id> --prompt "Review for performance issues..." --json
 ppg spawn --worktree <wt-id> --prompt "Review test coverage gaps..." --json --no-open
 ```
 
-**Option B is preferred** when each agent needs a distinct prompt (which is almost always the case).
+**Option A is preferred** when a matching swarm template exists. **Option C is preferred** for custom swarm workflows where each agent needs a distinct prompt.
 
 **Post-completion:**
 1. Aggregate all results: `ppg aggregate --all --json`
@@ -69,11 +81,14 @@ Each command creates a separate worktree on its own `ppg/<name>` branch.
 **Post-completion:**
 1. Aggregate results: `ppg aggregate --all --json`
 2. Present a summary table: task name, status, branch, key findings
-3. Present a **merge checklist** — list each worktree with its status and ask which to merge
-4. Merge confirmed ones: `ppg merge <wt-id> --json` (squash by default)
-5. Optionally create PRs: `gh pr create --head ppg/<name> --title "..." --body "..."` (if user wants PRs instead of direct merges)
-
-**Important:** In batch mode, always surface results and get user confirmation before merging. The user may want to review diffs, skip some tasks, or create PRs instead.
+3. **Stop and ask the user what to do next.** Options:
+   - Create PRs: `ppg pr <wt-id> --json` (pushes branch, creates GitHub PR)
+   - Merge directly: `ppg merge <wt-id> --json` (squash by default)
+   - Review diffs first: `ppg diff <wt-id> --json`
+   - Do nothing — leave worktrees for manual review
+4. After PRs are merged externally: `ppg reset --json` to clean up
+
+**Important:** Never auto-merge or auto-PR. Always present results and let the user choose the next step.
 
 ## GitHub Issue Integration