groundwork-method 0.0.1 → 0.10.0

package/migrations/gw-bet-prose-redesign.js

@@ -0,0 +1,105 @@
+// gw-bet-prose-redesign — retire the machine-readable bet artifacts for the prose model.
+//
+// The bet became pure prose: every machine-readable artifact is now built in code at
+// Delivery. Three shapes are gone — `docs/bets/<slug>/decomposition.json` (the suite and
+// git are the record), `docs/bets/<slug>/contracts/` (the prose API/data design carries the
+// shapes; the canonical contract is captured from the running service into `docs/architecture/api/<service>/`),
+// and the monolithic `decomposition.md` (now a browsable `decomposition/` prose tree). The
+// approval baseline moved from `approval_commit` in `decomposition.json` to the git tag
+// `bet/<slug>/approved` on the approved-prose commit.
+//
+// Restructuring a *live* bet's docs is risky, so this migration is largely ADVISORY: it
+// prints the model change and names any active bet a contributor must restructure by hand.
+// Where cleanup is SAFE and mechanical it acts — already-DELIVERED bets under
+// `docs/bets/_archive/` (whose contracts were already captured to `docs/architecture/api/` at Validation)
+// and stray `.groundwork/bets/<slug>/decomposition.json` files have their obsolete
+// `decomposition.json` / `contracts/` artifacts removed. Active bets are advised, never mutated;
+// their prose record (including any archived `decomposition.md`) is left untouched.
+//
+// Contract (migrations/README.md): forward-only, idempotent, detect-first.
+// detect() is read-only (update --dry-run calls it). Node built-ins only.
+
+const fs = require('fs');
+const path = require('path');
+
+function listDirs(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+}
+
+// Obsolete artifacts that are SAFE to delete: stray .groundwork/bets/<slug>/decomposition.json
+// and, under archived (delivered) bets, decomposition.json files + contracts/ directories.
+function obsoleteArtifacts(targetDir) {
+  const out = { files: [], dirs: [] };
+
+  const groundworkBets = path.join(targetDir, '.groundwork', 'bets');
+  for (const slug of listDirs(groundworkBets)) {
+    const p = path.join(groundworkBets, slug, 'decomposition.json');
+    if (fs.existsSync(p)) out.files.push(p);
+  }
+
+  const archive = path.join(targetDir, 'docs', 'bets', '_archive');
+  for (const slug of listDirs(archive)) {
+    const j = path.join(archive, slug, 'decomposition.json');
+    if (fs.existsSync(j)) out.files.push(j);
+    const c = path.join(archive, slug, 'contracts');
+    if (fs.existsSync(c)) out.dirs.push(c);
+  }
+
+  return out;
+}
+
+// Active (non-archived) bets still carrying an old-shape artifact — advise, never mutate.
+function activeBetsNeedingAttention(targetDir) {
+  const betsDir = path.join(targetDir, 'docs', 'bets');
+  const flagged = [];
+  for (const slug of listDirs(betsDir)) {
+    if (slug === '_archive') continue;
+    const betDir = path.join(betsDir, slug);
+    const stale = [];
+    if (fs.existsSync(path.join(betDir, 'decomposition.md'))) stale.push('decomposition.md');
+    if (fs.existsSync(path.join(betDir, 'decomposition.json'))) stale.push('decomposition.json');
+    if (fs.existsSync(path.join(betDir, 'contracts'))) stale.push('contracts/');
+    if (stale.length > 0) flagged.push({ slug, stale });
+  }
+  return flagged;
+}
+
+module.exports = {
+  detect({ targetDir }) {
+    if (!fs.existsSync(path.join(targetDir, '.groundwork'))) return 'n/a'; // not a GroundWork install
+    const obsolete = obsoleteArtifacts(targetDir);
+    const active = activeBetsNeedingAttention(targetDir);
+    if (obsolete.files.length || obsolete.dirs.length || active.length) return 'pending';
+    return 'done';
+  },
+
+  run({ targetDir }) {
+    const obsolete = obsoleteArtifacts(targetDir);
+    for (const f of obsolete.files) fs.rmSync(f, { force: true });
+    for (const d of obsolete.dirs) fs.rmSync(d, { recursive: true, force: true });
+
+    const removed = obsolete.files.length + obsolete.dirs.length;
+    if (removed > 0) {
+      console.log(`  Removed ${removed} obsolete bet artifact(s) (decomposition.json / contracts/) from delivered or stray bets.`);
+    }
+
+    console.log('  The bet is now pure prose; its machine-readable artifacts are built in code at Delivery:');
+    console.log('    • docs/bets/<slug>/decomposition.md  →  a browsable docs/bets/<slug>/decomposition/ prose tree');
+    console.log('    • decomposition.json is dropped — the bet-progress suite plus git history are the record');
+    console.log('    • docs/bets/<slug>/contracts/ is removed — the prose API/data design carries the shapes,');
+    console.log('      and the canonical contract is captured into docs/architecture/api/<service>/ from the running service');
+    console.log('    • the approval baseline is the git tag bet/<slug>/approved on the approved-prose commit');
+
+    const active = activeBetsNeedingAttention(targetDir);
+    if (active.length > 0) {
+      console.log('  Active bets still carry old-shape artifacts — restructure these by hand (left untouched here):');
+      for (const { slug, stale } of active) {
+        console.log(`    • ${slug}: ${stale.join(', ')}`);
+      }
+    }
+  },
+};

