@jaybeeuu/agent-cortex 1.37.1 → 1.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "1.37.1",
+  "version": "1.39.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
@@ -29,11 +29,13 @@
   "scripts": {
     "build": "echo 'Build complete — no compilation needed for PI package'",
     "lint": "pnpm typecheck",
-    "test": "pnpm -r test",
+    "test": "node --test test/*.test.mjs && pnpm -r test",
     "typecheck": "pnpm -r typecheck",
-    "build:claude": "node scripts/build-claude-agents.mjs",
+    "build:claude": "node bin/agent-cortex.mjs install claude --output claude",
+    "build:copilot": "node scripts/build-copilot-agents.mjs",
     "changeset": "changeset",
-    "version-packages": "changeset version && bash scripts/sync-plugin-version.sh",
+    "version-packages": "changeset version && bash scripts/sync-plugin-version.sh && pnpm build:claude && pnpm build:copilot",
+    "publish-package": "TARBALL=$(pnpm pack | tail -n 1) && npm publish \"$TARBALL\" --provenance --access public",
     "release": "changeset publish",
     "postinstall": "bash scripts/install-instructions.sh"
   }

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-cortex",
   "description": "Personal Copilot CLI plugin with custom agents and skills",
-  "version": "1.37.1",
+  "version": "1.39.0",
   "author": {
     "name": "jaybeeuu"
   },

package/pnpm-workspace.yaml

@@ -1,6 +1,6 @@
 packages:
   - "."
-  - "skills/*/scripts"
+  - "skills/**/scripts"
   - "extensions/*"
 allowBuilds:
   '@google/genai': false

package/scripts/build-copilot-agents.mjs

@@ -0,0 +1,30 @@
+// Regenerates the committed Copilot CLI flat agent files (agents/*.agent.md)
+// from the canonical composable agent sources (agents/<name>/).
+//
+// This script is a thin wrapper over the shared install-time generator
+// (bin/installers/copilot.mjs) — `agent-cortex install copilot` runs exactly the
+// same code path, so install-time and build-time output can never diverge. CI
+// runs this and checks `git diff --exit-code -- 'agents/*.agent.md'` to
+// guarantee the committed flat files are never stale: a fresh clone (or a
+// direct path plugin install) ships the Copilot plugin read-ready.
+//
+//   agents/<name>.agent.md    composed from agents/<name>/agent.md +
+//                             agents/<name>/copilot/frontmatter.json +
+//                             agents/<name>/copilot/<section>.md ({{SECTION:...}}),
+//                             with {{TOOL:...}}/{{PATH:...}} substituted against
+//                             the copilot column of token-map.json.
+//
+// The flat files live in the same agents/ directory the Copilot plugin scans
+// (plugin.json "agents": "agents/"), next to the composable dirs they come
+// from — the generator only writes *.agent.md files and never deletes.
+//
+// Run: pnpm build:copilot   (node scripts/build-copilot-agents.mjs)
+// Zero dependencies so it runs on the CI Node (20) and local Node alike.
+
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { installCopilot } from "../bin/installers/copilot.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+installCopilot({ root: ROOT, output: join(ROOT, "agents") });

package/scripts/lib/compose-agent.mjs

@@ -0,0 +1,241 @@
+// Shared composer: reads a composable agent directory (agents/<name>/) and emits
+// the harness-specific agent content defined by agents/README.md. The Copilot
+// generator (scripts/build-copilot-agents.mjs) and the Claude install-time generator
+// (bin/installers/claude.mjs) compose from here, so the composable dirs are
+// the single source of truth and the flat/generated files stay in lockstep.
+//
+// Composition per the agents/README.md contract:
+//   1. {{SECTION:name}} is replaced with <dir>/<harness>/<name>.md content.
+//   2. {{TOOL:key}} is replaced with the harness column of token-map.json.
+//   3. {{PATH:arg}} with a named key resolves through token-map.json's paths
+//      table; anything else is a relative path and stays verbatim.
+// Substitution order is SECTION → TOOL → PATH (matches extensions/agent-modes).
+// Missing sections, unknown tool keys, or schema-invalid frontmatter are hard
+// errors: a committed generated file must never ship a literal token or a
+// silently dropped section.
+//
+// Options (the pi installer passes `dropNullTools`, `pluginRoot` and
+// `resolveRelativePaths`; the copilot generator and claude installer use the strict defaults):
+//   dropNullTools          replace null-mapped tool tokens with an empty string and
+//                          warn instead of throwing (pi's prose rule per the
+//                          token-map contract)
+//   pluginRoot             override the plugin_root used for resolved paths
+//                          (installers compute it from the actual install layout)
+//   resolveRelativePaths   non-keyed {{PATH:...}} args resolve to pluginRoot/arg
+//                          instead of staying verbatim (install time; the build
+//                          scripts leave them bare for Copilot CLI resolution)
+//   warn                   callback for drop/omit warnings (default: no-op; the
+//                          pi installer collects them into its result)
+//
+// Zero dependencies so it runs on the CI Node (20) and local Node alike.
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── Token substitution ──────────────────────────────────────────────────────
+
+const TOOL_RE = /\{\{TOOL:([^}]+)\}\}/g;
+const PATH_RE = /\{\{PATH:([^}]+)\}\}/g;
+
+function noop() {}
+
+/**
+ * Substitute {{TOOL:...}} and {{PATH:...}} tokens in arbitrary content (agent
+ * bodies, skill files) against one harness column of token-map.json.
+ *
+ * - TOOL: unknown key → throw (the map must stay complete); null mapping → drop
+ *   with a warning when `dropNullTools`, otherwise throw.
+ * - PATH: named key → resolve through the paths table (plugin_root overridable);
+ *   non-keyed → join(pluginRoot, arg) when `resolveRelativePaths`, else verbatim.
+ * - SECTION tokens are *not* handled here — the agent composer resolves them from
+ *   the harness's section files before calling this.
+ *
+ * @param {string} content  Source text containing {{TOOL:...}}/{{PATH:...}} tokens
+ * @param {string} harness  Harness id: "copilot" | "claude" | "pi"
+ * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
+ * @param {object} options  { dropNullTools, pluginRoot, resolveRelativePaths, warn, context }
+ * @returns {string}
+ */
+export function substituteTokens(content, harness, tokenMap, options = {}) {
+  const { dropNullTools = false, pluginRoot, resolveRelativePaths = false, warn = noop, context = "" } = options;
+  const ctx = context ? `${context}: ` : "";
+
+  // 2. {{TOOL:key}} → token-map.json tools.<key>.<harness>
+  content = content.replace(TOOL_RE, (_token, key) => {
+    const entry = tokenMap.tools[key];
+    if (!entry) throw new Error(`${ctx}unknown tool token {{TOOL:${key}}} — extend token-map.json`);
+    const mapped = entry[harness];
+    if (mapped == null) {
+      if (dropNullTools) {
+        warn(`tool token {{TOOL:${key}}} has no ${harness} mapping — dropped`);
+        return "";
+      }
+      throw new Error(`${ctx}tool token {{TOOL:${key}}} has no ${harness} mapping (null) — drop the token in agent.md first`);
+    }
+    return mapped;
+  });
+
+  // 3. {{PATH:arg}} → named keys via token-map.json paths; relative paths verbatim
+  //    (or resolved against pluginRoot when the installer option is set)
+  content = content.replace(PATH_RE, (_token, arg) =>
+    resolvePath(arg, harness, tokenMap, { pluginRoot, resolveRelativePaths }),
+  );
+
+  return content;
+}
+
+/**
+ * Compose the harness-specific agent content from a composable agent directory.
+ *
+ * @param {string} root    Package root (contains agents/ and token-map.json)
+ * @param {string} name    Agent directory name (e.g. "ralph", "plan")
+ * @param {string} harness Harness id: "copilot" | "claude" | "pi"
+ * @returns {{ name: string, description: string, tools: string[], model?: string, argumentHint?: string, body: string }}
+ */
+export function composeAgent(root, name, harness, options = {}) {
+  const { dropNullTools = false, pluginRoot, resolveRelativePaths = false, warn = noop } = options;
+  const agentDir = join(root, "agents", name);
+  const frontmatter = parseFrontmatter(join(agentDir, harness, "frontmatter.json"), name, harness);
+  const tokenMap = loadTokenMap(root);
+
+  let body = readFileSync(join(agentDir, "agent.md"), "utf-8");
+
+  // 1. {{SECTION:name}} → <harness>/<name>.md (may itself contain TOOL/PATH tokens)
+  body = body.replace(/\{\{SECTION:([^}]+)\}\}/g, (_token, section) => {
+    const sectionPath = join(agentDir, harness, `${section}.md`);
+    if (!existsSync(sectionPath)) {
+      throw new Error(`agent "${name}": missing section "${section}" for harness "${harness}" (${sectionPath})`);
+    }
+    return readFileSync(sectionPath, "utf-8").trim();
+  });
+
+  // 2. + 3. TOOL/PATH substitution (contextualised for error messages)
+  body = substituteTokens(body, harness, tokenMap, {
+    dropNullTools,
+    pluginRoot,
+    resolveRelativePaths,
+    warn,
+    context: `agent "${name}"`,
+  });
+
+  return { ...frontmatter, body: body.trim() };
+}
+
+// ─── Frontmatter ─────────────────────────────────────────────────────────────
+
+const REQUIRED_FIELDS = ["name", "description", "tools"];
+const KNOWN_OPTIONAL_FIELDS = ["model", "argumentHint"];
+
+/** Parse and schema-check a harness frontmatter.json (strict, per agents/README.md). */
+function parseFrontmatter(path, name, harness) {
+  const raw = readFileSync(path, "utf-8");
+  let fm;
+  try {
+    fm = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`agent "${name}": invalid JSON in ${path}: ${err.message}`);
+  }
+  if (typeof fm !== "object" || fm === null) {
+    throw new Error(`agent "${name}": ${path} must be a JSON object`);
+  }
+  for (const field of REQUIRED_FIELDS) {
+    if (!(field in fm)) throw new Error(`agent "${name}": ${path} missing required field "${field}" (harness ${harness})`);
+  }
+  if (typeof fm.name !== "string" || fm.name.trim() === "") throw new Error(`agent "${name}": ${path} name must be a non-empty string`);
+  if (typeof fm.description !== "string" || fm.description.trim() === "") throw new Error(`agent "${name}": ${path} description must be a non-empty string`);
+  if (!Array.isArray(fm.tools) || fm.tools.length === 0 || !fm.tools.every((t) => typeof t === "string")) {
+    throw new Error(`agent "${name}": ${path} tools must be a non-empty array of strings`);
+  }
+  for (const key of Object.keys(fm)) {
+    if (![...REQUIRED_FIELDS, ...KNOWN_OPTIONAL_FIELDS].includes(key)) {
+      throw new Error(`agent "${name}": ${path} unknown field "${key}" — strict schema per agents/README.md`);
+    }
+  }
+  return {
+    name: fm.name,
+    description: fm.description,
+    tools: fm.tools,
+    ...(typeof fm.model === "string" ? { model: fm.model } : {}),
+    ...(typeof fm.argumentHint === "string" ? { argumentHint: fm.argumentHint } : {}),
+  };
+}
+
+// ─── Path resolution ─────────────────────────────────────────────────────────
+
+/**
+ * Resolve a {{PATH:...}} argument for a harness's generated output.
+ * Named keys resolve through token-map.json's paths table (recursively for
+ * {base, relative} specs); non-keyed args are relative paths, kept verbatim —
+ * the installer beads own precise runtime path resolution (see token-map.README.md).
+ * With the installer options (`pluginRoot`, `resolveRelativePaths`) the
+ * plugin_root base and bare relative paths resolve against the actual install
+ * layout instead.
+ */
+function resolvePath(arg, harness, tokenMap, opts = {}) {
+  const entry = tokenMap.paths?.[arg];
+  if (!entry) {
+    if (opts.resolveRelativePaths && opts.pluginRoot) return join(opts.pluginRoot, arg);
+    return arg;
+  }
+
+  const spec = entry[harness];
+  if (typeof spec === "string") {
+    if (arg === "plugin_root" && opts.pluginRoot) return opts.pluginRoot;
+    return spec;
+  }
+  if (spec && typeof spec === "object" && typeof spec.base === "string" && typeof spec.relative === "string") {
+    return join(resolvePath(spec.base, harness, tokenMap, opts), spec.relative);
+  }
+  throw new Error(`unresolvable {{PATH:${arg}}} for harness "${harness}" — extend token-map.json`);
+}
+
+/**
+ * Translate a frontmatter tool list into one harness's tool names.
+ *
+ * Canonical keys resolve through token-map.json's tools table; a null mapping
+ * means the harness has no equivalent and the entry is omitted (the contract's
+ * tool-list rule); a name that is not a canonical key passes through untouched
+ * (it may be a native tool, e.g. pi's fetch_content). Mirrors the runtime
+ * translation in extensions/agent-modes/discover.ts.
+ *
+ * @param {string[]} tools  Canonical tool names from a harness frontmatter.json
+ * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
+ * @param {string} harness  Harness id: "copilot" | "claude" | "pi"
+ * @param {object} options  { warn }
+ * @returns {string[]}
+ */
+export function translateToolList(tools, tokenMap, harness, { warn = noop } = {}) {
+  const out = [];
+  for (const tool of tools) {
+    const mapping = tokenMap.tools[tool];
+    if (mapping === undefined) {
+      out.push(tool);
+      continue;
+    }
+    const mapped = mapping[harness];
+    if (mapped == null) {
+      warn(`tool "${tool}" has no ${harness} mapping — omitted from the tool list`);
+      continue;
+    }
+    out.push(mapped);
+  }
+  return out;
+}
+
+// ─── Token map ───────────────────────────────────────────────────────────────
+
+/** Load token-map.json from the package root; missing/incomplete maps hard-fail. */
+export function loadTokenMap(root) {
+  const path = join(root, "token-map.json");
+  let raw;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    throw new Error(`missing ${path} — the composer requires token-map.json`);
+  }
+  const parsed = JSON.parse(raw);
+  if (!parsed.tools || !parsed.paths) {
+    throw new Error(`${path}: expected "tools" and "paths" tables`);
+  }
+  return parsed;
+}

package/skills/engineering/design-an-interface/SKILL.md

@@ -1,94 +1,114 @@
 ---
 name: design-an-interface
-description: Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".
+description: "Generate multiple radically different interface designs for a module via parallel sub-agents, then compare and synthesize. Use when designing an API, exploring interface options, or \"design it twice\"."
 ---
 
 # Design an Interface
 
-Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple radically different designs, then compare.
+## When to use
 
-## Workflow
-
-### 1. Gather Requirements
+- The user wants to design an API, module boundary, or public interface.
+- The user asks to explore interface options or compare module shapes.
+- The user mentions "design it twice" or says the first idea is unlikely to be the best.
+- An interface design step needs a guided parallel exploration — `improve-codebase-architecture` invokes this skill for its multi-design step.
 
-Before designing, understand:
+## When NOT to use
 
-- [ ] What problem does this module solve?
-- [ ] Who are the callers? (other modules, external users, tests)
-- [ ] What are the key operations?
-- [ ] Any constraints? (performance, compatibility, existing patterns)
-- [ ] What should be hidden inside vs exposed?
+- The user wants a single justified recommendation with tradeoff analysis — use `technical-direction` instead.
+- The module's shape is already fixed by an upstream contract or framework, so exploring alternatives is wasted effort.
+- The question is about implementation strategy, not interface shape.
 
