ab504bdf8c
Extract `/ultra-cc-architect-local` and `/ultra-skill-author-local` plus all 7 supporting agents, the `cc-architect-catalog` skill (13 files), the `ngram-overlap.mjs` IP-hygiene script, and the skill-factory test fixtures from `ultraplan-local` v2.4.0 into a new `ultra-cc-architect` plugin v0.1.0. Why: ultraplan-local had drifted into containing two distinct domains — a universal planning pipeline (brief → research → plan → execute) and a Claude-Code-specific architecture phase. Keeping them together forced users to inherit an unfinished CC-feature catalog (~11 seeds) when they only wanted the planning pipeline, and locked the catalog and the pipeline into the same release cadence. The architect was already optional and decoupled at the code level — only one filesystem touchpoint remained (auto-discovery of `architecture/overview.md`), which already handles absence gracefully. Plugin manifests: - ultraplan-local: 2.4.0 → 3.0.0 (description + keywords updated) - ultra-cc-architect: new at 0.1.0 (pre-release; catalog is thin, Fase 2/3 of skill-factory unbuilt, decision-layer empty, fallback list still needed) What stays in ultraplan-local: brief/research/plan/execute commands, all 19 planning agents, security hooks, plan auto-discovery of `architecture/overview.md` (filesystem-level contract, not code-level). What moved (28 files via git mv, R100 — full history preserved): - 2 commands, 8 agents, 1 skill catalog (13 files), 2 scripts, 8 fixtures Documentation updates: plugin CLAUDE.md and README.md for both plugins, root README.md (added ultra-cc-architect section, updated ultraplan-local section), root CLAUDE.md (added ultra-cc-architect to repo-struktur), marketplace.json (registered ultra-cc-architect), ultraplan-local CHANGELOG.md (v3.0.0 entry with migration guidance). Test verification: ngram-overlap.test.mjs passes 23/23 from new location. Memory updated: feedback_no_architect_until_v3.md now points at the new plugin and reframes the threshold around catalog maturity rather than an ultraplan-local milestone. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
191 lines
10 KiB
Markdown
191 lines
10 KiB
Markdown
# ultra-cc-architect — Match tasks to Claude Code features
|
|
|
|
|
|
|
|
|
|
|
|
|
|
*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)
|