package/migrations/gw-drop-test-manifest.js

@@ -0,0 +1,37 @@
+// gw-drop-test-manifest — remove orphaned bet test-manifest.json seal files.
+//
+// The SHA-256 test-manifest seal was removed: `./dev bet sign` no longer exists, and
+// `./dev test bet` no longer verifies a manifest. An approved bet suite is now held to
+// its definition of done by the approval commit + the delivery review reconciliation
+// (groundwork-bet workflows 03/04). The dev-bundle update removes the `bet sign` command
+// itself; this deletes the now-inert .groundwork/bets/<slug>/test-manifest.json files it
+// used to write. decomposition.json and everything else under the bet dir are untouched.
+//
+// Contract (migrations/README.md): forward-only, idempotent, detect-first.
+// detect() is read-only (update --dry-run calls it). Node built-ins only.
+
+const fs = require('fs');
+const path = require('path');
+
+function manifestPaths(targetDir) {
+  const betsDir = path.join(targetDir, '.groundwork', 'bets');
+  if (!fs.existsSync(betsDir)) return [];
+  return fs
+    .readdirSync(betsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => path.join(betsDir, d.name, 'test-manifest.json'))
+    .filter((p) => fs.existsSync(p));
+}
+
+module.exports = {
+  detect({ targetDir }) {
+    if (!fs.existsSync(path.join(targetDir, '.groundwork'))) return 'n/a'; // not a GroundWork install
+    return manifestPaths(targetDir).length > 0 ? 'pending' : 'done';
+  },
+
+  run({ targetDir }) {
+    for (const p of manifestPaths(targetDir)) {
+      fs.rmSync(p, { force: true });
+    }
+  },
+};

package/migrations/gw-register-serena-mcp.js

@@ -0,0 +1,42 @@
+// gw-register-serena-mcp — registers the Serena code-intelligence MCP server in .mcp.json
+// and removes the retired depwire server. init registers Serena directly; this heals older
+// installs (which registered depwire, or nothing) on update. Additive toward other servers:
+// only the depwire entry is removed. Every Serena consumer degrades gracefully when the
+// server is absent, so the recorded completion also respects a user who removes it later.
+
+const fs = require('fs');
+const path = require('path');
+
+const SERENA_MCP_SERVER = {
+  command: 'uvx',
+  args: ['--from', 'serena-agent==1.5.3', 'serena', 'start-mcp-server', '--context', 'ide-assistant', '--project', '.'],
+};
+
+module.exports = {
+  detect({ targetDir }) {
+    if (!fs.existsSync(path.join(targetDir, '.groundwork'))) return 'n/a';
+    const mcpPath = path.join(targetDir, '.mcp.json');
+    if (!fs.existsSync(mcpPath)) return 'pending';
+    try {
+      const servers = (JSON.parse(fs.readFileSync(mcpPath, 'utf8')).mcpServers) || {};
+      // Done only once Serena is present and the retired depwire server is gone.
+      return servers.serena && !servers.depwire ? 'done' : 'pending';
+    } catch {
+      return 'n/a'; // unparseable — touching it risks clobbering the user's file
+    }
+  },
+
+  run({ targetDir }) {
+    const mcpPath = path.join(targetDir, '.mcp.json');
+    let config = { mcpServers: {} };
+    if (fs.existsSync(mcpPath)) {
+      config = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
+      if (!config.mcpServers || typeof config.mcpServers !== 'object') config.mcpServers = {};
+    }
+    const hadDepwire = Boolean(config.mcpServers.depwire);
+    if (hadDepwire) delete config.mcpServers.depwire; // pull out the retired server
+    if (config.mcpServers.serena && !hadDepwire) return; // idempotent — nothing to change
+    config.mcpServers.serena = SERENA_MCP_SERVER;
+    fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2));
+  },
+};

package/migrations/gw-relocate-hidden-skills.js

@@ -0,0 +1,40 @@
+// gw-relocate-hidden-skills — remove the orphaned .agents/groundwork/skills/ tree.
+//
+// Hidden methodology skills moved from .agents/groundwork/skills/ to .groundwork/skills/
+// so no agent's skill scanner can pick them up. update installs the new tree at
+// .groundwork/skills/ (clean-copy), but the old location is outside that copy and would
+// linger as dead files. This deletes it. The promoted engineer skills under
+// .agents/skills/groundwork-*-engineer/ are a different tree and are left untouched.
+//
+// Contract (migrations/README.md): forward-only, idempotent, detect-first.
+// detect() is read-only (update --dry-run calls it). Node built-ins only.
+
+const fs = require('fs');
+const path = require('path');
+
+function oldHiddenDir(targetDir) {
+  return path.join(targetDir, '.agents', 'groundwork', 'skills');
+}
+
+module.exports = {
+  detect({ targetDir }) {
+    if (!fs.existsSync(path.join(targetDir, '.groundwork'))) return 'n/a'; // not a GroundWork install
+    return fs.existsSync(oldHiddenDir(targetDir)) ? 'pending' : 'done';
+  },
+
+  run({ targetDir }) {
+    const dir = oldHiddenDir(targetDir);
+    if (fs.existsSync(dir)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+    // Drop the now-empty .agents/groundwork/ wrapper so nothing dangling remains.
+    const wrapper = path.join(targetDir, '.agents', 'groundwork');
+    try {
+      if (fs.existsSync(wrapper) && fs.readdirSync(wrapper).length === 0) {
+        fs.rmdirSync(wrapper);
+      }
+    } catch {
+      /* a non-empty or racing wrapper is fine — leave it */
+    }
+  },
+};

package/migrations/gw-seed-config-toml.js

@@ -0,0 +1,24 @@
+// gw-seed-config-toml — installs the user-owned config file on installs that
+// predate it. init seeds config.toml once and update never touches it (it is
+// user-owned), so projects initialized before the file existed never get one.
+// Seeding the commented default is purely additive: an empty/absent file and the
+// default behave identically, so this cannot change behavior.
+
+const fs = require('fs');
+const path = require('path');
+
+module.exports = {
+  detect({ targetDir }) {
+    if (!fs.existsSync(path.join(targetDir, '.groundwork'))) return 'n/a';
+    return fs.existsSync(path.join(targetDir, '.groundwork', 'config', 'config.toml'))
+      ? 'done'
+      : 'pending';
+  },
+
+  run({ targetDir, packageRoot }) {
+    const src = path.join(packageRoot, 'src', 'config', 'config.toml');
+    const dest = path.join(targetDir, '.groundwork', 'config', 'config.toml');
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+  },
+};

package/migrations/index.json

@@ -0,0 +1,40 @@
+{
+  "registry_version": 1,
+  "migrations": [
+    {
+      "id": "gw-seed-config-toml",
+      "version": "0.10.0",
+      "title": "Seed .groundwork/config/config.toml",
+      "kind": "cli",
+      "summary": "Installs the user-owned config file on installs that predate it. init seeds it once; update never touched it, so older installs have none."
+    },
+    {
+      "id": "gw-register-serena-mcp",
+      "version": "0.10.0",
+      "title": "Register the Serena code-intelligence MCP server",
+      "kind": "cli",
+      "summary": "Adds the Serena MCP server to .mcp.json and removes the retired depwire server. Idempotent; only the depwire entry is removed, other servers are untouched."
+    },
+    {
+      "id": "gw-relocate-hidden-skills",
+      "version": "0.10.0",
+      "title": "Remove the orphaned .agents/groundwork/skills/ tree",
+      "kind": "cli",
+      "summary": "Hidden methodology skills moved to .groundwork/skills/ so no agent skill scanner can pick them up. update installs the new tree; this deletes the old .agents/groundwork/skills/ location. Promoted engineer skills under .agents/skills/ are untouched."
+    },
+    {
+      "id": "gw-drop-test-manifest",
+      "version": "0.10.0",
+      "title": "Remove orphaned bet test-manifest.json seal files",
+      "kind": "cli",
+      "summary": "The SHA-256 test-manifest seal was removed (./dev bet sign is gone; ./dev test bet no longer verifies a manifest). The dev-bundle update drops the bet sign command; this deletes the now-inert .groundwork/bets/<slug>/test-manifest.json files. decomposition.json and other bet artifacts are untouched."
+    },
+    {
+      "id": "gw-bet-prose-redesign",
+      "version": "0.10.0",
+      "title": "Retire the machine-readable bet artifacts for the prose model",
+      "kind": "cli",
+      "summary": "The bet is now pure prose: decomposition.md became a docs/bets/<slug>/decomposition/ tree, decomposition.json is dropped (the suite + git are the record), docs/bets/<slug>/contracts/ is removed (the prose design carries shapes; the canonical contract is captured into docs/architecture/api/<service>/ from running code), and the approval baseline is the git tag bet/<slug>/approved. Mechanically removes obsolete decomposition.json/contracts/ from archived (delivered) bets and stray .groundwork/bets/<slug>/decomposition.json; the groundwork-update skill's Bets family advances any in-flight bet's prose structure."
+    }
+  ]
+}

package/package.json

@@ -1,10 +1,74 @@
 {
   "name": "groundwork-method",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for groundwork-method",
+  "version": "0.10.0",
+  "description": "An installable delivery system for AI-driven software development: facilitated discovery to canonical docs, generators to a booted monorepo, and a contract-gated bet delivery loop.",
+  "bin": {
+    "groundwork": "./bin/groundwork.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "src/",
+    "dist/",
+    "migrations/",
+    "generators.json",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "npm run build:dev-cli && tsc",
+    "build:dev-cli": "tsc --noEmit -p src/generators/workspace-dev-cli/cli-src/tsconfig.json && node src/generators/workspace-dev-cli/cli-src/build.mjs",
+    "gen:workflow-index": "node scripts/generate_workflow_index.js",
+    "build:grammars": "node scripts/build-grammars.mjs",
+    "prepublishOnly": "npm run build:dev-cli && tsc && node scripts/generate_workflow_index.js --check"
+  },
+  "generators": "./generators.json",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "ai",
+    "agents",
+    "claude",
+    "delivery",
+    "methodology",
+    "scaffolding",
+    "nx",
+    "architecture",
+    "shape-up"
+  ],
+  "author": "RNEL",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryannel/GroundWork.git"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@nx/devkit": "^22.7.2",
+    "@tree-sitter-grammars/tree-sitter-kotlin": "1.1.0",
+    "@tree-sitter-grammars/tree-sitter-lua": "0.4.1",
+    "@types/node": "^25.8.0",
+    "esbuild": "^0.25.12",
+    "nx": "^22.7.2",
+    "tree-sitter-c": "0.24.1",
+    "tree-sitter-c-sharp": "0.23.5",
+    "tree-sitter-cli": "0.26.9",
+    "tree-sitter-cpp": "0.23.4",
+    "tree-sitter-dart": "1.0.0",
+    "tree-sitter-go": "0.25.0",
+    "tree-sitter-java": "0.23.5",
+    "tree-sitter-javascript": "0.25.0",
+    "tree-sitter-php": "0.24.2",
+    "tree-sitter-python": "0.25.0",
+    "tree-sitter-ruby": "0.23.1",
+    "tree-sitter-rust": "0.24.0",
+    "tree-sitter-scala": "0.24.0",
+    "tree-sitter-swift": "0.7.1",
+    "tree-sitter-typescript": "0.23.2",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "web-tree-sitter": "0.26.9",
+    "yaml": "^2.9.0"
+  }
 }

