ktg-plugin-marketplace/plugins/ultraplan-local/CLAUDE.md

ultraplan-local

Deep implementation planning and research with an explicit brief step, specialized agent swarms, external research, adversarial review, session decomposition, disciplined execution, and headless support. A local alternative to Anthropic's Ultraplan.

Design principle: Context Engineering — build the right context by orchestrating specialized agents. Each step in the pipeline (brief → research → plan → execute) produces a structured artifact that the next step consumes.

v3.0.0 — architect extracted to separate plugin. /ultra-cc-architect-local and /ultra-skill-author-local were moved to the ultra-cc-architect plugin (v0.1.0). The plan command still auto-discovers architecture/overview.md if present, so installing both plugins gives you the full five-stage flow. See CHANGELOG.md for migration steps.

Commands

Command	Description	Model
/ultrabrief-local	Brief — interactive interview produces a task brief with explicit research plan; optionally orchestrates the pipeline	opus
/ultraresearch-local	Research — deep local + external research, produces structured research brief	opus
/ultraplan-local	Plan — brief-reviewer, explore, plan, review. Requires --brief or --project. Auto-discovers architecture/overview.md if present	opus
/ultraexecute-local	Execute — disciplined plan/session-spec executor with failure recovery	opus

/ultrabrief-local modes

Flag	Behavior
(default)	Dynamic interview until quality gates pass → brief.md with research plan
--quick	Compact start; still escalates if required sections are weak or the brief-review gate fails → brief.md with research plan

Always interactive. Phase 3 is a section-driven completeness loop (no hard cap on question count); Phase 4 runs a brief-reviewer stop-gate with max 3 review iterations. After writing the brief, asks the user to choose manual (print commands) or auto (Claude runs research + plan in foreground).

/ultraresearch-local modes

Flag	Behavior
(default)	Interview + research (local + external) + synthesis + brief (foreground)
--project <dir>	Write brief to {dir}/research/{NN}-{slug}.md (auto-incremented)
--quick	Interview (short) + inline research (no agent swarm)
--local	Only codebase analysis agents (skip external + Gemini)
--external	Only external research agents (skip codebase analysis)
--fg	No-op alias (foreground is default since v2.4.0)

Flags combine: --project <dir> --local, --external --quick.

/ultraplan-local modes

