plan-op

name

plan-op

description

Plan an entire operation without executing it: right-size the output (single plan doc up to a full design-spec + implementation-plan + breakdown + weak-model-proof task-brief package with gates and dependency waves) and write it into the target repo's docs/ tree. Use when /plan-op is invoked, or the user says plan the whole operation, spec this out and produce task briefs, or plan but do not build. Not for single-PR PLAN.md gating (that is plan-first) and never implements anything.

plan-op — plan everything, execute nothing

1. Prime directive

You are PLANNING an operation. The planning documents are the deliverable — the run produces files, never code changes to the planned work. If asked mid-session to "just do it" or "go ahead and implement", REFUSE and redirect to the produced briefs: they are the execution interface. Only this main session writes files; agents you dispatch are read-only. Docs are written only on the plan branch/worktree (opened by the git ladder at the START of the GENERATE phase), and committed only at LAND — never in the main checkout of a worktree-mandating repo. STOP CONDITION: after LAND writes the docs and CLOSE prints the summary with COMPLETED/REMAINING/BLOCKED counts, the run ENDS. There is no implementation phase — not in this session, not ever.

2. Pipeline

idea → DETECT → TIER → [interview] → [GATE1: L manifest] → EVIDENCE → SPEC → [GATE2: M/L approval]
     → GENERATE (downstream docs) → BRIEF-VERIFY → AUDIT → LAND → CLOSE

Phase 1 — DETECT (silent, <30s)

• If .claude/plan-op.local.md exists, load it and skip all probing — the profile always wins.
• Otherwise run the probe ladder, classify NATIVE / PARTIAL / GREENFIELD, sample live docs for naming fingerprints, resolve placeholders, and write the profile (announced).
• Announce ONE line: Detected: docs/specs+plans+agent-tasks, gate=\make ci`, rebase/FF merges.`
• Read references/repo-detection.md on any first run in a repo, and whenever the repo is not NATIVE.

Phase 2 — TIER

• Score the idea on the five axes and pick a tier from the table below; --tier overrides everything.
• When unambiguous (most runs): announce in ≤3 lines — tier, the threshold that fired verbatim, the exact planned file list — and PROCEED. The announcement is a one-word veto window, not a question.
• When two axes disagree by ≥2 tiers: ask ONE AskUserQuestion with the three tiers as options, recommended tier pre-stated.
• Irreversible stakes (persisted data, schema, prod state) force Tier ≥ M no matter how small the diff.
• Read references/right-sizing.md before classifying, before asking anything.

Phase 3 — INTERVIEW (only if needed)

• One AskUserQuestion batch, max 4 questions, drawn from the bank in references/right-sizing.md; every question ships a smart default so "accept all" is valid.
• Ask only what detection and the idea text could not resolve: scope boundary, data-risk posture, locked decisions, undetectable gate command.
• NEVER ask about standing conventions (headers, worktrees, commit format, brief format, status counts) — those are settled.
• Tier S skips the interview unconditionally; when all questions are answerable from the idea, skip the batch and state each inferred answer in one line.

Phase 4 — GATE 1: MANIFEST (Tier L only)

• Present: detected mode, tier + fired threshold, exact list of files to be created with full paths, any docs/-structure or profile creation, and this run's own fan-out plan (N scouts / judge panel yes-no with trigger cited, or "single-threaded because X").
• Gate behavior follows the profile gates: setting (default stop): stop → present and STOP, wait for approval (the user can re-tier here); announce → present the manifest, then proceed after a short veto window unless interrupted (the re-tier correction point stays open, the friction does not). auto is NOT honored for this gate — the manifest is the last cheap moment to catch a mis-tier before N files exist, so auto degrades to announce here (say so in one line).
• Write the checkpoint state file (schema in §7). For S/M there is no manifest gate — structure creation is announced inside the TIER announcement instead.

Phase 5 — EVIDENCE

