ktg-plugin-marketplace/plugins/ultraplan-local

ultraplan-local — Brief, Research, Architect, 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, CC-feature architecture matching, and autonomous execution. Five 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
/ultra-cc-architect-local	Architect (optional) — match brief+research against available CC features; produce architecture note with explicit gaps
/ultraplan-local	Plan — agent swarm exploration, Opus planning, adversarial review
/ultraexecute-local	Execute — disciplined step-by-step implementation with failure recovery
/ultra-skill-author-local	Authoring (v2.3, skill-factory Fase 1) — generate one cc-architect-catalog draft from a local source with IP-hygiene

Every artifact lives in one project directory: .claude/projects/{YYYY-MM-DD}-{slug}/ contains brief.md, research/NN-*.md, architecture/overview.md (+ gaps.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)
/ultra-cc-architect-local	Match to CC features (optional) — match brief+research against Claude Code feature catalog (Hooks, Subagents, Skills, MCP, …) with brief-anchored rationale and honest coverage gaps.	architecture/overview.md + architecture/gaps.md
/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.	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?"

# Match task against available CC features (optional, v2.2)
/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth
# → architecture/overview.md + architecture/gaps.md

# Plan from brief + research + architecture (architecture auto-discovered)
/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.

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)

---

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

Matches the task brief and any research against available Claude Code features (Hooks, Subagents, Skills, Output Styles, MCP, Plan Mode, Worktrees, Background Agents) and produces an architecture note with brief-anchored rationale per feature and an explicit coverage-gap section.

This step is optional. You can go straight from research to planning. Use the architect step when:

• The task touches orchestration, policy, or long-running work where CC-feature choice matters.
• You want a reviewed, explicit feature selection before planning instead of letting the planner pick implicitly.
• You want a backlog of coverage gaps (things the skill catalog does not yet know) in a shareable form.

How it works

