@overdeck/desktop 0.45.22 → 0.45.23

package/sync-sources/skills/write-vbrief/SKILL.md

@@ -1,292 +1,17 @@
 ---
 name: write-vbrief
-description: >
-  Write a vBRIEF spec (.pan/spec.vbrief.json) and continue.json directly — without
-  launching the interactive planning agent. Use when the work is well-understood
-  and the agent can author the plan from the issue body and codebase alone.
-  Also use when you ARE the work agent and need to self-plan before implementing.
-  Covers the full xBRIEF v0.8 schema, continue.json format, task sizing rules,
-  inspection gates, and the `pan plan finalize` handoff command.
+description: "Compatibility redirect: /write-vbrief has been renamed to /write-xbrief"
 triggers:
+  - /write-vbrief
   - write vbrief
   - create vbrief
-  - write spec.vbrief.json
-  - skip planning agent
-  - self-plan
-  - author plan
-  - create plan manually
-  - write plan without planning agent
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Grep
-  - Glob
+allowed-tools: []
 ---
 
-# Write vBRIEF — Direct Plan Authoring
+# /write-vbrief renamed to /write-xbrief
 
-Use this skill when you want to author a vBRIEF plan directly, bypassing the interactive planning agent. This is appropriate when:
+This compatibility stub preserves the former skill name. Use `/write-xbrief` for direct xBRIEF plan authoring.
 
-- The work is well-scoped and doesn't need a Q&A discovery session
-- You are a work agent that received an issue without a pre-existing plan
-- The issue is small enough that a full planning session would cost more than the work itself
-- You need to rewrite or patch a broken vBRIEF before continuing work
+If this skill is invoked, stop reading this file and invoke `/write-xbrief` so the current xBRIEF v0.8 schema, task rules, and finalization guidance load.
 
