@ikon85/agent-workflow-kit 0.10.0

package/.agents/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,60 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence 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
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **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.
+
+## 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.

package/.agents/skills/domain-modeling/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: domain-modeling
+description: "Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model."
+---
+
+# Domain Modeling
+
+> **In this repo (if present):** `CONTEXT.md` + `docs/adr/` already exist (lazily created via `/grill-with-docs`). The **ADR conventions are SSOT in `docs/adr/README.md`** (project root; status lifecycle, template, numbering) — use that convention when creating an ADR, don't shadow it with the generic [ADR-FORMAT.md](./ADR-FORMAT.md). `/grill-with-docs`(-codex) maintains CONTEXT.md + ADRs in operation; this skill is the vocabulary underneath. Provenance: `docs/agents/provenance.md`.
+
+Actively build and sharpen the project's domain model as you design. This is the *active* discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why 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 any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

package/.agents/skills/domain-modeling/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+This skill is adapted from **Matt Pocock's skills**
+(https://github.com/mattpocock/skills), `skills/engineering/domain-modeling` @ d574778, Copyright (c) 2026 Matt Pocock,
+used under the MIT License. Locally adapted (fork-and-own); see PROVENANCE.md.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/.agents/skills/git-worktree-recover/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: git-worktree-recover
+description: "Recovery skill for git branch mix-ups — a commit landed on the wrong branch, the branch switched unexpectedly, or work appears lost. Uses git reflog to find the misplaced commit, moves it to the right branch (git branch -f), optionally resets the wrong branch, and sets up a clean worktree. Triggers: commit on the wrong branch, branch switched on its own, this commit doesn't belong here, my work is gone, I committed to main by accident."
+---
+
+# git-worktree-recover
+
+Recovery skill for branch mix-ups. When two processes share one checkout's global
+`HEAD`, they can clobber each other — a commit lands on the wrong branch. This
+skill is the **reaction** when a prevention layer (a worktree-per-session
+discipline and its guards) didn't stop it.
+
+## When to invoke
+
+- "My commit is on the wrong branch"
+- "The branch switched even though I did nothing"
+- "This commit doesn't belong here"
+- "My work is gone / I can't see my commit anymore"
+- "I accidentally committed to main"
+
+## Precondition
+
+If your project has a prevention layer — a SessionStart warning on active
+worktrees, a pre-edit guard that blocks edits on the wrong branch — this skill
+handles the case where that layer did NOT prevent a misplaced commit. Your project
+layer names those guards (`docs/agents/skills/git-worktree-recover.md`, seeded as
+an empty stub by `/setup-workflow`).
+
+---
+
+## Phase 1 — Assess the situation
+
+Run these four read-only commands (no harm):
+
+```bash
+git branch --show-current
+git log --oneline -10
+git reflog --oneline -20
+git worktree list
+```
+
+**Goal:** identify the misplaced commit SHA + the intended target branch.
+
+### What to look for in the reflog
+
+A line like:
+
+```
+691b655 HEAD@{3}: commit: <your commit message>
+```
+
+...appearing on a branch that is *not* the commit's intended branch. Note the SHA
+and message.
+
+---
+
+## Phase 2 — Safety checks
+
+Before any destructive action:
+
+1. **Is the target branch checked out in another worktree?**
+   ```bash
+   git worktree list
+   ```
+   `git branch -f <branch> <sha>` fails if the branch is checked out elsewhere —
+   that is safe (git refuses it), but check first to get a clear message.
+
+2. **Does the wrong branch have its own commits that must survive?**
+   ```bash
+   git log --oneline <wrong-branch>..origin/main
+   ```
+   If nothing of its own (it is `main`, or carries nothing) → a reset to
+   `origin/main` is safe.
+
+3. **Is the SHA really the right commit?**
+   ```bash
+   git show --stat <sha>
+   ```
+   Check the message + changed files against the intended context.
+
+---
+
+## Phase 3 — Move the commit to the right branch
+
+**Case A: target branch does not exist yet (most common)**
+
+```bash
+git branch <target-branch> <sha>
+git log --oneline <target-branch> -5   # verify
+```
+
+**Case B: target branch exists and the commit is missing there**
+
+```bash
+git branch -f <target-branch> <sha>    # only if NOT checked out elsewhere
+git log --oneline <target-branch> -5   # verify
+```
+
+**Case C: several commits on the wrong branch (stacked mix-up)**
+
+```bash
+git cherry-pick <sha1> <sha2> ...      # run on the correct branch, oldest first
+```
+
+---
+
+## Phase 4 — Clean up the wrong branch (optional, recommended)
+
+Only when:
+
+- the wrong branch is checked out in the main tree (not a worktree), AND
+- the wrong branch is `main` or carries no feature commits of its own.
+
+```bash
+git reset --hard origin/main
+git log --oneline -5   # the misplaced commit must NOT appear here anymore
+```
+
+If the wrong branch is a feature branch with its own state → do **not** reset; drop
+only the one commit (`git rebase --onto`). Rare special case — confirm before doing
+it.
+
+---
+
+## Phase 5 — Set up a worktree
+
+Set the recovered branch up cleanly in its own worktree. If your project has a
+worktree-setup command, use it (it typically runs `git worktree add`, installs
+deps and copies env files); otherwise:
+
+```bash
+git worktree add <path> <recovered-branch>
+```
+
+Your project layer names the exact command and what it copies.
+
+**Verify after setup:**
+
+```bash
+git worktree list
+```
+
+---
+
+## Phase 6 — Final check
+
+```bash
+git log --oneline <target-branch> -5   # SHA must appear here
+git log --oneline <wrong-branch> -3    # SHA must no longer be the top here
+git worktree list                      # clean
+```
+
+---
+
+## Background + cause
+
+`git` keeps ONE global `HEAD` pointer per checkout. If two processes run
+`git checkout`, the second overwrites the first — a commit can then land on the
+wrong branch. Not a bug, a git property. The fix is isolation via `git worktree`
+(one checkout dir per session); this skill is the reaction when a prevention guard
+did not catch it.
+
+**Safety guarantees of `git branch -f`:**
+
+- Refuses to run if the branch is checked out in another worktree (git built-in).
+- No data loss: the commit stays in the object store, only the branch pointer moves.
+- Always reversible via `git reflog`.
+
+## Anti-patterns
+
+- **`git rebase -i` to remove commits from main** — too destructive, risks a
+  force-push to main (a pre-push hook should block it, but avoid it anyway).
+- **`git reset --hard` without the safety check** — only after the worktree-list
+  check and only when the branch has no feature state of its own.
+- **Reflog without SHA verification (`git show`)** — reflog shows checkouts too,
+  not just commits; always `git show <sha>` before acting.

package/.agents/skills/grill-me/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: grill-me
+disable-model-invocation: true
+description: "Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions \"grill me\"."
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a *fact* can be found by exploring the codebase, look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
+
+Do not enact the plan until I confirm we have reached a shared understanding.
+
+## Related skills
+
+**Codebase with `CONTEXT.md`/ADRs present?** → use `grill-with-docs` instead of this skill — same grill, additionally sharpened against the existing domain model, maintains `CONTEXT.md`/ADRs inline.
+
+<!-- mirror-xform:start codex-escalation -->
+**High stakes / hard to reverse** (auth, schema, concurrency, migrations, payments)? On the Claude Code surface, this grill is followed by a cross-model review by Codex — not available on this surface.
+<!-- mirror-xform:end -->
+
+## Coherence is the default — the grill locks only the deltas
+
+A feature that builds on existing features inherits the existing building blocks by default, across **every** layer: the UI renders the same components, the backend calls the same services and calculations, data flows through the same paths, conventions carry over. Do not interview the user about how such a feature should look or behave where an existing counterpart exists — that is already decided. Lock only:
+
+1. **The deltas:** what is intentionally excluded, restricted, or different (navigation, filters, actions, person data, write access, …). Every delta is an explicit decision with a reason.
+2. **The consumer walk-through:** who consumes the result and what they see/get — walked through from the consumer's side, not the owner's.
+
+A parallel rebuild of something that exists — a simplified UI stand-in, a re-implemented calculation, a second data path — is a defect to surface, never a silent shortcut. (Incident: a share feature shipped rebuilt, simplified renderers across 6 pages because "looks like the page minus chrome" was treated as open design space instead of the default; half the implementation was replaced.)
+
+## Cross-cutting fork — pattern vs. concept (before plan-lock)
+
+Is the change **cross-cutting** (a new pattern OR a new data structure/domain distinction, touching ≥3 places, OR "everywhere / distinguish X of Y / migrate")? Then classify it **during the grill** — don't defer it to the post-spec self-critique (otherwise Codex reviews a plan without it):
+
+- **Pattern** (old→new, e.g. TanStack Query replacing manual loading): the denominator is **grep-able** → put in the plan: a census of all old spots + a `*.guard.test.ts` that stays red as long as old spots exist outside a shrinking allowlist.
+- **Concept** (a new distinction, e.g. Project↔Campaign): `grep` cannot find the **absence** of a concept → put in the plan: a **code-derived** surface list (routes/pages/exports/reports) × a **domain verdict per surface** (counts / N/A / open); "counts" rows become tracked items.
+
+Never claim "complete" from plan/memory — count the denominator fresh, report `X of Y`. Substance, trigger threshold + guard template → the project convention file `docs/conventions/spec-completeness.md` (if present), §Cross-cutting fork.
+
+## Plan-lock — writing PLAN.md
+
+Once all decisions are made (plan locked, before sign-off/handoff) and the session runs in a **worktree** → write the locked plan as `PLAN.md` to the worktree root (gitignored since, doesn't travel over git — consistent with CLAUDE.md "plan inside the worktree"). This way the locked plan survives a session cut and `to-prd` finds its default source. Continuing same-session work **without** a worktree stays allowed (conversation = source); but for a deliberate **session cut** before `to-prd`, `PLAN.md` is mandatory. (The `-codex` variant already writes `PLAN.md` anyway.)
+
+## Re-grill reconcile — execute-ready (Wave 26)
+
+Applies when you **re-grill an issue that already exists** (a leaf of a grilled epic, or a child of an anchor) — the most common re-grill path, since campaign HITL slices route via `/grill-me → /tdd`. Goal: the rooted sub-graph comes out **execute-ready**, never silent drift. (grill-me has no docs layer — CONTEXT.md/ADR don't apply; core rules identical to grill-with-docs §"Re-Grill Reconcile".)
+
+1. **Read parent-anchor decisions FIRST** — fetch the anchor body + its PRD/key decisions, take the seam decision **from there**. Do not re-derive the architecture from the leaf (lesson: a leaf whose central decision was never read got re-litigated through question rounds). For an atomic leaf, its own body/PRD is the reference.
+2. **Check the leaf for internal contradiction**: a body that contradicts itself ("no new UI" + "build a name field") or the anchor decision → **no execute**. Likewise a leaf that says *"final cut depends on #X"* via `<!-- final-cut-depends-on: #X -->` where **#X is closed** without resolving the cut.
+3. **On drift/contradiction:** update the affected issue(s), re-stamp `plan_revision`, set the correct bucket. Internal contradiction → set the leaf to **HITL**: strip `ready-for-agent` via `python3 scripts/board-sync.py add --bucket hitl --issue <n>` (the helper stays the owner of the workflow labels — no bare `gh issue edit --add-label`), add the `headings.vorBau` heading (board profile `docs/agents/board-sync.md`; <project> currently `## Vor Bau zu klären`). The drift-guard then blocks the build handoff via `target_buildable` — the contradiction flows through existing machinery, no heuristic in the hook.
+4. **Audit, non-blocking:** `python3 scripts/execute-ready-check.py --issue <n> --mode audit` → a visible two-liner. The **blocking** net is the drift-guard at handoff (`.claude/hooks/drift-guard.py`).
+
+**Markers** (HTML comments, grep-able): `<!-- guard-ack: #<n> r<N> reason:<text> by-user -->`, `<!-- final-cut-depends-on: #<n> -->`, `<!-- handoff-intent: build|grill -->`, `<!-- guard-legacy -->`. Canonical table of all markers: module docstring of `scripts/execute-ready-check.py`.

package/.agents/skills/grill-me/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+This skill is adapted from **Matt Pocock's skills**
+(https://github.com/mattpocock/skills), `skills/productivity/grill-me` @ d574778, Copyright (c) 2026 Matt Pocock,
+used under the MIT License. Locally adapted (fork-and-own); see PROVENANCE.md.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

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

@@ -0,0 +1,47 @@
+# 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
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+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/.agents/skills/grill-with-docs/CONTEXT-FORMAT.md

@@ -0,0 +1,60 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence 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
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **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.
+
+## 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.