ai-engineering-kit 0.1.0 → 0.3.0

package/README.md

@@ -6,7 +6,9 @@
 
 `ai-engineering-kit` scaffolds a repeatable workflow for building software with AI coding agents:
 
-- **Skills** — Markdown playbooks for each step: kickoff → foundations → PRD → plan → TDD → review → verify.
+- **Skills** — Markdown playbooks, grouped into categories you pick at install time:
+  - **core-workflow** — kickoff → foundations → PRD → plan → implement → review → verify.
+  - **engineering**, **productivity**, **misc** — additional day-to-day skills forked from [`mattpocock/skills`](https://github.com/mattpocock/skills) (see attribution below).
 - **A structured workspace** — `ai/` for ephemeral artifacts (brainstorms, PRDs, plans, reviews) and `docs/foundations/` for canonical, long-lived project knowledge.
 - **Agent-agnostic wiring** — skills live as portable Markdown in `ai/skills/`; the kit generates the entry file each agent reads (`CLAUDE.md` + a `.claude/skills/` symlink for Claude Code, `AGENTS.md` for Codex). More agents are a template + a manifest entry away.
 

package/dist/cli.js

@@ -22,26 +22,77 @@ function parseManifest(json) {
 
 // src/catalog/definition.ts
 var CATEGORIES = [
-  { id: "core-workflow", label: "Core workflow", from: "skills/core-workflow", to: "ai/skills" }
+  {
+    id: "core-workflow",
+    label: "Core workflow",
+    hint: "End-to-end loop: kickoff \u2192 PRD \u2192 plan \u2192 implement \u2192 review \u2192 verify",
+    from: "skills/core-workflow",
+    to: "ai/skills"
+  },
+  {
+    id: "engineering",
+    label: "Engineering",
+    hint: "Daily coding skills \u2014 TDD, debugging, triage, architecture (from mattpocock/skills)",
+    from: "skills/engineering",
+    to: "ai/skills"
+  },
+  {
+    id: "productivity",
+    label: "Productivity",
+    hint: "Workflow helpers \u2014 grilling, handoff, teaching, concise mode (from mattpocock/skills)",
+    from: "skills/productivity",
+    to: "ai/skills"
+  },
+  {
+    id: "misc",
+    label: "Misc",
+    hint: "Occasional utilities \u2014 git guardrails, pre-commit, scaffolding (from mattpocock/skills)",
+    from: "skills/misc",
+    to: "ai/skills"
+  }
 ];
 var TREE_COMPONENTS = [
-  { id: "docs-foundations", label: "docs/foundations scaffold", from: "docs/foundations", to: "docs/foundations" },
-  { id: "ai-workspace", label: "ai/ workspace dirs", from: "ai-workspace", to: "ai" }
+  {
+    id: "docs-foundations",
+    label: "Foundation docs",
+    hint: "Starter docs for product vision, guidelines, and technical decisions (docs/foundations/)",
+    from: "docs/foundations",
+    to: "docs/foundations"
+  },
+  {
+    id: "ai-workspace",
+    label: "Workspace folders",
+    hint: "Folders the skills write to: brainstorms, PRDs, plans, reviews (ai/)",
+    from: "ai-workspace",
+    to: "ai"
+  }
 ];
 var COMPONENTS = [
-  { id: "skills", label: "Skills", unlocks: "categories" },
-  ...TREE_COMPONENTS.map((t) => ({ id: t.id, label: t.label })),
-  { id: "entry-files", label: "Agent entry files", unlocks: "agents" }
+  {
+    id: "skills",
+    label: "Skills",
+    hint: "Reusable AI playbooks the agent runs on demand (plan, implement, review, debug\u2026)",
+    unlocks: "categories"
+  },
+  ...TREE_COMPONENTS.map((t) => ({ id: t.id, label: t.label, hint: t.hint })),
+  {
+    id: "entry-files",
+    label: "Agent entry files",
+    hint: "Instruction files that wire your coding agent to the skills (CLAUDE.md / AGENTS.md)",
+    unlocks: "agents"
+  }
 ];
 var AGENTS = [
   {
     id: "claude-code",
     label: "Claude Code",
+    hint: "Adds CLAUDE.md + a .claude/skills/ symlink for native skill discovery",
     files: [{ from: "agents/claude-code.CLAUDE.md", to: "CLAUDE.md", substitute: true }]
   },
   {
     id: "codex",
     label: "Codex",
+    hint: "Adds AGENTS.md referencing ai/skills/",
     files: [{ from: "agents/codex.AGENTS.md", to: "AGENTS.md", substitute: true }]
   }
 ];
@@ -292,13 +343,13 @@ import { multiselect, text, isCancel, cancel } from "@clack/prompts";
 
 // src/menu/menu.ts
 function componentOptions() {
-  return COMPONENTS.map((c) => ({ value: c.id, label: c.label }));
+  return COMPONENTS.map((c) => ({ value: c.id, label: c.label, hint: c.hint }));
 }
 function categoryOptions() {
-  return CATEGORIES.map((c) => ({ value: c.id, label: c.label }));
+  return CATEGORIES.map((c) => ({ value: c.id, label: c.label, hint: c.hint }));
 }
 function agentOptions() {
-  return AGENTS.map((a) => ({ value: a.id, label: a.label }));
+  return AGENTS.map((a) => ({ value: a.id, label: a.label, hint: a.hint }));
 }
 function buildSelection(answers) {
   return {
@@ -316,33 +367,26 @@ function required(value) {
   }
   return value;
 }
-async function promptForSelection(projectDir) {
-  const components = required(
+var allValues = (options) => options.map((o) => o.value);
+async function pickAll(message, options) {
+  return required(
     await multiselect({
-      message: "Which parts do you want to install?",
-      options: componentOptions(),
+      message: `${message} (everything is pre-selected \u2014 toggle off what you don't want)`,
+      options,
+      initialValues: allValues(options),
       required: true
     })
   );
+}
+async function promptForSelection(projectDir) {
+  const components = await pickAll("Which parts do you want to install?", componentOptions());
   let categories = [];
   if (components.includes("skills")) {
-    categories = required(
-      await multiselect({
-        message: "Which skill categories?",
-        options: categoryOptions(),
-        required: true
-      })
-    );
+    categories = await pickAll("Which skill categories?", categoryOptions());
   }
   let agents = [];
   if (components.includes("entry-files")) {
-    agents = required(
-      await multiselect({
-        message: "Which coding agents?",
-        options: agentOptions(),
-        required: true
-      })
-    );
+    agents = await pickAll("Which coding agents?", agentOptions());
   }
   const projectName = required(
     await text({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-engineering-kit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "An opinionated, agent-agnostic AI-development kit — disciplined skills plus a structured workspace — installed and updated through one npx command.",
   "type": "module",
   "license": "MIT",

package/template/skills/core-workflow/commit-organizer/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: commit-organizer
+description: Analyze all code changes across one or more repos and organize them into logical, separate conventional commits. Use when you have many unstaged/staged changes and want clean, atomic commits instead of one big commit.
+argument-hint: "[repo-path]"
+allowed-tools: Read, Bash(git *), Glob, Grep
+---
+
+# Commit Organizer
+
+Analyze all code changes (staged and unstaged) in the current directory. If the directory contains multiple git repos (a workspace root), analyze each repo independently. Organize changes into logical, atomic conventional commits.
+
+## How It Works
+
+1. Detect whether the current directory is a git repo or a workspace containing multiple repos
+2. For each repo, collect all modified, added, and untracked files
+3. Read the diffs and new file contents to understand what each change does
+4. Group related changes into logical commit units (e.g., a permission change + its test = one commit)
+5. Order commits so dependencies come first
+6. Present the commit plan to the user for approval
+7. Execute the commits one by one
+
+## Commit Message Rules
+
+- Use conventional commits: `type(scope): description`
+- Types: `feat`, `fix`, `refactor`, `style`, `docs`, `test`, `chore`
+- One line only, max 72 characters
+- Describe WHAT the change does from the user's perspective, not HOW
+- Use imperative mood: "add", "fix", "ensure", "change", not "added", "fixes"
+- Be specific — name the feature, the bug, the thing that changed
+
+### Good Examples
+
+```
+feat: add per-card CSV export to Insights dashboard cards
+feat: ensure bulk data export is only available to superAdmin users
+fix: use YYYY/MM/DD date format in all CSV exports
+refactor: extract shared RQS value mapping to exportUtils
+feat: add export audit log with search and pagination
+chore: add i18n keys for export and audit log UI
+```
+
+### Bad Examples
+
+```
+update code                          # too vague
+feat: changes to export              # what changes?
+fix: fix bug                         # what bug?
+feat: add new feature                # what feature?
+refactor: refactor stuff             # what stuff?
+feat: implement export refactoring   # describes the task, not the change
+```
+
+## Grouping Strategy
+
+Group changes into commits by **logical intent**, not by file type:
+
+- A backend permission change + frontend visibility change for the same feature = ONE commit
+- A new utility file + the component that uses it = ONE commit (if tightly coupled)
+- i18n keys can be grouped with the feature that uses them, or in a separate commit if they span multiple features
+- Unrelated changes to different features = SEPARATE commits
+- A new GraphQL schema + resolver + frontend query/mutation for one feature = ONE commit
+
+When in doubt, prefer fewer, more meaningful commits over many tiny ones.
+
+## Execution
+
+### Step 1: Detect Repos
+
+If `$ARGUMENTS` is provided, use it as the path. Otherwise use the current working directory.
+
+```bash
+# Check if current dir is a git repo
+git rev-parse --git-dir 2>/dev/null
+
+# If not, find git repos one level deep (workspace mode)
+for dir in */; do
+  if [ -d "$dir/.git" ]; then
+    echo "$dir"
+  fi
+done
+```
+
+### Step 2: Collect Changes Per Repo
+
+For each repo, run:
+
+```bash
+git status -u          # all changes including untracked (never use -uall)
+git diff               # unstaged changes
+git diff --cached      # staged changes
+```
+
+For untracked files, read their contents to understand what they add.
+
+### Step 3: Analyze and Group
+
+Read all diffs and new files. For each change, determine:
+- What feature or concern does this belong to?
+- Is it a feat, fix, refactor, style, docs, test, or chore?
+- What other changes is it related to?
+
+Group into commit units. Each unit has:
+- A list of files to stage
+- A commit message
+- A brief rationale (for the user to review)
+
+### Step 4: Present Plan
+
+Show the user a numbered list of proposed commits in order:
+
+```
+Repository: cliezen-graph
+
+  1. feat: restrict bulk CSV export to superAdmin users
+     Files: routes/exportCsv.js
+     
+  2. fix: use YYYY/MM/DD date format in bulk CSV exports
+     Files: routes/exports/csv.js
+
+Repository: cliezen-dashboard
+
+  3. feat: add shared export utilities and CSV formatters
+     Files: src/utils/exportUtils.js, src/utils/cardExportFormatters.js
+
+  4. feat: add per-card CSV export to Insights dashboard cards
+     Files: src/composables/useCardExport.js, src/components/Insights/DashCard.vue, src/graphql/mutations.js
+```
+
+Ask the user: "Does this commit plan look good? You can adjust, reorder, merge, or split any commits."
+
+Wait for approval before proceeding. If the user says "go" or "yes" or "looks good", execute. If they request changes, adjust and re-present.
+
+### Step 5: Execute Commits
+
+For each commit unit, in order:
+
+```bash
+cd <repo-path>
+git add <file1> <file2> ...    # stage only files for this commit
+git commit -m "<message>"       # commit with the planned message
+```
+
+After each commit, confirm success before moving to the next.
+
+If a commit fails (e.g., pre-commit hook), stop and report the error. Do not skip or force.
+
+### Step 6: Summary
+
+After all commits are done, show a summary:
+
+```
+Done! Created N commits across M repos:
+
+cliezen-graph (2 commits):
+  abc1234 feat: restrict bulk CSV export to superAdmin users
+  def5678 fix: use YYYY/MM/DD date format in bulk CSV exports
+
+cliezen-dashboard (4 commits):
+  111aaaa feat: add shared export utilities and CSV formatters
+  222bbbb feat: add per-card CSV export to Insights dashboard cards
+  ...
+```
+
+## Edge Cases
+
+- If there are no changes in a repo, skip it silently
+- If all changes belong to one logical unit, make one commit (don't force artificial splits)
+- If a file has changes belonging to two different features, note this and ask the user how to handle it (commit the whole file with the more significant change, or suggest the user manually split it with `git add -p`)
+- Never run `git add .` or `git add -A` — always stage specific files
+- Never amend existing commits
+- Never force push
+- Never use `--no-verify`
+- Never add Co-Authored-By, Signed-off-by, or any AI attribution trailers to commit messages
+- Commit messages are the developer's own — no mention of Claude, AI, or any tool

package/template/skills/engineering/diagnose/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: diagnose
+description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
+---
+
+# Diagnose
+
+A discipline for hard bugs. Skip phases only when explicitly justified.
+
+When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### Iterate on the loop itself
+
+Treat the loop as a product. Once you have _a_ loop, ask:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+Do not proceed to Phase 2 until you have a loop you believe in.
+
+## Phase 2 — Reproduce
+
+Run the loop. Watch the bug appear.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+Do not proceed until you reproduce the bug.
+
+## Phase 3 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+## Phase 6 — Cleanup + post-mortem
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
+- [ ] Regression test passes (or absence of seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
+
+**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

package/template/skills/engineering/diagnose/scripts/hitl-loop.template.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Human-in-the-loop reproduction loop.
+# Copy this file, edit the steps below, and run it.
+# The agent runs the script; the user follows prompts in their terminal.
+#
+# Usage:
+#   bash hitl-loop.template.sh
+#
+# Two helpers:
+#   step "<instruction>"          → show instruction, wait for Enter
+#   capture VAR "<question>"      → show question, read response into VAR
+#
+# At the end, captured values are printed as KEY=VALUE for the agent to parse.
+
+set -euo pipefail
+
+step() {
+  printf '\n>>> %s\n' "$1"
+  read -r -p "    [Enter when done] " _
+}
+
+capture() {
+  local var="$1" question="$2" answer
+  printf '\n>>> %s\n' "$question"
+  read -r -p "    > " answer
+  printf -v "$var" '%s' "$answer"
+}
+
+# --- edit below ---------------------------------------------------------
+
+step "Open the app at http://localhost:3000 and sign in."
+
+capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
+
+capture ERROR_MSG "Paste the error message (or 'none'):"
+
+# --- edit above ---------------------------------------------------------
+
+printf '\n--- Captured ---\n'
+printf 'ERRORED=%s\n' "$ERRORED"
+printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

package/template/skills/engineering/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/template/skills/engineering/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.