refactor(marketplace): split cc-architect from ultraplan-local into its own plugin
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>
This commit is contained in:
Kjell Tore Guttormsen
parent
97c5c9d934
commit
ab504bdf8c
48 changed files with 627 additions and 177 deletions
|
|
@ -1,23 +1,23 @@
|
|||
# ultraplan-local — Brief, Research, Architect, Plan, Execute
|
||||
# ultraplan-local — Brief, Research, Plan, Execute
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
*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 for deep implementation planning, multi-source research, CC-feature architecture matching, and autonomous execution. Five commands, one pipeline:
|
||||
A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, and autonomous execution. Four commands, one pipeline:
|
||||
|
||||
| Command | What it does |
|
||||
|---------|-------------|
|
||||
| **`/ultrabrief-local`** | Brief — interactive interview produces a task brief with explicit research plan |
|
||||
| **`/ultraresearch-local`** | Research — deep local + external research with triangulation |
|
||||
| **`/ultra-cc-architect-local`** | Architect (optional) — match brief+research against available CC features; produce architecture note with explicit gaps |
|
||||
| **`/ultraplan-local`** | Plan — agent swarm exploration, Opus planning, adversarial review |
|
||||
| **`/ultraexecute-local`** | Execute — disciplined step-by-step implementation with failure recovery |
|
||||
| **`/ultra-skill-author-local`** | Authoring (v2.3, skill-factory Fase 1) — generate one cc-architect-catalog draft from a local source with IP-hygiene |
|
||||
|
||||
Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `architecture/overview.md` (+ `gaps.md`), `plan.md`, `sessions/`, and `progress.json`.
|
||||
Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, and `progress.json`.
|
||||
|
||||
> **v3.0.0 — architect extracted to its own plugin.** The `/ultra-cc-architect-local` and `/ultra-skill-author-local` commands moved to the separate `ultra-cc-architect` plugin (v0.1.0). The plan command still auto-discovers `architecture/overview.md` if present, so installing both plugins gives you the full pipeline (brief → research → architect → plan → execute). See [CHANGELOG.md](CHANGELOG.md) for migration steps.
|
||||
|
||||
### Division of labor
|
||||
|
||||
|
|
@ -25,8 +25,7 @@ Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{s
|
|||
|---|---|---|
|
||||
| `/ultrabrief-local` | **Capture intent** — intent, goal, non-goals, success criteria, and a research plan with explicit topics. Interactive only. | `brief.md` (task brief) |
|
||||
| `/ultraresearch-local` | **Gather context** — code state, external docs, community, risk. Makes NO build decisions. | `research/NN-slug.md` (research brief) |
|
||||
| `/ultra-cc-architect-local` | **Match to CC features** (optional) — match brief+research against Claude Code feature catalog (Hooks, Subagents, Skills, MCP, …) with brief-anchored rationale and honest coverage gaps. | `architecture/overview.md` + `architecture/gaps.md` |
|
||||
| `/ultraplan-local` | **Transform intent into an executable contract** — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. Auto-discovers `architecture/overview.md` as priors. | `plan.md` with Manifest blocks + `plan_version: 1.7` |
|
||||
| `/ultraplan-local` | **Transform intent into an executable contract** — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. Auto-discovers `architecture/overview.md` as priors when the `ultra-cc-architect` plugin is installed. | `plan.md` with Manifest blocks + `plan_version: 1.7` |
|
||||
| `/ultraexecute-local` | **Execute the contract disciplined** — fresh verification, independent manifest audit, honest reporting. Does NOT compensate for weak plans — escalates. | `progress.json` + structured report + manifest-audit status |
|
||||
|
||||
**Principle:** Each step consumes the previous step's structured artifact. If execute has to guess, the plan is weak and must be revised upstream — not patched downstream.
|
||||
|
|
@ -60,11 +59,7 @@ claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-mar
|
|||
# Research each topic identified in the brief (manual default)
|
||||
/ultraresearch-local --project .claude/projects/2026-04-18-jwt-auth --external "What are current JWT best practices?"
|
||||
|
||||
# Match task against available CC features (optional, v2.2)
|
||||
/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth
|
||||
# → architecture/overview.md + architecture/gaps.md
|
||||
|
||||
# Plan from brief + research + architecture (architecture auto-discovered)
|
||||
# Plan from brief + research
|
||||
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth
|
||||
|
||||
# Execute
|
||||
|
|
@ -73,6 +68,8 @@ claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-mar
|
|||
|
||||
Or opt into auto-mode in `/ultrabrief-local` — it will run research and planning sequentially inline in the main context, and return when `plan.md` is ready.
|
||||
|
||||
For Claude-Code-specific architecture matching (matching brief+research to features like Hooks, Subagents, Skills, MCP), install the separate `ultra-cc-architect` plugin. It sits between research and plan — `/ultraplan-local` auto-discovers its output.
|
||||
|
||||
> **v2.4.0 — background mode removed.** All four orchestrator commands now run foreground in the main context. The `--fg` flag is preserved as a no-op alias for backward compatibility. Background mode silently degraded the agent swarm (the harness does not expose the Agent tool to sub-agents) — see [CHANGELOG](CHANGELOG.md) for the full rationale.
|
||||
|
||||
## When to use it
|
||||
|
|
@ -187,57 +184,6 @@ Flags combine: `--project <dir> --external`.
|
|||
|
||||
---
|
||||
|
||||
## `/ultra-cc-architect-local` — Architect *(optional, v2.2)*
|
||||
|
||||
Matches the task brief and any 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 per feature and an explicit coverage-gap section.
|
||||
|
||||
This step is optional. You can go straight from research to planning. 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` + `scope-guardian` in parallel (unless `--quick`).
|
||||
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 since v2.4.0). |
|
||||
| `--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** — a table with rationale (brief-anchored), supporting skill, and 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.
|
||||
|
||||
### CC-feature catalog
|
||||
|
||||
The architect command reads from `skills/cc-architect-catalog/`, a plugin-internal catalog of hand-written skills covering each CC feature at one or more layers (`reference`, `pattern`, `decision`). v2.2 shipped 10 seeds covering all 8 features at the reference layer (plus pattern layer for hooks and subagents). The catalog is designed for expansion via the skill-factory process (v2.3) — gaps surfaced by the architect command are the backlog for that work.
|
||||
|
||||
**Slug convention (v2.3):** files follow `<cc_feature>[-<qualifier>]-<layer>.md`. Unqualified slugs (e.g., `hooks-pattern.md`) are the baseline/canonical entry for a `(feature, layer)` pair. Qualified slugs (e.g., `hooks-observability-pattern.md`) cover specific sub-patterns without displacing the baseline. `feature-matcher` prefers the baseline when the brief does not specifically justify a qualified variant; it may propose multiple supporting skills when they cover non-overlapping aspects. Slug collisions with approved skills are a hard error — skill-factory drafts must qualify or revise instead. **v2.3.2:** `skill-drafter` performs a pre-write check against `{catalog_root}/<slug>.md` and prepends a warning block to its confirmation when the proposed slug would collide, suggesting a qualified slug derived from the concept handle. The draft still writes to `.drafts/` — the warning exists so users see the overwrite risk before running `mv`.
|
||||
|
||||
### 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.
|
||||
|
||||
---
|
||||
|
||||
## `/ultraplan-local` — Planning
|
||||
|
||||
Produces an implementation plan detailed enough for autonomous execution. **v2.0 breaking change:** requires `--brief` or `--project`. There is no longer an interview inside `/ultraplan-local` — use `/ultrabrief-local` first.
|
||||
|
|
@ -248,10 +194,11 @@ Produces an implementation plan detailed enough for autonomous execution. **v2.0
|
|||
2. **Spec review** → **brief review** — `brief-reviewer` validates completeness, consistency, testability, scope clarity, and research plan validity
|
||||
3. **Explore** — 6-8 specialized Sonnet agents analyze your codebase in parallel
|
||||
4. **Research** — optional research briefs enrich planning (`--research`, or auto-discovered in `{project_dir}/research/`)
|
||||
5. **Synthesize** — findings merged into a unified codebase understanding
|
||||
6. **Plan** — Opus creates a comprehensive implementation plan with per-step YAML manifests
|
||||
7. **Critique** — adversarial review by `plan-critic` (9 dimensions) and `scope-guardian`
|
||||
8. **Handoff** — plan written; execute now, save for later, or export
|
||||
5. **Architecture priors** — if `{project_dir}/architecture/overview.md` exists (produced by the optional `ultra-cc-architect` plugin), `cc_features_proposed` are loaded as priors. Missing file is fine.
|
||||
6. **Synthesize** — findings merged into a unified codebase understanding
|
||||
7. **Plan** — Opus creates a comprehensive implementation plan with per-step YAML manifests
|
||||
8. **Critique** — adversarial review by `plan-critic` (9 dimensions) and `scope-guardian`
|
||||
9. **Handoff** — plan written; execute now, save for later, or export
|
||||
|
||||
Output:
|
||||
- With `--project <dir>`: `{dir}/plan.md`
|
||||
|
|
@ -402,52 +349,6 @@ The executor implements defense-in-depth security across four layers:
|
|||
|
||||
---
|
||||
|
||||
## `/ultra-skill-author-local` — Authoring *(skill-factory Fase 1, v2.3)*
|
||||
|
||||
Manual one-skill-at-a-time generator for the `cc-architect-catalog`. Channel 2 of the skill-factory strategy: 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 10 seed skills covering 8 features × 2 layers, the matcher rarely finds support and silently produces empty proposals. 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 (concept → draft → IP-hygiene) 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
|
||||
|
||||
---
|
||||
|
||||
## The full pipeline
|
||||
|
||||
```
|
||||
|
|
@ -459,7 +360,7 @@ Calibration fixtures in `tests/fixtures/skill-factory/` pin the verdict bands ag
|
|||
│ ↓ │ │ ↓ │ │ agents (parallel) │ │ ↓ │
|
||||
│ Research │ │ Triangulation │ │ ↓ │ │ Execute steps │
|
||||
│ topics │ │ ↓ │ │ Opus planning │ │ (verify + manifest │
|
||||
│ ↓ │ → brief → (optional) ─→ → │ ↓ │→ │ + checkpoint) │
|
||||
│ ↓ │ → brief → → → → → → → → → → → ↓ │→ │ + checkpoint) │
|
||||
│ brief.md │ │ research/*.md │ │ plan-critic + │ │ ↓ │
|
||||
└──────────────┘ └───────────────────┘ │ scope-guardian │ │ Phase 7.5 manifest │
|
||||
│ ↓ │ │ audit + 7.6 recovery│
|
||||
|
|
@ -470,6 +371,8 @@ Calibration fixtures in `tests/fixtures/skill-factory/` pin the verdict bands ag
|
|||
|
||||
All artifacts live under `.claude/projects/{YYYY-MM-DD}-{slug}/`.
|
||||
|
||||
To insert a Claude-Code-specific architecture-matching step between research and plan, install the separate `ultra-cc-architect` plugin — `/ultraplan-local` auto-discovers its `architecture/overview.md` output as priors.
|
||||
|
||||
### Example workflows
|
||||
|
||||
**Standard pipeline (manual control):**
|
||||
|
|
@ -521,6 +424,28 @@ All artifacts live under `.claude/projects/{YYYY-MM-DD}-{slug}/`.
|
|||
|
||||
---
|
||||
|
||||
## Upgrading from v2.x to v3.0.0
|
||||
|
||||
v3.0.0 is a structural release that does **not** break the planning flow but changes plugin layout:
|
||||
|
||||
- `/ultra-cc-architect-local` and `/ultra-skill-author-local` were moved to the new `ultra-cc-architect` plugin (v0.1.0).
|
||||
- `/ultraplan-local` still auto-discovers `architecture/overview.md` if present — install both plugins to keep the full pipeline working.
|
||||
- `cc-architect-catalog` skill moved to the new plugin. If you customized seeds locally, follow `git log --follow` to track them in the new location.
|
||||
- `ngram-overlap.mjs` script and skill-factory test fixtures moved with the new plugin.
|
||||
|
||||
If you only used `/ultrabrief-local`, `/ultraresearch-local`, `/ultraplan-local`, and `/ultraexecute-local`: no action needed. Update the plugin and continue.
|
||||
|
||||
If you used `/ultra-cc-architect-local` or `/ultra-skill-author-local`: install the new plugin alongside this one:
|
||||
|
||||
```json
|
||||
{
|
||||
"enabledPlugins": {
|
||||
"ultraplan-local@ktg-plugin-marketplace": true,
|
||||
"ultra-cc-architect@ktg-plugin-marketplace": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Upgrading from v1.x
|
||||
|
||||
v2.0.0 is a **breaking release**. See [MIGRATION.md](MIGRATION.md) for a step-by-step guide. Short version:
|
||||
|
|
@ -570,6 +495,8 @@ Or enable directly in `~/.claude/settings.json`:
|
|||
}
|
||||
```
|
||||
|
||||
For Claude-Code-specific architecture matching (between research and plan), also enable `ultra-cc-architect@ktg-plugin-marketplace`.
|
||||
|
||||
## Cost profile
|
||||
|
||||
- **Brief**: 1 Opus session (interactive; interview + write)
|
||||
|
|
@ -596,7 +523,7 @@ The plugin minimizes Opus usage by front-loading cheap Sonnet exploration.
|
|||
```
|
||||
ultraplan-local/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json # Plugin manifest (v2.0.0)
|
||||
│ └── plugin.json # Plugin manifest (v3.0.0)
|
||||
├── agents/ # 19 specialized agents
|
||||
│ ├── architecture-mapper.md # Codebase structure and patterns
|
||||
│ ├── dependency-tracer.md # Import chains and data flow
|
||||
|
|
@ -641,6 +568,8 @@ ultraplan-local/
|
|||
└── README.md
|
||||
```
|
||||
|
||||
CC-feature catalog, skill-factory, and architect/skill-author commands moved to the separate `ultra-cc-architect` plugin in v3.0.0.
|
||||
|
||||
Pure markdown commands and agents. Hooks are self-contained Node.js with zero dependencies.
|
||||
|
||||
## Contributing
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue