panopticon-cli 0.5.9 → 0.5.11

package/skills/plan/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: plan
+description: >
+  Opus-driven planning for issues before Sonnet implementation. Creates workspace,
+  STATE.md, plan.vbrief.json with beads, and updates issue tracker. Ensures
+  strategic decisions are made by Opus, not cheaper models.
+triggers:
+  - plan
+  - /plan
+  - create plan
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - Grep
+  - Glob
+  - ToolSearch
+version: "2.0.0"
+author: "Ed Becker"
+license: "MIT"
+---
+
+# Plan Skill
+
+**Trigger:** `/plan <issue-id>`
+
+**CRITICAL:** This skill MUST be run by Opus. The entire point is that Opus does ALL the thinking so Sonnet just executes. If you are Sonnet or Haiku, STOP and tell the user to switch to Opus.
+
+## Core Principle
+
+**Opus plans EVERYTHING. Sonnet executes.**
+
+Do NOT leave any decisions for the implementation agent. Every architectural choice, every file path, every function name, every edge case - all decided here. The implementation agent should be able to work through beads mechanically without making any design decisions.
+
+---
+
+## EXECUTION STEPS
+
+### Step 1: Parse Issue ID and Create Workspace
+
+```bash
+# PAN-XXX -> /home/eltmon/projects/panopticon (GitHub)
+# MIN-XXX -> /home/eltmon/projects/myn (Linear)
+# HH-XXX  -> /home/eltmon/projects/househunt (Linear)
+# JH-XXX  -> /home/eltmon/projects/jobhunt (Linear)
+
+# CRITICAL: Create a proper git worktree with feature branch
+# DO NOT use mkdir -p - that creates a directory without git tracking!
+cd <project>
+pan workspace <issue-id>   # Creates workspaces/feature-<id>/ with feature branch
+
+# Then create planning directory inside the workspace
+mkdir -p workspaces/feature-<issue-id-lowercase>/.planning
+```
+
+**IMPORTANT:** The `pan workspace` command creates a git worktree on a feature branch.
+This is REQUIRED so that work agents don't commit directly to main.
+If `pan workspace` fails, fix the issue before continuing.
+
+### Step 2: Fetch Issue Details
+
+**GitHub (PAN-*):** `gh issue view <number>`
+**Linear:** Use `mcp__linear__get_issue` tool
+
+Read the FULL issue. Understand what's being asked.
+
+### Step 3: Deep Discovery
+
+**YOU MUST** thoroughly explore the codebase. Use `Task` tool with `subagent_type=Explore` or manually:
+
+1. Find ALL related files:
+   - Where does the feature touch?
+   - What patterns exist?
+   - What tests exist?
+
+2. Read key files completely:
+   - Don't skim - read line by line
+   - Understand the data flow
+   - Note function signatures
+
+3. Identify:
+   - Files to create (new)
+   - Files to modify (existing)
+   - Files to delete (cleanup)
+   - Tests to write/update
+
+### Step 4: Write STATE.md
+
+Create `.planning/STATE.md` with COMPLETE planning context:
+
+```markdown
+# <issue-id>: <Title>
+
+**Status:** Plan Approved
+**Planned by:** Claude Opus 4.6
+**Date:** <date>
+
+---
+
+## Discovery Summary
+<What you learned - specific file paths, patterns, gotchas>
+
+## Key Architectural Decisions
+
+### D1: <Topic>
+**Decision:** <What we're doing>
+**Rationale:** <Why this choice, not alternatives>
+
+### D2: ...
+
+## Architecture
+
+### What's Being Changed
+<Table of components, files, and what changes>
+
+### Key Touch Points
+<Specific file:line references for important changes>
+
+## Service URLs (if applicable)
+<If this issue involves services with URLs, list them here:>
+Frontend: https://...
+API: https://...
+
+## Remaining Work
+See plan.vbrief.json for the complete bead breakdown.
+```
+
+### Step 5: Produce plan.vbrief.json
+
+Create `.planning/plan.vbrief.json` following the vBRIEF schema. This replaces the manual `bd create` loop — the Panopticon complete-planning pipeline reads this file and creates beads automatically.
+
+```json
+{
+  "vBRIEFInfo": {
+    "version": "0.5",
+    "created": "<ISO timestamp>"
+  },
+  "plan": {
+    "id": "<ISSUE-ID>",
+    "title": "<Full issue title>",
+    "status": "approved",
+    "author": "plan",
+    "tags": ["<relevant>", "<tags>"],
+    "narratives": {
+      "Problem": "<What problem this solves>",
+      "Proposal": "<How we solve it>",
+      "Constraint": "<Any constraints>",
+      "Risk": "<Key risks>",
+      "Alternative": "<What alternatives were considered>"
+    },
+    "items": [
+      {
+        "id": "<kebab-case-id>",
+        "title": "<ISSUE-ID>: <Specific task name>",
+        "status": "pending",
+        "priority": "high",
+        "metadata": {
+          "difficulty": "simple|medium|complex",
+          "issueLabel": "<issue-id-lowercase>"
+        },
+        "narrative": {
+          "Action": "<Exact what to do: file paths, function names, specific changes>"
+        },
+        "subItems": [
+          {
+            "id": "<parent-id>.<ac-name>",
+            "title": "<Specific testable acceptance criterion>",
+            "status": "pending",
+            "metadata": { "kind": "acceptance_criterion" }
+          }
+        ]
+      }
+    ],
+    "edges": [
+      {
+        "from": "<item-id>",
+        "to": "<item-id>",
+        "type": "blocks"
+      }
+    ]
+  }
+}
+```
+
+**CRITICAL vBRIEF Structure Rules:**
+
+1. **Acceptance criteria MUST be subItems, NEVER top-level items.** Each AC is nested under its parent task/requirement as a `subItems` entry. Top-level items with `kind: "acceptance_criterion"` will fail vBRIEF Studio validation.
+
+2. **Hierarchical IDs required.** SubItem IDs must use dot-notation from the parent: `parent-id.ac-name`. Example: `work-prompt-ac.injects-ac-per-bead`. The parent prefix is mandatory.
+
+3. **Only actionable tasks are top-level items.** Requirements, tasks, and architectural decisions go in `items[]`. Acceptance criteria go in `subItems[]` under their parent.
+
+4. **Every task SHOULD have at least one acceptance criterion** in `subItems` to define "done."
+
+**Bead sizing guidance:**
+- Each item should be completable in one focused session
+- Include exact file paths and function names in the Action field
+- Set `edges` to capture blocking relationships between items
+- `difficulty`: trivial (typo/config), simple (1 file), medium (2-3 files), complex (multi-system)
+- 10-40 items for a typical feature; more for large refactors
+- SubItems (acceptance criteria) are NOT converted to beads — they're verification checklists
+
+**After writing the JSON file:**
+```bash
+# Mark planning complete so the pipeline picks it up
+touch workspaces/feature-<issue-id-lowercase>/.planning/.planning-complete
+```
+
+**Cloister hand-off:** When the `.planning-complete` marker is created, Cloister automatically:
+1. Reads `plan.vbrief.json` from the workspace
+2. Calls `createBeadsFromVBrief()` to convert vBRIEF items into beads tasks
+3. Preserves dependency relationships from `edges` (blocking order)
+4. Includes acceptance criteria in bead descriptions
+5. Starts the work agent with the beads ready for implementation
+
+You do NOT need to run `bd create` manually — Cloister handles the full conversion.
+
+### Step 6: Stitch Integration (UI Work)
+
+If issue involves UI, YOU MUST use Stitch:
+
+```bash
+# Load Stitch tools
+ToolSearch query: "+stitch"
+
+# Create project
+mcp__stitch__create_project name="<issue-id>-design"
+
+# Design each screen
+mcp__stitch__generate_screen_from_text ...
+```
+
+Document all designs in `.planning/STITCH_DESIGNS.md`.
+
+### Step 7: Update Issue Tracker
+
+**GitHub (PAN-*):**
+```bash
+gh label create "planned" --color "0E8A16" 2>/dev/null || true
+gh label create "ready-for-implementation" --color "1D76DB" 2>/dev/null || true
+gh label create "opus-planned" --color "7057FF" 2>/dev/null || true
+
+gh issue edit <number> --add-label "planned,ready-for-implementation,opus-planned"
+
+gh issue comment <number> --body "## Planning Complete
+**Planned by:** Claude Opus 4.6
+**Workspace:** workspaces/feature-<issue-id>/
+
+### Beads: <N> items in plan.vbrief.json
+### Next: /work-issue <ISSUE-ID>"
+```
+
+### Step 8: Output Summary
+
+```
+## Planning Complete for <ISSUE-ID>
+
+**Workspace:** <path>
+**STATE.md:** decisions log, architecture, key touch points
+**plan.vbrief.json:** <N> items, <M> edges
+
+**Unblocked Items:**
+1. <item-id>: <title> [P<n>]
+...
+
+**Next:** /work-issue <ISSUE-ID>
+```
+
+---
+
+## Task Breakdown Templates
+
+### For Backend API Work:
+
+```
+Items:
+- Define types/interfaces in types.ts
+- Create endpoint handler function
+- Add route registration
+- Add request validation
+- Add error handling
+- Write unit tests for handler
+- Write integration tests for endpoint
+```
+
+### For React Component Work:
+
+```
+Items:
+- Create component file with shell
+- Add props interface
+- Implement render logic
+- Add state management (if needed)
+- Add event handlers
+- Style with Tailwind/CSS
+- Add loading/error states
+- Write unit tests
+- Wire into parent component
+```
+
+### For Bug Fixes:
+
+```
+Items:
+- Write failing test that reproduces bug
+- Identify root cause (document in Action field)
+- Implement fix
+- Verify test passes
+- Add regression tests
+```
+
+### For Refactoring:
+
+```
+Items:
+- Write tests for current behavior (if missing)
+- Extract function/module
+- Update all call sites
+- Run tests, fix failures
+- Remove old code
+```
+
+---
+
+## Quality Checklist
+
+Before completing /plan, verify:
+
+- [ ] STATE.md has complete discovery, decisions, and architecture
+- [ ] plan.vbrief.json is valid JSON with all required fields
+- [ ] Each item has exact file paths in Action field
+- [ ] Dependencies (edges) are set correctly
+- [ ] .planning-complete marker created
+- [ ] Issue tracker updated
+- [ ] No decisions left for implementation agent