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 auto-discovered `{project_dir}/research/*.md` files and any explicit briefs
passed via `--research`. Read each brief before launching exploration agents. passed via `--research`. Read each brief before launching exploration agents.
- **Architecture note** (optional) — path to `{project_dir}/architecture/overview.md` - **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 this note proposes CC features (hooks, subagents, skills, MCP, etc.) the
implementation should lean on, with brief-anchored rationale and a coverage- implementation should lean on, with brief-anchored rationale and a coverage-
gap section. Missing file is fine — this is additive context, not a 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 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 non-canonical path (e.g. `architecture-overview.md`); preserve them for the
user-facing summary. If set, **architecture_note_path = {result.overview}**. user-facing summary. If set, **architecture_note_path = {result.overview}**.
Produced by the optional `/ultra-cc-architect-local` command from the separate Produced by an external opt-in architect plugin (no longer publicly distributed;
`ultra-cc-architect` plugin. Missing file is fine — additive discovery, not required. 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: 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) ## 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). **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` | | Loose `*.md` files in `architecture/` not in known set | warning `ARCH_LOOSE_FILES` |
| No `architecture/` dir | `found: false`, no warnings | | 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. **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 | | 1. brief → research | strict at write, soft at read | this plugin | low |
| 2. research → plan | soft, drift-warn | 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 | | 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+) | | 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 | | 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) | | 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) | | 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) | | ultrabrief-local | 13 (brief-reviewer per iteration, max 3) |
| ultraexecute-local | 0 (explicit no-agent rule) | | ultraexecute-local | 0 (explicit no-agent rule) |
| ultra-skill-author-local | 3 (concept-extractor → skill-drafter → ip-hygiene-checker) | | 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):** - **`commands/ultraresearch-local.md:325341` (Phase 7 Synthesis):**
Writes the research brief inline using the template. 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 ### 3. Root cause — v2.4.0 foreground migration
Each command carries a `> **Why foreground?**` block Each command carries a `> **Why foreground?**` block
(`ultraplan-local.md:330`, `ultraresearch-local.md:192`, (`ultraplan-local.md:330`, `ultraresearch-local.md:192`) documenting that the
`ultra-cc-architect-local.md:127`) documenting that the background background orchestrators were removed because agents spawned from background
orchestrators were removed because agents spawned from background
orchestrators silently degraded. The swarm-spawn logic was lifted into the orchestrators silently degraded. The swarm-spawn logic was lifted into the
main context — but so was the synthesis logic the orchestrators used to main context — but so was the synthesis logic the orchestrators used to
carry. The "summarizer" link is missing. 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 | | 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% | | 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 | | 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) ## 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 findings document — is small enough to keep resident for Phase 8 planning
and Phase 9 review. 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. that could validate the pattern before touching the main planner.
## Open questions ## Open questions