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

# ultraplan-local

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

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

## Commands

| Command | Description | Model |
|---------|-------------|-------|
| `/ultrabrief-local` | Brief — interactive interview produces a task brief with explicit research plan; optionally orchestrates the pipeline | opus |
| `/ultraresearch-local` | Research — deep local + external research, produces structured research brief | opus |
| `/ultra-cc-architect-local` | Architect *(optional, v2.2)* — match brief+research against Claude Code features; produce architecture note with gaps. Requires `--project` | opus |
| `/ultraplan-local` | Plan — brief-reviewer, explore, plan, review. Requires `--brief` or `--project`. Auto-discovers `architecture/overview.md` if present | opus |
| `/ultraexecute-local` | Execute — disciplined plan/session-spec executor with failure recovery | opus |
| `/ultra-skill-author-local` | Authoring *(v2.3, skill-factory Fase 1)* — generate one cc-architect-catalog draft from a local source with IP-hygiene | opus |

### /ultrabrief-local modes

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

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

### /ultraresearch-local modes

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

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

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

| Flag | Behavior |
|------|----------|
| `--project <dir>` | **Required** — read `{dir}/brief.md` and `{dir}/research/*.md`, write `{dir}/architecture/overview.md` + `{dir}/architecture/gaps.md` |
| `--fg` | No-op alias (foreground is default since v2.4.0) |
| `--quick` | Skip adversarial review (architecture-critic) |
| `--no-gaps` | Skip gap-identifier; overview.md only |

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

### /ultraplan-local modes

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

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

### /ultraexecute-local modes

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

## Agents

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

## Architecture

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

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

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

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

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

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

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

**Pipeline:** `/ultrabrief-local` produces the task brief. `/ultraresearch-local --project <dir>` fills in `{dir}/research/`. `/ultra-cc-architect-local --project <dir>` *(optional, v2.2)* matches available Claude Code features against brief+research and writes `{dir}/architecture/`. `/ultraplan-local --project <dir>` reads brief + research (+ architecture note if present) to produce `{dir}/plan.md`. `/ultraexecute-local --project <dir>` executes and writes `{dir}/progress.json`. All artifacts live in one project directory.

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

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

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

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

## State

All artifacts in one project directory (default):
- Project root: `.claude/projects/{YYYY-MM-DD}-{slug}/`
  - `brief.md` (task brief from `/ultrabrief-local`)
  - `research/{NN}-{slug}.md` (research briefs from `/ultraresearch-local --project`)
  - `architecture/overview.md` + `architecture/gaps.md` (optional, v2.2, from `/ultra-cc-architect-local --project`)
  - `plan.md` (from `/ultraplan-local --project`)
  - `sessions/session-*.md` (from `--decompose`)
  - `progress.json` (from `/ultraexecute-local --project`)

Legacy paths (still work without `--project`):
- Research briefs: `.claude/research/ultraresearch-{date}-{slug}.md`
- Plans: `.claude/plans/ultraplan-{date}-{slug}.md`
- Sessions: `.claude/ultraplan-sessions/{slug}/session-*.md`
- Launch scripts: `.claude/ultraplan-sessions/{slug}/launch.sh`
- Progress: `{plan-dir}/.ultraexecute-progress-{slug}.json`

Stats:
- Brief stats: `${CLAUDE_PLUGIN_DATA}/ultrabrief-stats.jsonl`
- Plan stats: `${CLAUDE_PLUGIN_DATA}/ultraplan-stats.jsonl`
- Exec stats: `${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl`
- Research stats: `${CLAUDE_PLUGIN_DATA}/ultraresearch-stats.jsonl`
- Architect stats: `${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-stats.jsonl`

## Terminology

- **Task brief** — produced by `/ultrabrief-local`. Declares intent, goal, and research plan. Drives planning.
- **Research brief** — produced by `/ultraresearch-local`. Answers a specific research question. Feeds planning.
- **Architecture note** — produced by `/ultra-cc-architect-local`. Proposes which Claude Code features fit the task with brief-anchored rationale + explicit gaps. Enriches planning.

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