diff --git a/.changes/architecture/work-resolve-issue-issue-12672-41723143585-1-6568f049.md b/.changes/architecture/work-resolve-issue-issue-12672-41723143585-1-6568f049.md new file mode 100644 index 00000000000..3d79f26d078 --- /dev/null +++ b/.changes/architecture/work-resolve-issue-issue-12672-41723143585-1-6568f049.md @@ -0,0 +1,15 @@ +--- +bump: major +--- + +### Added + +- A `medium` plugin option that sets where the architecture views go. It declares `options`, so the plugin now needs Claude Code v2.1.271 or later ([Limit a field to fixed options](https://code.claude.com/docs/en/plugins/manifest-reference#limit-a-field-to-fixed-options)). + +### Changed + +- The `map-*` views and the `improve` deepening report now resolve their medium through the shared resolver (`lib/view-settings.mjs resolve --lane architecture`) and print its report line. + +### Removed + +- `~/.claude/rendered-views.md` and the `.claude/rendered-views*.md` files no longer choose a publishing medium: an `artifact` or `hosted` value there is ignored. A `terminal` or `file` value there still keeps the view local when no scope sets a value. Each file gives one notice per project naming where to set the medium instead: this plugin's `medium` option, `docs/conventions/rendered-views.yaml`, or `docs/conventions/rendered-views.local.yaml`. diff --git a/.changes/debugging/work-resolve-issue-issue-12672-41723143585-1-124dbf76.md b/.changes/debugging/work-resolve-issue-issue-12672-41723143585-1-124dbf76.md new file mode 100644 index 00000000000..14f9e57d662 --- /dev/null +++ b/.changes/debugging/work-resolve-issue-issue-12672-41723143585-1-124dbf76.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- The shared `reference/rendered-view.md` now lists `architecture` as a medium-resolver lane beside `planning`; the post-mortem view still reads the rendered-views cascade itself. diff --git a/.changes/discovery/work-resolve-issue-issue-12672-41723143585-1-b0a6ab28.md b/.changes/discovery/work-resolve-issue-issue-12672-41723143585-1-b0a6ab28.md new file mode 100644 index 00000000000..2bf0301e2e9 --- /dev/null +++ b/.changes/discovery/work-resolve-issue-issue-12672-41723143585-1-b0a6ab28.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- The shared `reference/rendered-view.md` now lists `architecture` as a medium-resolver lane beside `planning`; the blindspot view still reads the rendered-views cascade itself. diff --git a/.changes/planning/work-resolve-issue-issue-12672-41723143585-1-40719358.md b/.changes/planning/work-resolve-issue-issue-12672-41723143585-1-40719358.md new file mode 100644 index 00000000000..1a7c15ec1b8 --- /dev/null +++ b/.changes/planning/work-resolve-issue-issue-12672-41723143585-1-40719358.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- The shared `reference/rendered-view.md` now lists `architecture` as a medium-resolver lane beside `planning`, and adds the architecture deepening report's medium rules. diff --git a/docs/contracts/rendered-views/README.md b/docs/contracts/rendered-views/README.md index ec763abc835..21756c9df8c 100644 --- a/docs/contracts/rendered-views/README.md +++ b/docs/contracts/rendered-views/README.md @@ -584,13 +584,15 @@ Emitters that resolve `medium` through the shared resolver (see The `rendered-vi keeping their shipped default only when no scope sets it: `adhd:clarify`. Its output prints the resolver's report line and notices. +`architecture:improve` resolves `medium` through the shared resolver (lane `architecture`, see +"The `rendered-views` settings") and publishes nothing: `terminal` skips the HTML report and leaves +the candidate artifact; every other value writes the local report. + Emitters that resolve `medium` from the argument, then the cascade, and publish nothing themselves. None has a `medium` option, so no plugin dial sits between the argument and the cascade. Each names the source of `medium`, or "shipped default", and keeps its shipped behavior when no layer sets one: -- `architecture:improve`: `terminal` skips the HTML report and leaves the candidate artifact; - every other value writes the local report. - `education:teach` (topic mode): `terminal` writes `lesson.md`; `file` keeps the host-aware format choice and drops the artifact-share offer; `artifact` and `hosted` keep the offer. - `prototype:explore-directions`: the mockup stays a local file at every value; `terminal` and diff --git a/lib/rendered-view.md b/lib/rendered-view.md index 0929f3f877d..bcb8a3fc79b 100644 --- a/lib/rendered-view.md +++ b/lib/rendered-view.md @@ -1,7 +1,8 @@ # Rendered views of a skill's record How a view lane offers an interactive view of the record its skill wrote. The lanes that carry this file: -planning (`/planning:plan`, `/planning:brainstorm`, `/planning:design`), architecture (the `map-*` skills), discovery +planning (`/planning:plan`, `/planning:brainstorm`, `/planning:design`), architecture (the `map-*` skills +and the `/architecture:improve` deepening report), discovery (`/discovery:blindspot`) and debugging (`/debugging:debug`). Each lane's section below names its record, build command and data shape. `` is the plugin's root directory, the one that holds `.claude-plugin/`: the path the calling skill gave for this file, cut before its first `skills/` or @@ -22,23 +23,26 @@ script written in the session. 2. **Offer the view in one sentence.** Build only when the reader accepts and the environment can serve a file. A CI or other non-interactive run emits no view: the record stands. 3. **Resolve `medium`.** The path depends on whether the lane's skill has migrated to the shared medium - resolver, not on whether the resolver registers the lane. `planning` and `debugging` have migrated; - architecture and discovery are registered but read the cascade themselves until their own change - migrates them. - - **Resolver lanes** (`planning`). The lane's build command runs the resolver, the publish gate and - delivery in one call: follow its section in place of steps 3 and 5, and step 4's rule for a missing - `node` or a non-zero exit still applies. Do not read the rendered-views convention files yourself. - - **Resolver lanes** (`debugging`). Run the resolver. `--option` takes this plugin's `medium` option as the - calling skill states it; add `--argument` only when the reader named a medium in the request: - - ```bash - node "/lib/view-settings.mjs" resolve --lane --option "" [--argument terminal|file|artifact] - ``` - - It prints one JSON line, then the report line naming the medium and what decided it, then any notice; - print those lines as they stand. The JSON's `medium` is the one to use: `terminal`, `file` or `artifact`. - Do not read the rendered-views convention files yourself. When `node` is missing, the builder cannot run - either: deliver the record. + resolver, not on whether the resolver registers the lane. `planning`, `architecture` and `debugging` + have migrated; discovery is registered but reads the cascade itself until its own change migrates it. + - **Resolver lanes** (`planning`, `architecture`, `debugging`). Do not read the rendered-views convention + files yourself. + - `planning`: the lane's build command runs the resolver, the publish gate and delivery in one call: + follow its section in place of steps 3 and 5, and step 4's rule for a missing `node` or a non-zero + exit still applies. + - `architecture`, `debugging`: run the resolver with the `--lane` its section names. `--option` takes + this plugin's `medium` option as the calling skill states it; add `--argument` only when the reader + named a medium in the request: + + ```bash + node "/lib/view-settings.mjs" resolve --lane --option "" [--argument terminal|file|artifact] + ``` + + It prints one JSON line, then the report line naming the medium and what decided it, then any notice; + print those lines as they stand. The JSON's `medium` is the one to use: `terminal`, `file` or + `artifact`. When `node` is missing, the builder cannot run either: deliver the record. When the + resolver exits 2 with its usage line, the argument names no medium: report it as unknown and resolve + again without `--argument`. - **Other lanes.** Read the `rendered-views` cascade surface: `~/.claude/rendered-views.md`, then `/.claude/rendered-views.md`, then `/.claude/rendered-views.local.md`, whichever exist. The last layer that states `medium:` wins (`auto`, `terminal`, `file`, `artifact`). A team layer @@ -202,6 +206,7 @@ with no `## Design` section exits 1. The `map-*` skills record a markdown file and a JSON record; both stay authoritative. A record holds manifest paths, connection hosts, type names and file citations. Write the record and its markdown first. +Resolver lane: `--lane architecture`. Build: pass the record file to the builder. The first argument is the skill's kind, and the record is the file in the table below: @@ -237,6 +242,19 @@ other row takes the first of `id`, `name`, `message`, `title`, `path`, `entry`, field it holds, evidence citations included. The filter matches a row's whole text, so typing a node id lists the node and every edge, finding and cycle that names it. The page draws no diagram: the markdown holds that. +### The deepening report + +`/architecture:improve deepening` writes its HTML report itself, not through the builder, and only ever as a +local file. Before writing it, resolve `medium` as step 3 does, passing the skill's `--medium` value as +`--argument`, and print the resolver's lines. When the resolver exits 2 with its usage line, the +`--medium` value names no medium: report it as unknown and resolve again without `--argument`. Then, by +the JSON's `medium`: + +- `terminal`: write no report. The durable candidate artifact and the reply are the deliverable. +- `file`: write the local report. +- `artifact`: write the local report. This lane publishes nothing, so say that a publishing value was read + as `file`. + ## Discovery: blindspot `/discovery:blindspot` records the blindspot cards and the improved prompt as written in the conversation, diff --git a/plugins/architecture/.claude-plugin/plugin.json b/plugins/architecture/.claude-plugin/plugin.json index 8caa59e3c7d..844b451a142 100644 --- a/plugins/architecture/.claude-plugin/plugin.json +++ b/plugins/architecture/.claude-plugin/plugin.json @@ -6,6 +6,15 @@ "email": "info@melodicsoftware.com" }, "version": "1.4.9", + "userConfig": { + "medium": { + "type": "string", + "title": "Preferred delivery medium", + "description": "Where the map-* views and the improve report go. auto (default): a local file; terminal: no page; file: a local file; artifact: a private Artifact (the improve report stays a local file); hosted is read as artifact. A team rendered-views file never publishes.", + "default": "auto", + "options": ["auto", "terminal", "file", "artifact", "hosted"] + } + }, "license": "MIT", "keywords": [ "architecture", diff --git a/plugins/architecture/README.md b/plugins/architecture/README.md index f5323fb83fb..1feea82e534 100644 --- a/plugins/architecture/README.md +++ b/plugins/architecture/README.md @@ -151,8 +151,10 @@ places no container is refused. `--live` is refused. Each `map-*` skill offers an interactive view of its JSON record after the report: a filter that traces an id through every row naming it, and rows that open to their fields and citations. The markdown and the record stay authoritative. The page is a checked-in template plus the record as escaped data, so -repository text never becomes markup or script. Where it is delivered comes from the `medium` key of the -`rendered-views` cascade (`file` when unset). The procedure is in `reference/rendered-view.md`. +repository text never becomes markup or script. Where it is delivered, and where the `improve` deepening +report goes, comes from the shared medium resolver, which reads the plugin's `medium` option and the +`rendered-views` files in `docs/conventions` (a local file when none sets it). The procedure is in +`reference/rendered-view.md`. ## Record a decision @@ -240,6 +242,84 @@ above. /plugin install architecture@melodic-software ``` + + +### Options reference + +Generated from this plugin's `.claude-plugin/plugin.json`. Every option Claude Code +will prompt for when the plugin is enabled, with the environment variable each hook +reads it from. + +| Option | Type | Default | Environment variable | Description | +| --- | --- | --- | --- | --- | +| `medium` | string | `"auto"` | `CLAUDE_PLUGIN_OPTION_MEDIUM` | Where the map-* views and the improve report go. auto (default): a local file; terminal: no page; file: a local file; artifact: a private Artifact (the improve report stays a local file); hosted is read as artifact. A team rendered-views file never publishes. | + +### How to set these + +Three supported routes: + +1. **Interactively.** Open this plugin's options dialog ([`/plugin` in a session](https://code.claude.com/docs/en/plugins/cli-reference#plugin-in-a-session)): + `/plugin configure architecture@`. +2. **Headless.** Save the values with [`claude plugin configure`](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure), + run from the project the plugin is installed in. Replace + `` with the marketplace you installed this plugin from: + + ```shell + claude plugin configure architecture@ --values-stdin < values.json + ``` + + `values.json` holds a JSON object of strings, booleans included: + + ```json + {"medium": ""} + ``` + + This is the preferred headless route in the [plugin-reconfiguration convention](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/plugin-reconfiguration/README.md), which records its + limits: the Claude Code version it needs, which install it finds, how it rejects a bad + value, and why a session started before the change keeps the old value until a fresh + session starts. Do **not** `claude plugin uninstall` to reconfigure: see + [What an uninstall deletes and keeps](https://code.claude.com/docs/en/plugins/cli-reference#what-an-uninstall-deletes-and-keeps). + + The fallback the convention names, for a Claude Code release without + `plugin configure`, reruns the install with the new value, passing the scope + `claude plugin list` reports for this plugin: + + ```shell + claude plugin install architecture@ -s --config medium= + ``` + +3. **By hand, in settings.** Add the value under `pluginConfigs` in your **user** + settings (`~/.claude/settings.json`): + + ```json + { + "pluginConfigs": { + "architecture@": { + "options": { + "medium": + } + } + } + } + ``` + + The [`pluginConfigs`](https://code.claude.com/docs/en/settings-reference#pluginconfigs) + entry names the settings scopes Claude Code reads this key from. + +Do not set the `CLAUDE_PLUGIN_OPTION_*` variables yourself; set the value through one +of the routes above. + +### Upstream documentation + +- [User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration): the `userConfig` schema and the `CLAUDE_PLUGIN_OPTION_` export +- [Plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure): the `--values-stdin` flag's reference entry +- [Plugin install options](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install): the `--config` flag's reference entry +- [Plugins and skills settings](https://code.claude.com/docs/en/settings-reference#plugins-and-skills): `enabledPlugins`, `extraKnownMarketplaces`, `pluginConfigs` +- [Settings files and who they affect](https://code.claude.com/docs/en/settings#settings-files-and-who-they-affect): user vs project vs local precedence +- [Manage installed plugins](https://code.claude.com/docs/en/plugins/install#manage-installed-plugins): enabling, disabling, `/plugin list` + + + ## License MIT (SPDX-License-Identifier: MIT). diff --git a/plugins/architecture/reference/rendered-view.md b/plugins/architecture/reference/rendered-view.md index 783de8783d8..0c15ea0831f 100644 --- a/plugins/architecture/reference/rendered-view.md +++ b/plugins/architecture/reference/rendered-view.md @@ -4,7 +4,8 @@ edit the canonical source, then rerun the script. --> # Rendered views of a skill's record How a view lane offers an interactive view of the record its skill wrote. The lanes that carry this file: -planning (`/planning:plan`, `/planning:brainstorm`, `/planning:design`), architecture (the `map-*` skills), discovery +planning (`/planning:plan`, `/planning:brainstorm`, `/planning:design`), architecture (the `map-*` skills +and the `/architecture:improve` deepening report), discovery (`/discovery:blindspot`) and debugging (`/debugging:debug`). Each lane's section below names its record, build command and data shape. `` is the plugin's root directory, the one that holds `.claude-plugin/`: the path the calling skill gave for this file, cut before its first `skills/` or @@ -25,23 +26,26 @@ script written in the session. 2. **Offer the view in one sentence.** Build only when the reader accepts and the environment can serve a file. A CI or other non-interactive run emits no view: the record stands. 3. **Resolve `medium`.** The path depends on whether the lane's skill has migrated to the shared medium - resolver, not on whether the resolver registers the lane. `planning` and `debugging` have migrated; - architecture and discovery are registered but read the cascade themselves until their own change - migrates them. - - **Resolver lanes** (`planning`). The lane's build command runs the resolver, the publish gate and - delivery in one call: follow its section in place of steps 3 and 5, and step 4's rule for a missing - `node` or a non-zero exit still applies. Do not read the rendered-views convention files yourself. - - **Resolver lanes** (`debugging`). Run the resolver. `--option` takes this plugin's `medium` option as the - calling skill states it; add `--argument` only when the reader named a medium in the request: - - ```bash - node "/lib/view-settings.mjs" resolve --lane --option "" [--argument terminal|file|artifact] - ``` - - It prints one JSON line, then the report line naming the medium and what decided it, then any notice; - print those lines as they stand. The JSON's `medium` is the one to use: `terminal`, `file` or `artifact`. - Do not read the rendered-views convention files yourself. When `node` is missing, the builder cannot run - either: deliver the record. + resolver, not on whether the resolver registers the lane. `planning`, `architecture` and `debugging` + have migrated; discovery is registered but reads the cascade itself until its own change migrates it. + - **Resolver lanes** (`planning`, `architecture`, `debugging`). Do not read the rendered-views convention + files yourself. + - `planning`: the lane's build command runs the resolver, the publish gate and delivery in one call: + follow its section in place of steps 3 and 5, and step 4's rule for a missing `node` or a non-zero + exit still applies. + - `architecture`, `debugging`: run the resolver with the `--lane` its section names. `--option` takes + this plugin's `medium` option as the calling skill states it; add `--argument` only when the reader + named a medium in the request: + + ```bash + node "/lib/view-settings.mjs" resolve --lane --option "" [--argument terminal|file|artifact] + ``` + + It prints one JSON line, then the report line naming the medium and what decided it, then any notice; + print those lines as they stand. The JSON's `medium` is the one to use: `terminal`, `file` or + `artifact`. When `node` is missing, the builder cannot run either: deliver the record. When the + resolver exits 2 with its usage line, the argument names no medium: report it as unknown and resolve + again without `--argument`. - **Other lanes.** Read the `rendered-views` cascade surface: `~/.claude/rendered-views.md`, then `/.claude/rendered-views.md`, then `/.claude/rendered-views.local.md`, whichever exist. The last layer that states `medium:` wins (`auto`, `terminal`, `file`, `artifact`). A team layer @@ -205,6 +209,7 @@ with no `## Design` section exits 1. The `map-*` skills record a markdown file and a JSON record; both stay authoritative. A record holds manifest paths, connection hosts, type names and file citations. Write the record and its markdown first. +Resolver lane: `--lane architecture`. Build: pass the record file to the builder. The first argument is the skill's kind, and the record is the file in the table below: @@ -240,6 +245,19 @@ other row takes the first of `id`, `name`, `message`, `title`, `path`, `entry`, field it holds, evidence citations included. The filter matches a row's whole text, so typing a node id lists the node and every edge, finding and cycle that names it. The page draws no diagram: the markdown holds that. +### The deepening report + +`/architecture:improve deepening` writes its HTML report itself, not through the builder, and only ever as a +local file. Before writing it, resolve `medium` as step 3 does, passing the skill's `--medium` value as +`--argument`, and print the resolver's lines. When the resolver exits 2 with its usage line, the +`--medium` value names no medium: report it as unknown and resolve again without `--argument`. Then, by +the JSON's `medium`: + +- `terminal`: write no report. The durable candidate artifact and the reply are the deliverable. +- `file`: write the local report. +- `artifact`: write the local report. This lane publishes nothing, so say that a publishing value was read + as `file`. + ## Discovery: blindspot `/discovery:blindspot` records the blindspot cards and the improved prompt as written in the conversation, diff --git a/plugins/architecture/skills/improve/SKILL.md b/plugins/architecture/skills/improve/SKILL.md index b865c761f92..687af9fb66b 100644 --- a/plugins/architecture/skills/improve/SKILL.md +++ b/plugins/architecture/skills/improve/SKILL.md @@ -8,7 +8,7 @@ metadata: summary: Scan the codebase for shallow modules or boundary crossings, then design or hand on the chosen fix --- -**Arguments.** `[deepening|boundaries|conventions] [--medium ]`. e.g., boundaries. `--medium` sets where the deepening report goes (`actions/deepening.md`, Phase 2). +**Arguments.** `[deepening|boundaries|conventions] [--medium ]`. e.g., boundaries. `--medium` sets where the deepening report goes (`actions/deepening.md`, Phase 2). `medium` option for the medium resolver ([`${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md`](${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md) "The deepening report"): `${user_config.medium}`. ## Repository context. Gather first diff --git a/plugins/architecture/skills/improve/actions/deepening.md b/plugins/architecture/skills/improve/actions/deepening.md index f18a5e03db4..d3ffbcc02a6 100644 --- a/plugins/architecture/skills/improve/actions/deepening.md +++ b/plugins/architecture/skills/improve/actions/deepening.md @@ -82,12 +82,7 @@ The report is one self-contained HTML file under the OS temp directory, one per **Another repository's files are not rendered to HTML until this lane is wired through the rendered-views escape helper.** When the scanned repository is not the user's own work (a freshly cloned third-party checkout, a vendored or fetched tree), skip the HTML report: the durable candidate artifact below is the deliverable, and say in one line why no page was produced. This is the baseline's third bullet applied to this skill; it overrides the report step above, not the scan. -**Resolve `medium` before writing the report.** The `rendered-views` preference is one of `auto`, `terminal`, `file`, `artifact` or `hosted`. A `--medium` argument naming one decides. Otherwise read whichever layers exist, in order: user-global `~/.claude/rendered-views.md`, team `/.claude/rendered-views.md`, overlay `/.claude/rendered-views.local.md`. `` is `${CLAUDE_PROJECT_DIR}` when set, else `git rev-parse --show-toplevel`; outside a work tree, read only the user-global layer. The last layer that sets `medium` wins. Count the overlay only when `git ls-files` does not list it and `git check-ignore` matches it; otherwise report it and ignore it. This plugin has no `medium` option, so no rung sits between the argument and the layers. `auto`, an empty value or no value leaves the shipped default, the local report above; any other value is reported and read as `auto`. Then: - -- `terminal` skips the HTML report: the durable candidate artifact and the reply are the deliverable. -- `file` writes the local report, as does `artifact` or `hosted`: this lane publishes nothing, so say that the value was read as `file`. - -Name the source of `medium` in the reply: the argument, the layer's path, or "shipped default". +**Resolve `medium` before writing the report.** The shared medium resolver decides, with this plugin's `medium` option as the skill's Arguments line states it and the `--medium` argument when given; print its report line and notices in the reply. Procedure, and what each resolved medium does to this report: [../../../reference/rendered-view.md](../../../reference/rendered-view.md) "The deepening report". Each candidate gets a card with: files involved, problem (one sentence), solution (one sentence), before/after diagram, benefits in terms of **leverage** and **locality**, recommendation badge (`Strong` / `Worth exploring` / `Speculative`), dependency category badge. diff --git a/plugins/architecture/skills/improve/evals/evals.json b/plugins/architecture/skills/improve/evals/evals.json index 2456990301f..68940aec831 100644 --- a/plugins/architecture/skills/improve/evals/evals.json +++ b/plugins/architecture/skills/improve/evals/evals.json @@ -208,16 +208,16 @@ }, { "id": 15, - "name": "user-global-terminal-medium-skips-html-report", - "prompt": "/architecture:improve deepening (Fixture: the scan is of the user's own repository; ~/.claude/rendered-views.md contains only 'medium: terminal'; the repo has no rendered-views layer; no --medium argument was given.)", - "expected_output": "Resolves medium from the rendered-views layers before writing the report, reads medium: terminal from the user-global layer, and writes no HTML report: the durable candidate artifact in the memory tier and the reply are the deliverable. The reply names ~/.claude/rendered-views.md as the source of the medium, gives the artifact path, and asks which candidate to explore.", + "name": "plugin-option-terminal-medium-skips-html-report", + "prompt": "/architecture:improve deepening (Fixture: the scan is of the user's own repository; the architecture plugin's medium option is set to terminal; ~/.claude/rendered-views.md still exists and contains only 'medium: file', and this is the plugin's first run in this project, so no notice state is recorded; the repo has no rendered-views convention file; no --medium argument was given.)", + "expected_output": "Before writing the report it runs the shared medium resolver, which reports `view: terminal (userConfig)` and a notice that ~/.claude/rendered-views.md is retired (it sets medium: file) and where to set the medium instead. It writes no HTML report: the durable candidate artifact in the memory tier and the reply are the deliverable. The reply prints the resolver's report line and notice, gives the artifact path, and asks which candidate to explore.", "files": [], "narration": true, "expectations": [ - "Resolves medium from the rendered-views layers before writing any report", + "Resolves medium through the shared medium resolver before writing any report, and does not read ~/.claude/rendered-views.md itself", "Writes no HTML report file and opens no browser", "Still writes the durable candidate artifact to the memory tier and gives its path", - "Names ~/.claude/rendered-views.md as the source of the medium" + "Prints the resolver's report line naming the plugin option (userConfig) as the source of the medium, and the retired-file notice for ~/.claude/rendered-views.md" ] } ] diff --git a/plugins/architecture/skills/map-components/SKILL.md b/plugins/architecture/skills/map-components/SKILL.md index a03ba8510cc..5b7acbfe529 100644 --- a/plugins/architecture/skills/map-components/SKILL.md +++ b/plugins/architecture/skills/map-components/SKILL.md @@ -205,8 +205,8 @@ End every run with this block, in this order: After the report, offer an interactive view of the chosen deployable's closure in one sentence. The markdown and `dependency-graph.json` stay authoritative. Build it only with `${CLAUDE_PLUGIN_ROOT}/scripts/build-view.mjs components --record --from `, never hand-written; the publish destination comes from the `medium` cascade key. -Procedure: [`${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md`](${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md). +deployable's node id>`, never hand-written; the shared medium resolver decides the destination, with this +plugin's `medium` option `${user_config.medium}`, and its report line is printed. Procedure: [`${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md`](${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md). ## What this skill does NOT do diff --git a/plugins/architecture/skills/map-components/evals/evals.json b/plugins/architecture/skills/map-components/evals/evals.json index 4ca524aee55..c278d4b9d10 100644 --- a/plugins/architecture/skills/map-components/evals/evals.json +++ b/plugins/architecture/skills/map-components/evals/evals.json @@ -74,12 +74,12 @@ "id": 6, "name": "offers-built-interactive-view", "prompt": "/architecture:map-components\n\ncomponents.md is written for the deployable src/Api/Api.csproj. I would like to filter and trace its components rather than read the tables.", - "expected_output": "After the report, offers an interactive view of the deployable's closure in one sentence, builds it only with scripts/build-view.mjs components from dependency-graph.json with --from naming the deployable, and resolves the publish destination from the medium cascade key.", + "expected_output": "After the report, offers an interactive view of the deployable's closure in one sentence, builds it only with scripts/build-view.mjs components from dependency-graph.json with --from naming the deployable, and resolves the destination through the shared medium resolver, printing its report line.", "expectations": [ "components.md and dependency-graph.json are written first and stay the record", "Offers the view in one sentence and builds only after the reader accepts", "Builds with scripts/build-view.mjs components --record dependency-graph.json --from src/Api/Api.csproj and writes no HTML or script itself", - "The publish destination comes from the medium key of the rendered-views cascade, with file as the default when unset" + "The destination comes from the shared medium resolver run for the architecture lane, and its report line is printed" ] } ] diff --git a/plugins/architecture/skills/map-containers/SKILL.md b/plugins/architecture/skills/map-containers/SKILL.md index 7719792c68e..94aabc4e631 100644 --- a/plugins/architecture/skills/map-containers/SKILL.md +++ b/plugins/architecture/skills/map-containers/SKILL.md @@ -212,7 +212,8 @@ End every run with this block, in this order, filled from the record and the scr After the report, offer an interactive view of `containers.json` in one sentence. The markdown and the record stay authoritative. Build it only with `${CLAUDE_PLUGIN_ROOT}/scripts/build-view.mjs containers`, never -hand-written; the publish destination comes from the `medium` cascade key. Procedure: +hand-written; the shared medium resolver decides the destination, with this plugin's `medium` option +`${user_config.medium}`, and its report line is printed. Procedure: [`${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md`](${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md). ## What this skill does NOT do diff --git a/plugins/architecture/skills/map-containers/evals/evals.json b/plugins/architecture/skills/map-containers/evals/evals.json index 73c5f7c677e..e73a943a0a1 100644 --- a/plugins/architecture/skills/map-containers/evals/evals.json +++ b/plugins/architecture/skills/map-containers/evals/evals.json @@ -63,12 +63,12 @@ "id": 6, "name": "offers-built-interactive-view", "prompt": "/architecture:map-containers\n\ncontainers.json and containers.md are written. I would like to filter and trace the containers rather than read the tables.", - "expected_output": "After the report, offers an interactive view of containers.json in one sentence, builds it only with scripts/build-view.mjs containers from the record, and resolves the publish destination from the medium cascade key.", + "expected_output": "After the report, offers an interactive view of containers.json in one sentence, builds it only with scripts/build-view.mjs containers from the record, and resolves the destination through the shared medium resolver, printing its report line.", "expectations": [ "containers.md and containers.json are written first and stay the record", "Offers the view in one sentence and builds only after the reader accepts", "Builds with scripts/build-view.mjs containers --record containers.json and writes no HTML or script itself", - "The publish destination comes from the medium key of the rendered-views cascade, with file as the default when unset" + "The destination comes from the shared medium resolver run for the architecture lane, and its report line is printed" ] } ] diff --git a/plugins/architecture/skills/map-context/SKILL.md b/plugins/architecture/skills/map-context/SKILL.md index be4965ee039..96561a2147f 100644 --- a/plugins/architecture/skills/map-context/SKILL.md +++ b/plugins/architecture/skills/map-context/SKILL.md @@ -173,7 +173,8 @@ End every run with this block, in this order, filled from the record and the scr After the report, offer an interactive view of `context.json` in one sentence. The markdown and the record stay authoritative. Build it only with `${CLAUDE_PLUGIN_ROOT}/scripts/build-view.mjs context`, never -hand-written; the publish destination comes from the `medium` cascade key. Procedure: +hand-written; the shared medium resolver decides the destination, with this plugin's `medium` option +`${user_config.medium}`, and its report line is printed. Procedure: [`${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md`](${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md). ## What this skill does NOT do diff --git a/plugins/architecture/skills/map-context/evals/evals.json b/plugins/architecture/skills/map-context/evals/evals.json index 02619c2f0f5..a9e6cc1ab2e 100644 --- a/plugins/architecture/skills/map-context/evals/evals.json +++ b/plugins/architecture/skills/map-context/evals/evals.json @@ -125,12 +125,12 @@ "id": 9, "name": "offers-built-interactive-view", "prompt": "/architecture:map-context\n\ncontext.json and context.md are written. I would like to filter and trace the external systems rather than read the tables.", - "expected_output": "After the report, offers an interactive view of context.json in one sentence, builds it only with scripts/build-view.mjs context from the record, and resolves the publish destination from the medium cascade key.", + "expected_output": "After the report, offers an interactive view of context.json in one sentence, builds it only with scripts/build-view.mjs context from the record, and resolves the destination through the shared medium resolver, printing its report line.", "expectations": [ "context.md and context.json are written first and stay the record", "Offers the view in one sentence and builds only after the reader accepts", "Builds with scripts/build-view.mjs context --record context.json and writes no HTML or script itself", - "The publish destination comes from the medium key of the rendered-views cascade, with file as the default when unset" + "The destination comes from the shared medium resolver run for the architecture lane, and its report line is printed" ] } ] diff --git a/plugins/architecture/skills/map-data/SKILL.md b/plugins/architecture/skills/map-data/SKILL.md index 747a8eda4bd..ac1540242d8 100644 --- a/plugins/architecture/skills/map-data/SKILL.md +++ b/plugins/architecture/skills/map-data/SKILL.md @@ -162,7 +162,8 @@ End every run with this block, in this order: After the report, offer an interactive view of `data-model.json` in one sentence. The markdown and the record stay authoritative. Build it only with `${CLAUDE_PLUGIN_ROOT}/scripts/build-view.mjs data`, -never hand-written; the publish destination comes from the `medium` cascade key. Procedure: +never hand-written; the shared medium resolver decides the destination, with this plugin's `medium` +option `${user_config.medium}`, and its report line is printed. Procedure: [`${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md`](${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md). ## What this skill does NOT do diff --git a/plugins/architecture/skills/map-data/evals/evals.json b/plugins/architecture/skills/map-data/evals/evals.json index 388a5280599..3a33d4d0e60 100644 --- a/plugins/architecture/skills/map-data/evals/evals.json +++ b/plugins/architecture/skills/map-data/evals/evals.json @@ -98,12 +98,12 @@ "id": 8, "name": "offers-built-interactive-view", "prompt": "/architecture:map-data\n\ndata-model.json and data-model.md are written. I would like to filter and trace the entities rather than read the diagram.", - "expected_output": "After the report, offers an interactive view of data-model.json in one sentence, builds it only with scripts/build-view.mjs data from the record, and resolves the publish destination from the medium cascade key.", + "expected_output": "After the report, offers an interactive view of data-model.json in one sentence, builds it only with scripts/build-view.mjs data from the record, and resolves the destination through the shared medium resolver, printing its report line.", "expectations": [ "data-model.md and data-model.json are written first and stay the record", "Offers the view in one sentence and builds only after the reader accepts", "Builds with scripts/build-view.mjs data --record data-model.json and writes no HTML or script itself", - "The publish destination comes from the medium key of the rendered-views cascade, with file as the default when unset" + "The destination comes from the shared medium resolver run for the architecture lane, and its report line is printed" ] } ] diff --git a/plugins/architecture/skills/map-dependencies/SKILL.md b/plugins/architecture/skills/map-dependencies/SKILL.md index 73d1f408039..0a3d24e755a 100644 --- a/plugins/architecture/skills/map-dependencies/SKILL.md +++ b/plugins/architecture/skills/map-dependencies/SKILL.md @@ -214,7 +214,8 @@ says it aggregated to directory level. After the report, offer an interactive view of `dependency-graph.json` in one sentence. The markdown and the record stay authoritative. Build it only with `${CLAUDE_PLUGIN_ROOT}/scripts/build-view.mjs dependencies`, -never hand-written; the publish destination comes from the `medium` cascade key. Procedure: +never hand-written; the shared medium resolver decides the destination, with this plugin's `medium` +option `${user_config.medium}`, and its report line is printed. Procedure: [`${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md`](${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md). ## What this skill does NOT do diff --git a/plugins/architecture/skills/map-dependencies/evals/evals.json b/plugins/architecture/skills/map-dependencies/evals/evals.json index 0788570d3e8..647c1583981 100644 --- a/plugins/architecture/skills/map-dependencies/evals/evals.json +++ b/plugins/architecture/skills/map-dependencies/evals/evals.json @@ -73,12 +73,12 @@ "id": 6, "name": "offers-built-interactive-view", "prompt": "/architecture:map-dependencies\n\ndependency-graph.json and dependency-graph.md are written. I would like to filter and trace the projects rather than read the flowchart.", - "expected_output": "After the report, offers an interactive view of dependency-graph.json in one sentence, builds it only with scripts/build-view.mjs dependencies from the record, and resolves the publish destination from the medium cascade key.", + "expected_output": "After the report, offers an interactive view of dependency-graph.json in one sentence, builds it only with scripts/build-view.mjs dependencies from the record, and resolves the destination through the shared medium resolver, printing its report line.", "expectations": [ "dependency-graph.md and dependency-graph.json are written first and stay the record", "Offers the view in one sentence and builds only after the reader accepts", "Builds with scripts/build-view.mjs dependencies --record dependency-graph.json and writes no HTML or script itself", - "The publish destination comes from the medium key of the rendered-views cascade, with file as the default when unset" + "The destination comes from the shared medium resolver run for the architecture lane, and its report line is printed" ] } ] diff --git a/plugins/architecture/skills/map-deployment/SKILL.md b/plugins/architecture/skills/map-deployment/SKILL.md index 3e04fb3989c..35aec149c0f 100644 --- a/plugins/architecture/skills/map-deployment/SKILL.md +++ b/plugins/architecture/skills/map-deployment/SKILL.md @@ -280,8 +280,9 @@ End every run with this block, in this order: After the report, offer an interactive view of `deployment.json` in one sentence. The markdown and the record stay authoritative. Build it only with -`${CLAUDE_PLUGIN_ROOT}/scripts/build-view.mjs deployment`, never hand-written; the publish -destination comes from the `medium` cascade key. Procedure: +`${CLAUDE_PLUGIN_ROOT}/scripts/build-view.mjs deployment`, never hand-written; the shared medium +resolver decides the destination, with this plugin's `medium` option `${user_config.medium}`, and its +report line is printed. Procedure: [`${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md`](${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md). ## What this skill does NOT do diff --git a/plugins/architecture/skills/map-deployment/evals/evals.json b/plugins/architecture/skills/map-deployment/evals/evals.json index 2dabb73f4ed..225f0432e06 100644 --- a/plugins/architecture/skills/map-deployment/evals/evals.json +++ b/plugins/architecture/skills/map-deployment/evals/evals.json @@ -192,12 +192,12 @@ "id": 15, "name": "offers-built-interactive-view", "prompt": "/architecture:map-deployment\n\ndeployment.json and deployment.md are written. I would like to filter and trace the placements rather than read the tables.", - "expected_output": "After the report, offers an interactive view of deployment.json in one sentence, builds it only with scripts/build-view.mjs deployment from the record, and resolves the publish destination from the medium cascade key.", + "expected_output": "After the report, offers an interactive view of deployment.json in one sentence, builds it only with scripts/build-view.mjs deployment from the record, and resolves the destination through the shared medium resolver, printing its report line.", "expectations": [ "deployment.md and deployment.json are written first and stay the record", "Offers the view in one sentence and builds only after the reader accepts", "Builds with scripts/build-view.mjs deployment --record deployment.json and writes no HTML or script itself", - "The publish destination comes from the medium key of the rendered-views cascade, with file as the default when unset" + "The destination comes from the shared medium resolver run for the architecture lane, and its report line is printed" ] } ] diff --git a/plugins/architecture/skills/map-events/SKILL.md b/plugins/architecture/skills/map-events/SKILL.md index c2493084ad0..75ef3560ecf 100644 --- a/plugins/architecture/skills/map-events/SKILL.md +++ b/plugins/architecture/skills/map-events/SKILL.md @@ -104,7 +104,8 @@ Exit 1 means the record is unreadable or not one object per line. Nothing was wr After the report, offer an interactive view of `events.json` in one sentence. The markdown and the record stay authoritative. Build it only with `${CLAUDE_PLUGIN_ROOT}/scripts/build-view.mjs events`, never -hand-written; the publish destination comes from the `medium` cascade key. Procedure: +hand-written; the shared medium resolver decides the destination, with this plugin's `medium` option +`${user_config.medium}`, and its report line is printed. Procedure: [`${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md`](${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md). ## What this skill does NOT do diff --git a/plugins/architecture/skills/map-events/evals/evals.json b/plugins/architecture/skills/map-events/evals/evals.json index cc457516a26..afa8db017aa 100644 --- a/plugins/architecture/skills/map-events/evals/evals.json +++ b/plugins/architecture/skills/map-events/evals/evals.json @@ -59,12 +59,12 @@ "id": 6, "name": "offers-built-interactive-view", "prompt": "/architecture:map-events\n\nevents.json and events.md are written. I would like to filter and trace the messages rather than read the flowchart.", - "expected_output": "After the report, offers an interactive view of events.json in one sentence, builds it only with scripts/build-view.mjs events from the record, and resolves the publish destination from the medium cascade key.", + "expected_output": "After the report, offers an interactive view of events.json in one sentence, builds it only with scripts/build-view.mjs events from the record, and resolves the destination through the shared medium resolver, printing its report line.", "expectations": [ "events.md and events.json are written first and stay the record", "Offers the view in one sentence and builds only after the reader accepts", "Builds with scripts/build-view.mjs events --record events.json and writes no HTML or script itself", - "The publish destination comes from the medium key of the rendered-views cascade, with file as the default when unset" + "The destination comes from the shared medium resolver run for the architecture lane, and its report line is printed" ] } ] diff --git a/plugins/architecture/skills/map-flow/SKILL.md b/plugins/architecture/skills/map-flow/SKILL.md index 9cb5027b56f..09da2008cf7 100644 --- a/plugins/architecture/skills/map-flow/SKILL.md +++ b/plugins/architecture/skills/map-flow/SKILL.md @@ -175,7 +175,8 @@ End every run with this block, in this order, filled from the record and the scr After the report, offer an interactive view of `flow.json` in one sentence. The markdown and the record stay authoritative. Build it only with `${CLAUDE_PLUGIN_ROOT}/scripts/build-view.mjs flow`, -never hand-written; the publish destination comes from the `medium` cascade key. Procedure: +never hand-written; the shared medium resolver decides the destination, with this plugin's `medium` +option `${user_config.medium}`, and its report line is printed. Procedure: [`${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md`](${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md). ## What this skill does NOT do diff --git a/plugins/architecture/skills/map-flow/evals/evals.json b/plugins/architecture/skills/map-flow/evals/evals.json index d5f2a71215d..d315a7de360 100644 --- a/plugins/architecture/skills/map-flow/evals/evals.json +++ b/plugins/architecture/skills/map-flow/evals/evals.json @@ -151,12 +151,12 @@ "id": 11, "name": "offers-built-interactive-view", "prompt": "/architecture:map-flow GET /orders/{id}\n\nflow.json and flow.md are written. I would like to open each hop and its citation rather than read the sequence diagram.", - "expected_output": "After the report, offers an interactive view of flow.json in one sentence, builds it only with scripts/build-view.mjs flow from the record, and resolves the publish destination from the medium cascade key.", + "expected_output": "After the report, offers an interactive view of flow.json in one sentence, builds it only with scripts/build-view.mjs flow from the record, and resolves the destination through the shared medium resolver, printing its report line.", "expectations": [ "flow.md and flow.json are written first and stay the record", "Offers the view in one sentence and builds only after the reader accepts", "Builds with scripts/build-view.mjs flow --record flow.json and writes no HTML or script itself", - "The publish destination comes from the medium key of the rendered-views cascade, with file as the default when unset" + "The destination comes from the shared medium resolver run for the architecture lane, and its report line is printed" ] } ] diff --git a/plugins/architecture/skills/map-landscape/SKILL.md b/plugins/architecture/skills/map-landscape/SKILL.md index 82ac3c7389d..a0c8c7ff2a2 100644 --- a/plugins/architecture/skills/map-landscape/SKILL.md +++ b/plugins/architecture/skills/map-landscape/SKILL.md @@ -205,7 +205,8 @@ End every run with this block, in this order, filled from the record and the scr After the report, offer an interactive view of `landscape.json` in one sentence. The markdown and the record stay authoritative. Build it only with `${CLAUDE_PLUGIN_ROOT}/scripts/build-view.mjs landscape`, never -hand-written; the publish destination comes from the `medium` cascade key. Procedure: +hand-written; the shared medium resolver decides the destination, with this plugin's `medium` option +`${user_config.medium}`, and its report line is printed. Procedure: [`${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md`](${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md). ## What this skill does NOT do diff --git a/plugins/architecture/skills/map-landscape/evals/evals.json b/plugins/architecture/skills/map-landscape/evals/evals.json index 76b42eb0578..85d3fe7e949 100644 --- a/plugins/architecture/skills/map-landscape/evals/evals.json +++ b/plugins/architecture/skills/map-landscape/evals/evals.json @@ -204,12 +204,12 @@ "id": 14, "name": "offers-built-interactive-view", "prompt": "/architecture:map-landscape\n\nlandscape.json and the landscape artifact are written. I would like to filter and trace the systems rather than read the tables.", - "expected_output": "After the report, offers an interactive view of landscape.json in one sentence, builds it only with scripts/build-view.mjs landscape from the record, and resolves the publish destination from the medium cascade key.", + "expected_output": "After the report, offers an interactive view of landscape.json in one sentence, builds it only with scripts/build-view.mjs landscape from the record, and resolves the destination through the shared medium resolver, printing its report line.", "expectations": [ "The markdown artifact and landscape.json are written first and stay the record", "Offers the view in one sentence and builds only after the reader accepts", "Builds with scripts/build-view.mjs landscape --record landscape.json and writes no HTML or script itself", - "The publish destination comes from the medium key of the rendered-views cascade, with file as the default when unset" + "The destination comes from the shared medium resolver run for the architecture lane, and its report line is printed" ] } ] diff --git a/plugins/debugging/reference/rendered-view.md b/plugins/debugging/reference/rendered-view.md index 783de8783d8..0c15ea0831f 100644 --- a/plugins/debugging/reference/rendered-view.md +++ b/plugins/debugging/reference/rendered-view.md @@ -4,7 +4,8 @@ edit the canonical source, then rerun the script. --> # Rendered views of a skill's record How a view lane offers an interactive view of the record its skill wrote. The lanes that carry this file: -planning (`/planning:plan`, `/planning:brainstorm`, `/planning:design`), architecture (the `map-*` skills), discovery +planning (`/planning:plan`, `/planning:brainstorm`, `/planning:design`), architecture (the `map-*` skills +and the `/architecture:improve` deepening report), discovery (`/discovery:blindspot`) and debugging (`/debugging:debug`). Each lane's section below names its record, build command and data shape. `` is the plugin's root directory, the one that holds `.claude-plugin/`: the path the calling skill gave for this file, cut before its first `skills/` or @@ -25,23 +26,26 @@ script written in the session. 2. **Offer the view in one sentence.** Build only when the reader accepts and the environment can serve a file. A CI or other non-interactive run emits no view: the record stands. 3. **Resolve `medium`.** The path depends on whether the lane's skill has migrated to the shared medium - resolver, not on whether the resolver registers the lane. `planning` and `debugging` have migrated; - architecture and discovery are registered but read the cascade themselves until their own change - migrates them. - - **Resolver lanes** (`planning`). The lane's build command runs the resolver, the publish gate and - delivery in one call: follow its section in place of steps 3 and 5, and step 4's rule for a missing - `node` or a non-zero exit still applies. Do not read the rendered-views convention files yourself. - - **Resolver lanes** (`debugging`). Run the resolver. `--option` takes this plugin's `medium` option as the - calling skill states it; add `--argument` only when the reader named a medium in the request: - - ```bash - node "/lib/view-settings.mjs" resolve --lane --option "" [--argument terminal|file|artifact] - ``` - - It prints one JSON line, then the report line naming the medium and what decided it, then any notice; - print those lines as they stand. The JSON's `medium` is the one to use: `terminal`, `file` or `artifact`. - Do not read the rendered-views convention files yourself. When `node` is missing, the builder cannot run - either: deliver the record. + resolver, not on whether the resolver registers the lane. `planning`, `architecture` and `debugging` + have migrated; discovery is registered but reads the cascade itself until its own change migrates it. + - **Resolver lanes** (`planning`, `architecture`, `debugging`). Do not read the rendered-views convention + files yourself. + - `planning`: the lane's build command runs the resolver, the publish gate and delivery in one call: + follow its section in place of steps 3 and 5, and step 4's rule for a missing `node` or a non-zero + exit still applies. + - `architecture`, `debugging`: run the resolver with the `--lane` its section names. `--option` takes + this plugin's `medium` option as the calling skill states it; add `--argument` only when the reader + named a medium in the request: + + ```bash + node "/lib/view-settings.mjs" resolve --lane --option "" [--argument terminal|file|artifact] + ``` + + It prints one JSON line, then the report line naming the medium and what decided it, then any notice; + print those lines as they stand. The JSON's `medium` is the one to use: `terminal`, `file` or + `artifact`. When `node` is missing, the builder cannot run either: deliver the record. When the + resolver exits 2 with its usage line, the argument names no medium: report it as unknown and resolve + again without `--argument`. - **Other lanes.** Read the `rendered-views` cascade surface: `~/.claude/rendered-views.md`, then `/.claude/rendered-views.md`, then `/.claude/rendered-views.local.md`, whichever exist. The last layer that states `medium:` wins (`auto`, `terminal`, `file`, `artifact`). A team layer @@ -205,6 +209,7 @@ with no `## Design` section exits 1. The `map-*` skills record a markdown file and a JSON record; both stay authoritative. A record holds manifest paths, connection hosts, type names and file citations. Write the record and its markdown first. +Resolver lane: `--lane architecture`. Build: pass the record file to the builder. The first argument is the skill's kind, and the record is the file in the table below: @@ -240,6 +245,19 @@ other row takes the first of `id`, `name`, `message`, `title`, `path`, `entry`, field it holds, evidence citations included. The filter matches a row's whole text, so typing a node id lists the node and every edge, finding and cycle that names it. The page draws no diagram: the markdown holds that. +### The deepening report + +`/architecture:improve deepening` writes its HTML report itself, not through the builder, and only ever as a +local file. Before writing it, resolve `medium` as step 3 does, passing the skill's `--medium` value as +`--argument`, and print the resolver's lines. When the resolver exits 2 with its usage line, the +`--medium` value names no medium: report it as unknown and resolve again without `--argument`. Then, by +the JSON's `medium`: + +- `terminal`: write no report. The durable candidate artifact and the reply are the deliverable. +- `file`: write the local report. +- `artifact`: write the local report. This lane publishes nothing, so say that a publishing value was read + as `file`. + ## Discovery: blindspot `/discovery:blindspot` records the blindspot cards and the improved prompt as written in the conversation, diff --git a/plugins/discovery/reference/rendered-view.md b/plugins/discovery/reference/rendered-view.md index 783de8783d8..0c15ea0831f 100644 --- a/plugins/discovery/reference/rendered-view.md +++ b/plugins/discovery/reference/rendered-view.md @@ -4,7 +4,8 @@ edit the canonical source, then rerun the script. --> # Rendered views of a skill's record How a view lane offers an interactive view of the record its skill wrote. The lanes that carry this file: -planning (`/planning:plan`, `/planning:brainstorm`, `/planning:design`), architecture (the `map-*` skills), discovery +planning (`/planning:plan`, `/planning:brainstorm`, `/planning:design`), architecture (the `map-*` skills +and the `/architecture:improve` deepening report), discovery (`/discovery:blindspot`) and debugging (`/debugging:debug`). Each lane's section below names its record, build command and data shape. `` is the plugin's root directory, the one that holds `.claude-plugin/`: the path the calling skill gave for this file, cut before its first `skills/` or @@ -25,23 +26,26 @@ script written in the session. 2. **Offer the view in one sentence.** Build only when the reader accepts and the environment can serve a file. A CI or other non-interactive run emits no view: the record stands. 3. **Resolve `medium`.** The path depends on whether the lane's skill has migrated to the shared medium - resolver, not on whether the resolver registers the lane. `planning` and `debugging` have migrated; - architecture and discovery are registered but read the cascade themselves until their own change - migrates them. - - **Resolver lanes** (`planning`). The lane's build command runs the resolver, the publish gate and - delivery in one call: follow its section in place of steps 3 and 5, and step 4's rule for a missing - `node` or a non-zero exit still applies. Do not read the rendered-views convention files yourself. - - **Resolver lanes** (`debugging`). Run the resolver. `--option` takes this plugin's `medium` option as the - calling skill states it; add `--argument` only when the reader named a medium in the request: - - ```bash - node "/lib/view-settings.mjs" resolve --lane --option "" [--argument terminal|file|artifact] - ``` - - It prints one JSON line, then the report line naming the medium and what decided it, then any notice; - print those lines as they stand. The JSON's `medium` is the one to use: `terminal`, `file` or `artifact`. - Do not read the rendered-views convention files yourself. When `node` is missing, the builder cannot run - either: deliver the record. + resolver, not on whether the resolver registers the lane. `planning`, `architecture` and `debugging` + have migrated; discovery is registered but reads the cascade itself until its own change migrates it. + - **Resolver lanes** (`planning`, `architecture`, `debugging`). Do not read the rendered-views convention + files yourself. + - `planning`: the lane's build command runs the resolver, the publish gate and delivery in one call: + follow its section in place of steps 3 and 5, and step 4's rule for a missing `node` or a non-zero + exit still applies. + - `architecture`, `debugging`: run the resolver with the `--lane` its section names. `--option` takes + this plugin's `medium` option as the calling skill states it; add `--argument` only when the reader + named a medium in the request: + + ```bash + node "/lib/view-settings.mjs" resolve --lane --option "" [--argument terminal|file|artifact] + ``` + + It prints one JSON line, then the report line naming the medium and what decided it, then any notice; + print those lines as they stand. The JSON's `medium` is the one to use: `terminal`, `file` or + `artifact`. When `node` is missing, the builder cannot run either: deliver the record. When the + resolver exits 2 with its usage line, the argument names no medium: report it as unknown and resolve + again without `--argument`. - **Other lanes.** Read the `rendered-views` cascade surface: `~/.claude/rendered-views.md`, then `/.claude/rendered-views.md`, then `/.claude/rendered-views.local.md`, whichever exist. The last layer that states `medium:` wins (`auto`, `terminal`, `file`, `artifact`). A team layer @@ -205,6 +209,7 @@ with no `## Design` section exits 1. The `map-*` skills record a markdown file and a JSON record; both stay authoritative. A record holds manifest paths, connection hosts, type names and file citations. Write the record and its markdown first. +Resolver lane: `--lane architecture`. Build: pass the record file to the builder. The first argument is the skill's kind, and the record is the file in the table below: @@ -240,6 +245,19 @@ other row takes the first of `id`, `name`, `message`, `title`, `path`, `entry`, field it holds, evidence citations included. The filter matches a row's whole text, so typing a node id lists the node and every edge, finding and cycle that names it. The page draws no diagram: the markdown holds that. +### The deepening report + +`/architecture:improve deepening` writes its HTML report itself, not through the builder, and only ever as a +local file. Before writing it, resolve `medium` as step 3 does, passing the skill's `--medium` value as +`--argument`, and print the resolver's lines. When the resolver exits 2 with its usage line, the +`--medium` value names no medium: report it as unknown and resolve again without `--argument`. Then, by +the JSON's `medium`: + +- `terminal`: write no report. The durable candidate artifact and the reply are the deliverable. +- `file`: write the local report. +- `artifact`: write the local report. This lane publishes nothing, so say that a publishing value was read + as `file`. + ## Discovery: blindspot `/discovery:blindspot` records the blindspot cards and the improved prompt as written in the conversation, diff --git a/plugins/planning/reference/rendered-view.md b/plugins/planning/reference/rendered-view.md index 783de8783d8..0c15ea0831f 100644 --- a/plugins/planning/reference/rendered-view.md +++ b/plugins/planning/reference/rendered-view.md @@ -4,7 +4,8 @@ edit the canonical source, then rerun the script. --> # Rendered views of a skill's record How a view lane offers an interactive view of the record its skill wrote. The lanes that carry this file: -planning (`/planning:plan`, `/planning:brainstorm`, `/planning:design`), architecture (the `map-*` skills), discovery +planning (`/planning:plan`, `/planning:brainstorm`, `/planning:design`), architecture (the `map-*` skills +and the `/architecture:improve` deepening report), discovery (`/discovery:blindspot`) and debugging (`/debugging:debug`). Each lane's section below names its record, build command and data shape. `` is the plugin's root directory, the one that holds `.claude-plugin/`: the path the calling skill gave for this file, cut before its first `skills/` or @@ -25,23 +26,26 @@ script written in the session. 2. **Offer the view in one sentence.** Build only when the reader accepts and the environment can serve a file. A CI or other non-interactive run emits no view: the record stands. 3. **Resolve `medium`.** The path depends on whether the lane's skill has migrated to the shared medium - resolver, not on whether the resolver registers the lane. `planning` and `debugging` have migrated; - architecture and discovery are registered but read the cascade themselves until their own change - migrates them. - - **Resolver lanes** (`planning`). The lane's build command runs the resolver, the publish gate and - delivery in one call: follow its section in place of steps 3 and 5, and step 4's rule for a missing - `node` or a non-zero exit still applies. Do not read the rendered-views convention files yourself. - - **Resolver lanes** (`debugging`). Run the resolver. `--option` takes this plugin's `medium` option as the - calling skill states it; add `--argument` only when the reader named a medium in the request: - - ```bash - node "/lib/view-settings.mjs" resolve --lane --option "" [--argument terminal|file|artifact] - ``` - - It prints one JSON line, then the report line naming the medium and what decided it, then any notice; - print those lines as they stand. The JSON's `medium` is the one to use: `terminal`, `file` or `artifact`. - Do not read the rendered-views convention files yourself. When `node` is missing, the builder cannot run - either: deliver the record. + resolver, not on whether the resolver registers the lane. `planning`, `architecture` and `debugging` + have migrated; discovery is registered but reads the cascade itself until its own change migrates it. + - **Resolver lanes** (`planning`, `architecture`, `debugging`). Do not read the rendered-views convention + files yourself. + - `planning`: the lane's build command runs the resolver, the publish gate and delivery in one call: + follow its section in place of steps 3 and 5, and step 4's rule for a missing `node` or a non-zero + exit still applies. + - `architecture`, `debugging`: run the resolver with the `--lane` its section names. `--option` takes + this plugin's `medium` option as the calling skill states it; add `--argument` only when the reader + named a medium in the request: + + ```bash + node "/lib/view-settings.mjs" resolve --lane --option "" [--argument terminal|file|artifact] + ``` + + It prints one JSON line, then the report line naming the medium and what decided it, then any notice; + print those lines as they stand. The JSON's `medium` is the one to use: `terminal`, `file` or + `artifact`. When `node` is missing, the builder cannot run either: deliver the record. When the + resolver exits 2 with its usage line, the argument names no medium: report it as unknown and resolve + again without `--argument`. - **Other lanes.** Read the `rendered-views` cascade surface: `~/.claude/rendered-views.md`, then `/.claude/rendered-views.md`, then `/.claude/rendered-views.local.md`, whichever exist. The last layer that states `medium:` wins (`auto`, `terminal`, `file`, `artifact`). A team layer @@ -205,6 +209,7 @@ with no `## Design` section exits 1. The `map-*` skills record a markdown file and a JSON record; both stay authoritative. A record holds manifest paths, connection hosts, type names and file citations. Write the record and its markdown first. +Resolver lane: `--lane architecture`. Build: pass the record file to the builder. The first argument is the skill's kind, and the record is the file in the table below: @@ -240,6 +245,19 @@ other row takes the first of `id`, `name`, `message`, `title`, `path`, `entry`, field it holds, evidence citations included. The filter matches a row's whole text, so typing a node id lists the node and every edge, finding and cycle that names it. The page draws no diagram: the markdown holds that. +### The deepening report + +`/architecture:improve deepening` writes its HTML report itself, not through the builder, and only ever as a +local file. Before writing it, resolve `medium` as step 3 does, passing the skill's `--medium` value as +`--argument`, and print the resolver's lines. When the resolver exits 2 with its usage line, the +`--medium` value names no medium: report it as unknown and resolve again without `--argument`. Then, by +the JSON's `medium`: + +- `terminal`: write no report. The durable candidate artifact and the reply are the deliverable. +- `file`: write the local report. +- `artifact`: write the local report. This lane publishes nothing, so say that a publishing value was read + as `file`. + ## Discovery: blindspot `/discovery:blindspot` records the blindspot cards and the improved prompt as written in the conversation, diff --git a/scripts/view-medium-list-exemptions.txt b/scripts/view-medium-list-exemptions.txt index 642baf52b4f..546b0041f7c 100644 --- a/scripts/view-medium-list-exemptions.txt +++ b/scripts/view-medium-list-exemptions.txt @@ -6,5 +6,4 @@ # more, or that names no registered lane, so the list can only shrink: the slice # that removes a lane's list deletes its row. -architecture # #12672 architecture slice visualization:visualize # #12669 visualization slice