Flag	Behavior
--project <dir>	Required path A — read {dir}/brief.md, auto-discover {dir}/research/*.md, write {dir}/plan.md
--brief <path>	Required path B — plan from a specific brief file; write to .claude/plans/ultraplan-{date}-{slug}.md
--research <brief> [brief2]	Enrich with extra research briefs beyond what is in {project_dir}/research/
--fg	No-op alias (foreground is default since v2.4.0)
--quick	Plan directly (no agent swarm)
--export <pr|issue|markdown|headless> <plan>	Generate shareable output from existing plan
--decompose <plan>	Split plan into self-contained headless sessions

Breaking change (v2.0): one of --brief or --project is required. There is no interview inside /ultraplan-local. The --spec flag has been removed — use /ultrabrief-local to produce a brief instead.

If {project_dir}/architecture/overview.md exists (typically produced by the separate ultra-cc-architect plugin), the plan command auto-discovers it and treats cc_features_proposed as priors. Missing file is fine — discovery is additive, not required.

/ultraexecute-local modes

Flag	Behavior
(default)	Execute plan — auto-detects Execution Strategy for multi-session
--project <dir>	Read {dir}/plan.md, write {dir}/progress.json
--resume	Resume from last progress checkpoint
--dry-run	Validate plan structure without executing
--validate	Schema-only check — parse steps + manifests, report READY | FAIL, no execution
--step N	Execute only step N
--fg	Force foreground — run all steps sequentially, ignore Execution Strategy
--session N	Execute only session N from plan's Execution Strategy

Agents

Agent	Model	Role
planning-orchestrator	opus	Inline reference documentation for the planning pipeline workflow (brief-driven)
research-orchestrator	opus	Inline reference documentation for the research pipeline workflow
architecture-mapper	sonnet	Codebase structure, tech stack, patterns
dependency-tracer	sonnet	Import chains, data flow, side effects
task-finder	sonnet	Task-relevant files, functions, reuse candidates
risk-assessor	sonnet	Risks, edge cases, failure modes
test-strategist	sonnet	Test patterns, coverage gaps, strategy
git-historian	sonnet	Recent changes, ownership, hot files
research-scout	sonnet	External docs for unfamiliar tech (conditional, planning only)
convention-scanner	sonnet	Coding conventions: naming, style, error handling, test patterns
brief-reviewer	sonnet	Task brief quality (5 dimensions: completeness, consistency, testability, scope clarity, research plan validity)
plan-critic	sonnet	Adversarial plan review (9 dimensions)
scope-guardian	sonnet	Scope alignment (creep + gaps)
session-decomposer	sonnet	Splits plans into headless sessions with dependency graph
docs-researcher	sonnet	Official documentation, RFCs, vendor docs (Tavily, MS Learn)
community-researcher	sonnet	Community experience: issues, blogs, discussions
security-researcher	sonnet	CVEs, audit history, supply chain risks
contrarian-researcher	sonnet	Counter-evidence, overlooked alternatives
gemini-bridge	sonnet	Gemini Deep Research second opinion (conditional)

Quality infrastructure (v3.1.0)

lib/ contains zero-dep validators and parsers wired into the four commands:

• lib/util/{frontmatter,result}.mjs — shared YAML-frontmatter parser + Result helpers
• lib/parsers/{plan-schema,manifest-yaml,project-discovery,arg-parser,bash-normalize}.mjs — pure parsers (no I/O), unit-tested
• lib/validators/{brief,research,plan,progress}-validator.mjs — schema validators with CLI shims (node lib/validators/X.mjs --json <path>)
• lib/validators/architecture-discovery.mjs — drift-WARN external-contract discovery for architecture/overview.md

Wiring points (replaces previous prose-grep instructions):

• /ultrabrief-local Phase 4g → brief-validator (post-write sanity check)
• /ultraplan-local Phase 1 → brief-validator --soft, research-validator --dir, architecture-discovery
• planning-orchestrator Phase 5.5 → plan-validator --strict (replaces 3 grep -cE calls)
• /ultraexecute-local --validate → plan-validator --strict + progress-validator

Tests under tests/**/*.test.mjs (109 tests, 0 deps). npm test is the fork-readiness gate.

Doc-consistency test at tests/lib/doc-consistency.test.mjs pins agent-table count, command-table coverage, plan_version invariant, and settings.json scope cleanliness.

docs/HANDOVER-CONTRACTS.md is the single source of truth for the 5 pipeline handovers (brief→research, research→plan, architecture→plan EXTERNAL, plan→execute, progress.json resume). Read it before changing any artifact format.

hooks/scripts/pre-compact-flush.mjs (PreCompact event, CC v2.1.105+) fixes the documented P0 in docs/ultraexecute-v2-observations-from-config-audit-v4.md: keeps progress.json in sync with git history before context compaction so --resume works after long conversations. Atomic write, monotonic only, never blocks compaction.

hooks/scripts/session-title.mjs (UserPromptSubmit, CC v2.1.94+) sets sessionTitle to ultra:<command>:<slug> for ultra-command invocations. Helps multi-session headless runs identify themselves in process lists.

