diff --git a/README.md b/README.md index 9af0655..06adb4f 100644 --- a/README.md +++ b/README.md @@ -412,7 +412,7 @@ Your agent can then read plans/work items/tech debt and (with a write-scope key) - [x] **v0.4.2 — Version-structured history & design log:** version ladder on asset history, user/agent-authored design notes, plan-side release picker, 10 new MCP tools (39 total) - [x] **v0.4.3 — AI drafting (feature-flagged):** release notes & design notes drafted from delivered work, always landing in an editor - [x] **v0.4.4 — Asset Record (Phase A):** per-asset capabilities register with delivery lineage, graduation from resolved work items, derived known-issues/debt sections, tombstoned removals, `get_asset_record` + `graduate_work_item` MCP tools (41 total) -- [x] **v0.4.5 — Asset Atlas:** top-level Assets view — a live system map (products as columns, dependency edges, health/debt/activity lenses, blast-radius hover) plus grid and sortable table views +- [x] **v0.4.5 — Asset Atlas** (see [`docs/specs/asset-atlas-spec.md`](docs/specs/asset-atlas-spec.md)): top-level Assets view — a live system map (products as columns, dependency edges, health/debt/activity lenses, blast-radius hover) plus grid and sortable table views - [ ] **v0.4.6+ — Reconciliation & round-trip engineering** (see [`docs/specs/asset-record-spec.md`](docs/specs/asset-record-spec.md)): agent reconciliation proposals, release publishing - [ ] AI-assisted effort estimation - [ ] Billing / subscription management (hosted tier, optional & feature-flagged) diff --git a/docs/app-spec.md b/docs/app-spec.md index c87a90d..829ad95 100644 --- a/docs/app-spec.md +++ b/docs/app-spec.md @@ -293,7 +293,7 @@ Two tabs: **Assets** and **Code Plans**. --- -#### `/assets` — Asset Atlas (v0.4.5) +#### `/assets` — Asset Atlas (v0.4.5; future phases in `docs/specs/asset-atlas-spec.md`) Top-level inventory of every visible asset (respects the global product scope + `?product=`), with a stats strip (totals, health breakdown, open debt, active plan targets), search (name/tag), and type/health filters. Three views: - **Map** (default) — a system map drawn live from the inventory: products as columns, assets as nodes (type icon, name, shipped-version chip), `asset_dependencies` edges as curves (line style per dependency type: solid depends_on, dashed integrates_with, dotted aggregates, arrowheads at the target). **Lenses** recolor node accents and detail lines by Health, Debt (effective score thresholds 25/50), or Activity (active plan targets). Hovering an asset highlights its edges and neighbors and dims the rest (blast radius); click navigates to the asset. Hand-rolled deterministic layout (barycenter-ordered columns) — HTML nodes over an SVG underlay, no graph library. - **Grid** — cards: type icon, product, health dot, version chip, active plans / open debt / capabilities counts, debt-score bar, owners. diff --git a/docs/guides/asset-atlas.md b/docs/guides/asset-atlas.md new file mode 100644 index 0000000..8820598 --- /dev/null +++ b/docs/guides/asset-atlas.md @@ -0,0 +1,85 @@ +# The Asset Atlas + +Open **Assets** in the sidebar and you get the whole architecture on one +screen: every asset across your products (or one product, when the global +product filter is set), with three ways to look at it — a **Map**, a card +**Grid**, and a sortable **Table**. A stats strip totals health, open debt, +and active plan targets; search matches names and tags; type and health +filters apply to all three views. + +The design principle is the same one that drives asset history and release +notes: **derived, not drawn.** The map is a projection of the asset inventory +and dependency edges your team already maintains to run its work — not a +diagram anyone has to keep in sync. Add an asset and it appears; record a +dependency and the edge draws itself; ship a release and the version chip +updates. It cannot rot, because it is not a document. + +## The Map + +Products render as columns, assets as nodes. Each node carries its type icon, +name, and the version stamped by the latest shipped release. Dependency edges +draw as curves between nodes, with the line style telling you the +relationship: + +| Style | Meaning | +|---|---| +| ─── solid | depends on | +| – – dashed | integrates with | +| ··· dotted | aggregates | + +The arrowhead points at the asset being depended on. + +### Lenses + +One map, three questions. The lens pills recolor every node's accent: + +- **Health** — the manually assessed health flag (healthy / warning / + critical). *Where is the system hurting?* +- **Debt** — the effective tech-debt score (manual override, or + severity-weighted from open tech-debt items). Green under 25, amber to 50, + red beyond. *Where is the debt concentrated?* +- **Activity** — assets currently targeted by active code plans light up; + quiet assets stay muted. *Where is work happening right now — and what is + nobody touching?* + +### Blast radius + +Hover any asset: its dependency edges and direct neighbors stay lit while the +rest of the map dims. That is the question every change starts with — *what +does this touch?* — answered before you open a plan. Click through to land on +the asset's detail page, where the [Record](asset-history.md) says what it +does and History says how it got there. + +## Grid & Table + +The **Grid** shows each asset as a card: health dot, version chip, active +plan / open debt / capability counts, a debt-score bar, and owner avatars — +the browsing view. The **Table** is the dense view: sortable by name, +product, debt score, active plans, or last-shipped date. Sorting by debt +descending is the de-facto debt review; sorting by last shipped ascending +finds what has not moved in months. + +## Where the data comes from + +| On the map | Maintained in | +|---|---| +| Nodes | Assets, created on product pages or via MCP (`create_asset`) | +| Edges | Asset dependencies (asset detail → Dependencies, product pages, or `add_asset_dependency`) | +| Version chips | Release version stamps ([releases](releases-and-versions.md)) | +| Health colors | The asset `health` flag | +| Debt colors | Open tech-debt work items (or a manual score override) | +| Activity | Active code plans targeting the asset | + +A sparse map is a prompt, not a failure: if the Atlas looks emptier than your +real system, the fastest fix is an agent-driven modeling pass — see +[Modeling Monorepos](modeling-monorepos.md) and the MCP +[modeling tools](ai-agents.md). + +## What's next + +The map is a picture today; the +[Asset Atlas spec](../specs/asset-atlas-spec.md) lays out its path to an +instrument: lens thresholds that focus the map on what matters (Phase B), +transitive blast radius with a "who to notify" rail (Phase C), and starting a +plan directly from the map with its impact visible before the first task is +written (Phase D). diff --git a/docs/index.html b/docs/index.html index 679379f..2c04ad4 100644 --- a/docs/index.html +++ b/docs/index.html @@ -594,6 +594,12 @@

