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