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

ultraplan-local — Brief, Research, Plan, Execute

AI-generated: all code produced by Claude Code through dialog-driven development. Full disclosure →

A Claude Code plugin for deep implementation planning, multi-source research, and autonomous execution. Four commands, one pipeline:

Command	What it does
/ultrabrief-local	Brief — interactive interview produces a task brief with explicit research plan
/ultraresearch-local	Research — deep local + external research with triangulation
/ultraplan-local	Plan — agent swarm exploration, Opus planning, adversarial review
/ultraexecute-local	Execute — disciplined step-by-step implementation with failure recovery

Every artifact lives in one project directory: .claude/projects/{YYYY-MM-DD}-{slug}/ contains brief.md, research/NN-*.md, plan.md, sessions/, and progress.json.

v3.0.0 — architect extracted to its own plugin. The /ultra-cc-architect-local and /ultra-skill-author-local commands moved to the separate 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 pipeline (brief → research → architect → plan → execute). See CHANGELOG.md for migration steps.

Division of labor

Command	Responsibility	Output
/ultrabrief-local	Capture intent — intent, goal, non-goals, success criteria, and a research plan with explicit topics. Interactive only.	brief.md (task brief)
/ultraresearch-local	Gather context — code state, external docs, community, risk. Makes NO build decisions.	research/NN-slug.md (research brief)
/ultraplan-local	Transform intent into an executable contract — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. Auto-discovers architecture/overview.md as priors when the ultra-cc-architect plugin is installed.	plan.md with Manifest blocks + plan_version: 1.7
/ultraexecute-local	Execute the contract disciplined — fresh verification, independent manifest audit, honest reporting. Does NOT compensate for weak plans — escalates.	progress.json + structured report + manifest-audit status

Principle: Each step consumes the previous step's structured artifact. If execute has to guess, the plan is weak and must be revised upstream — not patched downstream.

Two kinds of briefs

Terminology matters:

• Task brief — produced by /ultrabrief-local. Captures what we want and why. Drives planning.
• Research brief — produced by /ultraresearch-local. Captures what we learned about a topic. Feeds planning.

A project typically has one task brief and zero-to-N research briefs.

Self-verifying plan chain

Every step in the plan ends with a YAML manifest: block declaring expected_paths, commit_message_pattern, bash_syntax_check, forbidden_paths, must_contain. This makes the plan the objective completion predicate: a step may not be marked passed if its manifest does not verify, regardless of the Verify command's exit code (Hard Rule 17).

After all steps complete, /ultraexecute-local runs Phase 7.5 — Manifest audit (independent): re-verifies every expected path from git log + filesystem, ignoring the agent's own bookkeeping. Drift → status partial, Phase 7.6 auto-dispatches a bounded recovery session with only the missing steps (recovery_depth ≤ 2). Step 0 pre-flight (git push --dry-run) runs inside every session sandbox before any real work — exit 77 sentinel catches sandbox push-denial before the agent wastes the whole budget.

No cloud dependency. No GitHub requirement. Works on Mac, Linux, and Windows.

Quick start

# Install the marketplace, then browse and enable plugins with /plugin
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git

# Capture intent (interactive)
/ultrabrief-local Add user authentication with JWT tokens
# → .claude/projects/2026-04-18-jwt-auth/brief.md

# Research each topic identified in the brief (manual default)
/ultraresearch-local --project .claude/projects/2026-04-18-jwt-auth --external "What are current JWT best practices?"

# Plan from brief + research
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth

# Execute
/ultraexecute-local --project .claude/projects/2026-04-18-jwt-auth

Or opt into auto-mode in /ultrabrief-local — it will run research and planning sequentially inline in the main context, and return when plan.md is ready.

For Claude-Code-specific architecture matching (matching brief+research to features like Hooks, Subagents, Skills, MCP), install the separate ultra-cc-architect plugin. It sits between research and plan — /ultraplan-local auto-discovers its output.

v2.4.0 — background mode removed. All four orchestrator commands now run foreground in the main context. The --fg flag is preserved as a no-op alias for backward compatibility. Background mode silently degraded the agent swarm (the harness does not expose the Agent tool to sub-agents) — see CHANGELOG for the full rationale.

When to use it

Use it when:

• The task touches 3+ files or modules and you need to understand how they connect
• You're working in an unfamiliar codebase and need a map before you start
• The implementation has non-obvious dependencies, ordering constraints, or risks
• You want a reviewable plan before committing to an approach
• You need autonomous headless execution without human intervention
• You need to research a technology, library, or approach before deciding

Don't use it when:

• The task is a single-file change where the fix is obvious
• You already know exactly what to change and in what order

