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

name	description	argument-hint	model	allowed-tools
ultra-cc-architect-local	Match brief+research against available Claude Code features; produce architecture note with explicit gaps	--project <dir> [--fg | --quick | --no-gaps]	opus	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:

---
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:

# 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:

{
  "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.