• Solo read pass (LSP + grep) for S/M in a known repo.
• Dispatch 2–5 parallel read-only repo-scout agents when ANY trigger in the quick-rules table (§5A) fires; each scout gets one disjoint scope and the strict JSON report schema.
• PROVENANCE RULE: the exact greps scouts run become, verbatim, the re-verify grep blocks in briefs — every anchor cited downstream must have been resolvable this session.
• Read references/ultracode-orchestration.md before dispatching any agent.

Phase 6 — SPEC + GATE 2 (M/L)

• Tier S: skip — write the mini-plan directly in the next phase.
• Draft the design spec from @${CLAUDE_PLUGIN_ROOT}/templates/design-spec.md. For Tier L, run the design-judge panel only when BOTH ≥2 viable architectures survive AND stakes are irreversible; verdicts surface at the gate as CONFIRMED/CHALLENGED, merged into Decisions (locked) with losing options named.
• Present the gate: file path + ≤15-line summary for L, ≤30-line Decisions-locked summary + open questions for M. Never inline >300 lines in chat.
• Gate behavior follows the profile gates: setting (default stop): stop → STOP and wait for approval before any downstream doc; announce → present the Decisions-locked summary, then proceed after a veto window unless interrupted; auto → log the locked decisions and proceed with no pause. The spec gate is where locked decisions get vetoed before ~15 briefs cite them, so announce (a near-zero-friction veto window) is the recommended non-stop setting; auto skips that window entirely — only choose it when the decisions are genuinely uncontested.

Phase 7 — GENERATE (downstream docs, tier-ordered)