Rule of thumb: If you can describe the full implementation in one sentence and it touches 1-2 files, skip ultraplan and just implement. If you need to think about it, ultraplan earns its cost.

---

/ultrabrief-local — Brief

Interactive requirements-gathering command. Runs a dynamic, quality-gated interview and produces a task brief with an explicit research plan. Optionally orchestrates the rest of the pipeline.

How it works (v2.1 — quality-gated)

1. Parse mode — default (dynamic; probes until quality gates pass) or --quick (starts compact, still escalates if gates fail)
2. Create project directory — .claude/projects/{YYYY-MM-DD}-{slug}/ with research/ subdirectory
3. Phase 3 — Completeness loop — a section-driven loop (not a fixed question list) picks the next question from the section with the weakest signal (Intent → Goal → Success Criteria → Research Plan first, then optional sections). Required sections must reach an initial-signal gate before Phase 3 exits. No hard cap on question count.
4. Identify research topics — inline during Phase 3; probe for unfamiliar tech, version upgrades, security-sensitive decisions, architectural choices. Topics get a research question, scope, confidence, and cost.
5. Phase 4 — Draft, review, revise — draft the brief in memory, write to brief.md.draft, launch brief-reviewer as a stop-gate. The reviewer scores five dimensions (completeness, consistency, testability, scope clarity, research plan) 1–5 and returns machine-readable JSON. Gate passes when all ≥ 4 and research plan = 5. On fail, a targeted follow-up is generated from the weakest dimension's detail field and the draft is re-reviewed. Max 3 review iterations.
6. Finalize — rename draft to brief.md on pass, or write with brief_quality: partial + a ## Brief Quality section if the cap is hit or the user force-stops.
7. Auto-orchestration opt-in — user chooses manual (default) or auto (Claude-managed research + plan in foreground)
8. Stats tracking — append to ultrabrief-stats.jsonl (includes review_iterations and brief_quality)

Output: .claude/projects/{YYYY-MM-DD}-{slug}/brief.md

Modes

Mode	Usage	Behavior
Default	/ultrabrief-local <task>	Dynamic interview until quality gates pass. No question cap.
Quick	/ultrabrief-local --quick <task>	Starts compact (optional sections get at most one probe), still escalates on weak required sections or failed review gate.

/ultrabrief-local is always interactive. There is no foreground/background mode — the interview requires user input.

Force-stop

If you say "stop" or "enough" during Phase 4, the current review findings are surfaced with per-dimension scores and you choose:

• Answer one more follow-up — the loop continues.
• Stop now (accept partial brief) — the brief is finalized with brief_quality: partial and a ## Brief Quality section listing the failing dimensions. Downstream planning will treat these as reduced-confidence areas.

What the brief contains

• Intent — why this matters, motivation, user need (load-bearing)
• Goal — concrete end state in 1-3 sentences
• Non-Goals — explicitly out of scope
• Constraints / Preferences / NFRs — technical, time, resource limits
• Success Criteria — 2-4 falsifiable commands/observations
• Research Plan — N topics, each with research question, scope (local/external/both), confidence needed, cost estimate, and a ready-to-run /ultraresearch-local command
• Open Questions / Assumptions — from "I don't know" answers and implicit gaps
• Prior Attempts — what worked/failed before

---

/ultraresearch-local — Research

Deep, multi-phase research that combines local codebase analysis with external knowledge. Uses specialized agent swarms to investigate multiple dimensions in parallel, then triangulates findings.

How it works

1. Interview — short requirements gathering (skipped when --project reuses brief context)
2. Research dimensions — identify 3-8 facets to investigate in parallel
3. Local agents — 5 Sonnet agents analyze the codebase in parallel (architecture, dependencies, existing code, git history, conventions)
4. External agents — 4 Sonnet agents search documentation, community experience, security data, and counter-evidence in parallel
5. Gemini bridge — independent second opinion via Gemini Deep Research (optional)
6. Follow-ups — targeted investigation of knowledge gaps (max 2)
7. Triangulate — cross-validate local vs. external findings, rate confidence per dimension, flag contradictions
8. Synthesize — write structured research brief

Output:

• With --project <dir>: {dir}/research/{NN}-{slug}.md (auto-incremented index)
• Without: .claude/research/ultraresearch-{date}-{slug}.md

Modes

Mode	Usage	Behavior
Default	/ultraresearch-local <question>	Interview + research swarm (local + external + Gemini), foreground
Project	/ultraresearch-local --project <dir> <question>	Write brief into {dir}/research/NN-slug.md
Quick	/ultraresearch-local --quick <question>	Interview (short) + inline research, no agent swarm
Local	/ultraresearch-local --local <question>	Only codebase analysis agents (skip external + Gemini)
External	/ultraresearch-local --external <question>	Only external research agents (skip codebase analysis)
Foreground	/ultraresearch-local --fg <question>	No-op alias (foreground is default since v2.4.0)