-After writing the plan, run `pan plan finalize` to materialize vBRIEF tasks and promote the spec to main.
-
----
-
-## Step 1 — Explore First
-
-Before writing a single line of JSON, read the issue and explore the relevant code. A plan written without codebase context will have wrong file paths, wrong difficulty estimates, and spurious edges.
-
-Minimum exploration:
-- Read the issue body and any linked PRDs in `<projectRoot>/.pan/drafts/<ISSUE-ID>.md`
-- Grep for the primary symbols, commands, or files the issue mentions
-- Identify which subsystems are affected and how many files will change
-- Check for existing specs: `find <projectRoot>/.pan/specs -name "*<issue-id>*"`
-
----
-
-## Step 2 — Write `.pan/spec.vbrief.json`
-
-The file goes at `.pan/spec.vbrief.json` in the workspace root. It MUST conform to xBRIEF v0.8.
-
-### Full schema
-
-```json
-{
-  "xBRIEFInfo": {
-    "version": "0.8",
-    "created": "<ISO 8601 timestamp>",
-    "author": "overdeck/<VERSION>",
-    "description": "Plan for <ISSUE-ID>: <issue title>"
-  },
-  "plan": {
-    "id": "<issue-id-lowercase>",
-    "title": "<issue title>",
-    "status": "approved",
-    "uid": "<UUID v4>",
-    "author": "agent:<model-slug>",
-    "sequence": 1,
-    "created": "<ISO 8601 timestamp>",
-    "updated": "<ISO 8601 timestamp>",
-    "references": [
-      { "uri": "<issue URL>", "label": "<ISSUE-ID>", "type": "issue" }
-    ],
-    "tags": ["<relevant tags>"],
-    "narratives": {
-      "Problem": "<what problem this solves>",
-      "Proposal": "<the approach chosen>",
-      "NonGoals": "<explicitly out of scope; behaviors this issue must NOT introduce — one per line, prefixed '- '>"
-    },
-    "autoDecisions": [],
-    "items": [
-      {
-        "id": "<short-kebab-id>",
-        "title": "<task title>",
-        "status": "pending",
-        "priority": "medium",
-        "created": "<ISO 8601 timestamp>",
-        "metadata": {
-          "difficulty": "trivial|simple|medium|complex|expert",
-          "issueLabel": "<issue-id-lowercase>",
-          "requiresInspection": false,
-          "inspectionDepth": "fast",
-          "files_scope": ["src/path/to/file.ts"],
-          "files_scope_confidence": "high",
-          "verify_commands": ["npm run typecheck"],
-          "expected_outputs": ["typecheck completes without errors"],
-          "readiness": "ready",
-          "traces": ["FR-1", "NFR-2"]
-        },
-        "narrative": { "Action": "<what needs to be done>" },
-        "items": [
-          {
-            "id": "<parent-id>.ac1",
-            "title": "<specific testable acceptance criterion>",
-            "status": "pending",
-            "metadata": { "kind": "acceptance_criterion" }
-          }
-        ]
-      }
-    ],
-    "edges": [
-      { "from": "<source-item-id>", "to": "<target-item-id>", "type": "blocks" }
-    ]
-  }
-}
-```
-
-### Field rules
-
-| Field | Rule |
-|-------|------|
-| `plan.id` | Issue ID in **lowercase** — e.g. `"pan-1234"`. Never `issueId`, never `issue_id`. |
-| `plan.uid` | Fresh UUID v4. Generate with `node -e "console.log(crypto.randomUUID())"`. |
-| `plan.status` | Must be `"approved"` when written by a self-planning agent (skip `draft`/`proposed`). |
-| `items[].status` | One of: `draft`, `proposed`, `approved`, `pending`, `running`, `completed`, `blocked`, `cancelled`, `failed`. Use `"pending"` for new items. |
-| `plan.narratives.NonGoals` | Required narrative. List everything discovery established as out of scope (`"none"` if genuinely nothing); review enforces these as must-not constraints. |
-| `items[].metadata.requiresInspection` | **Required on every item.** See inspection rules below. |
-| `items[].metadata.inspectionDepth` | `"fast"` (default) or `"deep"`. Only matters when `requiresInspection: true`. |
-| `items[].metadata.files_scope` | Required `string[]` of files/globs this item is expected to touch. Use concrete paths or narrow globs, not broad repo-wide patterns. |
-| `items[].metadata.files_scope_confidence` | Required confidence in `files_scope`: `"high"`, `"medium"`, or `"low"`. |
-| `items[].metadata.verify_commands` | Required for slot-eligible items. List commands that verify this item before slot merge, e.g. `["npm run typecheck", "npx vitest run tests/unit/foo.test.ts"]`. |
-| `items[].metadata.expected_outputs` | Required for slot-eligible items. List the observable evidence expected from `verify_commands`, e.g. `["foo.test.ts passes"]`. |
-| `items[].metadata.readiness` | Required tri-state swarm readiness: `"ready"` for parallel-safe work, `"sequential"` for intentionally serialized work, `"needs_refinement"` when the item is not ready to dispatch. |
-| `items[].metadata.traces` | Optional `string[]` of PRD requirement IDs (`FR-1`, `NFR-2`) this item satisfies. |
-| nested `items` with `metadata.kind: "acceptance_criterion"` | Each item must have at least one acceptance-criterion child item. |
-
----
-
-## Step 3 — Write `.pan/continue.json`
-
-The continue file records decisions and hazards so the work agent (and review/test agents) have context that isn't in the vBRIEF narrative.
-
-```json
-{
-  "version": "1",
-  "issueId": "<ISSUE-ID-UPPERCASE>",
-  "created": "<ISO 8601 timestamp>",
-  "updated": "<ISO 8601 timestamp>",
-  "gitState": { "branch": "<current branch>", "sha": "<short sha>", "dirty": false },
-  "decisions": [
-    { "id": "D1", "summary": "<decision text>", "recordedAt": "<ISO 8601 timestamp>" }
-  ],
-  "hazards": [
-    { "id": "H1", "summary": "<risk or edge case>", "mitigation": "<how to handle it>" }
-  ],
-  "resumePoint": null,
-  "vBRIEF tasksMapping": {},
-  "agentModel": "agent:<model-slug>",
-  "sessionHistory": [
-    {
-      "timestamp": "<ISO 8601 timestamp>",
-      "reason": "planning",
-      "note": "Self-authored plan (no planning agent)",
-      "agentModel": "agent:<model-slug>"
-    }
-  ]
-}
-```
-
-Rules:
-- `version` must be `"1"`
-- `issueId` must be uppercase (e.g. `"PAN-1234"`)
-- `resumePoint` stays `null` — the work agent populates it when it begins
-- `vBRIEF tasksMapping` stays `{}` — `pan plan finalize` populates it
-
----
-
-## Step 4 — Finalize
-
-From the workspace root, run:
-
-```bash
-pan plan finalize
-```
-
-This atomically:
-1. Reads `.pan/spec.vbrief.json`
-2. Creates vBRIEF tasks through the canonical writer (one per `items[]` entry, edges respected)
-3. Sets `plan.status` to `"proposed"`
-4. Promotes the canonical spec into `<projectRoot>/.pan/specs/<YYYY-MM-DD>-<ISSUE>-<slug>.vbrief.json`
-5. Commits on main, pushes, transitions the tracker issue to Planned
-
-
----
-
-## Task sizing rules
-
-Default to **many small vBRIEF tasks** over a few large ones. A well-sized task:
-
-- Has one focused change (if you need "and" in the title, it's two vBRIEF tasks)
-- Is independently reviewable from its diff alone
-- Leaves the tree in a working state if merged alone
-- Has a testable acceptance criterion
-
-**Heuristics:**
-- One renamed command = one task
-- One moved file = one task (unless mechanically identical batch → sub-items under one task)
-- One new API endpoint = one task
-- One schema migration = one task
-- One doc update = one task (or one per logical cluster, not "update all docs")
-
-When in doubt, split. Too-small vBRIEF tasks: mild overhead. Too-large vBRIEF tasks: reviewers can't reason about them, agents deliver partial results, and the inspection gate can't verify mid-implementation.
-
----
-
-## Edge semantics
-
-Add an edge only when there is a **real** dependency:
-
-| When to add `blocks` edge | When NOT to add |
-|---------------------------|-----------------|
-| B consumes a file/type/value A produces | Narrative flow ("feels like it should come second") |
-| Both items modify the same file | Readability preference |
-| B can't start until A reaches a specific state | Defensive sequencing "just in case" |
-
-Absent edges = permission for the work agent to run items in parallel. A spurious edge silently forces serialization that was never intended.
-
-Edge types: `blocks` (hard), `informs` (soft/advisory), `invalidates`, `suggests`
-
----
-
-## Inspection gate (`requiresInspection`)
-
-Set `requiresInspection: true` **only** when a wrong implementation would cascade into downstream vBRIEF tasks before the verification gate catches it:
-
-- **Foundation for downstream vBRIEF tasks** — subsequent vBRIEF tasks depend on this task's interfaces, types, or module boundaries
-- **Architectural decision crystallizing in code** — naming a public API, choosing a library boundary, picking an event shape
-- **Spec ambiguity risk** — the description is broad enough that two very different diffs could both look "done"
-- **Security/auth surface** — defects here propagate into later vBRIEF tasks assuming the security posture
-- **Cross-cutting protocol or schema** — wire format, DB migration, RPC contract, event payload
-
-Set `requiresInspection: false` for:
-- Mechanical changes (flag flip, rename, single-file tweak)
-- Leaf vBRIEF tasks (no downstream task depends on their internals)
-- Tests, docs, comment-only updates
-- Wrongs that surface immediately at typecheck/lint
-
-When `requiresInspection: true`, you **must** also set `metadata.foundationFor: ["<task-id>", ...]` listing the downstream vBRIEF tasks that would need to be redone if this one were wrong. An empty `foundationFor` on an inspection task is a planning error — flip it back to `false`.
-
-Most plans have 0–2 inspection vBRIEF tasks. More than 3 suggests the vBRIEF tasks are too large.
-
----
-
-## Difficulty rubric
-
-| Level | When | Typical model |
-|-------|------|---------------|
-| `trivial` | Typo, comment, formatting only | haiku |
-| `simple` | Bug fix, single file, obvious change | haiku |
-| `medium` | New feature, 3–5 files, standard patterns | sonnet |
-| `complex` | Refactor, migration, 6+ files, some risk | sonnet |
-| `expert` | Architecture, security, performance, high risk | opus |
-
----
-
-## Quick checklist
-
-Before running `pan plan finalize`:
-
-- [ ] `.pan/spec.vbrief.json` has exactly two top-level keys: `xBRIEFInfo` and `plan`
-- [ ] `plan.id` is lowercase issue ID
-- [ ] `plan.uid` is a fresh UUID v4
-- [ ] `plan.status` is `"approved"`
-- [ ] Every item has `metadata.requiresInspection` (boolean)
-- [ ] Every item has `metadata.files_scope`, `metadata.files_scope_confidence`, and `metadata.readiness`
-- [ ] Every slot-eligible item has `metadata.verify_commands` and `metadata.expected_outputs`
-- [ ] Every item has at least one nested `items` AC entry
-- [ ] `foundationFor` populated on every `requiresInspection: true` item
-- [ ] No spurious edges
-- [ ] `.pan/continue.json` written with at least one `decisions[]` entry
-
----
-
-## See also
-
-- `docs/VBRIEF.md` — full schema reference and lifecycle states
-- `/pan-plan` — start the interactive planning agent instead
-- `pan plan finalize --help` — finalization flags
+Do not author a plan from this stub. The canonical instructions live in `sync-sources/skills/write-xbrief/SKILL.md`.

package/sync-sources/skills/write-xbrief/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: write-xbrief
+description: >
+  Write an xBRIEF spec and continue.json directly — without launching the interactive
+  planning agent. The workspace working copy deliberately remains .pan/spec.vbrief.json
+  for legacy compatibility. Use when the work is well-understood
+  and the agent can author the plan from the issue body and codebase alone.
+  Also use when you ARE the work agent and need to self-plan before implementing.
+  Covers the full xBRIEF v0.8 schema, continue.json format, task sizing rules,
+  inspection gates, and the `pan plan finalize` handoff command.
+triggers:
+  - write xbrief
+  - create xbrief
+  - write spec.vbrief.json
+  - skip planning agent
+  - self-plan
+  - author plan
+  - create plan manually
+  - write plan without planning agent
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Grep
+  - Glob
+---
+
+# Write xBRIEF — Direct Plan Authoring
+
+Use this skill when you want to author an xBRIEF plan directly, bypassing the interactive planning agent. This is appropriate when:
+
+- The work is well-scoped and doesn't need a Q&A discovery session
+- You are a work agent that received an issue without a pre-existing plan
+- The issue is small enough that a full planning session would cost more than the work itself
+- You need to rewrite or patch a broken xBRIEF before continuing work
+
+After writing the plan, run `pan plan finalize` to materialize xBRIEF tasks and promote the spec to the canonical state worktree.
+
+---
+
+## Step 1 — Explore First
+
+Before writing a single line of JSON, read the issue and explore the relevant code. A plan written without codebase context will have wrong file paths, wrong difficulty estimates, and spurious edges.
+
+Minimum exploration:
+- Read the issue body and the canonical PRD at `${OVERDECK_HOME}/state/<project>/drafts/<issue-id-lowercase>.md`
+- Grep for the primary symbols, commands, or files the issue mentions
+- Identify which subsystems are affected and how many files will change
+- Check `${OVERDECK_HOME}/state/<project>/specs/` for an existing issue spec
+
+---
+
+## Step 2 — Write `.pan/spec.vbrief.json`
+
+The file goes at `.pan/spec.vbrief.json` in the workspace root and MUST conform to xBRIEF v0.8. This workspace-only filename is a deliberate legacy-compatibility path; finalized canonical specs use the `.xbrief.json` extension.
+
+### Full schema
+
+```json
+{
+  "xBRIEFInfo": {
+    "version": "0.8",
+    "created": "<ISO 8601 timestamp>",
+    "author": "overdeck/<VERSION>",
+    "description": "Plan for <ISSUE-ID>: <issue title>"
+  },
+  "plan": {
+    "id": "<issue-id-lowercase>",
+    "title": "<issue title>",
+    "status": "approved",
+    "uid": "<UUID v4>",
+    "author": "agent:<model-slug>",
+    "sequence": 1,
+    "created": "<ISO 8601 timestamp>",
+    "updated": "<ISO 8601 timestamp>",
+    "references": [
+      { "uri": "<issue URL>", "label": "<ISSUE-ID>", "type": "issue" }
+    ],
+    "tags": ["<relevant tags>"],
+    "narratives": {
+      "Problem": "<what problem this solves>",
+      "Proposal": "<the approach chosen>",
+      "NonGoals": "<explicitly out of scope; behaviors this issue must NOT introduce — one per line, prefixed '- '>"
+    },
+    "autoDecisions": [],
+    "items": [
+      {
+        "id": "<short-kebab-id>",
+        "title": "<task title>",
+        "status": "pending",
+        "priority": "medium",
+        "created": "<ISO 8601 timestamp>",
+        "metadata": {
+          "difficulty": "trivial|simple|medium|complex|expert",
+          "kind": "docs|api|backend|frontend|infra|test|refactor|design|spike",
+          "issueLabel": "<issue-id-lowercase>",
+          "requiresInspection": false,
+          "inspectionDepth": "fast",
+          "files_scope": ["src/path/to/file.ts"],
+          "files_scope_confidence": "high",
+          "verify_commands": ["npm run typecheck"],
+          "expected_outputs": ["typecheck completes without errors"],
+          "readiness": "ready",
+          "traces": ["FR-1", "NFR-2"]
+        },
+        "narrative": { "Action": "<what needs to be done>" },
+        "items": [
+          {
+            "id": "<parent-id>.ac1",
+            "title": "<specific testable acceptance criterion>",
+            "status": "pending",
+            "metadata": { "kind": "acceptance_criterion" }
+          }
+        ]
+      }
+    ],
+    "edges": [
+      { "from": "<source-item-id>", "to": "<target-item-id>", "type": "blocks" }
+    ]
+  }
+}
+```
+
+### Field rules
+
+| Field | Rule |
+|-------|------|
+| `plan.id` | Issue ID in **lowercase** — e.g. `"pan-1234"`. Never `issueId`, never `issue_id`. |
+| `plan.uid` | Fresh UUID v4. Generate with `node -e "console.log(crypto.randomUUID())"`. |
+| `plan.status` | Must be `"approved"` when written by a self-planning agent (skip `draft`/`proposed`). |
+| `items[].status` | One of: `draft`, `proposed`, `approved`, `pending`, `running`, `completed`, `blocked`, `cancelled`, `failed`. Use `"pending"` for new items. |
+| `items[].metadata.kind` | Required routing category: `docs`, `api`, `backend`, `frontend`, `infra`, `test`, `refactor`, `design`, or `spike`. |
+| `plan.narratives.NonGoals` | Required narrative. List everything discovery established as out of scope (`"none"` if genuinely nothing); review enforces these as must-not constraints. |
+| `items[].metadata.requiresInspection` | **Required on every item.** See inspection rules below. |
+| `items[].metadata.inspectionDepth` | `"fast"` (default) or `"deep"`. Only matters when `requiresInspection: true`. |
+| `items[].metadata.files_scope` | Required `string[]` of files/globs this item is expected to touch. Use concrete paths or narrow globs, not broad repo-wide patterns. |
+| `items[].metadata.files_scope_confidence` | Required confidence in `files_scope`: `"high"`, `"medium"`, or `"low"`. |
+| `items[].metadata.verify_commands` | Required for slot-eligible items. List commands that verify this item before slot merge, e.g. `["npm run typecheck", "npx vitest run tests/unit/foo.test.ts"]`. |
+| `items[].metadata.expected_outputs` | Required for slot-eligible items. List the observable evidence expected from `verify_commands`, e.g. `["foo.test.ts passes"]`. |
+| `items[].metadata.readiness` | Required tri-state swarm readiness: `"ready"` for parallel-safe work, `"sequential"` for intentionally serialized work, `"needs_refinement"` when the item is not ready to dispatch. |
+| `items[].metadata.traces` | Optional `string[]` of PRD requirement IDs (`FR-1`, `NFR-2`) this item satisfies. |
+| nested `items` with `metadata.kind: "acceptance_criterion"` | Each item must have at least one acceptance-criterion child item. |
+
+---
+
+## Step 3 — Write `.pan/continue.json`
+
+The continue file records decisions and hazards so the work agent (and review/test agents) have context that isn't in the xBRIEF narrative.
+
+```json
+{
+  "version": "1",
+  "issueId": "<ISSUE-ID-UPPERCASE>",
+  "created": "<ISO 8601 timestamp>",
+  "updated": "<ISO 8601 timestamp>",
+  "gitState": { "branch": "<current branch>", "sha": "<short sha>", "dirty": false },
+  "decisions": [
+    { "id": "D1", "summary": "<decision text>", "recordedAt": "<ISO 8601 timestamp>" }
+  ],
+  "hazards": [
+    { "id": "H1", "summary": "<risk or edge case>", "mitigation": "<how to handle it>" }
+  ],
+  "resumePoint": null,
+  "tasksMapping": {},
+  "agentModel": "agent:<model-slug>",
+  "sessionHistory": [
+    {
+      "timestamp": "<ISO 8601 timestamp>",
+      "reason": "planning",
+      "note": "Self-authored plan (no planning agent)",
+      "agentModel": "agent:<model-slug>"
+    }
+  ]
+}
+```
+
+Rules:
+- `version` must be `"1"`
+- `issueId` must be uppercase (e.g. `"PAN-1234"`)
+- `resumePoint` stays `null` — the work agent populates it when it begins
+- `tasksMapping` stays `{}` — `pan plan finalize` populates it
+
+---
+
+## Step 4 — Finalize
+
+From the workspace root, run:
+
+```bash
+pan plan finalize
+```
+
+This atomically:
+1. Reads the legacy-compatible workspace path `.pan/spec.vbrief.json`
+2. Creates xBRIEF tasks through the canonical writer (one per `items[]` entry, edges respected)
+3. Sets `plan.status` to `"proposed"`
+4. Promotes the canonical spec to `${OVERDECK_HOME}/state/<project>/specs/<YYYY-MM-DD>-<ISSUE>-<slug>.xbrief.json`
+5. Commits and pushes `overdeck-state`, then transitions the tracker issue to Planned
+
+
+---
+
+## Task sizing rules
+
+Default to **many small xBRIEF tasks** over a few large ones. A well-sized task:
+
+- Has one focused change (if you need "and" in the title, it's two xBRIEF tasks)
+- Is independently reviewable from its diff alone
+- Leaves the tree in a working state if merged alone
+- Has a testable acceptance criterion
+
+**Heuristics:**
+- One renamed command = one task
+- One moved file = one task (unless mechanically identical batch → sub-items under one task)
+- One new API endpoint = one task
+- One schema migration = one task
+- One doc update = one task (or one per logical cluster, not "update all docs")
+
+When in doubt, split. Too-small xBRIEF tasks: mild overhead. Too-large xBRIEF tasks: reviewers can't reason about them, agents deliver partial results, and the inspection gate can't verify mid-implementation.
+
+---
+
+## Edge semantics
+
+Add an edge only when there is a **real** dependency:
+
+| When to add `blocks` edge | When NOT to add |
+|---------------------------|-----------------|
+| B consumes a file/type/value A produces | Narrative flow ("feels like it should come second") |
+| Both items modify the same file | Readability preference |
+| B can't start until A reaches a specific state | Defensive sequencing "just in case" |
+
+Absent edges = permission for the work agent to run items in parallel. A spurious edge silently forces serialization that was never intended.
+
+Edge types: `blocks` (hard), `informs` (soft/advisory), `invalidates`, `suggests`
+
+---
+
+## Inspection gate (`requiresInspection`)
+
+Set `requiresInspection: true` **only** when a wrong implementation would cascade into downstream xBRIEF tasks before the verification gate catches it:
+
+- **Foundation for downstream xBRIEF tasks** — subsequent xBRIEF tasks depend on this task's interfaces, types, or module boundaries
+- **Architectural decision crystallizing in code** — naming a public API, choosing a library boundary, picking an event shape
+- **Spec ambiguity risk** — the description is broad enough that two very different diffs could both look "done"
+- **Security/auth surface** — defects here propagate into later xBRIEF tasks assuming the security posture
+- **Cross-cutting protocol or schema** — wire format, DB migration, RPC contract, event payload
+
+Set `requiresInspection: false` for:
+- Mechanical changes (flag flip, rename, single-file tweak)
+- Leaf xBRIEF tasks (no downstream task depends on their internals)
+- Tests, docs, comment-only updates
+- Wrongs that surface immediately at typecheck/lint
+
+When `requiresInspection: true`, you **must** also set `metadata.foundationFor: ["<task-id>", ...]` listing the downstream xBRIEF tasks that would need to be redone if this one were wrong. An empty `foundationFor` on an inspection task is a planning error — flip it back to `false`.
+
+Most plans have 0–2 inspection xBRIEF tasks. More than 3 suggests the xBRIEF tasks are too large.
+
+---
+
+## Difficulty rubric
+
+| Level | When | Typical model |
+|-------|------|---------------|
+| `trivial` | Typo, comment, formatting only | haiku |
+| `simple` | Bug fix, single file, obvious change | haiku |
+| `medium` | New feature, 3–5 files, standard patterns | sonnet |
+| `complex` | Refactor, migration, 6+ files, some risk | sonnet |
+| `expert` | Architecture, security, performance, high risk | opus |
+
+---
+
+## Quick checklist
+
+Before running `pan plan finalize`:
+
+- [ ] `.pan/spec.vbrief.json` has exactly two top-level keys: `xBRIEFInfo` and `plan`
+- [ ] `plan.id` is lowercase issue ID
+- [ ] `plan.uid` is a fresh UUID v4
+- [ ] `plan.status` is `"approved"`
+- [ ] Every item has `metadata.kind` and `metadata.requiresInspection`
+- [ ] Every item has `metadata.files_scope`, `metadata.files_scope_confidence`, and `metadata.readiness`
+- [ ] Every slot-eligible item has `metadata.verify_commands` and `metadata.expected_outputs`
+- [ ] Every item has at least one nested `items` AC entry
+- [ ] `foundationFor` populated on every `requiresInspection: true` item
+- [ ] No spurious edges
+- [ ] `.pan/continue.json` written with at least one `decisions[]` entry
+
+---
+
+## See also
+
+- `docs/XBRIEF.md` — full schema reference and lifecycle states
+- `/pan-plan` — start the interactive planning agent instead
+- `pan plan finalize --help` — finalization flags

package/sync-sources/templates/claude-md/sections/warnings.md

@@ -94,7 +94,7 @@ git push -u origin $(git branch --show-current)
 # 4. Verify clean state
 git status  # Must show "nothing to commit"
 
-# 5. Update vBRIEF tasks
+# 5. Update xBRIEF item state
 ```
 
 **If ANY step fails, fix it before declaring work complete.**

package/server/agent-state-Co5Sy2Fw.js

@@ -1,3 +0,0 @@
-import { Mn as init_agent_state, Sn as clearAgentPausedSync, jn as getAgentStateSync, qn as setAgentPausedSync, wn as clearAgentTroubledSync } from "./queries-ZABd5aXP.js";
-init_agent_state();
-export { clearAgentPausedSync, clearAgentTroubledSync, getAgentStateSync, setAgentPausedSync };

package/server/agents-DyHKlq1I.js

@@ -1,3 +0,0 @@
-import { $ as stopAgent, A as buildCompactRecoverySeed, An as getAgentStateFilePath, B as appendActivity, Bn as recordAgentFailure, Bt as OHMYPI_AGENT_READY_TIMEOUT_SECONDS, Cn as clearAgentTroubled, D as detectCrashedAgents, Dn as getAgentDir, Dt as assertWorkspaceStackHealthyForSpawn, E as autoRecoverAgents, Fn as isRole, Gn as saveAgentStateSync, Gt as getProviderAuthMode, H as getLatestSessionId, Ht as getAgentRuntimeBaseCommand, Jn as setAgentYieldedSync, Jt as injectPiConversationMemory, K as saveSessionId, Kn as setAgentPaused, Kt as getRoleRuntimeBaseCommand, L as messageAgent, Ln as markAgentRunningState, M as resumeAgent, Mt as transitionIssueToInProgress, Nn as isAgentPaused, Nt as transitionIssueToInReview, O as recoverAgent, Ot as buildAgentLaunchConfig, Pn as isAgentTroubled, Rn as markAgentStoppedState, Sn as clearAgentPausedSync, Tn as clearYieldForResumeSync, U as getLatestSessionIdSync, Un as resetAgentFailureCount, V as getActivity, Vn as recordAgentFailureSync, Vt as describeOhmypiSpawnFailure, W as getSessionId, Wn as saveAgentState, X as spawnAgent, Xn as writeAgentStateJsonSync, Xt as waitForPromptReady, Yn as wipeAgentStateDirs, Yt as roleAgentDefinitionPath, Z as spawnRun, _n as writeChannelsBridgeMcpConfig, _t as deliverAgentPermissionDecision, a as listRunningAgentsSync, an as determineModel, ar as normalizeAgentId, bn as __testInternals, bt as setAgentDeliveryMethod, c as compactAtTierRunBoundary, cn as getProviderTmuxFlags, cr as waitForReadySignal, d as replayStandingAgent, et as stopAgentSync, f as shouldReplayCompactAtTierRunBoundary, fr as saveAgentRuntimeState, gn as dismissDevChannelsDialog, gt as deliverAgentMessage, hn as decideSupervisorForWorkAgent, i as listRunningAgents, in as buildSpawnEnvForModel, ir as isQualifiedAgentId, jn as getAgentStateSync, jt as retrieveSpawnTimeMemoryContext, k as restartAgent, kn as getAgentState, l as contextWindowForModel, lr as getAgentRuntimeState, mn as decideChannelsForWorkAgent, o as warnOnBareNumericIssueIds, on as getProviderEnvForModel, or as resolveAgentTargetSync, pn as buildDefaultResumeContinueMessage, qn as setAgentPausedSync, r as listAgentStates, rn as buildCavemanExports, rr as clearReadySignal, s as init_agents, sn as getProviderExportsForModel, sr as waitForAgentIdle, t as dropLegacyAgentStatesMissingRoleAsync, u as replayCrashedStandingAgent, ur as getAgentRuntimeStateSync, vn as GOVERNOR_SLOT_PAUSE_REASON_PREFIX, vt as deliverInitialPromptWithRetry, wn as clearAgentTroubledSync, xn as clearAgentPaused, yn as SESSION_EXITED_BEFORE_KICKOFF, yt as deliverResumeMessageWithTranscriptConfirmation, zn as markAgentTroubled } from "./queries-ZABd5aXP.js";
-init_agents();
-export { GOVERNOR_SLOT_PAUSE_REASON_PREFIX, OHMYPI_AGENT_READY_TIMEOUT_SECONDS, SESSION_EXITED_BEFORE_KICKOFF, __testInternals, appendActivity, assertWorkspaceStackHealthyForSpawn, autoRecoverAgents, buildAgentLaunchConfig, buildCavemanExports, buildCompactRecoverySeed, buildDefaultResumeContinueMessage, buildSpawnEnvForModel, clearAgentPaused, clearAgentPausedSync, clearAgentTroubled, clearAgentTroubledSync, clearReadySignal, clearYieldForResumeSync, compactAtTierRunBoundary, contextWindowForModel, decideChannelsForWorkAgent, decideSupervisorForWorkAgent, deliverAgentMessage, deliverAgentPermissionDecision, deliverInitialPromptWithRetry, deliverResumeMessageWithTranscriptConfirmation, describeOhmypiSpawnFailure, detectCrashedAgents, determineModel, dismissDevChannelsDialog, dropLegacyAgentStatesMissingRoleAsync, getActivity, getAgentDir, getAgentRuntimeBaseCommand, getAgentRuntimeState, getAgentRuntimeStateSync, getAgentState, getAgentStateFilePath, getAgentStateSync, getLatestSessionId, getLatestSessionIdSync, getProviderAuthMode, getProviderEnvForModel, getProviderExportsForModel, getProviderTmuxFlags, getRoleRuntimeBaseCommand, getSessionId, injectPiConversationMemory, isAgentPaused, isAgentTroubled, isQualifiedAgentId, isRole, listAgentStates, listRunningAgents, listRunningAgentsSync, markAgentRunningState, markAgentStoppedState, markAgentTroubled, messageAgent, normalizeAgentId, recordAgentFailure, recordAgentFailureSync, recoverAgent, replayCrashedStandingAgent, replayStandingAgent, resetAgentFailureCount, resolveAgentTargetSync, restartAgent, resumeAgent, retrieveSpawnTimeMemoryContext, roleAgentDefinitionPath, saveAgentRuntimeState, saveAgentState, saveAgentStateSync, saveSessionId, setAgentDeliveryMethod, setAgentPaused, setAgentPausedSync, setAgentYieldedSync, shouldReplayCompactAtTierRunBoundary, spawnAgent, spawnRun, stopAgent, stopAgentSync, transitionIssueToInProgress, transitionIssueToInReview, waitForAgentIdle, waitForPromptReady, waitForReadySignal, warnOnBareNumericIssueIds, wipeAgentStateDirs, writeAgentStateJsonSync, writeChannelsBridgeMcpConfig };

package/server/cli-BRORS9qY.js

@@ -1,3 +0,0 @@
-import { r as init_cli, t as createResetMarker } from "./cli-CbKNkFE5.js";
-init_cli();
-export { createResetMarker };

package/server/codex-DNyiQDKW.js

@@ -1,3 +0,0 @@
-import { a as extractThreadIdFromRollout, c as initCodexHome, f as waitForCodexRollout, l as init_codex, o as findLatestRollout, p as writeThreadId, s as findRolloutPath } from "./codex-CbmztVcc.js";
-init_codex();
-export { extractThreadIdFromRollout, findLatestRollout, findRolloutPath, initCodexHome, waitForCodexRollout, writeThreadId };

package/server/deacon-swarm-CV54eNmU.js

@@ -1,2 +0,0 @@
-import { r as coordinateSwarmSlots } from "./deacon-swarm-BryRr6AO.js";
-export { coordinateSwarmSlots };

package/server/dist-j64RzSrQ.js

@@ -1,3 +0,0 @@
-import { t as require_dist } from "./dist-D-Ed5yVw.js";
-export default require_dist();
-export {};

package/server/forge-B0_opi-V.js

@@ -1,2 +0,0 @@
-import { n as getForgeAdapter } from "./forge-B1S_KZv4.js";
-export { getForgeAdapter };

package/server/hume-BmhvfVbV.js

@@ -1,3 +0,0 @@
-import { i as init_hume, r as deleteHumeConfig } from "./hume-Dz_OymXE.js";
-init_hume();
-export { deleteHumeConfig };

package/server/inspect-agent-Dq0z1k3H.js

@@ -1,2 +0,0 @@
-import { n as onInspectComplete } from "./inspect-agent-BXCgNeZ4.js";
-export { onInspectComplete };

package/server/lifecycle-io-DmY2qwCn.js

@@ -1,3 +0,0 @@
-import { a as init_lifecycle_io, s as transitionVBriefOnMain } from "./lifecycle-io-taIb0PoH.js";
-init_lifecycle_io();
-export { transitionVBriefOnMain };

package/server/merge-ops-DwWCkSgo.js

@@ -1,2 +0,0 @@
-import { c as triggerMerge } from "./workspaces-CFPcL0vl.js";
-export { triggerMerge };