package/src/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+GroundWork is installed in this project. This file is the **canonical instruction source**
+for every AI coding agent that works here. Agent-specific files (e.g. `CLAUDE.md`) are
+symlinks to this one — **edit `AGENTS.md`, never the symlinked copies.**
+
+## Start here
+
+Run the **`groundwork-orchestrator`** skill. It reads project state and routes to the next
+step — greenfield discovery, brownfield scan, or the delivery (bet) loop. Everything in
+GroundWork flows from the orchestrator; you do not need to memorize the lifecycle.
+
+This is also the entry point for **maintenance**: when you want to "update GroundWork",
+"upgrade GroundWork", or bring this project up to date with the current framework, run the
+orchestrator and it routes to the update lane. Do not go hunting for a CLI command or a
+specific skill — the orchestrator is always the front door.
+
+## Where things live
+
+- **Registered skills** (auto-loaded): `.agents/skills/` — the orchestrator, `groundwork-check`,
+  and any installed engineer personas.
+- **Hidden methodology skills** (loaded on demand by the orchestrator): `.groundwork/skills/`.
+- **Project docs**: `docs/` — product brief, architecture, lifecycle, bets, and principles.
+- **Config & state**: `.groundwork/config/` — never hand-edit `state.json`.
+- **Knowledge index**: `llms.txt` at the project root.
+
+## Agent wiring
+
+This project is set up to be agent-agnostic from a single source of truth:
+
+- The content above lives once in `AGENTS.md` + `.agents/`.
+- Each agent reads it through symlinks created by `npx groundwork-method init`
+  (e.g. Claude Code: `CLAUDE.md → AGENTS.md`, `.claude → .agents`). AGENTS.md-native agents
+  (Cursor, Codex, OpenCode, Cline) read `AGENTS.md` and `.agents/skills/` directly.
+- Add another agent later with `npx groundwork-method init --agent <name>` — non-destructive.
+  `AGENTS.md` never moves; only symlinks change.

package/src/config/config.toml

