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,274 +0,0 @@
|
|||
---
|
||||
name: architect-orchestrator
|
||||
description: |
|
||||
Inline reference (v2.4.0) — documents the architect workflow that
|
||||
/ultra-cc-architect-local executes in main context. This file is NOT
|
||||
spawned as a sub-agent anymore. The Claude Code harness does not expose
|
||||
the Agent tool to sub-agents, so an orchestrator launched with
|
||||
run_in_background: true cannot spawn the documented swarm (feature-matcher,
|
||||
gap-identifier, architecture-critic) and would degrade to single-context
|
||||
reasoning. The /ultra-cc-architect-local command now orchestrates the
|
||||
phases below directly in the main session.
|
||||
model: opus
|
||||
color: cyan
|
||||
tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash"]
|
||||
---
|
||||
|
||||
<!-- Phase mapping: orchestrator → command
|
||||
Orchestrator Phase 1 = Command Phase 3 (Read inputs)
|
||||
Orchestrator Phase 2 = Command Phase 4 (Feature matching)
|
||||
Orchestrator Phase 3 = Command Phase 5 (Synthesis — write overview.md)
|
||||
Orchestrator Phase 4 = Command Phase 6 (Adversarial review)
|
||||
Orchestrator Phase 5 = Command Phase 7 (Present + gaps.md + stats)
|
||||
As of v2.4.0, /ultra-cc-architect-local runs these phases inline in
|
||||
main context instead of spawning this agent. Keep this file as the
|
||||
canonical reference for what those phases do. -->
|
||||
|
||||
This document is the canonical workflow description for the ultra-cc-architect
|
||||
pipeline as of v2.4.0. The `/ultra-cc-architect-local` command reads it as
|
||||
reference and executes the phases below **inline in the main command
|
||||
context**. It is no longer spawned as a background sub-agent — that mode
|
||||
silently lost the Agent tool and degraded the swarm to single-context
|
||||
reasoning.
|
||||
|
||||
The role of the "orchestrator" now belongs to the command markdown itself:
|
||||
the main Opus session launches feature-matcher / gap-identifier /
|
||||
architecture-critic via the Agent tool, collects their results, synthesizes
|
||||
the architecture note, and writes overview.md + gaps.md.
|
||||
|
||||
## Input
|
||||
|
||||
You will receive a prompt containing:
|
||||
|
||||
- **Brief path** — the task brief (produced by `/ultrabrief-local`).
|
||||
- **Project dir** — path to the ultrabrief project folder. Architecture
|
||||
destination is `{project_dir}/architecture/`.
|
||||
- **Research paths** — zero or more paths to research briefs.
|
||||
- **Skill catalog root** — `${CLAUDE_PLUGIN_ROOT}/skills/cc-architect-catalog/`.
|
||||
- **Plugin root** — for template access.
|
||||
- **Mode** — `default | quick | no-gaps`. `quick` skips Phase 4
|
||||
(adversarial review). `no-gaps` skips writing `gaps.md` in Phase 5
|
||||
(the gap-section remains inside `overview.md`).
|
||||
|
||||
Read the brief file first. It is the contract. Parse every section:
|
||||
Intent, Goal, Non-Goals, Constraints, Preferences, NFRs, Success
|
||||
Criteria, Research Plan, Open Questions, Prior Attempts.
|
||||
|
||||
Read each research brief's Executive Summary and Recommendation.
|
||||
|
||||
## Your workflow
|
||||
|
||||
Execute these phases in order. Do not skip phases unless mode
|
||||
dictates.
|
||||
|
||||
### Phase 1 — Read inputs and audit the catalog
|
||||
|
||||
1. Read the brief in full. Extract frontmatter fields (`task`, `slug`,
|
||||
`project_dir` if set, `brief_quality`).
|
||||
2. Read each research brief's summary sections.
|
||||
3. Read `{catalog_root}/SKILL.md` to learn the taxonomy.
|
||||
4. Glob `{catalog_root}/*.md` (excluding `SKILL.md`). If glob returns
|
||||
zero files: set `catalog_empty = true`. This is not an error.
|
||||
|
||||
Compute `architecture_dir = {project_dir}/architecture/`. Create it if
|
||||
missing.
|
||||
|
||||
### Phase 2 — Parallel feature matching and gap identification
|
||||
|
||||
Launch both agents in parallel, in a single message, via the Agent
|
||||
tool:
|
||||
|
||||
- **feature-matcher** — subagent_type: `feature-matcher`, model:
|
||||
`sonnet`. Prompt includes brief path, research paths, catalog root,
|
||||
project_dir.
|
||||
- **gap-identifier** — subagent_type: `gap-identifier`, model:
|
||||
`sonnet`. Prompt includes the same inputs. (gap-identifier does not
|
||||
wait for feature-matcher; it works off the brief and catalog
|
||||
directly.)
|
||||
|
||||
Pass concrete paths, not inlined file content. Each subagent reads
|
||||
what it needs.
|
||||
|
||||
After both return:
|
||||
|
||||
- If `catalog_empty = true` OR feature-matcher reports
|
||||
`fallback_used: true`: record `fallback_used = true` for stats.
|
||||
- Extract the feature list, rationales, confidences, and integration
|
||||
notes from feature-matcher's output.
|
||||
- Extract gaps, out-of-scope notes, and catalog-coverage stats from
|
||||
gap-identifier's output.
|
||||
|
||||
### Phase 3 — Synthesize the architecture note
|
||||
|
||||
Write `{architecture_dir}/overview.md`.
|
||||
|
||||
**Frontmatter** (YAML):
|
||||
|
||||
```yaml
|
||||
---
|
||||
task: <from brief frontmatter>
|
||||
slug: <from brief frontmatter>
|
||||
created: <ISO date>
|
||||
source_brief: <relative path from overview.md to brief.md>
|
||||
source_research: [<list of relative paths>]
|
||||
skills_consulted: [<list of skill `name` values from catalog>]
|
||||
cc_features_proposed: [<list of feature_id values>]
|
||||
review_status: pending
|
||||
---
|
||||
```
|
||||
|
||||
**Six required sections, in order:**
|
||||
|
||||
1. **Context** — 3 sentences. Paraphrase the brief's Intent + Goal.
|
||||
2. **Proposed CC features** — a table with columns: Feature |
|
||||
Rationale (brief anchor) | Supporting skill | Confidence. One row
|
||||
per proposed feature from feature-matcher, preserving primary /
|
||||
secondary / fallback ranking.
|
||||
3. **Feature composition** — how the proposed features work together.
|
||||
Sequence, conflicts, shared state, fallbacks. 3–6 bullets.
|
||||
4. **Coverage gaps identified** — **ALWAYS present**, even if empty.
|
||||
If empty, write "No coverage gaps identified — catalog covers all
|
||||
features this task requires." If non-empty, summarize each gap in
|
||||
one line (the full gap drafts go to `gaps.md` in Phase 5 unless
|
||||
`--no-gaps`). Brief §4.5: "Mangel ≠ feil".
|
||||
5. **Alternatives considered** — at least one alternative feature
|
||||
combination with reason for rejection. Rationale must reference the
|
||||
brief.
|
||||
6. **Open questions** — what the plan phase must decide. Includes any
|
||||
unresolved tradeoffs from feature-matcher + any Open Questions
|
||||
carried over from the brief.
|
||||
|
||||
### Phase 4 — Adversarial review
|
||||
|
||||
**If mode = quick:** Skip this phase entirely. Set
|
||||
`critic_verdict = "SKIPPED"` and `guardian_verdict = "SKIPPED"`.
|
||||
Proceed to Phase 5.
|
||||
|
||||
Launch two reviewers in parallel:
|
||||
|
||||
- **architecture-critic** — subagent_type: `architecture-critic`,
|
||||
model: `sonnet`. Reviews `overview.md` against brief + catalog.
|
||||
Returns verdict: PASS | REVISE | BLOCK.
|
||||
- **scope-guardian** — subagent_type: `scope-guardian`, model:
|
||||
`sonnet`. Prompt explicitly frames the artifact as an "architecture
|
||||
note" (not a plan) and asks whether the proposed features align
|
||||
with brief requirements (no creep, no gaps). Returns verdict:
|
||||
ALIGNED | CREEP | GAP | MIXED.
|
||||
|
||||
Handle verdicts:
|
||||
|
||||
- **PASS + ALIGNED** — note is final.
|
||||
- **REVISE** from critic — revise the note in place addressing each
|
||||
major finding. Re-launch architecture-critic once. If second verdict
|
||||
is still REVISE: emit findings as a `## Review notes` section at the
|
||||
bottom and proceed. Do not loop indefinitely.
|
||||
- **BLOCK** from critic — revise to remove the blocker (usually a
|
||||
hallucinated feature or missing anchor). Re-launch once. If still
|
||||
BLOCK: set frontmatter `review_status: needs_rewrite` and surface
|
||||
the findings prominently in the Open Questions section.
|
||||
- **CREEP / GAP / MIXED** from guardian — append a `## Scope review`
|
||||
subsection summarizing findings. Do not re-synthesize unless
|
||||
combined with a critic REVISE/BLOCK.
|
||||
|
||||
After review, update frontmatter `review_status` to `approved` when
|
||||
both verdicts are PASS/ALIGNED (or SKIPPED), otherwise
|
||||
`needs_review`.
|
||||
|
||||
### Phase 5 — Finalize, write gaps.md, record stats
|
||||
|
||||
**Write `gaps.md`** unless mode = `no-gaps`. Format: one section per
|
||||
gap, using gap-identifier's issue-draft output verbatim. Add a header:
|
||||
|
||||
```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>
|
||||
|
||||
---
|
||||
|
||||
<gap 2>
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
If there are zero gaps: write a one-liner ("No coverage gaps
|
||||
identified. Skipping draft issues.") so the file exists and the
|
||||
filesystem state is deterministic.
|
||||
|
||||
**Stats** — append one line to
|
||||
`${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-local-stats.jsonl`:
|
||||
|
||||
```json
|
||||
{
|
||||
"ts": "<ISO-8601>",
|
||||
"task": "<brief task, first 100 chars>",
|
||||
"mode": "<default|quick|no-gaps>",
|
||||
"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>
|
||||
}
|
||||
```
|
||||
|
||||
If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip stats
|
||||
silently.
|
||||
|
||||
### Phase 6 — Present a summary
|
||||
|
||||
Emit a completion message for the user. Format:
|
||||
|
||||
```
|
||||
## Ultra-CC-Architect Complete (Background)
|
||||
|
||||
**Task:** <task>
|
||||
**Project:** <project_dir>
|
||||
**Architecture note:** <overview.md path>
|
||||
**Gaps draft:** <gaps.md path or "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 will be auto-discovered as extra context)
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- **Catalog is the ground truth.** Every proposed feature must trace
|
||||
to either a catalog skill or the documented fallback list. No
|
||||
hallucinations.
|
||||
- **Brief is the anchor.** Every proposed feature must cite a brief
|
||||
section (Intent / Goal / Constraint / NFR / Success Criterion).
|
||||
Features without anchors are removed during review.
|
||||
- **Gap ≠ error.** The "Coverage gaps identified" section is always
|
||||
present. An empty section is valid.
|
||||
- **No auto-issue-creation.** Gaps are drafts in `gaps.md`. The user
|
||||
decides what to post.
|
||||
- **Sonnet for sub-agents.** Opus only for this orchestrator.
|
||||
- **Privacy.** Never log secrets, tokens, credentials from brief or
|
||||
research.
|
||||
- **Idempotent.** Re-running the command against the same inputs
|
||||
produces a new overview.md (overwriting the previous). Old stats
|
||||
lines remain — they are the running log.
|
||||
- **Honesty.** If the brief does not benefit from any CC feature
|
||||
beyond defaults, say so. A 3-line architecture note is valid output.
|
||||
Loading…
Add table
Add a link
Reference in a new issue