-Ask: "What does this module need to do? Who will use it?"
+## Philosophy / rationale
 
-### 2. Generate Designs (Parallel Sub-Agents)
+- **Your first idea is unlikely to be the best.** "Design It Twice" (John Ousterhout, *A Philosophy of Software Design*) holds that the first design is almost never the strongest. Generating multiple radically different candidates forces the comparison that finds the best shape.
+- **Contrast, not volume, creates insight.** Similar designs from parallel agents only confirm one idea. Each agent is assigned a different constraint so divergence is guaranteed by construction.
+- **Interface shape is the whole problem here.** The process stops at the interface — implementation effort is irrelevant to the comparison, because a good interface usually makes the implementation easier, not harder. Judging designs by implementation cost rewards shallow modules.
 
-Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a **radically different** approach.
+## Workflow
 
-```
-Prompt template for each sub-agent:
+1. **Gather requirements.** Before designing, pin down:
+   - What problem does the module solve?
+   - Who are the callers (other modules, external users, tests)?
+   - What are the key operations?
+   - What constraints apply (performance, compatibility, existing patterns)?
+   - What should be hidden inside vs exposed?
 
-Design an interface for: [module description]
+   Ask: "What does this module need to do? Who will use it?"
 
-Requirements: [gathered requirements]
+2. **Generate designs with parallel sub-agents.** Spawn 3+ sub-agents simultaneously with {{TOOL:task}}, each assigned a **different** constraint to guarantee radical difference. Use this prompt template per agent:
 
-Constraints for this design: [assign a different constraint to each agent]
-- Agent 1: "Minimize method count - aim for 1-3 methods max"
-- Agent 2: "Maximize flexibility - support many use cases"
-- Agent 3: "Optimize for the most common case"
-- Agent 4: "Take inspiration from [specific paradigm/library]"
+   ```
+   Design an interface for: [module description]
 
-Output format:
-1. Interface signature (types/methods)
-2. Usage example (how caller uses it)
-3. What this design hides internally
-4. Trade-offs of this approach
-```
+   Requirements: [gathered requirements]
 
-### 3. Present Designs
+   Constraints for this design: [assign a different constraint to each agent]
+   - Agent 1: "Minimize method count — aim for 1-3 methods max"
+   - Agent 2: "Maximize flexibility — support many use cases"
+   - Agent 3: "Optimize for the most common case"
+   - Agent 4: "Take inspiration from [specific paradigm/library]"
 
-Show each design with:
+   Output format:
+   1. Interface signature (types/methods)
+   2. Usage example (how a caller uses it)
+   3. What this design hides internally
+   4. Trade-offs of this approach
+   ```
 
-1. **Interface signature** - types, methods, params
-2. **Usage examples** - how callers actually use it in practice
-3. **What it hides** - complexity kept internal
+   Collect each agent's output with {{TOOL:read_agent}} when it finishes.
 
-Present designs sequentially so user can absorb each approach before comparison.
+3. **Present designs.** Show each design sequentially — signature, usage examples, what it hides — so the user absorbs each approach before any comparison happens.
 
-### 4. Compare Designs
+4. **Compare designs.** Compare in prose, not tables, on:
+   - **Interface simplicity** — fewer methods, simpler params
+   - **General-purpose vs specialized** — flexibility vs focus
+   - **Implementation efficiency** — does the shape allow efficient internals?
+   - **Depth** — small interface hiding significant complexity (deep module, good) vs large interface with thin implementation (shallow module, avoid)
+   - **Ease of correct use** vs ease of misuse
 
-After showing all designs, compare them on:
+   Highlight where the designs diverge most — that divergence is where the decision lives.
 
-- **Interface simplicity**: fewer methods, simpler params
-- **General-purpose vs specialized**: flexibility vs focus
-- **Implementation efficiency**: does shape allow efficient internals?
-- **Depth**: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
-- **Ease of correct use** vs **ease of misuse**
+5. **Synthesize.** Ask: "Which design best fits your primary use case?" and "What elements from other designs are worth incorporating?" Often the best design combines insights from multiple options.
 
-Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
+## Red Flags
 
-### 5. Synthesize
+- **Sub-agents converging on similar designs** — if two agents produce near-identical shapes, re-run with sharper, more opposed constraints. Similarity means the contrast step lost its value.
+- **Skipping comparison** — jumping from presentation to a favorite design discards the whole point of exploring alternatives.
+- **Sliding into implementation** — this process concerns interface shape only. Implementation details belong in a follow-up task.
+- **Judging designs by implementation effort** — a design that looks harder to build may still be the deeper, better interface.
 
