ktg-plugin-marketplace/plugins/ultra-cc-architect/commands/ultra-cc-architect-local.md

---
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`** — no-op alias beholdt for bakoverkompatibilitet. Alle faser
   kjører alltid inline i main-kontekst som av v2.4.0. Sett
   **execution = foreground** (eneste modus).

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     Foreground pipeline → overview.md + gaps.md
  --fg        No-op alias (foreground is the only mode as of v2.4.0)
  --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:      foreground{, quick}{, no-gaps}
Project:   {project_dir}
Brief:     {brief_path} ({brief_quality})
Research:  {N} files detected
```

## Phase 2 — Forbered output-mappe (foreground)

Opprett `{architecture_dir}` hvis den ikke eksisterer (`mkdir -p`).

Rapporter til brukeren:

```
Architecture pipeline running in foreground.

  Project: {project_dir}
  Brief:   {brief_path}
  Research: {N} briefs
  Output:  {architecture_dir}/overview.md (+ gaps.md)
```

Fortsett deretter inline til neste fase.

> **Hvorfor foreground?** Som av v2.4.0 spawnes `architect-orchestrator`
> ikke lenger som en background-agent. Claude Code-harnessen eksponerer
> ikke Agent-tool til sub-agenter, så en orchestrator startet med
> `run_in_background: true` kan ikke spawne `feature-matcher` /
> `gap-identifier` / `architecture-critic`-swarm og degraderer stille til
> enkelt-kontekst-resonnering. Å kjøre fasene inline i main-kontekst holder
> swarm-en intakt. Bruk `claude -p` i et separat terminal-vindu for
> langvarige headless-kjøringer.

---

**Alle resterende faser kjører inline i hovedkommandoens 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.