From 1e19ec4af4ed2c7861b78a74fcf758aee316009a Mon Sep 17 00:00:00 2001 From: Josh Mabry Date: Thu, 15 Oct 2026 14:31:27 -0700 Subject: [PATCH 1/3] =?UTF-8?q?feat:=20add=20Atlas=20=E2=80=94=20the=20arc?= =?UTF-8?q?hitecture=20map=20lives=20in=20the=20repo?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the atlas member (atlas-plugin v0.1.0) and enables it: a drill-down LikeC4 architecture map from the repo's architecture/ folder, committed with the code, with presenter tours. The navigator uses an existing model as the onboarding overview and offers (asking first) to write one. Needs Node >= 20 (PATH or the managed runtime). Core floor raised to 0.182.0 (atlas's min_protoagent_version); the Atlas-aware persona ships with protoAgent #4242. Co-Authored-By: Claude Opus 5.5 --- README.md | 39 ++++++++++++++++++++++++++++++++++++--- protoagent.bundle.yaml | 30 +++++++++++++++++++++++++----- 2 files changed, 61 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1802320..d1d7686 100644 --- a/README.md +++ b/README.md @@ -44,12 +44,13 @@ It ends with a three-bullet recap (cause, fix, how it was verified) you could sa | plugin | source | role | |---|---|---| -| `engineer` | builtin (protoAgent ≥ 0.180.0) | the navigator skills: `repo-onboard` (setup + guided tour) and `debug-loop` (seven guided steps, plus an appendix on why LLM/agent apps "stop without answering"). Off for every other agent. | +| `engineer` | builtin (protoAgent ≥ 0.180.0) | the navigator skills: `repo-onboard` (setup, architecture overview — the Atlas model when there is one — and a guided tour) and `debug-loop` (seven guided steps, plus an appendix on why LLM/agent apps "stop without answering"). Off for every other agent. | | `craft` | builtin | `/code-review`, `/grill`, `/due-diligence` and friends, rituals you type | | `friction` | builtin | harness-friction ledger: a rough edge leaves evidence instead of vanishing | | `delegates` | builtin | `delegate_to`, for an optional coding agent, used only when you say so | | `terminal` | [terminal-plugin](https://github.com/protoLabsAI/terminal-plugin) | **your** terminal: a real PTY shell in a console view beside chat | | `github` | [github-plugin](https://github.com/protoLabsAI/github-plugin) | GitHub over the `gh` CLI, **read-only by default**: issues, PRs, diffs, CI status, repo files | +| `atlas` | [atlas-plugin](https://github.com/protoLabsAI/atlas-plugin) | a drill-down **architecture map** of the repo, from a LikeC4 model in the repo's `architecture/`, with guided tours in presenter mode | The persona is protoAgent's `engineer` soul preset (`config/soul-presets/engineer.md` in core). The skills are core's in-tree `engineer` plugin. Both ship with protoAgent, and this @@ -72,6 +73,34 @@ so it also works on a fleet member behind the hub (terminal-plugin v0.5.1+; the `pywinpty` (declared with a `sys_platform == 'win32'` marker; the install dialog offers it). macOS and Linux use the stdlib PTY and need nothing. +### Atlas: the architecture map lives in the repo + +[Atlas](https://github.com/protoLabsAI/atlas-plugin) renders a repo's architecture as a +diagram you drill into (system → containers → components), from a [LikeC4](https://likec4.dev) +model: a few `.c4` files in the repo's **`architecture/`** folder, committed and reviewed with +the code like any other file. Click an element to zoom in; its code links open the exact +lines in the console's **code pane**. Tours (`architecture/atlas.tours.json`) play as +slides in presenter mode. + +How the navigator uses it (core's `repo-onboard`, protoAgent ≥ the release with #4242): + +- **The repo already has `architecture/`** → that model *is* the onboarding overview: it + validates it (problems are findings, not fixes), opens it beside chat, and offers to + extend it where it's missing what the code shows. +- **No model yet** → you get today's code-linked Mermaid overview, plus a one-line offer to + write the Atlas model. It writes into your repo, so it asks first, and writes only on your + yes. It validates the model until it's clean (`atlas_validate`), opens it, and leaves the + files uncommitted for you to review and commit. +- **The guided tour** becomes an Atlas tour, one slide per turn, with `show_code` on the + lines behind each slide, so the next person can replay it. +- **Mermaid stays** for one-off pictures (this bug's call sequence). Without Atlas enabled, + onboarding is exactly the Mermaid flow. + +**Needs Node.js 20+** to lay out diagrams: the `node` on PATH, or protoAgent's managed Node +runtime. If neither is there, Atlas shows a setup banner with a one-click **Install Node +runtime** button; the rest of the archetype works without it. The model directory is +`model_dir` (default `architecture`) in Settings ▸ Plugins ▸ Atlas. + ### GitHub: read by default, write when you decide The github plugin gives the agent **read** tools over the `gh` CLI (issues, PRs and their @@ -108,9 +137,13 @@ Pick **Engineer** in the new-agent picker (Fleet ▸ New agent, or the setup wiz python -m server plugin install https://github.com/protoLabsAI/engineer-archetype ``` -**Core floor: protoAgent ≥ 0.180.0.** Bundles can't enforce a minimum version, so here's +**Core floor: protoAgent ≥ 0.182.0.** Bundles can't enforce a minimum version, so here's what an older core misses: +- the `atlas` member needs 0.182.0 (its manifest's `min_protoagent_version`; code links use + the `protoagent:code:open` view bridge). The Atlas-aware onboarding (use or offer the + `architecture/` model, Atlas tours) ships in core with protoAgent #4242; on an older core + Atlas still works by hand, but onboarding draws only the Mermaid overview; - the `engineer` skill pack is missing (it ships in core); - before 0.180.0 (#3618) the plugin dependency check ignored PEP 508 markers, so the terminal's Windows-only `pywinpty` showed as a **missing dependency** on macOS/Linux; @@ -247,7 +280,7 @@ you're debugging. ## Pin lifecycle (ADR 0049) -The one external member (`terminal`) is pinned to a release tag, which is a **floor**: +The external members (`terminal`, `github`, `atlas`) are pinned to release tags, each a **floor**: installs take its newest *compatible* release (caret semantics; for 0.x the minor is the boundary). `scripts/verify_bundle.py`, run by `.github/workflows/verify-bundle.yml` on every PR and weekly, installs this manifest into a scratch agent on a fresh protoAgent diff --git a/protoagent.bundle.yaml b/protoagent.bundle.yaml index 23ad53c..907f92d 100644 --- a/protoagent.bundle.yaml +++ b/protoagent.bundle.yaml @@ -12,8 +12,13 @@ # hypothesis first, reviews their diff, and runs the checks. It edits or commits only # when the operator's latest message says so. See README.md for why. # -# CORE FLOOR — protoAgent >= 0.180.0 (bundles carry no min-version, so it is stated +# CORE FLOOR — protoAgent >= 0.182.0 (bundles carry no min-version, so it is stated # here and in the README, not enforced): +# * the atlas member's manifest declares min_protoagent_version 0.182.0 (the +# `protoagent:code:open` view bridge its code links use); the Atlas-aware +# repo-onboard / engineer persona ships in core with protoAgent #4242 — on a core +# without it Atlas still loads and works by hand, but onboarding draws the Mermaid +# overview and never offers the model; # * the in-tree `engineer` skill pack ships with the core (protoAgent PR that added # this archetype's catalog row); on an older core that `builtin` member is missing # and the agent boots without its skills; @@ -50,7 +55,11 @@ # Host). A navigator turn reads a lot of code; a strong model with prompt caching is # the comfortable choice. # -# PIN LIFECYCLE (ADR 0049): the external member is pinned to a release TAG; on core +# ATLAS needs Node.js >= 20 to lay out diagrams: the `node` on PATH, or protoAgent's +# managed Node runtime (one click on the setup banner Atlas raises when neither is there). +# Without it the view shows that banner; the rest of the archetype is unaffected. +# +# PIN LIFECYCLE (ADR 0049): the external members are pinned to a release TAG; on core # >= 0.146 that pin is a FLOOR (installs take the newest COMPATIBLE tag — caret # semantics, so for 0.x the minor is the boundary). Bump it deliberately only to adopt # an out-of-range release; the verify workflow proves each pin set. Keep member @@ -71,7 +80,9 @@ description: >- you write the fix, it reviews and runs the checks, you commit. It points at code in the console's code pane, opens your editor on the line when you're about to type, gives you a real terminal beside chat, and reads GitHub (issues, PRs, CI) to get up to - speed. It never edits, commits, or posts to GitHub unless you ask. + speed. With Atlas it maps the repo's architecture as a drill-down diagram that lives in + the repo (architecture/, committed with the code) and tours it in presenter mode. It + never edits, commits, or posts to GitHub unless you ask. # The core version this pin set was last verified against (ADR 0049) — metadata, not # enforced. See CORE FLOOR above. @@ -84,8 +95,9 @@ plugins: - { id: delegates, builtin: true } # delegate_to — an optional coding agent, only on the operator's say-so - { id: terminal, url: https://github.com/protoLabsAI/terminal-plugin, ref: v0.9.0 } # the OPERATOR's shell beside chat; the agent may READ it (agent_access: read) - { id: github, url: https://github.com/protoLabsAI/github-plugin, ref: v0.8.0 } # READ tools over `gh` (issues, PRs, diffs, CI, files); writes off by default + - { id: atlas, url: https://github.com/protoLabsAI/atlas-plugin, ref: v0.1.0 } # drill-down architecture map from the repo's architecture/*.c4 (LikeC4); tours + presenter; needs Node >= 20 -enabled: [engineer, craft, friction, delegates, terminal, github] # suggested turn-on list +enabled: [engineer, craft, friction, delegates, terminal, github, atlas] # suggested turn-on list # Create-time setup prompts (#2934, core >= 0.144.0) — the set-up step in the Setup # Wizard and the New Agent panel renders these and writes each answer at its key. @@ -160,6 +172,12 @@ config: # recommended defaults (you # run_command is this persona's main instrument, not an escape hatch (cores before # 0.180.0 logged every call as friction). escape_hatch_exempt: [run_command] + # Atlas: the architecture model LIVES IN THE REPO — `architecture/` under the project + # root, committed and reviewed with the code. The persona offers to write it (asking + # first) and uses an existing one as the onboarding overview. `project` blank = the + # console's current project. Node: blank `node_path` = PATH, then the managed runtime. + atlas: + model_dir: architecture # Agent archetype (ADR 0042 / 0100) — presents this bundle as the "Engineer" agent type # in the new-agent picker. `soul_preset` gives a DIRECT `plugin install ` the @@ -168,7 +186,9 @@ config: # recommended defaults (you # No `requires_tools` (capability contract) on purpose: every tool the persona commits to # (show_code, run_command, open_in_editor, onboard_project, memory_ingest) is a CORE tool # bound by the recommended `filesystem`/`onboarding` config above, not by a member plugin, -# and it never commits to a GitHub write. A contract naming core tools would fail +# and it never commits to a GitHub write. The atlas tools are used when bound and skipped +# when not (onboarding falls back to a Mermaid overview), so they aren't a contract either. +# A contract naming core tools would fail # scripts/verify_bundle.py (which loads members only) without catching anything new. archetype: label: Engineer From 3bd8cb0c5852772913394961327e2f3eb59e3f15 Mon Sep 17 00:00:00 2001 From: Josh Mabry Date: Thu, 15 Oct 2026 14:32:09 -0700 Subject: [PATCH 2/3] chore: bump bundle version to 0.2.0 (adds Atlas) Co-Authored-By: Claude Opus 5.5 --- protoagent.bundle.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protoagent.bundle.yaml b/protoagent.bundle.yaml index 907f92d..cd93bda 100644 --- a/protoagent.bundle.yaml +++ b/protoagent.bundle.yaml @@ -71,7 +71,7 @@ name: Engineer # plugin-release.yml (.github/workflows/release.yml); protoAgent's bundle loader ignores it. # Bump it in the PR that ships the release, then merge as `chore: release vX.Y.Z` (or # run the Release workflow by hand). -version: 0.1.3 +version: 0.2.0 description: >- A hands-on pair-programming navigator for the operator's own machine. Point it at a repo (a git URL or a folder) and it clones or registers it, proves the toolchain, From 519a18820dfb9d4a413d41243f1ef17249aba09e Mon Sep 17 00:00:00 2001 From: Josh Mabry Date: Thu, 15 Oct 2026 20:50:47 -0700 Subject: [PATCH 3/3] feat: pin Atlas v0.2.0 (live agent navigation, recording mode, docs) Co-Authored-By: Claude Opus 5.5 --- protoagent.bundle.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protoagent.bundle.yaml b/protoagent.bundle.yaml index cd93bda..07a6597 100644 --- a/protoagent.bundle.yaml +++ b/protoagent.bundle.yaml @@ -95,7 +95,7 @@ plugins: - { id: delegates, builtin: true } # delegate_to — an optional coding agent, only on the operator's say-so - { id: terminal, url: https://github.com/protoLabsAI/terminal-plugin, ref: v0.9.0 } # the OPERATOR's shell beside chat; the agent may READ it (agent_access: read) - { id: github, url: https://github.com/protoLabsAI/github-plugin, ref: v0.8.0 } # READ tools over `gh` (issues, PRs, diffs, CI, files); writes off by default - - { id: atlas, url: https://github.com/protoLabsAI/atlas-plugin, ref: v0.1.0 } # drill-down architecture map from the repo's architecture/*.c4 (LikeC4); tours + presenter; needs Node >= 20 + - { id: atlas, url: https://github.com/protoLabsAI/atlas-plugin, ref: v0.2.0 } # drill-down architecture map from the repo's architecture/*.c4 (LikeC4); tours + presenter, live agent navigation, recording mode; needs Node >= 20 enabled: [engineer, craft, friction, delegates, terminal, github, atlas] # suggested turn-on list