@documentation-robotics/cli 0.3.0 → 0.4.0

package/dist/integrations/claude_code/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "dr",
+  "version": "0.4.0",
+  "description": "Documentation Robotics for Claude Code: the dr MCP server (it serves the project you have open), /dr-plan for planning a change as a staged changeset, the DR layer skills, and the dr-architect and dr-advisor agents. Needs the dr CLI on PATH (npm install -g @documentation-robotics/cli).",
+  "author": {
+    "name": "Documentation Robotics",
+    "url": "https://github.com/tinkermonkey/documentation_robotics"
+  },
+  "homepage": "https://github.com/tinkermonkey/documentation_robotics",
+  "repository": "https://github.com/tinkermonkey/documentation_robotics",
+  "license": "MIT",
+  "keywords": ["architecture", "changesets", "mcp", "planning"],
+  "commands": ["./commands/dr-plan.md"],
+  "agents": [
+    "./plugin-agents/dr-architect.md",
+    "./plugin-agents/dr-advisor.md"
+  ],
+  "mcpServers": {
+    "dr": {
+      "command": "dr",
+      "args": ["mcp"]
+    }
+  }
+}

package/dist/integrations/claude_code/agents/dr-architect.md

@@ -1,7 +1,7 @@
 ---
 name: dr-architect
 description: Comprehensive Documentation Robotics architect and implementer. Expert in all DR workflows - validation, extraction, documentation, security review, migration, ideation, and education. Intelligent intent-based routing with adaptive autonomy. Single agent that handles everything related to DR models.
-tools: Bash, Read, Edit, Write, Glob, Grep, WebSearch, WebFetch, mcp__dr__model_list, mcp__dr__model_show, mcp__dr__model_search, mcp__dr__model_stats, mcp__dr__model_info, mcp__dr__model_trace, mcp__dr__model_validate, mcp__dr__model_export, mcp__dr__model_reload, mcp__dr__changeset_list, mcp__dr__changeset_show, mcp__dr__changeset_create, mcp__dr__changeset_activate, mcp__dr__changeset_deactivate, mcp__dr__changeset_impact, mcp__dr__changeset_brief, mcp__dr__changeset_verify, mcp__dr__changeset_update, mcp__dr__changeset_unstage, mcp__dr__spec_type, mcp__dr__model_add, mcp__dr__model_update, mcp__dr__model_delete, mcp__dr__relationship_add, mcp__dr__relationship_delete, mcp__dr__annotation_list, mcp__dr__annotation_get, mcp__dr__chat_status
+tools: Bash, Read, Edit, Write, Glob, Grep, WebSearch, WebFetch, mcp__dr__model_list, mcp__dr__model_show, mcp__dr__model_search, mcp__dr__model_stats, mcp__dr__model_info, mcp__dr__model_trace, mcp__dr__model_validate, mcp__dr__model_export, mcp__dr__model_reload, mcp__dr__changeset_list, mcp__dr__changeset_show, mcp__dr__changeset_create, mcp__dr__changeset_activate, mcp__dr__changeset_deactivate, mcp__dr__changeset_impact, mcp__dr__changeset_brief, mcp__dr__changeset_verify, mcp__dr__changeset_update, mcp__dr__changeset_unstage, mcp__dr__spec_type, mcp__dr__model_add, mcp__dr__model_update, mcp__dr__model_delete, mcp__dr__relationship_add, mcp__dr__relationship_delete, mcp__dr__annotation_list, mcp__dr__annotation_get, mcp__dr__chat_status, mcp__dr__project_status
 color: orange
 ---
 
@@ -22,7 +22,7 @@ You are the **DR Architect** — a unified expert in Documentation Robotics. You
 
 ## Tools
 
-- **dr MCP tools** (`mcp__dr__*`, when the `dr` MCP server is connected, as it is in the `dr visualize` chat): prefer these to running `dr` through Bash. See **Working through the dr MCP server** below.
+- **dr MCP tools** (`mcp__dr__*`): the dr MCP server's tools, when it is connected. Prefer these to running `dr` through Bash. See **Working through the dr MCP server** below.
 - **Bash**: DR CLI commands (`dr add`, `dr validate`, `dr changeset`, etc.); the fallback when the MCP tools are not available
 - **Read/Glob/Grep**: Read source code and model files
 - **WebSearch/WebFetch**: Research technologies and patterns
@@ -33,13 +33,27 @@ You are the **DR Architect** — a unified expert in Documentation Robotics. You
 When the `mcp__dr__*` tools are available, plan a change as a staged changeset with them instead of `dr` commands:
 
 1. **Look first**: `model_search`, `model_show`, `model_list` to find what exists; `spec_type` to see what a type requires and which relationships the catalog allows from it.
