@opengroundplan/core 0.1.1

package/registry/skills/test-first/references/anti-patterns.md

@@ -0,0 +1,178 @@
+# Test anti-patterns
+
+Named failure modes. Use the names in reports so the same problem gets the same label.
+
+---
+
+## A-01 The assertion-free test
+
+```
+test("handles the request", () => { handleRequest(input); });
+```
+
+**Why it exists:** it is the cheapest way to raise a coverage number.
+**What it costs:** full coverage credit, zero protection. Delete the function body and it still passes.
+**Spot it:** no assertion, or the only assertion is "did not throw".
+**Fix:** assert the observable outcome. If there is no observable outcome, the function's contract is unclear — that is the real finding.
+
+---
+
+## A-02 The test that was never red
+
+Written after the code, passed on first run, never observed failing.
+
+**What it costs:** it may be passing for a reason unrelated to the behavior — asserting on a default, a stale fixture, or a value that would be right either way.
+**Spot it:** any test added in the same commit as its implementation, with no evidence of a failing run.
+**Fix:** break the implementation deliberately and confirm the test fails. Ten seconds; it is the only thing that proves the test tests anything.
+
+---
+
+## A-03 Mock theater
+
+```
+expect(repo.save).toHaveBeenCalledWith(order);
+expect(mailer.send).toHaveBeenCalledAfter(repo.save);
+```
+
+**What it costs:** the test asserts *how* the code is written, not what it does. Any refactor breaks it; no bug is caught, because the mocks always behave.
+**Spot it:** assertions about call counts, arguments, and ordering, with no assertion on a result or state.
+**Fix:** assert the outcome — the order is retrievable, the message is on the queue. Keep interaction assertions only where the interaction *is* the contract (a webhook must be sent), and then only one.
+
+---
+
+## A-04 The mock pyramid
+
+Six mocks, forty lines of setup, one assertion.
+
+**What it costs:** the test verifies your model of the collaborators, not the system. When production breaks, this test stays green.
+**Spot it:** mock count ≥ 3, or setup 3× longer than the assertion.
+**Fix:** this is an integration concern in a unit test's clothing. Either move it up a level and use real collaborators, or split the unit so it has fewer collaborators. See the design-smell table in SKILL.md.
+
+---
+
+## A-05 Snapshot rot
+
+A large snapshot that gets regenerated whenever it fails.
+
+**What it costs:** the update becomes reflexive. Nobody reads a 400-line diff, so genuine regressions get committed as "snapshot updated".
+**Spot it:** snapshots over ~30 lines; commit history showing snapshot updates with no reasoning.
+**Fix:** assert on the specific fields that matter. Reserve snapshots for output that is genuinely opaque and genuinely stable, and keep them small enough to read in review.
+
+---
+
+## A-06 The flaky test we retry
+
+Marked with a retry, a sleep, or a quarantine tag.
+
+**What it costs:** worse than deleting it. It trains everyone to disbelieve red, which is the one signal the suite exists to produce.
+**Spot it:** retry configuration, `sleep` in test code, skip/quarantine annotations, tests that fail only in CI.
+**Fix:** find the cause — shared state, real time, ordering dependence, unawaited async, network. If you cannot fix it today, **delete it and record the gap**. A known gap beats a lying suite.
+
+---
+
+## A-07 Shared mutable fixture
+
+One fixture object, mutated across tests.
+
+**What it costs:** order dependence. Tests pass in the suite, fail alone, or fail when a new test is inserted.
+**Spot it:** module-level mutable state, `beforeAll` building objects that tests modify, tests that fail when run individually.
+**Fix:** build fresh state per test. Use a factory with sensible defaults and per-test overrides.
+
+---
+
+## A-08 Testing the framework
+
+Asserting that the ORM saves, the router routes, the validator validates.
+
+**What it costs:** slow tests, maintenance on every upgrade, no defect ever caught.
+**Spot it:** the test's assertions would still hold if your code were deleted.
+**Fix:** test *your* logic. At the framework boundary, test your configuration of it — that the right validation rule is applied, not that validation works.
+
+---
+
+## A-09 Implementation-mirroring test
+
+The test restates the implementation, including its bugs.
+
+```
+// impl: return items.filter(i => i.qty > 0).length
+test(...) { expect(count(items)).toBe(items.filter(i => i.qty > 0).length) }
+```
+
+**What it costs:** it can never fail meaningfully. Any bug in the implementation is faithfully reproduced in the expectation.
+**Spot it:** the expected value is computed rather than written literally.
+**Fix:** write the expected value by hand from a concrete input. Literal expectations are the whole point.
+
+---
+
+## A-10 The everything test
+
+One test, fifteen assertions, covering signup through checkout.
+
+**What it costs:** the first failure hides the rest; the name says nothing; every change touches it.
+**Spot it:** a test name containing "and", or a test longer than a screen.
+**Fix:** split by behavior. Shared setup goes in a helper, not in a merged test.
+
+---
+
+## A-11 Conditional logic in a test
+
+`if`, loops, or try/catch inside the test body.
+
+**What it costs:** a test with branches has untested branches. A loop can silently assert nothing when the collection is empty.
+**Spot it:** control flow in test code.
+**Fix:** parameterized/table-driven tests for repetition, separate tests for separate branches. Assert the collection is non-empty before looping over it.
+
+---
+
+## A-12 Time and randomness bombs
+
+Tests depending on the real clock, timezone, locale, or unseeded randomness.
+
+**What it costs:** passes today, fails at a month boundary, on a CI machine in another timezone, or one run in fifty.
+**Spot it:** direct calls to now/today/random in code under test; date literals near boundaries.
+**Fix:** inject the clock and the random source. This is also the design fix — hidden global dependencies were the actual problem.
+
+---
+
+## A-13 Coverage-driven tests
+
+Tests written to cover a line, not to verify a behavior.
+
+**What it costs:** maintenance with no protection, plus a coverage number that misleads everyone reading it.
+**Spot it:** tests for getters, constructors, and generated code; tests added in bulk with mechanical names.
+**Fix:** delete them. Replace with tests for the behaviors that matter. See `test-design.md` on why the threshold caused this.
+
+---
+
+## A-14 The bug fixed without a test
+
+A defect is fixed; no failing test preceded it.
+
+**What it costs:** nothing prevents the regression, and nobody can tell later whether the fix was ever verified.
+**Spot it:** a fix commit with no test change.
+**Fix:** always reproduce first. Write the test, watch it fail *for the reported reason*, then fix. The failing test is also your proof that you understood the bug.
+
+---
+
+## A-15 Slow suite tolerated
+
+The unit suite takes minutes, so nobody runs it before pushing.
+
+**What it costs:** the feedback loop that makes TDD work is gone. Tests become a CI formality.
+**Spot it:** real I/O, real sleeps, or a full app boot in tests labeled "unit".
+**Fix:** separate fast from slow explicitly; keep the fast set genuinely fast. Move I/O behind a port and use a fake. A suite nobody runs locally is a suite that stops shaping the design.
+
+---
+
+## Quick triage
+
+| Symptom | Likely | First check |
+|---|---|---|
+| Coverage high, bugs still ship | A-01, A-13 | mutation probe |
+| Every refactor breaks tests | A-03, A-09 | are assertions on outcomes? |
+| Tests pass alone, fail together | A-07 | shared mutable state |
+| CI red at random | A-06, A-12 | time, randomness, ordering |
+| Nobody runs tests locally | A-15 | what I/O is in the "unit" suite? |
+| Snapshot updated in most PRs | A-05 | snapshot size |
+| Regression of a bug fixed last month | A-14 | was there ever a failing test? |

