ktg-plugin-marketplace/plugins/ultra-cc-architect/CLAUDE.md

ultra-cc-architect

Claude-Code-specific architecture matching and skill-factory authoring. Extracted from ultraplan-local v2.4.0 in v0.1.0 (2026-04-30).

Status: pre-release (v0.1.0). Catalog is thin (~11 seed skills across 8 features), Fase 2/3 of the skill-factory remain unbuilt, decision-layer skills are intentionally empty. Expect breaking changes before v1.0.

Design principle: Context Engineering — match a task brief and research against available CC features, propose a feature set with brief-anchored rationale, surface honest coverage gaps. The plugin consumes upstream artifacts (typically from ultraplan-local) and produces an architecture note that downstream ultraplan-local can auto-discover as priors.

Commands

Command	Description	Model
/ultra-cc-architect-local	Architect — match brief+research against Claude Code features; produce architecture note with explicit gaps. Requires --project	opus
/ultra-skill-author-local	Authoring (skill-factory Fase 1) — generate one cc-architect-catalog draft from a local source with IP-hygiene	opus

/ultra-cc-architect-local modes

Flag	Behavior
--project <dir>	Required — read {dir}/brief.md and {dir}/research/*.md, write {dir}/architecture/overview.md + {dir}/architecture/gaps.md
--fg	No-op alias (foreground is default)
--quick	Skip adversarial review (architecture-critic)
--no-gaps	Skip gap-identifier; overview.md only

Architect sits between /ultraresearch-local and /ultraplan-local in the typical pipeline. It matches the task brief + research against available Claude Code features (Hooks, Subagents, Skills, Output Styles, MCP, Plan Mode, Worktrees, Background Agents) using the seeded cc-architect-catalog skill, and produces a proposed feature set with brief-anchored rationale plus explicit gaps (missing reference, pattern, decision, or outside-CC-scope).

/ultra-skill-author-local modes

Flag	Behavior
(default)	Run the pipeline (concept → draft → IP-hygiene) foreground
--fg	Same as default; flag accepted for pipeline-convention consistency
--quick	Skip IP-hygiene with BIG WARNING (drafting-pipeline test only)

Manual one-skill-at-a-time generator for the cc-architect-catalog. A curated local source enters, one draft skill exits in skills/cc-architect-catalog/.drafts/ with its n-gram containment score against the source stamped into the frontmatter (or the draft is deleted when the overlap is too high).

Agents

Agent	Model	Role
architect-orchestrator	opus	Inline reference documentation for the architecture phase workflow (feature-matcher + gap-identifier + critic)
feature-matcher	sonnet	Match brief+research to CC features using catalog; brief-anchored rationale + fallback ranking
gap-identifier	sonnet	Detect catalog/pattern/decision/outside-CC-scope gaps; emit issue-ready drafts
architecture-critic	sonnet	Adversarial review of architecture note (hallucination gate, brief-anchor integrity, gap honesty)
skill-author-orchestrator	opus	Inline reference for the /ultra-skill-author-local 3-stage pipeline
concept-extractor	sonnet	Read one local source file and extract a structured concept JSON (cc_feature, layer, slug)
skill-drafter	sonnet	Consume concept JSON + source; produce draft SKILL.md with 9-field frontmatter
ip-hygiene-checker	sonnet	Score draft against source via ngram-overlap.mjs; stamp verdict or delete draft

Architecture

Architect: Foreground workflow: Parse mode (--project required) → Read inputs + audit catalog skill → Parallel feature-matcher + gap-identifier (spawned from main context) → Synthesize overview.md (6 sections + YAML frontmatter) → Adversarial review via architecture-critic (skipped in --quick; hallucination gate is BLOCKER) → Write gaps.md + stats → Present summary. Writes to {dir}/architecture/overview.md and {dir}/architecture/gaps.md. Additive — downstream /ultraplan-local auto-discovers the note if present.

Skill-factory Fase 1 (/ultra-skill-author-local): Sequential 3-stage pipeline, no parallelism, no retry. Source file → concept-extractor (JSON: cc_feature/layer/slug) → skill-drafter (writes .drafts/<slug>.md, 9-field frontmatter, 150–600 word body in user voice) → ip-hygiene-checker (runs scripts/ngram-overlap.mjs; accepted/needs-review stamps ngram_overlap_score into frontmatter, rejected deletes the draft).

CC-feature catalog

The cc-architect-catalog skill at skills/cc-architect-catalog/ indexes Claude Code primitives across three layers:

• reference — how a feature works
• pattern — when to reach for it
• decision — adoption heuristics (intentionally empty in v0.1.0; pending skill-factory Fase 2)

The feature-matcher agent only proposes features covered by the catalog or an explicit fallback list — a hallucination gate that architecture-critic enforces as BLOCKER severity. The gap-identifier agent emits issue-ready drafts for missing catalog entries so the catalog grows with real usage rather than speculation.

Slug convention: catalog files follow <cc_feature>[-<qualifier>]-<layer>.md.

• Unqualified slugs (e.g., hooks-pattern.md) are the canonical baseline — one per (feature, layer) pair, covering generic shapes and decision-heuristics for the feature.
• Qualified slugs (e.g., hooks-observability-pattern.md) cover specific named sub-patterns. Zero-or-more per (feature, layer) pair. The qualifier MUST be kebab-case and descriptive (observability, migration, multi-tenant).
• Matcher logic: feature-matcher builds cc_feature → {layer → [skills]} and prefers the unqualified baseline when the brief does not specifically justify a variant. Multiple skills can be proposed together when they cover non-overlapping aspects of the same feature.
• Critic enforcement: architecture-critic verifies every cited supporting_skill name exists as a real file in the catalog (blocker severity). The cc_feature hallucination gate is unchanged — still validates against the taxonomy, not slugs.
• Collision handling: skill-factory drafts that would overwrite an approved slug are a hard error. Resolution is either to qualify the new slug or revise the existing baseline.
• Drafter collision hint: skill-drafter reads {catalog_root}/<slug>.md before writing, and prepends a warning block to its confirmation output when an existing skill would be overwritten during manual mv promotion. The draft is still written to .drafts/<slug>.md — the check is a hint, not a block.

Seeds (v0.1.0, inherited from ultraplan-local v2.3.1): 11 skills across 8 features — one qualified pattern (hooks-observability-pattern.md, promoted from ai-psychosis/README.md, ngram-overlap 0.01, approved). Decision-layer intentionally empty pending skill-factory Fase 2.

Project-directory contract (consumed)

The plugin participates in the ultraplan-local project-directory contract. It is not strictly required to use ultraplan-local, but the typical workflow assumes those upstream artifacts exist:

.claude/projects/{YYYY-MM-DD}-{slug}/
  brief.md           ← consumed (typically produced by /ultrabrief-local)
  research/*.md      ← consumed (typically produced by /ultraresearch-local)
  architecture/      ← produced by this plugin
    overview.md
    gaps.md
  plan.md            ← downstream consumer is /ultraplan-local (it auto-discovers overview.md)

Path discipline: the plugin only reads from brief.md + research/*.md, only writes to architecture/overview.md + architecture/gaps.md. No code dependency on ultraplan-local — the contract is filesystem-level only.

Stats

• Architect stats: ${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-stats.jsonl
• Skill-author stats: ${CLAUDE_PLUGIN_DATA}/ultra-skill-author-local-stats.jsonl

Roadmap to v1.0

Pre-release because:

• Catalog is thin (11 seed skills; gaps in pattern + decision layers across most features)
• Decision-layer skills are intentionally empty — Fase 2 of skill-factory not yet built
• Skill-factory has only Fase 1 (manual one-source one-draft); Fase 2/3 (CC-changelog watcher, batch processing, cross-feature decision skills) remain
• feature-matcher falls back to a hardcoded list when catalog is sparse — fragile until catalog grows

See ROADMAP.md (gitignored) for current milestone tracking.

Terminology

• Architecture note — the artifact produced by /ultra-cc-architect-local: overview.md + gaps.md. Proposes which Claude Code features fit the task with brief-anchored rationale and explicit gaps.
• Catalog skill — a single file in skills/cc-architect-catalog/<slug>.md. Indexes one (feature, layer) pair, possibly with a qualifier.
• Draft — output of skill-drafter, written to skills/cc-architect-catalog/.drafts/<slug>.md. Promoted to the catalog by manual mv after review.