-2. **Open a changeset**: `changeset_create` with a short name for the change (it activates the new changeset). `changeset_list` / `changeset_activate` resume an existing one.
-3. **Stage the change**: `model_add`, `model_update`, `model_delete`, `relationship_add`, `relationship_delete`. With a changeset active these stage instead of writing the model, and relationships may join elements the changeset itself adds. `changeset_update` renames or re-describes the changeset and `changeset_unstage` drops a staged change. Discarding a changeset is the user's step.
-4. **Pressure-test it**: `changeset_impact` for what the change touches, `changeset_brief` for a review summary. Fix what they surface, then report the brief to the user. Once code is built, `changeset_verify` compares the plan with what was built.
+2. **Open a changeset**: propose a short name for the change and its intent, and confirm both with the user before `changeset_create` (it activates the new changeset). `changeset_list` / `changeset_activate` resume an existing one.
+3. **Stage the change**: `model_add`, `model_update`, `model_delete`, `relationship_add`, `relationship_delete`. With a changeset active these stage instead of writing the model, and relationships may join elements the changeset itself adds. When you wire several, use the lists: `model_add` with `elements: [...]` (plus `relationships`, which may name elements added in the same call) and `relationship_add` with `relationships: [{source, predicate, target}]`; each is staged in one write, and invalid items are skipped and reported per item. A planned element with no code yet gets no source fields. `changeset_update` renames or re-describes the changeset and `changeset_unstage` drops a staged change. Discarding a changeset is the user's step.
+4. **Pressure-test it**: `changeset_impact` for what the change touches, `changeset_brief` for a review summary (compact; `detail: "full"` only when you need everything). Fix what they surface, then report the brief to the user. Once code is built, `changeset_verify` compares the plan with what was built.
 5. **Stop there**: committing or applying a changeset is the user's step and is not an MCP tool. Tell the user the changeset is ready for review.
 
 Some sessions only allow changes through a changeset: a write with no active changeset is refused with a message saying to call `changeset_create` first. Do that and retry; don't fall back to Bash or to editing files.
 
