@lemoncode/lemony 0.1.0

package/catalog/skills/task-closeout/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: task-closeout
+description: Close out a finished task — record it in history.md, archive the task spec + discoveries, activate the Architect for durable capture (ADRs, the architecture map, playbooks), and finalize via a dedicated closeout PR. Use when the Orchestrator finalizes an approved+merged task, mentions "closeout", "close the task", or "wrap up the issue".
+origin: vendor
+vendor_version: '{{vendor_version}}'
+invoked-by: [orchestrator]
+---
+
+# Task Closeout
+
+## Core Principle
+
+Closeout is **archive-on-done through a dedicated PR** (ADR 0009). The durable memory of
+a finished task — its spec and its resolved discoveries — is **archived live**, not
+deleted, so a future agent reads the decisions instead of doing git archaeology. The
+genuinely architectural decisions rise further, to ADRs. And the closeout record reaches
+the base branch **only through a PR**, never a direct push — the same branch isolation
+every other change obeys.
+
+Three moves, in this order:
+
+1. **Activate the Architect** — closeout is its reliable end-of-task checkpoint (#138).
+   In cold blood, no resume pressure, it drives durable capture: `write-adr` (HITL offer
+   per resolved discovery), `update-architecture` (automatic, when the map exists), and
+   `playbook-iterate` (HITL offer, once per task). The canon outlives any task folder.
+2. **Archive, don't delete** — `git mv` the spec + `discoveries.md` into
+   `_archive/<id>/`; drop only `progress.md` (true scratch). The high-value memory stays
+   live and grep-able.
+3. **Land via a PR** — the `history.md` append, the archival move, and any new ADR ride a
+   dedicated `harness/closeout-<id>` PR merged with `--auto`. No direct push to the base.
+
+Run this only when the **Reviewer has approved** and the task PR is merged. The merge is a
+human decision (the merge gate) — closeout never merges the task; it **confirms** the
+merge, then records it.
+
+## Preconditions
+
+- The Reviewer posted an explicit approval (the task passed `in-review`).
+- **The task PR is merged — confirmed against GitHub, not the conversation.**
+  `gh pr view <pr> --json state,mergedAt` must report `"state": "MERGED"`, regardless of
+  how it was merged (GitHub UI, CLI, or the Orchestrator running `gh pr merge` after the
+  human authorized it). If it is not `MERGED`, stop — the task stays at `in-review`
+  until the human merges.
+- The PRD for this task is `Status: completed` — `grill-with-docs` normally sets this
+  when the grill closed; if it's still `in_progress`, flip it now. (This is the
+  latest point the PRD can be marked done.)
+- **No discovery is left open.** If `discoveries.md` exists, every entry must carry a
+  resolved `**Resolution**` block (`Decision` / `Resumed at` filled) and no
+  `harness:discovery:*` label may remain on the issue. An unresolved discovery means a
+  sub-agent is still paused — run `resolve-discovery` before closing out.
+- **The `harness:status:closeout-pending` label exists on the remote.** `install` /
+  `update` / `repair` create it during label sync; an install that predates this label
+  needs one `lemony repair` first, or the park step's label flip will fail.
+
+## Why post-merge (don't archive early)
+
+Archival is **destructive** and must wait until the task PR is merged. Until that merge,
+the task can re-enter iteration — a Reviewer rejection, or human review comments at the
+gate (#111) — and that re-work needs the spec **live** in `tasks/<id>/spec/`. Archiving
+pre-merge would pull the spec out from under an in-flight fix. So every step below runs
+**after** the merge is confirmed.
+
+## Process
+
+Closeout runs **on the default branch, after the merge** — the task PR brought the
+branch (spec + code) onto it. Land there first so the closeout branch forks from the
+merged base: `git checkout <default> && git pull`.
+
+### 1. Activate the Architect for durable capture
+
+Closeout is the Architect's **reliable activation point** (#138): in cold blood, after
+the merge, with no paused sub-agent pulling toward "just unblock me", it drives the three
+durable-capture skills the on-demand triggers otherwise lose. Each one **no-ops cleanly
+when its skill isn't installed**, so this step is safe everywhere.
+
+The three differ in **who decides** — and the asymmetry is deliberate (ADR 0010):
+
+- **`write-adr` — HITL offer, per resolved discovery.** Walk the **resolved** entries in
+  `discoveries.md` and **offer** the ones that settled a real decision (not a trivial
+  clarification) as candidate ADRs, then dispatch the **Architect** (`write-adr`, fresh
+  context) on the ones the human accepts. Offer liberally — closeout does **not** apply
+  the ADR criterion itself; the Architect owns the three tests (hard to reverse /
+  surprising without context / a real trade-off) and **declines** the ones that fail, so
+  a generous offer costs only a "no". If there are no resolved discoveries, or none
+  qualify, skip — never pad the canon with reversible or obvious decisions. An ADR is
+  **net-new canon**: the human curates what enters, so it stays an offer.
+
+- **`update-architecture` — automatic dispatch, no pre-offer.** Only when
+  `docs/architecture.md` exists (the skill installs solely then). Dispatch the
+  **Architect** (`update-architecture`, fresh context) with the task's **merged diff**
+  (`gh pr diff <pr>`) plus the task's `spec/design.md` (still live here — archival is
+  step 4 below). The Architect reads the change, makes
+  the smallest true edit if the system's **shape** moved (referencing any ADR just
+  written — `see ADR-NNNN`), or reports **no-op** when nothing architectural changed.
+  There is **no human prompt here**: the map must _track reality_, not be curated, and the
+  edit is reviewed in the closeout PR diff like any other change. Run this **after**
+  `write-adr` so the map can cite the new ADR numbers.
+
+- **`playbook-iterate` — HITL offer, once per task.** A single reflective offer: did this
+  task surface a **reusable pattern** worth extracting, or a playbook worth iterating,
+  that **no `T6 PLAYBOOK_CONFLICT` already routed** mid-task? (A conflict blocks a
+  sub-agent and is handled in the moment; this catches the _non-blocking_ learning that
+  would otherwise be lost.) On the human's "yes", dispatch the **Architect**
+  (`playbook-iterate`, fresh context). Like an ADR, a playbook change is curated canon, so
+  it stays an offer; decline costs only a "no".
+
+Any artifact written — an ADR, the architecture edit, a playbook — lands in the working
+tree and rides the closeout PR below.
+
+### 2. Branch for the record
+
+```bash
+git checkout -b harness/closeout-<id>
+```
+
+All of closeout's writes go on this branch — nothing touches the base directly.
+
+### 3. Append one line to `history.md`
+
+`.claude/state/history.md` is the append-only, committed changelog — one entry per
+finished task. Add the task with whatever metrics you actually have:
+
+```markdown
+## #<id> — <topic> (<start-date> → <end-date>)
+
+Cycle: <h> | Iter: <review rounds> | Bugs 14d: <n/a until measured>
+```
+
+Record only metrics you can back up. Rich telemetry (tokens, post-merge bugs) is
+populated once the telemetry/event machinery is authored in a later phase; until
+then, leave those as `n/a` rather than inventing numbers.
+
+### 4. Archive the spec + discoveries; drop the scratch
+
+Move the durable memory into the archive and remove only the ephemeral scratch. The
+existence guards keep this **idempotent** — a retried closeout (e.g. crash mid-run) that
+already archived skips the move rather than erroring on an existing destination:
+
+```bash
+mkdir -p .claude/state/tasks/_archive/<id>
+# Move the durables only if not already archived (retry-safe):
+if [ -d .claude/state/tasks/<id>/spec ]; then
+  git mv .claude/state/tasks/<id>/spec .claude/state/tasks/_archive/<id>/spec
+fi
+# discoveries.md only exists if the task raised one — move it conditionally:
+if [ -f .claude/state/tasks/<id>/discoveries.md ]; then
+  git mv .claude/state/tasks/<id>/discoveries.md .claude/state/tasks/_archive/<id>/discoveries.md
+fi
+# Drop everything that remains under tasks/<id>/ — progress.md plus any straggler an
+# Implementer left. -r tolerates whatever is there; git doesn't track the empty dir.
+git rm -r .claude/state/tasks/<id>/
+```
+
+`spec/` and `discoveries.md` survive **live** under `_archive/<id>/` (grep-able), plus in
+git history and the GitHub issue. `progress.md` (the pause-point bitácora) and any other
+working scratch are gone.
+
+### 5. Open the closeout PR and auto-merge
+
+Commit the record, push the branch, open a PR, and let GitHub apply the repo's own rules:
+
+```bash
+git commit -m "closeout(<id>): archive task state, record in history.md"
+git push -u origin harness/closeout-<id>
+gh pr create --base <default> --head harness/closeout-<id> \
+  --title "closeout(<id>): <topic>" --body "Closeout record for #<id>."
+gh pr merge harness/closeout-<id> --auto --squash --delete-branch
+```
+
+The closeout PR **must not** carry `Closes #<id>` — the task PR already auto-closed the
+issue on merge; closeout only flips the label and finalizes.
+
+`gh pr merge` `--auto` defers to branch protection:
+
+- **Protection is PR + checks only** → the PR self-merges once checks pass. Continue to
+  step 6 (finalize) once the closeout PR reports merged.
+- **Protection requires human approval** → the PR waits. **Park** (see below).
+- **Auto-merge is disabled repo-wide** → `gh pr merge` `--auto` **errors** ("auto-merge is
+  not allowed for this repository") rather than queuing. This is a repo setting,
+  independent of branch protection. Treat the error as the wait case: **park**. (You may
+  instead merge it immediately with a plain `gh pr merge` `--squash --delete-branch` if the
+  human has authorized you to merge — same gesture as the task merge gate.)
+
+**Park:** flip the issue to `harness:status:closeout-pending`, tell the human the closeout
+PR is open and awaiting their merge, and stop. The task issue is **already closed** (the
+task PR's `Closes #<id>` fired on its merge), so `/resume` finds the parked closeout only
+by listing closed issues too (`--state all`) — a default open-only queue would miss it. A
+later `/resume` picks up at step 6 once the PR is merged. (Authority for the RESUME entry:
+the Orchestrator.)
+
+### 6. Finalize (once the closeout PR is merged)
+
+Confirm the closeout PR merged (`gh pr view <pr> --json state,mergedAt` → `MERGED`; on a
+`/resume`, pass the deterministic branch `harness/closeout-<id>` as `<pr>` — the
+merge-confirm accepts a branch name in place of a PR number), land the merged base
+(`git checkout <default> && git pull`), then:
+
+```bash
+git push origin --delete harness/<id>-<slug>   # delete the task branch (skip if already gone)
+gh issue close <id>                            # belt-and-suspenders if the merge didn't auto-close it
+```
+
+Then flip the issue to `harness:status:done` and **emit `task_done`** — both happen here,
+in finalize, exactly once (the parked → `/resume` path also lands here, so it is the
+single emit point for either path). You compute the envelope (cycle time, review
+rejections, level) as the Orchestrator running this skill; the fields and the `emit`
+command line are in `orchestrator.md` §Closeout. `events.jsonl` is local-only/gitignored
+(ADR 0008), so the emit never dirties the base.
+
+### 7. Report
+
+Return a one-line summary: the task id, the `history.md` entry, the archive path
+(`_archive/<id>/`), any ADR raised, and confirmation that the issue is closed (or that
+closeout is parked at `closeout-pending` awaiting the record PR's merge).
+
+## Scope note
+
+In this build, closeout records to `history.md`, archives the spec + discoveries, raises
+ADRs, and finalizes via the closeout PR. The session/metrics accounting beyond
+`task_done` is wired in a later phase — closeout is the place it will attach.
+
+## Uncontemplated Scenarios
+
+When a scenario doesn't clearly fit these rules:
+
+1. Apply the closest matching approach with reasoning.
+2. **Flag it**: "This scenario isn't covered by the task-closeout skill. I applied
+   [approach] because [reason]. Want to update the skill?"
+3. Offer to add a new rule for the case.

package/catalog/skills/tdd/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: tdd
+description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+phase: during-implementation
+invoked-by: [implementer]
+---
+
+# Test-Driven Development
+
+## Core Principle
+
+Tests verify behavior through public interfaces, not implementation details. Code
+can change entirely; tests shouldn't break. A good test reads like a specification —
+"user can checkout with valid cart" tells you exactly what capability exists.
+
+## Workflow
+
+### 0. Playbook preflight (mandatory — before writing any code or test)
+
+1. Identify which of the project's playbooks apply to this task and read them.
+   Playbooks are looked up by topic — `<topic>.md` under `docs/playbooks/` (then the
+   global layer); the local entry wins, and a missing playbook is not a blocker.
+2. Declare the test environment explicitly:
+
+   | This file type…                             | Use…                                               |
+   | ------------------------------------------- | -------------------------------------------------- |
+   | Pure logic, service, hook (no DOM)          | Node spec (`*.spec.ts`) — `environment: 'node'`    |
+   | React component, DOM interaction, rendering | Browser spec (`*.browser.spec.tsx`) — real browser |
+
+   State aloud: "This is a [type] test → [node/browser] mode, because [reason]."
+
+3. Output preflight log: "Playbooks loaded: [list]. Test environment: [node/browser].
+   Proceeding."
+
+### 1. Planning
+
+Before writing any code:
+
+- Confirm with user what interface changes are needed
+- Confirm with user which behaviors to test (prioritize — you can't test everything)
+- List the behaviors to test (not implementation steps)
+- Get user approval on the plan
+
+Ask: "What should the public interface look like? Which behaviors are most important
+to test?"
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behavior → test fails
+GREEN: Write minimal code to pass → test passes
+```
+
+This is your tracer bullet — proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test → fails
+GREEN: Minimal code to pass → passes
+```
+
+Rules:
+
+- One test at a time
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
+
+### 4. Refactor
+
+After all tests pass, look for refactor candidates:
+
+- Never refactor while RED — get to GREEN first
+- Run tests after each refactor step
+
+## Capture decisions worth remembering (ADR nudge)
+
+A green test proves _what_ the code does. It rarely captures _why_ this
+implementation was chosen over the alternatives. After a cycle (or at the end of a
+feature), ask: did this step embed a decision that will look arbitrary to a future
+reader?
+
+Three signals — if **all three** are true, write an ADR (`docs/adr/NNNN-slug.md`):
+
+1. **Hard to reverse** — changing your mind later costs real work (data migration,
+   public API break, cross-module refactor, downstream client coordination).
+2. **Surprising without context** — a future reader will see the code and wonder
+   "why on earth did they do it this way?"
+3. **Result of a real trade-off** — there were genuine alternatives and you picked
+   one for specific reasons (not "the obvious thing").
+
+Common triggers inside a TDD cycle:
+
+- A defensive cap or limit (depth, budget, retries, page size). The _value_ you
+  picked is the artifact most likely to drift later; the reason is rarely in the code.
+- A "consistency at every level" rule — easy to write, easy for a future patch to
+  break without noticing.
+- A non-obvious algorithm/data structure picked to satisfy a perf or budget test.
+- A deliberate **no-test** decision — "we are intentionally not covering X because the
+  cost outweighs the value." Future contributors will add the missing test and break
+  the design.
+- A boundary or scope decision: "this concern lives in module A, not module B."
+
+If only one or two signals hit, a `// Why: …` comment at the call site is usually
+enough. The bar for an ADR is "this decision will outlive my memory of writing it".
+
+When in doubt, flag it: "I made a non-trivial trade-off about X. Want me to draft an
+ADR?" — let the user decide. (The Architect's `write-adr` skill owns the ADR format;
+numbering is sequential under `docs/adr/`.)
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is the biggest TDD
+mistake.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+```
+
+Tests written in bulk test _imagined_ behavior. You outrun your headlights,
+committing to test structure before understanding the implementation. Each vertical
+cycle informs the next — because you just wrote the code, you know exactly what
+behavior matters.
+
+## When NOT to Apply TDD
+
+Not everything needs red-green-refactor:
+
+- **Validation schemas** — declarative, self-validating
+- **Configuration** (routes wiring, test config) — no logic to test
+- **Type definitions / interfaces** — no runtime behavior
+- **Re-exports / barrel files** — just wiring
+- **Constants and enums** — declarative
+- **Middleware wiring** — the middleware logic is tested, the wiring isn't
+- **Pass-through wrappers** — re-exporting a library without added logic
+- **Database migrations** — DDL scripts, validated by execution
+- **Static content** — i18n strings, templates, fixed content
+- **Logger / env config setup** — pure configuration
+- **Prototypes / spikes** — ask the user: "Do you want tests for this spike?"
+
+**Always test**: mappers (even small ones), services with business logic,
+repositories (integration), routes (API behavior), components (user interaction).
+
+## Mocking Strategy
+
+**`vi.spyOn` as default** — mock at system boundaries only (external APIs, databases,
+time/randomness). Don't mock your own modules' internals. DI only when it genuinely
+adds value. For mocking recipes → see your project's testing playbook.
+
+## Uncontemplated Scenarios
+
+When a scenario doesn't clearly fit these rules:
+
+1. Apply the closest matching rule with reasoning
+2. **Flag it**: "This scenario isn't covered by the tdd skill. I applied [rule]
+   because [reason]. Want to update the skill?"
+3. Offer to add a new rule for the case

package/catalog/skills/test-gap-report/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: test-gap-report
+description: Structural test-gap analysis of a change — which logic-bearing files lack a dedicated test, and which behaviors are untested. Walks the coverage matrix, not the runtime. Use during review to find missing tests before they become regressions; distinct from `verify` (which runs the suite) and `senior-review` (which judges the tests that exist).
+origin: vendor
+vendor_version: '{{vendor_version}}'
+phase: post-implementation
+invoked-by: [reviewer]
+---
+
+# Test Gap Report
+
+A **structural** gap analysis: which files in the change _should_ have a dedicated test
+and don't, and which behaviors are untested. This is separate from `verify` (which
+_runs_ the suite) and from `senior-review` (which judges whether the tests that exist
+are meaningful). Coverage numbers are a weak proxy — this walks the **coverage matrix**
+by file role instead.
+
+## Process
+
+### 1. Classify each changed file
+
+For every file the change adds or modifies, decide whether it needs a dedicated test
+using the coverage matrix (consult the project's testing playbook for project-specific
+roles):
+
+**Always needs a dedicated `*.spec.*`** (it carries logic — conditionals, loops,
+transformations, calculations):
+
+| Role                      | What to cover                                          |
+| ------------------------- | ------------------------------------------------------ |
+| service / use-case        | happy path, expected errors, edge cases                |
+| mapper / transformer      | every field, optional/nullable, empty collections      |
+| helper / util / validator | boundary values, error conditions                      |
+| hook                      | state transitions, side effects, cleanup               |
+| component                 | renders expected content, interactions, conditional UI |
+| processor / reducer       | each input/event type, unknown input                   |
+
+**Covered by integration (no dedicated spec needed)** — wiring, not logic:
+type-only models, thin route/api wrappers, simple stores, constants, config. A file
+here with **branching logic** is promoted to "always test."
+
+### 2. Find the gaps
+
+For each file in the "always" set:
+
+1. Does a co-located `*.spec.*` exist?
+2. If yes, does it cover the **behaviors** the change introduced (not just the ones
+   that were already there)? A new branch / error path / edge case added by this change
+   needs a new test even if the file already had a spec.
+3. **User-visible flows** (navigation / form / list / auth) added or modified → is
+   there an E2E test, or is one warranted per the testing playbook?
+
+### 3. Report
+
+```
+## Test Gap Report — <task name>
+
+| File | Role | Spec? | Gap |
+| --- | --- | --- | --- |
+| `order.service.ts` | service | ✅ | error path for empty cart untested |
+| `slug.util.ts` | util | ❌ | no spec — boundary cases untested |
+| `cart.view.tsx` | component | ✅ | covered |
+
+**Missing specs**: <n>  ·  **Partial coverage**: <n>
+**E2E**: needed / present / N/A
+**Verdict**: adequately covered / <n> gaps to close
+```
+
+Report gaps; do **not** silently write the missing tests yourself (that's the
+Implementer's loop). A gap is a finding routed back. If closing a gap reveals the
+behavior itself is unspecified, that's a **discovery** — run `raise-discovery`.

package/catalog/skills/triage-issue/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: triage-issue
+description: Triage a bug or issue by exploring the codebase to find root cause, then create a GitHub issue with a TDD-based fix plan. Use when user reports a bug, wants to file an issue, mentions "triage", or wants to investigate and plan a fix for a problem.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+invoked-by: [orchestrator]
+---
+
+# Triage Issue
+
+## Core Principle
+
+Investigate first, ask later. Find the root cause through codebase exploration
+before asking the user anything. Minimize questions, maximize diagnosis.
+
+## Process
+
+### 1. Capture the problem
+
+Get a brief description from the user. If they haven't provided one, ask ONE
+question: "What's the problem you're seeing?"
+
+Do NOT ask follow-up questions. Start investigating immediately.
+
+### 2. Explore and diagnose
+
+Deeply investigate the codebase to find:
+
+- **Where** the bug manifests (entry points, UI, API responses)
+- **What** code path is involved (trace the flow)
+- **Why** it fails (the root cause, not just the symptom)
+- **What** related code exists (similar patterns, tests, adjacent modules)
+
+Look at:
+
+- Related source files and their dependencies
+- Existing tests (what's tested, what's missing)
+- Recent changes to affected files (`git log`)
+- Error handling in the code path
+- Similar patterns elsewhere that work correctly
+
+### 3. Identify the fix approach
+
+Determine:
+
+- The minimal change needed to fix the root cause
+- Which modules/interfaces are affected
+- What behaviors need to be verified via tests
+- Whether this is a regression, missing feature, or design flaw
+
+### 4. Design TDD fix plan
+
+Create an ordered list of RED-GREEN cycles (vertical slices):
+
+- **RED**: a specific test that captures the broken/missing behavior
+- **GREEN**: the minimal code change to make that test pass
+
+Rules:
+
+- Tests verify behavior through public interfaces, not implementation details
+- One test at a time (NOT all tests first, then all code)
+- **Durability**: describe behaviors and contracts, not internal structure. A good
+  fix plan reads like a spec, a bad one reads like a diff
+
+For TDD philosophy → see the **tdd** skill. For test recipes → see your project's
+testing playbook.
+
+### 5. Confirm with the user
+
+Present the issue draft: problem summary, root cause analysis, and TDD fix plan.
+Ask: "Does this look right? Should I create the issue?"
+
+### 6. Create the GitHub issue
+
+After confirmation, create with `gh issue create` and the `harness:managed` label.
+Use a structure like:
+
+```
+## Problem
+<one-paragraph summary of the observed behavior>
+
+## Root cause
+<the actual cause, traced to file:line>
+
+## Fix plan (TDD)
+- [ ] RED: <test capturing behavior 1> → GREEN: <minimal change>
+- [ ] RED: <test capturing behavior 2> → GREEN: <minimal change>
+
+## Affected
+<modules / interfaces touched>
+```
+
+Print the issue URL and a one-line summary of the root cause.
+
+## Uncontemplated Scenarios
+
+When a scenario doesn't clearly fit these rules:
+
+1. Apply the closest matching approach with reasoning
+2. **Flag it**: "This scenario isn't covered by the triage-issue skill. I applied
+   [approach] because [reason]. Want to update the skill?"
+3. Offer to add a new rule for the case

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

@@ -0,0 +1,69 @@
+---
+name: update-architecture
+description: Keep docs/architecture.md current after an architecturally significant change — a new module/context, a changed boundary or integration seam, a new external dependency, a data-flow change. Use when the change alters the system's shape and the project keeps an architecture doc. The Orchestrator invokes the Architect with this skill; it only lands at install when docs/architecture.md already exists.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+applies-when: [has-architecture-doc]
+invoked-by: [architect]
+trigger-condition: a change alters the architecture (or drift is surfaced) and docs/architecture.md exists
+---
+
+# Update Architecture
+
+## Core Principle
+
+`docs/architecture.md` is the **living high-level map** of the system — the shape a new
+engineer reads first. It drifts the moment a change alters that shape and the doc isn't
+updated. This skill keeps it true to reality after an architecturally significant change.
+
+The trigger is usually a change in hand, but the job is the same when **drift is surfaced
+without a change** — an orientation or review finds the map already diverged from the code
+(a `code-explorer` Notes flag, a Reviewer side-finding; ADR 0011). Reconcile it the same
+way, applying the same significance bar below: only shape-level divergence is worth an edit.
+
+It is gated on `applies-when: has-architecture-doc`: it only installs when the project
+already keeps `docs/architecture.md`. The harness **never creates** an architecture doc
+where the client chose not to have one (decision #8 — the vendor gives the framework,
+not the architecture). If a project has no such doc and one is wanted, that's a client
+decision, not an automatic harness action.
+
+## What counts as architecturally significant
+
+Update the doc when the change touches the **shape**, not the detail:
+
+- a new module / bounded context, or one removed or merged;
+- a changed boundary or ownership rule ("X now owns Y; others reference by id");
+- a new or changed integration seam (sync HTTP → domain events, a new queue);
+- a new external dependency that carries lock-in (a database, a broker, an auth provider);
+- a data-flow change a reader of the diagram would otherwise get wrong.
+
+A bug fix, a refactor that preserves the shape, or a new function inside an existing
+module is **not** architecturally significant — leave the doc alone.
+
+## Process
+
+1. **Read the current doc** and locate the section the change — or the surfaced drift —
+   affects. Understand the existing structure before editing — match its level of
+   abstraction and its style.
+2. **Make the smallest true edit.** Reflect the new reality surgically: update the
+   affected section, a diagram, or a boundary statement. Don't rewrite what didn't change.
+3. **Link the why, don't restate it.** If the change was recorded as an ADR (via
+   `write-adr`), reference it (`see ADR-NNNN`) rather than re-explaining the rationale —
+   the architecture doc holds the _shape_, the ADR the _decision_.
+4. **Keep it high-level.** This is a map, not a code listing. Resist pulling in
+   implementation detail that belongs in code, `CLAUDE.md`, or a playbook.
+
+## Report
+
+Return to the Orchestrator: the section(s) updated and a one-line summary of what the
+map now reflects. If the change turned out **not** to be architecturally significant,
+say so and make no edit.
+
+## 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 update-architecture skill. I did [approach]
+   because [reason]. Want to refine the skill?"
+3. Offer to add a rule for the case.