docs(ultraplan-local): complete external-architect doc rydding [skip-docs]

D2 of post-v3.4.1 stabilisering. Removes 14 plugin-name references from
agents/, commands/, and docs/ tracked files (CLAUDE.md/README.md/SECURITY.md
were ryddet in v3.4.1 commit 6bca3fb).

The external architect plugin was moved out of the public marketplace
2026-05-04 due to ToS concerns around future skill sources. References in
prose are now stale or misleading for public users. The architecture/overview.md
filesystem slot remains available for any compatible producer — discovery
is plugin-agnostic via lib/validators/architecture-discovery.mjs (drift-WARN,
never drift-FAIL).

Files:
- agents/planning-orchestrator.md (1 ref generalized)
- commands/ultraplan-local.md (2 refs generalized; missed by prompt inventory)
- docs/HANDOVER-CONTRACTS.md (4 refs generalized; Handover 3 + stability summary)
- docs/architect-bridge-test.md (deleted; was a public-only bridge checklist)
- docs/subagent-delegation-audit.md (5 refs/rows removed; intervention #5 dropped, recommendation adjusted)

CHANGELOG.md retains historical references (20 occurrences) intentionally.

Verification:
- grep tracked non-CHANGELOG md: 0 references remaining
- npm test: 361/361 pass (baseline preserved)
This commit is contained in:
Kjell Tore Guttormsen 2026-05-05 10:46:29 +02:00
commit 4aac89ca11
5 changed files with 13 additions and 64 deletions

View file

@ -53,7 +53,8 @@ You will receive a prompt containing:
auto-discovered `{project_dir}/research/*.md` files and any explicit briefs
passed via `--research`. Read each brief before launching exploration agents.
- **Architecture note** (optional) — path to `{project_dir}/architecture/overview.md`
produced by the optional `/ultra-cc-architect-local` command. When provided,
produced by an external opt-in architect plugin (no longer publicly distributed;
the filesystem slot remains available for any compatible producer). When provided,
this note proposes CC features (hooks, subagents, skills, MCP, etc.) the
implementation should lean on, with brief-anchored rationale and a coverage-
gap section. Missing file is fine — this is additive context, not a

View file

@ -80,8 +80,9 @@ Parse `$ARGUMENTS` for mode flags. Order of precedence:
if `found == true`. The discovery module emits warnings if the file lives at a
non-canonical path (e.g. `architecture-overview.md`); preserve them for the
user-facing summary. If set, **architecture_note_path = {result.overview}**.
Produced by the optional `/ultra-cc-architect-local` command from the separate
`ultra-cc-architect` plugin. Missing file is fine — additive discovery, not required.
Produced by an external opt-in architect plugin (no longer publicly distributed;
the filesystem slot remains available for any compatible producer). Missing file
is fine — additive discovery, not required.
4. **`--brief <path>`** — extract the brief path. If the file does not exist:
```

View file

@ -141,9 +141,9 @@ Optional: `## Local Context`, `## External Knowledge`, `## Triangulation`, `## S
## Handover 3 — architecture/ → plan (EXTERNAL CONTRACT)
**This is the only handover where the producer is in a *different plugin*.** The `architecture/overview.md` (and optional `gaps.md`) are produced by `/ultra-cc-architect-local` from the separate `ultra-cc-architect` plugin (v0.1.0+). When that plugin is not installed, this handover is absent — and that is fine.
**This is the only handover where the producer is in a *different plugin*.** The `architecture/overview.md` (and optional `gaps.md`) are produced by an external opt-in architect plugin (no longer publicly distributed; the filesystem slot remains available for any compatible producer). When no producer is installed, this handover is absent — and that is fine.
**Producer:** `/ultra-cc-architect-local` (external plugin).
**Producer:** external opt-in architect plugin (no longer publicly distributed).
**Consumer:** `/ultraplan-local` Phase 1 (architecture-discovery) + `planning-orchestrator` Phase 7 (cross-reference architecture-note as priors during synthesis).
@ -165,9 +165,9 @@ Optional: `## Local Context`, `## External Knowledge`, `## Triangulation`, `## S
| Loose `*.md` files in `architecture/` not in known set | warning `ARCH_LOOSE_FILES` |
| No `architecture/` dir | `found: false`, no warnings |
The validator (`lib/validators/architecture-discovery.mjs`) is intentionally minimal. It is unit-tested to assert it does NOT read body content beyond the first heading — guarding against scope creep into the sister plugin's territory.
The validator (`lib/validators/architecture-discovery.mjs`) is intentionally minimal. It is unit-tested to assert it does NOT read body content beyond the first heading — guarding against scope creep into the producer's territory.
**Versioning:** the producer (`ultra-cc-architect`) owns its schema. We do not version this handover from our side.
**Versioning:** the external producer owns its schema. We do not version this handover from our side.
**Failure modes:** none. Discovery always succeeds (returns `found: false` if absent). The handover is additive.
@ -444,7 +444,7 @@ The `next-session-prompt-validator` (`lib/validators/next-session-prompt-validat
|---|---|---|---|
| 1. brief → research | strict at write, soft at read | this plugin | low |
| 2. research → plan | soft, drift-warn | this plugin | low |
| 3. architecture → plan | discovery-only, drift-WARN | **external** (ultra-cc-architect) | low — by design we tolerate drift |
| 3. architecture → plan | discovery-only, drift-WARN | **external** (opt-in architect plugin, not bundled) | low — by design we tolerate drift |
| 4. plan → execute | **strict, both ends** | this plugin | medium — Opus 4.7 narrative drift requires constant vigilance |
| 5. progress.json | shape + resume readiness | this plugin | medium — drift during compaction handled by pre-compact-flush hook (CC v2.1.105+) |
| 6. review → plan | strict at write, soft at read | this plugin | low — additive feedback loop; consumer falls back gracefully when source_findings is absent |

View file

@ -1,46 +0,0 @@
# Architect-bridge smoke test
`ultra-cc-architect` is a separate plugin (extracted in v3.0.0). This
plugin auto-discovers `architecture/overview.md` if produced. This
checklist verifies the bridge still works after either plugin changes.
## Manual checklist
1. Install both plugins from the marketplace.
2. Create a project: `/ultrabrief-local` → produce `brief.md` for a small
task ("add --verbose flag to a CLI").
3. Run `/ultra-cc-architect-local --project <project-dir>`. Verify
`architecture/overview.md` and `architecture/gaps.md` appear.
4. Run `/ultraplan-local --project <project-dir>`. Verify the planner's
Phase 1 output mentions architecture-discovery as one of the inputs
(look for `architecture/overview.md` in the validator log).
5. Open the resulting `plan.md`. The plan should reference
`cc_features_proposed` from the architecture note when it picks
features. The plan does **not** have to adopt them — they are priors,
not requirements.
## What "works" means
- Discovery finds `architecture/overview.md` (or any of the tolerated
loose names: `architecture-overview.md`, etc.) and surfaces drift as
warnings only.
- Plan synthesis cross-references the architecture note without
hard-failing if it is missing.
- No CI test enforces the bridge; that is intentional. The two plugins
are filesystem-coupled, not code-coupled.
## When to re-run
- After bumping either plugin's minor or major version.
- After changing `lib/validators/architecture-discovery.mjs` in this
plugin.
- After changing the architecture-note schema in `ultra-cc-architect`.
## Known tolerances
| Drift | Behavior |
|-------|----------|
| Missing `architecture/` directory | Discovery returns absent; plan proceeds without architecture input |
| Loose name (e.g., `architecture-overview.md` at project root) | WARN; discovery still finds it |
| Body schema changed | WARN; discovery only reads the first heading |
| `cc_features_proposed` missing | Plan ignores priors silently; no error |

View file

@ -23,7 +23,6 @@ Agent-spawn density per command (nominal):
|--------------------------|-------------------------------------------------------------------|
| ultraresearch-local | ~914 (5 local + 4 external + 1 bridge + up to 2 follow-ups) |
| ultraplan-local | ~10 (6 initial + conditional research-scout + up to 3 deep-dives) |
| ultra-cc-architect-local | 4 (feature-matcher, gap-identifier, critic, scope-guardian) |
| ultrabrief-local | 13 (brief-reviewer per iteration, max 3) |
| ultraexecute-local | 0 (explicit no-agent rule) |
| ultra-skill-author-local | 3 (concept-extractor → skill-drafter → ip-hygiene-checker) |
@ -51,16 +50,11 @@ The main context does the heavy cognitive work after swarm completion:
- **`commands/ultraresearch-local.md:325341` (Phase 7 Synthesis):**
Writes the research brief inline using the template.
- **`commands/ultra-cc-architect-local.md:181+` (Phase 5 Synthesize):**
Writes overview.md (6 sections + YAML frontmatter) inline from brief +
research + catalog + feature-matcher output.
### 3. Root cause — v2.4.0 foreground migration
Each command carries a `> **Why foreground?**` block
(`ultraplan-local.md:330`, `ultraresearch-local.md:192`,
`ultra-cc-architect-local.md:127`) documenting that the background
orchestrators were removed because agents spawned from background
(`ultraplan-local.md:330`, `ultraresearch-local.md:192`) documenting that the
background orchestrators were removed because agents spawned from background
orchestrators silently degraded. The swarm-spawn logic was lifted into the
main context — but so was the synthesis logic the orchestrators used to
carry. The "summarizer" link is missing.
@ -76,7 +70,6 @@ are rough estimates based on the size of the phase bodies — not measured.
| 2 | `plan-writer-agent` — writes plan.md from synthesis + template | ultraplan Phase 8 | part of #1 |
| 3 | `triangulation-synthesizer` — per-dimension local vs external diff + confidence rating | ultraresearch Phase 6 | 2530% |
| 4 | `research-brief-writer` — writes research brief from triangulation output | ultraresearch Phase 7 | part of #3 |
| 5 | `architecture-writer` — writes overview.md from matcher + gap output | ultra-cc-architect Phase 5 | 1520% |
## Tradeoffs (important)
@ -110,7 +103,7 @@ ultraplan Phase 7)** has the largest ROI. It isolates the heaviest read
findings document — is small enough to keep resident for Phase 8 planning
and Phase 9 review.
Interventions #3 and #5 are smaller-scope and lower-risk proofs-of-concept
Intervention #3 is a smaller-scope and lower-risk proof-of-concept
that could validate the pattern before touching the main planner.
## Open questions