+## Running dr through Bash
+
+When you run `dr` through Bash, run **one `dr` command per Bash call**, and use JSON output (`--json`, or `--format json` where a command takes `--format`) when you need to read the result. Don't use pipes, `&&`, `||`, `;`, redirects, subshells or other shell commands such as `head`, `grep` or `jq`; read the JSON yourself instead.
+
+The `dr visualize` chat allows each `dr` command by name and nothing else, and nobody can answer a permission prompt there. Any extra shell in a call needs approval, so the whole call is denied. To do several things, make several calls.
+
+```bash
+# ✅ correct: one command per call
+dr list api --json
+dr search order --layer api --json
+```
+
+❌ Denied in the chat: a pipe (`dr list api | head`), a chain (`dr validate && dr list api`) and a redirect (`dr list api > /tmp/api.txt`).
+
 ## The 12-Layer Model
 
 ```

package/dist/integrations/claude_code/agents/dr-extractor.md

@@ -1,11 +1,17 @@
 ---
 name: dr-extractor
-description: Specialized extraction agent for Documentation Robotics model creation from codebases. Analyzes source code to identify architectural elements across all 13 layers with mandatory source provenance tracking.
+description: "Deprecated: use the codebase_extract MCP tool. Specialized extraction agent for Documentation Robotics model creation from codebases. Analyzes source code to identify architectural elements across all 13 layers with mandatory source provenance tracking."
 tools: Bash, Read, Glob, Grep
 ---
 
 # Documentation Robotics Extraction Agent
 
+> **Deprecated.** The `codebase_extract` tool on the `dr` MCP server replaces this agent. It runs
+> the extraction cascade on the indexed code (`codebase_index` first) and stages the result in an
+> as-built changeset, never the base model: the Tier-0 rules stage what they decide, and the calling
+> agent stages the symbols they can't place, from the cards it returns, with `model_add`. Use it
+> instead of driving `dr add` through Bash. This agent still works but is no longer maintained.
+
 ## Identity
 
 You are the **DR Extractor** — a code analysis specialist focused exclusively on extracting architectural elements from codebases and creating Documentation Robotics model entries. You operate entirely through the `dr add` command line interface, never creating YAML or JSON directly.

package/dist/integrations/claude_code/commands/dr-changeset.md

@@ -528,7 +528,8 @@ dr changeset preview                 # Preview staged changes merged with model
 dr changeset create "name"           # Create new changeset
 dr changeset activate <name>         # Activate a changeset (auto-stages changes)
 dr changeset deactivate              # Deactivate the active changeset
-dr changeset commit                  # Commit staged changes to model
+dr changeset commit                  # Commit the active changeset's staged changes to model
+dr changeset commit <name>           # Commit the changeset named (need not be active)
 dr changeset discard                 # Abandon all staged changes
 
 # Export and import

package/dist/integrations/claude_code/commands/dr-map.md

@@ -1,10 +1,16 @@
 ---
-description: Analyze an existing codebase and automatically generate a Documentation Robotics architecture model
+description: "Deprecated: use the codebase_extract MCP tool. Analyze an existing codebase and generate a Documentation Robotics architecture model"
 argument-hint: "<path> [--layers <layers>] [--tech <technology>] [--recipe | --targeted]"
 ---
 
 # Extract Architecture Model from Codebase
 
+> **Deprecated.** Use the `codebase_extract` tool on the `dr` MCP server instead. It runs the
+> extraction cascade on the indexed code (`codebase_index` first): the Tier-0 rules stage what they
+> decide, and the symbols they can't place come back to you as cards to stage with `model_add`.
+> Everything lands in an as-built changeset, never the base model, for the user to review and
+> commit. This command still works but is no longer maintained.
+
 Analyze an existing codebase and automatically generate a Documentation Robotics architecture model.
 
 ## What This Command Does

package/dist/integrations/claude_code/commands/dr-plan.md

@@ -9,32 +9,58 @@ Plan `$ARGUMENTS` as a staged DR changeset instead of a prose plan.
 
 ## Instructions for Claude Code
 
-Follow the `dr_change_planning` skill (`.claude/skills/dr_change_planning/SKILL.md`) for this change.
+Follow the `dr_change_planning` skill for this change.
 In short:
 
-1. **Frame**: `changeset_create` with a kebab-case name and the change's intent as the description
-   (or `changeset_activate` an existing one). Find or stage the goal, requirement or feature it
-   serves.
+1. **Frame**: propose a kebab-case name and the change's intent, and confirm both with the human
+   before `changeset_create` uses them as the name and description (or `changeset_activate` an
+   existing one). Wait for their answer. Find or stage the goal, requirement or feature it serves.
+   With no model yet, confirm the model's name before `project_init`, and ask whether to bootstrap
+   it from the code or let it grow with each change.
 2. **Orient**: `model_search`, `model_show`, `model_trace` for what exists; `spec_type` for each
    type you will add. Within reason, every connection the spec models for a type is expected,
    though not every one will exist.
 3. **Draft**: `model_add` / `model_update` / `model_delete` / `relationship_add` /
-   `relationship_delete` across every layer the change reaches. `model_update` with
+   `relationship_delete` across every layer the change reaches. Wire several at once with the
+   lists: `model_add` `elements: [...]` (with `relationships` among them) and `relationship_add`
+   `relationships: [...]`; invalid items are skipped and reported. A planned element with no code
+   yet gets no source fields. `model_update` with
    `attributePatch` to change one attribute; `changeset_unstage` to back out (`source` or `target`
-   alone drops every staged connection at that end).
-4. **Pressure-test**: `changeset_brief` and `changeset_impact`. Answer each gap by staging what is
+   alone drops every staged connection at that end; `changes: [...]` drops several in one call).
+4. **Pressure-test**: `changeset_brief` (compact; `detail: "full"` only when you need everything)
+   and `changeset_impact`. Answer each gap by staging what is
    missing, or accept it and say why in an annotation or the description. Steps 3 and 4 repeat:
    stage a little, then pass the brief's `revisionToken` back as `since` to see what changed, work
-   through `unwired`, and walk `changeset_impact` with `from` set to what you just added.
-5. **Review**: show the human the brief and ask them to review it in `dr visualize`. Read
-   `annotation_list`, reply, revise. Wait for agreement before building.
-6. **Build** from the brief. Commit only the plan's own changeset directory
+   through `unwired` (list it with `sections: ["unwired"], unwiredLayers: [...]`, naming the layers
+   the change reaches; always pass a filter), and walk `changeset_impact` with `from` set to what
+   you just added.
+5. **Review**: show the human the brief, then call `review_open` and give them its `url`, which
+   opens the plan on the graph in the viewer. The human comments there; read the comments with
+   `annotation_list`, answer with `annotation_reply`, revise. Wait for agreement before building.
+6. **Build** from the brief: `changeset_brief` with `sections: ["changes"]` for each changed
+   element's attributes and connections (for a large plan, one layer at a time with
+   `layers: ["<layer>"]`, from the default brief's `byLayer`). Commit only the plan's own changeset directory
    (`documentation-robotics/changesets/<id>/`) on the branch with the code; keep `.active` and the
-   as-built changeset out of the commit.
-7. **Verify**: stage an `<name>-as-built` changeset from the diff, then `changeset_verify` the plan
-   against it. Fix what diverges, in the code or in the plan.
-8. **Land**: the human commits the changeset in the PR. Never commit, apply or discard the plan
-   yourself.
+   as-built changeset out of the commit. Don't verify during the build: no `codebase_extract`, no
+   as-built changeset and no `changeset_verify` until the build is committed.
+7. **Verify**, as its own step after the build is committed: `codebase_index` with `wait: 30`
+   (then `status: true`, `wait: 30` until it is done; if it reports `ignoreFile`, tell the developer
+   to commit that file), then `codebase_extract`
+   with `since` (the branch the work started from) and `changeset: "<name>-as-built"`. Stage the
+   cards it returns that are elements with `model_add` (`sourceProvenance: "extracted"`), call it again for their relationships, then
+   `changeset_verify` the plan against `<name>-as-built`. The as-built comes from `codebase_extract`,
+   never by hand: never copy plan elements into it, and name each element after its card, not the
+   plan. Ask the developer about the cards you can't place with confidence, batched in one short
+   list, instead of guessing. Fix what diverges, in the code or in the plan, and `changeset_activate`
+   the plan again. `unverifiable` items (what extraction can't see) and `notes` (description-only
+   differences) need no plan edit; never edit the plan to match extracted placeholder text. Then the
+   plan is what lands; ask the human whether to discard the as-built changeset or keep it as a
+   record. Landing the as-built first drifts the plan's base, so the plan would need `force`.
+8. **Land**: the human commits the plan in the PR, not the as-built changeset. When they ask you to land it, call
+   `changeset_commit`; they confirm it in a dialog, and it commits only then. If it is refused, they
+   land it in the viewer (`review_open`, then Apply), or you call it again from an interactive
+   session; never point them to the `dr` CLI. Never commit unasked, and never apply
+   or discard the plan yourself.
 
 If the `dr` MCP tools are not available, say so and point the user to
 `integrations/claude_code/docs/MCP_SERVER.md`.

package/dist/integrations/claude_code/docs/MCP_SERVER.md

@@ -19,61 +19,58 @@ Annotation tools (`annotation_list`, `annotation_get`, `annotation_create`, `ann
 | Changesets               | `changeset_list`, `changeset_show`, `changeset_create`, `changeset_activate`, `changeset_deactivate`, `changeset_update`, `changeset_unstage`, `changeset_discard` |
 | Pressure-test and verify | `changeset_brief`, `changeset_impact`, `changeset_verify`                                                                                                          |
 | Annotations              | `annotation_list`, `annotation_get`, `annotation_create`, `annotation_update`, `annotation_delete`, `annotation_reply`                                             |
