ktg-plugin-marketplace/plugins/ultraplan-local/agents/architect-orchestrator.md

name	description	model	color	tools
architect-orchestrator	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.	opus	cyan	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):

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

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

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