@@ -0,0 +1,30 @@
+# GroundWork project configuration.
+#
+# This file is yours: `groundwork init` seeds it once and `groundwork update`
+# never touches it. All sections are optional — an empty file behaves exactly
+# like no file.
+
+# ── Defaults ────────────────────────────────────────────────────────────────
+# Starting positions the facilitation skills PROPOSE during conversation.
+# A default is never silently applied: the architecture and scaffold phases
+# present it with reasoning and you still make the call.
+
+[defaults]
+# stack = "go"                   # preferred backend: go | python
+# frontend = "nextjs"            # preferred frontend generator
+# llm_provider = "anthropic"     # provider proposed for AI-powered services
+# llm_model = "claude-sonnet-4-6"
+
+# Generator flags the scaffold phase proposes, keyed by generator name.
+[defaults.generators]
+# go-microservice = "--withPostgres"
+
+# ── Custom skills ───────────────────────────────────────────────────────────
+# Your own methodology skills, merged into the orchestrator's routing AFTER
+# the built-in table — a built-in route wins any conflict. Key is the intent
+# the orchestrator matches; value is the instruction file path relative to
+# the project root. Keep custom skill files outside .groundwork/skills/
+# (that tree is replaced by `groundwork update`).
+
+[skills]
+# "security-review" = ".agents/custom/security-review/instructions.md"

package/src/config/groundwork-state.json

@@ -0,0 +1,5 @@
+{
+  "version": 2,
+  "project_type": null,
+  "completed": []
+}

package/src/docs/llms.txt

@@ -0,0 +1,72 @@
+# GroundWork Documentation Index
+
+The canonical documents in this project, in their expected order of
+relevance for AI agents working in this codebase.
+
+*The Vision-and-direction and System documents are created by the GroundWork
+setup phases and appear here as each phase commits — those links resolve once
+setup runs. The other sections ship at install time.*
+
+## Vision and direction
+- [Product Brief](docs/product-brief.md): The product's vision, users, and constraints.
+- [Design System](docs/design-system.md): Interface decisions, NFRs, and design language.
+- [Maturity Roadmap](docs/maturity.md): The project's assessment against the GroundWork maturity model and the tracked roadmap of open gaps.
+
+## How we work
+- [How we work](docs/ways-of-working/how-we-work.md): The two-mode lifecycle — setup and delivery loop.
+- [Units of work](docs/ways-of-working/units-of-work.md): Bets, milestones, and slices — the delivery vocabulary.
+- [Documentation protocol](docs/ways-of-working/documentation.md): Living documents, drift detection, and ADR conventions.
+
+## Engineering principles
+- [Manifesto](docs/principles/index.md): Core engineering beliefs that govern every decision.
+- [Code craft](docs/principles/foundations/code-craft.md): How we write and structure code.
+- [Documentation](docs/principles/foundations/documentation.md): What to document and how.
+- [Testing](docs/principles/foundations/testing.md): Test strategy and coverage philosophy.
+- [Product engineering](docs/principles/foundations/product-engineering.md): Shipping with user outcomes in mind.
+- [Continuous discovery](docs/principles/foundations/continuous-discovery.md): Discovery as a weekly habit — the opportunity-solution tree, problem space before solution.
+- [Product risks](docs/principles/foundations/product-risks.md): The four risks every bet must clear — value, usability, feasibility, viability — and killing the riskiest assumption first.
+- [Success metrics](docs/principles/foundations/success-metrics.md): Designing the measure — North Star and inputs, leading vs lagging, counter-metrics, signal before ship.
+- [Requirements & specs](docs/principles/foundations/requirements-and-specs.md): Evidence-grounded, testable specification — jobs-to-be-done, journeys, stable-ID requirements, Given/When/Then.
+- [Prioritization & appetite](docs/principles/foundations/prioritization-and-appetite.md): Choosing and sequencing across the portfolio — appetite over estimate, the bet as the unit, scoring frameworks in their place.
+- [Reliability](docs/principles/quality/reliability.md): Fault tolerance and failure modes.
+- [Observability](docs/principles/quality/observability.md): Logging, tracing, and alerting.
+- [Performance](docs/principles/quality/performance.md): Latency, throughput, and resource efficiency.
+- [Security](docs/principles/quality/security.md): Threat modelling and secure defaults.
+- [Privacy](docs/principles/quality/privacy.md): Data minimisation and consent.
+- [Accessibility](docs/principles/quality/accessibility.md): Inclusive design and WCAG compliance.
+- [The Day-2 Operational Baseline](docs/principles/delivery/day-2-operational-baseline.md): The stack-agnostic bar every project clears to be operable and debuggable on day two, plus the no-empty-capabilities and off-script-still-lands-well rules.
+- [Developer experience](docs/principles/delivery/devex.md): Fast feedback loops and ergonomic tooling.
+- [Progressive delivery](docs/principles/delivery/progressive-delivery.md): Feature flags and incremental rollout.
+- [Platform](docs/principles/delivery/platform.md): Internal platform and developer self-service.
+- [Cost engineering](docs/principles/delivery/cost-engineering.md): Cloud cost ownership and optimisation.
+- [How we structure code](docs/principles/system-design/code-structure.md): A pure core, swappable edges, and one obvious place for everything.
+- [API design](docs/principles/system-design/api-design.md): REST, gRPC, and contract-first design.
+- [Integration patterns](docs/principles/system-design/integration-patterns.md): Events, queues, and service communication.
+- [Real-time patterns](docs/principles/system-design/real-time.md): WebSocket, SSE, and streaming.
+- [Data engineering](docs/principles/system-design/data-engineering.md): Pipelines, schemas, and analytical patterns.
+- [Architecture decisions](docs/principles/system-design/architecture-decisions.md): ADRs as governed, re-evaluable records — assumptions, review triggers, supersession.
+- [Evolutionary architecture](docs/principles/system-design/evolutionary-architecture.md): Designing for change — fitness functions, architecture-as-code, strangler-fig modernization, advisory governance.
+- [Surface architecture](docs/principles/system-design/surface-architecture.md): Surfaces as adapters over the core — BFF seam, micro-frontends, render placement, design-system-as-contract.
+- [Identity & access](docs/principles/system-design/identity-and-access.md): Authn/authz as architecture — OIDC/OAuth2.1, SPIFFE workload identity, first-class agent identity, modelled authorization.
+- [Durable execution](docs/principles/system-design/durable-execution.md): Workflow-as-code — checkpointed long-running/multi-step processes, orchestration vs choreography, the substrate for durable agents.
+- [AI engineering](docs/principles/ai-native/ai-engineering.md): Prompts, evals, and model integration.
+- [Agent-native systems](docs/principles/ai-native/agent-native-systems.md): Designing for agentic workloads.
+- [Agentic systems](docs/principles/ai-native/agentic-systems.md): Agents as first-class actors — topology, MCP/A2A/AG-UI, memory, durable execution, guardrails, oversight.
+- [AI-native product](docs/principles/ai-native/ai-native-product.md): Product management for probabilistic systems — the continuous decision loop, evals as a product responsibility, dual success metrics, the three AI cost layers.
+- [Design foundations](docs/principles/design/design-foundations.md): The design discipline's core beliefs — taste as input, implemented specification as output, every interface state designed.
+- [Visual design](docs/principles/design/visual-design.md): Perceptual colour (OKLCH), typographic rigour, modelled light and depth, hierarchy by weight before size.
+- [Layout & space](docs/principles/design/layout-and-space.md): Spacing scale, grid, intrinsic and fluid layout, container queries, density, responsiveness.
+- [Interaction & motion](docs/principles/design/interaction-and-motion.md): Affordance and feedback, the full set of interface states, purposeful motion, perceived performance.
+- [Usability & UX](docs/principles/design/usability-and-ux.md): Heuristics and UX laws, cognitive load, forms, error prevention, navigation and scent.
+- [Design systems & tokens](docs/principles/design/design-systems-and-tokens.md): Token tiers and naming, theming, components as contracts, design-system governance.
+- [AI-native design](docs/principles/design/ai-native-design.md): Designing probabilistic and generative features — latency, confidence, failure, autonomy, chat-vs-GUI.
+- [Postgres](docs/principles/stack/postgres.md): Schema design, migrations, and query patterns.
+
+## System
+- [Architecture](docs/architecture/index.md): Service topology and communication patterns.
+- [Infrastructure](docs/architecture/infrastructure.md): Boot order, ports, health checks, and run commands.
+- [Domain](docs/architecture/domain/): Entity definitions, lifecycle state machines, and invariants.
+- [Decisions](docs/architecture/decisions/): Architectural decision records.
+
+## Stack principles (added by generators)
+<!-- Stack-specific docs are appended here when a generator deploys them. -->

package/src/docs/principles/ai-native/agent-native-systems.md