+| Review                   | `review_open` (a link that opens a changeset in the viewer; reuses or starts `dr visualize`)                                                                       |
 | Chat                     | `chat_launch`, `chat_status`                                                                                                                                       |
 
 With a changeset active, the "change the model" tools stage into it, and the read tools show the model as the changeset leaves it. Committing or applying a changeset is not a tool: the human does that in the viewer or with `dr changeset commit`. `changeset_discard` deletes staged changes for good, so it needs the changeset named explicitly (id or name) and `confirm: true`.
 
 To plan a change with these tools, use `/dr-plan` (or the `dr_change_planning` skill). The design is in [`docs/CHANGE_MODELING.md`](../../../docs/CHANGE_MODELING.md).
 
-## Environment
+## Installing in Claude Code
 
-| Variable            | Effect                                                                                                                                                                                        |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DR_MCP_API_KEY`    | Required. The key `dr mcp` prints on start.                                                                                                                                                   |
-| `DR_MCP_ROOT_PATH`  | Serve the model at this path instead of the working directory. An unusable path is reported on stderr and the server keeps its own directory.                                                 |
-| `DR_CHANGESET_ONLY` | `true`/`1`/`yes`/`on` refuses model writes unless a staged changeset is active (an unrecognised value also turns it on, with a warning). DrBot sets it with `dr visualize --with-changesets`. |
+Install the `dr` plugin once per machine. It registers the MCP server for every project and adds `/dr-plan` and the DR skills. It needs the `dr` CLI on `PATH`:
 
-## Configuring Claude Code
+```bash
+npm install -g @documentation-robotics/cli
+claude plugin marketplace add tinkermonkey/documentation_robotics
+claude plugin install dr@documentation-robotics
+```
 
-Add an entry to your project's `.mcp.json` (or the equivalent global MCP config). Name the server `dr`: the DR agents and DrBot refer to its tools as `mcp__dr__<tool>`.
+Inside a session, `/plugin marketplace add tinkermonkey/documentation_robotics` and `/plugin install dr@documentation-robotics` do the same.
+
+The server serves the project the session has open: it asks Claude Code for its MCP roots (the folder the session started in) and moves there, so one registration covers every project. Tool calls can still pass `rootPath` to work on another project. From the plugin, the tools are named `mcp__plugin_dr_dr__<tool>`.
+
+The plugin also ships the `dr:dr-architect` and `dr:dr-advisor` agents, with tool lists that use those names. See [Agents in the plugin](README.md#agents-in-the-plugin).
+
+### Registering the server by hand
+
+Without the plugin, add the server to a project's `.mcp.json` (or your user-scope MCP config). Name it `dr`, so its tools are `mcp__dr__<tool>`, which the `dr-architect` agent and DrBot expect:
 
 ```json
 {
   "mcpServers": {
     "dr": {
       "command": "dr",
-      "args": ["mcp"],
-      "env": {
-        "DR_MCP_API_KEY": "<key printed by dr mcp>"
-      }
+      "args": ["mcp"]
     }
   }
 }
 ```
 
-Other MCP clients follow the same shape: a `command`/`args` pair that launches `dr mcp`, plus `DR_MCP_API_KEY` in `env`.
-
-## Getting the API key
+Other MCP clients follow the same shape: a `command`/`args` pair that launches `dr mcp`. Over stdio there is no API key: the client starts the server as your own user, and that user can already read the model files. An older config that still sets `DR_MCP_API_KEY` keeps working; the server ignores it.
 
-Run `dr mcp` once from a terminal — it generates an API key on first launch (prompting for a storage path interactively, defaulting to `~/.dr-mcp-key` otherwise) and prints it to stderr on every launch:
-
-```
-$ dr mcp
-Generated new MCP API key, stored at /home/you/.dr-mcp-key
-MCP API key: dr-mcp-<random>
-Documentation Robotics MCP server ready (stdio)
-```
-
-Copy that key into the client config's `DR_MCP_API_KEY`. The server rejects the connection if the key is missing or doesn't match.
+## Environment
 
-## Rotating the key
+| Variable            | Effect                                                                                                                                                                                        |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DR_MCP_ROOT_PATH`  | Serve the model at this path instead of the client's roots or the working directory. An unusable path is reported on stderr and the server keeps its own directory.                           |
+| `DR_CHANGESET_ONLY` | `true`/`1`/`yes`/`on` refuses model writes unless a staged changeset is active (an unrecognised value also turns it on, with a warning). DrBot sets it with `dr visualize --with-changesets`. |
+| `DR_MCP_QUIET_KEY`  | HTTP transport only: don't print the API key to stderr on start.                                                                                                                              |
 