• Git ladder FIRST, before any doc is written: worktree git worktree add ../<repo>-plan-<slug> -b docs/plan-<slug> in worktree-mandating repos; plain branch plan/<slug> in ordinary foreign repos; not a git repo → write in place + warn (commit/PR skipped at LAND). Every downstream doc is written INSIDE this plan worktree/branch.
• Every doc from its template, fresh uuid4 (uuidgen | tr '[:upper:]' '[:lower:]'; fallback python3 -c "import uuid;print(uuid.uuid4())"), version 1.0.0, file: header line matching the real output path.
• Tier L: skeleton FIRST, then project. Before writing any package document, author one authoritative skeleton (the source of truth for every cross-referenced fact: task IDs, exact_files, tiers, priorities, depends_on, polarity, verified anchors, shared-state). Compute the collision matrix and waves FROM it, once. Every document is then a projection of the skeleton — never author the same fact (a task ID, a wave number, a file path) into two documents independently, or they drift. Read references/skeleton.md before generating a Tier L package.
• Tier S: one mini-plan; at most ONE line of execution advice. Tier M: spec + TDD impl plan with 5-step failing-test→pass→commit loops and literal Run:/Expected: pairs.
• Tier L, mechanically in order (all projected from the skeleton): taskboard plan → collision matrix computed from every task's Exact-files list → wave table → mandatory Execution mode: line on every phase/wave citing its numeric trigger → BREAKDOWN with 3-bucket sort (only Bucket 1 becomes briefs) → TASK-NN briefs → workstream README + orchestration.md + run.sh; when docs/agent-tasks/ORCHESTRATION.md is absent (GREENFIELD or PARTIAL), additionally seed the package ORCHESTRATION.md + run-sweep.sh — never overwrite them when present; ≥2 workstreams adds 00-ROADMAP.md.
• Each brief's idempotency/acceptance direction follows its skeleton polarity (additive → grep the new thing is present; removal/transform → grep the old thing is absent + the replacement is present). A removal task must NOT inherit the additive template's presence-grep, or its idempotency reads "done" forever. See references/weak-model-proofing.md invariant 10.
• Read references/skeleton.md before generating (Tier L), references/collision-waves.md before the wave table, references/weak-model-proofing.md before the first TASK brief, references/house-conventions.md before writing any file in a repo lacking .standards/ (the target repo's own CLAUDE.md/.standards wins on conflict).

Phase 8 — BRIEF-VERIFY

• Dispatch one brief-verifier agent per TASK brief, in a single parallel batch; each role-plays a cold weak model executing the brief.
• Failures loop back for repair; re-verify until every brief passes the checklist.
• Read references/weak-model-proofing.md for the fail checklist the verifiers apply.

Phase 9 — AUDIT (mechanical, no user round-trip)

• Dispatch the plan-auditor against the docs in the plan worktree/branch: execute every re-verify grep at HEAD (fail on zero hits); recompute the file-overlap matrix and assert overlapping task pairs sit in different waves; lint every produced doc (4-line header, guid fresh and unique across the package, file: path == real path, required sections); every Run: has an Expected:, every brief has an anti-over-suppression case or an explicit Anti-over-suppression: N/A line, gate resolved or explicitly GATE UNDETECTED.
• ALWAYS for Tier L; for Tier M when the plan cites >10 anchors; header lint always.
• Fix findings and re-audit until clean. Contract: references/audit-checklist.md.

Phase 10 — LAND

• The plan worktree/branch (opened at the start of the GENERATE phase) already contains every produced doc — LAND is commit + push + open PR only. Not a git repo (per the GENERATE-phase ladder) → skip commit/PR, warn.
• Prepend entries to TODO.md and CHANGELOG.md if present — never replace; UNLESS a changelog-management tool owns CHANGELOG.md (release-please, changesets, auto-changelog config detected), in which case record the plan in the plan docs only and say why (see references/repo-detection.md).
• Conventional commit docs(plan): <slug> planning package with the resolved trailer, push, gh pr create; OFFER gh pr merge --rebase but never auto-merge. No gh/remote → push + manual-PR instructions.

Phase 11 — CLOSE

• Delete the state file (deactivates the write-fence).
• Handoff report: artifact inventory with absolute paths; per-wave execution route quoting the plan's own Execution-mode lines; the paste-ready dispatch preamble for TASK-01; the explicit line "NO implementation was executed — planning only"; whether TODO.md/CHANGELOG.md were updated.
• Worktree lifecycle: the plan worktree/branch STAYS OPEN until the PR merges — the docs live on it. State this in the handoff (one line: "plan worktree <path> stays until PR # merges; git worktree remove it then"). Do NOT remove it at CLOSE; do NOT leave its cleanup unmentioned.
• Mandatory footer: COMPLETED: <n> — <artifacts> / REMAINING: <n> — <execution phases, not this session's job> / BLOCKED: <n> — <Bucket-2 items awaiting design>.
• Then the run ENDS. Do not offer to start implementing. If the user asks, point at the briefs and the Execution-mode lines.

3. Tier table

Tier	Trigger thresholds	Artifacts	Gates	Templates
0	≤1–2 files, no design tension	NONE — decline with the script in references/right-sizing.md; offer a single TASK brief only if the user insists	—	—
S	≤~5 files, one PR, no contested decisions, no data risk	docs/plans/YYYY-MM-DD-<slug>-plan.md	0	@${CLAUDE_PLUGIN_ROOT}/templates/mini-plan.md
M	new mechanism OR contested decisions OR any data-touching step; one executor, ≤3 PRs	design spec + TDD impl plan	1 (spec approval)	@${CLAUDE_PLUGIN_ROOT}/templates/design-spec.md, @${CLAUDE_PLUGIN_ROOT}/templates/impl-plan-tdd.md
L	≥4 assignable tasks OR ≥2 waves OR ≥3 workstreams OR fan-out audience	spec + taskboard plan + BREAKDOWN + workstream package; + roadmap at ≥2 workstreams; seeds agent-tasks ORCHESTRATION.md + run-sweep.sh when docs/agent-tasks/ORCHESTRATION.md is absent (GREENFIELD or PARTIAL)	2 (manifest, spec) + mechanical audit	taskboard, breakdown, task-brief, workstream-* , roadmap templates (see index)

Irreversible stakes force ≥ M. --tier overrides. Load templates lazily — only the chosen tier's.

4. Template index

Artifact	Template	Output path pattern	Emitted at
Mini-plan	@${CLAUDE_PLUGIN_ROOT}/templates/mini-plan.md	docs/plans/YYYY-MM-DD-<slug>-plan.md	Tier S, GENERATE phase
Design spec	@${CLAUDE_PLUGIN_ROOT}/templates/design-spec.md	docs/specs/YYYY-MM-DD-<topic>-design.md	M/L, SPEC phase
TDD impl plan	@${CLAUDE_PLUGIN_ROOT}/templates/impl-plan-tdd.md	docs/plans/YYYY-MM-DD-<topic>.md	Tier M, GENERATE phase
Taskboard plan	@${CLAUDE_PLUGIN_ROOT}/templates/impl-plan-taskboard.md	docs/plans/YYYY-MM-DD-<topic>.md	Tier L, GENERATE phase
Breakdown	@${CLAUDE_PLUGIN_ROOT}/templates/breakdown.md	docs/agent-tasks/BREAKDOWN-YYYY-MM-DD.md	Tier L, GENERATE phase
Task brief	@${CLAUDE_PLUGIN_ROOT}/templates/task-brief.md	docs/agent-tasks/<ws>/TASK-NN-<slug>.md	Tier L, GENERATE phase
Workstream README	@${CLAUDE_PLUGIN_ROOT}/templates/workstream-README.md	docs/agent-tasks/<ws>/README.md	Tier L, GENERATE phase
Workstream orchestration	@${CLAUDE_PLUGIN_ROOT}/templates/workstream-orchestration.md	docs/agent-tasks/<ws>/orchestration.md	Tier L, GENERATE phase
Workstream runner	@${CLAUDE_PLUGIN_ROOT}/templates/workstream-run.sh	docs/agent-tasks/<ws>/run.sh	Tier L, GENERATE phase
Package orchestration	@${CLAUDE_PLUGIN_ROOT}/templates/agent-tasks-ORCHESTRATION.md	docs/agent-tasks/ORCHESTRATION.md	Tier L, when docs/agent-tasks/ORCHESTRATION.md is absent (GREENFIELD or PARTIAL) — never overwritten when present (NATIVE)
Sweep runner	@${CLAUDE_PLUGIN_ROOT}/templates/agent-tasks-run-sweep.sh	docs/agent-tasks/run-sweep.sh	Tier L, seeded alongside the package ORCHESTRATION.md (same absence rule)
Roadmap	@${CLAUDE_PLUGIN_ROOT}/templates/roadmap.md	docs/<initiative>/00-ROADMAP.md	Tier L with ≥2 workstreams
Repo profile	@${CLAUDE_PLUGIN_ROOT}/templates/plan-op.local.example.md	.claude/plan-op.local.md	DETECT phase, first run in a repo

Output paths shown for the canonical layout; the resolved profile ({{DOCS_ROOT}}, docs-site overrides) may relocate them.

5. Ultracode quick rules

A. Planning-time agents (all read-only; only this session writes files)

Agent	Dispatch when	Skip when
repo-scouts (2–5, parallel, Sonnet-class)	ANY of: idea spans ≥3 subsystems; relevant files >15; first run in an unfamiliar repo; planner has read <20% of files it must cite	Tier S; or LSP + a few greps answers everything
design-judge panel (2–3 lenses)	BOTH ≥2 viable architectures survive AND stakes are irreversible (or user-flagged high-stakes)	ALWAYS for Tier S; for M without irreversible stakes — paneling those is over-production
brief-verifier (1 per brief, parallel batch)	ALWAYS over generated TASK briefs	never skipped
plan-auditor (mechanical)	ALWAYS for Tier L; Tier M when >10 anchors cited; header lint always	Tier S (no anchors, no waves)

B. Execution-mode stamps embedded in produced plans

Stamp	Numeric trigger
/parallel-sweep (or equivalent coordinator workflow)	wave has ≥3 mechanically similar tasks OR one change touches ≥20 callsites across ≥3 files — AND disjoint files within the wave AND Bucket-1-quality briefs AND a local per-worktree gate
SERIAL WAVES (coordinator-driven)	brief-able tasks share files; the collision-table row IS the justification; wave N+1 only after wave N merges and siblings rebase
SINGLE-AGENT (strong model)	judgment tasks: design-adjacent, schema/migration semantics, irreversible writes, conflict-prone hot paths — NEVER parallelized, NEVER weak-tier
NOT AGENT WORK	Bucket 2 (needs a design session first) and Bucket 3 (operational, no code deliverable)

Dispatch prompts, model-tier role names, and edge cases: references/ultracode-orchestration.md — read it before dispatching any agent AND before stamping any Execution-mode line.

6. Non-negotiables

• Never execute planned work — the documents are the deliverable, full stop.
• Never edit main; land via the git ladder (worktree / branch / warn).
• Fresh uuid4 + version 1.0.0 + file: path == real path in every produced header; canonical header rules beat any live sample.

• 300-line content goes to files, never chat.

• Every cited anchor was grep-verified this session.
• Scout greps become brief re-verify blocks verbatim (provenance rule).
• Tier L is generated skeleton-first: one source of truth, every doc a projection (references/skeleton.md).
• Collision matrix is computed from Exact-files lists, never eyeballed.
• No bare line numbers in a brief — every cited file:line, edit-target OR reference, carries a re-verify grep.
• A brief's idempotency check matches its polarity: additive greps for presence, removal/transform greps for absence.
• Every Run: has an Expected:.
• Only Bucket-1 work becomes weak-model briefs.
• Tier-0 ideas get declined, not padded into a package.
• No orchestration package below Tier L.
• Mechanical audit is mandatory for Tier L — it cannot be skipped.
• Conventional commits with the resolved trailer.
• Exact-count COMPLETED / REMAINING / BLOCKED footer on every status report.

7. Checkpoint / resume

State file: .claude/state/plan-op-<slug>.json, written after EVERY phase transition. Schema:

{
  "slug": "itl-hardening",
  "phase": "detect|tier|interview|gate1|evidence|spec|gate2|generate|brief-verify|audit|land|close",
  "tier": "S|M|L",
  "mode": "NATIVE|PARTIAL|GREENFIELD",
  "started_at": "2026-07-05T14:02:11Z",
  "artifacts": [
    { "path": "docs/specs/2026-07-05-itl-hardening-design.md", "status": "written" },
    { "path": "docs/agent-tasks/itl/TASK-01-checksum-guard.md", "status": "pending" }
  ]
}

status is one of pending | written | committed. --resume [slug] loads the newest (or named) state file, then RE-STATS every artifacts[].path on disk rather than trusting recorded status — a hand-edited or deleted doc re-enters the generate phase. The state file doubles as the write-fence activation flag (scripts/write-fence.sh); delete it at CLOSE. A state file older than 24h is stale — the fence self-cleans it.

8. References index

• references/right-sizing.md — read at the TIER phase, before classifying and before asking anything.
• references/repo-detection.md — read at the DETECT phase on the first run in any repo, and for any non-NATIVE repo.
• references/ultracode-orchestration.md — read at the EVIDENCE phase before dispatching agents, and again before writing wave tables / Execution-mode lines.
• references/house-conventions.md — read before writing any file in a repo lacking .standards/; the target repo's own CLAUDE.md/.standards wins on conflict.
• references/skeleton.md — read at the GENERATE phase before generating a Tier L package (skeleton-first: one source of truth, every doc projected).
• references/weak-model-proofing.md — read before writing the first TASK brief.
• references/collision-waves.md — read for Tier L with ≥2 tasks, before the wave table.
• references/audit-checklist.md — read at the AUDIT phase; also the contract for /plan-op-audit.