@jaybeeuu/agent-cortex 1.20.0

package/extensions/subagent/prompts/implement-and-review.md

@@ -0,0 +1,10 @@
+---
+description: Worker implements, reviewer reviews, worker applies feedback
+---
+Use the subagent tool with the chain parameter to execute this workflow:
+
+1. First, use the "worker" agent to implement: $@
+2. Then, use the "reviewer" agent to review the implementation from the previous step (use {previous} placeholder)
+3. Finally, use the "worker" agent to apply the feedback from the review (use {previous} placeholder)
+
+Execute this as a chain, passing output between steps via {previous}.

package/extensions/subagent/prompts/implement.md

@@ -0,0 +1,10 @@
+---
+description: Full implementation workflow - scout gathers context, planner creates plan, worker implements
+---
+Use the subagent tool with the chain parameter to execute this workflow:
+
+1. First, use the "scout" agent to find all code relevant to: $@
+2. Then, use the "planner" agent to create an implementation plan for "$@" using the context from the previous step (use {previous} placeholder)
+3. Finally, use the "worker" agent to implement the plan from the previous step (use {previous} placeholder)
+
+Execute this as a chain, passing output between steps via {previous}.

package/extensions/subagent/prompts/scout-and-plan.md

@@ -0,0 +1,9 @@
+---
+description: Scout gathers context, planner creates implementation plan (no implementation)
+---
+Use the subagent tool with the chain parameter to execute this workflow:
+
+1. First, use the "scout" agent to find all code relevant to: $@
+2. Then, use the "planner" agent to create an implementation plan for "$@" using the context from the previous step (use {previous} placeholder)
+
+Execute this as a chain, passing output between steps via {previous}. Do NOT implement - just return the plan.

package/hooks.json

@@ -0,0 +1,10 @@
+{
+  "hooks": {
+    "sessionStart": [
+      {
+        "type": "prompt",
+        "prompt": "Load AGENTS.md and active beads context before taking action."
+      }
+    ]
+  }
+}

package/lib/cli.mjs

@@ -0,0 +1,37 @@
+const SUPPORTED_HARNESSES = ["copilot", "claude", "pi"];
+
+export function parseArgs(argv) {
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    return { command: "help" };
+  }
+
+  const [command, ...rest] = argv;
+
+  if (command === "install") {
+    const harness = rest[0] ?? null;
+    return { command: "install", harness };
+  }
+
+  return { command: "unknown", name: command };
+}
+
+export function buildHelpText() {
+  return `Usage: agent-cortex <command> [options]
+
+Commands:
+  install <harness>   Install agent-cortex for a harness
+                      Supported harnesses: ${SUPPORTED_HARNESSES.join(", ")}
+  --help, -h          Show this help text`;
+}
+
+export function validateHarness(harness) {
+  if (harness === null) {
+    return { ok: false, error: "Missing harness argument. Supported harnesses: copilot, claude, pi" };
+  }
+  if (!SUPPORTED_HARNESSES.includes(harness)) {
+    return { ok: false, error: `Unknown harness "${harness}". Supported harnesses: ${SUPPORTED_HARNESSES.join(", ")}` };
+  }
+  return { ok: true };
+}
+
+export { SUPPORTED_HARNESSES };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@jaybeeuu/agent-cortex",
+  "version": "1.20.0",
+  "description": "Personal PI package with custom agents, skills, and extensions",
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jaybeeuu/agent-cortex"
+  },
+  "bin": {
+    "agent-cortex": "./bin/agent-cortex.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "yaml": "^2.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "build": "echo 'Build complete — no compilation needed for PI package'",
+    "lint": "pnpm typecheck",
+    "test": "pnpm -r test",
+    "typecheck": "pnpm -r typecheck",
+    "build:claude": "node scripts/build-claude-agents.mjs",
+    "postinstall": "bash scripts/install-instructions.sh"
+  }
+}

package/pi/keybindings.json

@@ -0,0 +1,3 @@
+{
+  "tui.input.newLine": ["shift+enter", "ctrl+enter"]
+}

package/pi/settings.json