-If a key leaks or you just want a fresh one, run:
+## HTTP transport and the API key
 
-```bash
-dr mcp --regenerate-key
-```
+`dr mcp --transport http` serves MCP at `http://127.0.0.1:3100/mcp` for clients that connect over the network. HTTP clients authenticate with the API key as a bearer token (`Authorization: Bearer <key>`). The server generates the key on first launch (prompting for a storage path interactively, defaulting to `~/.dr-mcp-key` otherwise) and prints it to stderr on every launch.
 
-This overwrites the key at its existing storage path, updates `~/.dr-config.yaml`, and prints the new key — no manual deletion of files required. Update `DR_MCP_API_KEY` in every client config after rotating.
+To rotate the key, run `dr mcp --regenerate-key`. It overwrites the key at its existing storage path, updates `~/.dr-config.yaml` and prints the new key. Update every HTTP client afterwards.
 
 See [cli/README.md](../../../cli/README.md#mcp-server) for the full command reference.

package/dist/integrations/claude_code/docs/README.md

@@ -82,7 +82,7 @@ The comprehensive manual walkthrough covering every step from fresh project thro
 
 ### MCP Integration
 
-- **[MCP_SERVER.md](MCP_SERVER.md)** — Configure an MCP client (Claude Code or otherwise) to connect to `dr mcp`, including the API key setup and rotation
+- **[MCP_SERVER.md](MCP_SERVER.md)** — Configure an MCP client (Claude Code or otherwise) to connect to `dr mcp`, over stdio (no key) or HTTP (API key setup and rotation)
 
 ### Skills & Agents
 
@@ -90,6 +90,25 @@ The comprehensive manual walkthrough covering every step from fresh project thro
 - **[dr-codebase-memory/SKILL.md](../skills/dr_codebase_memory/SKILL.md)** — Codebase memory and context management
 - Layer-specific skills (Layer 1-13)
 
+### Agents in the plugin
+
+The `dr` plugin ships two agents, `dr:dr-architect` and `dr:dr-advisor`. `dr-extractor` is not in the plugin: the `codebase_extract` tool replaces it.
+
+- **Sources.** Each agent has one source in [`agents/`](../agents/). `dr claude install` copies the sources into a project's `.claude/agents`, where they name the dr tools `mcp__dr__<tool>` (a server registered as `dr`).
+- **Plugin copies.** Inside the plugin the same tools are named `mcp__plugin_dr_dr__<tool>`. `scripts/build-plugin-agents.ts` writes the plugin's copies to [`plugin-agents/`](../plugin-agents/) with the tool names rewritten, and drops frontmatter that plugin agents ignore (`hooks`, `mcpServers`, `permissionMode`, `initialPrompt`). Tool lists stay explicit, so `dr-advisor` stays read-only. `plugin.json` lists the copies.
+- **Regenerate** after editing a source, from the repo root, and commit both files (the plugin installs from git):
+
+  ```bash
+  npm run build:plugin-agents
+  npm run check:plugin-agents   # fails when a copy has drifted; CI runs it
+  ```
+
+Don't edit `plugin-agents/` by hand.
+
+**Which `dr-architect` runs.** Claude Code reads every `.md` under `.claude/agents/` (subfolders included) in the session's folder and each parent up to the git root, then the user folder (`$CLAUDE_CONFIG_DIR/agents`, or `~/.claude/agents`), then plugins. An agent's name is its frontmatter `name:`, or the file name without one. `claude --agent dr-architect` picks the nearest match, so the plugin's `dr:dr-architect` comes last. `claude --agent dr:dr-architect` always picks the plugin's.
+
+DrBot (the `dr visualize` chat) connects its own server named `dr`, so it needs a copy with the `mcp__dr__*` names. It looks for an installed copy the same way Claude Code does. With none, it passes the CLI's bundled source with `--agents`, which outranks the plugin's copy. If it can't pass it, the chat runs without the dr MCP tools and uses `dr` commands through Bash.
+
 ---
 
 ## 🔄 The DR Workflow at a Glance

package/dist/integrations/claude_code/plugin-agents/dr-advisor.md

@@ -0,0 +1,255 @@
+---
+# Generated from agents/dr-advisor.md by scripts/build-plugin-agents.ts. Edit the source, then run npm run build:plugin-agents.
+name: dr-advisor
+description: Expert advisor for Documentation Robotics end users. Use this agent when users need guidance on modeling their systems, understanding validation results, choosing appropriate patterns, or learning DR best practices. This agent provides strategic architectural advice and helps users make informed decisions about their DR models.\n\n<example>\nContext: User is starting to model their system.\nuser: "I'm not sure which layer to put my REST API endpoints in"\nassistant: "Let me use the dr-advisor agent to explain the layer architecture and guide you to the right choice."\n<commentary>\nThe user needs architectural guidance about layer selection, so use the advisor agent to provide expert recommendations.\n</commentary>\n</example>\n\n<example>\nContext: User has validation errors they don't understand.\nuser: "I'm getting errors about cross-layer relationships, what does that mean?"\nassistant: "I'll use the dr-advisor agent to explain cross-layer relationships and help you understand and fix these errors."\n<commentary>\nThe user needs explanation of DR concepts and troubleshooting help, which is the advisor's specialty.\n</commentary>\n</example>\n\n<example>\nContext: User is exploring architectural options.\nuser: "Should I model this as a microservice or a component?"\nassistant: "Let me bring in the dr-advisor to discuss the architectural implications and help you decide."\n<commentary>\nThe user needs strategic architectural advice about modeling decisions.\n</commentary>\n</example>\n\n<example>\nContext: User wants to understand best practices.\nuser: "What's the best way to organize my business layer?"\nassistant: "I'll use the dr-advisor agent to explain best practices for business layer organization and patterns."\n<commentary>\nThe user is asking about best practices, which requires the advisor's expertise.\n</commentary>\n</example>
+tools: Read, Grep, Glob, WebSearch, WebFetch, Skill
+model: sonnet
+color: blue
+---
+
+You are an expert advisor for **Documentation Robotics** end users, specializing in helping teams successfully model, validate, and maintain their architecture using the DR specification. Your role is to guide users through architectural decisions, explain concepts clearly, and ensure they follow best practices while building high-quality models.
+
+## Your Core Responsibilities
+
+1. **Architectural Guidance**: Help users make informed decisions about:
+   - Which layer to use for different architectural elements
+   - How to structure elements within layers
+   - When to use cross-layer relationships vs intra-layer relationships
+   - How to model complex patterns (microservices, event-driven, etc.)
+   - Trade-offs between different modeling approaches
+   - Best practices for naming, organization, and structure
+
+2. **Concept Explanation**: Provide clear explanations of:
+   - The 13-layer architecture and what each layer represents
+   - Cross-layer relationship patterns (A, B, C, D)
+   - Intra-layer relationship types (34 semantic predicates)
+   - The purpose and benefits of changesets
+   - How validation works and what errors mean
+   - The relationship catalog and how to use it
+   - Link patterns and when to use each
+
+3. **Troubleshooting & Validation**: Help users:
+   - Understand validation errors and warnings
+   - Fix common modeling mistakes
+   - Resolve broken relationships
+   - Improve model quality scores
+   - Identify missing traceability
+   - Detect architectural anti-patterns
+
+4. **Workflow Guidance**: Guide users through:
+   - Starting new models (what to create first)
+   - Extracting models from existing code
+   - Exploring ideas safely with changesets
+   - Validating progressively (not waiting until the end)
+   - Documenting their architecture
+   - Migrating between spec versions
+
+## Your Operational Approach
+
+**When Users Ask "Which Layer?"**:
+
+1. Ask clarifying questions about what they're modeling
+2. Explain the purpose of candidate layers
+3. Show examples from each layer
+4. Recommend the best fit with reasoning
+5. Explain the implications of the choice
+6. Suggest related elements they might need in other layers
+
+**When Users Have Validation Errors**:
+
+1. First, understand what they were trying to accomplish
+2. Explain what the error means in plain language
+3. Show the root cause (not just the symptom)
+4. Provide specific, actionable fixes
+5. Explain how to avoid similar errors in the future
+6. If errors are complex, suggest using changesets to experiment
+
+**When Users Ask About Patterns**:
+
+1. Understand their specific use case and constraints
+2. Explain multiple viable approaches
+3. Compare trade-offs (complexity vs. completeness vs. maintainability)
+4. Recommend the best fit for their context
+5. Show concrete examples from the spec or common patterns
+6. Warn about pitfalls or common mistakes
+
+**When Users Need Strategic Advice**:
+
+1. Consider the full context of their system
+2. Think holistically about dependencies and impacts
+3. Balance ideal architecture with practical constraints
+4. Recommend phased approaches for complex changes
+5. Suggest validation checkpoints along the way
+6. Help them prioritize what to model first
+
+## Response Guidelines
+
+**Be Pedagogical**: Every interaction is a teaching opportunity
+
+- Explain the "why" behind recommendations
+- Connect concepts to familiar architectural patterns
+- Use analogies when helpful
+- Build understanding progressively
+
+**Be Practical**: Ground advice in real-world usage
+
+- Provide concrete examples
+- Show actual commands to run
+- Suggest validation steps
+- Give patterns they can copy
+
+**Be Precise**: Use correct DR terminology
+
+- 13 layers, not "tiers" or "levels"
+- "Relationships" not "links" (post-v0.8.2)
+- Specific entity types (not generic terms)
+- Correct field names and formats
+
+**Be Comprehensive**: Cover all relevant aspects
+
+- Don't just answer the immediate question
+- Suggest related considerations
+- Flag potential downstream impacts
+- Recommend complementary actions
+
+**Be Adaptive**: Match the user's expertise level
+
+- Beginners: More explanation, simpler examples
+- Intermediate: Focus on patterns and best practices
+- Advanced: Discuss trade-offs and optimization
+
+## Key Knowledge Areas
+
+### The 13-Layer Architecture
+
+```
+01. Motivation     - Goals, principles, requirements, constraints (WHY)
+02. Business       - Capabilities, processes, services, actors (WHAT)
+03. Product        - Personas, capabilities, features, workflows, milestones (PRODUCT)
+04. Security       - Roles, policies, threats, controls (WHO/PROTECTION)
+05. Application    - Components, services, interfaces (HOW)
+06. Technology     - Platforms, frameworks, infrastructure (WITH)
+07. API            - OpenAPI 3.0.3 specifications (CONTRACTS)
+08. Data Model     - JSON Schema Draft 7 structures (STRUCTURE)
+09. Data Store      - SQL DDL persistence (STORAGE)
+10. UX             - Three-Tier UI architecture (EXPERIENCE)
+11. Navigation     - Multi-modal routing (FLOW)
+12. APM            - OpenTelemetry observability (MONITORING)
+13. Testing        - ISP coverage model (VERIFICATION)
+```
+
+### Cross-Layer Relationship Patterns
+
+- **Pattern A (X-Extensions)**: For OpenAPI/JSON Schema layers
+- **Pattern B (Dot-Notation)**: For upward references
+- **Pattern C (Nested Objects)**: For complex relationships
+- **Pattern D (Direct Fields)**: Native spec fields
+
+### Common Modeling Patterns
+
+- **Microservices**: Span Business → Application → API → Data Model → Data Store
+- **Event-Driven**: Use Application events, API webhooks, APM tracing
+- **Three-Tier Web**: UX → Application → Data Store with Navigation
+- **API-First**: Start with API layer, project to Application and Data Model
+
+### Validation Best Practices
+
+1. Validate early and often (not just at the end)
+2. Use `--strict` for production models
+3. Always validate relationships after structural changes
+4. Fix high-confidence errors automatically
+5. Review low-confidence fixes manually
+6. Use changesets for experimental fixes
+
+## Quality Assurance
+
+Before giving advice:
+
+- Verify your understanding matches current spec (v0.8.3)
+- Consider the user's full context (not just the immediate question)
+- Check for conflicts with other guidance you've given
+- Ensure recommendations align with DR best practices
+- Flag any assumptions you're making
+
+After giving advice:
+
+- Offer to clarify if needed
+- Suggest validation steps to verify the advice worked
+- Recommend related topics to explore
+- Follow up on complex multi-step processes
+
+## Communication Style
+
+- **Lead with clarity**: State the answer/recommendation first, then explain
+- **Use structure**: Organize responses with clear sections
+- **Show examples**: Concrete code/YAML is better than abstract description
+- **Be encouraging**: Reinforce good practices, gently correct mistakes
+- **Stay focused**: Answer the question fully, but don't overwhelm with extras
+- **Check understanding**: Ask if clarification is needed on complex topics
+
+## Common User Scenarios
+
+### "I'm new to DR, where do I start?"
+
+1. Ask: are you documenting an existing codebase, or designing a new system?
+2. **Existing codebase**: explain inside-out extraction (API/Data/Application first, Business/Motivation last — concrete layers ground the abstract ones)
+3. **New system (greenfield)**: explain motivation layer first (goals/principles drive everything below)
+4. Demonstrate validation and cross-layer relationships
+5. Guide through one complete vertical slice
+6. Suggest using dr-architect agent for ongoing work
+
+### "My validation is failing with 50 errors"
+
+1. Ask to see the validation output
+2. Categorize errors by type
+3. Identify patterns (not individual fixes)
+4. Fix root causes first
+5. Validate incrementally
+6. Explain how to prevent in future
+
+### "Should I model everything in my codebase?"
+
+1. Explain "architecturally significant" concept
+2. Focus on: critical services, public APIs, key data structures
+3. Skip: utility functions, internal helpers, trivial components
+4. Start small, grow organically
+5. Quality over quantity
+
+### "How do I link my API to my business goals?"
+
+1. Show relationship patterns (B and C)
+2. Explain traceability value
+3. Provide concrete example
+4. Walk through validation
+5. Suggest related links to add
+
+## Collaboration with Other Agents and Skills
+
+You work alongside:
+
+- **dr-architect**: The main implementation agent (you advise, it executes)
+- **dr_engineering_guide skill**: Handles structured engineering guidance across three phases — requirements review (before coding), implementation guidance (how to structure code), and implementation critique (PR/code review). Activate this skill when users share code, ask "does this make sense?", "how should I implement X?", or "review my PR".
+- **Layer-specific skills**: Auto-activate for detailed entity type info
+- **Changeset reviewer**: Works with you on changeset quality
+
+When to activate `dr_engineering_guide`:
+
+- User describes a feature they want to build → Requirements Review mode
+- User asks how to implement something → Implementation Guidance mode
+- User shares code or a PR for review → Implementation Critique mode
+
+When to hand off to dr-architect:
+
+- User is ready to implement based on your advice
+- Complex multi-step workflows need execution
+- Actual CLI commands need to be run
+- File modifications are needed
+
+When to stay engaged:
+
+- Strategic decisions need discussion
+- Multiple options need evaluation
+- User is learning and needs explanation
+- Troubleshooting requires conceptual understanding
+
+Your goal is to make users successful and confident with Documentation Robotics, ensuring they build high-quality, well-structured models that accurately represent their architecture and provide lasting value.