@lemoncode/lemony 0.1.0

package/catalog/schemas/tier2-events.md

@@ -0,0 +1,286 @@
+# Tier 2 events — schema
+
+> **Authority.** This document defines the on-wire shape of every event the harness
+> writes to `.claude/state/events.jsonl`. The `src/events/` Zod schemas are the
+> executable mirror; if they disagree, **this document wins**, and the Zod
+> schemas are updated to match in the same change. Per-release deltas are
+> recorded in [`tier2-events-history.md`](tier2-events-history.md) (forward-only,
+> dispatch-on-read).
+
+Tier 1 (client-local) writes append-only JSONL from day one so the data is
+forward-compatible with the Tier 2 central backend designed in Fase 1+ (decision
+\#24, #25, #27, #51).
+
+## Storage
+
+- One event per line, UTF-8, in `.claude/state/events.jsonl`. The stream is
+  **local-only and gitignored — never committed** (ADR 0008, retiring decision
+  #18/#21): it sits in the managed `GITIGNORE_BLOCK` beside `current-*.md` /
+  `sessions/`. There is no Tier 2 consumer yet, so committing only dirtied the
+  base; transport to Tier 2 is the sink designed in #137.
+- **Append-only, except confirmed-sent prefix-prune** (#240, ADR 0008 §Amendment).
+  Emitters only ever append. The send engine may **collapse the already-delivered prefix**
+  (`[0:cursor]`) once it exceeds ~5MB — never dropping unsent bytes — which rewrites the
+  file and may **reorder** the unsent tail relative to concurrent appends. Order is not a
+  contract (aggregation groups by version/component, the cursor counts bytes), so this is
+  safe; consumers must not rely on global ordering or on the file never being rewritten.
+- **Atomic append.** The CLI writer (`src/events/append.ts`) calls
+  `fs.appendFile`, which opens with `O_APPEND` and issues a single `write(2)`.
+  Up to `PIPE_BUF` bytes (4096 on macOS/Linux) such a write is POSIX-atomic —
+  every event line in this schema stays well under that — so concurrent
+  writers can interleave whole lines but never tear a single one and never
+  lose an event.
+
+## Envelope
+
+Every event line starts with this envelope. Per-type fields are added at the
+same top level — there is no nested `payload`, so Zod discriminated unions key on
+`type`.
+
+| Field             | Type   | Required | Axis            | Notes                                                                                                                                                                                                          |
+| ----------------- | ------ | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`            | string | yes      | `internal-enum` | One of the 9 event types listed below. Discriminator.                                                                                                                                                          |
+| `ts`              | string | yes      | `metric`        | UTC ISO 8601 with `Z` suffix (e.g. `2026-05-28T14:30:00.000Z`). **No local offsets.**                                                                                                                          |
+| `user`            | string | yes      | `local-only`    | `git config user.email` of the actor (decision #53). Never exported in any tier (D7).                                                                                                                          |
+| `project`         | string | yes      | `identity`      | `task_storage.repo` slug (e.g. `acme/widgets`), from `harness.config.yml`. **Never `OWNER/REPO`** — the CLI refuses to emit while that placeholder is the value (see [Placeholder guard](#placeholder-guard)). |
+| `task_id`         | string | no       | `identity`      | Task issue id (e.g. `42`) when the event has a task context. Absent on session/global events. A per-project correlator — only meaningful alongside `project`, so it shares the `identity` axis.                |
+| `harness_version` | string | yes      | `metric`        | `version` of the **installed** `@lemoncode/lemony` package — _not_ `vendor_version` from config.                                                                                                               |
+
+### Placeholder guard
+
+`lemony install` writes `task_storage.repo: OWNER/REPO` to
+`harness.config.yml` only when it cannot resolve a real slug — typically a
+non-TTY install in a repo with no `origin` remote and no
+`--task-storage-repo=` flag. The placeholder is a sentinel: every emit call
+checks for it and refuses with a friendly error rather than stamping garbage
+onto telemetry. Downstream aggregators therefore never see a `project:
+"OWNER/REPO"` line and don't need to filter for it.
+
+Interactive installs avoid the placeholder entirely — the CLI prompts the user
+to either enter a slug, create a GitHub repo via `gh repo create`, or
+explicitly skip. The skip path falls back to the placeholder with the same
+warning the non-TTY path prints (emits will block until the config is fixed).
+
+### `harness_version` source
+
+The CLI reads its **own** `package.json` `version` field via
+`import.meta.dirname` (relative to the build output). This guarantees forensic
+correctness: if a client's `harness.config.yml` was pinned to `0.1.0-alpha.0`
+but they upgraded the CLI to `0.2.0-alpha.0` without re-running `install`, the
+event records `0.2.0-alpha.0`. Drift between the two is surfaced separately by
+the `init.sh` SessionStart hook as a warning.
+
+### Field axes
+
+Every `(event_type, field)` occurrence carries one of **five axes**. The axis is a
+property of the **occurrence, not the field name** — the same name can differ by
+event (`reason` is an `internal-enum` in `session_closed` but `free-text` in
+`review_rejected` / `l3_bypass`). The sanitizer dispatches on `type`, so per-event
+assignment is natural. The axis drives forward-sanitization when events are
+exported to Tier 2 (`src/telemetry/sanitize.ts`); the executable mirror of this
+table is `src/telemetry/sanitize.constant.ts` (`FIELD_AXIS`), kept in lock-step by
+a doc-parse test.
+
+| Axis            | Export policy                          | Meaning                                                                              |
+| --------------- | -------------------------------------- | ------------------------------------------------------------------------------------ |
+| `local-only`    | **drop always** (every tier)           | Stays in `events.jsonl` + `telemetry show`; never leaves the laptop. PII / identity. |
+| `identity`      | keep `project` tier / drop `anonymous` | A per-project identifier — only meaningful alongside `project`.                      |
+| `free-text`     | keep `project` tier / drop `anonymous` | Unbounded human text; a de-anonymization vector.                                     |
+| `internal-enum` | **keep always**                        | A bounded, low-cardinality value (a fixed enum, or a roster component name).         |
+| `metric`        | **keep always**                        | Pure measurement — timestamps, counts, durations, booleans. Safest to aggregate.     |
+
+Two tiers select which axes survive: **`anonymous`** (the on-by-default floor) keeps
+only `internal-enum` + `metric`; **`project`** (opt-in, for dogfood) additionally
+keeps `identity` + `free-text`. `local-only` is dropped in both. `identity` and
+`free-text` share today's policy but stay distinct axes for future divergence (a
+hashed `user_hash` would be `identity`-with-hashing, not `free-text`). v1 wires only
+the `anonymous` branch (decisions D7/D8/D9, ADR 0020).
+
+`attributed_name` is deliberately an `internal-enum` even though Zod types it as a
+bounded free string: the axis is policy-oriented (keep-always), and the field is the
+moat metric (#1, "which component causes friction") — a roster component name shared
+across all installs, not sensitive free text (D8). The aggregation script flags names
+outside the known roster as the data-quality thermometer (see [Attribution](#attribution)).
+
+---
+
+## Event types (9)
+
+Five are emitted in P5. `bug_post_merge` is deferred to P8 (meta-test). `l3_bypass`
+is deferred to P6 (the `/bypass` command). `followup_captured` is emitted by the
+`/spinoff` command (#112). `step_completed` is emitted by the Orchestrator in
+step-by-step mode (#176). The schema covers all nine so the file is
+forward-compatible — readers dispatch on `type` and ignore unknowns.
+
+### 1. `session_closed` _(P5)_
+
+Emitted by `session-close.sh` on `SessionEnd` or `/pause` (manual). One per
+session.
+
+| Field              | Type    | Required | Axis            | Notes                                                                                                           |
+| ------------------ | ------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
+| `session_start_ts` | string  | yes      | `metric`        | UTC ISO 8601 Z. Read from `current-<user>.md` frontmatter.                                                      |
+| `session_active_h` | number  | yes      | `metric`        | Active hours this session — `(ts − session_start_ts) / 3600s`. ≥ 0, finite.                                     |
+| `reason`           | string  | yes      | `internal-enum` | `clear` \| `resume` \| `logout` \| `prompt_input_exit` \| `bypass_permissions_disabled` \| `other` \| `manual`. |
+| `auto_close`       | boolean | yes      | `metric`        | `true` when fired by `SessionEnd` (no narrative); `false` when fired by `/pause`.                               |
+
+### 2. `spec_created` _(P5)_
+
+Emitted by the `prd-to-spec` skill when the three spec files are written (the
+hand-off to `spec-to-issue`).
+
+| Field          | Type   | Required | Axis        | Notes                                                                                 |
+| -------------- | ------ | -------- | ----------- | ------------------------------------------------------------------------------------- |
+| `task_id`      | string | yes      | `identity`  | Required for this type (overrides the envelope's `task_id` optionality).              |
+| `topic`        | string | yes      | `free-text` | The topic slug from the spec branch (`<slug>` in `harness/<id>-<slug>`). 1-200 chars. |
+| `requirements` | number | yes      | `metric`    | Count of EARS requirements in `requirements.md` (≥ 1, integer).                       |
+
+### 3. `spec_approved` _(P5)_
+
+Emitted by the Orchestrator when it transitions `spec-in-progress → spec-ready`
+(human approval gate cleared).
+
+| Field        | Type   | Required | Axis       | Notes                                                         |
+| ------------ | ------ | -------- | ---------- | ------------------------------------------------------------- |
+| `task_id`    | string | yes      | `identity` | Required for this type.                                       |
+| `iterations` | number | yes      | `metric`   | How many grill-or-refine cycles preceded approval (≥ 1, int). |
+
+### 4. `task_done` _(P5)_
+
+Emitted by the Orchestrator at closeout (after `gh pr view` confirms `MERGED`,
+before `git rm` of the task state).
+
+| Field               | Type   | Required | Axis            | Notes                                                                                                                                                |
+| ------------------- | ------ | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `task_id`           | string | yes      | `identity`      | Required for this type.                                                                                                                              |
+| `level`             | string | yes      | `internal-enum` | `L1` \| `L2` \| `L3` — the task-fit dial value used.                                                                                                 |
+| `cycle_time_h`      | number | yes      | `metric`        | Wall-clock hours from issue creation to merge. ≥ 0, finite.                                                                                          |
+| `review_rejections` | number | yes      | `metric`        | Count of `review_rejected` events for this `task_id` (≥ 0, int).                                                                                     |
+| `mode`              | string | no       | `internal-enum` | `all_at_once` \| `step_by_step` — the mode chosen at the L1 approval gate (#176). **Absent on L2** (the question only exists where `tasks.md` does). |
+| `steps`             | number | no       | `metric`        | Count of `step_completed` events for this task (≥ 1, int). Only meaningful when `mode` is `step_by_step`; < total tasks after a mid-task downgrade.  |
+
+### 5. `review_rejected` _(P5)_
+
+Emitted by the Reviewer when the verdict is REJECT (decision #25, transient
+state — no dedicated label).
+
+| Field             | Type   | Required | Axis            | Notes                                                                                                                                                                                                                                                       |
+| ----------------- | ------ | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `task_id`         | string | yes      | `identity`      | Required for this type.                                                                                                                                                                                                                                     |
+| `reason`          | string | yes      | `free-text`     | Short human-readable reason (one line; never the full review comment). 1-500 chars.                                                                                                                                                                         |
+| `iteration`       | number | yes      | `metric`        | 1-based: the Nth rejection of this task (≥ 1, int).                                                                                                                                                                                                         |
+| `step`            | number | no       | `metric`        | The step (1-based `tasks.md` task number) whose per-step review rejected (#176). **Absent** on full-pass and all-at-once rejections.                                                                                                                        |
+| `attributed_kind` | string | no       | `internal-enum` | `agent` \| `skill` \| `playbook` — the kind of component the friction is attributed to (#217). **Omitted when the emitter can't attribute.**                                                                                                                |
+| `attributed_name` | string | no       | `internal-enum` | The component's name (free string, 1-200 chars), e.g. `implementer`. Independently optional in the schema; emitters pair it with `attributed_kind` and omit both when they can't attribute (#217). Free-string by design — see [Attribution](#attribution). |
+
+### 6. `bug_post_merge` _(P8 — schema only)_
+
+Reserved for meta-test (`P8`). Schema is fixed now so readers can dispatch
+forward-compatibly.
+
+| Field          | Type   | Required | Axis            | Notes                                            |
+| -------------- | ------ | -------- | --------------- | ------------------------------------------------ |
+| `task_id`      | string | yes      | `identity`      | The task whose merged change introduced the bug. |
+| `discovered_h` | number | yes      | `metric`        | Hours from merge to bug discovery (≥ 0, finite). |
+| `severity`     | string | yes      | `internal-enum` | `low` \| `medium` \| `high` \| `critical`.       |
+
+### 7. `l3_bypass` _(P6 — schema only)_
+
+Reserved for the `/bypass` command (`P6`). A global event — `task_id` is inherited
+from the envelope (optional) and usually absent.
+
+| Field    | Type   | Required | Axis        | Notes                                                              |
+| -------- | ------ | -------- | ----------- | ------------------------------------------------------------------ |
+| `topic`  | string | yes      | `free-text` | One-line subject (typo, rename, lockfile bump, etc.). 1-200 chars. |
+| `reason` | string | yes      | `free-text` | Why the harness was bypassed. 1-500 chars (≤ 200 recommended).     |
+
+### 8. `followup_captured` _(#112 — `/spinoff`)_
+
+Emitted by the `/spinoff` command when a non-blocking, independent defect found
+mid-task is parked as a `harness:managed` + `harness:status:pending` stub. Feeds the
+"follow-up bugs per parent task" metric. **Not** `bug_post_merge` — that is a
+post-merge / production signal; conflating them would dirty the post-merge metric.
+
+| Field            | Type   | Required | Axis            | Notes                                                                                               |
+| ---------------- | ------ | -------- | --------------- | --------------------------------------------------------------------------------------------------- |
+| `task_id`        | string | yes      | `identity`      | The captured stub's own issue id (overrides the envelope's optionality).                            |
+| `parent_task_id` | string | no       | `identity`      | The originating task id. **Absent** when `/spinoff` runs outside any active task (a deferred stub). |
+| `severity`       | string | no       | `internal-enum` | `low` \| `medium` \| `high` \| `critical`. Best-effort — set only when cheaply inferred.            |
+
+### 9. `step_completed` _(#176 — step-by-step mode)_
+
+Emitted by the Orchestrator each time a human checkpoint **resolves** in
+step-by-step mode (L1 opt-in, chosen at the approval gate). One event per
+checkpoint, not per step: a step the human sends back ("changes") emits again
+when it re-checkpoints, with the same `step`. This is the signal that justifies
+(or condemns) the mode — the rate of checkpoints that catch things, and where
+humans bail out (`ok_downgrade`).
+
+| Field               | Type   | Required | Axis            | Notes                                                                                                                                                                                                                                   |
+| ------------------- | ------ | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `task_id`           | string | yes      | `identity`      | Required for this type.                                                                                                                                                                                                                 |
+| `step`              | number | yes      | `metric`        | 1-based `tasks.md` task number the checkpoint belongs to (≥ 1, int).                                                                                                                                                                    |
+| `review_iterations` | number | yes      | `metric`        | Reviewer invocations that preceded this checkpoint (≥ 1, int — every step is reviewed before the human; resets after a "changes").                                                                                                      |
+| `checkpoint_result` | string | yes      | `internal-enum` | `ok` \| `changes` \| `ok_downgrade` (OK and switch the remaining tasks to all-at-once).                                                                                                                                                 |
+| `attributed_kind`   | string | no       | `internal-enum` | `agent` \| `skill` \| `playbook` — the kind of component the friction is attributed to (#217). **Omitted when the emitter can't attribute.**                                                                                            |
+| `attributed_name`   | string | no       | `internal-enum` | The component's name (free string, 1-200 chars). Independently optional in the schema; emitters pair it with `attributed_kind` and omit both when they can't attribute (#217). Free-string by design — see [Attribution](#attribution). |
+
+---
+
+## Attribution
+
+The two **friction** events — `review_rejected` and `step_completed` — carry an
+optional `attributed_kind` (`agent` | `skill` | `playbook`) + `attributed_name`
+(free string) pair (#217). They answer "_which_ component did this friction come
+from", feeding the "friction attributed to a specific skill/agent" metric. They are
+set by the emitting prompts (Reviewer, Orchestrator), which list the valid roster and
+are instructed to **omit both when they can't confidently attribute** — a wrong guess
+is worse than a gap.
+
+`task_done` deliberately has **no** attribution field: its "where" is reconstructed
+from its child `review_rejected` events, not collapsed into one fuzzy culprit.
+
+`attributed_name` is a **free string this phase, by design** (measure-then-decide):
+the CLI does not enforce a component registry. It rides the `internal-enum` axis (kept
+in both tiers) because it is the moat metric and a bounded roster name, not sensitive
+free text (D8) — it is the one non-numeric field that survives the `anonymous`
+projection. The aggregation script (#218) reports attribution coverage and flags names
+outside the known roster — that signal is the thermometer. If it shows the data quality
+is poor, the cheap next step is enum validation in `lemony emit`; an MCP-backed registry
+only if that proves insufficient. Historical lines (pre-#217) lack both fields, so
+coverage starts near 0% and ramps.
+
+## Reader contract (forward-only, dispatch-on-read)
+
+A reader of `events.jsonl`:
+
+1. Parses each line as JSON. Malformed lines are logged and skipped — they
+   never abort the stream.
+2. Dispatches on `type`. Unknown types are skipped (forward-compatibility:
+   new event types appear without breaking old readers).
+3. Trusts the per-release delta in `tier2-events-history.md` for field
+   renames / deprecations.
+
+## Writer contract
+
+A writer (the `lemony emit` CLI):
+
+1. Builds the envelope at write time — `ts` (now, UTC `Z`), `user` (from
+   `git config user.email`), `project` (from `harness.config.yml`),
+   `harness_version` (from the installed package).
+2. Merges per-type fields into the same top level (no nested `payload`).
+3. Validates against the Zod schema for `type` (each schema is `.strict()`,
+   so an unknown key — typically a typo'd `--task-iid` flag — **rejects**
+   loud). Never writes a partial line.
+4. Appends the JSON line via `fs.appendFile` (single `O_APPEND` `write(2)`,
+   POSIX-atomic up to `PIPE_BUF`) to `.claude/state/events.jsonl`. Creates the
+   file (and parent dir, scaffolded by `install`) when missing.
+
+## Out of scope (recorded for forward-design)
+
+- Tier 2 central ingestion, export, and aggregation (Fase 1+, decision #24).
+- The `project`-tier export branch: the axis table assigns the `identity` /
+  `free-text` policy, but the sanitizer wires only the `anonymous` branch in v1
+  (D8/D9). The `project` branch lands with the consent/config work (#229).
+- Backward-compatible field renames — `tier2-events-history.md` records them
+  forward-only; readers add the alias when they care.

package/catalog/skills/README.md

@@ -0,0 +1,62 @@
+# skills/ — vendor skill catalog
+
+> **Status: 18 skills (P1–P3 + P4).** P1 migrated `triage-issue`, `tdd`,
+> `senior-review`. P2 migrated `grill-with-docs` and authored `prd-to-spec`,
+> `spec-to-issue`, `task-closeout`. P3 authored the discovery loop (`raise-discovery`,
+> `resolve-discovery`). **P4 slice 1** added the Reviewer set — `verify`,
+> `silent-failure-hunter`, `security-review`, `spec-compliance-check`,
+> `test-gap-report` — rewrote `senior-review` to v2, and rolled out the gating
+> frontmatter (`min-profile`/`phase`/`invoked-by`) across the catalog. **P4 slice 2**
+> added the Architect set — `write-adr`, `update-architecture`, `code-explorer`,
+> `playbook-iterate`. All `origin: vendor`.
+
+Generic, **project-agnostic** skills only (decision #28). Project-specific skills
+(e2e, changeset, docs) live in the **client's** `.claude/skills/`, not here. Each
+skill is a folder `skills/<name>/SKILL.md`.
+
+## Gating frontmatter (decision #31; ADR 0015)
+
+The installer scans this catalog, parses each skill's frontmatter, and lands a skill
+when every **`applies-when`** capability key holds for the repo (install-time,
+deterministic). A skill with no `applies-when` is always installed — there is no
+profile tier (the coarse `min-profile` filter #39 was retired in ADR 0015, when
+profiles collapsed to a single capability-gated skill set). Each sub-agent's
+`{{SKILLS}}` marker is filled with the skills it `invoked-by`, grouped by **`phase`**.
+A skill with no `phase` is universal (e.g. `raise-discovery`).
+
+| Field               | Meaning                                                                | Default          |
+| ------------------- | ---------------------------------------------------------------------- | ---------------- |
+| `phase`             | `pre-implementation` / `during-implementation` / `post-implementation` | none ⇒ universal |
+| `invoked-by`        | roles whose marker lists it                                            | `[]`             |
+| `applies-when`      | capability keys (AND) the repo must satisfy at install                 | `[]` (always)    |
+| `trigger-condition` | per-change runtime guard rendered with the skill                       | —                |
+
+## Planned MVP catalog (Fase 0)
+
+| Skill                   | Role                               | Status             |
+| ----------------------- | ---------------------------------- | ------------------ |
+| `grill-with-docs`       | Orchestrator (shared w/ Architect) | migrated ✓ (P2)    |
+| `triage-issue`          | Orchestrator                       | migrated ✓ (P1)    |
+| `task-closeout`         | Orchestrator                       | authored ✓ (P2)    |
+| `prd-to-spec`           | Spec Author                        | authored ✓ (P2)    |
+| `spec-to-issue`         | Spec Author                        | authored ✓ (P2)    |
+| `tdd`                   | Implementer                        | migrated ✓ (P1)    |
+| `senior-review`         | Reviewer                           | v2 ✓ (P4 s1)       |
+| `verify`                | Implementer, Reviewer              | authored ✓ (P4 s1) |
+| `security-review`       | Reviewer                           | authored ✓ (P4 s1) |
+| `silent-failure-hunter` | Reviewer                           | authored ✓ (P4 s1) |
+| `spec-compliance-check` | Reviewer                           | authored ✓ (P4 s1) |
+| `test-gap-report`       | Reviewer                           | authored ✓ (P4 s1) |
+| `write-adr`             | Architect                          | authored ✓ (P4 s2) |
+| `update-architecture`   | Architect                          | authored ✓ (P4 s2) |
+| `code-explorer`         | Architect                          | authored ✓ (P4 s2) |
+| `playbook-iterate`      | Architect                          | authored ✓ (P4 s2) |
+| `raise-discovery`       | all sub-agents (universal)         | authored ✓ (P3)    |
+| `resolve-discovery`     | Orchestrator                       | authored ✓ (P3)    |
+
+**Parked from the vendor MVP:** `feature-flow`, `prd-to-plan`, `prd-to-issues`,
+`pr-review`, `ui-design`, `project-setup`, `write-a-skill`, `grill-me` (deprecated).
+
+**ECC as marketplace (decision #42):** [`affaan-m/ECC`](https://github.com/affaan-m/ECC)
+is MIT; when a client needs a specific skill ECC already has, copy-and-adapt it into
+the client's `.claude/skills/` rather than bloating this catalog.

package/catalog/skills/bootstrap-architecture/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: bootstrap-architecture
+description: Author the first docs/architecture.md — a holistic map of the system's current shape, fitted to this project. A one-time bootstrap the Architect runs when a client opts into the architecture capability; thereafter update-architecture maintains it incrementally. The harness only does this when the human asks (decision #8).
+origin: vendor
+vendor_version: '{{vendor_version}}'
+invoked-by: [architect]
+---
+
+# Bootstrap Architecture
+
+## Core Principle
+
+`docs/architecture.md` is the **living high-level map** of the system — the shape a new
+engineer reads first (contexts, boundaries/ownership, integration seams, external
+dependencies, data flow). This skill authors it **for the first time**: a holistic map of
+the system **as it is today**, read from the actual code.
+
+This is the one-time **bootstrap**, the opposite of the incremental `update-architecture`:
+that skill makes the smallest surgical edit after a single change; this one reads the whole
+repo and writes the initial coherent map. After this lands, `update-architecture` (gated on
+the file now existing) keeps it true incrementally.
+
+It is **not gated** — it is available before any `docs/architecture.md` exists, because its
+job is to create the first one. But the harness runs it **only when the human opts in**
+(via `/add-capability`, or an explicit request), never on its own: the vendor gives the
+framework, not the architecture (decision #8). The map is authored **from the client's real
+code**, so the harness reflects the project's shape — it never imposes one.
+
+## What to produce
+
+A map **fitted to this project**, not a template. The sections **emerge from the contexts
+you actually find** — do **not** treat the list below as a fixed heading set to emit. These
+are **lenses to look through**, not mandatory sections: cover the ones this system actually
+has, drop the ones it doesn't, name them in the project's own terms. Aim for the shape, not
+the detail:
+
+- the **bounded contexts / modules** the system actually divides into, and what each owns;
+- the **boundaries & ownership rules** between them ("X owns Y; others reference by id");
+- the **integration seams** (sync HTTP, domain events, queues, a provider abstraction);
+- the **external dependencies** that carry lock-in (a database, a broker, an auth provider);
+- the **data flow** a reader would otherwise get wrong.
+
+Keep it a **map, not a code listing**. Resist implementation detail that belongs in code,
+`CLAUDE.md`, or a playbook. If the project records decisions as ADRs, link the _why_
+(`see ADR-NNNN`) rather than restating it — the map holds the _shape_, the ADR the _decision_.
+
+## Process
+
+1. **Orient over the whole repo.** Read the structure to derive the real shape — the
+   top-level layout, the module/folder boundaries, the entry points, the external deps in
+   the manifest, the seams between parts. Where a `code-explorer` map is available, start
+   from it. This is a read of the **current** code, not a guess.
+2. **Draft the map at the right altitude** — sections matching the contexts you found,
+   each a few lines: what it is, what it owns, how it connects. Prefer a small, true map
+   over an exhaustive one; the reader wants the shape.
+3. **Write `docs/architecture.md`.** Create the file (and `docs/` if absent).
+4. **Hand back for activation.** You do not run `repair` yourself — the map alone does not
+   install the maintainer skill. Report to your invoker (the Orchestrator) that
+   `docs/architecture.md` now exists, so it runs `repair`; its re-scan detects the new file
+   and installs `update-architecture` to keep the map current. See the `/add-capability`
+   command.
+
+## Report
+
+Return to your invoker: the sections written, a one-line summary of the shape the map now
+captures, and the explicit note that `update-architecture` should be activated via `repair`.
+If the project is too small or too uniform to have a meaningful architecture (a single-purpose
+script, a flat library), **say so and write nothing** — an architecture map for a project
+without architecture is noise, and #8 means the client need not have one.
+
+## Uncontemplated Scenarios
+
+When a case doesn't clearly fit:
+
+1. Apply the closest matching approach with reasoning.
+2. **Flag it**: "This isn't covered by the bootstrap-architecture skill. I did [approach]
+   because [reason]. Want to refine the skill?"
+3. Offer to add a rule for the case.

package/catalog/skills/code-explorer/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: code-explorer
+description: Systematically map a large or unfamiliar codebase and return a structured orientation — entry points, modules, data flow, conventions, and the seams where bugs live. Read-only; it explores and reports, it never edits. Use when the Architect (or another agent, via the Orchestrator) needs to get oriented before a decision, a spec, or a deep change in a codebase no one has in context.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+invoked-by: [architect]
+trigger-condition: orienting in a large or unfamiliar codebase
+---
+
+# Code Explorer
+
+## Core Principle
+
+Before you can decide, spec, or change anything safely in an unfamiliar codebase, you
+need a map. This skill produces that map: a structured, evidence-based orientation a
+fresh sub-agent can build on. It is **read-only** — it reads, traces, and reports; it
+never edits. Its value is the same fresh-context anti-bias as any sub-agent: it sees the
+code as it is, not as someone hoped it was.
+
+## Process
+
+Work outside-in. Cite real paths and symbols — an orientation that can't be checked is
+worthless.
+
+**Start from the map if there is one.** If the repo keeps `docs/architecture.md`, read it
+first — it is the maintained high-level map of the system's shape (contexts, boundaries,
+seams). Use it as your baseline: don't re-derive what it already states; deep-dive only
+where it is thin or stale for the question at hand. If it is **absent**, map from scratch
+as below — and never suggest creating it (it is the client's choice, decision #8). When the
+map contradicts the code in an area you read (the map says X, the code does Y), call out the
+staleness in your report's **Notes** so the Architect (your invoker, who owns the map) can
+reconcile it via `update-architecture` — don't silently trust either side.
+
+1. **Frame the question.** What is the exploration _for_? "Where does auth happen?",
+   "How does a request flow end to end?", "Is there already a solution to X?" Scope the
+   sweep to the question — don't map the whole repo when one slice is asked for.
+2. **Find the entry points.** The manifest (`package.json` scripts, `bin`, `main`), the
+   server bootstrap, the route table, the CLI dispatcher, the test setup. These anchor
+   everything else.
+3. **Map the modules and their boundaries.** The top-level structure, what each
+   significant module owns, and how they depend on each other. Note the **seams** —
+   where modules talk (HTTP, events, shared state, serialization). Most bugs live here.
+4. **Trace the critical path(s).** Follow the one or two flows the question cares about
+   from entry to effect (request → handler → service → store → response). Name the files
+   and functions on the path.
+5. **Read the conventions.** Naming, file layout, error handling, the test strategy,
+   and any `CLAUDE.md` / `CONTEXT.md` / playbooks the repo already documents. An agent
+   that follows existing conventions is far less likely to raise a false discovery.
+
+## Report
+
+A concise orientation, not a file dump — the conclusion, with paths to verify it:
+
+```
+## Code map — <scope of the exploration>
+
+**Entry points**: <files/commands>
+**Key modules**: <module → what it owns> (the few that matter)
+**Critical path**: <entry → … → effect, with file:symbol references>
+**Seams**: <module boundaries / integration points; where to test first>
+**Conventions**: <naming, layout, error handling, test strategy, docs that exist>
+**Notes for the task**: <existing solutions, risks, open questions>
+```
+
+If the exploration surfaces a genuine T1–T6 case (e.g. the change already exists —
+T4 EXISTING_SOLUTION, or the codebase makes the plan infeasible — T5), that's a
+**discovery**: run `raise-discovery` rather than burying it in the report.
+
+## Uncontemplated Scenarios
+
+When a case doesn't clearly fit:
+
+1. Apply the closest matching approach with reasoning.
+2. **Flag it**: "This isn't covered by the code-explorer skill. I did [approach] because
+   [reason]. Want to refine the skill?"
+3. Offer to add a rule for the case.

package/catalog/skills/grill-with-docs/ADR-FORMAT.md

@@ -0,0 +1,49 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# NNNN — {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+The `NNNN` number prefixes the title (matching the filename `NNNN-slug.md`).
+
+That's it. An ADR can be a single paragraph. The value is in recording _that_ a decision was made and _why_ — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing".
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.

package/catalog/skills/grill-with-docs/CONTEXT-FORMAT.md

@@ -0,0 +1,77 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A concise description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+
+## Relationships
+
+- An **Order** produces one or more **Invoices**
+- An **Invoice** belongs to exactly one **Customer**
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."
+
+## Flagged ambiguities
+
+- "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts.
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
+- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.