Flags combine: --project <dir> --external.

Research agents

Agent	Role	Scope
architecture-mapper	How architecture relates to the research question	Local
dependency-tracer	Dependencies and integrations relevant to the topic	Local
task-finder	Existing code relevant to the question	Local
git-historian	Recent changes and ownership in related areas	Local
convention-scanner	Coding patterns relevant to evaluating options	Local (medium+ codebases)
docs-researcher	Official documentation, RFCs, vendor docs	External
community-researcher	Real-world experience, issues, blog posts	External
security-researcher	CVEs, audit history, supply chain risks	External
contrarian-researcher	Counter-evidence, overlooked alternatives	External
gemini-bridge	Independent second opinion via Gemini Deep Research	External (optional)

---

/ultraplan-local — Planning

Produces an implementation plan detailed enough for autonomous execution. v2.0 breaking change: requires --brief or --project. There is no longer an interview inside /ultraplan-local — use /ultrabrief-local first.

How it works

1. Parse mode — validate that a brief is provided
2. Spec review → brief review — brief-reviewer validates completeness, consistency, testability, scope clarity, and research plan validity
3. Explore — 6-8 specialized Sonnet agents analyze your codebase in parallel
4. Research — optional research briefs enrich planning (--research, or auto-discovered in {project_dir}/research/)
5. Architecture priors — if {project_dir}/architecture/overview.md exists (produced by the optional ultra-cc-architect plugin), cc_features_proposed are loaded as priors. Missing file is fine.
6. Synthesize — findings merged into a unified codebase understanding
7. Plan — Opus creates a comprehensive implementation plan with per-step YAML manifests
8. Critique — adversarial review by plan-critic (9 dimensions) and scope-guardian
9. Handoff — plan written; execute now, save for later, or export

Output:

• With --project <dir>: {dir}/plan.md
• With --brief <path>: .claude/plans/ultraplan-{date}-{slug}.md

Modes

