diff --git a/plugins/ultraplan-local/CHANGELOG.md b/plugins/ultraplan-local/CHANGELOG.md index 657cb5e..0dd7fcf 100644 --- a/plugins/ultraplan-local/CHANGELOG.md +++ b/plugins/ultraplan-local/CHANGELOG.md @@ -237,6 +237,8 @@ This release is plugin-internal — no breaking changes to artifact formats or C ## [3.0.0] - 2026-04-30 +_Note (2026-05-04): the ultra-cc-architect plugin is no longer publicly distributed. The architecture/overview.md filesystem contract remains supported but no public producer ships._ + ### Architect extracted to its own plugin The `/ultra-cc-architect-local` and `/ultra-skill-author-local` commands, all diff --git a/plugins/ultraplan-local/CLAUDE.md b/plugins/ultraplan-local/CLAUDE.md index 4528f25..78e96b6 100644 --- a/plugins/ultraplan-local/CLAUDE.md +++ b/plugins/ultraplan-local/CLAUDE.md @@ -4,7 +4,7 @@ Deep implementation planning and research with an explicit brief step, specializ **Design principle: Context Engineering** — build the right context by orchestrating specialized agents. Each step in the pipeline (brief → research → plan → execute) produces a structured artifact that the next step consumes. -> **v3.0.0 — architect extracted to separate plugin.** `/ultra-cc-architect-local` and `/ultra-skill-author-local` were moved to the `ultra-cc-architect` plugin (v0.1.0). The plan command still auto-discovers `architecture/overview.md` if present, so installing both plugins gives you the full five-stage flow. See [CHANGELOG.md](CHANGELOG.md) for migration steps. +> **v3.0.0 — architect step extracted from this plugin.** The plan command still auto-discovers `architecture/overview.md` if present, so any compatible producer (architect plugin no longer publicly distributed; the architecture/overview.md slot remains available for any compatible producer) plugs into the same slot. See [CHANGELOG.md](CHANGELOG.md) for migration history. ## Commands @@ -56,7 +56,7 @@ Flags combine: `--project --local`, `--external --quick`. **Breaking change (v2.0):** one of `--brief` or `--project` is required. There is no interview inside `/ultraplan-local`. The `--spec` flag has been removed — use `/ultrabrief-local` to produce a brief instead. -If `{project_dir}/architecture/overview.md` exists (typically produced by the separate `ultra-cc-architect` plugin), the plan command auto-discovers it and treats `cc_features_proposed` as priors. Missing file is fine — discovery is additive, not required. +If `{project_dir}/architecture/overview.md` exists (typically produced by an opt-in upstream architect plugin, not bundled), the plan command auto-discovers it and treats `cc_features_proposed` as priors. Missing file is fine — discovery is additive, not required. ### /ultraexecute-local modes @@ -173,7 +173,7 @@ Path C migration would require: (1) re-architecting tool-list to be identical ac **Research:** Foreground workflow (v2.4.0): Parse mode → Interview → Parallel research swarm (5 local + 4 external + 1 bridge, spawned from main context) → Follow-ups → Triangulation → Synthesis + brief → Stats. With `--project`, writes to `{dir}/research/NN-slug.md`. -**Plan:** Foreground workflow (v2.4.0): Parse mode (validate brief input) → Codebase sizing → Brief review (`brief-reviewer`) → Parallel exploration (6-8 agents, spawned from main context) → Deep-dives → Synthesis (with architecture-note cross-reference if present) → Planning → Adversarial review (`plan-critic` + `scope-guardian`) → Present/refine → Handoff. With `--project`, writes to `{dir}/plan.md` and auto-detects `{dir}/architecture/overview.md` (produced by the separate `ultra-cc-architect` plugin if installed). +**Plan:** Foreground workflow (v2.4.0): Parse mode (validate brief input) → Codebase sizing → Brief review (`brief-reviewer`) → Parallel exploration (6-8 agents, spawned from main context) → Deep-dives → Synthesis (with architecture-note cross-reference if present) → Planning → Adversarial review (`plan-critic` + `scope-guardian`) → Present/refine → Handoff. With `--project`, writes to `{dir}/plan.md` and auto-detects `{dir}/architecture/overview.md` (produced by an opt-in upstream architect plugin if installed; not bundled). **Decompose:** Parse plan → Analyze step dependencies → Group into sessions → Identify parallel waves → Generate session specs + dependency graph + launch script. @@ -183,15 +183,15 @@ Path C migration would require: (1) re-architecting tool-list to be identical ac **Security:** 4-layer defense-in-depth: plugin hooks (pre-bash-executor, pre-write-executor), prompt-level denylist (works in headless sessions), pre-execution plan scan (Phase 2.4), scoped `--allowedTools` replacing `--dangerously-skip-permissions`. Hard Rules 14-16 enforce verify command security, repo-boundary writes, and sensitive path protection. -**Pipeline:** `/ultrabrief-local` produces the task brief. `/ultraresearch-local --project ` fills in `{dir}/research/`. `/ultraplan-local --project ` reads brief + research to produce `{dir}/plan.md` (and auto-discovers `{dir}/architecture/overview.md` if the separate `ultra-cc-architect` plugin produced one). `/ultraexecute-local --project ` executes and writes `{dir}/progress.json`. All artifacts live in one project directory. +**Pipeline:** `/ultrabrief-local` produces the task brief. `/ultraresearch-local --project ` fills in `{dir}/research/`. `/ultraplan-local --project ` reads brief + research to produce `{dir}/plan.md` (and auto-discovers `{dir}/architecture/overview.md` if an opt-in upstream architect plugin produced one). `/ultraexecute-local --project ` executes and writes `{dir}/progress.json`. All artifacts live in one project directory. -**Project-directory contract (v3.0.0):** ultraplan-local owns the directory layout below. The `architecture/` subdirectory is opt-in and produced by the separate `ultra-cc-architect` plugin — install that plugin to participate in the architect step. +**Project-directory contract (v3.0.0):** ultraplan-local owns the directory layout below. The `architecture/` subdirectory is opt-in and produced by an opt-in upstream architect plugin (not bundled) — the architect plugin is no longer publicly distributed, but the `architecture/overview.md` slot remains available for any compatible producer. ``` .claude/projects/{YYYY-MM-DD}-{slug}/ brief.md ← ultrabrief-local writes; everyone reads research/*.md ← ultraresearch-local writes; plan + architect read - architecture/ ← OPT-IN, owned by ultra-cc-architect plugin + architecture/ ← OPT-IN, owned by an opt-in upstream architect plugin (not bundled) overview.md gaps.md plan.md ← ultraplan-local writes; ultraexecute reads @@ -206,7 +206,7 @@ All artifacts in one project directory (default): - Project root: `.claude/projects/{YYYY-MM-DD}-{slug}/` - `brief.md` (task brief from `/ultrabrief-local`) - `research/{NN}-{slug}.md` (research briefs from `/ultraresearch-local --project`) - - `architecture/overview.md` + `architecture/gaps.md` (opt-in, produced by the separate `ultra-cc-architect` plugin) + - `architecture/overview.md` + `architecture/gaps.md` (opt-in, produced by an opt-in upstream architect plugin, not bundled) - `plan.md` (from `/ultraplan-local --project`) - `sessions/session-*.md` (from `--decompose`) - `progress.json` (from `/ultraexecute-local --project`) @@ -231,7 +231,7 @@ Stats: - **Task brief** — produced by `/ultrabrief-local`. Declares intent, goal, and research plan. Drives planning. - **Research brief** — produced by `/ultraresearch-local`. Answers a specific research question. Feeds planning. -- **Architecture note** — opt-in, produced by `/ultra-cc-architect-local` from the separate `ultra-cc-architect` plugin. Proposes which Claude Code features fit the task with brief-anchored rationale + explicit gaps. When present, enriches planning. +- **Architecture note** — opt-in, produced by an opt-in upstream architect plugin (not bundled; the architect plugin is no longer publicly distributed, but the `architecture/overview.md` filesystem slot remains available for any compatible producer). Proposes which Claude Code features fit the task with brief-anchored rationale + explicit gaps. When present, enriches planning. - **Review** — produced by `/ultrareview-local`. Independent post-hoc review of delivered code against the task brief. **Handover 6 (review → plan)** routes BLOCKER + MAJOR findings into `/ultraplan-local --brief review.md` for a remediation plan. The plan's optional `source_findings:` frontmatter list is the audit trail back to the consumed findings. MINOR + SUGGESTION are skipped for v1.0 plan-input. - **Session state** — `.session-state.local.json` per project. **Handover 7** — produced by any session-end mechanism (`/ultraexecute-local` Phase 8/2.55/4, `/ultraplan-end-session-local` helper, future graceful-handoff v2.2). Consumed by `/ultracontinue-local` to resume the next session in a fresh chat. Schema v1 is forward-compat (unknown top-level keys ignored). Never committed (gitignored via `*.local.json`). diff --git a/plugins/ultraplan-local/README.md b/plugins/ultraplan-local/README.md index 27a7065..5fd64ef 100644 --- a/plugins/ultraplan-local/README.md +++ b/plugins/ultraplan-local/README.md @@ -27,7 +27,7 @@ Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{s |---|---|---| | `/ultrabrief-local` | **Capture intent** — intent, goal, non-goals, success criteria, and a research plan with explicit topics. Interactive only. | `brief.md` (task brief) | | `/ultraresearch-local` | **Gather context** — code state, external docs, community, risk. Makes NO build decisions. | `research/NN-slug.md` (research brief) | -| `/ultraplan-local` | **Transform intent into an executable contract** — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. Auto-discovers `architecture/overview.md` as priors when the `ultra-cc-architect` plugin is installed. | `plan.md` with Manifest blocks + `plan_version: 1.7` | +| `/ultraplan-local` | **Transform intent into an executable contract** — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. Auto-discovers `architecture/overview.md` as priors when an opt-in upstream architect plugin (not bundled) is installed. | `plan.md` with Manifest blocks + `plan_version: 1.7` | | `/ultraexecute-local` | **Execute the contract disciplined** — fresh verification, independent manifest audit, honest reporting. Does NOT compensate for weak plans — escalates. | `progress.json` + structured report + manifest-audit status | | `/ultrareview-local` | **Close the loop** — independent post-hoc reviewer reads `brief.md` and the diff produced by execute, runs brief-conformance + code-correctness reviewers in parallel, dedups via Judge Agent. Severity-tagged findings (Critical/High/Medium/Low/Info) feed back into planning via Handover 6. | `review.md` (`type: ultrareview`) with stable 40-char hex finding-IDs | @@ -89,7 +89,7 @@ Or opt into auto-mode in `/ultrabrief-local` — it will run research and planni If review finds issues, feed `review.md` back into planning to produce a remediation plan: `/ultraplan-local --brief .claude/projects/2026-04-18-jwt-auth/review.md`. The remediation plan carries `source_findings: [, ...]` in its frontmatter — full audit trail back to the consumed findings (Handover 6). -For Claude-Code-specific architecture matching (matching brief+research to features like Hooks, Subagents, Skills, MCP), install the separate `ultra-cc-architect` plugin. It sits between research and plan — `/ultraplan-local` auto-discovers its output. +An optional architect step can sit between research and plan — `/ultraplan-local` auto-discovers an `architecture/overview.md` produced by an opt-in upstream architect plugin (not bundled here; the architect plugin is no longer publicly distributed, but the `architecture/overview.md` filesystem slot remains available for any compatible producer). ## When to use it @@ -200,7 +200,7 @@ Research uses up to 5 local agents (architecture-mapper, dependency-tracer, task Produces an implementation plan detailed enough for autonomous execution. **v2.0 breaking change:** requires `--brief` or `--project`. There is no longer an interview inside `/ultraplan-local` — use `/ultrabrief-local` first. -After `brief-reviewer` validates the input brief, 6–8 Sonnet exploration agents analyze the codebase in parallel and merge findings into a synthesis. Optional research briefs (`--research`, or auto-discovered in `{project_dir}/research/`) enrich the plan; `architecture/overview.md` priors are loaded if the `ultra-cc-architect` plugin produced one. Opus then writes the plan with per-step YAML manifests, which `plan-critic` (9 dimensions) and `scope-guardian` adversarially review before handoff. +After `brief-reviewer` validates the input brief, 6–8 Sonnet exploration agents analyze the codebase in parallel and merge findings into a synthesis. Optional research briefs (`--research`, or auto-discovered in `{project_dir}/research/`) enrich the plan; `architecture/overview.md` priors are loaded if an opt-in upstream architect plugin (not bundled) produced one. Opus then writes the plan with per-step YAML manifests, which `plan-critic` (9 dimensions) and `scope-guardian` adversarially review before handoff. Output: - With `--project `: `{dir}/plan.md` @@ -517,7 +517,7 @@ Both arguments are required. No interactive prompt — headless-safe. All artifacts live under `.claude/projects/{YYYY-MM-DD}-{slug}/`. -To insert a Claude-Code-specific architecture-matching step between research and plan, install the separate `ultra-cc-architect` plugin — `/ultraplan-local` auto-discovers its `architecture/overview.md` output as priors. +An opt-in upstream architect plugin (not bundled) can insert a Claude-Code-specific architecture-matching step between research and plan — `/ultraplan-local` auto-discovers its `architecture/overview.md` output as priors when present. ### Example workflows @@ -605,7 +605,7 @@ Validators (zero npm deps, hand-rolled YAML subset): | `lib/validators/research-validator.mjs` | research-brief frontmatter (confidence ∈ [0,1], dimensions ≥ 1) + body sections; `--dir` mode validates a whole `research/` folder | | `lib/validators/plan-validator.mjs` | wraps plan-schema + manifest-yaml; enforces v1.7 step heading, manifest count match, and forbidden-narrative-form denylist (`### Fase/Phase/Stage/Steg N`) — replaces the Phase 5.5 grep checks | | `lib/validators/progress-validator.mjs` | progress.json shape (schema_version, status enum, current_step in range) + resume-readiness check | -| `lib/validators/architecture-discovery.mjs` | EXTERNAL CONTRACT — drift-WARN, never drift-FAIL. Discovers `architecture/overview.md` (owned by the separate `ultra-cc-architect` plugin) and tolerates non-canonical filenames with warnings. | +| `lib/validators/architecture-discovery.mjs` | EXTERNAL CONTRACT — drift-WARN, never drift-FAIL. Discovers `architecture/overview.md` (owned by an opt-in upstream architect plugin, not bundled) and tolerates non-canonical filenames with warnings. | Each module exposes a CLI: `node lib/validators/.mjs --json ` returns structured `{valid, errors, warnings, parsed}`. Commands invoke the CLI as their schema check. @@ -615,7 +615,7 @@ Borrowed pattern from `llm-security` (commit `97c5c9d`); extending the plugin sh ### Handover contracts -`docs/HANDOVER-CONTRACTS.md` is the single source of truth for the file formats that pass between the four pipeline commands (brief → research → plan → execute). When you fork the plugin or extend a stage, that document tells you what every producer must write and what every consumer is allowed to assume. It also documents the *external* contract for `architecture/overview.md` (owned by the separate `ultra-cc-architect` plugin) — discovery only, drift-warn never drift-fail. +`docs/HANDOVER-CONTRACTS.md` is the single source of truth for the file formats that pass between the four pipeline commands (brief → research → plan → execute). When you fork the plugin or extend a stage, that document tells you what every producer must write and what every consumer is allowed to assume. It also documents the *external* contract for `architecture/overview.md` (owned by an opt-in upstream architect plugin, not bundled) — discovery only, drift-warn never drift-fail. ### PreCompact resume integrity (CC v2.1.105+) @@ -643,7 +643,7 @@ Or enable directly in `~/.claude/settings.json`: } ``` -For Claude-Code-specific architecture matching (between research and plan), also enable `ultra-cc-architect@ktg-plugin-marketplace`. +An optional architect step between research and plan was previously available via a separate plugin; that architect plugin is no longer publicly distributed. The `architecture/overview.md` filesystem slot remains supported by `/ultraplan-local` for any compatible producer. ## Cost profile @@ -744,11 +744,11 @@ schema drift. ### Disable the architect bridge -`/ultraplan-local` auto-discovers `architecture/overview.md` if the -separate `ultra-cc-architect` plugin produced one. To suppress this, -either don't install `ultra-cc-architect`, or set `architecture/` -absent in your project directory. Discovery is additive — missing -file is fine, no error. +`/ultraplan-local` auto-discovers `architecture/overview.md` if an +opt-in upstream architect plugin (not bundled) produced one. To +suppress this, leave the `architecture/` directory absent from your +project directory. Discovery is additive — missing file is fine, no +error. ## Contributing diff --git a/plugins/ultraplan-local/SECURITY.md b/plugins/ultraplan-local/SECURITY.md index eeb2e9e..845d33e 100644 --- a/plugins/ultraplan-local/SECURITY.md +++ b/plugins/ultraplan-local/SECURITY.md @@ -53,10 +53,11 @@ phases to detect malformed artifacts before they propagate. ## Out of scope -- **`ultra-cc-architect` plugin.** Separate plugin with its own - `SECURITY.md`. The architecture-discovery validator in this plugin - treats `architecture/overview.md` as an external contract (drift-WARN, - never drift-FAIL). +- **Opt-in upstream architect step.** Any external producer of + `architecture/overview.md` ships its own security posture. The + architecture-discovery validator in this plugin treats + `architecture/overview.md` as an external contract (drift-WARN, never + drift-FAIL). - **LLM output content.** The plugin validates artifact *shape*, not artifact *truthfulness*. A plan that passes `plan-validator --strict` may still contain hallucinated file paths or unsafe commands; that is