@@ -0,0 +1,29 @@
+{
+  "tinyModel": {
+    "model": "opencode/mimo-v2.5-free",
+    "maxNameLength": 40,
+    "maxSummaryLength": 100
+  },
+  "lastChangelogVersion": "0.83.0",
+  "packages": [
+    "../../src/agent-cortex",
+    "npm:pi-web-access@0.10.7",
+    "npm:@getpipher/vision",
+    "npm:@hypabolic/pi-hypa",
+    "npm:context-mode"
+  ],
+  "defaultProvider": "opencode-go",
+  "defaultModel": "qwen3.7-max",
+  "theme": "dark",
+  "defaultThinkingLevel": "high",
+  "enabledModels": [
+    "opencode/nemotron-3-ultra-free",
+    "opencode-go/qwen3.7-max",
+    "opencode/kimi-k2.7-code",
+    "opencode/mimo-v2.5-free",
+    "opencode-go/mimo-v2.5",
+    "opencode/deepseek-v4-flash-free",
+    "opencode-go/deepseek-v4-flash",
+    "opencode/big-pickle"
+  ]
+}

package/plugin.json

@@ -0,0 +1,35 @@
+{
+  "name": "agent-cortex",
+  "description": "Personal Copilot CLI plugin with custom agents and skills",
+  "version": "1.36.0",
+  "author": {
+    "name": "jaybeeuu"
+  },
+  "license": "MIT",
+  "repository": "https://github.com/jaybeeuu/agent-cortex",
+  "bin": "bin/agent-cortex.mjs",
+  "agents": "agents/",
+  "skills": "skills/",
+  "mcpServers": {
+    "context7": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp@latest"
+      ]
+    },
+    "github": {
+      "type": "stdio",
+      "command": "pnpm",
+      "args": [
+        "dlx",
+        "@modelcontextprotocol/server-github"
+      ],
+      "tools": [
+        "*"
+      ]
+    }
+  },
+  "hooks": "hooks.json"
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+packages:
+  - "skills/*/scripts"
+  - "extensions/*"
+allowBuilds:
+  '@google/genai': false
+  esbuild: false
+  protobufjs: false

package/scripts/build-claude-agents.mjs

@@ -0,0 +1,179 @@
+// Builds the self-contained Claude Code plugin subtree at claude/ from the canonical
+// Copilot sources. The Copilot files (agents/*.agent.md) and the grouped skills/ tree
+// stay the single source of truth; the claude/ subtree is generated and committed.
+// CI runs this and checks `git diff --exit-code claude/` to guarantee it is never stale.
+//
+//   claude/agents/*.md   generated from agents/*.agent.md (frontmatter + tools converted)
+//   claude/skills/<name> symlinks to the grouped skills/<group>/<name> dirs (single source)
+//
+// Claude only loads agents from the default ./agents/ dir of the plugin root (custom
+// `agents` manifest paths are ignored), so the plugin root is claude/ — isolating it
+// from the Copilot .agent.md files, which would otherwise load as broken agents.
+//
+// Run: pnpm build:claude   (node scripts/build-claude-agents.mjs)
+// Zero dependencies so it runs on the CI Node (20) and local Node alike.
+
+import { readdirSync, readFileSync, writeFileSync, mkdirSync, rmSync, symlinkSync, statSync, copyFileSync, existsSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const AGENT_SRC = join(ROOT, "agents");
+const NATIVE_SRC = join(ROOT, "agents-native");
+const SKILL_SRC = join(ROOT, "skills");
+const AGENT_OUT = join(ROOT, "claude", "agents");
+const SKILL_OUT = join(ROOT, "claude", "skills");
+
+// Copilot tool name -> Claude tool name. `null` = drop (no Claude equivalent).
+const TOOL_MAP = {
+  bash: "Bash",
+  view: "Read",
+  edit: "Edit",
+  create: "Write",
+  grep: "Grep",
+  rg: "Grep",
+  glob: "Glob",
+  ask_user: "AskUserQuestion",
+  web_fetch: "WebFetch",
+  skill: "Skill",
+  task: "Task",
+  read_agent: null, // Claude's Task returns results inline; no separate read step.
+};
+
+// Agents NOT transformed from the Copilot source. `ralph` is authored natively for Claude
+// instead (agents-native/ralph.md) — its event-driven orchestration can't be produced by
+// token substitution from the poll-loop Copilot source.
+const DEFER = new Set(["ralph"]);
+
+// Ralph-coupled Copilot skills that don't apply to the lean Claude Ralph (and carry dead
+// ~/.copilot orchestration paths). Not symlinked into the Claude plugin.
+const SKILL_EXCLUDE = new Set(["ralph", "run-pipeline-stage"]);
+
+const COPILOT_PLUGIN_ROOT = "~/.copilot/installed-plugins/_direct/agent-cortex";
+const CLAUDE_PLUGIN_ROOT = "${CLAUDE_PLUGIN_ROOT}";
+const NAME_PREFIX = "agent-cortex:";
+
+function parseFrontmatter(text, file) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!m) throw new Error(`${file}: no YAML frontmatter found`);
+  return { fm: m[1], body: text.slice(m[0].length) };
+}
+
+function scalarLine(fm, key) {
+  const m = fm.match(new RegExp(`^${key}:[ \\t]*(.+?)[ \\t]*$`, "m"));
+  return m ? m[1] : undefined;
+}
+
+function stripQuotes(s) {
+  return s === undefined ? undefined : s.replace(/^["']([\s\S]*)["']$/, "$1");
+}
+
+function mapTools(fm, file) {
+  const raw = scalarLine(fm, "tools");
+  if (!raw) throw new Error(`${file}: no tools field`);
+  let list;
+  try {
+    list = JSON.parse(raw);
+  } catch {
+    throw new Error(`${file}: tools is not a JSON array: ${raw}`);
+  }
+  const out = [];
+  for (const t of list) {
+    if (!(t in TOOL_MAP)) throw new Error(`${file}: unknown tool "${t}" — extend TOOL_MAP`);
+    const mapped = TOOL_MAP[t];
+    if (mapped && !out.includes(mapped)) out.push(mapped);
+  }
+  return out;
+}
+
+// Rewrite harness-specific tokens in the prose body: exact backticked tool names and
+// the hardcoded Copilot plugin path. Only touches `\`token\`` so shell snippets like
+// `bd create` inside code fences are untouched.
+function transformBody(body) {
+  let out = body;
+  for (const [copilot, claude] of Object.entries(TOOL_MAP)) {
+    if (claude) out = out.split("`" + copilot + "`").join("`" + claude + "`");
+  }
+  return out.split(COPILOT_PLUGIN_ROOT).join(CLAUDE_PLUGIN_ROOT);
+}
+
+function buildAgents() {
+  rmSync(AGENT_OUT, { recursive: true, force: true });
+  mkdirSync(AGENT_OUT, { recursive: true });
+
+  const written = [];
+  const skipped = [];
+  for (const file of readdirSync(AGENT_SRC).filter((f) => f.endsWith(".agent.md")).sort()) {
+    const { fm, body } = parseFrontmatter(readFileSync(join(AGENT_SRC, file), "utf8"), file);
+
+    const rawName = stripQuotes(scalarLine(fm, "name"));
+    if (!rawName) throw new Error(`${file}: no name field`);
+    const slug = rawName.startsWith(NAME_PREFIX) ? rawName.slice(NAME_PREFIX.length) : rawName;
+    if (DEFER.has(slug)) {
+      skipped.push(slug);
+      continue;
+    }
+
+    const description = scalarLine(fm, "description");
+    if (!description) throw new Error(`${file}: no description field`);
+
+    const header =
+      `---\n` +
+      `# GENERATED from agents/${file} by scripts/build-claude-agents.mjs — DO NOT EDIT.\n` +
+      `name: ${slug}\n` +
+      `description: ${description}\n` +
+      `tools: ${mapTools(fm, file).join(", ")}\n` +
+      `---\n`;
+    const out = `${header}\n${transformBody(body).replace(/^\r?\n+/, "").replace(/\s*$/, "")}\n`;
+    writeFileSync(join(AGENT_OUT, `${slug}.md`), out);
+    written.push(slug);
+  }
+  console.log(`Generated ${written.length} Claude agent(s): ${written.join(", ")}`);
+  if (skipped.length) console.log(`Skipped Copilot source(s): ${skipped.join(", ")}`);
+}
+
+// Copy hand-authored Claude-native agents into claude/agents/ verbatim, alongside the
+// generated ones. These have no Copilot source (their bodies differ structurally per harness).
+function copyNativeAgents() {
+  if (!existsSync(NATIVE_SRC)) return;
+  const copied = [];
+  for (const file of readdirSync(NATIVE_SRC).filter((f) => f.endsWith(".md")).sort()) {
+    copyFileSync(join(NATIVE_SRC, file), join(AGENT_OUT, file));
+    copied.push(file.replace(/\.md$/, ""));
+  }
+  if (copied.length) console.log(`Copied ${copied.length} native Claude agent(s): ${copied.join(", ")}`);
+}
+
+// Symlink each grouped skill (skills/<group>/<name>/) into the flat claude/skills/ dir
+// so Claude's one-level-deep skill scan discovers them without duplicating content.
+function buildSkills() {
+  rmSync(SKILL_OUT, { recursive: true, force: true });
+  mkdirSync(SKILL_OUT, { recursive: true });
+
+  const byName = new Map();
+  for (const group of readdirSync(SKILL_SRC).sort()) {
+    const groupDir = join(SKILL_SRC, group);
+    if (!statSync(groupDir).isDirectory()) continue;
+    for (const name of readdirSync(groupDir).sort()) {
+      const skillDir = join(groupDir, name);
+      let hasSkill;
+      try {
+        hasSkill = statSync(join(skillDir, "SKILL.md")).isFile();
+      } catch {
+        hasSkill = false;
+      }
+      if (!hasSkill) continue;
+      if (SKILL_EXCLUDE.has(name)) continue;
+      if (byName.has(name)) {
+        throw new Error(`duplicate skill name "${name}" (${byName.get(name)} and ${group}) — names must be unique when flattened`);
+      }
+      byName.set(name, group);
+      symlinkSync(relative(SKILL_OUT, skillDir), join(SKILL_OUT, name));
+    }
+  }
+  console.log(`Linked ${byName.size} skill(s) into claude/skills/`);
+}
+
+buildAgents();
+copyNativeAgents();
+buildSkills();

package/scripts/install-instructions.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Installs ~/.copilot/copilot-instructions.md with proactive skill directives.
+# Run after cloning this plugin: pnpm install (or bash scripts/install-instructions.sh)
+# Safe to re-run — replaces the agent-cortex section only.
+
+set -euo pipefail
+
+INSTRUCTIONS_FILE="$HOME/.copilot/copilot-instructions.md"
+MARKER_START="<!-- agent-cortex:start -->"
+MARKER_END="<!-- agent-cortex:end -->"
+
+BLOCK="$MARKER_START
+<!-- This block is managed by agent-cortex. Manual edits inside will be overwritten. -->
+
+## Proactive skill use (agent-cortex plugin)
+
+You have a set of custom skills available. Apply them automatically whenever they are relevant — the user should not have to invoke them by name.
+
+### Code & tests
+
+- Apply **style-code** whenever writing, editing, or reviewing code. It defines naming, module boundaries, and architectural conventions.
+- Apply **style-tests** whenever writing, editing, or reviewing tests. It defines assertion strategy, mock discipline, and what to test.
+- Apply **style-comms** whenever writing external-facing communication: tickets, RFCs, PRDs, proposals, or reports.
+- Apply **style-documentation** whenever deciding what to document or reviewing existing docs.
+- Use **tdd** (red-green-refactor loop) whenever building a new feature or fixing a bug where correctness matters.
+- Run **review-security** before committing any changes that touch secrets, auth, or credentials.
+
+### Planning & design
+
+- Use **write-a-prd** when the user wants to plan a new feature or product requirement.
+- Use **prd-to-tasks** after a PRD is approved to break it into phased epics and task beads.
+- Use **create-task** when creating a new trackable task bead.
+- Use **record-idea** when the user shares an early-stage idea that is not yet ready to implement.
+- Use **request-refactor-plan** when the user wants to plan a refactor with safe incremental commits.
+- Use **write-a-ticket** when writing a ticket for an external issue tracker (e.g. Jira).
+- Use **design-an-interface** when the user wants to explore multiple API or module designs.
+- Use **technical-direction** when evaluating architecture or technology choices with tradeoff analysis.
+- Use **grill-me** or **grill-with-docs** when the user wants to stress-test a plan or design.
+- Use **improve-codebase-architecture** when the user wants to find architectural improvement opportunities.
+
+### Task execution
+
+- Use **bd-tool** whenever the user mentions beads, bd, tasks, or asks what work is available.
+- Use **ralph** to run all pending beads end-to-end with review gates.
+- Use **run-pipeline-stage** to work through individual pipeline stages inline.
+- Use **hitl-collab** when a task requires human review, manual steps, or a PR handoff.
+- Use **classify-bead** when a bead is missing its implementation-type label.
+
+### Repo & plugin maintenance
+
+- Use **maintain-agent-docs** when reviewing or updating AGENTS.md or agent-consumed docs.
+- Use **refactor-skill** when restructuring or reviewing an existing skill.
+- Use **write-a-skill** when creating a new skill.
+- Use **init-beads** when setting up the bd task-tracker in a new project.
+
+$MARKER_END"
+
+mkdir -p "$(dirname "$INSTRUCTIONS_FILE")"
+
+if [ ! -f "$INSTRUCTIONS_FILE" ]; then
+  printf '%s\n' "$BLOCK" > "$INSTRUCTIONS_FILE"
+  echo "✓ Created $INSTRUCTIONS_FILE"
+elif grep -qF "$MARKER_START" "$INSTRUCTIONS_FILE"; then
+  # Write replacement block to a temp file so awk can read it with getline
+  BLOCK_FILE=$(mktemp)
+  printf '%s\n' "$BLOCK" > "$BLOCK_FILE"
+  awk -v start="$MARKER_START" -v end="$MARKER_END" -v blockfile="$BLOCK_FILE" '
+    $0 == start {
+      while ((getline line < blockfile) > 0) print line
+      close(blockfile)
+      skip=1; next
+    }
+    $0 == end { skip=0; next }
+    !skip     { print }
+  ' "$INSTRUCTIONS_FILE" > "${INSTRUCTIONS_FILE}.tmp"
+  mv "${INSTRUCTIONS_FILE}.tmp" "$INSTRUCTIONS_FILE"
+  rm -f "$BLOCK_FILE"
+  echo "✓ Updated agent-cortex section in $INSTRUCTIONS_FILE"
+else
+  printf '\n%s\n' "$BLOCK" >> "$INSTRUCTIONS_FILE"
+  echo "✓ Appended agent-cortex section to $INSTRUCTIONS_FILE"
+fi

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

@@ -0,0 +1,94 @@
+---
+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".
+---
+
+# 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.
+
+## Workflow
+
+### 1. Gather Requirements
+
+Before designing, understand:
+
+- [ ] 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?
+
+Ask: "What does this module need to do? Who will use it?"
+
+### 2. Generate Designs (Parallel Sub-Agents)
+
+Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a **radically different** approach.
+
+```
+Prompt template for each sub-agent:
+
+Design an interface for: [module description]
+
+Requirements: [gathered requirements]
+
+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]"
+
+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
+```
+
+### 3. Present Designs
+
+Show each design with:
+
+1. **Interface signature** - types, methods, params
+2. **Usage examples** - how callers actually use it in practice
+3. **What it hides** - complexity kept internal
+
+Present designs sequentially so user can absorb each approach before comparison.
+
+### 4. Compare Designs
+
+After showing all designs, compare them on:
+
+- **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**
+
+Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
+
+### 5. Synthesize
+
+Often the best design combines insights from multiple options. Ask:
+
+- "Which design best fits your primary use case?"
+- "Any elements from other designs worth incorporating?"
+
+## Evaluation Criteria
+
+From "A Philosophy of Software Design":
+
+**Interface simplicity**: Fewer methods, simpler params = easier to learn and use correctly.
+
+**General-purpose**: Can handle future use cases without changes. But beware over-generalization.
+
+**Implementation efficiency**: Does interface shape allow efficient implementation? Or force awkward internals?
+
+**Depth**: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
+
+## Anti-Patterns
+
+- 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

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

@@ -0,0 +1,88 @@
+---
+name: grill-with-docs
+description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
+---
+
+<what-to-do>
+
+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, waiting for feedback on each question before continuing.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+</what-to-do>
+
+<supporting-info>
+
+## Domain awareness
+
+During codebase exploration, also look for existing documentation:
+
+### 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).
+
+</supporting-info>