Mode	Usage	Behavior
Project	/ultraplan-local --project <dir>	Read {dir}/brief.md + auto-discover {dir}/research/*.md, write {dir}/plan.md
Brief	/ultraplan-local --brief <path>	Plan from a specific brief file
Research-enriched	/ultraplan-local --project <dir> --research <brief>	Add extra research briefs beyond what is in research/
Foreground	/ultraplan-local --project <dir> --fg	No-op alias (foreground is default since v2.4.0)
Quick	/ultraplan-local --project <dir> --quick	No agent swarm, lightweight scan only
Decompose	/ultraplan-local --decompose plan.md	Split plan into headless session specs
Export	/ultraplan-local --export pr plan.md	PR description, issue comment, or clean markdown

--brief or --project is required. /ultraplan-local with no brief exits with an error and a pointer to /ultrabrief-local.

What the plan contains

Every plan includes:

• Context — derived from brief ## Intent + ## Goal
• Architecture Diagram — Mermaid C4-style component diagram
• Codebase Analysis — tech stack, patterns, relevant files, reusable code
• Research Sources — findings from research briefs (when present)
• Implementation Plan — ordered steps with file paths, changes, failure recovery, and git checkpoints
• Per-step Manifest — YAML block with expected_paths, commit_message_pattern, bash_syntax_check, forbidden_paths, must_contain
• Alternatives Considered — other approaches with pros/cons
• Test Strategy — from test-strategist findings
• Risks and Mitigations — from risk-assessor findings
• Verification — testable end-to-end criteria
• Execution Strategy — session grouping and parallel waves (plans with > 5 steps)
• Plan Quality Score — quantitative grade (A-D) across 6 weighted dimensions

Every implementation step includes:

• On failure: — what to do when verification fails (revert / retry / skip / escalate)
• Checkpoint: — git commit after success
• Manifest: — the objective completion predicate (Hard Rule 17)

Exploration agents

Agent	Role	Runs on
architecture-mapper	Codebase structure, patterns, anti-patterns	All codebases
dependency-tracer	Import chains, data flow, side effects	All codebases
task-finder	Task-relevant files, functions, reuse candidates	All codebases
test-strategist	Test patterns, coverage gaps, strategy	All codebases
git-historian	Git history, ownership, hot files, branches	All codebases
risk-assessor	Threats, edge cases, failure modes	All codebases
research-scout	External docs, best practices	When unfamiliar tech detected
convention-scanner	Coding conventions, naming, style, test patterns	Medium+ codebases

Review agents

Agent	Role
brief-reviewer	Checks task brief quality (completeness, consistency, testability, scope clarity, research plan validity) before exploration
plan-critic	Adversarial review: 9 dimensions, quantitative scoring, no-placeholder enforcement, manifest audit as hard gate
scope-guardian	Verifies plan matches brief: finds scope creep and scope gaps

---

/ultraexecute-local — Execution

Reads a plan from /ultraplan-local and implements it with strict discipline. No guessing, no improvising — follows the plan exactly.

How it works per step

1. Implement — applies the Changes field exactly as written
2. Verify — runs the Verify command (exit code is truth)
3. Manifest audit — validates expected paths, forbidden paths, commit pattern
4. On failure — follows the plan's recovery clause (revert / retry / skip / escalate)
5. Checkpoint — commits changes per the plan's Checkpoint field

Modes

Mode	Usage	Behavior
Project	/ultraexecute-local --project <dir>	Read {dir}/plan.md, write {dir}/progress.json
Plan path	/ultraexecute-local plan.md	Execute a specific plan file
Resume	/ultraexecute-local --project <dir> --resume	Resume from last progress checkpoint
Dry run	/ultraexecute-local --project <dir> --dry-run	Validate plan structure + preview sessions and billing
Validate	/ultraexecute-local --project <dir> --validate	Schema-only check — parse steps + manifests, report READY | FAIL, no execution
Single step	/ultraexecute-local --project <dir> --step 3	Execute only step 3
Foreground	/ultraexecute-local --project <dir> --fg	Force sequential, ignore Execution Strategy
Single session	/ultraexecute-local --project <dir> --session 2	Execute only session 2 from Execution Strategy

Session-aware parallel execution (worktree-isolated)

When a plan has an ## Execution Strategy section (auto-generated by /ultraplan-local for plans with > 5 steps), /ultraexecute-local automatically:

1. Pre-flight checks — validates clean working tree, plan file tracked in git, no scope fence overlaps between parallel sessions, no stale worktrees
2. Creates git worktrees — each parallel session gets its own isolated worktree and branch (ultraplan/{slug}/session-{N})
3. Launches claude -p per session per wave, each in its own worktree
4. Merges branches back sequentially with --no-ff after each wave completes
5. Cleans up worktrees and branches unconditionally (even on failure)
6. Runs master verification on the merged result

Wave 1: Session 1 (worktree-1) + Session 2 (worktree-2)  -- parallel
         ↓ both complete → sequential merge to main
Wave 2: Session 3 (worktree-3)                             -- sequential
         ↓ complete → merge to main
Cleanup worktrees + Master verification

Each session operates in complete filesystem isolation — no shared git index, no race conditions, no data loss. If a merge produces conflicts, the merge is aborted and conflicting files are reported.

Use --fg to force sequential execution even when a plan has an Execution Strategy.

Billing safety

Before launching parallel claude -p sessions, /ultraexecute-local checks whether ANTHROPIC_API_KEY is set in your environment. If it is, parallel sessions will bill your API account (pay-per-token), not your Claude subscription (Max/Pro). This can be expensive — parallel Opus sessions can cost $50-100+ per run.

When an API key is detected, you are asked how to proceed:

• Use --fg instead (recommended) — run sequentially in the current session using your subscription
• Continue with API billing — launch parallel sessions on your API account
• Stop — cancel and unset the API key first

If no API key is set, parallel sessions use your subscription and proceed without asking.

Failure recovery

• 3-attempt retry cap — retries twice, then stops (never loops forever)
• On failure: revert — undo changes, stop
• On failure: retry — try alternative approach, then revert if still failing
• On failure: skip — non-critical step, continue
• On failure: escalate — stop everything, needs human judgment

Security hardening

The executor implements defense-in-depth security across four layers:

1. Plugin hooks — pre-bash-executor.mjs blocks 13 categories of destructive commands (rm -rf /, chmod 777, pipe-to-shell, eval injection, disk wipe, shutdown, fork bombs, cron persistence, process killing, history destruction) with bash evasion normalization. pre-write-executor.mjs blocks writes to .git/hooks/, .claude/settings.json, shell configs, .ssh/, .aws/, and .env files
2. Prompt-level denylist — Security rules embedded in the executor command and session spec template that work even in headless claude -p sessions where hooks don't run
3. Pre-execution plan scan — Phase 2.4 scans all Verify: and Checkpoint: commands against the denylist before execution begins, catching dangerous commands before they reach the executor
4. Scoped tool access — Headless child sessions use --allowedTools "Read,Write,Edit,Bash,Glob,Grep" instead of --dangerously-skip-permissions, blocking Agent spawning, MCP tools, and web access in parallel sessions

Recommended: disable Skill shell execution (CC v2.1.91+)

For fork-ers handling untrusted task briefs or plans from external sources, set disableSkillShellExecution: true in ~/.claude/settings.json or in the project's .claude/settings.json:

{
  "disableSkillShellExecution": true
}

This prevents Skills from invoking arbitrary shell, which closes a prompt-injection vector that the plugin's own hooks cannot fully mitigate (Skills can fire before pre-bash-executor matches). See SECURITY.md for the full hardening list.

Headless execution

/ultraexecute-local is designed for claude -p headless sessions:

• No questions asked — all recovery decisions come from the plan
• Progress file — crash recovery via {project_dir}/progress.json (or .ultraexecute-progress-{slug}.json for legacy plans)
• Scope fence enforcement — never touches files outside the session's scope
• JSON summary — machine-parseable ultraexecute_summary block for log parsing

Headless multi-session tuning (CC v2.1.89+)

When running multiple parallel claude -p sessions (decomposed plans or wave-based execution), set MCP_CONNECTION_NONBLOCKING=true in the launching environment so MCP server connection latency does not serialize startup across waves:

export MCP_CONNECTION_NONBLOCKING=true
bash .claude/projects/{slug}/sessions/launch.sh

Without this, each child session can spend 1-3 s blocking on MCP connect, multiplying across waves. Setting it lets MCP connect lazily on first tool call.

Session titles for ultra commands (CC v2.1.94+)

A UserPromptSubmit hook (hooks/scripts/session-title.mjs) sets the session title to ultra:<command>:<slug> whenever you invoke one of the four ultra commands. This makes multi-session headless runs and session-picker output trivially identifiable. Slug derivation:

Invocation	Session title
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth	ultra:plan:jwt-auth
/ultrabrief-local --quick	ultra:brief:ad-hoc
/ultraexecute-local --project .claude/projects/2026-05-10-cleanup --resume	ultra:execute:cleanup

The hook is fail-open — any error → title is left untouched.

Per-step timing (CC v2.1.97+)

A PostToolUse hook (hooks/scripts/post-bash-stats.mjs) appends duration_ms from each Bash tool call to ${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl. One line per Bash call; useful for identifying long-running verify or checkpoint commands across executions.

---

The full pipeline

 /ultrabrief-local   /ultraresearch-local    /ultraplan-local         /ultraexecute-local
 ┌──────────────┐    ┌───────────────────┐   ┌─────────────────────┐  ┌─────────────────────┐
 │ Interview    │    │ 5 local agents    │   │ brief-reviewer      │  │ Parse plan          │
 │ ↓            │    │ 4 external agents │   │ ↓                   │  │ ↓                   │
 │ Intent/Goal  │    │ + Gemini bridge   │   │ 6-8 exploration     │  │ Detect sessions     │
 │ ↓            │    │ ↓                 │   │ agents (parallel)   │  │ ↓                   │
 │ Research     │    │ Triangulation     │   │ ↓                   │  │ Execute steps       │
 │ topics       │    │ ↓                 │   │ Opus planning       │  │ (verify + manifest  │
 │ ↓            │ → brief → → → → → → → → → → → ↓                   │→ │  + checkpoint)      │
 │ brief.md     │    │ research/*.md     │   │ plan-critic +       │  │ ↓                   │
 └──────────────┘    └───────────────────┘   │ scope-guardian      │  │ Phase 7.5 manifest  │
                                             │ ↓                   │  │ audit + 7.6 recovery│
                                             │ plan.md             │  │ ↓                   │
                                             └─────────────────────┘  │ progress.json + done│
                                                                      └─────────────────────┘

All artifacts live under .claude/projects/{YYYY-MM-DD}-{slug}/.

To insert a Claude-Code-specific architecture-matching step between research and plan, install the separate ultra-cc-architect plugin — /ultraplan-local auto-discovers its architecture/overview.md output as priors.

Example workflows

Standard pipeline (manual control):

/ultrabrief-local Add session caching with Redis
# → .claude/projects/2026-04-18-redis-session-caching/brief.md
# Interview identifies 2 research topics.

/ultraresearch-local --project .claude/projects/2026-04-18-redis-session-caching --external "What are Redis session-caching best practices?"
/ultraresearch-local --project .claude/projects/2026-04-18-redis-session-caching --local "How is caching currently handled in the codebase?"
# → .claude/projects/2026-04-18-redis-session-caching/research/01-*.md, 02-*.md

/ultraplan-local --project .claude/projects/2026-04-18-redis-session-caching
# → .claude/projects/2026-04-18-redis-session-caching/plan.md

/ultraexecute-local --project .claude/projects/2026-04-18-redis-session-caching
# → progress.json + code changes

Auto-mode (Claude manages the pipeline):

/ultrabrief-local Add session caching with Redis
# Interview identifies topics. Choose "Auto (managed by Claude Code)" when asked.
# Claude runs research in parallel, then planning in foreground.
# Returns when plan.md is ready.

/ultraexecute-local --project .claude/projects/2026-04-18-redis-session-caching

Standalone research (no planning):

/ultraresearch-local What are the security implications of using JWT for session management?
# Read the brief, share with team, use for decision-making.

Quick plan for small tasks:

/ultrabrief-local --quick Fix the login redirect bug
/ultraplan-local --project .claude/projects/2026-04-18-login-redirect-fix --quick
/ultraexecute-local --project .claude/projects/2026-04-18-login-redirect-fix

Dry run + validate before executing:

/ultraexecute-local --project <dir> --validate   # schema check, no execution
/ultraexecute-local --project <dir> --dry-run    # preview sessions and billing
/ultraexecute-local --project <dir>              # execute

---

Upgrading from v2.x to v3.0.0

v3.0.0 is a structural release that does not break the planning flow but changes plugin layout:

• /ultra-cc-architect-local and /ultra-skill-author-local were moved to the new ultra-cc-architect plugin (v0.1.0).
• /ultraplan-local still auto-discovers architecture/overview.md if present — install both plugins to keep the full pipeline working.
• cc-architect-catalog skill moved to the new plugin. If you customized seeds locally, follow git log --follow to track them in the new location.
• ngram-overlap.mjs script and skill-factory test fixtures moved with the new plugin.

If you only used /ultrabrief-local, /ultraresearch-local, /ultraplan-local, and /ultraexecute-local: no action needed. Update the plugin and continue.

If you used /ultra-cc-architect-local or /ultra-skill-author-local: install the new plugin alongside this one:

{
  "enabledPlugins": {
    "ultraplan-local@ktg-plugin-marketplace": true,
    "ultra-cc-architect@ktg-plugin-marketplace": true
  }
}

Upgrading from v1.x

v2.0.0 is a breaking release. See MIGRATION.md for a step-by-step guide. Short version:

• /ultraplan-local no longer runs an interview. Use /ultrabrief-local first.
• /ultraplan-local --spec <path> is removed. Use --brief <path> or --project <dir> instead.
• Old specs do not work as-is. Convert a spec to a brief by filling in ## Intent and ## Research Plan sections (MIGRATION.md has a template).
• All artifacts now live in .claude/projects/{date}-{slug}/ by default. Legacy paths (.claude/research/, .claude/plans/) still work without --project.

How it compares

Feature	Ultraplan (cloud)	Copilot Workspace	Cursor	ultraplan-local
Planning model	Opus	GPT-4	Unknown	Opus
Requirements gathering	Task only	Issue-driven	Prompt	Dedicated brief command with explicit research plan
Codebase exploration	Cloud	Cloud	Cloud	6-8 specialized agents
Deep research pipeline	No	No	No	10 agents + Gemini + triangulation
Adversarial review	No	No	No	brief-reviewer + plan-critic + scope-guardian
Plan quality scoring	No	No	No	A-D grade, 6 dimensions
Failure recovery per step	No	No	No	revert/retry/skip/escalate
Session-aware parallel execution	No	No	No	Automatic wave-based
No-placeholder enforcement	No	No	No	Hard blocker
Manifest audit as hard gate	No	No	No	Hard Rule 17
Headless autonomous execution	No	No	No	/ultraexecute-local with claude -p
Requires GitHub	Yes	Yes	No	No
Cross-platform	Web only	Web only	Desktop	Mac, Linux, Windows

Quality infrastructure (since v3.1.0)

The plugin ships with node:test-based unit tests and a lib/ directory of pure-JS validators wired into the commands. Forking the plugin for internal use? Run npm test to confirm the parsers, validators, and doc-consistency invariants still hold:

cd plugins/ultraplan-local
npm test    # runs all tests under tests/**/*.test.mjs

