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:
parent
f339437e6d
commit
4aac89ca11
5 changed files with 13 additions and 64 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
@ -23,7 +23,6 @@ Agent-spawn density per command (nominal):
|
|||
|--------------------------|-------------------------------------------------------------------|
|
||||
| ultraresearch-local | ~9–14 (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 | 1–3 (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:325–341` (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 | 25–30% |
|
||||
| 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 | 15–20% |
|
||||
|
||||
## 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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue