--- 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"] --- 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: slug: created: source_brief: source_research: [] skills_consulted: [] cc_features_proposed: [] 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 — These are issue-ready drafts. Copy to the project's git host manually when you decide a gap warrants tracking. No auto-creation. --- --- ... ``` 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": "", "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": } ``` 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:** **Project:** **Architecture note:** **Gaps draft:** **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 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.