Validators (zero npm deps, hand-rolled YAML subset):

Module	Purpose
lib/validators/brief-validator.mjs	brief.md frontmatter + state machine (research_topics + status coherence) + body sections
lib/validators/research-validator.mjs	research-brief frontmatter (confidence ∈ [0,1], dimensions ≥ 1) + body sections; --dir mode validates a whole research/ folder
lib/validators/plan-validator.mjs	wraps plan-schema + manifest-yaml; enforces v1.7 step heading, manifest count match, and forbidden-narrative-form denylist (### Fase/Phase/Stage/Steg N) — replaces the Phase 5.5 grep checks
lib/validators/progress-validator.mjs	progress.json shape (schema_version, status enum, current_step in range) + resume-readiness check
lib/validators/architecture-discovery.mjs	EXTERNAL CONTRACT — drift-WARN, never drift-FAIL. Discovers architecture/overview.md (owned by the separate ultra-cc-architect plugin) and tolerates non-canonical filenames with warnings.

Each module exposes a CLI: node lib/validators/<name>.mjs --json <path> returns structured {valid, errors, warnings, parsed}. Commands invoke the CLI as their schema check.

A doc-consistency test (tests/lib/doc-consistency.test.mjs) pins prose-vs-source invariants — the agent table in CLAUDE.md must match the agents/*.md file count, every command's frontmatter name: must match its filename, and templates/plan-template.md must declare plan_version: 1.7.

Borrowed pattern from llm-security (commit 97c5c9d); extending the plugin should preserve the invariants the test pins.

Handover contracts

docs/HANDOVER-CONTRACTS.md is the single source of truth for the file formats that pass between the four pipeline commands (brief → research → plan → execute). When you fork the plugin or extend a stage, that document tells you what every producer must write and what every consumer is allowed to assume. It also documents the external contract for architecture/overview.md (owned by the separate ultra-cc-architect plugin) — discovery only, drift-warn never drift-fail.

PreCompact resume integrity (CC v2.1.105+)

The pre-compact-flush.mjs hook directly fixes the documented P0 in docs/ultraexecute-v2-observations-from-config-audit-v4.md: in skill-driven execution, progress.json could fall behind git reality before context compaction, breaking /ultraexecute-local --resume after long conversations. The hook fires on every PreCompact event, locates any progress.json under .claude/projects/, compares stored current_step against git log --oneline {session_start_sha}..HEAD, and atomically writes a fresh checkpoint (tmp + rename, monotonic only) when git is ahead. Never blocks compaction.

Known limitations

Infrastructure-as-code (IaC) gets reduced value. The exploration agents are designed for application code. Terraform, Helm, Pulumi, CDK projects will get a plan, but agents like architecture-mapper and test-strategist produce less useful output for IaC. Use ultraplan-local for the structural plan, then supplement IaC-specific steps manually.

Installation

Add the marketplace and browse plugins with /plugin:

claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git

Or enable directly in ~/.claude/settings.json:

{
  "enabledPlugins": {
    "ultraplan-local@ktg-plugin-marketplace": true
  }
}

For Claude-Code-specific architecture matching (between research and plan), also enable ultra-cc-architect@ktg-plugin-marketplace.

Cost profile

• Brief: 1 Opus session (interactive; interview + write)
• Research (local): Up to 5 Sonnet agents (architecture, dependencies, code, git, conventions)
• Research (external): Up to 4 Sonnet agents (docs, community, security, contrarian) + Gemini bridge
• Exploration: 6-8 Sonnet agents with effort/turn limits (cost-effective)
• Planning research: 0-1 Sonnet agent (only when unfamiliar tech detected and no research brief provided)
• Review: 3 Sonnet agents (brief-reviewer + plan-critic + scope-guardian)
• Orchestration: 1 Opus agent per command (research-orchestrator or planning-orchestrator)
• Execution: 1 Opus session per session in the plan
• Typical total: Comparable to a long Claude Code session

The plugin minimizes Opus usage by front-loading cheap Sonnet exploration.

Requirements

• Claude Code (CLI, desktop app, or web app)
• Claude subscription with Opus access (Max plan recommended)
• Optional: Tavily MCP server for enhanced external research
• Optional: Gemini MCP server for independent second opinion via Gemini Deep Research

Architecture

ultraplan-local/
├── .claude-plugin/
│   └── plugin.json                # Plugin manifest (v3.0.0)
├── agents/                        # 19 specialized agents
│   ├── architecture-mapper.md     # Codebase structure and patterns
│   ├── dependency-tracer.md       # Import chains and data flow
│   ├── task-finder.md             # Task-relevant code discovery
│   ├── test-strategist.md         # Test patterns and strategy
│   ├── git-historian.md           # Git history, ownership, hot files
│   ├── risk-assessor.md           # Risks and failure modes
│   ├── brief-reviewer.md          # Task brief quality review (5 dimensions)
│   ├── plan-critic.md             # Adversarial plan review + scoring
│   ├── scope-guardian.md          # Scope alignment check
│   ├── research-scout.md          # External research (planning)
│   ├── session-decomposer.md      # Plan → headless session specs
│   ├── convention-scanner.md      # Coding conventions and patterns
│   ├── planning-orchestrator.md   # Inline reference for the planning pipeline (brief-driven)
│   ├── research-orchestrator.md   # Inline reference for the research pipeline
│   ├── docs-researcher.md         # Official docs, RFCs, vendor docs
│   ├── community-researcher.md    # Real-world experience, issues, blogs
│   ├── security-researcher.md     # CVEs, audit history, supply chain
│   ├── contrarian-researcher.md   # Counter-evidence, alternatives
│   └── gemini-bridge.md           # Gemini Deep Research second opinion
├── commands/                      # 4 slash commands
│   ├── ultrabrief-local.md        # /ultrabrief-local — interactive brief
│   ├── ultraresearch-local.md     # /ultraresearch-local — research
│   ├── ultraplan-local.md         # /ultraplan-local — planning
│   └── ultraexecute-local.md      # /ultraexecute-local — execution
├── templates/
│   ├── ultrabrief-template.md     # Task brief format (intent, goal, research plan)
│   ├── plan-template.md           # Plan format (with failure recovery + execution strategy)
│   ├── research-brief-template.md # Research brief format (with triangulation + confidence)
│   ├── session-spec-template.md   # Session spec format for headless execution
│   └── headless-launch-template.md # Launch script template
├── hooks/
│   ├── hooks.json                 # Hook registration (PreToolUse: Bash, Write)
│   └── scripts/
│       ├── pre-bash-executor.mjs  # Blocks destructive commands (13 BLOCK + 8 WARN rules)
│       └── pre-write-executor.mjs # Blocks writes to sensitive paths (8 rules)
├── settings.json                  # Default plugin configuration
├── CONTRIBUTING.md
├── CHANGELOG.md
├── MIGRATION.md                   # v1 → v2 migration guide
├── LICENSE
└── README.md

CC-feature catalog, skill-factory, and architect/skill-author commands moved to the separate ultra-cc-architect plugin in v3.0.0.

Pure markdown commands and agents. Hooks are self-contained Node.js with zero dependencies.

Extending the plugin

Common modifications fork-ers make. None require touching lib/ — all of these are surface-level changes to commands, agents, or settings.

Add a new exploration agent

Exploration agents run in parallel during /ultraplan-local Phase 5. They read the codebase and contribute structured findings to plan synthesis.

1. Copy agents/architecture-mapper.md as a template:

   cp agents/architecture-mapper.md agents/my-new-agent.md
   

2. Update the frontmatter name, description, tools, and model. Use sonnet unless the agent needs deep reasoning (most don't).
3. Add the agent to the swarm in agents/planning-orchestrator.md Phase 5 — register it under the codebase-size bucket where it should fire (always / medium+ / large only).
4. Update the agent table in CLAUDE.md and README.md to keep the doc-consistency test green:

   npm test -- tests/lib/doc-consistency.test.mjs
   

Switch the planning model

The default for /ultrabrief-local, /ultraresearch-local, /ultraplan-local, and /ultraexecute-local is opus (deep reasoning). To run on Sonnet for cost or latency, search-and-replace the frontmatter in three files:

sed -i.bak 's/^model: opus$/model: sonnet/' \
  commands/ultrabrief-local.md \
  commands/ultraresearch-local.md \
  commands/ultraplan-local.md \
  commands/ultraexecute-local.md

The exploration agents stay on Sonnet — only the orchestrator is bumped.

Disable external research

/ultraresearch-local --local skips Tavily, Microsoft Learn, and the Gemini bridge. To make --local the default, edit the front of commands/ultraresearch-local.md Phase 1 and flip the default branch of the --local argument check. Or just always pass --local and document it in your team's CLAUDE.md.

Plugin data contract

The four commands write to a single project directory (.claude/projects/{date}-{slug}/). The full schema for every artifact is in docs/HANDOVER-CONTRACTS.md. That document is the single source of truth for:

• File paths each command reads/writes
• Frontmatter schema for brief.md, research/*.md, plan.md
• progress.json schema
• Validator → handover mapping
• Versioning and breaking-change protocol

If you fork the plugin and change the schema for any artifact, update that doc and the corresponding lib/validators/*.mjs and run npm test — the validators and doc-consistency tests will catch schema drift.

Disable the architect bridge

/ultraplan-local auto-discovers architecture/overview.md if the separate ultra-cc-architect plugin produced one. To suppress this, either don't install ultra-cc-architect, or set architecture/ absent in your project directory. Discovery is additive — missing file is fine, no error.

Contributing

See CONTRIBUTING.md.

License

MIT