hooks/scripts/post-bash-stats.mjs (PostToolUse, CC v2.1.97+) appends duration_ms for each Bash call into ${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl. Useful for finding long-running verify or checkpoint commands.

Architecture

Brief: 7-phase workflow: Parse mode → Create project dir → Phase 3 completeness loop (section-driven, no question cap) → Phase 4 draft/review/revise with brief-reviewer as stop-gate (max 3 iterations; gate = all dimensions ≥ 4 and research plan = 5) → Finalize (brief.md on pass, or brief_quality: partial on cap/force-stop) → Manual/auto opt-in → Stats. Always interactive. Auto mode runs research + plan inline in the main context (v2.4.0).

Research: Foreground workflow (v2.4.0): Parse mode → Interview → Parallel research swarm (5 local + 4 external + 1 bridge, spawned from main context) → Follow-ups → Triangulation → Synthesis + brief → Stats. With --project, writes to {dir}/research/NN-slug.md.

Plan: Foreground workflow (v2.4.0): Parse mode (validate brief input) → Codebase sizing → Brief review (brief-reviewer) → Parallel exploration (6-8 agents, spawned from main context) → Deep-dives → Synthesis (with architecture-note cross-reference if present) → Planning → Adversarial review (plan-critic + scope-guardian) → Present/refine → Handoff. With --project, writes to {dir}/plan.md and auto-detects {dir}/architecture/overview.md (produced by the separate ultra-cc-architect plugin if installed).

Decompose: Parse plan → Analyze step dependencies → Group into sessions → Identify parallel waves → Generate session specs + dependency graph + launch script.

Execute: Parse plan → Security scan (Phase 2.4) → Detect Execution Strategy → Single-session (step loop) or multi-session (parallel waves via claude -p with scoped --allowedTools) → Phase 7.5 manifest audit → Phase 7.6 bounded recovery (if partial) → Report. With --project, reads {dir}/plan.md and writes {dir}/progress.json.

Security: 4-layer defense-in-depth: plugin hooks (pre-bash-executor, pre-write-executor), prompt-level denylist (works in headless sessions), pre-execution plan scan (Phase 2.4), scoped --allowedTools replacing --dangerously-skip-permissions. Hard Rules 14-16 enforce verify command security, repo-boundary writes, and sensitive path protection.

Pipeline: /ultrabrief-local produces the task brief. /ultraresearch-local --project <dir> fills in {dir}/research/. /ultraplan-local --project <dir> reads brief + research to produce {dir}/plan.md (and auto-discovers {dir}/architecture/overview.md if the separate ultra-cc-architect plugin produced one). /ultraexecute-local --project <dir> executes and writes {dir}/progress.json. All artifacts live in one project directory.

Project-directory contract (v3.0.0): ultraplan-local owns the directory layout below. The architecture/ subdirectory is opt-in and produced by the separate ultra-cc-architect plugin — install that plugin to participate in the architect step.

.claude/projects/{YYYY-MM-DD}-{slug}/
  brief.md           ← ultrabrief-local writes; everyone reads
  research/*.md      ← ultraresearch-local writes; plan + architect read
  architecture/      ← OPT-IN, owned by ultra-cc-architect plugin
    overview.md
    gaps.md
  plan.md            ← ultraplan-local writes; ultraexecute reads
  progress.json      ← ultraexecute-local writes

No code-level dependency between plugins — the contract is filesystem-level only.

State

All artifacts in one project directory (default):

• Project root: .claude/projects/{YYYY-MM-DD}-{slug}/
  • brief.md (task brief from /ultrabrief-local)
  • research/{NN}-{slug}.md (research briefs from /ultraresearch-local --project)
  • architecture/overview.md + architecture/gaps.md (opt-in, produced by the separate ultra-cc-architect plugin)
  • plan.md (from /ultraplan-local --project)
  • sessions/session-*.md (from --decompose)
  • progress.json (from /ultraexecute-local --project)

Legacy paths (still work without --project):

• Research briefs: .claude/research/ultraresearch-{date}-{slug}.md
• Plans: .claude/plans/ultraplan-{date}-{slug}.md
• Sessions: .claude/ultraplan-sessions/{slug}/session-*.md
• Launch scripts: .claude/ultraplan-sessions/{slug}/launch.sh
• Progress: {plan-dir}/.ultraexecute-progress-{slug}.json

Stats:

• Brief stats: ${CLAUDE_PLUGIN_DATA}/ultrabrief-stats.jsonl
• Plan stats: ${CLAUDE_PLUGIN_DATA}/ultraplan-stats.jsonl
• Exec stats: ${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl
• Research stats: ${CLAUDE_PLUGIN_DATA}/ultraresearch-stats.jsonl

Terminology

• Task brief — produced by /ultrabrief-local. Declares intent, goal, and research plan. Drives planning.
• Research brief — produced by /ultraresearch-local. Answers a specific research question. Feeds planning.
• Architecture note — opt-in, produced by /ultra-cc-architect-local from the separate ultra-cc-architect plugin. Proposes which Claude Code features fit the task with brief-anchored rationale + explicit gaps. When present, enriches planning.

A project typically has 1 task brief, 0–N research briefs, and 0 or 1 architecture note.