ktg-plugin-marketplace/plugins/ultraplan-local

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.

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.

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.

What you get

Concrete capabilities, observable in the code — not aspirations.

Across all profiles:

• Strategy-to-execution on four explicit handover points. Each transition is a filesystem contract (docs/HANDOVER-CONTRACTS.md), not a conversation. You can stop after any stage and resume later without context loss.
• Resume safety after long sessions. The PreCompact hook reconciles progress.json with git history before context compaction (CC v2.1.105+) — closes a documented --resume failure mode.
• Schema discipline. plan-validator --strict enforces ### Step N: form and rejects narrative drift (### Fase, ### Phase, ### Stage, ### Steg) before execution.
• Audit trail by construction. Every executed step records commit_sha, verify_passed, files_changed in progress.json.

Solo developer. Plans survive across sessions; adversarial review (plan-critic + scope-guardian) catches your own tunnel vision before code is written; brief-phase forces clarity on what the task actually is. examples/01-add-verbose-flag/ shows what good shape looks like.

Team (2–10). Plan files are handover-ready — a colleague can pick up a project directory without re-asking "what did you mean here?". --decompose splits a plan into self-contained headless sessions with scoped --allowedTools. The plan-critic semantic rubric gives the team a shared definition of "this plan defers decisions to the executor".

Virksomhet / regulated environment. Defense-in-depth security across four layers (plugin hooks, prompt-level denylist, pre-execution plan scan, scoped tool access). disableSkillShellExecution: true recommendation for fork-ers handling untrusted briefs. No cloud dependency, no GitHub requirement. Validators are plain-Node CLIs — invocable from CI, custom hooks, or external tools, not just from ultra commands.

What it doesn't solve:

• LLM output truthfulness. Validators check shape, not facts. A plan with hallucinated paths passes schema but fails in execute. Plan-critic catches some, not all.
• Multi-user concurrency on a single project directory. Two simultaneous executors will clobber progress.json.
• Cost management. Opus on the orchestrator layer is expensive; documented in Cost profile, no automatic model downgrade.
• Linear/Jira/Slack integrations. Intentional omission — solo project, no enterprise wiring.

One-line summary: an executable contract pipeline where each stage is filesystem-validated, session-survivable, and skill-independent — in exchange for writing an actual brief before planning and an actual plan before coding.

---

/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.

A section-driven interview loop fills required brief sections (Intent / Goal / Success Criteria / Research Plan) until each shows initial signal, then brief-reviewer scores the draft on five dimensions (completeness, consistency, testability, scope clarity, research-plan validity) and gates publication. Max 3 review iterations; force-stop yields a brief_quality: partial brief with the failing dimensions documented.

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.

A parallel swarm of up to 5 local + 4 external Sonnet agents investigates 3–8 research dimensions, with optional Gemini Deep Research as an independent second opinion. Findings are triangulated (local vs. external, confidence per dimension, contradictions flagged) and synthesized into a 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 uses up to 5 local agents (architecture-mapper, dependency-tracer, task-finder, git-historian, convention-scanner) and 4 external agents (docs-researcher, community-researcher, security-researcher, contrarian-researcher) plus the optional Gemini bridge for an independent second opinion. Per-agent details in agents/.

---

/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.

After brief-reviewer validates the input brief, 6–8 Sonnet exploration agents analyze the codebase in parallel and merge findings into a synthesis. Optional research briefs (--research, or auto-discovered in {project_dir}/research/) enrich the plan; architecture/overview.md priors are loaded if the ultra-cc-architect plugin produced one. Opus then writes the plan with per-step YAML manifests, which plan-critic (9 dimensions) and scope-guardian adversarially review before handoff.

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 uses 6–8 Sonnet agents in parallel (architecture-mapper, dependency-tracer, task-finder, test-strategist, git-historian, risk-assessor, plus convention-scanner on medium+ codebases and research-scout when unfamiliar tech is detected). Adversarial review then runs brief-reviewer, plan-critic (9 dimensions, no-placeholder enforcement, manifest audit), and scope-guardian (creep + gap detection). Per-agent details in agents/.

---

/ultraexecute-local — Execution

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

Per step: apply Changes exactly as written → run Verify (exit code is truth) → manifest audit (expected paths, forbidden paths, commit pattern) → follow the plan's failure clause if anything fails (revert / retry / skip / escalate) → Checkpoint commit. After all steps: independent Phase 7.5 manifest audit from git log + filesystem (ignoring agent bookkeeping); drift triggers Phase 7.6 bounded recovery.

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

Migration notes for breaking changes (v1.x → v2.0, v2.x → v3.0) live in CHANGELOG.md and MIGRATION.md. v3.x non-breaking — minor bumps within v3 add features without changing pipeline contracts.

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

Opus runs the orchestrators (one per command) and the executor (one per plan session). Sonnet runs the exploration and review swarms (5–10 agents per command, with effort/turn limits). The pipeline front-loads cheap Sonnet work so Opus only does synthesis and execution. Typical total: comparable to a long single Claude Code session — the per-command cost is published in ${CLAUDE_PLUGIN_DATA}/ultra*-stats.jsonl if you want exact numbers.

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

Top-level layout:

ultraplan-local/
├── agents/        19 specialized agents (sonnet for exploration, opus for orchestration)
├── commands/      4 slash commands (ultrabrief, ultraresearch, ultraplan, ultraexecute)
├── templates/     Frontmatter templates for brief, research, plan, session, launch
├── hooks/         5 hooks (pre-bash, pre-write, session-title, post-bash-stats, pre-compact-flush)
├── lib/           Zero-dep parsers and validators (CLI shims under lib/validators/)
├── tests/         109 node:test cases — `npm test` is the fork-readiness gate
├── docs/          HANDOVER-CONTRACTS.md + architect-bridge-test.md
└── examples/      01-add-verbose-flag/ — calibrated end-to-end pipeline demo

Pure markdown commands and agents. Hooks and validators are self-contained Node.js with zero npm dependencies. See CONTRIBUTING.md for the full file inventory.

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