package/registry/skills/test-first/references/test-design.md

@@ -0,0 +1,156 @@
+# Test design
+
+## Why coverage percentage fails as a target
+
+Coverage measures **execution**, not **verification**. The distinction is the entire problem.
+
+```
+// 100% line coverage. Zero assertions. Verifies nothing.
+test("processes an order", () => {
+  processOrder(sampleOrder);
+});
+```
+
+That test executes every line of `processOrder`. Delete the discount calculation, invert the tax logic, return `null` — it still passes. A coverage tool reports it as fully covered.
+
+This is Goodhart's Law in its purest form: *when a measure becomes a target, it ceases to be a good measure*. A mandated threshold creates pressure to produce exactly the tests above, because they are the cheapest way to move the number. The result is a suite that is expensive to maintain, slow to run, and incapable of catching a regression — while reporting green on a dashboard that leadership trusts.
+
+Secondary failure modes of a hard threshold:
+
+- **Testing the trivial to fund the number.** Accessors and constructors get tests because they are cheap coverage; the branchy pricing logic stays untested because it is expensive.
+- **Deleting code to hit the number.** Removing a defensive branch nobody tests raises coverage and lowers safety.
+- **Blocking correct work.** A small, well-tested change gets rejected because it lands in a file whose *existing* coverage is low.
+- **Punishing error handling.** Error paths are hard to trigger, so they are the first thing excluded.
+
+**Use coverage the other way round.** It is a good detector and a bad target. Uncovered lines are a question — "is this behavior meant to be unverified?" — and the answer is sometimes legitimately yes. High coverage answers nothing.
+
+If your repo mandates a gate, satisfy it and ignore it as a quality signal. Say so plainly rather than implying the number means something.
+
+---
+
+## What to target instead
+
+### 1. Behavior coverage
+
+Every acceptance criterion in `specs/NNN-slug/spec.md` maps to at least one test that fails if that criterion breaks. Track it as a list, not a percentage:
+
+```
+AC1 rejects expired tokens          → auth_test: rejects_expired_token          ✓
+AC2 refreshes within grace window   → auth_test: refreshes_inside_grace_window  ✓
+AC3 audit entry on every rejection  → (none)                                     ✗ unpinned
+```
+
+Three lines of that are worth more than any coverage report. It says exactly what is unprotected.
+
+### 2. Mutation resistance
+
+The real question: **if the code were subtly wrong, would a test fail?** Test it directly.
+
+**The manual mutation probe** — no tooling required, five minutes, brutally informative:
+
+1. Pick the function you most want to trust.
+2. Make one small semantic change: flip `>` to `>=`, swap `&&` for `||`, negate a condition, delete a line, return a constant, change an off-by-one.
+3. Run the suite.
+4. **A test must fail.** If none does, that behavior is unpinned regardless of coverage.
+5. Revert. Repeat 3-5 times across the branchiest code.
+
+Every surviving mutation is a missing test, located precisely. Automated mutation tools do this exhaustively where they exist for the stack; the manual probe works everywhere and takes minutes.
+
+Report as: `5 mutations probed, 4 killed, 1 survived (boundary at the retry cap is unpinned)`.
+
+### 3. Failure-mode coverage
+
+Production incidents concentrate on paths nobody tested. For each unit, ask:
+
+- What does it do when its dependency times out? Returns an error? Returns malformed data?
+- What does it do with empty input? Null? A value at the type's limit?
+- What happens if it is called twice concurrently? Retried after a partial failure?
+- What does the caller see — a typed error, a generic exception, or a silent default?
+
+A happy-path-only suite tests the case that was never going to break.
+
+### 4. Boundary coverage
+
+For anything numeric, ordered, or sized: **zero, one, many, max, and one past each edge.** Off-by-one is still, decades on, one of the most common defect classes, and it lives exclusively at these values.
+
+---
+
+## Structuring a test
+
+**Arrange / Act / Assert**, visually separated. If Arrange dwarfs the other two, the design is telling you something (see the design-smell table in SKILL.md).
+
+**Name by behavior and outcome.** The name should let a reader understand the failure without opening the test:
+
+| Weak | Strong |
+|---|---|
+| `testValidate` | `rejects_token_expired_before_grace_window` |
+| `test_user_1` | `returns_empty_list_when_user_has_no_orders` |
+| `works` | `retries_once_then_surfaces_the_upstream_error` |
+
+**One reason to fail.** Multiple assertions are fine when they describe one outcome (three fields of one returned object). They are not fine when they describe three behaviors — you lose which one broke, and the first failure hides the rest.
+
+**Assert on outcomes, not interactions.** `expect(result.total).toBe(...)` survives refactoring. `expect(calculator.applyTax).toHaveBeenCalledAfter(...)` breaks on every refactor and catches nothing a result assertion would miss.
+
+**Make the failure message do the work.** You will read it while something is on fire. Include the input that produced the failure.
+
+---
+
+## Test doubles: use the lightest one that works
+
+| Double | Use when | Cost |
+|---|---|---|
+| **Real object** | it is fast, deterministic, side-effect free | none — prefer this |
+| **Stub** | you need a canned return to drive a path | low |
+| **Fake** | you need working behavior without the real cost (in-memory store) | medium; must stay faithful |
+| **Mock** | the *interaction itself* is the behavior under test (a message must be published) | high; couples to implementation |
+| **Spy** | you need to observe without changing behavior | medium |
+
+Rules:
+
+- Mock at your **own** boundaries — the ports you defined — not at third-party internals. Mocking someone else's library means testing your belief about their behavior.
+- **Never mock the thing you are testing.** Partial mocks of the unit under test are a design smell wearing a disguise.
+- A test with more than ~2 mocks is usually integration work being forced into a unit test.
+- If you fake an external service, keep a small contract test against the real one — otherwise the fake drifts and your green suite lies.
+
+---
+
+## Levels
+
+| Level | Verifies | Keep it | Ratio |
+|---|---|---|---|
+| **Unit** | one unit's decisions in isolation | fast, in-memory, no I/O | most tests |
+| **Integration** | units plus a real boundary (db, queue, http) | few, focused on the seam | some |
+| **Contract** | two modules still agree on a shape | one per published surface | few |
+| **End-to-end** | a whole user-visible flow works | the critical paths only | fewest |
+
+The shape is a pyramid because cost and flakiness rise with level while diagnostic precision falls. An e2e failure says "something broke"; a unit failure says "this function's boundary condition broke".
+
+Do not push an integration concern down into a unit test with a wall of mocks. That tests the mocks. Push it up.
+
+---
+
+## Characterizing untested code
+
+When you must change code that has no tests:
+
+1. **Do not fix anything yet.** Read enough to guess what it does.
+2. Write a test asserting what you *believe* happens. Run it.
+3. If it fails, the code does something else. **Change the test to match the code**, not the code to match the test — you are recording reality, including bugs.
+4. Repeat until the behaviors you are about to change are pinned.
+5. Now change the code. Tests that break tell you exactly what you altered.
+6. A pinned behavior that was actually a bug: fix it as its own deliberate change, with its own test, and say so.
+
+The point is a safety net, not correctness. Correctness comes after.
+
+---
+
+## When TDD is the wrong tool
+
+Be honest about this — dogma costs credibility.
+
+- **Genuine exploration.** You do not know what you are building. Spike freely, then throw the spike away and rebuild test-first. Do not ship the spike.
+- **Pure UI arrangement.** Visual layout is verified by looking at it. Pin the *logic* behind the UI; do not assert on markup structure.
+- **Code that is about to be deleted.** A one-week migration script does not need a suite.
+- **Generated code.** Test the generator, not the output.
+
+Everywhere else — especially anything with a branch, a boundary, or money in it — write the test first.

package/registry/skills/test-first/skill.yaml

@@ -0,0 +1,7 @@
+id: test-first
+kind: skill
+name: Test-First Development
+description: Drive code through red → green → refactor, targeting behavior coverage and mutation resistance rather than a coverage percentage.
+tags: [testing, tdd, quality, workflow]
+targets: [claude-code, cursor, github-copilot, windsurf, cline, codex, gemini-cli, agents-md]
+requiresCapability: [instructions]

package/templates/README.md

@@ -0,0 +1,104 @@
+# Templates
+
+The composable pieces Groundplan assembles a repository from. Four kinds, applied in order:
+
+| Kind | Count | What it contributes | How many apply |
+| --- | --- | --- | --- |
+| `bases/` | 10 | The runnable skeleton: language, framework, build, entrypoint | exactly one |
+| `architectures/` | 22 | A layout overlay plus the check that keeps it true | at most one |
+| `layers/` | 22 | A capability: auth, database, CI, Docker, observability | any number |
+| `agent-kits/` | 1 | `AGENTS.md` and the delegation contract every repo gets | always |
+
+Each directory holds a `blueprint.yaml` (identity, variables, file rules, conflicts) and a
+`files/` tree whose paths and contents carry `{{ }}` tokens. Nothing is copied verbatim — see
+`docs/ARCHITECTURE.md` for the rendering and merge rules.
+
+## Architecture overlays
+
+An overlay is **not** just folders. Each one ships the enforcement that makes its rule
+survive contact with a real team: a dependency-free Node script, an `import-linter` contract,
+a Go `boundary_test.go`, a .NET fitness-test project, or several at once. A layout without a
+check is a suggestion; with one it fails the build.
+
+Every overlay is stack-gated. Choosing an architecture on a stack it has no rules for emits
+no files — check the Stacks column before pairing one with a base.
+
+| Overlay | Enforces | Stacks | Checks shipped |
+| --- | --- | --- | --- |
+| `agentic-tool-loop` | Tool definitions stay separate from the loop that calls them | node, python, typescript | node, import-linter, pytest |
+| `bff` | Each frontend gets its own backend; no shared god-API | node, typescript | node |
+| `clean` | Dependencies point inward, toward the domain | dotnet, go, node, polyglot, python, typescript | node, import-linter, go, .NET |
+| `cqrs` | Commands and queries never reach into each other | dotnet, node, python, typescript | node, import-linter, .NET |
+| `event-driven` | Handlers depend on the event catalog, never on each other | dotnet, node, python, typescript | node, import-linter, pytest, .NET |
+| `feature-sliced-design` | Layer import order (app → pages → features → shared) | node, typescript | node |
+| `hexagonal` | The domain talks to ports; adapters implement them | dotnet, go, node, polyglot, python | node, import-linter, go, .NET |
+| `lakehouse` | Table layers stay ordered; no skipping upstream | python | import-linter, pytest |
+| `layered` | No layer reaches past the one beneath it | dotnet, go, node, python, typescript | node, import-linter, go, .NET |
+| `llm-workflow` | Predefined code paths; the model fills steps, not control flow | node, python, typescript | node, import-linter, pytest |
+| `medallion` | Bronze → silver → gold, with skip-layer bans | python | import-linter, pytest |
+| `micro-frontends` | Remotes stay independently buildable | node, typescript | node |
+| `microservices` | Services share contracts, never each other's internals | dotnet, go, node, python, typescript | node, import-linter, pytest, go, .NET |
+| `modular-monolith` | Modules touch only published module APIs | dotnet, go, node, python, typescript | node, import-linter, pytest, go, .NET |
+| `monolith` | Features stay private; one deployable | dotnet, go, node, python, typescript | node, import-linter, pytest, go, .NET |
+| `multi-agent` | Orchestrator drives workers; workers stay unaware | node, python, typescript | node, import-linter, pytest |
+| `mvc-mvvm` | Views never reach models directly | dotnet, python, typescript | node, import-linter, pytest, .NET |
+| `onion` | Concentric dependencies, domain at the core | dotnet, go, node, python, typescript | import-linter, go, .NET |
+| `pipes-and-filters` | Stages compose through one contract | go, node, python, typescript | node, import-linter, pytest, go |
+| `rag-hybrid` | Retrieval stays separable from generation | node, python, typescript | node, import-linter, pytest |
+| `serverless` | One function per entrypoint; no shared mutable runtime | node, python, typescript | node, import-linter, pytest |
+| `vertical-slice` | Slices never reference each other | dotnet, go, node, python, typescript | node, import-linter, pytest, go, .NET |
+
+### Catalogued without an overlay
+
+Two entries in `catalog/architectures/` deliberately ship no folder overlay, and `doctor`
+reports them as expected rather than missing:
+
+- **`ddd-tactical`** — tactical DDD (aggregates, value objects, repositories) fills in the
+  core of another pattern rather than defining a layout of its own. Pair it with `clean`,
+  `hexagonal`, or `onion`.
+- **`nextjs-colocation`** — this *is* the Next.js App Router's own default layout, so the
+  `nextjs-app` base already produces it. An overlay would only restate the base.
+
+## Conventions
+
+**One base, one architecture, many layers.** Bases are mutually exclusive; the resolver
+rejects a second one.
+
+**Conflicts are declared on both sides.** The resolver reports a conflicting pair only from
+the lexicographically first id, so a one-sided declaration silently does nothing when the
+other id sorts first. Declare it in both blueprints.
+
+**Two blueprints may write one destination only with an explicit `onConflict`.** Otherwise
+the plan fails with `both write <path>`. Prefer `merge` / `merge-json` for manifests; use
+`overwrite` or `skip` when one blueprint genuinely supersedes another, and say why in a
+comment. Because which of two layers applies second depends on selection order, the pair
+needs handling on both sides to be order-independent.
+
+**Dependencies are declared, not installed.** A package added by a `postApply` step is
+missing from the first install. Contribute to `package.json`, `pyproject.toml`, `go.mod`, or
+`Directory.Packages.props` with `onConflict: merge` instead (ADR 0005, spec 003).
+
+**A fitness test needs something to assert on.** A namespace or folder holding no type is
+invisible to reflection, so a seed type ships with each layout — otherwise the check passes
+while enforcing nothing.
+
+## Verifying a change
+
+```bash
+pnpm -r build
+pnpm --filter @opengroundplan/core test
+node packages/cli/dist/index.js doctor
+```
+
+Green gates are necessary, not sufficient. `CONTRIBUTING.md` is explicit that the proof that
+counts is a generated repo that builds:
+
+```bash
+node packages/core/scripts/generate.mjs <tmpdir> <base> <overlay-id> core
+cd <tmpdir> && dotnet build && dotnet test    # or the stack's equivalent
+```
+
+Generate against **every** base the overlay claims to support. Bases differ in ways the
+templates do not see: `dotnet-aspire` pulls in transitive packages that a `*.Api.dll` glob
+will match, and a solution name containing a reserved word (`Event`, `Base`) changes the
+namespaces analyzers see. Both classes of bug pass the test suite and fail the build.

