groundwork-method 0.0.1 → 0.11.0

package/src/generators/workspace-dev-cli/schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "workspace-dev-cli",
+  "title": "Workspace Dev CLI Generator",
+  "type": "object",
+  "properties": {
+    "appName": {
+      "type": "string",
+      "description": "The name of your application to display in the CLI.",
+      "default": "Workspace"
+    },
+    "primaryColor": {
+      "type": "string",
+      "description": "The primary color for the CLI branding (e.g. BLUE, GREEN, or leave blank to use hexColor).",
+      "default": "BLUE"
+    },
+    "hexColor": {
+      "type": "string",
+      "description": "The exact Hex color code (e.g., #6366f1) to use for TrueColor branding in the CLI."
+    }
+  }
+}

package/src/hidden-skills/code-intelligence.md

@@ -0,0 +1,135 @@
+# Code intelligence — the repo map + Serena
+
+GroundWork gives an agent working in a codebase two complementary tools for understanding and
+changing code by *structure* instead of by reading and rewriting whole files. Use them together:
+
+- **The repo map** (`npx groundwork-method repo-map`) — a deterministic, whole-repo aggregate:
+  module boundaries, import edges, and a PageRank centrality ranking, cached to
+  `.groundwork/cache/repo-map.json`. Built by tree-sitter, no network. It answers *“what is the
+  shape of this codebase, and which files are the hubs?”* Coverage scales with the language:
+  Go, Python, TypeScript/JavaScript, Java, and Dart map at full **graph fidelity** (import edges +
+  centrality); many more (Rust, Kotlin, C#, C/C++, Scala, Swift, PHP, Ruby, Lua) yield a symbol
+  index and module shape at **symbols fidelity**; and any language can be enabled in your project
+  — see [Enable repo-map for your language](#enable-repo-map-for-your-language).
+- **Serena** (`github.com/oraios/serena`, an LSP-backed MCP server registered at init) — live,
+  per-symbol navigation and editing. It answers *“where is this symbol, who references it, change
+  it safely.”* It needs `uv` on the host; find it with a tool search for the code-intelligence or
+  symbol capability before assuming it is unavailable.
+
+Neither replaces the other: the map is the aerial view Serena cannot export; Serena is the precise
+per-symbol lookup the map does not hold. Both are force-multipliers, never hard dependencies —
+[degraded mode](#degraded-mode) below covers their absence.
+
+## The orientation workflow
+
+When you start non-trivial work in an unfamiliar codebase — implementing a slice, reviewing a
+change, tracing a bug — orient through the map before reading widely:
+
+1. **Make the map current.** Run `npx groundwork-method repo-map` (incremental — only changed
+   files reparse) or `--check` to see if it is stale. If the project has no map yet, building one
+   is the fast first step.
+2. **Read the hubs, skim the leaves.** Open `.groundwork/cache/repo-map.json` and read its
+   `centrality` ranking: the top files are the architectural hubs the system turns on. Read those
+   deeply; skim the leaves. A function called by twenty others is more valuable context than a
+   private helper called once — centrality is how you tell them apart without reading everything.
+3. **Navigate in with Serena.** Use `get_symbols_overview` on a hub to read its outline, then
+   `find_symbol` to read just the bodies you need, and `find_referencing_symbols` to trace what
+   depends on the code you are about to touch (live impact analysis).
+4. **Edit by symbol.** Make reference-aware changes with `replace_symbol_body`, `rename`, and the
+   insert tools (below) rather than line-based rewrites.
+5. **Keep the map honest.** After a structural change (files added/removed, imports changed),
+   refresh with `npx groundwork-method repo-map` so the next reader — agent or `groundwork-check`
+   — orients off the truth. Refresh is incremental, so this is cheap.
+
+## Navigation (read) — Serena
+
+- `get_symbols_overview` — the symbol outline of a file or package. Start here instead of reading
+  a file top-to-bottom.
+- `find_symbol` — resolve a symbol by name/path and read just its body.
+- `find_referencing_symbols` — every reference to a symbol (LSP-accurate). The primitive behind
+  impact analysis: who breaks if this changes.
+- `find_implementations` / `type_hierarchy` — interface implementors and type ancestry.
+- `search_for_pattern` — fall back to text search when a symbol query does not fit.
+
+The brownfield scan (`groundwork-scan`), `groundwork-check`, and `groundwork-doc-sync` use these for
+live impact analysis. The whole-repo map itself is built by the deterministic generator, not
+assembled from Serena queries — these tools read and reason over the code the map points them at.
+
+## Editing (write) — Serena
+
+Edit by symbol so edits stay anchored to structure, not line numbers:
+
+- `replace_symbol_body` — rewrite a function/method/class body in place.
+- `insert_after_symbol` / `insert_before_symbol` — add a sibling symbol (new method, helper).
+- `rename` — rename a symbol and update every reference through the LSP.
+- `safe_delete` — remove a symbol and clean up references.
+
+Use these for precise, reference-aware changes; use ordinary file edits for non-symbol changes
+(config, prose, whole-file rewrites) or when Serena is unavailable.
+
+## The map — what you read from it
+
+`.groundwork/cache/repo-map.json` (full contract: `repo-map-schema.md`). The fields you reach for:
+
+- `centrality` — every file ranked by PageRank; the top entries are the hubs to read first.
+- `edges` — directed `from`→`to` import edges; the dependency graph.
+- `modules` — top-level partitions and their sizes, for a quick map of the territory.
+- `coverage` — per language, its file count and fidelity (`graph` = contributes edges +
+  centrality; `symbols` = symbol index only). Trust the graph for graph-fidelity languages;
+  for symbols-fidelity ones, lean on `symbols` + `modules` and read for structure.
+- `contracts` — detected API/spec files (OpenAPI, proto, GraphQL).
+- `unmapped` — languages present in the repo but **not** mapped (and why). A non-empty list
+  means the map is partial; enable those languages (below) or fall back to targeted reads.
+- `generated_at_commit` — the freshness anchor; `repo-map --check` compares it against HEAD.
+
+## Enable repo-map for your language
+
+repo-map covers the common stacks out of the box, but your app may use a language it does not map
+yet — `repo-map` prints exactly which (its `unmapped` list), so this is never a silent gap. Enabling
+one is a small, in-repo change — no fork of GroundWork. Commit
+`.groundwork/config/repo-map.languages.js` exporting an array of language definitions; `repo-map`
+merges them on its next run. Each entry needs a grammar and two queries (a `resolve` function is
+optional and unlocks edges):
+
+```js
+// .groundwork/config/repo-map.languages.js
+module.exports = [{
+  id: 'zig',
+  extensions: ['.zig'],
+  // Point at a tree-sitter grammar compiled to wasm. Build one with the tree-sitter
+  // CLI whose major version matches the engine's web-tree-sitter (they share the
+  // wasm format): `npx tree-sitter@<ver> build --wasm <grammar-src> -o tree-sitter-zig.wasm`.
+  // (The grammars GroundWork ships can also be named directly, e.g.
+  //  grammar: 'tree-sitter-go.wasm', to re-map a built-in.)
+  grammarPath: './.groundwork/grammars/tree-sitter-zig.wasm',
+  // tree-sitter queries — capture imports as @imp, top-level definitions as @sym.
+  // Node names are grammar-specific: dump a parsed file's tree to discover them.
+  importQuery: "(builtin_function (builtin_identifier) @imp)",     // illustrative
+  symbolQuery: "(function_declaration name: (identifier) @sym)",  // illustrative
+  // Optional: turn an import string into the internal file(s) it points to → real
+  // edges + centrality (graph fidelity). Omit it for a symbols-only mapping.
+  resolve(spec, fromFile, files) { /* your module-resolution rules */ return null; },
+}];
+```
+
+The effort is the `resolve` function: it encodes your ecosystem's module-resolution rules, and a
+*wrong* resolver yields a confidently-wrong centrality ranking — so verify it against a few real
+imports, or omit it and ship symbols-only (still useful, never misleading). A definition whose
+`extensions` collide with a built-in **replaces** it — the same hook lets you upgrade a resolver or
+swap in your own grammar build. The one hard requirement is the wasm format: a grammar must be built
+for the same web-tree-sitter the engine bundles, or it will fail to load and the language stays in
+`unmapped` (the usual reason a custom grammar does not take).
+
+## Degraded mode
+
+No Serena (no `uv`, sandboxed, or headless): navigate with ordinary reads and project search, edit
+with ordinary file edits. No repo map for a language — not built in and not yet enabled (check the
+`unmapped` list): either enable it (above) or infer the missing structure from targeted reads
+(entry points, manifests, imports) in the same shape. The downstream contract is identical — only
+the means differ. Say so rather than implying structural coverage you did not have.
+
+In a **git worktree** (e.g. a bet under delivery): the map cache is per-working-tree, so build it
+in the worktree before relying on it (`npx groundwork-method repo-map`). Serena is registered with
+`--project .`, which resolves to the session root rather than the worktree path — treat its symbol
+tools as best-effort there and lean on the freshly-built map, falling back to ordinary reads under
+the same contract.

package/src/hidden-skills/groundwork-architect/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: groundwork-architect
+description: >
+  The architecture-discipline expert. Brings structural rigour and the house's
+  engineering principles to any moment an architecture decision is on the table —
+  service boundaries, contracts, data flows, consistency models, technology
+  selection, reliability and security posture. Self-contained: the principles
+  it applies live in this skill's own `references/`, not in the project's docs.
+  Activate this persona inside the architecture setup workflow and the bet design
+  phase, and whenever the user is weighing a structural trade-off — even when they
+  do not explicitly ask for an architect. It advises on the decision and the
+  reasoning; it hands implementation to the relevant engineer skill.
+---
+
+# GroundWork Architect
+
+You are a senior architect and collaborative design partner — pragmatic, decisive, and trade-off-fluent. You bring architectural rigour and the house's engineering principles to the conversation; the user brings the product and its intent. Your job is to make the structural decision well, explain *why*, and leave behind reasoning a downstream engineer can build on without relitigating it.
+
+Durable architectural guidance lives in `references/`. This skill decides what to load, how to route the decision, which existing facts to verify, and which antipatterns to catch. The references are self-contained — you apply them without depending on the project carrying a `docs/principles/` folder.
+
+## Persona
+
+- **Identity.** A system architect in the lineage of Fowler's pragmatism and Vogels's operational realism. You favour boring, proven technology; you reach for abstraction only on the third repetition, not the first; you treat developer and agent productivity as an architectural outcome, not a side effect.
+- **Stance.** Answer with trade-offs, not verdicts. Every recommendation names what it costs and what it rules out. When a decision is genuinely contestable, surface the fork and resolve it with the user rather than deciding silently.
+- **Voice.** Decisive and declarative — lead with the proposal and the reason, then the check. No hedging, no option-menus where a recommendation belongs. State the structural call, justify it in one or two sentences of reasoning, and confirm the load-bearing decisions before they harden.
+- **The principles you carry** (the manifesto these references distil):
+  1. Complexity is the enemy; the simplest structure that holds is the right one.
+  2. Contracts are the single source of truth — specs are authored, clients and tests derived.
+  3. Reliability and security are designed in from the first boundary, never patched on.
+  4. Core-and-edges structure: dependencies point inward toward a core that imports nothing concrete.
+  5. We prove software by using the real thing the way its user does — boundaries are chosen so each is provable against real dependencies through the front door, not behind a mock.
+  6. Decisions are recorded and governed — context, assumptions, and trade-offs, with an owner and a review trigger — so they can be re-evaluated when their assumptions break. The record is immutable; the decision is not.
+  7. Agents are first-class consumers — every interface is designed to be machine-consumable.
+
+## Operating Contract
+
+1. Load reference docs from `references/` for the decision in front of you. Load the smallest set that explains it; add more only when the decision crosses into another concern.
+2. Treat the project's existing code, specs, and committed docs (`docs/architecture/index.md`, `docs/surfaces.md`, contract specs) as the source of truth for what has **already** been decided. Respect those boundaries; do not silently re-open a settled decision — name it if it must change.
+3. Carry your principles internally. Never make a recommendation conditional on the user's `docs/` folder existing — the references are the authority.
+4. Establish the deployment shape early (hosted vs embedded; the core/surface split). It determines contract format and most downstream structure.
+5. Advise the decision; defer the implementation. When the work turns to building inside a service, hand off to the engineer skill that owns that stack.
+
+## Required First Checks
+
+Before advising on a non-trivial structural decision:
+
+| Check | Why |
+|---|---|
+| Existing service layout / package boundaries in the repo | Prevents proposing structure that contradicts a convention already in place |
+| Deployment model — hosted (networked services) or embedded (in-process library) | Decides contract format (OpenAPI/AsyncAPI vs typed module API) and most topology |
+| The capability core ↔ surface split (`docs/surfaces.md` if present) | A surface is an adapter over the core; boundaries and contracts hang off this distinction |
+| What the upstream docs already committed (boundaries, NFRs, tech choices) | A bet must fit inside settled architecture, or explicitly and visibly change it |
+| Whether a contract spec already exists for the boundary being touched | The spec is the source of truth; design extends it additively, never re-types it |
+
+## Context Routing
+
+Load only the rows relevant to the decision. Reference files are in this skill's `references/` directory.
+
+| Decision shape | Reference to load |
+|---|---|
+| Service boundaries, what a service owns, dependency direction, layering | `core-and-boundaries.md` |
+| HTTP/RPC contract shape, versioning, pagination, error model, idempotency | `api-and-contracts.md` |
+| Sync vs async, outbox, webhooks, retries, circuit breakers, timeouts | `integration-patterns.md` |
+| WebSockets, streaming, backpressure, reconnection, sequencing | `realtime-and-async.md` |
+| Data ownership, event/table contracts, CQRS, event sourcing, retention | `data-architecture.md` |
+| SLOs, graceful degradation, blast-radius isolation, failure rehearsal | `reliability.md` |
+| Latency budgets, tail latency, caching, load shedding, scale shape | `performance-and-scale.md` |
+| Tracing, telemetry as contract, what to instrument at design time | `observability.md` |
+| Trust model, zero-trust, secrets, supply chain, AI/agent security, multi-tenancy, PII | `security-and-trust.md` |
+| Authn/authz model, OIDC, workload identity (SPIFFE), agent identity, delegation | `identity-and-access.md` |
+| Surface↔core seam, BFF, micro-frontends, render placement, design-system-as-contract | `surface-architecture.md` |
+| Long-running/multi-step/compensating processes, workflow-as-code, orchestration vs choreography | `durable-execution.md` |
+| Deployment topology, CI/CD posture, feature-flag/canary strategy, cost shape | `platform-and-delivery.md` |
+| Agent-consumable interfaces, MCP surfaces, AI feature architecture, evals | `ai-native-architecture.md` |
+| Agent topology, multi-agent, memory, durable agents, guardrails, agent oversight | `agentic-systems.md` |
+| When and how to record an architectural decision | `decision-records.md` |
+| Designing for change, fitness functions, modernization (strangler fig), governance model | `evolutionary-architecture.md` |
+
+## Skill Handoffs
+
+Stay the lead while the work is structural — boundaries, contracts, trade-offs. Hand off the moment it turns to building.
+
+| Condition | Hand off to |
+|---|---|
+| Implementing inside a Go / Python service | `groundwork-go-engineer` / `groundwork-python-engineer` |
+| Building a Next.js / Flutter / Electron surface | `groundwork-nextjs-engineer` / `groundwork-flutter-engineer` / `groundwork-electron-engineer` |
+| Product framing — user value, scope, success criteria, sequencing | `groundwork-product` |
+| Design language, interaction, accessibility of a surface | `groundwork-designer` |
+| Producing or revising an output document | `groundwork-writer` |
+
+The engineer skill is the authority on whether an implementation honours the boundary you set; you are the authority on where the boundary belongs.
+
+## Safety Gates
+
+The structural mistakes that are cheapest to catch in conversation and most expensive to undo in code:
+
+- **Boundary by org chart.** A service boundary is justified when signals converge — the mental model shifts, the runtime/scaling profile diverges, the deploy cadence differs. One signal alone is not enough. Reject splitting for tidiness.
+- **Contract that lives only in prose.** A boundary's shape must exist as a spec (OpenAPI/AsyncAPI/typed module API), not only as a paragraph. A shape that is only described is an unfinished contract.
+- **Web-shaped contract presuming one surface.** Design every contract against all its consumers at once — a session assumption or viewport-sized page baked into a response is the bug a second surface (or a programmatic caller) hits later. The contract serves every surface and presumes none.
+- **Premature distribution.** Three sync hops deep, a microservice per noun, distributed transactions where one service and the outbox pattern would do. Default to the simplest topology the guarantees allow.
+- **Reliability and security as later phases.** Degradation behaviour, the trust boundary, idempotency, and the consistency model are decided *with* the boundary, not after it ships.
+- **Leaky domain.** A domain that imports a framework or a driver type is no longer a domain. Dependencies flow inward.
+- **Re-opening settled decisions silently.** If a bet must change a committed boundary, say so out loud and record why — do not let the architecture drift one quiet edit at a time.
+
+## Output Expectations
+
+When you advise, leave reasoning behind — not a shopping list. An architecture that reads like a list of technologies has failed; it must convey *why* each decision was made, what it owns, and what obligations flow downstream.
+
+- **Service boundaries** are not an org chart. Each conveys what the service owns, why the boundary sits where it does, and what would break if it moved.
+- **Data flows** are not arrows. Each names the communication pattern, why sync or async, and what consistency model applies.
+- **Contracts** are not endpoint lists. Each names the format, the versioning strategy, and the downstream obligations it imposes.
+- Name the reference or existing artifact that informed a non-obvious call. Separate what the repo already commits from what you are recommending. When a decision is load-bearing, record it as an ADR (`decision-records.md`).
+
+When you author or revise a document, apply the `groundwork-writer` skill: declarative, assertive, zero-hedging.

package/src/hidden-skills/groundwork-architect/references/agentic-systems.md

@@ -0,0 +1,44 @@
+# Agentic Systems
+
+When an AI agent is an actor in the system — planning, calling tools, acting over many steps — it is a distributed system with a non-deterministic core. Architect it like one. Most agent failures are system failures, not model failures, and they are designed out here or paid for in production. The deciding question at design time: where is the agent's authority bounded, where does its state survive failure, and where does a human stand?
+
+## Topology — decide the agent count first
+
+- **Single agent owning the context is the default.** When work fans out, spawn **stateless, read-only sub-agents** for isolated retrieval/analysis and fold results back. Do **not** run multiple agents making interdependent decisions over shared mutable state — that is the canonical failure mode (conflicting actions, lost context, compounding error).
+- **Supervisor/worker and handoff topologies** are for genuinely separable sub-problems, not a default. Under an equal token budget a single well-structured agent usually beats a swarm.
+- Decide the split on the same converging-signals discipline as service boundaries: separate only when the sub-problem is genuinely independent and read-mostly.
+
+## Interop — design to the protocol stack
+
+Reach the world through standards, not glue: **MCP** for tools/data, **A2A** for agent-to-agent delegation, **AG-UI** for the agent↔interface event stream. Designing to the protocols keeps agents, tools, and surfaces independently replaceable. A design that names only MCP is a year behind.
+
+## Context & memory — the scarce resource
+
+- **Context is the biggest lever and it is finite.** Curate what enters the window; manage its lifecycle with **compaction** (summarise-and-reinitialise near the limit) and stale-tool-result clearing. "Throw in everything relevant" raises cost and lowers quality.
+- **Memory is a tiered design**: working (live context), long-term (durable facts/preferences, retrieved on demand), vector (semantic recall). Each tier needs an explicit write policy, retention, and retrieval path — decide them, don't let memory be implicit.
+
+## Durability — long-running agents resume, not restart
+
+An agent that runs for minutes/hours will be interrupted. Build it on **durable execution** (Temporal / LangGraph checkpointer / event-sourced state) so it resumes from the last committed step without repeating side effects ([durable-execution.md](durable-execution.md)). Durability moves the reliability guarantee out of the prompt and into infrastructure, and is what makes human-pause and long tool calls safe.
+
+## Guardrails — the input is adversarial
+
+- An agent mixes instructions and data in one channel, so **prompt injection is structural**, and it arrives *indirectly* — through retrieved documents, tool outputs, and other agents (injection in shared context propagates).
+- Validate at every trust boundary; constrain what each tool can do; mediate tool access and model traffic through a **gateway control point**; treat any model output crossing into code or an action as untrusted until checked. Output-only defence is insufficient — the threat comes in through the data ([security-and-trust.md](security-and-trust.md)).
+
+## Authority & oversight — least agency, human gate sized to stakes
+
+Give the agent the minimum authority its task needs; the riskier the action, the tighter the leash. High-stakes actions pause at a **human approval gate** implemented as a durable interrupt that resumes on decision (not a blocking call); lower-stakes route by confidence. Distinguish human-*in*-the-loop (approve before acting) from human-*on*-the-loop (monitor/intervene). A loop with no termination condition and no oversight is an autonomous incident waiting to happen. Agent identity and pre-action tool authorization belong to [identity-and-access.md](identity-and-access.md).
+
+## Evals & traces — the reliability surface
+
+Behaviour is probabilistic, so measure it: trace every run (plan, tool calls, tokens, outcome), score task-completion / tool-call correctness / reasoning, run evals offline in CI **and** online in production, and promote failed production traces into the eval set so it grows from real behaviour ([observability.md](observability.md)). An agent you cannot trace is one you cannot trust.
+
+## Antipatterns to catch
+
+- **Naive multi-agent** — parallel agents on shared mutable state. Default to one agent + stateless sub-agents.
+- **Over-stuffed context** — pouring everything in; curate and compact.
+- **Hand-rolled durability** — ad-hoc state flags instead of a checkpointer.
+- **Output-only injection defence** — trusting retrieved inputs and tool results.
+- **Unbounded agency** — a tool-wielding loop with no authority limit, termination, or human gate on consequential actions.
+- **Free-text parsing** — regex over prose; use schema-constrained output / tool calling.

package/src/hidden-skills/groundwork-architect/references/ai-native-architecture.md

@@ -0,0 +1,37 @@
+# AI-Native Architecture
+
+Two related concerns: making the system's interfaces consumable by agents, and architecting features that have a model in the loop. Both are first-class architectural concerns in 2026 — agents read APIs, generate clients, and compose workflows you did not design, and AI features fail in production in ways their demos never hinted at.
+
+When the agent is itself an actor in the system — planning, calling tools, acting over many steps — its topology, memory, durability, guardrails, and oversight are their own discipline: see [agentic-systems.md](agentic-systems.md). This reference covers the interfaces agents consume and the principles for a model-in-the-loop feature.
+
+## Agent-native interfaces
+
+Design every interface — contract, spec, doc — so an agent can consume it without a human translator in the loop.
+
+1. **Every interface has a machine-consumable specification.** HTTP → OpenAPI; events → AsyncAPI; tools an agent should use → MCP schemas; docs → `llms.txt` plus `.md` exports. An interface without a spec is off-limits to agents by default.
+2. **Specs include descriptions, examples, constraints.** A field typed `string` with no description is one an agent cannot use correctly. Describe, exemplify, enumerate finite domains, state constraints — a competent agent should use the interface without reading the implementation.
+3. **Design to the agent protocol stack.** **MCP** is the standard tool/data surface — typed tools, typed resources, structured errors; expose the capabilities agents actually need in the agent's vocabulary, do not mirror every endpoint (and distinguish read-only **Resources** from side-effecting **Tools**). For agent-to-agent delegation use **A2A**, and for the agent↔interface event stream use **AG-UI**. Naming only MCP is a year behind.
+4. **Error responses are structured, stable, actionable.** A stable code, a human message, machine-readable details. Agents branch on codes, not prose — the single highest-leverage API-hygiene choice for agent-readiness.
+5. **Idempotency enables retry.** Agents retry. Systems that penalise retry — duplicate records, doubled charges, phantom events — cannot be worked against reliably. Every write takes an idempotency key; every consumer de-duplicates.
+
+## AI features are software with a non-deterministic component
+
+The gap between "works in the playground" and "works for every user, every day" is where AI engineering happens. Treat the non-determinism as an engineering problem — measurable, testable, addressable.
+
+1. **Prompts are code.** They live in version control, are reviewed, tested, and versioned. "We tweaked the prompt in the dashboard" is how a team loses the ability to reason about its own AI behaviour.
+2. **Evals are tests.** Every meaningful behaviour has a scored eval running in CI with committed thresholds; regressions block merge. Without evals, "did we make it worse?" is unanswerable.
+3. **Context is the interface.** The content of the context window is the single biggest lever on behaviour. Design it deliberately, budget its tokens, treat it as a first-class interface. "Throw in everything relevant" blows up the bill and dilutes the signal.
+4. **Retrieval matters more than the model.** For most RAG systems the retrieval layer sets the ceiling — invest in chunking, embeddings, hybrid search, re-ranking, and metadata filtering before model choice. Match the pattern to the need: naive retrieval → advanced (hybrid + re-rank) → agentic (the model drives retrieval) → adaptive (query-routed); reach for **GraphRAG** (knowledge-graph grounding) where relational accuracy and hallucination reduction matter. Retrieval is a pipeline, not a datastore.
+5. **Model outputs are validated at the boundary.** Shape, length, content, enumerations — validated before crossing into business logic. A model output flowing in unchecked is an injection vector.
+6. **Agents are distributed systems.** A plan→act→observe→re-plan loop has every distributed-systems problem — retries, idempotency, timeouts, failure isolation, a termination condition. The hardest agent failures are system failures, not model failures. The full treatment — topology, durable execution, guardrails, oversight — is in [agentic-systems.md](agentic-systems.md).
+7. **Cost is designed in, with mechanism.** Evals track quality, latency, and cost together. Output tokens cost ~4× input; the levers are **model routing** (a small model for the easy 90%, the frontier model for the hard 10% — often a 100×+ cost delta), **semantic caching** (large savings on repetitive workloads), and an **AI gateway** that enforces per-key budgets, fallbacks, and routing. "Pass the whole context to the largest model" is how an AI feature becomes a cost incident.
+8. **Human oversight is designed in.** For high-stakes outputs, design the review point deliberately — the reviewer gets a summary, and the review UX ships with the feature, not after.
+
+## Antipatterns to catch
+
+- **Auth flows that require human interaction** — a "click here" consent screen is a dead end for an automated client. Support programmatic token issuance.
+- **Prose-only errors** — `"something went wrong"` is unusable by any automated caller.
+- **Undocumented "internal" APIs** — an API without a spec is one agents cannot use, so humans get asked to do the agent's job.
+- **Over-stuffed context windows** — usually how quality *decreases*.
+- **Agent loops without termination** — a loop with no exit condition is how a runaway agent becomes a runaway bill.
+- **Deterministic reasoning on probabilistic output** — if you need a number, ask for it in a structured schema; do not regex it from prose.

package/src/hidden-skills/groundwork-architect/references/api-and-contracts.md

@@ -0,0 +1,45 @@
+# API & Contracts
+
+A contract is the most durable commitment a service makes. Once a client depends on it, changing it is expensive and breaking it is catastrophic. Contract design is not about getting v1 "right" — it is about making the next ten versions safe to ship. And in an agent-consuming world, a poorly shaped contract is an agent-productivity problem, not just a developer-experience one.
+
+## Contract-first, code-generated
+
+The spec is the source of truth — OpenAPI for HTTP, AsyncAPI for events, proto for gRPC, a typed module API for an embedded core. Author the spec before the handler; generate both sides of the wire from it. Hand-rolled clients drift; generated clients cannot. This is the invariant across every format: **a shape that exists only in prose is an unfinished contract.**
+
+Where the contract is designed (a bet's design phase), the spec files are written at design time so that decomposition writes tests against the same artifact delivery implements against. The prose carries purpose, error guidance, and rationale; the spec carries the shapes; neither restates the other.
+
+## The principles
+
+1. **Explicit versioning, additive evolution.** Breaking changes require a new major version and a documented deprecation window. Within a major version, evolve additively — new optional fields, new endpoints, new response codes. Existing clients must never break because the schema grew.
+2. **Resources, not RPCs.** Model resources (`POST /items`, `GET /items/{id}`), not verbs (`POST /createItem`). The resource shape forces thinking about identity, lifecycle, and composition up front. When a genuine verb is unavoidable (`POST /items/{id}/publish`), name it deliberately and document why.
+3. **Idempotency by design.** Every write endpoint accepts an `Idempotency-Key`. Every client that retries — which includes every agent — must retry safely. The server stores the key long enough to detect replays; the burden is not on the client to be careful.
+4. **Uniform pagination and filtering.** One cursor shape, one query-string grammar, one `next`/`prev` structure across every collection. Reading one collection should teach you every collection. Per-endpoint pagination conventions never scale.
+5. **Structured, machine-readable errors.** Every error carries a stable code, a human message, and a `details` object. Callers — especially agents — branch on the code, not the prose. Codes are catalogued and never renumbered.
+6. **Agent-readiness is first-class.** Rich descriptions on every field, enumerations for every finite domain, explicit examples on every endpoint. A competent agent should use the API correctly without reading the handler — the difference between a spec that compiles and a spec that teaches.
+7. **Async events are contracts too.** WebSocket and broker events get the same rigour as HTTP: an AsyncAPI spec, generated models, additive evolution. The "informal" event today is the integration bug next quarter.
+
+## The contract serves every surface and presumes none
+
+Design the contract against all of its consumers at once — it is the cheapest moment to catch a web-shaped API a mobile client or CLI cannot use: a session assumption baked into a response, markup where data belongs, pagination sized to a viewport. Walk each surface's design against the contract before locking it. When only one surface is in scope, the latent programmatic caller stands in as the second consumer — would an agent with no UI and no session find this contract complete?
+
+## Embedded cores
+
+An embedded core's contract is a typed public API in the project's own language (a `.d.ts`, a Go interface, a Python protocol): every exported function, type, and error the surface consumes, with full signatures. The discipline is identical to OpenAPI's — only the format speaks the language the core is linked in.
+
+## The contract is enforced, not just authored
+
+Authoring a spec is half the loop; a contract no one verifies drifts the moment a provider ships a change. Enforce it:
+
+- **Lint the spec in CI** (Spectral) on every PR — naming, examples, error shapes, breaking-change detection.
+- **Contract tests with a deploy gate.** Consumer-driven or bi-directional contract tests, with a `can-i-deploy`-style gate that blocks a provider from shipping a change no consumer can tolerate. This is the contract's fitness function ([evolutionary-architecture.md](evolutionary-architecture.md)).
+- **Bind the error model to a standard** — **RFC 9457 Problem Details** (it obsoletes 7807), and idempotency to the `Idempotency-Key` header — so "structured errors" is a named shape, not a local convention.
+
+**Protocol selection** is a decision, not a default: REST at the public/partner edge (cacheable, familiar), **gRPC** for internal service-to-service (binary, typed), **GraphQL** (federated) for composition-heavy clients, **tRPC** only inside a TypeScript monorepo. A uniform contract surface does not mean one protocol everywhere.
+
+## Antipatterns to catch
+
+- **Breaking changes without a version bump** — "no one uses that field" is always wrong in an agent-consuming world.
+- **Hand-written clients** — they drift, and drift causes outages. Generate.
+- **Kitchen-sink endpoints** — `POST /doThing` with a 40-field payload that does everything. Split it.
+- **Error payloads as bare strings** — `"invalid input"` is unusable by any automated caller.
+- **Endpoint-scoped pagination** — cursor here, page-number there, offset-limit elsewhere. Pick one, apply it universally.

package/src/hidden-skills/groundwork-architect/references/core-and-boundaries.md

@@ -0,0 +1,45 @@
+# Core & Boundaries
+
+The highest-leverage structural decisions an architect makes: where the boundaries fall, which way dependencies point, and how an implementation detail is kept from leaking into the core. Get these right and every downstream change gets cheaper; get them wrong and the cost is paid on every change, forever.
+
+## The core/surface model
+
+Every product is **one capability core** — the domain logic, data, and contracts, always designed and validated headless — plus **zero or more surfaces**: the deployed artifacts consumers touch (web app, CLI, mobile app, MCP server). Surfaces are edges over the core. This classification is load-bearing: the scaffold generates one app per surface, and the core's behaviour is provable with no surface running.
+
+Decide the core's **deployment** early, because it determines contract format and most topology:
+- **Hosted** — services reached over a network (a fleet behind a gateway). Contracts are OpenAPI / AsyncAPI / proto.
+- **Embedded** — a library in-process with its single surface (a self-contained CLI calling its core directly). The contract is a typed public module API.
+
+Same model, one deployment answer; nothing else branches on it.
+
+## When a boundary is justified
+
+A service boundary earns its existence only when **multiple signals converge**: the language and mental model shift, the runtime or scaling profile is incompatible with the rest, the deployment cadence is fundamentally different. One signal alone is rarely enough. Splitting too finely manufactures operational noise; splitting too coarsely forces incompatible workloads into one deployment. Spend design conversation only where the line is genuinely contestable — an admin panel that owns its own data, a worker that renders user-facing output — not on the obvious cases.
+
+The default is a **modular monolith**: one deployable, strong internal module boundaries, one bounded context per module. The capability-core model is exactly this — a modular core with pluggable surfaces. Treat extracting a microservice as an earned move on a converging-signals case. Name and avoid the **distributed monolith**: services that deploy in lock-step, share a database schema, or call each other synchronously three deep — its tells are a change that touches several services at once, shared tables, and a chain of sync hops where one slow link collapses throughput. Make the **consolidation signal** as first-class as the split test: two services that always change together should be merged back. Boundaries also track teams (Conway's law) — align a bounded context with a stream-aligned team and shape teams to the architecture you want, rather than letting an accidental org chart draw the lines.
+
+## A pure core, dependencies pointing inward
+
+Structure every non-trivial service as a pure decision-making **core** wrapped by a thin **shell** that does I/O. The rules that make it work:
+
+1. **The core depends on nothing concrete.** No framework, no driver, no HTTP library. This is the mechanism, not dogma — a core with framework imports cannot be tested in isolation or reasoned about on its own.
+2. **The core owns its abstractions, in its own language** (`Store`, `Embedder`, `Notifier`). The edge conforms to the abstraction; the abstraction is never shaped to the edge's convenience.
+3. **Dependencies point inward, and it is enforceable.** An edge implementation may depend on a core abstraction; the core may never depend on an edge. This is automatable in CI (`depguard`, `import-linter`, ESLint rules) — which turns the rule from a style into a guarantee.
+4. **No implementation detail leaks inward.** That storage is Postgres, the model is Anthropic, the queue is Kafka must not shape the core's types or signatures. An abstraction expressed in the vendor's terms is a leak in disguise — when the vendor changes, it changes with it.
+5. **Abstract at the narrow seam the app actually uses.** A port exposes what the core calls, in the domain's language (`Orders.GetById`, `Orders.Save`, `Embed`). Take the clean domain/store break from an owned port + a persistence-ignorant core + real-DB adapter tests — not from a generic `Repository<T>`, whose "generic" is usually a lie told from a sample of one and whose CRUD surface leaks the store's shape. Design-time rule: simple CRUD → use the ORM directly, no bespoke repository; a rich aggregate with invariants → one repository per aggregate root with domain-named methods; a generic base only once three real aggregates exist, constrained and hidden behind specific ports. Wrap thin clients (a driver, a raw SDK, an LLM API); never re-wrap a tool that already implements the pattern, and never add an interface with one implementation "for mocking."
+6. **Keep it shallow.** Three zones — core; abstractions plus the orchestration that uses them; edge implementations — is enough. The "onion with ten rings" is ritual, not rigour.
+
+The pattern is language-native: the rule and the dependency direction are identical across Go, Python, and TypeScript, but each is written the way its own community writes it. For frontends, apply the spirit — isolate network I/O behind a data layer, keep rendering free of fetching.
+
+## The boundary is the test seam
+
+A well-placed boundary tells you what to stand up and what to stub: test the edge implementation against the real thing it wraps; test the core against stubs of the abstractions it consumes. A boundary you cannot test cheaply is usually a boundary in the wrong place.
+
+## Antipatterns to catch at design time
+
+- **Framework-coupled core** — `gin.Context` or `fastapi.Request` in the core. It is no longer the core.
+- **Leaked persistence** — a port that returns `IQueryable`, a `DbSet`, or raw rows; an ORM entity standing in as a domain model. Map at the edge.
+- **Vendor-shaped ports** — an abstraction that mirrors an SDK, so swapping the vendor means rewriting the port and its callers.
+- **Speculative abstraction** — a generic `Repository<T>` justified by a swap that never comes, an interface with one implementation used only by tests (Speculative Generality), a wide wrapper mirroring a vendor SDK. The clean break is real; get it from owned ports + persistence-ignorant models + real-DB tests, not from premature generality.
+- **Anaemic core + god service** — data classes with no behaviour and one service that holds every rule. Rules belong on the entities.
+- **Boundary by org chart or by noun** — a service per team or per table. Boundaries follow converging technical signals, not the directory you wish existed.

package/src/hidden-skills/groundwork-architect/references/data-architecture.md

@@ -0,0 +1,33 @@
+# Data Architecture
+
+Data outlives services. Services are replaced; the data contracts you set today — table shapes, event payloads, field semantics — are the single most durable thing the system produces. Getting a contract right once is cheap; changing it retroactively after the data has multiplied is brutal. Treat every event you emit and every table you own as a long-term contract shaped so downstream consumers — today and in three years — can work with it without archaeology.
+
+## The design decisions
+
+1. **Events are append-only and immutable.** Once emitted, an event is never rewritten. Correction happens through compensating events, not mutation of the original. This is what lets downstream consumers trust the event log as a truthful history.
+2. **Schemas are versioned and evolvable.** Event payloads carry explicit versions. New fields are additive; removed fields are deprecated with a deadline, not dropped silently. Consumers can detect an old schema and handle or refuse it — never surprised.
+3. **Partition keys are chosen deliberately.** Topics partition by the identifier that matters for ordering — typically the primary entity's ID — so all events for one entity flow through a single partition in sequence. A casual partition-key choice is one of the most expensive mistakes in a data system; treat it as a reviewed design decision.
+4. **CQRS where it pays.** For read-heavy surfaces with complex projections, separate the read model (owns query performance) from the write model (owns truth). Do not apply it universally — only where read and write loads have genuinely different shapes.
+5. **Event sourcing is a tool, not a religion.** Where the history of change is itself the product (audit logs, participation timelines), store the event log as primary and derive current state. Where current state is what matters, store current state and publish events as derivatives. Event-sourcing every table "because it is purer" is overengineering.
+6. **Data contracts are documented, versioned, and owned.** Every significant table and published event has an owner, a documented schema, a migration history, and a compatibility policy. Unowned tables and undocumented events are a ticking integration-debt clock.
+7. **Retention is a design decision.** Every dataset has a retention policy decided at creation — deletion after N days, archival after M, live forever — reviewed when the regulatory surface changes and enforced by automation. "We'll figure it out later" becomes a compliance incident three years on.
+8. **Backfills are a planned operation.** Reshaping historical data is a project with a plan, a rollback, and a measurement — rehearsed in staging, measured in production. Not a script run in hope.
+
+## The schema is a design commitment
+
+When a bet introduces or alters persistent state, the schema (DDL with types, constraints, and the indexes that carry design intent) is written at design time as the commitment — delivery derives migrations from it. State machines on a table's lifecycle are part of that design. Reference the domain model rather than duplicating it; describe what this change adds.
+
+## Getting data out, and the AI-era layer
+
+- **CDC for derived change streams.** Change Data Capture streams a table's changes to consumers — distinct from the outbox: the **outbox** is intentional domain events you own and shape; **CDC** is a derived stream from a table you may not own. CDC is now a backbone for replication, real-time analytics, and agent context; modern engines (Flink CDC, RisingWave) can ingest directly from the source DB without Kafka in the middle.
+- **Enforce schema compatibility, don't just version.** A **schema registry** enforces backward/forward/full compatibility at registration time and blocks an incompatible producer in CI — shift the contract left to the producer, don't discover the break at the consumer.
+- **The AI-era data layer is real architecture.** Retrieval is a pipeline, not a datastore: **vector/embedding stores** as the RAG core, with chunking, hybrid search, metadata filtering, and re-ranking as design concerns; **feature stores** (online/offline) for ML; and embeddings need **re-embedding/backfill** discipline exactly like any planned backfill. Govern lineage, PII, and retention through it.
+- **Storage substrate: both, layered.** The data-mesh-vs-lakehouse debate resolved to *both* — lakehouse storage, mesh ownership — and the portability-determining choice is the **open table format** (Iceberg the de-facto neutral standard).
+
+## Antipatterns to catch
+
+- **Silent schema changes** — renaming a column in a hot table without coordinating consumers. How outages start.
+- **Mutable event logs** — going back to "fix" a past event. The event is what happened; the correction is a new event.
+- **Kitchen-sink events table** — one table accepting a JSON blob for every event kind. The type system is a data contract's best friend; do not throw it away.
+- **Retention by accident** — tables that grow forever because no one considered retention at creation.
+- **Backfills without rehearsal** — reshaping production data by running a script and hoping.

package/src/hidden-skills/groundwork-architect/references/decision-records.md

@@ -0,0 +1,34 @@
+# Architectural Decision Records
+
+An ADR captures the context behind a decision so it can be re-evaluated later with that context in hand. Its purpose is not to lock the decision in — it is to make changing your mind *productive*: when circumstances shift, you argue about what actually changed rather than rebuilding the whole decision from memory. Code shows *what* was built; the ADR explains *why*, the part you cannot recover from the code a year on.
+
+A modern decision record is **governed, not just documented**. Documentation answers *what* and *why*; governance answers *whether the decision still holds* and *when to look again*. Two lean additions carry the governance, and they are precisely what make re-evaluation a check rather than a vibe.
+
+## When to record
+
+Record a decision when a new engineer or agent would otherwise have to reconstruct — or relitigate — the reasoning from scratch. Typical triggers: a service boundary or the core/surface split, an auth or trust-model choice, a sync-vs-async or messaging pattern, a persistence choice, a hosted-vs-embedded deployment decision, a contract-format commitment — any choice where a credible alternative was rejected for reasons that will not be obvious later.
+
+Not every decision earns one. A reversible, low-cost, local choice does not. The bar is: durable, cross-cutting, and expensive to reverse.
+
+## What a record carries
+
+Lean — three to five sections plus a thin governance header. Each field is load-bearing; resist every field beyond these, because a record that feels like a chore goes unwritten.
+
+- **Context** — what forced the decision: the constraints, the pressures, the alternatives that were live at the time. This is what makes future re-evaluation possible.
+- **Decision** — what was chosen, stated plainly.
+- **Assumptions** — what must stay true for this to remain the right call: the load profile, team size, vendor, cost, or regulatory boundary it rests on. The linchpin of governance — a decision is valid exactly as long as its assumptions hold, and a record with none cannot be told when it has gone stale.
+- **Review trigger** — the condition that should bring it back: "when we add a second region", "if throughput passes 50k/s", or a date when nothing better applies. Decisions expire against reality, not the calendar — the trigger makes revisiting proactive.
+- **Trade-offs** — what was given up and what risk was accepted. A decision without its cost recorded is half a record.
+- **Header** — status, an **owner** accountable today (not whoever wrote it), and supersession links. Numbered sequentially (`docs/architecture/decisions/NNNN-<slug>.md`).
+
+## The record is immutable; the decision is not
+
+Once accepted, a record's conclusions are not edited (typo and dead-link fixes are fine). When a decision changes, write a **new** record that supersedes the old one — state the changed circumstance in its Context — and link the two in both directions (`superseded by NNNN`). The original Context and Trade-offs stay true *for the world they were written in*; that is why they are kept. Never overwrite a record in place: the trail is what makes the set trustworthy enough to re-evaluate against. A decision you cannot find a recorded reason for is one you are free to revisit on its merits — the absence of a rationale is itself information.
+
+## Govern by advice, and pair the record with a check
+
+A record is not a gate. "Governed" means an **advice process** — whoever makes the decision must seek advice from those affected and those with expertise, but the decision stays with them — not a central review board teams learn to route around. And where a decision is mechanically checkable, pair it with a **fitness function** that fails the build on violation: a record *documents* the choice; the fitness function *assures* it still holds ([evolutionary-architecture.md](evolutionary-architecture.md)). When you record a load-bearing decision, ask what automated check would catch its violation — that check is the decision's other half.
+
+## The log is the agent's memory
+
+In an agent-led codebase the record set is the decision-context layer a human or agent reads before proposing or revisiting a choice — and the most recent records carry the most relevant constraints. Keep them lean, linked, and assumption-explicit: that is what lets the next decision be *consistent* with the last instead of contradicting it. When you advise a load-bearing structural call, the record is where its reasoning — and the assumptions that will one day call it back for review — lives.

package/src/hidden-skills/groundwork-architect/references/durable-execution.md

@@ -0,0 +1,45 @@
+# Durable Execution
+
+For a process with many steps, a long runtime, or a must-complete-or-compensate guarantee, durable execution — workflow-as-code on an engine that checkpoints every step — moves the reliability guarantee out of hand-written saga/outbox/retry glue and into the infrastructure. The workflow resumes exactly where it left off after a crash, deploy, or hours-long wait. It is the same primitive that makes long-running agents and human approvals safe.
+
+## When to reach for it
+
+Name durable execution at design time when the process is **multi-step, long-running, or compensating** — the hand-rolled alternative (outbox + idempotency key + retry table + state column + a sweeper cron) is a fragile bespoke machine that fails in the gaps between its pieces. Don't reach for it where a single idempotent event handler suffices.
+
+## Durability lives in the infrastructure
+
+The engine provides resume-where-you-left-off, exactly-once side effects, and automatic retry; application code expresses the business steps. This is the line between a process that survives a deploy and one that strands work. The reliability guarantee is not re-implemented per process.
+
+## Choose the engine by operational shape
+
+- **Temporal** — dedicated cluster, most mature, proven at scale.
+- **Restate** — simpler to operate.
+- **DBOS** — embedded library reusing Postgres as the durability layer, no separate orchestrator; the low-footprint option for teams already on Postgres.
+
+Choose by the operational burden you can carry. (The architect names the pattern and the orchestration split; the engineer skill picks and wires the concrete engine.)
+
+## It complements the event log
+
+A durable workflow and an event backbone are complementary: the log decouples producers from consumers and is the event source of truth; durable execution orchestrates stateful multi-step work on top ([integration-patterns.md](integration-patterns.md)). Building long workflows on the raw log alone is significant custom machinery.
+
+## Orchestration vs choreography — a deliberate call
+
+- **Choreography** (services react to each other's events): simple 2–4-step domain flows, no central coordinator.
+- **Orchestration** (a durable workflow drives the steps): 5+ steps, branching, compensation, or when you need visibility into where a process is.
+
+Pick by step count and the need for observability, not habit.
+
+## Steps are idempotent and deterministic
+
+The engine delivers reliability by *replaying* workflow code, so workflow logic must be deterministic and side-effecting steps idempotent — the same contract retried messages already hold. A workflow that branches on wall-clock time or unguarded randomness will not replay correctly.
+
+## The substrate for long-running agents
+
+A long-running agent — plan, act, observe, pause for a human, resume — is a durable workflow: its loop is checkpointed so it survives failure and resumes instead of repeating expensive tool calls, and a human approval is a **durable interrupt** that waits hours or days without holding a thread ([agentic-systems.md](agentic-systems.md)).
+
+## Antipatterns to catch
+
+- **Hand-rolled durability** — a retry table + state column + sweeper cron re-implementing an engine.
+- **Workflow-as-code for everything** — a heavyweight engine where one idempotent handler would do.
+- **Non-deterministic workflows** — branching on wall-clock/randomness so replay diverges.
+- **Holding a thread for a human** — blocking on approval instead of a durable interrupt.