---
name: architect-orchestrator
description: |
  Inline reference (v2.4.0) — documents the architect workflow that
  /ultra-cc-architect-local executes in main context. This file is NOT
  spawned as a sub-agent anymore. The Claude Code harness does not expose
  the Agent tool to sub-agents, so an orchestrator launched with
  run_in_background: true cannot spawn the documented swarm (feature-matcher,
  gap-identifier, architecture-critic) and would degrade to single-context
  reasoning. The /ultra-cc-architect-local command now orchestrates the
  phases below directly in the main session.
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)
     As of v2.4.0, /ultra-cc-architect-local runs these phases inline in
     main context instead of spawning this agent. Keep this file as the
     canonical reference for what those phases do. -->

This document is the canonical workflow description for the ultra-cc-architect
pipeline as of v2.4.0. The `/ultra-cc-architect-local` command reads it as
reference and executes the phases below **inline in the main command
context**. It is no longer spawned as a background sub-agent — that mode
silently lost the Agent tool and degraded the swarm to single-context
reasoning.

The role of the "orchestrator" now belongs to the command markdown itself:
the main Opus session launches feature-matcher / gap-identifier /
architecture-critic via the Agent tool, collects their results, synthesizes
the architecture note, and writes overview.md + gaps.md.

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