write-xbrief

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

{
  "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.

{
  "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:

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