Asset History & Design Log

The version-structured timeline every asset builds for itself, and how humans and agents record design notes worth keeping.

Read →
+ +
Guide
+

The Asset Atlas

+

The live system map: lenses for health, debt, and activity, blast-radius hover, and the grid and table views beside it.

+
Read →
+
Guide

Working with AI Agents

@@ -612,6 +618,12 @@

Asset Record Spec

The capabilities register per asset shipped in v0.4.4. Next (v0.4.6+): agent-driven reconciliation against code and round-trip release publishing.

Read →
+ +
Design
+

Asset Atlas Spec

+

The map shipped in v0.4.5, and its path from picture to planning surface: lens thresholds, transitive blast radius, and plans started from the map.

+
Read →
+
Design

MCP Server Spec

diff --git a/docs/screenshots/asset-dependencies.png b/docs/screenshots/asset-dependencies.png index 0b1e8ed..e3bd01f 100644 Binary files a/docs/screenshots/asset-dependencies.png and b/docs/screenshots/asset-dependencies.png differ diff --git a/docs/screenshots/asset-history.png b/docs/screenshots/asset-history.png index ce400d5..9363801 100644 Binary files a/docs/screenshots/asset-history.png and b/docs/screenshots/asset-history.png differ diff --git a/docs/screenshots/asset-record.png b/docs/screenshots/asset-record.png index e62a05e..290adc1 100644 Binary files a/docs/screenshots/asset-record.png and b/docs/screenshots/asset-record.png differ diff --git a/docs/screenshots/dashboard.png b/docs/screenshots/dashboard.png index 56951dc..a8c5f46 100644 Binary files a/docs/screenshots/dashboard.png and b/docs/screenshots/dashboard.png differ diff --git a/docs/screenshots/plan-detail.png b/docs/screenshots/plan-detail.png index 74b8202..b572436 100644 Binary files a/docs/screenshots/plan-detail.png and b/docs/screenshots/plan-detail.png differ diff --git a/docs/screenshots/release-detail.png b/docs/screenshots/release-detail.png index 8c3e708..2d61b72 100644 Binary files a/docs/screenshots/release-detail.png and b/docs/screenshots/release-detail.png differ diff --git a/docs/screenshots/releases.png b/docs/screenshots/releases.png index 3b74914..43573fe 100644 Binary files a/docs/screenshots/releases.png and b/docs/screenshots/releases.png differ diff --git a/docs/screenshots/work-items.png b/docs/screenshots/work-items.png index 6b5ba66..f278cc7 100644 Binary files a/docs/screenshots/work-items.png and b/docs/screenshots/work-items.png differ diff --git a/docs/specs/asset-atlas-spec.md b/docs/specs/asset-atlas-spec.md new file mode 100644 index 0000000..f9f42c9 --- /dev/null +++ b/docs/specs/asset-atlas-spec.md @@ -0,0 +1,183 @@ +# Asset Atlas — Design Spec + +> **Status: PHASE A SHIPPED `v0.4.5`; Phases B–D PROPOSED** (2026-08). +> Companion to `asset-record-spec.md` (the record is what a node *is*; the +> Atlas is where it *sits*) and `design-spec-v3.md`. Reuses the existing data +> layer, access model, and MCP conventions unchanged. + +--- + +## 1. Purpose & Positioning + +Assets are the main work surface of CodePlans — work items target them, plans +change them, releases version them, records describe them — yet until v0.4.5 +they were only reachable by drilling through a product. The Atlas gives assets +a first-class home, and stakes out a claim no tracker makes: + +**The architecture diagram that cannot rot.** Every team has a system diagram +somewhere — a whiteboard photo, a Miro board, a wiki page — and every one of +them is wrong within a quarter, because diagrams are *documents* maintained +beside the system. The Atlas is not a document. It is a *projection* of the +asset inventory and dependency edges the team already maintains to run its +work. Add an asset, it appears; record a dependency, the edge draws; stamp a +release, the version chip updates. The map is correct for the same reason the +release notes are correct: it is derived, not drawn. + +The design direction across all phases: evolve the map from a **picture** +(Phase A: see the system) into an **instrument** (Phase B: interrogate it) +into a **planning surface** (Phases C–D: act on it). Each phase keeps the +derived-not-drawn rule — the map never stores layout, annotations, or state of +its own beyond ephemeral view preferences. + +### Litmus test + +An engineer new to the team opens `/assets`, and within one minute can answer: +*what services exist, which ones are in trouble, what would break if I changed +this one* — then click once more and read what that asset actually does (its +Record). When planning a change, the same map is where the plan starts, with +its blast radius visible before the first task is written. + +--- + +## 2. Phase A — The Atlas `v0.4.5` ✅ SHIPPED + +Summarized for reference; see `docs/app-spec.md` (`/assets`) for the +authoritative current state. + +- **Route & nav**: `/assets`, sidebar entry between Products and Work Items. + Respects the global product scope and `?product=`. +- **Three views**: Map (default), Grid (cards), Table (sortable). Shared + stats strip, name/tag search, type + health filters. +- **Map**: products as columns, assets as nodes (type icon, name, latest + shipped-version chip), `asset_dependencies` edges as curves — solid + *depends_on*, dashed *integrates_with*, dotted *aggregates*, arrowhead at + the target. **Lenses** recolor node accents by Health, Debt (effective + score, thresholds 25/50), or Activity (active plan targets). Hovering an + asset highlights its edges + direct neighbors and dims the rest; click + navigates to the asset. +- **Layout**: deterministic, hand-rolled — barycenter-ordered columns, HTML + nodes over an SVG underlay. No graph library, no stored positions. +- **Data**: `getAssetInventory(userId, { productId? })` — org-scoped assets + with effective debt score, open item/debt counts, active plan targets, + capability count, latest shipped version stamp, owners, plus the dependency + edges among them (edges leaving the scope are dropped so the map always + matches the node set). + +--- + +## 3. Phase B — Focus mode: lens thresholds & map filtering (PROPOSED) + +A lens currently *colors* every node; focus mode lets it *select*. The +question changes from "where is the debt?" to "show me only what matters and +its context." + +### UX + +- Each lens gains an optional **threshold control** rendered beside the lens + pills when that lens is active: + - Health: `all · warning+ · critical` + - Debt: `all · ≥25 · ≥50` + - Activity: `all · active · quiet` (quiet inverts — find the unmaintained) +- With a threshold set, the map enters **focus mode**: matching nodes render + full-strength, their direct neighbors render half-dimmed (context), and + everything else collapses to small dots so column shape is preserved + without noise. Edges not touching a matching node fade to near-invisible. +- The stats strip re-counts to the focused set (`4 of 15 assets in focus`). + Grid and Table honor the same threshold as a plain filter — focus mode is + a map rendering, not a separate data path. +- Search composes: a search query in focus mode intersects. + +### Non-goals + +No saved "views", no per-user map state beyond the existing persisted view +preferences mechanism. Focus is a transient question, not a dashboard. + +--- + +## 4. Phase C — Transitive blast radius (PROPOSED) + +Hover today shows direct neighbors — depth 1. Real incidents propagate. + +### UX + +- **Click-to-pin** an asset (hover stays as-is): the map enters **radius + mode** with the pinned asset marked. A depth control appears: + `direct · +2 · full closure`. +- Downstream (dependents — who breaks) renders in the warning hue; upstream + (dependencies — who I lean on) renders muted; depth is shown on each edge + ring. The two directions are visually distinct because the questions are + different: *who do I hurt* vs *who can hurt me*. +- A side rail lists the closure grouped by depth with owner avatars — the + "who to notify" list, copyable. Rows link to the asset; each row shows the + path (`Atlas → BFF → Mobile App`) on hover, since the *route* of the + impact is the reviewable claim. +- Pinning composes with lenses (radius selects, lens colors) but suspends + Phase B focus mode — one selection mechanism at a time. +- `Esc` or clicking the canvas unpins. + +### Data + +Transitive closure is computed client-side by BFS over the already-shipped +edge list — no new queries. Cycles are handled by visited-set; depth is the +shortest path. The existing `getImpactedAssets` (plan impact, depth 1) is +unchanged; if plan detail later wants transitive impact, it reuses this +traversal, not a new endpoint. + +--- + +## 5. Phase D — The map as planning surface (PROPOSED) + +The Atlas closes the loop back into the core object model: plans start where +their blast radius is visible. + +### UX + +- A **"Plan a change"** affordance on the map toggles target-selection mode: + clicking nodes multi-selects them as prospective plan targets (selection + chips accumulate in a floating bar). +- The bar live-renders the union blast radius of the selection (Phase C + traversal, depth configurable) — *before a plan exists*, the cost of the + change is on screen. +- **"Create plan"** opens the existing plan-create side panel pre-filled: + target assets = selection; product inferred when the selection is + single-product (multi-product selections offer the plan-per-product split + the model requires); the impact list is included in the description + scaffold as a checklist of assets to review, each with owners. +- After creation, the map renders the new plan's targets with the standard + Activity-lens treatment. No plan geometry is stored — the plan is the + record; the map re-derives. + +### MCP + +One new read tool when Phase C/D land (not before): +`get_asset_map(productId?)` returning the same shape the Atlas consumes — +nodes with stats plus edges — so agents can answer "what breaks if X +changes" and scaffold plans with the same blast-radius reasoning the UI +shows humans. Write flows stay on the existing `create_code_plan` / +`add_plan_asset` tools. + +--- + +## 6. Explicitly Out of Scope + +- **Stored layout or annotations** — no dragging nodes, no sticky notes, no + saved positions. The moment layout is stored, the map is a document again + and starts rotting. (Deterministic layout is also what keeps two teammates' + maps identical.) +- **A general graph editor** — edges are created where they are owned today + (asset detail / product dependency views / MCP), not by drawing on the map. +- **Runtime topology** (service mesh, tracing, live traffic) — the Atlas maps + the *declared* architecture. Reconciling declared vs observed topology is + agent territory, and belongs beside the record's reconciliation phases + (`asset-record-spec.md` Phase B), not here. +- **Cross-org or public sharing** of maps. + +--- + +## 7. Sequencing + +Phases B–D are deliberately unversioned: they slot into the 4.x line as +capacity allows, interleaved with the asset-record reconciliation work +(`v0.4.6+`), which remains the strategic priority. B is small and can ride +along with any release; C unlocks D and should precede it; D touches the +plan-create flow and deserves its own release.