@opengroundplan/core 0.1.1

package/registry/skills/architecture-guard/references/violation-catalog.md

@@ -0,0 +1,149 @@
+# Violation catalog
+
+Named failure modes, how to spot each in a diff, severity, and the fix that usually applies. Use the names in reports so the same problem gets the same label every time.
+
+Every entry assumes a rule was declared in `AGENTS.md` `boundaries[]`. Without a declared rule, these are smells, not violations.
+
+---
+
+## V-01 Upward import
+
+**What:** a lower/inner zone imports a higher/outer one.
+**Spot it:** in the diff, an added import whose resolved path maps to a zone above the importing file.
+**Severity:** high — this is the violation that makes the architecture stop meaning anything.
+**Fix:** invert the dependency. Define the interface in the inner zone; let the outer zone implement it and wire it at the composition root.
+
+---
+
+## V-02 Sibling coupling
+
+**What:** two peers at the same level import each other (feature-a → feature-b, module-a → module-b's internals).
+**Spot it:** an import path containing a second peer segment different from the importer's own.
+**Severity:** high if bidirectional (a cycle), medium if one-way.
+**Fix:** move the shared concept down to `shared`/`entities`, or communicate through the declared event/contract path. Do not add a third peer to "mediate" — that is V-08 in waiting.
+
+---
+
+## V-03 Transitive laundering
+
+**What:** the forbidden edge exists, but through an innocent hop. `domain → utils → orm-client`.
+**Spot it:** follow every edge out of the changed file two hops deep. Any module that re-exports across zones is a laundering candidate. A `utils` that imports a driver, client, or SDK is the classic tell.
+**Severity:** high — same effect as V-01, harder to see, so it survives longer.
+**Fix:** split the hop module along the boundary. The part the inner zone needs moves inward; the part touching infrastructure stays outward.
+
+---
+
+## V-04 Barrel leak
+
+**What:** an index/barrel file re-exports symbols from another zone, so importers cross a boundary without ever naming it.
+**Spot it:** any barrel whose export list resolves to more than one zone. Also: a diff that adds one line to a barrel and nothing else, while a distant file starts using a new symbol.
+**Severity:** medium — often accidental, always contagious.
+**Fix:** one barrel per zone; barrels re-export only from within their own zone.
+
+---
+
+## V-05 Deep import
+
+**What:** reaching past a module's declared public surface into its internals.
+**Spot it:** import path has more segments than the module's declared entry.
+**Severity:** medium; high if the internal is undocumented or unstable.
+**Fix:** either promote the symbol to the public surface deliberately, or add the missing capability to the surface. Never "just this once" — the second one arrives within a week.
+
+---
+
+## V-06 Type leak
+
+**What:** no illegal import statement, but a public signature exposes a type from the wrong zone — a persistence entity in a controller response, an ORM row type in a domain method, an HTTP request type in a port.
+**Spot it:** read the changed public signatures, not just the import block. Type-only imports count.
+**Severity:** medium — compiles fine, couples permanently.
+**Fix:** map at the boundary. Each zone owns its own shapes; the adapter translates.
+
+---
+
+## V-07 Framework bleed
+
+**What:** the core acquires a dependency on a framework, ORM, HTTP client, serializer, or DI container — often via a decorator, annotation, or base class rather than an import.
+**Spot it:** third-party package names appearing under the core path; annotations on domain types; a domain class extending a framework base class.
+**Severity:** high in clean/hexagonal, medium in layered.
+**Fix:** move the annotation to a persistence-side mapping, or introduce a plain core type with an outer mapper.
+
+---
+
+## V-08 Shared-module sprawl
+
+**What:** `shared`/`common`/`utils` grows until every zone depends on it and it depends on everything.
+**Spot it:** shared has imports pointing at feature/module zones (that alone is V-01), or its file count grows every sprint, or unrelated concepts sit side by side.
+**Severity:** medium as a violation only if shared imports upward; otherwise report as a smell with a proposed boundary line.
+**Fix:** split shared by concern and declare each split's allowed consumers. Kernel-style shared code holds primitives and contracts, never behavior that belongs to a feature.
+
+---
+
+## V-09 Port defined on the wrong side
+
+**What:** the interface the core depends on is declared in the adapter package, so the compile-time arrow still points outward.
+**Spot it:** an interface file whose path is under `adapters/`/`infrastructure/` and whose consumers are in the core.
+**Severity:** high — the inversion is cosmetic.
+**Fix:** move the interface into the core. The adapter package should have no exports the core imports.
+
+---
+
+## V-10 Composition-root sprawl
+
+**What:** wiring, container registration, or `new` of concrete adapters appears outside the single composition root.
+**Spot it:** direct construction of an infrastructure class in a use-case or domain file; container registration calls scattered across modules.
+**Severity:** medium.
+**Fix:** all concrete wiring in one entry point. Everything else receives its dependencies.
+
+---
+
+## V-11 Data-level coupling
+
+**What:** two modules that never import each other share a table, a queue topic, or a cache key namespace owned by one of them.
+**Spot it:** migrations and query targets, not imports. Search for the owning module's table/topic names outside that module.
+**Severity:** high — invisible to every static tool, and the most expensive to unwind.
+**Fix:** the owning module exposes an operation; the other calls it. Or the data genuinely belongs to neither and moves to a shared owner via ADR.
+
+---
+
+## V-12 Test-only escape hatch
+
+**What:** test code reaches into internals across a boundary.
+**Spot it:** deep imports under test paths.
+**Severity:** low — **but only if** `boundaries[]` grants tests a relaxation. Without a declared exemption it is a normal violation at the normal severity.
+**Fix:** usually none needed. If tests routinely need internals, the public surface is missing a seam — report as a smell and route to the **test-first** skill.
+
+---
+
+## V-13 Extended pre-existing violation
+
+**What:** the diff adds a new instance of a violation that already existed elsewhere.
+**Spot it:** the violating pattern predates the diff, but the diff adds a file or import to it.
+**Severity:** inherit the base violation's severity. This is **not** pre-existing debt — the change made it worse.
+**Fix:** do not let "it was already like this" pass. Either follow the correct pattern for the new code, or record the exception via ADR.
+
+---
+
+## Not violations (report as smells at most)
+
+| Pattern | Why it is not a violation |
+|---|---|
+| An import that no declared rule covers | No rule, no violation. Propose a rule instead. |
+| A file in a zone nobody declared | Unclassified. Report the gap in `boundaries[]`. |
+| Generated code crossing a boundary | Needs a declared exemption; flag the missing exemption, not the code. |
+| A large file, a long function, a bad name | Different review entirely. Not this skill. |
+| Duplication across two zones | Often *correct* — duplication is the price of decoupling. Only a smell if the concept is genuinely shared. |
+| A cycle within a single zone | Untidy, but no boundary crossed. Note it, do not fail. |
+
+---
+
+## Fix selection
+
+Three options, always. Present the trade-off; let the human choose.
+
+| Option | Use when | Cost |
+|---|---|---|
+| **Invert** — define the interface on the inner side | The dependency is real and needed | Indirection; one more file |
+| **Relocate** — move the code to the zone it belongs in | The code was simply in the wrong place | Touches call sites; may widen the diff |
+| **Amend the boundary** — change the declared rule | The rule no longer matches how the system should be built | Requires an ADR; affects every future change |
+
+Never pick "amend" to make a diff pass. That is the fix that quietly deletes the architecture.

package/registry/skills/architecture-guard/skill.yaml

@@ -0,0 +1,7 @@
+id: architecture-guard
+kind: skill
+name: Architecture Guard
+description: Check a change against the boundaries declared in AGENTS.md — detect illegal dependency directions and report violations without auto-fixing.
+tags: [architecture, boundaries, review, dependencies]
+targets: [claude-code, cursor, github-copilot, windsurf, cline, codex, gemini-cli, agents-md]
+requiresCapability: [instructions]

package/registry/skills/handoff/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: handoff
+description: "Write .agent/HANDOFF.md so a different AI tool or a later session can resume the work. Use when the user says handoff, pick this up in another tool, save state, where were we, wrapping up for now, /handoff — or when switching tools mid-task. Also maintains .agent/ACTIVE.md, DECISIONS.md, DONE.md. NOT for durable architecture decisions."
+metadata:
+  version: 1.0.0
+  category: workflow
+  updated: 2026-07-18
+---
+
+# Cross-Tool Handoff
+
+You are an expert at leaving exactly enough state on disk that a **different** tool — one that shares no session, no memory, and no chat history with you — can pick the work up cold and be productive in under a minute.
+
+Your goal is a file so short it gets read, and so accurate it can be trusted.
+
+## Before Starting
+
+Read, in this order:
+
+1. `AGENTS.md` — the repo's source of truth. **Never duplicate it into the handoff.** If the next tool needs to know the test command, it reads `commands.*` there; a copy in HANDOFF.md is a copy that will be wrong within a week.
+2. `.agent/ACTIVE.md` — what is in flight.
+3. `.agent/HANDOFF.md` — if it exists, it is either stale or yours to replace. Never append to it.
+4. The current working state — branch, uncommitted files, whether verification passes.
+
+## How This Skill Works
+
+**Mode 1 — Write a handoff.** Work is mid-flight and stopping. Produce the file, then say plainly what the next tool should do first.
+
+**Mode 2 — Resume from a handoff.** A handoff exists. Read it, verify each claim against the repo (branch, files, build state) before trusting it, report drift, then continue.
+
+**Mode 3 — Retire a handoff.** Work is complete. **Propose deleting `.agent/HANDOFF.md`** and moving the outcome to `DONE.md`. A stale handoff is worse than none: it sends the next agent confidently in the wrong direction, and it costs more to detect than to have never written.
+
+## The rules
+
+**≤30 lines.** Hard limit. Past that it stops being read, and an unread handoff is a stale handoff. If it does not fit, the missing context belongs in `spec.md`, `plan.md`, or an ADR — link, do not inline.
+
+**Tool-neutral.** Never mention vendor session state: no session ids, no chat-history references, no "as we discussed above", no tool-specific mechanics, no "my previous turn". The reader has none of that. Write for a stranger with a terminal and this repo. Anything only meaningful inside your own session is noise.
+
+**Facts, not narrative.** No process story. State what is true and what to do next.
+
+**Verifiable claims only.** "Tests pass" must mean you ran the declared verification. If you did not, say `not run`. A wrong build-state line destroys trust in the whole file.
+
+**No secrets, no absolute local paths.** Repo-relative paths only.
+
+## What goes in
+
+Five sections, in this order. Use [references/handoff-template.md](references/handoff-template.md).
+
+| Section | Answers | Keep to |
+|---|---|---|
+| **Goal** | What outcome are we after, and where is it specified? | 1-2 lines + link to `specs/NNN-slug/` |
+| **Status** | What is done, what is half-done, what is untouched? | 3-6 lines |
+| **Next** | The single concrete first action, then 1-2 after it | 2-3 lines, imperative |
+| **Build state** | Does it compile? Do tests pass? Which check was actually run? | 1-2 lines |
+| **Uncommitted** | Branch, dirty files, anything not on disk in a committed state | 2-4 lines |
+
+Optional sixth: **Traps** — one or two things that already cost time (a misleading error, a required env var, an ordering constraint). One line each, only if genuinely non-obvious.
+
+## What stays out
+
+- Anything already in `AGENTS.md` — stack, commands, conventions, boundaries.
+- Durable decisions → `.agent/DECISIONS.md` or an ADR.
+- Finished work narrative → `.agent/DONE.md`.
+- The full requirement list → `specs/NNN-slug/spec.md`.
+- Explanations of *why* the codebase is shaped this way → ADR.
+- Anything you did not verify.
+
+## The four-file protocol
+
+| File | Lifetime | Writer | Purpose |
+|---|---|---|---|
+| `.agent/ACTIVE.md` | replaced | whoever starts a phase | pointer to the current spec + phase + next task |
+| `.agent/HANDOFF.md` | ephemeral, **deleted when done** | whoever stops mid-work | state a different tool needs to resume |
+| `.agent/DECISIONS.md` | append-only, permanent | whoever makes a call | why things are the way they are |
+| `.agent/DONE.md` | append-only, permanent | whoever finishes | execution log of completed work |
+
+ACTIVE is *where we are*. HANDOFF is *how to continue*. DECISIONS is *why*. DONE is *what happened*. Confusing the four is the usual failure: a handoff that grows a decision log becomes 200 lines and stops being read.
+
+Full protocol — who writes what, when, and the resume sequence — in [references/agent-protocol.md](references/agent-protocol.md).
+
+## Resuming from a handoff
+
+Trust nothing until verified. In order:
+
+1. Check the branch matches. If not, stop and report — the handoff may describe other work entirely.
+2. Check the named files exist and are dirty/clean as claimed.
+3. Run the declared verification yourself. If the build-state line was wrong, that is the first thing to report and the handoff is now suspect throughout.
+4. Read the linked spec/plan for context the handoff deliberately omitted.
+5. Do the **Next** action. Then rewrite the handoff or delete it — never leave the old one in place after acting on it.
+
+If the handoff contradicts the repo, the repo wins. Say so out loud rather than reconciling silently.
+
+## Proactive Triggers
+
+- **The user says they are switching tools, machines, or stopping** → offer a handoff before they ask.
+- **`.agent/HANDOFF.md` exists and its branch or files do not match reality** → flag it as stale immediately; do not act on it.
+- **Work described in the handoff is complete** → propose deleting the file, not updating it.
+- **The handoff is drifting past 30 lines** → say which content is being moved out and where.
+- **A "decision" is being written into the handoff** → redirect it to `.agent/DECISIONS.md` or an ADR; handoffs are ephemeral and the reasoning would be lost on delete.
+- **Uncommitted work exists with no handoff and the session is ending** → flag the risk; uncommitted state is invisible to every other tool.
+
+## Output Artifacts
+
+| When you ask for... | You get... |
+|---|---|
+| "Write a handoff" | `.agent/HANDOFF.md` ≤30 lines: goal, status, next, build state, uncommitted |
+| "Where were we?" | Verified resume report — handoff claims checked against the repo, drift called out |
+| "We're done" | Proposal to delete `HANDOFF.md`, clear `ACTIVE.md`, append `DONE.md`, promote any decision |
+| "Set up the .agent files" | The four-file scaffold with the write-ownership rules |
+| "Is this handoff still good?" | Staleness verdict with the specific claims that no longer hold |
+
+## Communication
+
+Bottom line first: what the next tool should do, in one line. Tag every claim: 🟢 verified just now, 🟡 believed but unverified, 🔴 assumed. Any 🔴 in the build-state line means write `not run` in the file instead.
+
+## Related Skills
+
+- **spec-driven**: Use for the requirements themselves; the handoff links to `specs/NNN-slug/`, never restates it. NOT a substitute for a spec.
+- **adr-write**: Use for decisions that must survive the handoff's deletion. NOT for "we tried X and it didn't work today".
+- **onboard**: Use when the next tool needs a repo *map*, not task state. NOT for mid-task continuity.
+- **architecture-guard**: Use to record an unresolved boundary question so the next tool does not re-litigate it — one Traps line plus a link.
+- **test-first**: Use when the handoff's next action is a failing test; naming the test is the clearest possible "next".
+- **security-review**: Use when a handoff must flag an unreviewed diff touching auth, input, or dependencies.
+- **perf-budget**: Use when work is paused with a budget knowingly regressed — that belongs in Status, explicitly.
+- Commands: `/handoff` writes the file, `/verify` produces a trustworthy build-state line, `/spec` and `/plan` hold the context the handoff links to, `/adr` promotes a decision out of it.

package/registry/skills/handoff/references/agent-protocol.md

@@ -0,0 +1,128 @@
+# The `.agent/` protocol
+
+Four plain markdown files at known paths. No vendor session state, no database, no tool lock-in. One tool can start work, a second can continue it, and a third can finish it — because everything they need is on disk and in the repo's history.
+
+```
+.agent/
+├── ACTIVE.md      what is in flight right now          (replaced)
+├── HANDOFF.md     how a different tool resumes         (ephemeral — deleted when done)
+├── DECISIONS.md   why things are the way they are      (append-only)
+└── DONE.md        what actually happened               (append-only)
+```
+
+---
+
+## Write ownership
+
+| File | Who writes | When | Write mode |
+|---|---|---|---|
+| `ACTIVE.md` | whoever enters a phase | phase start, task completion | **replace** — one current state, never a history |
+| `HANDOFF.md` | whoever stops mid-work | stopping, tool switch, session end | **replace**, then **delete** on completion |
+| `DECISIONS.md` | whoever makes a call | at the moment of the call | **append** — never edit an entry |
+| `DONE.md` | whoever finishes a unit | task or spec completion | **append** — never edit an entry |
+
+The two append-only files are the durable record. The two replaced files are working state. Never append to working state and never edit the record.
+
+---
+
+## ACTIVE.md
+
+A pointer, not a copy. Under ten lines.
+
+```markdown
+# Active
+
+Spec: `specs/042-payment-retry/` — phase: implement
+Next task: T4 — move retry cap to config (`src/payments/retry.ts`, config module)
+Blocked by: nothing
+Updated: 2026-07-18
+```
+
+- Replaced on every phase change and after each task completes.
+- Cleared (emptied or deleted) when the spec ships.
+- If `ACTIVE.md` names a spec whose tasks are all checked, it is stale — reconcile before starting anything new.
+- Two specs in `ACTIVE.md` at once is a smell: either the work is genuinely parallel and should say so, or one was abandoned.
+
+## HANDOFF.md
+
+See `handoff-template.md`. The distinguishing property: **it is the only one of the four that gets deleted.**
+
+Why deletion matters — a stale handoff is confidently wrong. It names a branch that merged, a next action that landed, a failing test that now passes. The next agent trusts it, acts on it, and wastes more time than if the file had never existed. `ACTIVE.md` being slightly behind is recoverable; `HANDOFF.md` being behind is actively harmful.
+
+Rule: **if the work described is complete, propose deleting the file.** Do not update it to say "done". Done state lives in `DONE.md`.
+
+## DECISIONS.md
+
+Append-only. The working reasoning log — lower ceremony than an ADR, higher durability than a handoff.
+
+```markdown
+## 2026-07-18 — Idempotency key generated per request, not per attempt
+Per-attempt keys defeat the whole mechanism; upstream treats each attempt as new.
+Considered: server-generated keys — rejected, upstream does not return one before commit.
+Scope: `specs/042-payment-retry`. Promote to ADR? no — internal to this client.
+```
+
+- One entry per call worth remembering. Date, decision, reason, what else was considered.
+- Never edit an entry. If the decision was reversed, append a new entry that says so and references the old date.
+- Entries that turn out to constrain future work get **promoted to an ADR** — write the ADR, then append a one-line pointer here. The original entry stays.
+- This is where "we tried X and it deadlocked" goes. That is genuinely valuable and genuinely not ADR material.
+
+## DONE.md
+
+Append-only execution log. What shipped, when, and where to look.
+
+```markdown
+## 2026-07-18 — specs/042-payment-retry shipped
+Retries no longer double-charge on upstream timeout. 7 tasks, 4 files.
+Verification: full suite green via declared commands. Budget: no regression.
+Follow-up: sandbox returns 200-with-error-body; tracked in specs/044-upstream-error-shape.
+```
+
+- Written at spec completion, or at task completion for long-running specs.
+- Includes the verification result — a DONE entry without one is a claim, not a log.
+- Follow-ups discovered but not done go here *and* into a new spec. A follow-up recorded only in `DONE.md` never happens.
+
+---
+
+## The resume sequence
+
+A tool arriving cold reads in this order and stops as soon as it has enough:
+
+1. **`AGENTS.md`** — stack, commands, conventions, boundaries, protected paths, ADR index. Always first. Everything else assumes it.
+2. **`.agent/HANDOFF.md`** — if present, this is the fastest path to productive. Verify its claims before trusting them.
+3. **`.agent/ACTIVE.md`** — if no handoff, this says where the work is.
+4. **`specs/NNN-slug/`** — the spec named by either of the above: `tasks.md` first for position, then `plan.md` for approach, then `spec.md` only if scope is in question.
+5. **`.agent/DECISIONS.md`** — scan the most recent entries when something in the code looks wrong; the answer is often there.
+6. **`docs/adr/`** — only when a boundary or a durable choice is being questioned. The `AGENTS.md` index covers the recent window; the archive is on-demand.
+
+`DONE.md` is not part of the resume path. It is for auditing what happened, not deciding what to do next.
+
+---
+
+## Reconciliation at completion
+
+When a spec ships, all four files change together:
+
+- [ ] `HANDOFF.md` — **deleted**
+- [ ] `ACTIVE.md` — cleared, or repointed at the next spec
+- [ ] `DECISIONS.md` — appended with any call made during the work; ADR-worthy ones promoted
+- [ ] `DONE.md` — appended with outcome and verification result
+- [ ] `specs/NNN-slug/spec.md` — status set to shipped
+- [ ] `AGENTS.md` — updated if a convention, boundary, command, or ADR-index entry changed
+
+Skipping the first line is the single most common failure in this protocol.
+
+---
+
+## Why plain markdown at fixed paths
+
+Every constraint here follows from one requirement: **no shared session.** The tools involved do not talk to each other, may not run on the same machine, and may not exist yet when the convention is written.
+
+That rules out anything vendor-specific and gives the properties that matter:
+
+- **Readable by any tool** — including ones nobody has adapted for, because it is just text in the repo.
+- **Diffable and reviewable** — state changes show up in review like any other change.
+- **Versioned with the code** — a checkout at any commit carries the state that was true then.
+- **Human-readable** — a person can read and fix it without tooling.
+
+The cost is discipline: nothing enforces these files. They are only worth having if they are kept honest, which is why the rules above are mostly about *deleting* and *not duplicating* rather than about writing more.

package/registry/skills/handoff/references/handoff-template.md

@@ -0,0 +1,116 @@
+# HANDOFF.md template
+
+Copy into `.agent/HANDOFF.md`. **Hard limit: 30 lines.** Written for a stranger with a terminal, this repo, and no chat history.
+
+---
+
+```markdown
+# Handoff — <YYYY-MM-DD HH:MM>
+
+## Goal
+<One line: the outcome. Not the task list.>
+Spec: `specs/NNN-slug/` (plan approved / tasks 4 of 9 done)
+
+## Status
+- Done: <what is finished and verified>
+- In progress: <what is half-written, and how far>
+- Not started: <what remains, one line>
+
+## Next
+1. <The single concrete first action — a file and a change, or a test to make pass>
+2. <Then this>
+
+## Build state
+<compiles: yes/no> · <verification: pass / fail / not run — via the declared `commands.*`>
+<If failing: the one error, one line.>
+
+## Uncommitted
+Branch: `<branch>`
+Dirty: `<path>`, `<path>`
+<Anything not on disk in a committed state, or "nothing">
+
+## Traps
+- <Non-obvious thing that already cost time. Omit this section if there are none.>
+```
+
+---
+
+## Worked example
+
+```markdown
+# Handoff — 2026-07-18 16:40
+
+## Goal
+Payment retries must not double-charge on upstream timeout.
+Spec: `specs/042-payment-retry/` (tasks 3 of 7 done)
+
+## Next
+1. Make `PaymentClientTest.rejects_duplicate_idempotency_key` pass — it fails today,
+   the key is generated per-attempt instead of per-request.
+2. Then T4: move the retry cap to config with a typed default; no literal at the call site.
+
+## Status
+- Done: idempotency key threaded through the request path (T1-T3), tests green.
+- In progress: retry wrapper exists but generates a fresh key per attempt — that is the bug.
+- Not started: T4 config plumbing, T5 AGENTS.md update.
+
+## Build state
+compiles: yes · verification: 1 failing test (the intended red from T4) — via declared test command
+
+## Uncommitted
+Branch: `spec/042-payment-retry`
+Dirty: `src/payments/retry.ts`, `test/payments/retry.test.ts`
+Nothing stashed.
+
+## Traps
+- The upstream sandbox returns 200 with an error body on timeout; do not trust status alone.
+```
+
+That is 24 lines and a cold reader knows exactly what to type first.
+
+---
+
+## Section rules
+
+**Goal** — the outcome, not the activity. "Payment retries must not double-charge" not "working on retry logic". Always link the spec dir; that is where scope lives.
+
+**Status** — three buckets, no narrative. "Done" means verified, not written. If something is done-but-unverified, it is In progress.
+
+**Next** — the highest-value line in the file. Must be executable without a decision: a named test to make pass, a named file and change, or a named command to run. "Continue the implementation" is a failed Next.
+
+**Build state** — must be true. If you did not run verification, write `not run`. Never infer green from "the last thing I did looked fine". Reference the declared `commands.*` from `AGENTS.md` rather than pasting a literal command — the next tool reads it there.
+
+**Uncommitted** — the only state invisible to a fresh clone. Branch, dirty paths, stashes, and any generated artifact not tracked. If the tree is clean, write `nothing` — that itself is useful.
+
+**Traps** — one line each, only genuinely non-obvious things that already burned time. Not general advice. Not repo conventions (those live in `AGENTS.md`). Cap at three; past that it belongs in the spec or an ADR.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Instead |
+|---|---|---|
+| "As discussed earlier..." | The reader has no earlier | State the fact |
+| Pasting the test command literally | Drifts from `AGENTS.md` | Say "the declared test command" |
+| Restating conventions from AGENTS.md | Duplication guarantees drift | Delete it |
+| A "Decisions" section | Deleted with the file; the reasoning is lost | `.agent/DECISIONS.md` or an ADR |
+| 80 lines of context | Nobody reads it, so nobody updates it | Link the spec |
+| "Tests should pass" | Unverifiable hedge | `pass`, `fail`, or `not run` |
+| Leaving it after finishing the work | Stale handoff sends the next agent wrong | Delete the file |
+| Appending to an existing handoff | Two truths, one file | Replace it wholesale |
+| Session ids, tool names, model names | Meaningless to the next tool | Omit |
+| Absolute local paths, tokens, keys | Broken or dangerous elsewhere | Repo-relative, never secrets |
+
+---
+
+## Staleness check
+
+Before trusting any handoff, verify in this order. Any mismatch makes the whole file suspect, not just that line.
+
+1. Branch in the file == current branch?
+2. Dirty files listed == files actually dirty?
+3. Build state claim == what verification reports right now?
+4. The spec linked exists and its task progress matches?
+5. The Next action still makes sense given the code on disk?
+
+Report drift explicitly before continuing. When the file and the repo disagree, the repo wins.

package/registry/skills/handoff/skill.yaml

@@ -0,0 +1,7 @@
+id: handoff
+kind: skill
+name: Cross-Tool Handoff
+description: Write .agent/HANDOFF.md so a different AI tool can resume — short, tool-neutral, and deleted the moment it goes stale.
+tags: [workflow, continuity, agent-protocol, handoff]
+targets: [claude-code, cursor, github-copilot, windsurf, cline, codex, gemini-cli, agents-md]
+requiresCapability: [instructions]

package/registry/skills/onboard/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: onboard
+description: "Map an unfamiliar repo for a fresh agent — entry points, module boundaries, where tests live, build/test/lint commands, the five files to read first, and known traps. Use when the user says onboard, orient me, map this repo, how is this codebase organized, where do I start, I'm new here. NOT for mid-task continuity — that is handoff."
+metadata:
+  version: 1.0.0
+  category: onboarding
+  updated: 2026-07-18
+---
+
+# Repo Onboarding Map
+
+You are an expert at walking into an unfamiliar codebase and producing the map you wish you'd had. Your goal is a written map that gets the *next* agent productive in one read — and a proposal to fold the durable parts into `AGENTS.md` rather than starting a parallel doc.
+
+## Before Starting
+
+Check what already exists before exploring anything:
+
+1. **`AGENTS.md`** — if it exists and is accurate, most of this skill is already done. Your job becomes *verifying* and *filling gaps*, not rediscovering.
+2. `.agent/DECISIONS.md`, `docs/adr/` — decisions already recorded. Do not re-derive reasoning that is written down.
+3. `specs/` — in-flight and shipped work; the recent ones show how the team actually works.
+4. README, contributing guide, and any docs directory.
+
+If `AGENTS.md` is accurate and complete, say so and stop. Producing a second map that duplicates it guarantees drift, and drifted instructions are worse than none.
+
+## How This Skill Works
+
+**Mode 1 — Cold map.** No `AGENTS.md`. Full discovery, produce the map, propose the `AGENTS.md` content.
+
+**Mode 2 — Verify and fill.** `AGENTS.md` exists. Check each claim against the repo, report what is stale or missing, propose targeted edits. This is the common case and it is fast.
+
+**Mode 3 — Scoped map.** The agent only needs one area ("how does auth work here"). Map that subsystem and its edges, not the whole repo.
+
+## Commands come from the repo, never from you
+
+Build, test, lint, typecheck, and dev commands are read from `AGENTS.md` `commands.*`. If that is absent, derive them from the project manifest and script definitions, then **propose them as `commands.*` entries** rather than baking them into your output.
+
+Never write a literal command into the map as if it were fact when you have not confirmed it runs. A wrong command is the fastest way to burn a new agent's first ten minutes. Confirmed → 🟢. Read from a manifest but not run → 🟡. Guessed from the stack → 🔴, and say so.
+
+## Discovery order
+
+Work outside-in. Full checklist with the concrete signals for each step in [references/discovery-checklist.md](references/discovery-checklist.md).
+
+1. **Shape** — top-level directories, monorepo or single package, workspace definitions.
+2. **Entry points** — the process starts, the HTTP/CLI/job surfaces, the composition roots. Find where execution *begins*, not where most code lives.
+3. **Module boundaries** — the intended architecture style, and whether the code honors it. Cross-check against `boundaries[]` if declared.
+4. **Tests** — where they live, how they are named, what layers they cover, and how they are run. A repo's test layout tells you more about its real conventions than its README does.
+5. **Commands** — from `AGENTS.md` first, manifest second.
+6. **Config and secrets** — where settings resolve, where the typed defaults live, what env vars are required to start.
+7. **Traps** — the things that cost the last person an hour.
+
+## The five files to read first
+
+The heart of the deliverable. Pick exactly five — a ranked list, each with one line on *why*. Discipline is the point: fifteen "important" files is not a map.
+
+Choose to cover these roles, one file each where possible:
+
+| Role | What it teaches | Typical pick |
+|---|---|---|
+| Entry point | how execution starts and what gets wired | the main/server/CLI bootstrap |
+| Composition root | how dependencies are assembled | container/DI/registration module |
+| Core domain unit | the vocabulary the codebase thinks in | the most-imported domain type |
+| Representative test | how the team actually verifies behavior | a well-written test for a core flow |
+| Config surface | how settings and defaults resolve | the single config module |
+
+Skip a role if the repo genuinely lacks it — and *say* it is missing. "There is no single composition root" is a finding, not a gap in your map.
+
+## Traps
+
+The section experienced people value most. A trap is something that will cost time and that nothing in the repo warns about:
+
+- A required env var with no default and an unhelpful failure.
+- A generated directory that must exist before the build works.
+- A test suite that passes only after a one-time setup step.
+- A directory whose name lies about its contents.
+- Two similarly named modules where the obvious one is deprecated.
+- An ordering constraint (migrations, codegen) that is not enforced.
+
+Only include traps you have **evidence** for — a comment, a script, a CI step, a failing command you actually saw. Speculative traps are worse than none.
+
+## Output: a written map, then a proposal
+
+Produce the map using [references/repo-map-template.md](references/repo-map-template.md).
+
+Then propose folding the durable parts into `AGENTS.md` — `overview`, `commands.*`, `conventions[]`, `boundaries[]`, `protectedPaths[]`. **Do not create a parallel onboarding document.** `AGENTS.md` is the source of truth read by every tool; a second doc drifts, and the newer agent believes the wrong one. Present the proposed edits and stop for approval.
+
+What stays out of `AGENTS.md`: the narrative map itself, the discovery evidence, and anything true only today. Those are conversation output.
+
+## Proactive Triggers
+
+- **No `AGENTS.md` in a repo with real structure** → propose one; it is the highest-leverage file in the repo for agent work.
+- **`AGENTS.md` claims a command that fails, or a path that does not exist** → flag as stale before anything else; a wrong source of truth is worse than none.
+- **Directory structure implies an architecture with no `boundaries[]` declared** → propose the boundary lines and route to **architecture-guard**.
+- **Tests exist but no test command is discoverable** → flag it; this blocks every verification loop that follows.
+- **Two directories serve the same role** (`utils/` and `helpers/`, `lib/` and `common/`) → flag the ambiguity; new code will land in the wrong one.
+- **A load-bearing decision is visible in the code but recorded nowhere** → route to **adr-write** for a backfill.
+
+## Output Artifacts
+
+| When you ask for... | You get... |
+|---|---|
+| "Map this repo" | Written map: shape, entry points, boundaries, tests, commands, five-files list, traps — each claim confidence-tagged |
+| "Where do I start?" | Ranked five files with one line each on why, in reading order |
+| "Is AGENTS.md accurate?" | Claim-by-claim verification with stale items and proposed corrections |
+| "How does <subsystem> work?" | Scoped map of that area, its entry points, its edges, and its tests |
+| "Set up AGENTS.md" | Proposed `overview`, `commands.*`, `conventions[]`, `boundaries[]`, `protectedPaths[]` — for approval, not auto-written |
+
+## Communication
+
+Bottom line first: the one-sentence description of what this repo is. Tag every claim: 🟢 verified by reading or running, 🟡 inferred from structure, 🔴 assumed from convention. Say "I could not determine X" rather than filling a gap with a plausible guess — a confident wrong map costs more than an honest incomplete one.
+
+## Related Skills
+
+- **handoff**: Use for mid-task state a specific agent needs to resume. NOT for repo structure.
+- **architecture-guard**: Use once boundaries are declared, to enforce them. This skill *discovers* the shape; that one *guards* it.
+- **spec-driven**: Use after onboarding, for the first change. NOT before you know where things live.
+- **adr-write**: Use to backfill decisions the map surfaced but nobody recorded. NOT for structure itself.
+- **test-first**: Use once the test layout and command are known. The map tells you where tests go; that skill tells you how to write them.
+- **security-review**: Use when the map surfaces auth, input handling, or dependency surfaces worth reviewing.
+- **perf-budget**: Use when the map surfaces declared budgets or a measurement source in CI.
+- Commands: `/verify` confirms the discovered commands actually run, `/spec` starts the first change, `/handoff` carries the map's conclusions to another tool, `/adr` records what onboarding uncovered.