pure-point-guard 0.1.0

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

@@ -0,0 +1,248 @@
+# ppg CLI Command Reference
+
+Quick reference for all ppg commands relevant to conductor workflows. Always use `--json` for machine-readable output.
+
+## ppg init
+
+Initialize ppg in the current git repository. Creates `.pg/` directory structure, default config, empty manifest, and sample template.
+
+```bash
+ppg init --json
+```
+
+**JSON output:**
+```json
+{ "success": true, "projectRoot": "/path/to/repo", "sessionName": "ppg-repo", "pgDir": "/path/to/repo/.pg" }
+```
+
+**Errors:** `NOT_GIT_REPO`, `TMUX_NOT_FOUND`
+
+## ppg spawn
+
+Spawn a new worktree with agent(s), or add agents to an existing worktree.
+
+```bash
+# New worktree + agent
+ppg spawn --name <name> --prompt <text> --json --no-open
+
+# Multiple agents in new worktree (same prompt)
+ppg spawn --name <name> --prompt <text> --count <n> --json --no-open
+
+# Add agent to existing worktree (different prompt)
+ppg spawn --worktree <wt-id> --prompt <text> --json --no-open
+
+# Specify base branch
+ppg spawn --name <name> --prompt <text> --base <branch> --json --no-open
+
+# Use a template
+ppg spawn --name <name> --template <template-name> --var KEY=value --json --no-open
+
+# Use a prompt file
+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) |
+| `-a, --agent <type>` | Agent type from config (default: `claude`) |
+| `-p, --prompt <text>` | Inline prompt text |
+| `-f, --prompt-file <path>` | Path to file containing prompt |
+| `-t, --template <name>` | Template name from `.pg/templates/` |
+| `--var <KEY=value>` | Template variable (repeatable) |
+| `-b, --base <branch>` | Base branch (default: current branch) |
+| `-w, --worktree <id>` | Add agent to existing worktree instead of creating new one |
+| `-c, --count <n>` | Number of agents to spawn (default: 1) |
+| `--no-open` | Suppress Terminal.app window |
+| `--json` | JSON output |
+
+**JSON output (new worktree):**
+```json
+{
+  "success": true,
+  "worktree": { "id": "wt-abc123", "name": "task-name", "branch": "ppg/task-name", "path": "/path/.worktrees/wt-abc123", "tmuxWindow": "ppg-repo:1" },
+  "agents": [{ "id": "ag-xyz12345", "tmuxTarget": "ppg-repo:1" }]
+}
+```
+
+**JSON output (existing worktree):**
+```json
+{
+  "success": true,
+  "worktree": { "id": "wt-abc123", "name": "task-name" },
+  "agents": [{ "id": "ag-new12345", "tmuxTarget": "%16" }]
+}
+```
+
+**Errors:** `NOT_INITIALIZED`, `WORKTREE_NOT_FOUND` (when using `--worktree`)
+
+## ppg status
+
+Show status of all worktrees and agents. Refreshes agent statuses from tmux before returning.
+
+```bash
+ppg status --json                    # All worktrees
+ppg status <worktree-id> --json      # Specific worktree
+```
+
+**JSON output:**
+```json
+{
+  "session": "ppg-repo",
+  "worktrees": {
+    "wt-abc123": {
+      "id": "wt-abc123",
+      "name": "task-name",
+      "path": "/path/.worktrees/wt-abc123",
+      "branch": "ppg/task-name",
+      "baseBranch": "main",
+      "status": "active",
+      "tmuxWindow": "ppg-repo:1",
+      "agents": {
+        "ag-xyz12345": {
+          "id": "ag-xyz12345",
+          "name": "claude",
+          "agentType": "claude",
+          "status": "running",
+          "tmuxTarget": "ppg-repo:1",
+          "prompt": "...",
+          "resultFile": "/path/.pg/results/ag-xyz12345.md",
+          "startedAt": "2025-01-01T00:00:00.000Z"
+        }
+      },
+      "createdAt": "2025-01-01T00:00:00.000Z"
+    }
+  }
+}
+```
+
+**Agent statuses:** `spawning` | `running` | `waiting` | `completed` | `failed` | `killed` | `lost`
+**Worktree statuses:** `active` | `merging` | `merged` | `failed` | `cleaned`
+
+## ppg kill
+
+Kill running agents. Can target a single agent, all agents in a worktree, or everything.
+
+```bash
+ppg kill --agent <agent-id> --json               # Kill one agent
+ppg kill --worktree <wt-id> --json               # Kill all agents in worktree
+ppg kill --worktree <wt-id> --remove --json      # Kill + remove worktree
+ppg kill --all --json                            # Kill everything
+ppg kill --all --remove --json                   # Kill everything + cleanup
+```
+
+**JSON output:**
+```json
+{ "success": true, "killed": ["ag-xyz12345"], "removed": false }
+```
+
+## ppg aggregate
+
+Collect result files from completed agents.
+
+```bash
+ppg aggregate --all --json              # All worktrees
+ppg aggregate <worktree-id> --json      # Specific worktree
+```
+
+**JSON output:**
+```json
+{
+  "results": [
+    {
+      "agentId": "ag-xyz12345",
+      "worktreeId": "wt-abc123",
+      "worktreeName": "task-name",
+      "branch": "ppg/task-name",
+      "status": "completed",
+      "content": "Full text content of the agent's result file..."
+    }
+  ]
+}
+```
+
+Results come from `.pg/results/<agentId>.md`. If no result file exists, falls back to tmux pane capture.
+
+## ppg merge
+
+Merge a worktree's branch back into its base branch. Default strategy is squash.
+
+```bash
+ppg merge <wt-id> --json                          # Squash merge + cleanup
+ppg merge <wt-id> --strategy no-ff --json          # Merge commit (preserves history)
+ppg merge <wt-id> --no-cleanup --json              # Merge but keep worktree alive
+ppg merge <wt-id> --dry-run                        # Preview without doing anything
+ppg merge <wt-id> --force --json                   # Merge even if agents aren't done
+```
+
+**JSON output:**
+```json
+{
+  "success": true,
+  "worktreeId": "wt-abc123",
+  "branch": "ppg/task-name",
+  "baseBranch": "main",
+  "strategy": "squash",
+  "cleaned": true
+}
+```
+
+**Errors:** `WORKTREE_NOT_FOUND`, merge conflict (git error), agents still running (without `--force`)
+
+Cleanup sequence: kill tmux window, teardown env, `git worktree remove --force`, `git branch -D ppg/<name>`, set manifest status `cleaned`.
+
+## ppg logs
+
+View an agent's tmux pane output.
+
+```bash
+ppg logs <agent-id> --json                 # Last 100 lines
+ppg logs <agent-id> --lines 500 --json     # Last 500 lines
+ppg logs <agent-id> --full --json          # Full history
+```
+
+**JSON output:**
+```json
+{ "agentId": "ag-xyz12345", "status": "running", "tmuxTarget": "ppg-repo:1", "output": "pane content..." }
+```
+
+## ppg worktree create
+
+Create a standalone worktree without spawning any agents. Useful when you want to set up the worktree first, then add agents later.
+
+```bash
+ppg worktree create --name <name> --json
+ppg worktree create --name <name> --base <branch> --json
+```
+
+**JSON output:**
+```json
+{
+  "success": true,
+  "worktree": { "id": "wt-abc123", "name": "task-name", "branch": "ppg/task-name", "baseBranch": "main", "path": "/path/.worktrees/wt-abc123" }
+}
+```
+
+## ppg list templates
+
+List available prompt templates.
+
+```bash
+ppg list templates --json
+```
+
+**JSON output:**
+```json
+{ "templates": [{ "name": "default", "description": "Task template", "variables": ["TASK_NAME", "PROMPT", "WORKTREE_PATH"] }] }
+```
+
+## Error Codes
+
+| Code | Meaning | Recovery |
+|------|---------|----------|
+| `TMUX_NOT_FOUND` | tmux not installed | Fatal — user must install tmux |
+| `NOT_GIT_REPO` | Not inside a git repository | Fatal — user must cd to a repo |
+| `NOT_INITIALIZED` | `.pg/` directory missing | Auto-fix: run `ppg init --json` |
+| `MANIFEST_LOCK` | Could not acquire manifest lock | Retry after brief delay (rare) |
+| `WORKTREE_NOT_FOUND` | Worktree ID/name not in manifest | Check `ppg status --json` for valid IDs |
+| `AGENT_NOT_FOUND` | Agent ID not in manifest | Check `ppg status --json` for valid IDs |

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

@@ -0,0 +1,183 @@
+# Conductor Loop Protocol
+
+The conductor loop has 5 phases: Spawn, Poll, Aggregate, Merge, Summary.
+
+## Phase 1: Spawn
+
+For each task, run `ppg spawn` and capture the JSON output.
+
+```bash
+ppg spawn --name "<name>" --prompt "<self-contained prompt>" --json --no-open
+```
+
+**Track the output.** Each spawn returns:
+```json
+{
+  "success": true,
+  "worktree": { "id": "wt-abc123", "name": "task-name", "branch": "ppg/task-name", "path": "/path/to/.worktrees/wt-abc123", "tmuxWindow": "ppg-project:1" },
+  "agents": [{ "id": "ag-xyz12345", "tmuxTarget": "ppg-project:1" }]
+}
+```
+
+**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:
+```bash
+# First agent — creates the worktree
+ppg spawn --name "review" --prompt "Focus on code quality..." --json --no-open
+# Additional agents — join existing worktree
+ppg spawn --worktree wt-abc123 --prompt "Focus on security..." --json --no-open
+ppg spawn --worktree wt-abc123 --prompt "Focus on performance..." --json --no-open
+```
+
+**Error handling during spawn:**
+- If spawn fails, report the error and continue with remaining tasks
+- Common errors: `NOT_INITIALIZED` (auto-fix with `ppg init`), `TMUX_NOT_FOUND` (fatal — tell user to install tmux)
+
+## Phase 2: Poll
+
+Poll `ppg status --json` every 5 seconds until all agents reach a terminal state.
+
+```bash
+ppg status --json
+```
+
+Returns:
+```json
+{
+  "session": "ppg-project",
+  "worktrees": {
+    "wt-abc123": {
+      "id": "wt-abc123",
+      "name": "task-name",
+      "status": "active",
+      "branch": "ppg/task-name",
+      "agents": {
+        "ag-xyz12345": {
+          "id": "ag-xyz12345",
+          "status": "running",
+          "agentType": "claude",
+          "startedAt": "2025-01-01T00:00:00.000Z"
+        }
+      }
+    }
+  }
+}
+```
+
+**Terminal states** for agents: `completed`, `failed`, `killed`, `lost`
+**Non-terminal states**: `spawning`, `running`, `waiting`
+
+**Polling behavior:**
+- Show a brief status update each cycle: `"Polling... 2/5 agents completed, 3 running"`
+- After **2 minutes**: mention that agents are still running and show elapsed time
+- After **10 minutes**: warn the user and offer to continue waiting or kill remaining agents
+- On `failed` or `lost`: immediately report the agent ID and worktree, offer to re-spawn or skip
+
+**Stop polling when:** all tracked agents are in terminal states.
+
+## Phase 3: Aggregate
+
+Collect results from completed agents.
+
+```bash
+ppg aggregate --all --json
+```
+
+Returns:
+```json
+{
+  "results": [
+    {
+      "agentId": "ag-xyz12345",
+      "worktreeId": "wt-abc123",
+      "worktreeName": "task-name",
+      "branch": "ppg/task-name",
+      "status": "completed",
+      "content": "## Results\n\nThe agent's output from its result file..."
+    }
+  ]
+}
+```
+
+**For swarm mode:**
+- Read all results
+- Identify common themes, agreements, and conflicts across agents
+- Synthesize into a unified summary with attribution (which agent said what)
+- Highlight any disagreements between agents
+
+**For batch mode:**
+- Present a table: task name | status | branch | brief summary of result
+- For failed agents, show what went wrong
+- Keep individual results available for the user to drill into
+
+## Phase 4: Merge (Batch Mode Only)
+
+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 batch mode:**
+
+Present a merge checklist:
+```
+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
+
+Cannot merge:
+  [3] issue-15 (wt-ghi789) — ppg/issue-15 — failed
+
+Which would you like to merge? (e.g., "1,2" or "all" or "none")
+```
+
+Wait for user confirmation, then merge each confirmed worktree:
+
+```bash
+ppg merge <wt-id> --json
+```
+
+Returns:
+```json
+{
+  "success": true,
+  "worktreeId": "wt-abc123",
+  "branch": "ppg/fix-auth-bug",
+  "baseBranch": "main",
+  "strategy": "squash",
+  "cleaned": true
+}
+```
+
+**Merge conflict handling:**
+- If `ppg merge` fails, capture the error
+- Report the conflict to the user with: branch name, conflicting files if available
+- 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:
+```bash
+gh pr create --head ppg/<name> --title "<title>" --body "<description from agent results>"
+```
+Do NOT run `ppg merge` if creating PRs — the worktree and branch need to stay alive.
+
+## Phase 5: Summary
+
+Present a final summary covering the entire run:
+
+**For swarm mode:**
+```
+## Swarm Summary
+- Subject: <what was reviewed/analyzed>
+- Agents: N spawned, N completed, N failed
+- Key findings: <synthesized highlights>
+```
+
+**For batch mode:**
+```
+## Batch Summary
+- Tasks: N spawned, N completed, N failed
+- Merged: N worktrees into <base-branch>
+- Skipped: N (list reasons)
+- PRs created: N (if applicable)
+```
+
+Include any follow-up actions the user might want to take.

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

@@ -0,0 +1,85 @@
+# Conductor Modes
+
+## Swarm Mode — Multiple Agents, One Worktree
+
+**Trigger signals:** "review", "audit", "analyze", "perspectives", "opinions", "critique", "evaluate", "assess", "examine", "check from multiple angles"
+
+**Concept:** Multiple agents work on the SAME codebase in the SAME worktree. Each agent brings a different perspective or focus area. Their outputs are aggregated and synthesized — no merge needed because they produce analysis, not code changes.
+
+**Task decomposition:**
+1. Identify the subject (PR, file, module, system)
+2. Define N perspectives — each gets a unique angle and prompt
+3. Each prompt should specify: what to focus on, what format to produce results in, and what the result file should contain
+
+**Spawn patterns:**
+
+Option A — 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):
+```
+# First spawn creates the worktree
+ppg spawn --name "pr-review" --prompt "Review code quality and readability..." --json --no-open
+# Capture worktree ID from JSON output, then:
+ppg spawn --worktree <wt-id> --prompt "Review for performance issues..." --json --no-open
+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).
+
+**Post-completion:**
+1. Aggregate all results: `ppg aggregate --all --json`
+2. Synthesize findings — identify common themes, conflicts, and unique insights
+3. Present a unified summary to the user
+4. Typically NO merge — swarm output is advisory. If agents did make code changes, ask the user before merging.
+
+**Suggested swarm sizes:**
+- Code review: 3-4 agents (quality, security, performance, testing)
+- Architecture review: 3 agents (design patterns, scalability, maintainability)
+- Bug hunt: 2-3 agents (different hypotheses about root cause)
+
+## Batch Mode — One Worktree Per Task
+
+**Trigger signals:** "issues", "tickets", "tasks", "fix all", "one PR per", "implement these features", "work on #N", "tackle", "each in its own branch"
+
+**Concept:** Each task gets its own isolated worktree and branch. Agents work independently on separate concerns. Each completed worktree can be merged individually, becoming its own commit (or PR if the user wants).
+
+**Task decomposition:**
+1. Gather the list of tasks — from GitHub issues, user description, or codebase analysis
+2. For each task, define:
+   - **name**: Short kebab-case identifier (e.g., `fix-auth-bug`, `add-dark-mode`, `issue-15`)
+   - **prompt**: Self-contained description with full context. The agent knows nothing about the other tasks or this conversation.
+3. Each prompt MUST include:
+   - What to do (the task)
+   - Where to find relevant code (files, modules, patterns)
+   - What "done" looks like (acceptance criteria)
+   - Instruction to write results to `{{RESULT_FILE}}`
+
+**Spawn pattern:**
+```
+ppg spawn --name "fix-auth-bug" --prompt "Fix the authentication bug where..." --json --no-open
+ppg spawn --name "add-dark-mode" --prompt "Implement dark mode toggle..." --json --no-open
+ppg spawn --name "issue-15" --prompt "Resolve issue #15: ..." --json --no-open
+```
+
+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.
+
+## GitHub Issue Integration
+
+When the user references GitHub issues (e.g., `#12`, `#15`):
+
+1. Fetch issue details: `gh issue view <number> --json title,body,labels,assignees`
+2. Use the issue title and body as context for the agent prompt
+3. Name the worktree after the issue: `issue-<number>`
+4. After merge, optionally close the issue: `gh issue close <number>` (ask the user first)