# ultra-cc-architect — Match tasks to Claude Code features

![Version](https://img.shields.io/badge/version-0.1.0-orange)
![Status](https://img.shields.io/badge/status-pre--release-yellow)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple)

*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*

A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin that matches a task brief and research against available Claude Code features (Hooks, Subagents, Skills, Output Styles, MCP, Plan Mode, Worktrees, Background Agents) and produces an architecture note with brief-anchored rationale plus explicit coverage gaps.

> **Pre-release (v0.1.0).** Extracted from `ultraplan-local` v2.4.0 on 2026-04-30. The catalog is thin (11 seed skills) and the skill-factory has only Fase 1. Expect breaking changes before v1.0. See [Roadmap to v1.0](#roadmap-to-v10).

| Command | What it does |
|---------|--------------|
| **`/ultra-cc-architect-local`** | Match brief+research against CC features; produce architecture note with explicit gaps |
| **`/ultra-skill-author-local`** | Skill-factory Fase 1 — generate one cc-architect-catalog draft from a local source with IP-hygiene |

## Why a separate plugin

`ultraplan-local` provides a universal planning pipeline (brief → research → plan → execute) that is technology-agnostic. `ultra-cc-architect` is the Claude-Code-specific layer on top: it only makes sense if you're building features for Claude Code itself. Splitting them out:

- Lets you adopt the planning pipeline without inheriting an unfinished CC-feature catalog
- Lets the catalog and feature-matching logic version independently from the planning flow
- Makes it explicit when a workflow takes a CC-specific turn

## Typical workflow

`ultra-cc-architect` consumes the same project-directory contract as `ultraplan-local`. The full pipeline:

```bash
# 1. Capture intent (ultraplan-local plugin)
/ultrabrief-local Add a custom prompt-injection hook to all our plugins
# → .claude/projects/2026-04-30-prompt-injection-hook/brief.md

# 2. Research (ultraplan-local plugin)
/ultraresearch-local --project .claude/projects/2026-04-30-prompt-injection-hook --external "How do PreToolUse hooks compose with prompt-level rules?"
# → .claude/projects/2026-04-30-prompt-injection-hook/research/01-*.md

# 3. Match to CC features (THIS plugin)
/ultra-cc-architect-local --project .claude/projects/2026-04-30-prompt-injection-hook
# → architecture/overview.md + architecture/gaps.md

# 4. Plan (ultraplan-local plugin — auto-discovers architecture/overview.md)
/ultraplan-local --project .claude/projects/2026-04-30-prompt-injection-hook

# 5. Execute (ultraplan-local plugin)
/ultraexecute-local --project .claude/projects/2026-04-30-prompt-injection-hook
```

You don't have to use `ultraplan-local` — the plugin reads `brief.md` + `research/*.md` from any directory matching the contract. But the natural upstream is `/ultrabrief-local` + `/ultraresearch-local`, and the natural downstream is `/ultraplan-local`.

## `/ultra-cc-architect-local` — Architect

Reads the task brief and any research, then matches against available Claude Code features and produces an architecture note with brief-anchored rationale per feature and an explicit coverage-gap section.

Use the architect step when:
- The task touches orchestration, policy, or long-running work where CC-feature choice matters
- You want a reviewed, explicit feature selection before planning instead of letting the planner pick implicitly
- You want a backlog of coverage gaps (things the skill catalog does not yet know) in a shareable form

### How it works

1. Read `{project_dir}/brief.md` + all `{project_dir}/research/*.md`
2. Read the CC-feature skill catalog from `skills/cc-architect-catalog/`
3. Run `feature-matcher` + `gap-identifier` in parallel
4. Write `architecture/overview.md` (six required sections, YAML frontmatter)
5. Run `architecture-critic` (unless `--quick`) — hallucination gate is BLOCKER
6. Write `architecture/gaps.md` as issue-ready drafts (unless `--no-gaps`)

Downstream: `/ultraplan-local` auto-discovers `architecture/overview.md` in project mode and treats its `cc_features_proposed` as *priors* — exploration agents may override with evidence.

### Modes

| Flag | Behavior |
|------|----------|
| `--project <dir>` | **Required.** Read `{dir}/brief.md` + `{dir}/research/*.md`; write to `{dir}/architecture/`. |
| `--fg` | No-op alias (foreground is default). |
| `--quick` | Skip adversarial review (no `architecture-critic` pass). |
| `--no-gaps` | Do not write `gaps.md` (gap section remains inside `overview.md`). |

### What the architecture note contains

- **Context** — 3 sentences paraphrasing brief Intent + Goal
- **Proposed CC features** — table with rationale (brief-anchored), supporting skill, confidence per feature
- **Feature composition** — sequence, conflicts, fallbacks
- **Coverage gaps identified** — always present, even if empty. Honest "what we don't know yet"
- **Alternatives considered** — at least one rejected feature combination with rationale from the brief
- **Open questions** — forwarded to the plan phase

### Hallucination gate

The `architecture-critic` agent blocks any feature proposal that is not in the catalog's `cc_feature` taxonomy or the `feature-matcher`'s documented fallback minimum list. This prevents the architect from inventing CC features that do not exist.

## `/ultra-skill-author-local` — Skill-factory Fase 1

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

### Why it exists

`/ultra-cc-architect-local` enforces a hallucination gate that only permits feature proposals backed by the catalog. With 11 seed skills covering 8 features, the matcher falls back to a hardcoded list more often than it should. This command grows the catalog without spinning up automation: one source → one draft → manual review → manual `mv` for promotion.

### Pipeline

Sequential, no retry, no parallelism:

```
/ultra-skill-author-local <source>
  → concept-extractor (sonnet)    → JSON: cc_feature, layer, slug
  → skill-drafter (sonnet)        → .drafts/<slug>.md, 9-field frontmatter
  → ip-hygiene-checker (sonnet)   → runs scripts/ngram-overlap.mjs
        verdict accepted/needs-review → stamp ngram_overlap_score
        verdict rejected               → rm draft (no preservation)
```

### Modes

| Mode | Usage | Behavior |
|------|-------|----------|
| **Default** | `/ultra-skill-author-local <source>` | Run the pipeline foreground |
| **`--fg`** | `/ultra-skill-author-local <source> --fg` | Same as default; flag accepted for pipeline-convention consistency |
| **`--quick`** | `/ultra-skill-author-local <source> --quick` | Skip IP-hygiene with BIG WARNING (drafting-pipeline test only) |

### IP-hygiene utility

`scripts/ngram-overlap.mjs` — pure Node stdlib, zero dependencies. Word-5-gram containment similarity (asymmetric draft⊆source) plus longest-consecutive-shingle-run secondary signal. Verdict bands: `accepted` (<0.15 AND <8), `needs-review` (mid), `rejected` (≥0.35 OR ≥15). Short-text fallback to n=4 when min(words) <500. CLI emits JSON.

Calibration fixtures in `tests/fixtures/skill-factory/` pin the verdict bands against representative prose. Re-verify any threshold change against these fixtures.

### Non-goals (explicit, Fase 1)

- No automation, cron, or watcher
- No CC changelog diffing or auto-research
- No batch processing or review command
- No decision-layer skills (cross-feature comparison is Fase 2+)
- No URL or remote sources — local files only
- Manual `mv` from `.drafts/` to catalog root is the promotion mechanism

## CC-feature catalog

The catalog at `skills/cc-architect-catalog/` indexes Claude Code primitives across three layers (`reference`, `pattern`, `decision`). v0.1.0 inherits the v2.3.1 seeds from `ultraplan-local`: 11 skills covering 8 features, with one qualified pattern (`hooks-observability-pattern.md`).

**Slug convention:** `<cc_feature>[-<qualifier>]-<layer>.md`. Unqualified slugs are the canonical baseline per `(feature, layer)` pair; qualified slugs cover specific sub-patterns. `feature-matcher` prefers the unqualified baseline when the brief does not specifically justify a qualified variant. Slug collisions with approved skills are a hard error.

The catalog is designed for expansion via `/ultra-skill-author-local`. Gaps surfaced by `/ultra-cc-architect-local` are the backlog for catalog growth.

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

v1.0 ships when the catalog is dense enough that the fallback list can be removed and decision-layer skills exist for the most common adoption-question patterns.

## Installation

Add the marketplace and enable both plugins:

```bash
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
```

Then in `~/.claude/settings.json`:

```json
{
  "enabledPlugins": {
    "ultraplan-local@ktg-plugin-marketplace": true,
    "ultra-cc-architect@ktg-plugin-marketplace": true
  }
}
```

You can install `ultra-cc-architect` without `ultraplan-local`, but the typical workflow assumes brief + research artifacts produced upstream.

## Cost profile

- **Architect**: 1 Opus orchestration + 2-3 Sonnet agents (feature-matcher + gap-identifier in parallel; architecture-critic if not `--quick`)
- **Skill-author**: 3 Sonnet agents sequential (concept-extractor + skill-drafter + ip-hygiene-checker)

## Requirements

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (CLI, desktop app, or web app)
- Claude subscription with Opus access (Max plan recommended)
- For typical pipeline use: `ultraplan-local` plugin (provides upstream `/ultrabrief-local` + `/ultraresearch-local` and downstream `/ultraplan-local`)

## License

[MIT](LICENSE)