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

# ultraplan-local — Brief, Research, Architect, Plan, Execute

![Version](https://img.shields.io/badge/version-2.4.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple)

*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*

A [Claude Code](https://docs.anthropic.com/en/docs/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

```bash
# 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](CHANGELOG.md) 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 |
| **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

### 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):**
```bash
/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):**
```bash
/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):**
```bash
/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:**
```bash
/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:**
```bash
/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](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`:

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

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

```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](https://docs.anthropic.com/en/docs/claude-code) (CLI, desktop app, or web app)
- Claude subscription with Opus access (Max plan recommended)
- Optional: [Tavily MCP server](https://github.com/tavily-ai/tavily-mcp) for enhanced external research
- Optional: [Gemini MCP server](https://github.com/anthropics/anthropic-cookbook/tree/main/tool-use/gemini-mcp) 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](CONTRIBUTING.md).

## License

[MIT](LICENSE)