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, CC-feature matching, 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 → architect → plan → execute) produces a structured artifact that the next step consumes.

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
/ultra-cc-architect-local	Architect (optional, v2.2) — match brief+research against Claude Code features; produce architecture note with gaps. Requires --project	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
/ultra-skill-author-local	Authoring (v2.3, skill-factory Fase 1) — generate one cc-architect-catalog draft from a local source with IP-hygiene	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 + background research (local + external) + synthesis + brief
--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	All phases in foreground (blocking)

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

/ultra-cc-architect-local modes (optional, v2.2)

Flag	Behavior
--project <dir>	Required — read {dir}/brief.md and {dir}/research/*.md, write {dir}/architecture/overview.md + {dir}/architecture/gaps.md
--fg	All phases in foreground (blocking)
--quick	Skip adversarial review (architecture-critic)
--no-gaps	Skip gap-identifier; overview.md only

Architect sits between /ultraresearch-local and /ultraplan-local. It matches the task brief + research against available Claude Code features (Hooks, Subagents, Skills, Output Styles, MCP, Plan Mode, Worktrees, Background Agents) using a seeded catalog skill, and produces a proposed feature set with brief-anchored rationale plus explicit gaps (missing reference, pattern, decision, or outside-CC-scope).

/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	All phases in foreground (blocking)
--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.

/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	Runs full planning pipeline as background task (brief-driven)
research-orchestrator	opus	Runs full research pipeline as background task
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
architect-orchestrator	opus	Runs architecture phase as background task (feature-matcher + gap-identifier + critic)
feature-matcher	sonnet	Match brief+research to CC features using catalog; brief-anchored rationale + fallback ranking
gap-identifier	sonnet	Detect catalog/pattern/decision/outside-CC-scope gaps; emit issue-ready drafts
architecture-critic	sonnet	Adversarial review of architecture note (hallucination gate, brief-anchor integrity, gap honesty)
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)

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 blocks foreground until plan is ready.

Research: 8-phase workflow: Parse mode → Interview → Background transition → Parallel research (5 local + 4 external + 1 bridge) → Follow-ups → Triangulation → Synthesis + brief → Stats. With --project, writes to {dir}/research/NN-slug.md.

Architect (v2.2, optional): 7-phase workflow: Parse mode (--project required) → Background transition → Read inputs + audit catalog skill → Parallel feature-matcher + gap-identifier → Synthesize overview.md (6 sections + YAML frontmatter) → Adversarial review via architecture-critic (skipped in --quick; hallucination gate is BLOCKER) → Write gaps.md + stats → Present summary. With --project, writes {dir}/architecture/overview.md and {dir}/architecture/gaps.md. Additive — downstream /ultraplan-local auto-discovers the note if present.

Plan: 12-phase workflow: Parse mode (validate brief input) → Background transition → Codebase sizing → Brief review (brief-reviewer) → Parallel exploration (6-8 agents) → 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.

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/. /ultra-cc-architect-local --project <dir> (optional, v2.2) matches available Claude Code features against brief+research and writes {dir}/architecture/. /ultraplan-local --project <dir> reads brief + research (+ architecture note if present) to produce {dir}/plan.md. /ultraexecute-local --project <dir> executes and writes {dir}/progress.json. All artifacts live in one project directory.

CC-feature catalog skill: The architect phase loads the cc-architect-catalog skill, which indexes Claude Code primitives (hooks, subagents, skills, output styles, MCP, plan mode, worktrees, background agents) across three layers: reference (how a feature works), pattern (when to reach for it), decision (adoption heuristics). The feature-matcher agent only proposes features covered by the catalog or an explicit fallback list — a hallucination gate that architecture-critic enforces as BLOCKER severity. The gap-identifier agent emits issue-ready drafts for missing catalog entries so the catalog grows with real usage rather than speculation. The catalog lives at skills/cc-architect-catalog/.

Slug convention (v2.3.1): catalog files follow <cc_feature>[-<qualifier>]-<layer>.md.

• Unqualified slugs (e.g., hooks-pattern.md) are the canonical baseline — one per (feature, layer) pair, covering generic shapes and decision-heuristics for the feature.
• Qualified slugs (e.g., hooks-observability-pattern.md) cover specific named sub-patterns. Zero-or-more per (feature, layer) pair. The qualifier MUST be kebab-case and descriptive (observability, migration, multi-tenant).
• Matcher logic: feature-matcher builds cc_feature → {layer → [skills]} and prefers the unqualified baseline when the brief does not specifically justify a variant. Multiple skills can be proposed together when they cover non-overlapping aspects of the same feature.
• Critic enforcement: architecture-critic verifies every cited supporting_skill name exists as a real file in the catalog (blocker severity). The cc_feature hallucination gate is unchanged — still validates against the taxonomy, not slugs.
• Collision handling: skill-factory drafts that would overwrite an approved slug are a hard error. Resolution is either to qualify the new slug or revise the existing baseline.
• Drafter collision hint (v2.3.2): skill-drafter reads {catalog_root}/<slug>.md before writing, and prepends a warning block to its confirmation output when an existing skill would be overwritten during manual mv promotion. The warning cites the existing file's review_status and suggests a qualified slug derived from the concept handle. The draft is still written to .drafts/<slug>.md — the check is a hint, not a block.

Seeds v2.3.1: 11 skills across 8 features — one qualified pattern (hooks-observability-pattern.md, promoted from ai-psychosis/README.md, ngram-overlap 0.01, approved). Decision-layer intentionally empty pending skill-factory Fase 2.

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 (optional, v2.2, from /ultra-cc-architect-local --project)
  • 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
• Architect stats: ${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-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 — produced by /ultra-cc-architect-local. Proposes which Claude Code features fit the task with brief-anchored rationale + explicit gaps. Enriches planning.

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