@@ -0,0 +1,90 @@
+---
+title: Agent-Native Systems
+description: Making APIs and docs AI-consumable — MCP, llms.txt, structured metadata, and the interfaces that let agents work alongside humans.
+status: active
+last_reviewed: 2026-06-19
+---
+# Agent-Native Systems
+
+## TL;DR
+
+AI agents read our APIs, our events, and our documentation programmatically. Building agent-native systems means designing every interface — contract, spec, doc page — so that an agent can consume it without a human translator in the loop. MCP for structured tool surfaces, machine-readable docs for retrieval, stable error codes, rich OpenAPI examples — the pieces compose into a system agents can work inside. The catch: an agent is an *untrusted, retrying, context-limited* consumer, and the parts of this stack that are genuinely durable are not the same as the parts the market is currently hyping.
+
+## Why this matters
+
+The organisation that takes agent-readiness seriously in 2026 gets a multiplier on every engineer's output. Agents write code faster, answer questions faster, and onboard faster when the systems they are working against are designed for them. The organisation that treats agent-readiness as an afterthought pays the cost in a constant low-grade friction: agents that need babysitting, outputs that need correction, onboarding that requires a human bootstrapping step for every task.
+
+The investment is mostly the same hygiene that serves human engineers — typed contracts, worked examples, stable error codes. That overlap is the point: agent-readiness is rarely a separate budget line, and the work that pays off is the work you would defend on its own merits anyway. Be suspicious of any "agent-ready" task that only helps agents; it is usually a bet on a convention that has not earned its keep.
+
+## Our principles
+
+### 1. Every interface has a machine-consumable specification
+
+HTTP endpoints have OpenAPI; events have AsyncAPI; the tools an agent should use have MCP schemas; documentation has machine-readable exports. An interface without a machine-consumable spec is off-limits to agents by default — and, in practice, hard for humans to integrate against too. This is the load-bearing principle of the whole page; the rest are refinements of it.
+
+### 2. Specifications include descriptions, examples, and constraints
+
+A spec that says a field is `string` without saying what the string represents is a spec an agent cannot use correctly. We write descriptions, give examples, enumerate finite domains, and state constraints explicitly. The standard is: a competent agent should be able to use the interface without reading the implementation.
+
+Worked examples carry more weight than prose. A concrete sample invocation disambiguates a schema faster than a paragraph of description, and model providers now treat examples as first-class — Anthropic's tool-use examples and OpenAI's schema examples both exist because example-grounding measurably improves correct tool use. When you have one good description and one good example to write, write the example.
+
+### 3. MCP is our standard tool surface — and we treat it as an attack surface
+
+When we want agents to *act* on the system beyond reading, we expose the capability through a Model Context Protocol server. This is no longer a bet: MCP launched November 2024 and within a year was adopted across Anthropic, OpenAI, Google, Microsoft, and AWS and placed under vendor-neutral foundation governance. It is the interop layer. A bespoke prompt-engineering integration is the deprecated pattern.
+
+Two things that "MCP is the standard" does not let you skip:
+
+**Security.** An MCP tool's *description and output are model input* — they steer the agent. That makes them an injection vector, not just metadata. The documented failure modes are real and named (OWASP published an MCP Top 10 in 2025): tool poisoning (malicious instructions hidden in a tool description the user never sees), rug pulls (a trusted tool silently mutating its behaviour after approval), and prompt injection riding in on tool *results* from upstream data. The 2025 Supabase/Cursor incident — a privileged agent reading attacker-controlled support tickets as instructions and exfiltrating tokens — is the canonical example. So: tool descriptions and tool outputs are untrusted input. Servers run least-privilege (scoped credentials per tool, never a blanket service-role key), destructive or irreversible operations require an out-of-band confirmation step, and tool definitions are version-pinned and re-reviewed on change rather than trusted on first approval.
+
+**Scale.** Loading every tool's full schema into context up front does not scale — a large surface can burn six figures of tokens before the agent does any work, and a model reasoning over hundreds of tools picks worse. The decision rule: under ~20 stable tools, define them directly. Past that, do not flatten everything into the context window — use on-demand tool discovery (defer loading; let the agent search for the tool it needs) or let the agent *write code* against a typed API instead of issuing one tool call per step. Anthropic's November 2025 code-execution-with-MCP work reported the latter taking a ~150K-token tool surface down to ~2K. This is the same instinct as the next anti-pattern, made quantitative.
+
+### 4. Documentation ships in a machine-readable channel
+
+Every docs page ships a plain-text/Markdown export an agent can fetch and read without parsing HTML, JavaScript, or rendered layout. This is the durable, uncontested half of "AI-readable docs," and we do it unconditionally: it is cheap, it serves our own retrieval and agent pipelines directly, and it degrades gracefully for any consumer.
+
+`llms.txt` — a curated index file pointing at those exports — is the contested half, and we are deliberate about *why* we ship it. As of 2026 no major AI provider (OpenAI, Google, Anthropic, Meta) commits to reading `llms.txt` in production; Google has stated plainly it does not use the file and that it offers no search-visibility benefit, and site adoption sits around one in ten. So `llms.txt` is **not** an SEO or third-party-crawler play, and we do not justify it that way. Its real value is as an index for the agents *we* control — our own assistants, RAG indexers, and internal tooling, which can be pointed at a clean manifest instead of crawling a sitemap. Decision rule: ship the per-page `.md` exports always; ship `llms.txt` when we operate agents that will consume it, and skip it if our only argument for it is hoping someone else's crawler honours it.
+
+### 5. Error responses are structured, stable, and actionable
+
+Every error carries a stable code, a human message, and machine-readable details. The code is catalogued and never renumbered. Agents branch on codes; they do not parse prose. This is the single highest-leverage API hygiene choice for agent-readiness — and it costs nothing a human integrator would not also thank you for. The detail object should carry what the caller needs to *recover*, not just diagnose: which field failed, the constraint it violated, and whether a retry could ever succeed (a `429` with backoff guidance is actionable; a bare `500` is a guessing game).
+
+### 6. Idempotency enables retry
+
+Agents retry — on timeouts, on ambiguous failures, on their own re-planning. Systems that penalise retry — duplicate records, doubled charges, phantom events — cannot be worked against reliably. Every write endpoint accepts an idempotency key ([API Design](../system-design/api-design.md)); every event consumer is de-duplicating ([Integration Patterns](../system-design/integration-patterns.md)). Make the *contract* explicit too: state how long a key is honoured and what a replay returns, because an agent that cannot tell "already done" from "do it again" will eventually do it again.
+
+### 7. Constrain the artifact, not the reasoning
+
+When an agent produces a structured result — a database record, an API payload, a configuration fragment — we constrain *that artifact's shape* with schema-constrained generation (JSON schema with strict mode, or tool calling) rather than free-text-then-parse. Free-text parsing is how agent pipelines become brittle, and modern strict-mode decoding makes schema conformance a near-guarantee rather than a hope.
+
+The nuance practitioners learned the hard way: forcing a model to *reason inside* a rigid format degrades the reasoning itself. Tam et al. ("Let Me Speak Freely?", 2024) measured large accuracy drops on reasoning tasks when output was format-constrained versus free-form. So the decision rule is to separate thinking from emitting: let the model reason in prose (a scratchpad, a reasoning field, or a first turn), then emit the constrained artifact (a second turn, or a dedicated tool call). Constrain the part that has to be machine-valid; do not strangle the part that has to be correct.
+
+Related, and often confused: structured outputs fix the *shape of an answer the model must give*; tool calling lets the model *choose whether and which action to take*. Reach for structured outputs when you always need a typed result back; reach for tool calling when the model is deciding what to do next.
+
+### 8. Documentation is reviewed for agent consumption
+
+When we write a page, we ask: would an agent reading this through a text channel understand what to do? If the page assumes visual hierarchy, colour, or context that does not survive serialisation, we re-shape it. Agent-readiness is a docs quality attribute, not a separate track of work — and the reshaping (explicit structure, stated assumptions, source-form diagrams) makes the page better for the human skimming it on a phone, too.
+
+## How we apply this
+
+- [API Design](../system-design/api-design.md) — the OpenAPI discipline that makes our APIs agent-consumable.
+- [Documentation](../foundations/documentation.md) — the dual-audience docs stance.
+
+## Anti-patterns we reject
+
+- **Auth flows that require human interaction.** A consent screen with a "click here" button is a dead end for an automated client. Design auth that supports programmatic token issuance — and scope those tokens to the task, since an agent credential is exactly what an injection attack wants to steal.
+- **Prose-only error responses.** `"something went wrong"` is unusable by any automated caller.
+- **Undocumented "internal" APIs.** An API without a spec is an API that agents cannot use — which means humans will be asked to do the thing an agent should be doing.
+- **MCP tools that wrap everything.** An MCP server that mirrors every endpoint in the API is noise that costs tokens and degrades tool selection. Expose the capabilities agents actually need, named in the agent's vocabulary; for large surfaces, prefer on-demand discovery or code execution over loading every schema up front (Principle 3).
+- **Trusting tool descriptions and tool output.** Treating an MCP tool's metadata or an upstream tool result as safe instruction is how prompt injection and tool poisoning land. It is untrusted input; gate the privileged action.
+- **Documentation that leans on rendered visuals.** An architecture diagram nobody can parse from Markdown is a diagram an agent cannot read. Prefer Mermaid source in the Markdown.
+- **Shipping `llms.txt` as an SEO bet.** If the only reason to add it is hope that a third-party crawler honours it, skip it — that bet has not paid off (Principle 4).
+
+## Further reading
+
+- *Model Context Protocol* ([modelcontextprotocol.io](https://modelcontextprotocol.io)) — the canonical MCP specification.
+- *OWASP Top 10 for MCP* — the named threat taxonomy (tool poisoning, rug pulls, injection) behind Principle 3's security stance.
+- *Code execution with MCP* (Anthropic engineering, November 2025) — the tool-surface scaling argument and the code-over-tool-calls pattern.
+- *llms.txt specification* ([llmstxt.org](https://llmstxt.org)) — the convention, read alongside the honest adoption picture in Principle 4.
+- *"Let Me Speak Freely? A Study on the Impact of Format Restrictions on Performance of Large Language Models"* — Tam et al., 2024 ([arXiv:2408.02442](https://arxiv.org/abs/2408.02442)) — evidence for constraining the artifact, not the reasoning.
+- *OpenAPI Specification* ([openapis.org](https://www.openapis.org)) — the HTTP contract format.
+- *Simon Willison's blog* ([simonwillison.net](https://simonwillison.net)) — ongoing, practical commentary on the state of tooling.