From 6b49a78ccac35b04664a62d30e9e2a032a4c8204 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 19:12:43 +0000 Subject: [PATCH] Concepts guide + layers-and-boundaries spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/guides/concepts.md ('How CodePlans Thinks'): the conceptual map — what each object is for, the load-bearing product boundary (access, plans, releases), the normative rule (products ship, assets change), worked examples (single SaaS, portfolio, monorepo, internal platform), the layer axis, and the five design principles (derived not maintained; reality not intent; shipping is a human act; agents are first-class users; models are refinable) - docs/specs/layers-and-boundaries-spec.md (proposed, v0.4.6): assets .layer (free text + conventional taxonomy, display-time defaults from type), Atlas layer columns with single-product auto-switch, moveAsset semantics (blocked by open plans, work items follow, history is history), MCP changes (layer params, move_asset tool -> 42, modeling- guide Boundaries section, boundary heuristics in tool descriptions) - Reconciliation phases shifted to v0.4.7/v0.4.8 across the record spec, README roadmap, app-spec, and site; doc cards added for both new documents; atlas spec cross-references the layer axis Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01Y7FhGxYjnJHJ7m9MpH2dgJ --- README.md | 3 +- docs/app-spec.md | 2 +- docs/guides/concepts.md | 141 ++++++++++++++++++++ docs/index.html | 16 ++- docs/specs/asset-atlas-spec.md | 7 +- docs/specs/asset-record-spec.md | 4 +- docs/specs/layers-and-boundaries-spec.md | 162 +++++++++++++++++++++++ 7 files changed, 328 insertions(+), 7 deletions(-) create mode 100644 docs/guides/concepts.md create mode 100644 docs/specs/layers-and-boundaries-spec.md diff --git a/README.md b/README.md index 06adb4f..132f618 100644 --- a/README.md +++ b/README.md @@ -413,7 +413,8 @@ Your agent can then read plans/work items/tech debt and (with a write-scope key) - [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** (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 +- [ ] **v0.4.6 — Layers & model boundaries** (see [`docs/specs/layers-and-boundaries-spec.md`](docs/specs/layers-and-boundaries-spec.md)): asset `layer` field, Atlas layer columns for single-product systems, `move_asset` model refactoring, boundary guidance in MCP +- [ ] **v0.4.7+ — 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 829ad95..9fd81f3 100644 --- a/docs/app-spec.md +++ b/docs/app-spec.md @@ -4,7 +4,7 @@ > design and rationale, see `docs/specs/design-spec-v3.md` (all phases shipped), > `docs/specs/releases-and-asset-history-spec.md` (Phases A–D shipped), and > `docs/specs/asset-record-spec.md` (Phase A shipped; Phases B–C are the next -> tranche, v0.4.6+). +> tranche, v0.4.7+). ### Overview diff --git a/docs/guides/concepts.md b/docs/guides/concepts.md new file mode 100644 index 0000000..f630edd --- /dev/null +++ b/docs/guides/concepts.md @@ -0,0 +1,141 @@ +# How CodePlans Thinks + +CodePlans has a small object model with strong opinions. Most questions about +"where should this go?" answer themselves once you know what each object is +*for* — not just what it's called. This guide is the conceptual map: the +objects, the boundaries between them, and the design principles the whole tool +keeps returning to. + +## The object model in one pass + +``` +Product ──▶ Asset ──▶ (targeted by) Code Plan ──▶ Task + │ │ │ + │ │◀── Work Item (demand, linked many-to-many to plans) + │ │ + └─ Release ─┴─ stamps asset versions; groups the plans that ship together + +Per asset: History (derived diary) · Record (delivered reality) +``` + +| Object | What it is for | What it carries | +|---|---|---| +| **Product** | The unit you *ship, version, and grant access to* | Access control, code plans, releases, integrations targeting | +| **Asset** | The unit you *change* — the work surface | Health, tech debt, dependencies, owners, history, record | +| **Work item** | Demand — a feature, bug, UX issue, or debt someone wants addressed | Type, severity, status, target asset, links to plans | +| **Code plan** | A coordinated change — the bridge from demand to execution | Tasks, target assets (with branch/PR per asset), linked work items, its release | +| **Task** | The unit of execution | Status, assignee, effort, schedule | +| **Release** | What ships *together* — always an explicit human act | Attached plans, per-asset version stamps, derived release notes | +| **Record** | What an asset *is* today — delivered capabilities with receipts | Capabilities (with lineage), known issues, debt register | +| **History** | How the asset *got here* — a derived diary | Version stamps, delivered plans, resolved items, design notes | + +Two of these are load-bearing in ways that are easy to miss, and they're where +modeling questions concentrate: **products** and **assets**. + +## The boundary rule: products ship, assets change + +> **A product is something you ship, version, and grant access to as a unit. +> An asset is something you change.** + +Products aren't folders. Three mechanisms hang off the product boundary: + +1. **Access** — visibility is scoped by product. Splitting one system into + many products fragments who can see what. +2. **Plans** — every code plan belongs to one product, and can only target + that product's assets. Split a real system across products and a + cross-cutting change needs two plans where one is true. +3. **Releases** — a release is per-product, and its whole purpose is + coordinating a revision *across* assets: "Platform v2.4.0 takes Auth to + v1.8.0 and Search to v1.2.0." Products drawn too small make coordinated + releases structurally impossible to express. + +So the test for "should this be a product?" is not "does it have a clear +system boundary?" — most good *assets* have clear system boundaries. The test +is: **does it ship on its own cadence, under its own version, to its own +audience?** + +### Worked examples + +- **A single SaaS** (one app, one API, shared libraries, a datastore or + three): **one product**, many assets. Even at 30–40 assets, this is a + well-modeled instance, not an under-split one. Your releases coordinate + the whole surface; that's the point. +- **A portfolio** (the demo dataset): a web platform, mobile apps with + app-store release trains, and a public API with its own versioning + contract — **three products**, because each genuinely ships on its own + cadence to its own audience. +- **A monorepo** is orthogonal: one repo can host several products, and one + product can span several repos. Model the shipping boundary, not the + folder structure — assets carry `repoPath` for the folder mapping (see + [Modeling Monorepos](modeling-monorepos.md)). +- **A shared internal platform** consumed by other teams *is* a product if + it versions and publishes on its own contract — that's an audience. + +When in doubt, prefer **fewer products with more assets**. Assets are cheap, +carry all the operational texture (health, debt, dependencies, history, +record), and — by design — can be moved and refined later. Products are +commitments. + +### The second axis: layers + +Deep single-product systems still want internal structure — a backend API, +a domain library, and a web app are different *kinds* of asset even though +they ship together. That structure is a **layer**, not a product: an +attribute of the asset (edge, frontend, backend, domain, data, infra, +shared…) rather than a boundary around it. Layers give the +[Asset Atlas](asset-atlas.md) its columns when the product axis degenerates +(one product = one column), and give agents a vocabulary for structural +modeling. The layer concept is specced in +[`layers-and-boundaries-spec.md`](../specs/layers-and-boundaries-spec.md). + +## The design principles + +Five rules explain most of CodePlans' behavior. They're worth knowing because +new features keep being judged against them. + +**1. Derived, not maintained.** Anything that must be manually kept in sync +will rot — so wherever possible, views are *projections* of data the team +already maintains to run its work. Asset history is projected from plans, +work items, and releases. Release notes derive from the work items the +attached plans delivered. The Atlas map is drawn from the asset inventory and +dependency edges — there is deliberately no way to drag a node or pin a +layout, because stored layout would make the map a document again, and +documents rot. + +**2. Reality, not intent.** The asset Record only ever contains *delivered or +verified* claims — a capability enters it by graduating from a resolved work +item (with full lineage: work item → plan → release) or by being verified +against code. Intent lives upstream in work items and PM tools and links out. +This one rule is what keeps the record from becoming a second backlog. + +**3. Shipping is a human act.** Releases have an explicit lifecycle and an +explicit "Mark Shipped" — nothing infers shipping from merges or deploy +events. Shipped releases become read-only, because the record of what shipped +must stay trustworthy. Corrections reopen deliberately. + +**4. Agents are first-class users.** Everything the UI can do to the model, +the MCP server exposes — currently 41 tools, with the same access rules and +guardrails enforced at the tool layer (shipped releases reject mutation, +mirrored items reject writes to tracker-owned fields). Modeling guidance +ships *inside* the tools (`get_modeling_guide`, and heuristics in tool +descriptions), because for agent-driven modeling, the tool description *is* +the UX. Agent-authored artifacts (design notes) are attributed and badged, +never disguised as human. + +**5. Models are refinable.** Your first model of a system will be wrong +somewhere, and an agent's first pass more so. The tool is built so +refinement is cheap and history survives it: modeling operations are +idempotent (re-running a capture or modeling pass reconciles rather than +duplicates), records tombstone rather than delete, lineage text survives +foreign-key changes, and structural refactoring (moving an asset to the +right product, assigning layers) is a supported operation — not a data +migration. + +## Where to go next + +- [The Asset Atlas](asset-atlas.md) — the system map these boundaries feed +- [Releases & Versions](releases-and-versions.md) — the shipping boundary in practice +- [Asset History & the Design Log](asset-history.md) — the derived diary +- [Modeling Monorepos](modeling-monorepos.md) — repo structure vs model structure +- [Working with AI Agents](ai-agents.md) — the MCP tool catalog and agent workflows +- [`docs/app-spec.md`](../app-spec.md) — the authoritative current state diff --git a/docs/index.html b/docs/index.html index 2c04ad4..5538e5e 100644 --- a/docs/index.html +++ b/docs/index.html @@ -558,6 +558,12 @@

App Spec

Complete spec of the current app: schemas, views, query/mutation API, access rules, and wiring gaps.

Read →
+ +
Guide
+

How CodePlans Thinks

+

The conceptual map: what products, assets, plans, and releases are each for, the boundary rule between them, and the five design principles behind the tool.

+
Read →
+
Guide

Capturing a Docs Corpus

@@ -615,7 +621,7 @@

Releases & Asset History Spec
Design

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.

+

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

Read →
@@ -624,6 +630,12 @@

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
+

Layers & Boundaries Spec

+

Next (v0.4.6): the product-vs-asset rule made operational — asset layers, layer columns on the Atlas, and move_asset for refining a model.

+
Read →
+
Design

MCP Server Spec

@@ -941,7 +953,7 @@

Current feature status

AI drafting — release notes & design notes (feature-flagged)Available Asset Record — per-asset capabilities register with delivery lineage (v0.4.4)Available Asset Atlas — live system map with health/debt/activity lenses (v0.4.5)Available - Asset Record — agent reconciliation & round-trip publishing (v0.4.6+)Planned + Asset Record — agent reconciliation & round-trip publishing (v0.4.7+)Planned AI-assisted effort estimationPlanned diff --git a/docs/specs/asset-atlas-spec.md b/docs/specs/asset-atlas-spec.md index f9f42c9..3af87f3 100644 --- a/docs/specs/asset-atlas-spec.md +++ b/docs/specs/asset-atlas-spec.md @@ -178,6 +178,11 @@ shows humans. Write flows stay on the existing `create_code_plan` / 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 +(`v0.4.7+`), 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. + +The Atlas's second grouping axis — **layer columns** for single-product +systems — is specced separately in `layers-and-boundaries-spec.md` +(`v0.4.6`) together with the boundary guidance and `move_asset` it belongs +with. diff --git a/docs/specs/asset-record-spec.md b/docs/specs/asset-record-spec.md index fb7e423..eebd5b7 100644 --- a/docs/specs/asset-record-spec.md +++ b/docs/specs/asset-record-spec.md @@ -334,14 +334,14 @@ known issues/debt); resolve-time graduation prompt + backfill checklist; *Exit criteria: a team can build and browse a receipted capabilities register with zero agent involvement.* -### Phase B — Reconciliation `v0.4.6` +### Phase B — Reconciliation `v0.4.7` `record_proposals` + review queue UI; `propose_record_change`, `list_record_proposals`, `resolve_record_proposal` MCP tools; the reconcile guide; AI-drafted capability descriptions on graduation (flagged, Phase D plumbing). *Exit criteria: an agent-run reconcile pass on this repo files sensible proposals end-to-end.* -### Phase C — Round-trip `v0.4.7` +### Phase C — Round-trip `v0.4.8` Publish-to-GitHub-Releases action on shipped releases; spec-audit section in the reconcile guide; Record freshness surfaced on the asset header (oldest `verifiedAt` drives a "record last verified" hint). *Exit criteria: the litmus diff --git a/docs/specs/layers-and-boundaries-spec.md b/docs/specs/layers-and-boundaries-spec.md new file mode 100644 index 0000000..674a66d --- /dev/null +++ b/docs/specs/layers-and-boundaries-spec.md @@ -0,0 +1,162 @@ +# Layers & Model Boundaries — Design Spec + +> **Status: PROPOSED** (2026-08), targeting `v0.4.6`. Companion to +> `asset-atlas-spec.md` (this supplies the Atlas's second grouping axis) and +> the concepts guide (`docs/guides/concepts.md`, which states the boundary +> rule this spec operationalizes). Shifts asset-record reconciliation to +> `v0.4.7+` — and serves it: reconciliation agents will propose *structural* +> corrections too, and `move_asset` is the tool they need. + +--- + +## 1. Problem + +Between a product and its assets there is room for interpretation, and real +instances land on both sides of it. The demo dataset models a portfolio +(three products that genuinely ship separately); a production single-SaaS +instance correctly models **one product with ~40 assets** — and gets a +degenerate Atlas (one column), no vocabulary for internal structure, and no +supported way to refactor the model if the first pass drew a boundary wrong. + +Three gaps, one tranche: + +1. **Guidance** — the product-vs-asset rule exists in heads, not in the tool. + For agent-driven modeling, guidance must live in the MCP tool layer. +2. **Structure** — single-product systems need a second axis (*layer*) that + is an attribute of an asset, not a boundary around it. +3. **Mobility** — refining a model must be a supported operation with defined + semantics, not a data migration. + +## 2. Design rule (normative) + +> **A product is something you ship, version, and grant access to as a +> unit. An asset is something you change. Layers describe where an asset +> sits inside its product. When in doubt, prefer fewer products with more +> assets — assets are movable; products are commitments.** + +This rule is documented in the concepts guide, embedded in the MCP modeling +guide, and repeated in one-line form in the relevant tool descriptions. + +--- + +## 3. The `layer` field + +### 3.1 Schema + +`assets.layer` — nullable text, both dialects. Free text by design (teams' +vocabularies differ), with a **conventional taxonomy** promoted everywhere +the field is surfaced: + +`edge · frontend · backend · domain · data · infra · shared` + +### 3.2 Effective layer (display-time default) + +A null layer never renders as "unknown". The **effective layer** is derived +from asset type when unset: + +| Asset type | Default layer | +|---|---| +| app | frontend | +| service | backend | +| datastore | data | +| platform | infra | +| library | shared | + +Existing instances therefore get a sensible layered map with zero migration +or backfill. The default is computed at display/query time, never written to +the row — an explicit layer is a human (or agent) statement; a default is +not. + +### 3.3 Where it surfaces + +- **Asset edit** (product page dialog + MCP): a layer input offering the + taxonomy plus free entry. +- **Asset detail header**: a small layer chip beside the type badge (only + when explicitly set). +- **Atlas**: the grouping axis below. + +## 4. Atlas: layer columns + +- A **"Columns: Product | Layer"** toggle joins the Atlas toolbar. +- **Auto behavior**: when exactly one product is in scope (global product + filter, `?product=`, or the org simply has one product), the map defaults + to Layer columns; multi-product scope defaults to Product columns. The + toggle always overrides. +- Layer columns order by the conventional taxonomy sequence (edge → frontend + → backend → domain → data → infra → shared, unknown layers appended + alphabetically) — which matches typical dependency flow, so most edges + point one direction. +- In Layer mode, node sublabels show the product name when scope is + multi-product (the inverse of Product mode, where the lens detail shows). + Lenses, hover blast radius, filters, and the legend are unchanged. +- Grid gains a layer chip on cards; Table gains a Layer column (sortable, + effective layer, explicit ones marked). + +## 5. `moveAsset` — model refactoring with semantics + +`moveAsset(assetId, targetProductId)` — mutation + MCP tool (`move_asset`, +write scope). Not an `update_asset` side effect: the guardrails need a home. + +**Semantics:** + +1. **Blocked by open plans.** If any *draft or active* plan in the current + product targets the asset, the move fails with the list of blocking plans + (`{ error, blockingPlans: [{id, title, status}] }`). Retarget or complete + them first — silently detaching live work would falsify plans. +2. **Work items follow.** Work items with `assetId = asset` update their + `productId` to the target. Demand belongs to the asset. +3. **History is history.** Completed-plan links (`code_plan_assets`), + release version stamps (`release_assets`), sync-log entries, design-log + entries, capabilities and their lineage are all left untouched. An + asset's past does not change because its home does — same principle as + `originSummary` surviving FK nulling. Cross-product historical stamps + render as normal history entries. +4. **Access re-scopes automatically** — visibility follows the new product's + org scope; the mutation validates the caller can see both products. +5. Owners, dependencies, notes, health, debt, layer ride along unchanged + (dependency edges are asset-to-asset and product-agnostic). + +UI: a "Move to product…" action in the asset edit dialog exposing the same +mutation and surfacing blocking plans. MCP is the primary interface — model +refactoring is agent work. + +## 6. MCP changes + +- `create_asset` / `update_asset`: add optional `layer` param (taxonomy + named in the description, free text accepted). +- **New tool `move_asset`** (write): the §5 semantics, with the blocking-plan + error shaped for agent recovery. Tool count 41 → **42**. +- `get_modeling_guide`: new **Boundaries** section — the §2 rule, the layer + taxonomy with defaults table, the worked examples from the concepts guide + (single SaaS / portfolio / monorepo / internal platform), and a + "refining a model" recipe (audit → assign layers → `move_asset` where a + boundary was wrong → re-check the Atlas). +- One-line boundary heuristics added to `create_product` and `create_asset` + descriptions ("create a product only for something shipped, versioned, + and access-controlled as a unit — subsystems are assets with layers"). + +## 7. Demo seed + +Assign explicit layers to a representative subset of demo assets (leaving +some null to demonstrate effective-layer defaults), so a single-product +scope shows a credible layered map out of the box. + +## 8. Testing + +- Effective-layer derivation (explicit beats default; defaults per type). +- Inventory carries layers; Atlas grouping is pure client logic over it. +- `moveAsset`: blocks on draft/active plans with the correct list; moves + work items' product; preserves stamps, completed-plan links, and + capabilities; validates access on both ends; idempotent no-op when + already in the target product. + +## 9. Out of scope + +- Layer-scoped access control, per-layer health rollups, or any mechanism + hanging off layers — layers are *description*, not *boundary*. The moment + layers carry permissions they become products with extra steps. +- Auto-assigning persisted layers by heuristic or agent without an explicit + write — defaults stay display-time. +- Moving assets *across organizations*. +- Bulk/merge operations on products (merge two products = move assets one + by one, deliberately).