package/templates/agent-kits/core/blueprint.yaml

@@ -0,0 +1,39 @@
+id: core
+kind: agent-kit
+name: Agent kit
+description: >
+  AGENTS.md as the single source of truth, the tool-neutral .agent/ handoff protocol,
+  and spec-driven scaffolding. Always applied — a repo without it is invisible to agents.
+
+tags: [agents, specs, always]
+
+requires: []
+conflicts: []
+provides: [agents-md, agent-protocol, specs]
+supportsArchitectures: []
+
+variables:
+  # buildCommand / testCommand / lintCommand are supplied by the engine from the chosen
+  # base blueprint — asking a user who just picked Next.js for their build command is noise.
+  - name: delegationTable
+    prompt: Delegation routing table
+    type: string
+    required: false
+    default: '_No delegation routes declared._'
+
+files:
+  # The canonical instruction file. Everything else in the repo points at this.
+  - from: files/AGENTS.md
+    to: .
+
+  # Tool-neutral state, so one tool can resume what another started.
+  - from: files/.agent/**
+    to: .
+
+  - from: files/specs/**
+    to: .
+
+  - from: files/docs/**
+    to: .
+
+postApply: []

package/templates/agent-kits/core/files/.agent/ACTIVE.md

@@ -0,0 +1,25 @@
+# Active Work
+
+<!-- Overwrite this file. One task in flight at a time. -->
+
+**Status:** idle
+**Tool:** —
+**Started:** —
+
+## Task
+
+_Nothing in flight. Replace this section when you pick up work._
+
+## Scope
+
+Files and directories this task is allowed to touch:
+
+- _none yet_
+
+## Not in scope
+
+- Anything under the protected paths listed in `{{ agentsMdPath }}`.
+
+## Next step
+
+_—_

package/templates/agent-kits/core/files/.agent/DECISIONS.md

@@ -0,0 +1,27 @@
+# Decisions
+
+<!-- Append only. Newest at the bottom. Never edit or delete an earlier entry. -->
+
+Record a decision when you chose between real alternatives. The rejected option is the part
+nobody can reconstruct from the code later.
+
+Format:
+
+```
+## YYYY-MM-DD — <short title>
+**Context:** what forced a choice
+**Decision:** what was chosen
+**Rejected:** what was not chosen, and why
+**Consequence:** what this now makes hard or easy
+```
+
+---
+
+## {{ today }} — Repository scaffolded
+
+**Context:** {{ solutionName | title }} needed a starting architecture and agent wiring.
+**Decision:** Scaffolded with Groundplan; `{{ agentsMdPath }}` is the single source of truth for
+agent instructions, and every tool-specific file is a wrapper or a delta over it.
+**Rejected:** Per-tool instruction files maintained independently — guarantees drift.
+**Consequence:** Changing agent guidance means editing one file. Tool-specific files must
+never restate canonical content.

package/templates/agent-kits/core/files/.agent/DELEGATION.md

@@ -0,0 +1,30 @@
+# Agent Delegation
+
+Routing table for {{ solutionName | title }}. Rendered from `agent-kit`'s `delegation`
+field — edit the agent-kit source, never this file.
+
+Different agents are good at different jobs and priced differently. Pick by task, not habit.
+
+{{ delegationTable }}
+
+## Handoff protocol
+
+Any tool may pick up work any other tool started. State lives in plain markdown at fixed
+paths under `.agent/`, so no vendor session is ever required to resume.
+
+| File | Role | Write discipline |
+|---|---|---|
+| `.agent/ACTIVE.md` | What is in flight right now | Overwrite — one task at a time |
+| `.agent/HANDOFF.md` | State needed to resume in a *different* tool | Overwrite at each handoff |
+| `.agent/DECISIONS.md` | Why things are the way they are | Append only |
+| `.agent/DONE.md` | Execution log | Append only |
+
+### Rules
+
+- Update `.agent/ACTIVE.md` when you start a task and when you stop, even mid-task.
+- Write `.agent/HANDOFF.md` before ending a session with work unfinished. Assume the next
+  reader has none of your context and cannot see your conversation.
+- Append to `.agent/DECISIONS.md` when you choose between real alternatives. Record the
+  rejected option — that is the part nobody can reconstruct later.
+- Never rewrite history in the append-only files. A wrong entry gets a correcting entry.
+- Canonical project instructions stay in `{{ agentsMdPath }}`. Never copy them here.

package/templates/agent-kits/core/files/.agent/DONE.md

@@ -0,0 +1,9 @@
+# Execution Log
+
+<!-- Append only. Newest at the bottom. One line per completed unit of work. -->
+
+Format: `YYYY-MM-DD | tool | what shipped | verified by`
+
+---
+
+{{ today }} | groundplan | scaffolded {{ solutionName | kebab }} | `{{ buildCommand }}`

package/templates/agent-kits/core/files/.agent/HANDOFF.md

@@ -0,0 +1,38 @@
+# Handoff
+
+<!-- Overwrite at each handoff. Assume the reader has zero context and a different tool. -->
+
+**From:** —
+**To:** any tool
+**At:** —
+
+## What I was doing
+
+_—_
+
+## What is done
+
+- _—_
+
+## What is not done
+
+- _—_
+
+## How to verify
+
+Run these and expect them to pass before continuing:
+
+```
+{{ testCommand }}
+{{ lintCommand }}
+```
+
+## Traps
+
+Things that cost me time and will cost you time too:
+
+- _—_
+
+## Suggested next tool
+
+See the routing table in `.agent/DELEGATION.md`.