-Often the best design combines insights from multiple options. Ask:
+## Common Rationalizations
 
-- "Which design best fits your primary use case?"
-- "Any elements from other designs worth incorporating?"
+| Rationalization | Rebuttal |
+|---|---|
+| "My first design is probably fine" | That is exactly the assumption "design it twice" exists to break. Generate the alternatives before committing. |
+| "The agents will just produce similar things, so why bother" | Similarity is a failure mode you control — assign opposed constraints so divergence is guaranteed by construction. |
+| "I can compare these myself, no need to present each one" | Sequential presentation forces you to articulate what each design actually is before judging it, which is where the insight comes from. |
 
-## Evaluation Criteria
+## Phase-gate checklists
 
-From "A Philosophy of Software Design":
+- [ ] Phase 1 complete: requirements gathered and constraints listed
+- [ ] Phase 2 complete: 3+ designs returned, each constrained differently
+- [ ] Phase 3 complete: all designs presented sequentially
+- [ ] Phase 4 complete: comparison shared and divergence highlighted
+- [ ] Phase 5 complete: candidate synthesized with user input
 
-**Interface simplicity**: Fewer methods, simpler params = easier to learn and use correctly.
+## Cross-skill references
 
-**General-purpose**: Can handle future use cases without changes. But beware over-generalization.
+- `improve-codebase-architecture` invokes this skill for its multi-design step (step 5 of its workflow).
+- Run `grill-with-docs` when the module's domain terminology is unsettled — design names should match the ubiquitous language.
 
-**Implementation efficiency**: Does interface shape allow efficient implementation? Or force awkward internals?
+## Examples
 
-**Depth**: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
+Input: "Design the interface for a rate limiter module"
+Output: four radically different interface sketches (minimal-method, flexible, common-case-optimized, paradigm-inspired), presented sequentially, compared on simplicity, depth, and trade-offs, then synthesized into one recommended shape with the user.
 
-## Anti-Patterns
+## Verification checklist
 
-- Don't let sub-agents produce similar designs - enforce radical difference
-- Don't skip comparison - the value is in contrast
-- Don't implement - this is purely about interface shape
-- Don't evaluate based on implementation effort
+- [ ] Requirements captured before any sub-agent is spawned
+- [ ] At least 3 sub-agents spawned, each with a distinct constraint
+- [ ] Each design reports signature, usage example, hidden complexity, and trade-offs
+- [ ] Designs presented sequentially before any comparison
+- [ ] Comparison covers simplicity, generality, efficiency, depth, and ease of correct use
+- [ ] Synthesis asks the user which design fits their primary use case
+- [ ] No implementation work performed — interface shape only

package/skills/engineering/grill-with-docs/REFERENCE.md

@@ -0,0 +1,78 @@
+# Grill-with-docs reference
+
+Rarely-needed detail the workflow points to when you must create or update project documents.
+
+## Finding the domain model
+
+### Single-context repos
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+### Multi-context repos
+
+A `CONTEXT-MAP.md` at the root points to where each context 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 resolves. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## CONTEXT.md entry format
+
+One `# term` heading per entry with a plain-prose definition and cross-links to related terms:
+
+```md
+# cancellation
+An order may be cancelled only before fulfilment begins. See refund for the
+post-fulfilment reversal path.
+```
+
+Rules:
+
+- Glossary only — no implementation details, no specs, no scratch notes.
+- Prefer one concise definition over long paragraphs.
+- Cross-link related terms so the vocabulary is navigable.
+
+## ADR format
+
+One file per decision in `docs/adr/`, zero-padded sequence number plus kebab-case title:
+
+```
+0003-cancel-before-fulfilment-only.md
+```
+
+Structure:
+
+```md
+# Title
+
+## Context
+What problem forced the decision and why the question arose.
+
+## Decision
+The choice, stated precisely.
+
+## Consequences
+What becomes easier or harder as a result; what a future reader must know.
+```
+
+Offer an ADR only when all three hold — hard to reverse, surprising without context, real trade-off. If any is missing, skip it.