1. Read {project_dir}/brief.md + all {project_dir}/research/*.md.
2. Read the CC-feature skill catalog from skills/cc-architect-catalog/.
3. Run feature-matcher + gap-identifier in parallel.
4. Write architecture/overview.md (six required sections, YAML frontmatter).
5. Run architecture-critic + scope-guardian in parallel (unless --quick).
6. Write architecture/gaps.md as issue-ready drafts (unless --no-gaps).

Downstream: /ultraplan-local auto-discovers architecture/overview.md in project mode and treats its cc_features_proposed as priors — exploration agents may override with evidence.

Modes

Flag	Behavior
--project <dir>	Required. Read {dir}/brief.md + {dir}/research/*.md; write to {dir}/architecture/.
--fg	No-op alias (foreground is default since v2.4.0).
--quick	Skip adversarial review (no architecture-critic pass).
--no-gaps	Do not write gaps.md (gap-section remains inside overview.md).

What the architecture note contains

• Context — 3 sentences paraphrasing brief Intent + Goal.
• Proposed CC features — a table with rationale (brief-anchored), supporting skill, and confidence per feature.
• Feature composition — sequence, conflicts, fallbacks.
• Coverage gaps identified — always present, even if empty. Honest "what we don't know yet".
• Alternatives considered — at least one rejected feature combination with rationale from the brief.
• Open questions — forwarded to the plan phase.

CC-feature catalog

The architect command reads from skills/cc-architect-catalog/, a plugin-internal catalog of hand-written skills covering each CC feature at one or more layers (reference, pattern, decision). v2.2 shipped 10 seeds covering all 8 features at the reference layer (plus pattern layer for hooks and subagents). The catalog is designed for expansion via the skill-factory process (v2.3) — gaps surfaced by the architect command are the backlog for that work.

Slug convention (v2.3): files follow <cc_feature>[-<qualifier>]-<layer>.md. Unqualified slugs (e.g., hooks-pattern.md) are the baseline/canonical entry for a (feature, layer) pair. Qualified slugs (e.g., hooks-observability-pattern.md) cover specific sub-patterns without displacing the baseline. feature-matcher prefers the baseline when the brief does not specifically justify a qualified variant; it may propose multiple supporting skills when they cover non-overlapping aspects. Slug collisions with approved skills are a hard error — skill-factory drafts must qualify or revise instead. v2.3.2: skill-drafter performs a pre-write check against {catalog_root}/<slug>.md and prepends a warning block to its confirmation when the proposed slug would collide, suggesting a qualified slug derived from the concept handle. The draft still writes to .drafts/ — the warning exists so users see the overwrite risk before running mv.

Hallucination gate

The architecture-critic agent blocks any feature proposal that is not in the catalog's cc_feature taxonomy or the feature-matcher's documented fallback minimum list. This prevents the architect from inventing CC features that do not exist.

---

/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. Synthesize — findings merged into a unified codebase understanding
6. Plan — Opus creates a comprehensive implementation plan with per-step YAML manifests
7. Critique — adversarial review by plan-critic (9 dimensions) and scope-guardian
8. 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
Profile	/ultraplan-local --project <dir> --profile <name>	Explicit profile override (overrides recommended_profile in brief)
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.

Profiles (M0 — foundation)

A profile describes which exploration/review agents to spawn, which catalog filter to apply, and which adversarial regime to use. Profiles live in profiles/*.yaml and are loaded via scripts/profile-loader.mjs (null-deps Node, limited-subset YAML parser, validates that every referenced agent exists).

M0 ships only the default profile, which mirrors the current hardcoded Phase 5/9 agent set — so existing flows are unaffected. M1 (coming next) lets /ultrabrief-local recommend a profile based on brief content; M2 ships additional built-in profiles (quick, bugfix, feature, refactor, security-deep, research-heavy) and replaces the hardcoded Phase 5 agent table. M3 adds user-extensible profiles in .claude/ultraplan-profiles/.

# Inspect available profiles
node plugins/ultraplan-local/scripts/profile-loader.mjs list

# Load a specific profile (JSON output)
node plugins/ultraplan-local/scripts/profile-loader.mjs load default

# Validate a profile YAML
node plugins/ultraplan-local/scripts/profile-loader.mjs validate path/to/profile.yaml

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

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

---

/ultra-skill-author-local — Authoring (skill-factory Fase 1, v2.3)

Manual one-skill-at-a-time generator for the cc-architect-catalog. Channel 2 of the skill-factory strategy: a curated local source enters, one draft skill exits in skills/cc-architect-catalog/.drafts/ with its n-gram containment score against the source stamped into the frontmatter (or the draft is deleted when the overlap is too high).

Why it exists

/ultra-cc-architect-local enforces a hallucination gate that only permits feature proposals backed by the catalog. With 10 seed skills covering 8 features × 2 layers, the matcher rarely finds support and silently produces empty proposals. This command grows the catalog without spinning up automation: one source → one draft → manual review → manual mv for promotion.

Pipeline

Sequential, no retry, no parallelism:

/ultra-skill-author-local <source>
  → concept-extractor (sonnet)    → JSON: cc_feature, layer, slug
  → skill-drafter (sonnet)        → .drafts/<slug>.md, 9-field frontmatter
  → ip-hygiene-checker (sonnet)   → runs scripts/ngram-overlap.mjs
        verdict accepted/needs-review → stamp ngram_overlap_score
        verdict rejected               → rm draft (no preservation)

Modes

Mode	Usage	Behavior
Default	/ultra-skill-author-local <source>	Run the pipeline (concept → draft → IP-hygiene) foreground
--fg	/ultra-skill-author-local <source> --fg	Same as default; flag accepted for pipeline-convention consistency
--quick	/ultra-skill-author-local <source> --quick	Skip IP-hygiene with BIG WARNING (drafting-pipeline test only)

IP-hygiene utility

scripts/ngram-overlap.mjs — pure Node stdlib, zero dependencies. Word-5-gram containment similarity (asymmetric draft⊆source) plus longest-consecutive-shingle-run secondary signal. Verdict bands: accepted (<0.15 AND <8), needs-review (mid), rejected (≥0.35 OR ≥15). Short-text fallback to n=4 when min(words) <500. CLI emits JSON.

Calibration fixtures in tests/fixtures/skill-factory/ pin the verdict bands against representative prose. Re-verify any threshold change against these fixtures.

Non-goals (explicit, Fase 1)

• No automation, cron, or watcher
• No CC changelog diffing or auto-research
• No batch processing or review command
• No decision-layer skills (cross-feature comparison is Fase 2+)
• No URL or remote sources — local files only
• Manual mv from .drafts/ to catalog root is the promotion mechanism

---

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 → (optional) ─→ →  │ ↓                   │→ │  + 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}/.

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

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
  }
}

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 (v2.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

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

Contributing

See CONTRIBUTING.md.

License

MIT