feat(ultraplan-local): v2.2.0 — /ultra-cc-architect-local
New optional command between /ultraresearch-local and /ultraplan-local that matches brief+research against 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 gaps. Added: - commands/ultra-cc-architect-local.md (--project, --fg, --quick, --no-gaps) - agents/architect-orchestrator.md (opus) — 6-phase background orchestrator - agents/feature-matcher.md (sonnet) — fallback-ranked feature proposals - agents/gap-identifier.md (sonnet) — 4 gap classes with issue-ready drafts - agents/architecture-critic.md (sonnet) — hallucination gate as BLOCKER - skills/cc-architect-catalog/ — SKILL.md + 10 seed entries (reference/pattern) Changed (non-breaking): - commands/ultraplan-local.md — auto-discovers architecture/overview.md - agents/planning-orchestrator.md — cross-references cc_features_proposed - plugin.json — 2.1.0 → 2.2.0, description, cc-architecture keyword - CHANGELOG, README, CLAUDE.md (plugin + marketplace root) Pipeline becomes brief → research → architect → plan → execute. Architect is optional; existing project dirs keep working unchanged. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen
parent
23aaaa6e6c
commit
2da95b3cd3
24 changed files with 2325 additions and 28 deletions
376
plugins/ultraplan-local/commands/ultra-cc-architect-local.md
Normal file
376
plugins/ultraplan-local/commands/ultra-cc-architect-local.md
Normal file
|
|
@ -0,0 +1,376 @@
|
|||
---
|
||||
name: ultra-cc-architect-local
|
||||
description: Match brief+research against available Claude Code features; produce architecture note with explicit gaps
|
||||
argument-hint: "--project <dir> [--fg | --quick | --no-gaps]"
|
||||
model: opus
|
||||
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
|
||||
---
|
||||
|
||||
# Ultra CC Architect Local v1.0
|
||||
|
||||
Valgfri pipeline-kommando som matcher oppgavens behov (brief +
|
||||
research) mot tilgjengelige Claude Code-features (Hooks, Subagents,
|
||||
Skills, Output Styles, MCP, Plan Mode, Worktrees, Background Agents)
|
||||
og produserer et arkitekturnotat med eksplisitt gap-seksjon.
|
||||
|
||||
Pipelinen er 5-stegs når denne kommandoen er med:
|
||||
|
||||
```
|
||||
/ultrabrief-local → brief.md
|
||||
/ultraresearch-local → research/*.md
|
||||
/ultra-cc-architect-local → architecture/overview.md + gaps.md (this command)
|
||||
/ultraplan-local → plan.md
|
||||
/ultraexecute-local → execution
|
||||
```
|
||||
|
||||
**Designprinsipp — selvlærende, men ikke autonom.** Kommandoen leser
|
||||
en kuratert skill-katalog (`skills/cc-architect-catalog/`) med seed-
|
||||
skills for hver CC-feature. Katalogen utvides over tid av en egen
|
||||
skill-factory (separat utviklingsprosess). Arkitekturnotatet er et
|
||||
forslag — brukeren godkjenner før plan-fasen.
|
||||
|
||||
**Pipeline-integrasjon.** `/ultraplan-local` oppdager automatisk
|
||||
`{project_dir}/architecture/overview.md` og bruker feature-forslagene
|
||||
som priors (ikke mandater) under exploration og planning.
|
||||
|
||||
## Phase 1 — Parse mode and validate input
|
||||
|
||||
Parse `$ARGUMENTS` for flags. Ordered precedence:
|
||||
|
||||
1. **`--project <dir>`** (PÅKREVD) — les `{dir}/brief.md` og
|
||||
auto-oppdag `{dir}/research/*.md`. Skriv til `{dir}/architecture/`.
|
||||
Hvis `{dir}` eller `{dir}/brief.md` mangler:
|
||||
```
|
||||
Error: project directory not initialized. Run /ultrabrief-local first.
|
||||
Missing: {dir}/brief.md
|
||||
```
|
||||
Sett **project_dir = {dir}**, **brief_path = {dir}/brief.md**.
|
||||
Sett **architecture_dir = {dir}/architecture/** — opprettes i
|
||||
Phase 2 hvis den mangler.
|
||||
|
||||
2. **`--fg`** — foreground. Alle faser inline. Default er background
|
||||
via `architect-orchestrator`. Sett **execution = foreground**.
|
||||
|
||||
3. **`--quick`** — hopp over Phase 6 (adversarial review). Sett
|
||||
**mode = quick**.
|
||||
|
||||
4. **`--no-gaps`** — utelat `gaps.md` (gap-seksjonen beholdes internt
|
||||
i `overview.md`). Sett **mode_suffix = no-gaps**. (Kan kombineres
|
||||
med `--quick`.)
|
||||
|
||||
5. Hvis `--project` mangler: vis usage og stopp:
|
||||
|
||||
```
|
||||
Usage: /ultra-cc-architect-local --project <dir> [--fg] [--quick] [--no-gaps]
|
||||
|
||||
A project directory is required. Run /ultrabrief-local first to create one.
|
||||
|
||||
Modes:
|
||||
default Background via architect-orchestrator → overview.md + gaps.md
|
||||
--fg All phases in foreground (blocks session)
|
||||
--quick Skip adversarial review (no architecture-critic pass)
|
||||
--no-gaps Do not write gaps.md (gap-section stays inside overview.md)
|
||||
|
||||
Examples:
|
||||
/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth
|
||||
/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth --fg
|
||||
/ultra-cc-architect-local --project .claude/projects/2026-04-18-jwt-auth --fg --quick
|
||||
|
||||
Pipeline position (5-steg):
|
||||
/ultrabrief-local → /ultraresearch-local → /ultra-cc-architect-local
|
||||
→ /ultraplan-local → /ultraexecute-local
|
||||
```
|
||||
|
||||
Ikke fortsett forbi dette steget hvis `--project` mangler.
|
||||
|
||||
### Les briefen
|
||||
|
||||
Les `{brief_path}` og parse frontmatter. Hent:
|
||||
- `task` — one-liner for stats
|
||||
- `slug` — brukes i overview-frontmatter
|
||||
- `project_dir` — hvis satt, kryssjekk mot flag; mismatch → advarsel,
|
||||
men bruk flag-verdien
|
||||
- `brief_quality` — `complete | partial`. Partial briefer er lovlige;
|
||||
noter i overview.md under "Open questions".
|
||||
|
||||
### Scan research/
|
||||
|
||||
Glob `{project_dir}/research/*.md`. Lagre liste som
|
||||
**research_paths**. Zero research er lovlig.
|
||||
|
||||
### Rapporter detektert modus
|
||||
|
||||
```
|
||||
Mode: {default | foreground}{, quick}{, no-gaps}
|
||||
Project: {project_dir}
|
||||
Brief: {brief_path} ({brief_quality})
|
||||
Research: {N} files detected
|
||||
```
|
||||
|
||||
## Phase 2 — Background transition
|
||||
|
||||
**Hvis execution = foreground:** hopp over denne fasen. Fortsett inline
|
||||
fra Phase 3.
|
||||
|
||||
**Hvis execution = default (background):**
|
||||
|
||||
Opprett `{architecture_dir}` hvis den ikke eksisterer (`mkdir -p`).
|
||||
|
||||
Launch the **architect-orchestrator** agent with this prompt:
|
||||
|
||||
```
|
||||
Brief file: {brief_path}
|
||||
Project dir: {project_dir}
|
||||
Architecture dir: {architecture_dir}
|
||||
Research briefs: {comma-separated research_paths, or "none"}
|
||||
Skill catalog root: ${CLAUDE_PLUGIN_ROOT}/skills/cc-architect-catalog
|
||||
Plugin root: ${CLAUDE_PLUGIN_ROOT}
|
||||
Mode: {default | quick}{, no-gaps if set}
|
||||
|
||||
Read the brief and every research brief. Execute your full workflow.
|
||||
Write overview.md to the architecture dir. Write gaps.md unless mode
|
||||
includes no-gaps.
|
||||
```
|
||||
|
||||
Launch via Agent-tool med `run_in_background: true`, `subagent_type:
|
||||
architect-orchestrator`.
|
||||
|
||||
Deretter output til bruker og **stopp ditt svar**:
|
||||
|
||||
```
|
||||
Background architecture run started via architect-orchestrator.
|
||||
|
||||
Project: {project_dir}
|
||||
Brief: {brief_path}
|
||||
Research: {N} briefs
|
||||
Output: {architecture_dir}/overview.md (+ gaps.md)
|
||||
|
||||
You will be notified when the architecture note is ready.
|
||||
You can continue working on other tasks in the meantime.
|
||||
```
|
||||
|
||||
Ikke vent på orchestratoren. Ikke fortsett til Phase 3.
|
||||
architect-orchestrator håndterer Phase 3–7 autonomt.
|
||||
|
||||
---
|
||||
|
||||
**Alt under denne linjen kjører enten i foreground-modus eller inne i
|
||||
background-agenten. Instruksjonene er identiske uavhengig av kontekst.**
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Read inputs and audit the catalog
|
||||
|
||||
Les briefen i sin helhet. Hent Intent, Goal, Non-Goals, Constraints,
|
||||
Preferences, NFRs, Success Criteria, Research Plan, Open Questions,
|
||||
Prior Attempts.
|
||||
|
||||
Les hver research-brief sitt Executive Summary + Recommendation
|
||||
(2–3 setninger per brief).
|
||||
|
||||
Les `${CLAUDE_PLUGIN_ROOT}/skills/cc-architect-catalog/SKILL.md` for å
|
||||
lære taxonomy og lag-modellen.
|
||||
|
||||
Glob `${CLAUDE_PLUGIN_ROOT}/skills/cc-architect-catalog/*.md`
|
||||
(unntatt `SKILL.md`). Hvis glob returnerer null filer: sett
|
||||
`catalog_empty = true` (ikke feil — `feature-matcher` har fallback).
|
||||
|
||||
Opprett `{architecture_dir}` hvis den ikke eksisterer.
|
||||
|
||||
## Phase 4 — Feature matching (parallel swarm)
|
||||
|
||||
Launch to agents i parallell, i én melding:
|
||||
|
||||
- **feature-matcher** (model: sonnet). Prompt med brief_path,
|
||||
research_paths, catalog_root, project_dir.
|
||||
- **gap-identifier** (model: sonnet). Samme input. Jobber uavhengig
|
||||
av feature-matcher (off briefen og katalogen direkte).
|
||||
|
||||
Pass konkrete filstier, ikke inlined content.
|
||||
|
||||
Etter begge returnerer:
|
||||
|
||||
- `fallback_used = true` hvis `catalog_empty` eller feature-matcher
|
||||
rapporterer det.
|
||||
- Trekk ut feature-liste, rationales, confidences, integration-noter
|
||||
fra feature-matcher.
|
||||
- Trekk ut gaps, out-of-scope, katalog-dekningsstats fra
|
||||
gap-identifier.
|
||||
|
||||
## Phase 5 — Synthesize architecture/overview.md
|
||||
|
||||
Skriv `{architecture_dir}/overview.md`.
|
||||
|
||||
**Frontmatter:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
task: <from brief>
|
||||
slug: <from brief>
|
||||
created: <ISO date>
|
||||
source_brief: <relative path to brief.md>
|
||||
source_research: [<list of relative research paths>]
|
||||
skills_consulted: [<list of skill `name` values>]
|
||||
cc_features_proposed: [<list of feature_id values>]
|
||||
review_status: pending
|
||||
---
|
||||
```
|
||||
|
||||
**Seks seksjoner i denne rekkefølgen:**
|
||||
|
||||
1. **Context** — 3 setninger. Paraphrase brief Intent + Goal.
|
||||
2. **Proposed CC features** — tabell: Feature | Rationale (brief
|
||||
anchor) | Supporting skill | Confidence. Én rad per foreslått
|
||||
feature. Behold primary/secondary/fallback-grupperingen som
|
||||
underseksjoner hvis feature-matcher leverte dem.
|
||||
3. **Feature composition** — hvordan features samspiller. Sekvens,
|
||||
konflikter, delte tilstander, fallbacks. 3–6 bullets.
|
||||
4. **Coverage gaps identified** — **ALLTID tilstede**, også når tom.
|
||||
Hvis tom, skriv "No coverage gaps identified — catalog covers all
|
||||
features this task requires." Hvis ikke-tom, oppsummer hver gap i
|
||||
én linje. Full issue-draft-tekst går til `gaps.md` i Phase 7 (med
|
||||
mindre `--no-gaps`).
|
||||
5. **Alternatives considered** — minst én alternativ feature-
|
||||
kombinasjon med grunn for avvisning. Rationale må referere
|
||||
briefen.
|
||||
6. **Open questions** — hva plan-fasen må avgjøre. Inkluder evt.
|
||||
uløste tradeoffs fra feature-matcher + briefens egne Open
|
||||
Questions.
|
||||
|
||||
## Phase 6 — Adversarial review
|
||||
|
||||
**Hvis mode = quick:** hopp over denne fasen. Sett
|
||||
`critic_verdict = "SKIPPED"` og `guardian_verdict = "SKIPPED"`.
|
||||
Fortsett til Phase 7.
|
||||
|
||||
Launch to reviewere i parallell:
|
||||
|
||||
- **architecture-critic** (model: sonnet). Input: overview.md,
|
||||
brief_path, research_paths, catalog_root.
|
||||
- **scope-guardian** (model: sonnet). Prompt **eksplisitt**: "The
|
||||
artifact under review is an architecture note (not an implementation
|
||||
plan). Verify that the proposed features align with brief
|
||||
requirements. Flag scope creep (features not justified by the brief)
|
||||
and scope gaps (brief requirements no proposed feature addresses)."
|
||||
|
||||
Håndter verdikter:
|
||||
|
||||
- **PASS + ALIGNED** — note ferdig. `review_status: approved`.
|
||||
- **REVISE** fra critic — revidér notatet i plass, adresser hver
|
||||
major finding. Re-launch architecture-critic én gang. Fortsatt
|
||||
REVISE → emit findings som `## Review notes`-seksjon nederst,
|
||||
fortsett. Ikke loop.
|
||||
- **BLOCK** fra critic — revidér for å fjerne blocker (typisk
|
||||
hallucinert feature eller manglende anchor). Re-launch én gang.
|
||||
Fortsatt BLOCK → `review_status: needs_rewrite`, surface findings
|
||||
i Open Questions.
|
||||
- **CREEP / GAP / MIXED** fra guardian — append `## Scope review`-
|
||||
subseksjon med funnene. Ikke re-synthesize med mindre combined med
|
||||
critic REVISE/BLOCK.
|
||||
|
||||
Oppdater `review_status` i frontmatter etter resultatet.
|
||||
|
||||
## Phase 7 — Present, write gaps.md, stats
|
||||
|
||||
**gaps.md** — skrives med mindre `--no-gaps`. Format:
|
||||
|
||||
```markdown
|
||||
# Coverage gaps — <task>
|
||||
|
||||
These are issue-ready drafts. Copy to the project's git host manually
|
||||
when you decide a gap warrants tracking. No auto-creation.
|
||||
|
||||
---
|
||||
|
||||
<gap 1 full draft>
|
||||
|
||||
---
|
||||
|
||||
<gap 2>
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
Zero gaps: skriv en-liner ("No coverage gaps identified.") slik at
|
||||
filstaten er deterministisk.
|
||||
|
||||
**Stats** — append én linje til
|
||||
`${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-local-stats.jsonl`:
|
||||
|
||||
```json
|
||||
{
|
||||
"ts": "<ISO-8601>",
|
||||
"task": "<brief task, first 100 chars>",
|
||||
"mode": "<default|quick|no-gaps|quick+no-gaps|foreground|foreground+quick|...>",
|
||||
"slug": "<from brief>",
|
||||
"project_dir": "<project_dir>",
|
||||
"architecture_path": "<architecture_dir>/overview.md",
|
||||
"gaps_path": "<architecture_dir>/gaps.md | null>",
|
||||
"skills_catalog_size": <N>,
|
||||
"skills_consulted": <N>,
|
||||
"features_proposed": <N>,
|
||||
"gaps_identified": <N>,
|
||||
"critic_verdict": "<PASS|REVISE|BLOCK|SKIPPED>",
|
||||
"guardian_verdict": "<ALIGNED|CREEP|GAP|MIXED|SKIPPED>",
|
||||
"fallback_used": <true|false>
|
||||
}
|
||||
```
|
||||
|
||||
Hvis `${CLAUDE_PLUGIN_DATA}` ikke er satt eller ikke skrivbar, skip
|
||||
stats silently.
|
||||
|
||||
**Summary til brukeren:**
|
||||
|
||||
```
|
||||
## Ultra-CC-Architect Complete
|
||||
|
||||
**Task:** <task>
|
||||
**Project:** <project_dir>
|
||||
**Architecture note:** <architecture_dir>/overview.md
|
||||
**Gaps draft:** <architecture_dir>/gaps.md | skipped (--no-gaps)
|
||||
**Features proposed:** N (primary: N, secondary: N, fallback: N)
|
||||
**Gaps identified:** N
|
||||
**Review:** <critic_verdict> / <guardian_verdict>
|
||||
|
||||
### Primary features
|
||||
- <feature 1>: <one-line rationale>
|
||||
- <feature 2>: ...
|
||||
|
||||
### Top gaps (if any)
|
||||
- <gap 1>
|
||||
- <gap 2>
|
||||
|
||||
Next step: /ultraplan-local --project <project_dir>
|
||||
(the architecture note is auto-discovered as extra context)
|
||||
```
|
||||
|
||||
## Hard rules
|
||||
|
||||
- **Catalog is ground truth.** Hver foreslått feature må komme fra
|
||||
katalogens `cc_feature`-taxonomy eller feature-matcher's dokumenterte
|
||||
fallback-liste. `architecture-critic` blokkerer hallucinated
|
||||
features.
|
||||
- **Brief is anchor.** Hver foreslått feature må sitere en konkret
|
||||
brief-seksjon (Intent/Goal/Constraint/NFR/Success Criterion). Features
|
||||
uten anchor fjernes under review.
|
||||
- **Gap ≠ error.** "Coverage gaps identified"-seksjonen er **alltid**
|
||||
til stede — tom eller full. Brief §4.5 ("Mangel ≠ feil").
|
||||
- **No auto-issue-creation.** Gaps er drafts i `gaps.md`. Brukeren
|
||||
avgjør hva som postes.
|
||||
- **Sonnet for sub-agents.** Opus kun for orchestrator og hoved-
|
||||
kommandoen.
|
||||
- **Privacy.** Aldri logg secrets, tokens, credentials fra brief,
|
||||
research eller katalog.
|
||||
- **Idempotent.** Re-kjøring overskriver `overview.md` og `gaps.md`.
|
||||
Stats-linjene akkumuleres.
|
||||
- **Graceful degradation.** Tom katalog → fallback-liste. Manglende
|
||||
research → jobb kun fra brief. Partial brief → noter i Open
|
||||
Questions.
|
||||
- **Additiv i pipeline.** `/ultraplan-local` oppdager overview.md
|
||||
automatisk men må fungere uendret om filen mangler.
|
||||
- **No third-party content copied** (brief §4.4). Seed-skills er
|
||||
håndskrevet. Fremtidig skill-factory-output håndterer IP-hygiene
|
||||
separat.
|
||||
- **No n-gram computation here.** Feltet `ngram_overlap_score`
|
||||
respekteres (ikke-null > threshold → flagge), men beregnes av
|
||||
skill-factory, ikke denne kommandoen.
|
||||
|
|
@ -62,6 +62,10 @@ Parse `$ARGUMENTS` for mode flags. Order of precedence:
|
|||
```
|
||||
- Set **project_dir = {dir}**, **brief_path = {dir}/brief.md**.
|
||||
- Set **has_research_brief = true** if `{dir}/research/*.md` matches ≥ 1 file.
|
||||
- Set **has_architecture_note = true** if `{dir}/architecture/overview.md` exists.
|
||||
If set, **architecture_note_path = {dir}/architecture/overview.md**. Produced by
|
||||
the optional `/ultra-cc-architect-local` command. Missing file is fine — this is
|
||||
additive discovery, not a requirement.
|
||||
|
||||
4. **`--brief <path>`** — extract the brief path. If the file does not exist:
|
||||
```
|
||||
|
|
@ -323,9 +327,12 @@ Mode: {default | quick}
|
|||
Plan destination: {plan destination}
|
||||
Plugin root: ${CLAUDE_PLUGIN_ROOT}
|
||||
Research briefs: {comma-separated list, or "none"}
|
||||
Architecture note: {architecture_note_path or "none"}
|
||||
|
||||
Read the brief file and every research brief. Execute your full planning
|
||||
workflow. Write the plan to the destination path.
|
||||
Read the brief file and every research brief. If an architecture note is
|
||||
provided, read it before launching exploration agents and treat its feature
|
||||
proposals as priors (not mandates) — exploration may override with evidence.
|
||||
Execute your full planning workflow. Write the plan to the destination path.
|
||||
```
|
||||
|
||||
Launch the planning-orchestrator via the Agent tool with `run_in_background: true`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue