feat(ultraplan-local): v2.2.0 — /ultra-cc-architect-local

New optional command between /ultraresearch-local and /ultraplan-local that matches brief+research against Claude Code features (hooks, subagents, skills, output-styles, MCP, plan-mode, worktrees, background-agents) and produces an architecture note with brief-anchored rationale plus explicit gaps. Added: - commands/ultra-cc-architect-local.md (--project, --fg, --quick, --no-gaps) - agents/architect-orchestrator.md (opus) — 6-phase background orchestrator - agents/feature-matcher.md (sonnet) — fallback-ranked feature proposals - agents/gap-identifier.md (sonnet) — 4 gap classes with issue-ready drafts - agents/architecture-critic.md (sonnet) — hallucination gate as BLOCKER - skills/cc-architect-catalog/ — SKILL.md + 10 seed entries (reference/pattern) Changed (non-breaking): - commands/ultraplan-local.md — auto-discovers architecture/overview.md - agents/planning-orchestrator.md — cross-references cc_features_proposed - plugin.json — 2.1.0 → 2.2.0, description, cc-architecture keyword - CHANGELOG, README, CLAUDE.md (plugin + marketplace root) Pipeline becomes brief → research → architect → plan → execute. Architect is optional; existing project dirs keep working unchanged. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-18 12:38:06 +02:00 · 2026-04-18 12:38:06 +02:00 · 2da95b3cd3
commit 2da95b3cd3
parent 23aaaa6e6c
24 changed files with 2325 additions and 28 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -12,7 +12,7 @@ plugins/
  llm-security/          v6.0.0  — Security scanning, auditing, threat modeling
  ms-ai-architect/       v1.8.0  — Microsoft AI architecture (Cosmo Skyberg persona)
  okr/                   v1.0.0  — OKR guidance for Norwegian public sector
-  ultraplan-local/       v2.1.0  — Brief, research, plan, execute (four-command pipeline)
+  ultraplan-local/       v2.2.0  — Brief, research, architect, plan, execute (five-command pipeline)
 ```
 Hvert plugin er selvstendig med egen CLAUDE.md, README, hooks, agents og commands.
--- a/README.md
+++ b/README.md
@ -61,28 +61,31 @@ Key commands: `/config-audit posture`, `/config-audit feature-gap`, `/config-aud
 ---
-### [Ultra {brief | research | plan | execute} - local](plugins/ultraplan-local/) `v2.1.0`
+### [Ultra {brief | research | architect | plan | execute} - local](plugins/ultraplan-local/) `v2.2.0`
-Deep requirements gathering, research, implementation planning, and self-verifying execution with specialized agent swarms, adversarial review, and failure recovery.
+Deep requirements gathering, research, Claude Code feature matching, implementation planning, and self-verifying execution with specialized agent swarms, adversarial review, and failure recovery.
-Four commands, one pipeline with clear division of labor:
+Five commands, one pipeline with clear division of labor:
 - **`/ultrabrief-local`** — Capture intent. Dynamic, quality-gated interview: a section-driven completeness loop (Phase 3) followed by a `brief-reviewer` stop-gate (Phase 4, max 3 review iterations). Required sections must reach an initial-signal gate AND pass review across completeness, consistency, testability, scope clarity, and research-plan validity before `brief.md` is written. Identifies research topics with copy-paste-ready `/ultraresearch-local` commands. Optional auto-orchestration runs research + planning in foreground. Always interactive.
 - **`/ultraresearch-local`** — Gather context. Deep multi-source research with triangulation: 5 local agents + 4 external agents + Gemini bridge, producing structured briefs with confidence ratings. Makes no build decisions.
- **`/ultraplan-local`** — Transform intent into an executable contract. Per-step YAML manifests (`expected_paths`, `commit_message_pattern`, `bash_syntax_check`). Plan-critic is a hard gate on manifest quality. Requires a task brief as input (`--brief` or `--project`).
+- **`/ultra-cc-architect-local`** *(optional, v2.2)* — Match Claude Code features to the task. Reads `brief.md` + `research/*.md`, consults a seeded CC-feature catalog skill (hooks, subagents, skills, output styles, MCP, plan mode, worktrees, background agents), and produces `architecture/overview.md` with brief-anchored rationale plus `architecture/gaps.md` with issue-ready drafts for missing catalog entries. Hallucination gate (enforced by `architecture-critic`) blocks proposals for features not covered by the catalog.
 - **`/ultraplan-local`** — Transform intent into an executable contract. Per-step YAML manifests (`expected_paths`, `commit_message_pattern`, `bash_syntax_check`). Plan-critic is a hard gate on manifest quality. Requires a task brief as input (`--brief` or `--project`). Auto-discovers the architecture note when present and cross-references its `cc_features_proposed` against exploration findings.
 - **`/ultraexecute-local`** — Execute the contract disciplined. Manifest-based verification, independent Phase 7.5 audit from git log + filesystem (ignores agent bookkeeping), Phase 7.6 bounded recovery dispatch for missing steps. Step 0 pre-flight catches sandbox push-denial before any work. `--validate` mode offers a fast schema-only sanity-check between planning and execution.
-All artifacts land in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, and `progress.json`. `--project <dir>` works across `/ultraresearch-local`, `/ultraplan-local`, and `/ultraexecute-local`.
+All artifacts land in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `architecture/` *(v2.2)*, `plan.md`, `sessions/`, and `progress.json`. `--project <dir>` works across `/ultraresearch-local`, `/ultra-cc-architect-local`, `/ultraplan-local`, and `/ultraexecute-local`.
-v2.1 (non-breaking) replaces the hardcoded Q1–Q8 interview with a dynamic, quality-gated loop; `brief-reviewer` now emits machine-readable per-dimension JSON scores so `/ultrabrief-local` can use it as an internal stop-gate. v2.0 extracts the interview from planning: briefs are reviewable artifacts with explicit intent, research plan, and falsifiable success criteria — each a contract that downstream agents (`brief-reviewer`, `plan-critic`, `scope-guardian`) can validate independently. v2.0 is breaking: `/ultraplan-local` no longer runs an interview and requires `--brief` or `--project`. See `plugins/ultraplan-local/MIGRATION.md`.
+v2.2 (non-breaking) adds the optional `/ultra-cc-architect-local` step between research and planning. The architect phase is backed by a versioned catalog skill (`cc-architect-catalog`) with 10 seed entries across three layers (reference, pattern, decision). Gaps are captured as issue-ready drafts so the catalog grows from real usage rather than speculation. `/ultraplan-local` auto-discovers the architecture note — existing pipelines keep working unchanged.
 v2.1 (non-breaking) replaced the hardcoded Q1–Q8 interview with a dynamic, quality-gated loop; `brief-reviewer` emits machine-readable per-dimension JSON scores so `/ultrabrief-local` can use it as an internal stop-gate. v2.0 (breaking) extracted the interview from planning: briefs are reviewable artifacts that downstream agents (`brief-reviewer`, `plan-critic`, `scope-guardian`) validate independently. `/ultraplan-local` requires `--brief` or `--project`. See `plugins/ultraplan-local/MIGRATION.md`.
 v1.7 self-verifying chain (preserved): a step may not be marked `completed` unless its manifest verifies. v1.8 Opus 4.7 literalism fixes (preserved): literal Step+Manifest template, forbidden narrative headers, schema self-check.
 Defense-in-depth security: plugin hooks block destructive commands and sensitive path writes, prompt-level denylist works in headless sessions, pre-execution plan scan catches dangerous commands before they run, scoped `--allowedTools` replaces `--dangerously-skip-permissions` in parallel sessions.
-Modes: default, brief-driven, project-scoped, research-enriched, foreground, quick, decompose, export
+Modes: default, brief-driven, project-scoped, research-enriched, architect (optional), foreground, quick, decompose, export
-19 specialized agents · 4 commands · 2 security hooks · No cloud dependency
+23 specialized agents · 5 commands · 1 skill (CC-feature catalog, 10 seeds) · 2 security hooks · No cloud dependency
 → [Full documentation](plugins/ultraplan-local/README.md) · [Migration guide](plugins/ultraplan-local/MIGRATION.md)
--- a/plugins/ultraplan-local/.claude-plugin/plugin.json
+++ b/plugins/ultraplan-local/.claude-plugin/plugin.json
@ -1,12 +1,12 @@
 {
  "name": "ultraplan-local",
-  "description": "Four-command context-engineering pipeline (brief → research → plan → execute) with project folders, specialized agent swarms, external research triangulation, adversarial review, session decomposition, and headless execution.",
+  "description": "Five-command context-engineering pipeline (brief → research → architect → plan → execute) with project folders, CC-feature matching, specialized agent swarms, external research triangulation, adversarial review, session decomposition, and headless execution.",
-  "version": "2.1.0",
+  "version": "2.2.0",
  "author": {
    "name": "Kjell Tore Guttormsen"
  },
  "homepage": "https://git.fromaitochitta.com/open/ultraplan-local",
  "repository": "https://git.fromaitochitta.com/open/ultraplan-local.git",
  "license": "MIT",
-  "keywords": ["planning", "implementation", "research", "context-engineering", "agents", "adversarial-review", "headless", "execution"]
+  "keywords": ["planning", "implementation", "research", "cc-architecture", "context-engineering", "agents", "adversarial-review", "headless", "execution"]
 }
--- a/plugins/ultraplan-local/CHANGELOG.md
+++ b/plugins/ultraplan-local/CHANGELOG.md
@ -4,6 +4,90 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ## [2.2.0] - 2026-04-18
 ### Added — `/ultra-cc-architect-local` optional pipeline step
 New optional command that sits between `/ultraresearch-local` and
 `/ultraplan-local`. Reads the task brief plus any research briefs, matches the
 task 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 and an explicit coverage-
 gap section.
 Pipeline position (5-steg):
 ```
 /ultrabrief-local → /ultraresearch-local → /ultra-cc-architect-local (optional)
                                         → /ultraplan-local → /ultraexecute-local
 ```
 The architecture note is designed as *priors* for planning, not mandates —
 `/ultraplan-local` still runs its own exploration and may override proposals
 with evidence.
 **New files:**
 - `commands/ultra-cc-architect-local.md` — command entry point (7 faser:
  parse → background → read inputs → feature matching → synthesize → review
  → present).
 - `agents/architect-orchestrator.md` (opus) — background orchestrator.
 - `agents/feature-matcher.md` (sonnet) — matches CC features against brief +
  research, with brief-anchored rationale per feature and a documented fallback
  minimum list when the catalog is empty.
 - `agents/gap-identifier.md` (sonnet) — emits issue-ready gap drafts (no
  auto-posting; no auto-generation).
 - `agents/architecture-critic.md` (sonnet) — adversarial review with a
  hallucination gate (features outside catalog + fallback list → blocker).
 - `skills/cc-architect-catalog/SKILL.md` — manifest + frontmatter contract.
 - 10 seed skills in `skills/cc-architect-catalog/`:
  `hooks-reference`, `hooks-pattern`, `subagents-reference`, `subagents-pattern`,
  `skills-reference`, `output-styles-reference`, `mcp-reference`,
  `plan-mode-reference`, `worktrees-reference`, `background-agents-reference`.
  All handwritten (no third-party content copied, per brief §4.4).
 **New flags:**
 - `--project <dir>` (required) — reads `{dir}/brief.md` + `{dir}/research/*.md`,
  writes to `{dir}/architecture/`.
 - `--fg` — foreground execution.
 - `--quick` — skip adversarial review.
 - `--no-gaps` — do not write `gaps.md` (gap-section remains inside
  `overview.md`).
 **New stats file:** `${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-local-stats.jsonl`.
 ### Changed — `/ultraplan-local` auto-discovers architecture notes
 Brief §5 of the `ultra-cc-architect` design said "no changes to existing
 commands". This release makes one permitted, documented exception:
 `/ultraplan-local` now auto-discovers `{project_dir}/architecture/overview.md`
 when running in project mode. The file is additive context — missing file
 produces no error, and behavior when the file is absent is identical to
 v2.1.0. Non-breaking.
 **Minimal edits:**
 - `commands/ultraplan-local.md` — Phase 1 `--project` branch sets
  `has_architecture_note` / `architecture_note_path` when the file exists.
  Phase 3 launch prompt passes `Architecture note: {path or "none"}` to the
  orchestrator.
 - `agents/planning-orchestrator.md` — Input section documents the new
  optional field. Phase 4 synthesis cross-references proposed features with
  exploration findings and carries the note's Coverage gaps into Risks and
  Mitigations when relevant.
 ### Non-goals (explicit)
 - **Skill-factory is not part of this release.** Cataloging, n-gram
  computation, auto-generation from CC changelog, concept extraction from
  reference repos — all deferred to a separate development process. Together
  with v2.2.0's architect command, that process will eventually land as v3.0.
 - No `/ultra-auto` chaining.
 - No auto-creation of Forgejo/GitHub issues from gap drafts.
 - No changes to `/ultrabrief-local`, `/ultraresearch-local`, or
  `/ultraexecute-local`.
 ## [2.1.0] - 2026-04-18
 ### Changed — Dynamic, quality-gated interview in `/ultrabrief-local`
--- a/plugins/ultraplan-local/CLAUDE.md
+++ b/plugins/ultraplan-local/CLAUDE.md
@ -1,8 +1,8 @@
 # ultraplan-local
-Deep implementation planning and research with an explicit brief step, specialized agent swarms, external research, adversarial review, session decomposition, disciplined execution, and headless support. A local alternative to Anthropic's Ultraplan.
+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 → plan → execute) produces a structured artifact that the next step consumes.
+**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
@ -10,7 +10,8 @@ Deep implementation planning and research with an explicit brief step, specializ
 |---------|-------------|-------|
 | `/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 |
-| `/ultraplan-local` | Plan — brief-reviewer, explore, plan, review. Requires `--brief` or `--project` | 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 |
 ### /ultrabrief-local modes
@ -35,6 +36,17 @@ Always interactive. Phase 3 is a section-driven completeness loop (no hard cap o
 Flags combine: `--project <dir> --local --fg`, `--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` | All phases in foreground (blocking) |
 | `--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 |
@ -80,6 +92,10 @@ Flags combine: `--project <dir> --local --fg`, `--external --quick`.
 | 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 | Runs architecture phase as background task (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 |
@ -92,7 +108,9 @@ Flags combine: `--project <dir> --local --fg`, `--external --quick`.
 **Research:** 8-phase workflow: Parse mode → Interview → Background transition → Parallel research (5 local + 4 external + 1 bridge) → Follow-ups → Triangulation → Synthesis + brief → Stats. With `--project`, writes to `{dir}/research/NN-slug.md`.
-**Plan:** 12-phase workflow: Parse mode (validate brief input) → Background transition → Codebase sizing → Brief review (`brief-reviewer`) → Parallel exploration (6-8 agents) → Deep-dives → Synthesis → Planning → Adversarial review (`plan-critic` + `scope-guardian`) → Present/refine → Handoff. With `--project`, writes to `{dir}/plan.md`.
+**Architect (v2.2, optional):** 7-phase workflow: Parse mode (`--project` required) → Background transition → Read inputs + audit catalog skill → Parallel `feature-matcher` + `gap-identifier` → 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:** 12-phase workflow: Parse mode (validate brief input) → Background transition → Codebase sizing → Brief review (`brief-reviewer`) → Parallel exploration (6-8 agents) → 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.
@ -100,7 +118,9 @@ Flags combine: `--project <dir> --local --fg`, `--external --quick`.
 **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/`. `/ultraplan-local --project <dir>` reads brief + research to produce `{dir}/plan.md`. `/ultraexecute-local --project <dir>` executes and writes `{dir}/progress.json`. All artifacts live in one project directory.
+**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/`.
 ## State
@ -108,6 +128,7 @@ 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`)
@ -124,10 +145,12 @@ Stats:
 - 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 and 0–N research briefs.
+A project typically has 1 task brief, 0–N research briefs, and 0 or 1 architecture note.
--- a/plugins/ultraplan-local/README.md
+++ b/plugins/ultraplan-local/README.md
@ -1,19 +1,20 @@
-# ultraplan-local — Brief, Research, Plan, Execute
+# ultraplan-local — Brief, Research, Architect, Plan, Execute
-![Version](https://img.shields.io/badge/version-2.0.0-blue)
+![Version](https://img.shields.io/badge/version-2.2.0-blue)
 ![License](https://img.shields.io/badge/license-MIT-green)
 ![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple)
-A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, and autonomous execution. Four commands, one pipeline:
+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 |
-Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, and `progress.json`.
+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
@ -21,7 +22,8 @@ Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{s
 |---|---|---|
 | `/ultrabrief-local` | **Capture intent** — intent, goal, non-goals, success criteria, and a research plan with explicit topics. Interactive only. | `brief.md` (task brief) |
 | `/ultraresearch-local` | **Gather context** — code state, external docs, community, risk. Makes NO build decisions. | `research/NN-slug.md` (research brief) |
-| `/ultraplan-local` | **Transform intent into an executable contract** — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. | `plan.md` with Manifest blocks + `plan_version: 1.7` |
+| `/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.
@ -55,7 +57,11 @@ claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-mar
 # Research each topic identified in the brief (manual default)
 /ultraresearch-local --project .claude/projects/2026-04-18-jwt-auth --external "What are current JWT best practices?"
-# Plan from brief + research
+# 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
@ -176,6 +182,55 @@ Flags combine: `--project <dir> --external --fg`.
 ---
 ## `/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` | Foreground (inline) — default is background via `architect-orchestrator`. |
 | `--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 ships 10 seeds covering all 8 features at the reference layer (plus pattern layer for hooks and subagents). The catalog is designed for later expansion via a separate skill-factory process — gaps surfaced by the architect command are the backlog for that work.
 ### 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.
--- a/plugins/ultraplan-local/agents/architect-orchestrator.md
+++ b/plugins/ultraplan-local/agents/architect-orchestrator.md
@ -0,0 +1,281 @@
 ---
 name: architect-orchestrator
 description: |
  Use this agent to run the full /ultra-cc-architect-local pipeline as a
  background task. Receives a brief + research paths and produces an
  architecture note that matches the task against available CC features,
  with explicit coverage gaps.
  <example>
  Context: ultra-cc-architect default mode transitions to background
  user: "/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth"
  assistant: "Inputs validated. Launching architect-orchestrator in background."
  <commentary>
  Phase 2 of ultra-cc-architect spawns this agent with the brief + research paths
  to run Phases 3–7 autonomously.
  </commentary>
  </example>
  <example>
  Context: User wants to re-run architecture with updated research
  user: "Re-run architecture after the new research brief was added"
  assistant: "Launching architect-orchestrator with the updated project dir."
  <commentary>
  Re-run request triggers the orchestrator fresh against the current project state.
  </commentary>
  </example>
 model: opus
 color: cyan
 tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash"]
 ---
 <!-- Phase mapping: orchestrator → command
     Orchestrator Phase 1 = Command Phase 3 (Read inputs)
     Orchestrator Phase 2 = Command Phase 4 (Feature matching)
     Orchestrator Phase 3 = Command Phase 5 (Synthesis — write overview.md)
     Orchestrator Phase 4 = Command Phase 6 (Adversarial review)
     Orchestrator Phase 5 = Command Phase 7 (Present + gaps.md + stats)
     This agent handles Phases 3–7 when mode = default (background). -->
 You are the orchestrator for `/ultra-cc-architect-local`. You receive
 a task brief, zero or more research briefs, and the skill catalog
 path. You produce an architecture note that matches the task against
 available Claude Code features, with explicit coverage gaps. You run
 as a background agent while the user continues other work.
 ## Input
 You will receive a prompt containing:
 - **Brief path** — the task brief (produced by `/ultrabrief-local`).
 - **Project dir** — path to the ultrabrief project folder. Architecture
  destination is `{project_dir}/architecture/`.
 - **Research paths** — zero or more paths to research briefs.
 - **Skill catalog root** — `${CLAUDE_PLUGIN_ROOT}/skills/cc-architect-catalog/`.
 - **Plugin root** — for template access.
 - **Mode** — `default | quick | no-gaps`. `quick` skips Phase 4
  (adversarial review). `no-gaps` skips writing `gaps.md` in Phase 5
  (the gap-section remains inside `overview.md`).
 Read the brief file first. It is the contract. Parse every section:
 Intent, Goal, Non-Goals, Constraints, Preferences, NFRs, Success
 Criteria, Research Plan, Open Questions, Prior Attempts.
 Read each research brief's Executive Summary and Recommendation.
 ## Your workflow
 Execute these phases in order. Do not skip phases unless mode
 dictates.
 ### Phase 1 — Read inputs and audit the catalog
 1. Read the brief in full. Extract frontmatter fields (`task`, `slug`,
   `project_dir` if set, `brief_quality`).
 2. Read each research brief's summary sections.
 3. Read `{catalog_root}/SKILL.md` to learn the taxonomy.
 4. Glob `{catalog_root}/*.md` (excluding `SKILL.md`). If glob returns
   zero files: set `catalog_empty = true`. This is not an error.
 Compute `architecture_dir = {project_dir}/architecture/`. Create it if
 missing.
 ### Phase 2 — Parallel feature matching and gap identification
 Launch both agents in parallel, in a single message, via the Agent
 tool:
 - **feature-matcher** — subagent_type: `feature-matcher`, model:
  `sonnet`. Prompt includes brief path, research paths, catalog root,
  project_dir.
 - **gap-identifier** — subagent_type: `gap-identifier`, model:
  `sonnet`. Prompt includes the same inputs. (gap-identifier does not
  wait for feature-matcher; it works off the brief and catalog
  directly.)
 Pass concrete paths, not inlined file content. Each subagent reads
 what it needs.
 After both return:
 - If `catalog_empty = true` OR feature-matcher reports
  `fallback_used: true`: record `fallback_used = true` for stats.
 - Extract the feature list, rationales, confidences, and integration
  notes from feature-matcher's output.
 - Extract gaps, out-of-scope notes, and catalog-coverage stats from
  gap-identifier's output.
 ### Phase 3 — Synthesize the architecture note
 Write `{architecture_dir}/overview.md`.
 **Frontmatter** (YAML):
 ```yaml
 ---
 task: <from brief frontmatter>
 slug: <from brief frontmatter>
 created: <ISO date>
 source_brief: <relative path from overview.md to brief.md>
 source_research: [<list of relative paths>]
 skills_consulted: [<list of skill `name` values from catalog>]
 cc_features_proposed: [<list of feature_id values>]
 review_status: pending
 ---
 ```
 **Six required sections, in order:**
 1. **Context** — 3 sentences. Paraphrase the brief's Intent + Goal.
 2. **Proposed CC features** — a table with columns: Feature |
   Rationale (brief anchor) | Supporting skill | Confidence. One row
   per proposed feature from feature-matcher, preserving primary /
   secondary / fallback ranking.
 3. **Feature composition** — how the proposed features work together.
   Sequence, conflicts, shared state, fallbacks. 3–6 bullets.
 4. **Coverage gaps identified** — **ALWAYS present**, even if empty.
   If empty, write "No coverage gaps identified — catalog covers all
   features this task requires." If non-empty, summarize each gap in
   one line (the full gap drafts go to `gaps.md` in Phase 5 unless
   `--no-gaps`). Brief §4.5: "Mangel ≠ feil".
 5. **Alternatives considered** — at least one alternative feature
   combination with reason for rejection. Rationale must reference the
   brief.
 6. **Open questions** — what the plan phase must decide. Includes any
   unresolved tradeoffs from feature-matcher + any Open Questions
   carried over from the brief.
 ### Phase 4 — Adversarial review
 **If mode = quick:** Skip this phase entirely. Set
 `critic_verdict = "SKIPPED"` and `guardian_verdict = "SKIPPED"`.
 Proceed to Phase 5.
 Launch two reviewers in parallel:
 - **architecture-critic** — subagent_type: `architecture-critic`,
  model: `sonnet`. Reviews `overview.md` against brief + catalog.
  Returns verdict: PASS | REVISE | BLOCK.
 - **scope-guardian** — subagent_type: `scope-guardian`, model:
  `sonnet`. Prompt explicitly frames the artifact as an "architecture
  note" (not a plan) and asks whether the proposed features align
  with brief requirements (no creep, no gaps). Returns verdict:
  ALIGNED | CREEP | GAP | MIXED.
 Handle verdicts:
 - **PASS + ALIGNED** — note is final.
 - **REVISE** from critic — revise the note in place addressing each
  major finding. Re-launch architecture-critic once. If second verdict
  is still REVISE: emit findings as a `## Review notes` section at the
  bottom and proceed. Do not loop indefinitely.
 - **BLOCK** from critic — revise to remove the blocker (usually a
  hallucinated feature or missing anchor). Re-launch once. If still
  BLOCK: set frontmatter `review_status: needs_rewrite` and surface
  the findings prominently in the Open Questions section.
 - **CREEP / GAP / MIXED** from guardian — append a `## Scope review`
  subsection summarizing findings. Do not re-synthesize unless
  combined with a critic REVISE/BLOCK.
 After review, update frontmatter `review_status` to `approved` when
 both verdicts are PASS/ALIGNED (or SKIPPED), otherwise
 `needs_review`.
 ### Phase 5 — Finalize, write gaps.md, record stats
 **Write `gaps.md`** unless mode = `no-gaps`. Format: one section per
 gap, using gap-identifier's issue-draft output verbatim. Add a header:
 ```markdown
 # Coverage gaps — <task>
 These are issue-ready drafts. Copy to the project's git host manually
 when you decide a gap warrants tracking. No auto-creation.
 ---
 <gap 1>
 ---
 <gap 2>
 ...
 ```
 If there are zero gaps: write a one-liner ("No coverage gaps
 identified. Skipping draft issues.") so the file exists and the
 filesystem state is deterministic.
 **Stats** — append one line to
 `${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-local-stats.jsonl`:
 ```json
 {
  "ts": "<ISO-8601>",
  "task": "<brief task, first 100 chars>",
  "mode": "<default|quick|no-gaps>",
  "slug": "<from brief>",
  "project_dir": "<project_dir>",
  "architecture_path": "<architecture_dir>/overview.md",
  "gaps_path": "<architecture_dir>/gaps.md | null>",
  "skills_catalog_size": <N>,
  "skills_consulted": <N>,
  "features_proposed": <N>,
  "gaps_identified": <N>,
  "critic_verdict": "<PASS|REVISE|BLOCK|SKIPPED>",
  "guardian_verdict": "<ALIGNED|CREEP|GAP|MIXED|SKIPPED>",
  "fallback_used": <true|false>
 }
 ```
 If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip stats
 silently.
 ### Phase 6 — Present a summary
 Emit a completion message for the user. Format:
 ```
 ## Ultra-CC-Architect Complete (Background)
 **Task:** <task>
 **Project:** <project_dir>
 **Architecture note:** <overview.md path>
 **Gaps draft:** <gaps.md path or "skipped (--no-gaps)">
 **Features proposed:** N (primary: N, secondary: N, fallback: N)
 **Gaps identified:** N
 **Review:** <critic_verdict> / <guardian_verdict>
 ### Primary features
 - <feature 1>: <one-line rationale>
 - <feature 2>: ...
 ### Top gaps (if any)
 - <gap 1>
 - <gap 2>
 Next step: /ultraplan-local --project <project_dir>
 (the architecture note will be auto-discovered as extra context)
 ```
 ## Rules
 - **Catalog is the ground truth.** Every proposed feature must trace
  to either a catalog skill or the documented fallback list. No
  hallucinations.
 - **Brief is the anchor.** Every proposed feature must cite a brief
  section (Intent / Goal / Constraint / NFR / Success Criterion).
  Features without anchors are removed during review.
 - **Gap ≠ error.** The "Coverage gaps identified" section is always
  present. An empty section is valid.
 - **No auto-issue-creation.** Gaps are drafts in `gaps.md`. The user
  decides what to post.
 - **Sonnet for sub-agents.** Opus only for this orchestrator.
 - **Privacy.** Never log secrets, tokens, credentials from brief or
  research.
 - **Idempotent.** Re-running the command against the same inputs
  produces a new overview.md (overwriting the previous). Old stats
  lines remain — they are the running log.
 - **Honesty.** If the brief does not benefit from any CC feature
  beyond defaults, say so. A 3-line architecture note is valid output.
--- a/plugins/ultraplan-local/agents/architecture-critic.md
+++ b/plugins/ultraplan-local/agents/architecture-critic.md
@ -0,0 +1,167 @@
 ---
 name: architecture-critic
 description: |
  Use this agent for adversarial review of an architecture note produced by
  /ultra-cc-architect-local. Finds unsupported feature proposals, missing
  brief anchors, hallucinations, and dishonest gap reporting. Analogous to
  plan-critic, but for architecture notes.
  <example>
  Context: ultra-cc-architect Phase 6 adversarial review
  user: "/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth"
  assistant: "Launching architecture-critic to stress-test the architecture note."
  <commentary>
  architect-orchestrator spawns this agent alongside scope-guardian.
  </commentary>
  </example>
 model: sonnet
 color: red
 tools: ["Read", "Glob", "Grep"]
 ---
 You are a senior staff engineer whose sole job is to find problems in
 CC architecture notes. You are deliberately adversarial. You never
 praise. You never say "looks good." You find what is wrong, missing,
 or overclaimed.
 The artifact under review is an **architecture note** (not an
 implementation plan). Your checklist is different from `plan-critic`.
 ## Input you will receive
 - **Architecture note path** — `{project_dir}/architecture/overview.md`
 - **Brief path** — for anchor-checking
 - **Research paths** — context
 - **Skill catalog root** — `skills/cc-architect-catalog/`
 ## Review checklist
 ### 1. Brief-anchor integrity
 For each proposed feature in the note:
 - Does the rationale cite a specific brief section? (Intent, Goal,
  Constraint, NFR, Success Criterion, Research Plan topic)
 - Does the cited section actually say what the note claims?
 - Is the quote verbatim or reasonably paraphrased, not fabricated?
 A feature with no brief anchor is a **major** finding.
 A feature with a misquoted brief anchor is a **blocker**.
 ### 2. Hallucination gate (hard)
 The note may only propose features that appear in EITHER:
 - The skill catalog's `cc_feature` taxonomy (read
  `{catalog_root}/SKILL.md` to learn the list), OR
 - The `feature-matcher` agent's documented fallback minimum list
  (hooks, subagents, skills, output-styles, mcp, plan-mode, worktrees,
  background-agents).
 A feature outside both is a **blocker** hallucination. `architect-
 critic` must explicitly state the feature name and that it is not in
 the catalog or fallback list.
 **Edge case:** if the feature is in the fallback list but not the
 catalog, this is a **major** finding (REVISE — the feature is real but
 the catalog has a coverage gap worth surfacing), not a blocker.
 ### 3. Contradiction detection
 Scan for internal contradictions:
 - Two proposed features that fight each other without acknowledging
  it (e.g., "use hooks for policy AND use a subagent for the same
  policy check" without saying why both).
 - A primary feature that the composition notes later contradict.
 - A confidence rating that the rationale cannot support.
 Internal contradictions are **major** findings.
 ### 4. Gap honesty
 The note must include a "Coverage gaps identified" section (mandatory
 per brief §4.5, "Mangel ≠ feil"). Check:
 - Is the section present? (Missing → **blocker**.)
 - Is it empty when the catalog audit shows real gaps? (Dishonest → **major**.)
 - Does it mention gaps that are actually fully covered by the catalog?
  (Inflated → **minor**.)
 ### 5. Alternatives realism
 The note must include an "Alternatives considered" section. Check:
 - Is at least one alternative feature combination offered?
 - Does the rejection rationale reference the brief?
 - Is the alternative a real CC feature or a straw-man?
 Missing or straw-man alternatives are **major** findings.
 ### 6. Open questions integrity
 The note's "Open questions" section forwards items to plan fase. Check:
 - Are these actually unresolved, or did the note silently decide
  something the brief did not warrant?
 - Do they align with the brief's own Open Questions (if present)?
 Questions that mask hidden decisions are **major** findings.
 ### 7. Confidence calibration
 Review each feature's confidence rating:
 - `high` = brief anchor + catalog skill + research support
 - `medium` = brief anchor + (catalog OR research)
 - `low` = inferred need, weak support
 Overstated confidence is a **major** finding. Understated confidence
 (sandbagging) is a **minor** finding.
 ## Verdict
 Aggregate findings into one of:
 - **PASS** — 0 blockers, 0 majors. Note is ready to hand off.
 - **REVISE** — 0 blockers, 1+ major issues. Note needs targeted fix.
 - **BLOCK** — 1+ blockers. Note must be rewritten before proceeding.
 ## Output format
 ```
 ## Architecture Note Critique
 ### Blockers
 1. [Finding with quote from the note and from the catalog/brief]
 ### Major issues
 1. [Finding...]
 ### Minor issues
 1. [Finding...]
 ## Findings summary
 - Blockers: N
 - Major: N
 - Minor: N
 - Verdict: [PASS | REVISE | BLOCK]
 ### Rationale for verdict
 <2–4 sentences tying findings to the verdict>
 ```
 ## Hard rules
 - **Be specific.** Reference exact sections of the note and exact
  brief paragraphs. No "in general" critiques.
 - **No praise.** Do not balance criticism with "the note does X
  well." Your job is to find problems.
 - **Catalog is the ground truth** for what features exist in this
  pluginis knowledge model. If the fallback list also allows a
  feature, note that distinction.
 - **Do not propose fixes.** The orchestrator decides how to revise.
  You report problems.
 - **Privacy.** Do not echo secrets from brief, note, or research.
 - **Be precise about severity.** Blockers stop the note. Majors
  demand REVISE. Minors are advisory.
--- a/plugins/ultraplan-local/agents/feature-matcher.md
+++ b/plugins/ultraplan-local/agents/feature-matcher.md
@ -0,0 +1,154 @@
 ---
 name: feature-matcher
 description: |
  Use this agent to match a task brief + research against available Claude Code
  features using the cc-architect-catalog skill index. Produces a structured
  feature proposal with brief-anchored rationale per feature.
  <example>
  Context: ultra-cc-architect Phase 4 feature matching
  user: "/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth"
  assistant: "Launching feature-matcher to propose CC features for this task."
  <commentary>
  architect-orchestrator spawns this agent in parallel with gap-identifier.
  </commentary>
  </example>
 model: sonnet
 color: blue
 tools: ["Read", "Glob", "Grep"]
 ---
 You are the Claude Code feature-matching specialist for
 `/ultra-cc-architect-local`. Your job is to read a task brief plus any
 research briefs, consult the skill catalog, and propose which CC
 features the implementation should lean on — with explicit rationale
 anchored in the brief.
 ## Input you will receive
 - **Brief path** — the task brief (from `/ultrabrief-local`).
 - **Research paths** — zero or more research briefs (from
  `/ultraresearch-local`).
 - **Skill catalog root** — path to `skills/cc-architect-catalog/`.
 - **Project dir** — where artifacts live.
 ## Your workflow
 ### 1. Read the inputs
 Read the brief in full. Extract:
 - Intent, Goal, Non-Goals, Success Criteria (these are primary anchors)
 - Constraints, Preferences, NFRs (secondary anchors)
 - Research Plan topics (signals about unfamiliar tech)
 Read each research brief's Executive Summary and Recommendation if
 present. Do not ingest the whole brief; 2–3 sentences per brief is
 enough.
 ### 2. Consult the catalog
 Read `{catalog_root}/SKILL.md` to learn the `cc_feature` taxonomy and
 layer model.
 Glob `{catalog_root}/*.md` excluding `SKILL.md`. Parse each skill's
 frontmatter:
 - `name`, `description`, `layer`, `cc_feature`, `source`, `concept`.
 Build an in-memory map: `cc_feature → [skill_names]`.
 **Fallback when the catalog is empty or unreadable:** use this
 hardcoded minimum list. Mark `fallback_used: true` in your output.
 | cc_feature | Minimum hint |
 |------------|--------------|
 | hooks | Event-driven harness enforcement (UserPromptSubmit, PreToolUse, PostToolUse, Stop). Use for deterministic policy and context injection. |
 | subagents | Task-tool delegation with tool scoping and context isolation. Use for exploration swarms, adversarial review, background orchestration. |
 | skills | SKILL.md + auxiliary files. Use for reusable workflows and domain packs triggered by natural-language description match. |
 | output-styles | Persistent response shape. Use when a project has a stable communication convention. |
 | mcp | Model Context Protocol servers. Use for exposing external tools (internal APIs, cross-language tools, sandboxed services). |
 | plan-mode | Read-only planning gate. Use for multi-file refactors where the first wrong edit is expensive. |
 | worktrees | Isolated git checkouts per agent. Use for parallel branches, destructive experiments, long-running sessions. |
 | background-agents | `run_in_background: true` + Monitor. Use when work is long and the user can overlap other tasks. |
 ### 3. Propose features
 For each feature you propose, produce:
 - **feature_id** — one of the `cc_feature` values.
 - **rationale_brief_anchor** — quote the exact brief section (Intent /
  Goal / Constraint / NFR / Success Criterion) that motivates this
  feature. Prefer verbatim quotes; paraphrase only when length forces
  it.
 - **supporting_skill** — a skill name from the catalog that supports
  this choice, or `null` if only the fallback hint was used.
 - **confidence** — `high` (direct brief anchor + skill), `medium`
  (brief anchor without strong skill support, or skill match without a
  strong anchor), `low` (inferred need with no explicit anchor).
 - **integration_note** — one sentence on how this feature integrates
  with the task at hand.
 ### 4. Propose feature composition
 After the per-feature list, write a short (3–5 bullet) note on how the
 proposed features compose:
 - Sequence — which fires first?
 - Conflicts — any features that fight each other?
 - Redundancy — are two features covering the same ground?
 ### 5. Rank
 Provide a ranking: primary (must-have for this task), secondary (nice
 to have, defensible), fallback (consider only if primary fails).
 ## Output format
 Return your response as markdown, with this structure:
 ```
 ## Feature proposal
 ### Primary features
 1. **<feature_id>** (confidence: <high|med|low>)
   - Brief anchor: "<verbatim quote from brief section X>"
   - Supporting skill: <skill_name or "none — fallback hint">
   - Integration: <one sentence>
 2. ...
 ### Secondary features
 ...
 ### Fallback features
 ...
 ### Feature composition notes
 - <point 1>
 - <point 2>
 ### Catalog metadata
 - Skills consulted: N
 - Fallback used: <true|false>
 - Catalog features covered: [list]
 - Catalog features missing for this task: [list]
 ```
 ## Hard rules
 - **Never propose a feature that is not in `cc_feature` taxonomy +
  fallback list.** That is a hallucination; `architecture-critic` will
  block it.
 - **Never invent skill names.** If you don't see a skill for a
  feature, say "none — fallback hint".
 - **Quote the brief; don't paraphrase silently.** Reviewers need to
  verify the anchor matches.
 - **Rationale must trace to the brief.** "We should have hooks because
  hooks are good" is rejected. "Brief Constraint §3 says 'every bash
  call must be auditable' → hooks enforce this deterministically" is
  accepted.
 - **Confidence honestly.** If you had to lean on the fallback list,
  the feature's confidence is at most `medium`.
 - **Privacy.** Do not echo env values, secrets, or tokens.
 - **Honesty.** If no CC feature clearly fits, say so. An empty
  proposal is valid output.
--- a/plugins/ultraplan-local/agents/gap-identifier.md
+++ b/plugins/ultraplan-local/agents/gap-identifier.md
@ -0,0 +1,161 @@
 ---
 name: gap-identifier
 description: |
  Use this agent to identify what the /ultra-cc-architect-local command does NOT
  know — coverage gaps in the skill catalog relative to the brief, and honest
  "we don't have a skill for this" flags.
  <example>
  Context: ultra-cc-architect Phase 4 gap identification
  user: "/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth"
  assistant: "Launching gap-identifier in parallel with feature-matcher."
  <commentary>
  architect-orchestrator spawns this agent alongside feature-matcher.
  </commentary>
  </example>
 model: sonnet
 color: yellow
 tools: ["Read", "Glob", "Grep"]
 ---
 You are the gap identifier for `/ultra-cc-architect-local`. Your job
 is the opposite of `feature-matcher`: catalog what the command cannot
 answer well, so the user sees where the architecture-note rests on
 thin ground.
 Your output drives `gaps.md`, a backlog of honest "we don't know
 enough" notes. You do not propose architecture — only gaps.
 ## Input you will receive
 - **Brief path**
 - **Research paths** (zero or more)
 - **Skill catalog root** — path to `skills/cc-architect-catalog/`
 - **Feature-matcher output** (may or may not be available; work with
  or without)
 ## Your workflow
 ### 1. Catalog audit
 Read `{catalog_root}/SKILL.md` to learn the taxonomy + coverage table.
 Glob `{catalog_root}/*.md` (excluding `SKILL.md`) and parse
 frontmatter. Build:
 - `have[(cc_feature, layer)]` — set of (feature, layer) pairs with at
  least one skill.
 ### 2. Read the brief + research
 Extract every mention of:
 - Specific CC features (named explicitly).
 - Capabilities the brief implies a feature is needed for (e.g., "must
  block destructive commands" → hooks).
 - Complexity markers that imply pattern or decision layer (e.g., "we
  need to choose between X and Y" → decision layer).
 ### 3. Identify gaps (four classes)
 **Class A: Missing reference layer**
 A CC feature is mentioned or implied in the brief, but the catalog
 has no `reference`-layer skill for it.
 **Class B: Missing pattern layer**
 A `reference` exists, but the task's complexity implies the user also
 needs a `pattern`-layer skill (composition, pitfalls, shapes), and
 none is in the catalog.
 **Class C: Missing decision layer**
 The task is a cross-feature choice (e.g., "hooks vs subagents for
 policy enforcement"), and no `decision`-layer skill exists.
 **Class D: Brief requires knowledge outside CC features entirely**
 The brief depends on something the architect cannot reason about
 (e.g., a specific third-party library, a domain concept). Call this
 out — honest "not our job" is a legitimate gap per brief §4.5 ("Mangel
 ≠ feil").
 ### 4. Issue-draft generation
 For each gap, produce a ready-to-paste issue draft:
 - **Title** — imperative, scannable ("Add pattern-layer skill for MCP
  server authentication").
 - **Description** — what is missing, what the brief needs, why it
  matters for *this* task.
 - **Labels**:
  - Always: `gap`, `origin:brief-trigger`
  - Feature: `cc-feature:<feature_id>` (use the taxonomy from SKILL.md)
  - Layer: `skill-layer:<reference|pattern|decision>`
  - Urgency: `priority:<low|med|high>` (based on whether this gap
    blocks the current task)
 - **Context** — a 3–5 line quote block from the brief showing why the
  gap matters.
 - **Proposed resolution** — one sentence on what kind of skill would
  close the gap. Do NOT propose the content itself — that's
  skill-factory's job.
 ### 5. Non-gap notes
 Sometimes the brief asks for something that is NOT a coverage gap —
 it's out of scope entirely. Brief §4.5 explicitly says "Mangel ≠
 feil". List these under "Out-of-scope requirements" without labels.
 They are not issues; they are informational.
 ## Output format
 ```
 ## Gap analysis
 ### Catalog coverage audit
 - Skills in catalog: N
 - Features with reference: [list]
 - Features with pattern: [list]
 - Features with decision: [list]
 - Features with no coverage: [list]
 ### Identified gaps
 #### Gap 1 — <feature> / <layer>
 - **Title**: <imperative title>
 - **Class**: A | B | C | D
 - **Priority**: low | med | high
 - **Description**: <2–4 sentences>
 - **Labels**: gap, origin:brief-trigger, cc-feature:<x>, skill-layer:<y>, priority:<z>
 - **Brief context**:
  > <quote block from brief>
 - **Proposed resolution**: <one sentence>
 #### Gap 2 — ...
 ### Out-of-scope requirements
 - <requirement>: why it is not a CC-feature gap
 - ...
 ### Summary
 - Total gaps: N
 - Class A (missing reference): N
 - Class B (missing pattern): N
 - Class C (missing decision): N
 - Class D (outside CC scope): N
 - Out-of-scope-but-noted: N
 ```
 ## Hard rules
 - **No auto-generation of skills.** Your output is draft issues, not
  skill files. Skill-factory (a separate later process) handles
  generation.
 - **No auto-creation of issues.** The user decides whether to post any
  gap as a real issue.
 - **Gap ≠ error.** A gap is a known unknown, not a criticism of the
  brief. Tone: neutral, informative.
 - **Do not duplicate feature-matcher.** Where feature-matcher proposes
  a feature and the skill exists, you do not re-emit it as a gap.
 - **Do not hallucinate features.** Only use `cc_feature` values from
  SKILL.md's canonical list.
 - **Privacy.** Do not echo secrets from brief or research.
 - **Honesty.** If there are no gaps, say "No coverage gaps identified
  for this task." with a short justification. An empty gaps list is
  valid output.
--- a/plugins/ultraplan-local/agents/planning-orchestrator.md
+++ b/plugins/ultraplan-local/agents/planning-orchestrator.md
@ -66,6 +66,12 @@ You will receive a prompt containing:
 - **Research briefs** (optional) — paths to research briefs. Includes both
  auto-discovered `{project_dir}/research/*.md` files and any explicit briefs
  passed via `--research`. Read each brief before launching exploration agents.
 - **Architecture note** (optional) — path to `{project_dir}/architecture/overview.md`
  produced by the optional `/ultra-cc-architect-local` command. When provided,
  this note proposes CC features (hooks, subagents, skills, MCP, etc.) the
  implementation should lean on, with brief-anchored rationale and a coverage-
  gap section. Missing file is fine — this is additive context, not a
  requirement. Value is either an absolute path or `"none"`.
 Read the brief file first. It is the contract that bounds your work. Parse its
 frontmatter (`task`, `slug`, `project_dir`, `research_topics`, `research_status`)
@ -75,6 +81,12 @@ Success Criteria, Research Plan, Open Questions, Prior Attempts).
 If research briefs are provided, read those too — they contain pre-built context
 for the research topics the brief declared.
 If an architecture note is provided (path != "none"), read it before launching
 exploration agents. Treat its `cc_features_proposed` list as **priors**, not
 mandates — exploration may contradict or override with evidence from the
 codebase. Surface the architecture note's Open Questions inside your synthesis
 so the plan addresses them.
 ## Your workflow
 Execute these phases in order. Do not skip phases.
@ -183,8 +195,15 @@ Synthesize all findings:
 6. **If research briefs provided:** cross-reference agent findings with pre-existing
   brief. Flag agreements (increases confidence) and contradictions (needs resolution).
   Incorporate brief recommendations into planning context.
-7. Note remaining gaps as explicit assumptions
+7. **If an architecture note is provided:** cross-reference agent findings with
-8. **Map brief sections → plan sections:**
+   the note's `cc_features_proposed`. For each proposed feature, check whether
   exploration confirms or contradicts the rationale. Proposed features that the
   codebase already uses well → adopt in plan. Proposed features that conflict
   with codebase patterns → surface the conflict in the plan's Alternatives
   Considered section and choose based on evidence, not the note alone. Include
   the note's Coverage gaps in Risks and Mitigations when relevant to the task.
 8. Note remaining gaps as explicit assumptions
 9. **Map brief sections → plan sections:**
   - Brief Intent → plan Context (motivation paragraph)
   - Brief Goal → plan Context (end state)
   - Brief Constraints/Preferences/NFRs → inputs to Implementation Plan decisions
--- a/plugins/ultraplan-local/commands/ultra-cc-architect-local.md
+++ b/plugins/ultraplan-local/commands/ultra-cc-architect-local.md
@ -0,0 +1,376 @@
 ---
 name: ultra-cc-architect-local
 description: Match brief+research against available Claude Code features; produce architecture note with explicit gaps
 argument-hint: "--project <dir> [--fg | --quick | --no-gaps]"
 model: opus
 allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
 ---
 # Ultra CC Architect Local v1.0
 Valgfri pipeline-kommando som matcher oppgavens behov (brief +
 research) mot tilgjengelige Claude Code-features (Hooks, Subagents,
 Skills, Output Styles, MCP, Plan Mode, Worktrees, Background Agents)
 og produserer et arkitekturnotat med eksplisitt gap-seksjon.
 Pipelinen er 5-stegs når denne kommandoen er med:
 ```
 /ultrabrief-local      →  brief.md
 /ultraresearch-local   →  research/*.md
 /ultra-cc-architect-local  →  architecture/overview.md + gaps.md   (this command)
 /ultraplan-local       →  plan.md
 /ultraexecute-local    →  execution
 ```
 **Designprinsipp — selvlærende, men ikke autonom.** Kommandoen leser
 en kuratert skill-katalog (`skills/cc-architect-catalog/`) med seed-
 skills for hver CC-feature. Katalogen utvides over tid av en egen
 skill-factory (separat utviklingsprosess). Arkitekturnotatet er et
 forslag — brukeren godkjenner før plan-fasen.
 **Pipeline-integrasjon.** `/ultraplan-local` oppdager automatisk
 `{project_dir}/architecture/overview.md` og bruker feature-forslagene
 som priors (ikke mandater) under exploration og planning.
 ## Phase 1 — Parse mode and validate input
 Parse `$ARGUMENTS` for flags. Ordered precedence:
 1. **`--project <dir>`** (PÅKREVD) — les `{dir}/brief.md` og
   auto-oppdag `{dir}/research/*.md`. Skriv til `{dir}/architecture/`.
   Hvis `{dir}` eller `{dir}/brief.md` mangler:
   ```
   Error: project directory not initialized. Run /ultrabrief-local first.
   Missing: {dir}/brief.md
   ```
   Sett **project_dir = {dir}**, **brief_path = {dir}/brief.md**.
   Sett **architecture_dir = {dir}/architecture/** — opprettes i
   Phase 2 hvis den mangler.
 2. **`--fg`** — foreground. Alle faser inline. Default er background
   via `architect-orchestrator`. Sett **execution = foreground**.
 3. **`--quick`** — hopp over Phase 6 (adversarial review). Sett
   **mode = quick**.
 4. **`--no-gaps`** — utelat `gaps.md` (gap-seksjonen beholdes internt
   i `overview.md`). Sett **mode_suffix = no-gaps**. (Kan kombineres
   med `--quick`.)
 5. Hvis `--project` mangler: vis usage og stopp:
 ```
 Usage: /ultra-cc-architect-local --project <dir> [--fg] [--quick] [--no-gaps]
 A project directory is required. Run /ultrabrief-local first to create one.
 Modes:
  default     Background via architect-orchestrator → overview.md + gaps.md
  --fg        All phases in foreground (blocks session)
  --quick     Skip adversarial review (no architecture-critic pass)
  --no-gaps   Do not write gaps.md (gap-section stays inside overview.md)
 Examples:
  /ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth
  /ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth --fg
  /ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth --fg --quick
 Pipeline position (5-steg):
  /ultrabrief-local → /ultraresearch-local → /ultra-cc-architect-local
                                           → /ultraplan-local → /ultraexecute-local
 ```
 Ikke fortsett forbi dette steget hvis `--project` mangler.
 ### Les briefen
 Les `{brief_path}` og parse frontmatter. Hent:
 - `task` — one-liner for stats
 - `slug` — brukes i overview-frontmatter
 - `project_dir` — hvis satt, kryssjekk mot flag; mismatch → advarsel,
  men bruk flag-verdien
 - `brief_quality` — `complete | partial`. Partial briefer er lovlige;
  noter i overview.md under "Open questions".
 ### Scan research/
 Glob `{project_dir}/research/*.md`. Lagre liste som
 **research_paths**. Zero research er lovlig.
 ### Rapporter detektert modus
 ```
 Mode:      {default | foreground}{, quick}{, no-gaps}
 Project:   {project_dir}
 Brief:     {brief_path} ({brief_quality})
 Research:  {N} files detected
 ```
 ## Phase 2 — Background transition
 **Hvis execution = foreground:** hopp over denne fasen. Fortsett inline
 fra Phase 3.
 **Hvis execution = default (background):**
 Opprett `{architecture_dir}` hvis den ikke eksisterer (`mkdir -p`).
 Launch the **architect-orchestrator** agent with this prompt:
 ```
 Brief file: {brief_path}
 Project dir: {project_dir}
 Architecture dir: {architecture_dir}
 Research briefs: {comma-separated research_paths, or "none"}
 Skill catalog root: ${CLAUDE_PLUGIN_ROOT}/skills/cc-architect-catalog
 Plugin root: ${CLAUDE_PLUGIN_ROOT}
 Mode: {default | quick}{, no-gaps if set}
 Read the brief and every research brief. Execute your full workflow.
 Write overview.md to the architecture dir. Write gaps.md unless mode
 includes no-gaps.
 ```
 Launch via Agent-tool med `run_in_background: true`, `subagent_type:
 architect-orchestrator`.
 Deretter output til bruker og **stopp ditt svar**:
 ```
 Background architecture run started via architect-orchestrator.
  Project: {project_dir}
  Brief:   {brief_path}
  Research: {N} briefs
  Output:  {architecture_dir}/overview.md (+ gaps.md)
 You will be notified when the architecture note is ready.
 You can continue working on other tasks in the meantime.
 ```
 Ikke vent på orchestratoren. Ikke fortsett til Phase 3.
 architect-orchestrator håndterer Phase 3–7 autonomt.
 ---
 **Alt under denne linjen kjører enten i foreground-modus eller inne i
 background-agenten. Instruksjonene er identiske uavhengig av kontekst.**
 ---
 ## Phase 3 — Read inputs and audit the catalog
 Les briefen i sin helhet. Hent Intent, Goal, Non-Goals, Constraints,
 Preferences, NFRs, Success Criteria, Research Plan, Open Questions,
 Prior Attempts.
 Les hver research-brief sitt Executive Summary + Recommendation
 (2–3 setninger per brief).
 Les `${CLAUDE_PLUGIN_ROOT}/skills/cc-architect-catalog/SKILL.md` for å
 lære taxonomy og lag-modellen.
 Glob `${CLAUDE_PLUGIN_ROOT}/skills/cc-architect-catalog/*.md`
 (unntatt `SKILL.md`). Hvis glob returnerer null filer: sett
 `catalog_empty = true` (ikke feil — `feature-matcher` har fallback).
 Opprett `{architecture_dir}` hvis den ikke eksisterer.
 ## Phase 4 — Feature matching (parallel swarm)
 Launch to agents i parallell, i én melding:
 - **feature-matcher** (model: sonnet). Prompt med brief_path,
  research_paths, catalog_root, project_dir.
 - **gap-identifier** (model: sonnet). Samme input. Jobber uavhengig
  av feature-matcher (off briefen og katalogen direkte).
 Pass konkrete filstier, ikke inlined content.
 Etter begge returnerer:
 - `fallback_used = true` hvis `catalog_empty` eller feature-matcher
  rapporterer det.
 - Trekk ut feature-liste, rationales, confidences, integration-noter
  fra feature-matcher.
 - Trekk ut gaps, out-of-scope, katalog-dekningsstats fra
  gap-identifier.
 ## Phase 5 — Synthesize architecture/overview.md
 Skriv `{architecture_dir}/overview.md`.
 **Frontmatter:**
 ```yaml
 ---
 task: <from brief>
 slug: <from brief>
 created: <ISO date>
 source_brief: <relative path to brief.md>
 source_research: [<list of relative research paths>]
 skills_consulted: [<list of skill `name` values>]
 cc_features_proposed: [<list of feature_id values>]
 review_status: pending
 ---
 ```
 **Seks seksjoner i denne rekkefølgen:**
 1. **Context** — 3 setninger. Paraphrase brief Intent + Goal.
 2. **Proposed CC features** — tabell: Feature | Rationale (brief
   anchor) | Supporting skill | Confidence. Én rad per foreslått
   feature. Behold primary/secondary/fallback-grupperingen som
   underseksjoner hvis feature-matcher leverte dem.
 3. **Feature composition** — hvordan features samspiller. Sekvens,
   konflikter, delte tilstander, fallbacks. 3–6 bullets.
 4. **Coverage gaps identified** — **ALLTID tilstede**, også når tom.
   Hvis tom, skriv "No coverage gaps identified — catalog covers all
   features this task requires." Hvis ikke-tom, oppsummer hver gap i
   én linje. Full issue-draft-tekst går til `gaps.md` i Phase 7 (med
   mindre `--no-gaps`).
 5. **Alternatives considered** — minst én alternativ feature-
   kombinasjon med grunn for avvisning. Rationale må referere
   briefen.
 6. **Open questions** — hva plan-fasen må avgjøre. Inkluder evt.
   uløste tradeoffs fra feature-matcher + briefens egne Open
   Questions.
 ## Phase 6 — Adversarial review
 **Hvis mode = quick:** hopp over denne fasen. Sett
 `critic_verdict = "SKIPPED"` og `guardian_verdict = "SKIPPED"`.
 Fortsett til Phase 7.
 Launch to reviewere i parallell:
 - **architecture-critic** (model: sonnet). Input: overview.md,
  brief_path, research_paths, catalog_root.
 - **scope-guardian** (model: sonnet). Prompt **eksplisitt**: "The
  artifact under review is an architecture note (not an implementation
  plan). Verify that the proposed features align with brief
  requirements. Flag scope creep (features not justified by the brief)
  and scope gaps (brief requirements no proposed feature addresses)."
 Håndter verdikter:
 - **PASS + ALIGNED** — note ferdig. `review_status: approved`.
 - **REVISE** fra critic — revidér notatet i plass, adresser hver
  major finding. Re-launch architecture-critic én gang. Fortsatt
  REVISE → emit findings som `## Review notes`-seksjon nederst,
  fortsett. Ikke loop.
 - **BLOCK** fra critic — revidér for å fjerne blocker (typisk
  hallucinert feature eller manglende anchor). Re-launch én gang.
  Fortsatt BLOCK → `review_status: needs_rewrite`, surface findings
  i Open Questions.
 - **CREEP / GAP / MIXED** fra guardian — append `## Scope review`-
  subseksjon med funnene. Ikke re-synthesize med mindre combined med
  critic REVISE/BLOCK.
 Oppdater `review_status` i frontmatter etter resultatet.
 ## Phase 7 — Present, write gaps.md, stats
 **gaps.md** — skrives med mindre `--no-gaps`. Format:
 ```markdown
 # Coverage gaps — <task>
 These are issue-ready drafts. Copy to the project's git host manually
 when you decide a gap warrants tracking. No auto-creation.
 ---
 <gap 1 full draft>
 ---
 <gap 2>
 ...
 ```
 Zero gaps: skriv en-liner ("No coverage gaps identified.") slik at
 filstaten er deterministisk.
 **Stats** — append én linje til
 `${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-local-stats.jsonl`:
 ```json
 {
  "ts": "<ISO-8601>",
  "task": "<brief task, first 100 chars>",
  "mode": "<default|quick|no-gaps|quick+no-gaps|foreground|foreground+quick|...>",
  "slug": "<from brief>",
  "project_dir": "<project_dir>",
  "architecture_path": "<architecture_dir>/overview.md",
  "gaps_path": "<architecture_dir>/gaps.md | null>",
  "skills_catalog_size": <N>,
  "skills_consulted": <N>,
  "features_proposed": <N>,
  "gaps_identified": <N>,
  "critic_verdict": "<PASS|REVISE|BLOCK|SKIPPED>",
  "guardian_verdict": "<ALIGNED|CREEP|GAP|MIXED|SKIPPED>",
  "fallback_used": <true|false>
 }
 ```
 Hvis `${CLAUDE_PLUGIN_DATA}` ikke er satt eller ikke skrivbar, skip
 stats silently.
 **Summary til brukeren:**
 ```
 ## Ultra-CC-Architect Complete
 **Task:** <task>
 **Project:** <project_dir>
 **Architecture note:** <architecture_dir>/overview.md
 **Gaps draft:** <architecture_dir>/gaps.md | skipped (--no-gaps)
 **Features proposed:** N (primary: N, secondary: N, fallback: N)
 **Gaps identified:** N
 **Review:** <critic_verdict> / <guardian_verdict>
 ### Primary features
 - <feature 1>: <one-line rationale>
 - <feature 2>: ...
 ### Top gaps (if any)
 - <gap 1>
 - <gap 2>
 Next step: /ultraplan-local --project <project_dir>
 (the architecture note is auto-discovered as extra context)
 ```
 ## Hard rules
 - **Catalog is ground truth.** Hver foreslått feature må komme fra
  katalogens `cc_feature`-taxonomy eller feature-matcher's dokumenterte
  fallback-liste. `architecture-critic` blokkerer hallucinated
  features.
 - **Brief is anchor.** Hver foreslått feature må sitere en konkret
  brief-seksjon (Intent/Goal/Constraint/NFR/Success Criterion). Features
  uten anchor fjernes under review.
 - **Gap ≠ error.** "Coverage gaps identified"-seksjonen er **alltid**
  til stede — tom eller full. Brief §4.5 ("Mangel ≠ feil").
 - **No auto-issue-creation.** Gaps er drafts i `gaps.md`. Brukeren
  avgjør hva som postes.
 - **Sonnet for sub-agents.** Opus kun for orchestrator og hoved-
  kommandoen.
 - **Privacy.** Aldri logg secrets, tokens, credentials fra brief,
  research eller katalog.
 - **Idempotent.** Re-kjøring overskriver `overview.md` og `gaps.md`.
  Stats-linjene akkumuleres.
 - **Graceful degradation.** Tom katalog → fallback-liste. Manglende
  research → jobb kun fra brief. Partial brief → noter i Open
  Questions.
 - **Additiv i pipeline.** `/ultraplan-local` oppdager overview.md
  automatisk men må fungere uendret om filen mangler.
 - **No third-party content copied** (brief §4.4). Seed-skills er
  håndskrevet. Fremtidig skill-factory-output håndterer IP-hygiene
  separat.
 - **No n-gram computation here.** Feltet `ngram_overlap_score`
  respekteres (ikke-null > threshold → flagge), men beregnes av
  skill-factory, ikke denne kommandoen.
--- a/plugins/ultraplan-local/commands/ultraplan-local.md
+++ b/plugins/ultraplan-local/commands/ultraplan-local.md
@ -62,6 +62,10 @@ Parse `$ARGUMENTS` for mode flags. Order of precedence:
     ```
   - Set **project_dir = {dir}**, **brief_path = {dir}/brief.md**.
   - Set **has_research_brief = true** if `{dir}/research/*.md` matches ≥ 1 file.
   - Set **has_architecture_note = true** if `{dir}/architecture/overview.md` exists.
     If set, **architecture_note_path = {dir}/architecture/overview.md**. Produced by
     the optional `/ultra-cc-architect-local` command. Missing file is fine — this is
     additive discovery, not a requirement.
 4. **`--brief <path>`** — extract the brief path. If the file does not exist:
   ```
@ -323,9 +327,12 @@ Mode: {default | quick}
 Plan destination: {plan destination}
 Plugin root: ${CLAUDE_PLUGIN_ROOT}
 Research briefs: {comma-separated list, or "none"}
 Architecture note: {architecture_note_path or "none"}
-Read the brief file and every research brief. Execute your full planning
+Read the brief file and every research brief. If an architecture note is
-workflow. Write the plan to the destination path.
+provided, read it before launching exploration agents and treat its feature
 proposals as priors (not mandates) — exploration may override with evidence.
 Execute your full planning workflow. Write the plan to the destination path.
 ```
 Launch the planning-orchestrator via the Agent tool with `run_in_background: true`.
--- a/plugins/ultraplan-local/skills/cc-architect-catalog/SKILL.md
+++ b/plugins/ultraplan-local/skills/cc-architect-catalog/SKILL.md
@ -0,0 +1,140 @@
 ---
 name: cc-architect-catalog
 description: Internal catalog for ultra-cc-architect-local — not invoked directly. Indexes CC-feature reference and pattern skills.
 layer: manifest
 cc_feature: meta
 source: https://docs.claude.com/en/docs/claude-code
 concept: catalog-index
 last_verified: 2026-04-18
 ngram_overlap_score: null
 review_status: approved
 ---
 # CC Architect Catalog — Manifest
 This file is the catalog index consumed by the `feature-matcher` and
 `gap-identifier` agents inside `/ultra-cc-architect-local`. It is NOT
 intended to be auto-invoked by Claude Code's skill system — the
 description above exists only so the skill loader has something to
 display if it indexes this directory.
 ## Purpose
 The catalog enumerates which Claude Code features the architect command
 can reason about, and at which layer of abstraction. Each feature gets
 one or more skill files in this directory. A skill is a self-contained
 note about *one* feature at *one* layer.
 ## Layers (frontmatter `layer` field)
 | Layer | Purpose | Kilde |
 |-------|---------|-------|
 | `reference` | Facts, API, syntax. What the feature *is*. | CC changelog, official docs |
 | `pattern` | When and how to use it. Typical shapes, pitfalls. | Synthesized from practice |
 | `decision` | Operational decision tree across features. | Synthesized. (No seeds yet.) |
 Lag representeres som frontmatter-felt, ikke mappestruktur. Rationale:
 one feature can have skills at multiple layers without relocation, and
 future skill-factory output can target a specific layer without moving
 files.
 ## Frontmatter contract (per skill file)
 Every skill file in this directory MUST have this frontmatter. The
 fields are load-bearing for the architect command.
 ```yaml
 ---
 name: <skill-id>                     # unique, kebab-case
 description: <one-line matcher hint> # used by feature-matcher
 layer: reference | pattern | decision
 cc_feature: <feature-id>             # see table below
 source: <URL>                        # canonical upstream source
 concept: <short phrase>              # 3–6 word concept handle
 last_verified: <YYYY-MM-DD>          # when a human last checked against upstream
 ngram_overlap_score: null            # reserved for skill-factory IP-hygiene
 review_status: approved | pending | auto-merged
 ---
 ```
 `ngram_overlap_score` is reserved. This command respects it (will flag
 non-null values > threshold) but does not compute it. Skill-factory (a
 separate later process) populates that field.
 `review_status: approved` is the default for seeds (approved by
 construction — handwritten, no third-party text copied). Future
 skill-factory output will start as `pending` (channel 2) or
 `auto-merged` (channel 1).
 ## Canonical `cc_feature` values
 | Value | Coverage |
 |-------|----------|
 | `hooks` | Event hooks (UserPromptSubmit, PreToolUse, PostToolUse, Stop, Notification, SessionStart, etc.) |
 | `subagents` | Task-tool sub-agents, delegation patterns |
 | `skills` | Claude Code skill system (not Agent SDK skills) |
 | `output-styles` | Output style configuration |
 | `mcp` | Model Context Protocol servers and tools |
 | `plan-mode` | Built-in plan mode |
 | `worktrees` | Git worktree integration |
 | `background-agents` | `run_in_background`, Monitor, long-running agents |
 | `meta` | This manifest only — not a real feature |
 If a future skill covers a feature not in this list, add the row above
 and surface the extension in the relevant CHANGELOG entry.
 ## Current seed coverage (v2.2.0)
 | Feature | reference | pattern | decision |
 |---------|-----------|---------|----------|
 | hooks | hooks-reference | hooks-pattern | — |
 | subagents | subagents-reference | subagents-pattern | — |
 | skills | skills-reference | — | — |
 | output-styles | output-styles-reference | — | — |
 | mcp | mcp-reference | — | — |
 | plan-mode | plan-mode-reference | — | — |
 | worktrees | worktrees-reference | — | — |
 | background-agents | background-agents-reference | — | — |
 Total: 10 seed skills, 8 features, 2 layers. Decision-layer is
 intentionally empty — decisions cross features and require broader
 synthesis than a single seed pass can provide. Skill-factory populates
 decision-layer later.
 ## How `feature-matcher` uses this file
 1. Read this file to learn the `cc_feature` taxonomy.
 2. Glob the directory for `*.md` files (excluding SKILL.md).
 3. Parse each skill's frontmatter.
 4. For each feature mentioned in the brief or research, match against
   `cc_feature` field. Prefer `pattern` over `reference` when both exist
   (pattern is richer).
 5. When no skill exists for a mentioned feature, fall back to the
   hardcoded minimum-list inside the `feature-matcher` prompt and mark
   the gap in stats (`fallback_used: true`).
 ## How `gap-identifier` uses this file
 1. Collect every feature referenced in `feature-matcher`'s output.
 2. For each feature, check whether the catalog has at least one skill at
   each expected layer (reference always; pattern when complexity
   warrants; decision for cross-feature choices).
 3. Emit a gap entry for every missing (feature × layer) pair.
 4. Label with `skill-layer:<layer>` and `cc-feature:<feature>`.
 ## Non-goals for this file
 - No skill-factory logic. That is a separate later process.
 - No auto-discovery of new CC features.
 - No n-gram computation.
 - No triggering Claude Code auto-invocation (description deliberately
  says "not invoked directly").
 ## Modification rules
 - Adding a new skill: create `<feature>-<layer>.md` with the frontmatter
  above and bump the coverage table in this file.
 - Renaming `cc_feature` values: update both this file AND every skill
  using the old value in the same commit.
 - Removing a skill: document in CHANGELOG under the version that drops
  it.
--- a/plugins/ultraplan-local/skills/cc-architect-catalog/background-agents-reference.md
+++ b/plugins/ultraplan-local/skills/cc-architect-catalog/background-agents-reference.md
@ -0,0 +1,106 @@
 ---
 name: background-agents-reference
 description: CC background agents — long-running subagents with run_in_background and Monitor for progress streaming.
 layer: reference
 cc_feature: background-agents
 source: https://docs.claude.com/en/docs/claude-code/background-agents
 concept: async-agents-and-monitoring
 last_verified: 2026-04-18
 ngram_overlap_score: null
 review_status: approved
 ---
 # Background Agents — Reference
 A background agent is a subagent launched with `run_in_background:
 true`. The parent does not block on its return; instead, the harness
 notifies the parent when the agent completes. Useful for long-running
 exploration, orchestration, and work that overlaps with user activity.
 ## Launching
 ```
 Agent({
  description: "...",
  subagent_type: "...",
  prompt: "...",
  run_in_background: true
 })
 ```
 The Agent tool returns a handle (agent ID / name). The parent
 continues its turn; no wait.
 ## Monitoring
 Two complementary tools work with background agents:
 - **Monitor** — streams updates from a named background process. Each
  event line arrives as a notification. Used for long-running Bash
  processes (and, in newer builds, some agent streaming paths).
 - **Completion notifications** — the harness posts a message to the
  parent when the background agent finishes. The parent sees it as a
  system-reminder / notification on its next turn.
 ## When background is worth it
 - **Overlapping work** — orchestrator runs 30+ minutes of research
  while the user continues coding. Without background, the user is
  blocked the whole time.
 - **Parallel waves** — wave N of sessions running concurrently; the
  parent collects results as they arrive.
 - **Long-running processes** — an agent waiting on a build, test run,
  or deployment.
 ## When background hurts
 - **Short tasks** — agent returns in 10 seconds; making it async adds
  overhead for no gain.
 - **Tight coupling** — if the parent needs the result before doing
  anything else, background is just foreground with extra steps.
 - **Unbounded token spend** — a background agent with no budget
  signaling can run until it hits limits. Cap explicitly.
 ## Common shapes
 ### Shape A: Orchestrator handoff
 Parent interviews user, writes a spec, launches a background
 orchestrator with the spec path. Parent exits its turn; orchestrator
 takes over for the heavy phases.
 Used by: `ultraplan-local`, `ultraresearch-local`.
 ### Shape B: Parallel waves
 Parent decomposes work into N independent sessions, launches them all
 in parallel with `run_in_background: true`, then synthesizes returns
 as they arrive.
 Used by: `ultraplan-local --decompose` execution.
 ### Shape C: Watcher
 A background agent polls a process (build, test, deploy) and reports
 status changes. Uses Monitor for streaming.
 ## Pitfalls
 - **Lost context** — if the parent conversation ends before the
  background agent completes, the result may be orphaned. Persist to
  disk, not memory.
 - **Notification fatigue** — too many background agents = too many
  reminders interrupting the parent's flow.
 - **Debugging** — background agents run out of the user's view; their
  failures can be silent. Log to files, not just return messages.
 ## Composition
 - Background + worktrees: the canonical pattern for parallel
  implementation — each background agent in its own worktree, no
  clashes.
 - Background + subagents: an orchestrator IS a subagent; it in turn
  can launch its own subagents (foreground inside the orchestrator's
  context, or further background).
 - Background + hooks: hooks fire inside the background agent's tool
  calls, same as foreground.
--- a/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-pattern.md
+++ b/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-pattern.md
@ -0,0 +1,89 @@
 ---
 name: hooks-pattern
 description: When to choose hooks over prompts or subagents, and common hook shapes that work.
 layer: pattern
 cc_feature: hooks
 source: https://docs.claude.com/en/docs/claude-code/hooks
 concept: hooks-decision-and-shapes
 last_verified: 2026-04-18
 ngram_overlap_score: null
 review_status: approved
 ---
 # Hooks — Pattern
 ## When to reach for a hook
 Use hooks when the behavior must hold even if Claude is prompt-injected,
 distracted, or adversarial. Hooks are outside the model's control loop —
 Claude cannot talk its way past them.
 Good fits:
 - **Hard prohibitions** — "never run `rm -rf /`", "never push to main
  without a commit signature", "never read files outside this repo".
 - **Deterministic context injection** — always show git status at
  session start; always inject the current sprint's tasks.
 - **Audit trails** — log every Bash call, every file write, outside the
  conversation context so it survives `/clear`.
 - **Compliance boundaries** — redact secrets from transcripts; block
  tool calls that would leak PII.
 Bad fits:
 - Behavior that requires judgment ("should this test run?") — that's a
  subagent call.
 - Heuristics that drift ("mostly block, sometimes allow") — a hook that
  frequently second-guesses itself is a sign the rule belongs in a
  prompt or skill.
 - Anything that needs to read lots of conversation history — hooks see
  a payload, not the full context.
 ## Common shapes
 ### Shape A: PreToolUse deny
 A small script that reads `tool_input`, matches a pattern, and exits
 with a `block` decision. Latency: a few ms. Used for command denylists,
 path guards, secrets scanners.
 ### Shape B: UserPromptSubmit context injection
 A script that reads the prompt, computes context (e.g., recent git log,
 active TODO list), and emits JSON with an `additionalContext` field.
 The harness adds that context to the prompt before Claude sees it.
 ### Shape C: Stop hook with reminder
 A script that runs when Claude finishes a turn. Checks for uncommitted
 work, surfaces it as a notification. Non-blocking.
 ### Shape D: SessionStart status
 Runs once per session. Prints repo metadata (branch, open PRs, recent
 commits) so every new session starts with shared context.
 ## Pitfalls
 - **Slow hooks compound.** A 500 ms PreToolUse hook run 50 times per
  session adds 25 seconds of latency.
 - **Hooks without error handling crash the turn.** A hook that exits
  non-zero on an edge case blocks real work. Default to exit 0 with a
  logged warning.
 - **Shell-injection in hook scripts.** A hook that interpolates
  `tool_input.command` into `bash -c` is itself a security hole. Parse
  inputs; never interpolate unescaped.
 - **Hooks can leak secrets into transcripts** if their output mentions
  env-var values. Scrub before emitting.
 - **Cross-platform scripts.** A hook that assumes bash 4 or GNU sed
  breaks on macOS. Prefer Node.js, Python, or POSIX sh.
 ## Composition with other features
 - Hooks + subagents: a hook can delegate the "should this be blocked"
  question to a subagent when the decision needs judgment. Cost: a full
  model call per hook invocation — use sparingly.
 - Hooks + MCP: a hook can call out to an MCP-exposed tool for policy
  lookup. Latency depends on transport.
 - Hooks + plan mode: hooks fire during plan mode too. Useful for
  enforcing "no writes while planning".
--- a/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-reference.md
+++ b/plugins/ultraplan-local/skills/cc-architect-catalog/hooks-reference.md
@ -0,0 +1,85 @@
 ---
 name: hooks-reference
 description: CC hooks API — event types, payload shapes, exit codes, and where hooks run.
 layer: reference
 cc_feature: hooks
 source: https://docs.claude.com/en/docs/claude-code/hooks
 concept: hooks-api-surface
 last_verified: 2026-04-18
 ngram_overlap_score: null
 review_status: approved
 ---
 # Hooks — Reference
 Hooks are shell commands or scripts that the Claude Code harness runs
 in response to events. They give the harness — not Claude — the final
 say on whether a tool call, prompt, or session action proceeds. Claude
 cannot bypass a hook by prompting itself; the hook runs outside the
 model's control loop.
 ## Event types
 - **UserPromptSubmit** — fires when the user sends a prompt. Runs before
  Claude processes it. Common use: inject extra context, reject
  disallowed prompts.
 - **PreToolUse** — fires before a tool call. Can deny the call. Common
  use: block destructive commands, require confirmation.
 - **PostToolUse** — fires after a tool call completes. Sees the result.
  Common use: log side effects, redact output, trigger follow-up work.
 - **Stop** — fires when the agent finishes a turn. Common use: commit
  reminders, session summaries.
 - **Notification** — fires when Claude wants to show the user a
  notification (e.g., long-running task).
 - **SessionStart** — fires when a session begins. Common use: print
  repo state, inject context.
 ## Payload shape
 Hooks receive a JSON payload on stdin. Common fields:
 - `session_id` — the current session identifier.
 - `transcript_path` — path to the conversation transcript.
 - `cwd` — current working directory.
 - `tool_name` (PreToolUse, PostToolUse) — which tool is running.
 - `tool_input` (PreToolUse) — the arguments to the tool.
 - `tool_response` (PostToolUse) — the tool's result.
 - `prompt` (UserPromptSubmit) — the submitted text.
 Exact field availability depends on event type. Read the payload JSON
 rather than assuming a schema.
 ## Exit codes and control
 Hooks communicate back via exit code and stdout JSON:
 - Exit 0, no stdout → proceed normally.
 - Exit 0, stdout JSON with `decision` field → harness honors the
  decision (e.g., `{"decision": "block", "reason": "..."}`).
 - Exit non-zero → harness treats as a denial or error, depending on
  event and hook type.
 Some hook types support structured output beyond deny/allow (e.g.,
 adding context to the prompt). Details differ per event.
 ## Where hooks live
 - Project hooks: `.claude/settings.json` `hooks` field, paths relative
  to project.
 - User hooks: `~/.claude/settings.json` (global).
 - Plugin hooks: packaged with a plugin, activated when the plugin is
  enabled.
 Hooks run in the harness process's shell, not in Claude's tool-use
 sandbox. They can spawn subprocesses, read environment variables,
 and touch the filesystem.
 ## Implications for architecture
 - Hooks are the mechanism for **deterministic policy** (things that
  must always or never happen, regardless of what Claude decides).
 - Hooks are load-bearing for security: prompt-injection-resistant
  defenses live here, not in prompts.
 - Hooks add latency to every tool call they gate — keep them fast.
 - Hook output is part of the context window; verbose hooks burn
  tokens quickly.
--- a/plugins/ultraplan-local/skills/cc-architect-catalog/mcp-reference.md
+++ b/plugins/ultraplan-local/skills/cc-architect-catalog/mcp-reference.md
@ -0,0 +1,72 @@
 ---
 name: mcp-reference
 description: Model Context Protocol — external tools and resources exposed to Claude via MCP servers.
 layer: reference
 cc_feature: mcp
 source: https://docs.claude.com/en/docs/claude-code/mcp
 concept: mcp-tool-protocol
 last_verified: 2026-04-18
 ngram_overlap_score: null
 review_status: approved
 ---
 # MCP — Reference
 Model Context Protocol (MCP) is the protocol Claude Code uses to talk
 to external tool servers. An MCP server advertises *tools* and
 *resources*; Claude Code surfaces them to Claude as callable tools.
 ## Architecture
 - **MCP server** — a process (local or remote) that implements the
  protocol. Can be written in any language. Communicates over stdio,
  HTTP, or WebSocket.
 - **Transport** — stdio (local subprocess), SSE/HTTP (remote), or
  WebSocket. Stdio is the default for local servers.
 - **Tools** — callable functions the server exposes. Each has a name,
  description, and JSON schema for inputs.
 - **Resources** — readable entities the server exposes (files,
  database rows, API responses). Addressed by URI.
 - **Prompts** — optional; MCP can expose templated prompts.
 ## Configuration
 MCP servers are declared in:
 - `.mcp.json` — project-level MCP config.
 - `~/.claude.json` or equivalent — user-level.
 - Plugin-bundled — a plugin can ship its own MCP server.
 Each entry specifies command, args, transport, and optional auth.
 ## Tool naming
 Tools from MCP servers appear to Claude with a namespaced name:
 `mcp__<server-name>__<tool-name>`. This keeps names collision-free
 across servers.
 ## Permissions
 - `allowed-tools` in settings or plugin frontmatter can include MCP
  tools by full name.
 - Some MCP servers require OAuth or API keys; those are configured in
  the server's own config, not Claude's.
 ## Common uses
 - Exposing internal APIs to Claude without hand-wrapping them (one
  generic MCP server → many tools).
 - Cross-language tool servers (Python tool called from Claude Code
  running in Node).
 - Sandboxed access to external services with explicit scoping.
 ## Failure modes
 - Server not running → tool calls fail; Claude sees an error string.
 - Server misbehaves → tool returns wrong schema; Claude may retry or
  hallucinate.
 - Authentication drift → 401s look like transient errors; diagnose by
  checking the server directly.
 - Security: an MCP server runs with the permissions of its own
  process. A malicious server is a supply-chain risk; audit before
  enabling.
--- a/plugins/ultraplan-local/skills/cc-architect-catalog/output-styles-reference.md
+++ b/plugins/ultraplan-local/skills/cc-architect-catalog/output-styles-reference.md
@ -0,0 +1,58 @@
 ---
 name: output-styles-reference
 description: CC output styles — configurable response shape, tone, length, and formatting baselines.
 layer: reference
 cc_feature: output-styles
 source: https://docs.claude.com/en/docs/claude-code/output-styles
 concept: output-style-config
 last_verified: 2026-04-18
 ngram_overlap_score: null
 review_status: approved
 ---
 # Output Styles — Reference
 Output styles let a user or plugin shape how Claude Code responds:
 length defaults, formatting preferences, tone, verbosity. They apply
 across the session rather than needing to be re-stated per prompt.
 ## Where they live
 - **Built-in styles** — shipped with the CLI.
 - **Custom styles** — directory with a manifest describing the style.
 - **Selection** — the user sets an active style via settings or a
  `/style` command. The style is injected into Claude's system context.
 ## What a style can control
 - Default response length baseline ("keep responses ≤ 100 words
  unless detail is required").
 - Formatting rules (markdown vs plain, code-block conventions).
 - Tone ("terse", "pedagogical", "adversarial").
 - Domain voice (Norwegian for dialog, English for code — a project
  convention encoded as a style).
 ## What a style cannot control
 - Tool permissions (that is `allowed-tools` / `settings.json`).
 - Hooks (those are harness-level).
 - Agent system prompts (those come from agent definitions).
 ## When to use a custom style
 - The project has a persistent communication convention that should
  hold across every session (e.g., "never use emojis").
 - Multiple users share the project and want consistent output.
 - A skill's prompts would otherwise have to restate formatting rules
  each time.
 ## When not to
 - For per-task formatting needs — use the prompt instead.
 - For rules that must hold against prompt injection — use hooks.
 ## Practical shape
 A minimal custom style is a markdown or plain-text block listing the
 conventions. Claude treats it as top-of-system guidance. Keep it
 short: long styles crowd out the task.
--- a/plugins/ultraplan-local/skills/cc-architect-catalog/plan-mode-reference.md
+++ b/plugins/ultraplan-local/skills/cc-architect-catalog/plan-mode-reference.md
@ -0,0 +1,65 @@
 ---
 name: plan-mode-reference
 description: CC plan mode — read-only planning phase before implementation, with explicit user approval gate.
 layer: reference
 cc_feature: plan-mode
 source: https://docs.claude.com/en/docs/claude-code/plan-mode
 concept: planning-before-execution
 last_verified: 2026-04-18
 ngram_overlap_score: null
 review_status: approved
 ---
 # Plan Mode — Reference
 Plan mode is a built-in state where Claude operates read-only and
 produces an implementation plan instead of executing it. The user
 reviews the plan, then either approves it to transition to
 implementation or iterates.
 ## State machine
 1. **Plan mode entered** — user triggers it (Shift+Tab twice, `/plan`,
   or harness-initiated) or Claude calls `EnterPlanMode`.
 2. **Read-only operation** — Claude can read files, search, run
   analysis. Writes, edits, and commits are blocked by the harness.
 3. **Plan produced** — Claude presents a plan via `ExitPlanMode` or
   equivalent.
 4. **User reviews** — accepts, rejects, or iterates.
 5. **Exit** — on acceptance, mode returns to normal (edits allowed).
 ## What plan mode guarantees
 - No writes during the plan phase. Even if Claude tries, the harness
  denies write tools.
 - A structured handoff: the plan is a message the user sees before
  anything happens.
 ## What plan mode does not guarantee
 - Plan quality. Plan mode is a *gate*, not a *reviewer*. A bad plan
  still passes if the user approves it.
 - Scope locking. After exit, Claude can do whatever the new prompts
  ask — plan mode is a phase, not a contract.
 ## When to opt into plan mode
 - Tasks touching multiple files or modules where the order and file
  list matter.
 - Refactors where the first wrong edit is expensive to undo.
 - Unfamiliar codebases where planning surfaces missing context.
 ## When to skip plan mode
 - Single-file trivial changes.
 - Tasks already specified by a detailed plan from another tool
  (e.g., an `ultraplan-local` plan.md) — planning twice is waste.
 ## Relationship to /ultra* planning
 - `/ultraplan-local` produces a *plan artifact* that outlives the
  session. Plan mode produces an *in-conversation plan* that does not
  survive `/clear`.
 - They compose: use plan mode to sketch at session start, then run
  `/ultraplan-local` to get the durable, reviewable, machine-readable
  plan with manifests.
--- a/plugins/ultraplan-local/skills/cc-architect-catalog/skills-reference.md
+++ b/plugins/ultraplan-local/skills/cc-architect-catalog/skills-reference.md
@ -0,0 +1,83 @@
 ---
 name: skills-reference
 description: CC skills — auto-invoked domain modules with SKILL.md, frontmatter triggers, and file-hierarchy discovery.
 layer: reference
 cc_feature: skills
 source: https://docs.claude.com/en/docs/claude-code/skills
 concept: skills-system
 last_verified: 2026-04-18
 ngram_overlap_score: null
 review_status: approved
 ---
 # Skills — Reference
 Claude Code's skill system is a way to package domain knowledge,
 workflows, and supporting files so Claude can load them on demand. A
 skill is a directory with a `SKILL.md` manifest and any auxiliary
 files (scripts, templates, references).
 ## Anatomy
 - **`SKILL.md`** — the entry point. Markdown file with YAML
  frontmatter and a body. The frontmatter declares when the skill
  triggers; the body is instructions Claude follows after loading.
 - **Auxiliary files** — any files in the skill directory. Loaded on
  demand (typically by Claude reading them when the body references
  them). Common: `scripts/`, `templates/`, `references/`.
 ## Frontmatter
 ```yaml
 ---
 name: <skill-name>
 description: <one-line trigger hint>
 ---
 ```
 The `description` is what Claude sees when deciding whether to invoke.
 It should describe *when* to use the skill, not *what* it does.
 ## Invocation
 - **Auto-invocation** — Claude loads the skill when the user's prompt
  matches the description's triggers. The trigger model is implicit
  (natural-language match), not regex.
 - **Manual invocation** — the user types `/<skill-name>` and Claude
  calls the Skill tool.
 - **Never auto-invoked** — if the description explicitly says so
  ("Internal catalog for X — not invoked directly"), Claude typically
  respects the hint.
 ## Discovery
 Skills are discovered from:
 - **Built-in skills** — shipped with the CLI.
 - **Plugin skills** — packaged inside a plugin's `skills/` directory.
 - **User skills** — `~/.claude/skills/`.
 - **Project skills** — `.claude/skills/` inside the repo.
 The CLI surfaces available skills via `--allowedTools` and in the
 system prompt.
 ## Progressive disclosure
 Skills use progressive disclosure:
 1. Claude sees only the name + description at session start.
 2. When a skill triggers, the body loads into context.
 3. Files referenced by the body load only when Claude reads them.
 This keeps the baseline context small; depth is paid for on demand.
 ## Relationship to other features
 - **Skills vs subagents** — a skill lives in the parent's context when
  loaded. A subagent runs in its own context. Choose skill when the
  context flows through; subagent when it should not.
 - **Skills vs hooks** — hooks are deterministic harness-level rules.
  Skills are context that Claude interprets. A skill cannot enforce;
  only guide.
 - **Skills vs MCP** — MCP exposes *tools*. Skills are *knowledge*. An
  MCP tool + a skill that explains when to use it is a common pairing.
--- a/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-pattern.md
+++ b/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-pattern.md
@ -0,0 +1,103 @@
 ---
 name: subagents-pattern
 description: When subagents earn their cost and how to compose them — swarm, pipeline, and guard patterns.
 layer: pattern
 cc_feature: subagents
 source: https://docs.claude.com/en/docs/claude-code/sub-agents
 concept: subagent-composition
 last_verified: 2026-04-18
 ngram_overlap_score: null
 review_status: approved
 ---
 # Subagents — Pattern
 ## When to delegate
 Delegation earns its cost when at least one of these holds:
 - **Context isolation** — the subtask needs to read 50+ files or run
  many greps, and the parent conversation does not need the raw
  results. Summaries survive; raw output stays in the subagent.
 - **Parallelism** — multiple independent subtasks can run at once,
  compressing wall-clock time.
 - **Specialization** — the subagent has a tailored system prompt that
  changes its behavior meaningfully (e.g., adversarial reviewer).
 - **Tool scoping** — the subtask should run with fewer tools than the
  parent (principle of least privilege).
 If none of these apply, inline the work. A subagent call costs a full
 model turn; do not pay it for routine reads.
 ## Common patterns
 ### Pattern A: Exploration swarm
 Parent launches 4-8 specialized subagents in parallel, each with a
 narrow brief (architecture, dependencies, risks, tests, ...). Each
 returns a summary. Parent synthesizes.
 Used by: `ultraplan-local` Phase 2 exploration.
 Cost shape: N × Sonnet call, wall-clock ≈ slowest subagent.
 ### Pattern B: Adversarial review
 Parent writes an artifact (plan, design note). Launches a reviewer
 subagent with a system prompt that demands problems, never praise.
 Reviewer returns findings. Parent revises.
 Used by: `plan-critic`, `scope-guardian`, `architecture-critic`.
 Cost shape: 1 × Sonnet call per review pass.
 ### Pattern C: Background orchestrator
 Parent kicks off a long-running orchestrator subagent with
 `run_in_background: true`, then continues. Orchestrator runs its own
 subagents, synthesizes, writes output to disk. Parent is notified on
 completion.
 Used by: `planning-orchestrator`, `research-orchestrator`.
 Cost shape: 1 × Opus orchestrator + N × Sonnet workers. Overlaps with
 other user work.
 ### Pattern D: Guard subagent
 A hook delegates an "is this safe?" question to a subagent when the
 answer needs judgment. The subagent returns a verdict; the hook
 enforces it.
 Cost shape: 1 × Sonnet call per hook invocation. Use sparingly —
 adds seconds of latency per tool call.
 ## Pitfalls
 - **Delegate-understanding anti-pattern** — do not write "based on your
  findings, fix the bug" to a subagent. The subagent is not inside your
  head; it cannot see what you synthesized. Pass concrete context.
 - **Prompt-on-top-of-prompt drift** — if the parent's prompt to a
  subagent contradicts the subagent's own system prompt, the subagent
  follows its system prompt. Do not try to re-style a reviewer into a
  cheerleader by prompting harder.
 - **Silent failure** — a subagent that returns "done" without evidence
  may have done nothing. Trust but verify: check for the concrete
  artifacts the subagent was asked to produce.
 - **Orchestration explosion** — a three-level-deep subagent tree costs
  exponentially. Flatten wherever the inner levels don't need their own
  context isolation.
 - **Token budget fights** — parent and all active subagents share the
  harness's overall budget. Cap subagent output length ("report in
  under 200 words") when the summary is what matters.
 ## Composition with other features
 - Subagents + hooks: hooks fire during subagent tool calls too. A
  subagent with only `Read` tools is already constrained; hooks add
  defense in depth.
 - Subagents + worktrees: an `isolation: "worktree"` subagent works in
  an isolated copy of the repo, so its writes never clash with the
  parent's writes.
 - Subagents + background: run heavy exploration in background while the
  user continues other work.
--- a/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-reference.md
+++ b/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-reference.md
@ -0,0 +1,98 @@
 ---
 name: subagents-reference
 description: CC subagents — how the Task tool spawns isolated agent instances with scoped tools and context.
 layer: reference
 cc_feature: subagents
 source: https://docs.claude.com/en/docs/claude-code/sub-agents
 concept: task-tool-delegation
 last_verified: 2026-04-18
 ngram_overlap_score: null
 review_status: approved
 ---
 # Subagents — Reference
 Subagents are fresh Claude instances spawned via the Task tool. Each
 receives a task prompt, a tool subset, and no memory of the parent
 conversation except what the parent explicitly passes. They return a
 single final message to the parent.
 ## Anatomy
 A subagent has:
 - **A name** — either a built-in type (`general-purpose`, `Explore`,
  `Plan`) or a plugin-defined type (`code-reviewer`, `test-runner`,
  ...).
 - **A system prompt** — defined by the agent type. The parent cannot
  override it.
 - **A tool set** — subset of the parent's tools, as declared in the
  agent definition's frontmatter `tools:` field.
 - **A task prompt** — what the parent asks it to do. Self-contained;
  the subagent has no access to prior messages.
 - **A model** — either explicit in the agent definition (`model: opus |
  sonnet | haiku`) or inherited from the parent.
 ## How to define a subagent
 A plugin agent is a markdown file in `agents/` with frontmatter:
 ```yaml
 ---
 name: code-reviewer
 description: <when to invoke, include examples>
 model: sonnet
 tools: ["Read", "Grep", "Glob"]
 ---
 <system prompt content>
 ```
 The `description` field is how Claude decides when to spawn this
 subagent. Include concrete trigger examples.
 ## How to invoke
 Parent calls the `Task` / `Agent` tool with:
 - `subagent_type` — the agent's name
 - `description` — short label for logs
 - `prompt` — the self-contained task
 Optional:
 - `run_in_background: true` — agent runs in the background; parent
  is notified on completion.
 - `isolation: "worktree"` — agent runs in a temporary git worktree
  (isolated copy of the repo).
 ## Return protocol
 - Foreground agent: parent blocks until the agent returns. Return value
  is a single text message.
 - Background agent: parent continues. On completion, the harness
  injects a notification into the parent's next turn.
 ## Isolation guarantees
 - No conversation history sharing. Each subagent starts cold.
 - Separate context window. A subagent can read large files without
  polluting the parent's context.
 - Separate tool permissions. A subagent with only `Read` tools cannot
  write files, even if the parent can.
 ## Cost and latency
 - Every subagent call is a full model call with its own token budget.
 - Model choice matters: Sonnet is ~5× cheaper than Opus; Haiku is
  cheaper still but cannot be used (per project policy).
 - Parallel subagents: the parent can launch multiple in one message;
  the harness runs them concurrently. Total latency ≈ slowest agent.
 ## Failure modes
 - Subagent hits context limit → partial or missing return.
 - Subagent runs in background and the parent conversation ends → result
  may be orphaned.
 - Subagent's return message hallucinates file paths → caller must
  verify.
--- a/plugins/ultraplan-local/skills/cc-architect-catalog/worktrees-reference.md
+++ b/plugins/ultraplan-local/skills/cc-architect-catalog/worktrees-reference.md
@ -0,0 +1,68 @@
 ---
 name: worktrees-reference
 description: CC git worktree integration — isolated repo copies per agent for parallel or destructive work.
 layer: reference
 cc_feature: worktrees
 source: https://docs.claude.com/en/docs/claude-code/worktrees
 concept: git-worktree-isolation
 last_verified: 2026-04-18
 ngram_overlap_score: null
 review_status: approved
 ---
 # Worktrees — Reference
 Git worktrees let a repo check out multiple branches simultaneously in
 separate directories. Claude Code integrates with worktrees to give
 agents isolated filesystem scopes — one agent's edits cannot clash
 with another's.
 ## How it surfaces in CC
 - **`isolation: "worktree"` on a subagent call** — the harness creates
  a temporary worktree for the subagent. The subagent runs with its
  cwd set to the worktree. Changes stay there until merged or
  discarded.
 - **`/worktree` skill / command** — interactive tooling for creating,
  listing, and merging worktrees during a session.
 - **Auto-cleanup** — worktrees created by subagents are removed if the
  subagent made no changes. Otherwise the path is returned in the
  result for the caller to review.
 ## Branch semantics
 - Each worktree checks out a named branch. Two worktrees cannot check
  out the same branch (git's rule).
 - Creating a worktree creates a branch if one does not exist.
 - Deleting a worktree does not delete the branch; use `git branch -d`
  separately if desired.
 ## Use cases
 - **Parallel exploration** — three subagents trying three approaches,
  each in its own worktree. The parent compares diffs.
 - **Destructive experiments** — upgrade a dependency, run the full
  test suite, measure breakage. Discard the worktree if results are
  bad.
 - **Long-running session without blocking main** — execute a refactor
  in a worktree while continuing other work in the main checkout.
 ## Pitfalls
 - **Shared state leaks** — node_modules, .env, build artifacts are
  per-worktree but may be symlinked in ways that defeat isolation.
  Verify.
 - **Disk use** — each worktree is a full checkout of the tree. For
  large repos, disk pressure adds up.
 - **Branch proliferation** — agents that create worktrees without
  cleanup leave orphan branches. Prune periodically.
 - **Not a sandbox** — a worktree isolates files, not network or
  processes. A subagent in a worktree can still call the outside
  world.
 ## Composition
 - Worktrees + background agents: a background agent in a worktree can
  work on a long task while the user continues in the main checkout.
 - Worktrees + subagents + hooks: hooks fire inside the worktree cwd,
  so path-based hooks naturally scope to the isolated work.