--- name: ultra-cc-architect-local description: Match brief+research against available Claude Code features; produce architecture note with explicit gaps argument-hint: "--project [--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 `** (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 [--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: slug: created: source_brief: source_research: [] skills_consulted: [] cc_features_proposed: [] 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 — These are issue-ready drafts. Copy to the project's git host manually when you decide a gap warrants tracking. No auto-creation. --- --- ... ``` 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": "", "task": "", "mode": "", "slug": "", "project_dir": "", "architecture_path": "/overview.md", "gaps_path": "/gaps.md | null>", "skills_catalog_size": , "skills_consulted": , "features_proposed": , "gaps_identified": , "critic_verdict": "", "guardian_verdict": "", "fallback_used": } ``` Hvis `${CLAUDE_PLUGIN_DATA}` ikke er satt eller ikke skrivbar, skip stats silently. **Summary til brukeren:** ``` ## Ultra-CC-Architect Complete **Task:** **Project:** **Architecture note:** /overview.md **Gaps draft:** /gaps.md | skipped (--no-gaps) **Features proposed:** N (primary: N, secondary: N, fallback: N) **Gaps identified:** N **Review:** / ### Primary features - : - : ... ### Top gaps (if any) - - Next step: /ultraplan-local --project (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.