@ai-agent-lead/skills 1.0.0

package/README.md

@@ -0,0 +1,37 @@
+# Skills
+
+A library of Claude Code skills that encode engineering discipline so Claude follows it by default.
+
+## Why
+
+Out of the box Claude writes code competently, but shipping well needs more than that: investigate before building, design the interface before writing, test-first, review at PR boundaries, and verify before merge.
+
+These skills bake those habits into Claude's defaults. Each one fires on its own trigger phrases — `tdd` when a task starts with a feature, `prod-ready` before merge, `pr-review` on someone else's PR, and so on — instead of waiting for me to remember to ask.
+
+The goal: turn engineering discipline from something I have to enforce into something Claude reaches for automatically.
+
+## Where things live
+
+- [`skills/`](./skills/) — the skill set. See [`skills/README.md`](./skills/README.md) for the index, the role/trigger taxonomy, and how skills compose into workflows.
+
+## Installation
+
+You can install all the skills in this repository directly using `npx`:
+
+```bash
+npx github:ai-agent-lead/skills
+```
+
+### Options and Customization
+
+By default, the installer runs in an interactive console wizard allowing you to select your targets. You can also specify flags to customize the installation target and scope:
+
+- `--global`, `-g`       Install to personal/user-level global directories (e.g. `~/.claude/skills`)
+- `--local`, `-l`        Install to current project/workspace directories (e.g. `./.claude/skills`)
+- `--claude`            Install skills only for Claude Code
+- `--codex`             Install skills only for Codex
+- `--antigravity`, `-agy` Install skills only for Antigravity
+- `--all`               Install skills for all supported assistants (default)
+- `--force`, `-f`         Overwrite files without confirmation
+- `--help`, `-h`          Show the help menu with all options
+

package/bin/install.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+import readline from 'readline';
+
+// --- ANSI Colors ---
+const ESC = '\x1b[';
+const RESET = `${ESC}0m`;
+const BOLD = `${ESC}1m`;
+const GRAY = `${ESC}90m`;
+const RED = `${ESC}31m`;
+const GREEN = `${ESC}32m`;
+const YELLOW = `${ESC}33m`;
+const BLUE = `${ESC}34m`;
+const MAGENTA = `${ESC}35m`;
+const CYAN = `${ESC}36m`;
+const WHITE = `${ESC}37m`;
+
+const BRAND_COLOR = `${BOLD}${CYAN}`;
+const SUCCESS_COLOR = `${BOLD}${GREEN}`;
+const INFO_COLOR = `${CYAN}`;
+
+// Get current filename and directory in ESM
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SOURCE_SKILLS_DIR = path.resolve(__dirname, '../skills');
+
+// --- Helper Functions ---
+function printBanner() {
+  console.log(`
+${BRAND_COLOR}   _    ___     _     ___  ___  _  _  _____   _     ___   _    ___
+  /_\\  |_ _|   /_\\   / __|| __|| \\| ||_   _| | |   | __| /_\\  |   \\
+ / _ \\  | |   / _ \\ | (_ || _| | .\` |  | |   | |__ | _| / _ \\ | |) |
+/_/ \\_\\|___| /_/ \\_\\ \\___||___||_|\\_|  |_|   |____||___/_/ \\_\\|___/
+${RESET}
+${BOLD}${WHITE}              S K I L L S   I N S T A L L E R${RESET}
+${GRAY}-------------------------------------------------------------${RESET}
+`);
+}
+
+function printHelp() {
+  printBanner();
+  console.log(`${BOLD}Usage:${RESET}`);
+  console.log(`  npx github:ai-agent-lead/skills [options]`);
+  console.log(``);
+  console.log(`${BOLD}Options:${RESET}`);
+  console.log(`  ${CYAN}--global, -g${RESET}       Install to global directories (e.g. ~/.claude/skills)`);
+  console.log(`  ${CYAN}--local, -l${RESET}        Install to local project directories (e.g. ./.claude/skills)`);
+  console.log(`  ${CYAN}--claude${RESET}            Install skills only for Claude Code`);
+  console.log(`  ${CYAN}--codex${RESET}             Install skills only for Codex`);
+  console.log(`  ${CYAN}--antigravity, -agy${RESET} Install skills only for Antigravity`);
+  console.log(`  ${CYAN}--all${RESET}               Install skills for all supported assistants (default)`);
+  console.log(`  ${CYAN}--force, -f${RESET}         Overwrite files without confirmation`);
+  console.log(`  ${CYAN}--help, -h${RESET}          Show this help menu`);
+  console.log(``);
+  console.log(`${BOLD}Examples:${RESET}`);
+  console.log(`  npx github:ai-agent-lead/skills --global`);
+  console.log(`  npx github:ai-agent-lead/skills --local --claude`);
+  console.log(``);
+}
+
+function askQuestion(query) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise(resolve => rl.question(query, answer => {
+    rl.close();
+    resolve(answer.trim());
+  }));
+}
+
+function copyFolderSync(from, to, { force = false } = {}, stats = { copied: 0, skipped: 0 }) {
+  if (!fs.existsSync(from)) return stats;
+  fs.mkdirSync(to, { recursive: true });
+  const elements = fs.readdirSync(from);
+  for (const element of elements) {
+    const fromPath = path.join(from, element);
+    const toPath = path.join(to, element);
+    const stat = fs.lstatSync(fromPath);
+    if (stat.isDirectory()) {
+      copyFolderSync(fromPath, toPath, { force }, stats);
+    } else if (stat.isFile()) {
+      if (!force && fs.existsSync(toPath)) {
+        stats.skipped++;
+        continue;
+      }
+      fs.copyFileSync(fromPath, toPath);
+      stats.copied++;
+    }
+  }
+  return stats;
+}
+
+// --- Main Execution ---
+async function run() {
+  const args = process.argv.slice(2);
+  
+  const flags = {
+    global: false,
+    local: false,
+    claude: false,
+    codex: false,
+    antigravity: false,
+    all: false,
+    force: false,
+    help: false
+  };
+
+  for (const arg of args) {
+    if (arg === '--global' || arg === '-g') flags.global = true;
+    else if (arg === '--local' || arg === '-l') flags.local = true;
+    else if (arg === '--claude') flags.claude = true;
+    else if (arg === '--codex') flags.codex = true;
+    else if (arg === '--antigravity' || arg === '--agy' || arg === '-agy') flags.antigravity = true;
+    else if (arg === '--all') flags.all = true;
+    else if (arg === '--force' || arg === '-f') flags.force = true;
+    else if (arg === '--help' || arg === '-h') flags.help = true;
+  }
+
+  if (flags.help) {
+    printHelp();
+    return;
+  }
+
+  // Check if source skills folder exists in the package
+  if (!fs.existsSync(SOURCE_SKILLS_DIR)) {
+    console.error(`${RED}✗ Error: Source skills folder not found at: ${SOURCE_SKILLS_DIR}${RESET}`);
+    process.exit(1);
+  }
+
+  // Interactive Mode
+  if (args.length === 0 && process.stdout.isTTY) {
+    printBanner();
+    console.log(`${INFO_COLOR}No options provided. Running interactive setup...${RESET}\n`);
+    
+    console.log(`${BOLD}1. Select Scope:${RESET}`);
+    console.log(`   [1] Global (Personal / User-level) - ${GRAY}Available in all projects${RESET}`);
+    console.log(`   [2] Local (Project / Workspace-specific) - ${GRAY}Available in current folder${RESET}`);
+    console.log(`   [3] Both Scope Options`);
+    const scopeAns = await askQuestion(`${BOLD}${CYAN}? Choose scope [1-3] (Default: 1): ${RESET}`);
+    
+    if (scopeAns === '2') {
+      flags.local = true;
+    } else if (scopeAns === '3') {
+      flags.global = true;
+      flags.local = true;
+    } else {
+      flags.global = true;
+    }
+    console.log(``);
+
+    console.log(`${BOLD}2. Select Targets:${RESET}`);
+    console.log(`   [1] All Assistants (Claude, Codex, Antigravity)`);
+    console.log(`   [2] Claude Code only`);
+    console.log(`   [3] Codex only`);
+    console.log(`   [4] Antigravity only`);
+    const targetAns = await askQuestion(`${BOLD}${CYAN}? Choose target [1-4] (Default: 1): ${RESET}`);
+    
+    if (targetAns === '2') {
+      flags.claude = true;
+    } else if (targetAns === '3') {
+      flags.codex = true;
+    } else if (targetAns === '4') {
+      flags.antigravity = true;
+    } else {
+      flags.claude = true;
+      flags.codex = true;
+      flags.antigravity = true;
+    }
+    console.log(``);
+  } else {
+    // If not interactive and no flags specified, apply defaults
+    const hasScopeFlag = flags.global || flags.local;
+    if (!hasScopeFlag) {
+      flags.global = true; // Default to global
+    }
+
+    const hasAssistantFlag = flags.claude || flags.codex || flags.antigravity;
+    if (!hasAssistantFlag) {
+      flags.claude = true;
+      flags.codex = true;
+      flags.antigravity = true;
+    }
+  }
+
+  // Setup Paths
+  const home = os.homedir();
+  const cwd = process.cwd();
+
+  const destinations = [];
+
+  if (flags.global) {
+    if (flags.claude) {
+      destinations.push({ name: 'Claude Code (Global)', path: path.join(home, '.claude', 'skills') });
+    }
+    if (flags.codex) {
+      destinations.push({ name: 'Codex (Global)', path: path.join(home, '.codex', 'skills') });
+    }
+    if (flags.antigravity) {
+      destinations.push({ name: 'Antigravity (Global)', path: path.join(home, '.gemini', 'antigravity', 'skills') });
+      destinations.push({ name: 'Antigravity CLI (Global)', path: path.join(home, '.gemini', 'antigravity-cli', 'skills') });
+      destinations.push({ name: 'Antigravity Config (Global)', path: path.join(home, '.gemini', 'config', 'skills') });
+    }
+  }
+
+  if (flags.local) {
+    if (flags.claude) {
+      destinations.push({ name: 'Claude Code (Local)', path: path.join(cwd, '.claude', 'skills') });
+    }
+    if (flags.codex) {
+      destinations.push({ name: 'Codex (Local)', path: path.join(cwd, '.codex', 'skills') });
+    }
+    if (flags.antigravity) {
+      destinations.push({ name: 'Antigravity Agents (Local)', path: path.join(cwd, '.agents', 'skills') });
+      destinations.push({ name: 'Antigravity Agent (Local)', path: path.join(cwd, '.agent', 'skills') });
+      destinations.push({ name: 'Antigravity CLI (Local)', path: path.join(cwd, '.antigravitycli', 'skills') });
+    }
+  }
+
+  if (destinations.length === 0) {
+    console.log(`${YELLOW}⚠ No destinations matching current selection.${RESET}`);
+    return;
+  }
+
+  if (args.length !== 0 || !process.stdout.isTTY) {
+    printBanner();
+  }
+
+  console.log(`${BOLD}Starting installation to destinations...${RESET}`);
+  console.log(`${GRAY}---------------------------------------------${RESET}`);
+
+  let successCount = 0;
+  for (const dest of destinations) {
+    console.log(`${INFO_COLOR}➜ Installing to ${BOLD}${dest.name}${RESET}${GRAY}...${RESET}`);
+    try {
+      // Resolve absolute paths nicely for output display
+      const displayPath = dest.path.replace(home, '~');
+      console.log(`  ${GRAY}Path: ${displayPath}${RESET}`);
+      
+      // Perform directory copy
+      const result = copyFolderSync(SOURCE_SKILLS_DIR, dest.path, { force: flags.force });
+
+      const summary = result.skipped > 0
+        ? ` (${result.copied} copied, ${result.skipped} skipped — use --force to overwrite)`
+        : ` (${result.copied} files)`;
+      console.log(`  ${SUCCESS_COLOR}✔ Successfully installed to ${dest.name}!${RESET}${GRAY}${summary}${RESET}`);
+      successCount++;
+    } catch (err) {
+      console.error(`  ${RED}✗ Failed to install to ${dest.name}: ${err.message}${RESET}`);
+    }
+    console.log(``);
+  }
+
+  console.log(`${GRAY}---------------------------------------------${RESET}`);
+  if (successCount === destinations.length) {
+    console.log(`${SUCCESS_COLOR}🎉 Installation complete! All (${successCount}/${destinations.length}) targets successfully updated.${RESET}`);
+  } else if (successCount > 0) {
+    console.log(`${YELLOW}⚠ Installation completed with warnings. Installed ${successCount} of ${destinations.length} targets.${RESET}`);
+  } else {
+    console.error(`${RED}✗ Installation failed. No targets were updated.${RESET}`);
+    process.exit(1);
+  }
+}
+
+run().catch(err => {
+  console.error(`${RED}✗ Unexpected Error: ${err.message}${RESET}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@ai-agent-lead/skills",
+  "version": "1.0.0",
+  "description": "Install AI agent skills for Claude Code, Codex, and Antigravity",
+  "main": "bin/install.js",
+  "bin": {
+    "install-skills": "bin/install.js"
+  },
+  "type": "module",
+  "files": [
+    "bin/",
+    "skills/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ai-agent-lead/skills.git"
+  },
+  "keywords": [
+    "claude",
+    "codex",
+    "antigravity",
+    "skills",
+    "ai-agent"
+  ],
+  "author": "ai-agent-lead",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/LANGUAGE.md

@@ -0,0 +1,72 @@
+# Language
+
+Shared vocabulary across every skill in this set. Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+
+This file is the canonical source. Skills that need this vocabulary (`design`, `system-design`, `improve-codebase-architecture`, `grill-plan`) link here rather than duplicating definitions.
+
+## Architecture terms
+
+**Module**
+Anything with an interface and an implementation. Deliberately scale-agnostic — applies equally to a function, class, package, or tier-spanning slice.
+_Avoid_: unit, component, service.
+
+**Interface**
+Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics.
+_Avoid_: API, signature (too narrow — those refer only to the type-level surface).
+
+**Implementation**
+What's inside a module — its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+
+**Depth**
+Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(from Michael Feathers)_
+A place where you can alter behaviour without editing in that place. The *location* at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it.
+_Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter**
+A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
+
+**Leverage**
+What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests.
+
+**Locality**
+What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Topology terms (greenfield system shape)
+
+**Responsibility**
+What a module does, stated in one sentence. If you can't say it in one sentence, the module is too big — split or merge.
+
+**Dependency direction**
+Module A depends on B if A imports, calls, or relies on B's interface. Directional. The dependency graph at the system level is the topology.
+
+**Acyclic**
+The dependency graph has no cycles. If A → B → A, the modules aren't really separate — merge them, or insert a third module to break the cycle.
+
+**Port** *(from ports & adapters / hexagonal architecture)*
+An interface defined by a domain module so that infrastructure can implement it without the domain depending on infrastructure. The port lives in the domain; the adapter lives in the infra. Inverts the naive dependency direction.
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, the module wasn't hiding anything (it was a pass-through). If complexity reappears across N callers, the module was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+- **Domain doesn't depend on infrastructure.** Use ports — domain defines the interface, infrastructure implements it. Keeps domain logic runnable in tests with no infra.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+- A **Port** is an **Interface** defined by a domain **Module** for an infra **Adapter** to implement.
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout's original): rewards padding the implementation. We use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
+- **Layer-named modules** (`controllers`, `services`, `repositories`): a category split, not a responsibility split. Prefer feature slicing (`ordering/`, `billing/`, `auth/`).

package/skills/README.md

@@ -0,0 +1,156 @@
+# Claude skills
+
+Skills shape how Claude works on this repo. Each skill lives in its own subdirectory with a `SKILL.md` (the contract Claude reads) plus templates or supporting docs.
+
+This README is for humans. Claude discovers skills automatically — nothing is registered here.
+
+## Index — by trigger phase
+
+Grouped by role. Trigger phrases are in each skill's `description` frontmatter.
+
+### Planning & investigation
+
+| Skill | Trigger | Produces | Location |
+| --- | --- | --- | --- |
+| `bootstrap` | Starting a new project or service | `docs/` structure + `docs/CONTEXT.md` | [bootstrap/](./bootstrap/) |
+| `feature-doc` | Before any non-trivial feature or bug fix | `docs/features/<short-name>.md` | [feature-doc/](./feature-doc/) |
+| `investigate` | Open-ended research, proposals, or "options before code" | `docs/research/<topic>.md` | [investigate/](./investigate/) |
+| `grill-plan` | Stress-test a **chosen** plan against existing terminology and decisions | Updates to `docs/CONTEXT.md` and `docs/adr/` | [grill-plan/](./grill-plan/) |
+| `bench` | Verifying performance ACs or profiling hot paths | `docs/benchmarks/<feature>.md` | [bench/](./bench/) |
+
+### Design & architecture
+
+| Skill | Trigger | Produces | Location |
+| --- | --- | --- | --- |
+| `system-design` | Greenfield system architecture — modules, dependency direction, seams | `docs/architecture.md` (system map) | [system-design/](./system-design/) |
+| `design` | Designing a module or public API before implementation | Guidance only — optional `docs/features/<feature>.design.md` for non-trivial shapes | [design/](./design/) |
+| `improve-codebase-architecture` | Finding deepening opportunities — turning shallow modules into deep ones | Numbered candidate list, optional ADR / CONTEXT.md updates | [improve-codebase-architecture/](./improve-codebase-architecture/) |
+| `code-hygiene` | Line/function-level coding discipline (boring, naming, YAGNI, rule of 3, locality) | Guidance only — applied as a lens during `simplify` and `pr-review` | [code-hygiene/](./code-hygiene/) |
+| `zoom-out` | User-invoked: ask for higher-level context when unfamiliar with an area | Map of relevant modules and callers in `CONTEXT.md` vocabulary | [zoom-out/](./zoom-out/) |
+
+### Implementation
+
+| Skill | Trigger | Produces | Location |
+| --- | --- | --- | --- |
+| `debug` | Non-trivial bug whose root cause isn't obvious — runs **before** `tdd` | Reproduction + named root cause; optional `docs/research/<bug>.md` | [debug/](./debug/) |
+| `tdd` | Implementing a feature or fixing a bug, test-first | Test-first code | [tdd/](./tdd/) |
+| `tdd-rounds` | Multi-round TDD orchestration via Builder sub-agents (≥10 ACs / multi-package) | Builder briefs + reports + `docs/STATE.md` | [tdd-rounds/](./tdd-rounds/) |
+| `simplify` | End-of-slice / end-of-round sweep — reuse, quality, efficiency, test relevance | Tightened diff + a separate `simplify` commit | [simplify/](./simplify/) |
+
+### Pre-merge gates & review
+
+| Skill | Trigger | Produces | Location |
+| --- | --- | --- | --- |
+| `prod-ready` | After tdd green, before merge | Verified pre-merge checklist (incl. doc drift) | [prod-ready/](./prod-ready/) |
+| `security-review` | Surface-changing work — new entry points, identity flows, authz, sensitive data, external deps | Threat model + verified controls; appended to feature doc, or `docs/security/<feature>.md` for high-stakes | [security-review/](./security-review/) |
+| `pr-review` | Reviewing someone else's PR (or self-reviewing before opening) | Structured review with severity-classified findings (blocker / suggestion / nit / question) | [pr-review/](./pr-review/) |
+| `verify-real-deps` | Pre-tag smoke test against real third-party APIs | `docs/known-issues.md` bug ledger; fix-rounds until clean | [verify-real-deps/](./verify-real-deps/) |
+
+## Index — by role
+
+Orthogonal axis. The trigger-phrase index above tells you *when* a skill fires; this one tells you *what kind of thing it is*.
+
+| Role | Skills | What they have in common |
+| --- | --- | --- |
+| **Doc-producing** (writes a durable artifact under `docs/`) | `feature-doc`, `investigate`, `system-design`, `grill-plan`, `debug` (optional), `security-review` (optional), `verify-real-deps` | Output survives the conversation. The discipline of writing it is the value. |
+| **Build** (writes code) | `tdd`, `tdd-rounds`, `simplify` | Diff-producing. Always behind a contract (feature doc + ACs). |
+| **Gate** (verifies before merge / tag) | `prod-ready`, `security-review`, `pr-review`, `verify-real-deps` | Pre-merge or pre-tag — refuse to advance until the checklist passes. |
+| **Diagnose** (no code, no doc — just analysis) | `debug`, `zoom-out`, `sync-check` | Run *before* a build skill when the input isn't yet clear. |
+| **Shape** (decides module / topology) | `design`, `system-design`, `improve-codebase-architecture` | Greenfield-module / greenfield-system / brownfield. Same vocabulary ([`LANGUAGE.md`](./LANGUAGE.md)). |
+| **Lens** (applied during other skills, not invoked alone) | `code-hygiene` | Five principles you carry into `simplify`, `pr-review`, and any code-reading session. |
+
+## Skill relationship map
+
+The 16 skills + their dependencies. Lateral edges are vocabulary / lens; vertical edges are workflow flow.
+
+```
+                     ┌─────────────────────────────────────────────┐
+                     │              SHARED SUBSTRATE                │
+                     │                                              │
+                     │   LANGUAGE.md   formats/   TRIGGERS.md       │
+                     │       ▲             ▲          ▲             │
+                     └───────┼─────────────┼──────────┼─────────────┘
+                             │ vocab       │ format   │ routing
+   ┌─────────────────────────┴─────────────┴──────────┴────────────┐
+   │                                                                │
+   │   investigate ──► feature-doc ──► (design) ──► tdd ──► simplify │
+   │       │              │                ▲          ▲          │   │
+   │       │              ▼                │          │          │   │
+   │       │          grill-plan ──► ADR   │          │          ▼   │
+   │       │              ▲                │          │     prod-ready│
+   │       │              │                │          │          │   │
+   │       └──────────────┘                │          │          ▼   │
+   │                                       │          │     pr-review │
+   │   system-design ──► design (per mod) ─┘          │          │   │
+   │       │                                          │          ▼   │
+   │       ▼                                          │  verify-real-deps │
+   │  docs/architecture.md                            │          │   │
+   │                                                  │          ▼   │
+   │   improve-codebase-architecture ─────────────────┘     [merge]  │
+   │       ▲                                                          │
+   │       │                                                          │
+   │   tdd-rounds (orchestrator) ── dispatches Builders ──────────────│
+   │       │      ▲   ▲     ▲                                         │
+   │       │      │   │     │                                         │
+   │       │   debug security-review                                  │
+   │       │   (when bug)  (when surface)                             │
+   │                                                                  │
+   │   ┌────────────── LENSES & UTILITIES ──────────────┐             │
+   │   │  code-hygiene ──► applied during simplify,    │             │
+   │   │                   pr-review, any code reading  │             │
+   │   │                                                │             │
+   │   │  zoom-out ──► interrupts any workflow,        │             │
+   │   │              maps unfamiliar areas             │             │
+   │   └────────────────────────────────────────────────┘             │
+   └──────────────────────────────────────────────────────────────────┘
+```
+
+**Six things the map shows:**
+
+1. `code-hygiene` and `zoom-out` are not nodes in any flow — they're lenses / utilities applied across.
+2. `grill-plan` is the only skill invoked from three upstreams (`investigate`, `feature-doc`, `improve-codebase-architecture`) — it's the shared pressure-test step.
+3. `tdd-rounds` is the only multi-callee orchestrator — dispatches `design`, `tdd`, `simplify`, `prod-ready`, `verify-real-deps` to Builders.
+4. `pr-review` is the reviewer-side mirror of `prod-ready` — Section 7 doc-drift covered in both.
+5. `system-design` and `improve-codebase-architecture` are duals — same [LANGUAGE.md](./LANGUAGE.md), greenfield vs brownfield.
+6. The shared substrate ([LANGUAGE.md](./LANGUAGE.md), [formats/](./formats/), [TRIGGERS.md](./TRIGGERS.md)) is referenced everywhere — never copy-paste the content into a skill.
+
+## Workflows
+
+The skills compose into canonical workflows (greenfield feature, large feature, investigation, refactor, bug fix, greenfield system) plus utilities (`zoom-out`, `pr-review`). See [WORKFLOWS.md](./WORKFLOWS.md) for the decision tree, ASCII flow diagrams, and cross-workflow patterns.
+
+## Trigger lookup
+
+[TRIGGERS.md](./TRIGGERS.md) is the flat phrase → skill index. Useful for routing-collision debugging and onboarding.
+
+## Shared vocabulary
+
+[`LANGUAGE.md`](./LANGUAGE.md) at this directory's root is the canonical vocabulary used across every skill — **module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**, **responsibility**, **dependency direction**, **port**. Skills link here rather than duplicating definitions.
+
+## Shared formats
+
+[`formats/`](./formats/) holds reference docs that more than one skill consumes:
+
+- [`formats/ADR-FORMAT.md`](./formats/ADR-FORMAT.md) — ADR template, numbering, when-to-write criteria.
+- [`formats/CONTEXT-FORMAT.md`](./formats/CONTEXT-FORMAT.md) — `CONTEXT.md` structure, single-vs-multi-context layout, minimal example.
+
+Used by `grill-plan`, `improve-codebase-architecture`, `system-design`, `investigate`, and (lazily) `feature-doc`.
+
+## Conventions
+
+- **File naming.** UPPERCASE for skill-level reference docs (`SKILL.md`, `LANGUAGE.md`, `MOTIVATION.md`, `*-FORMAT.md`, etc.) — Claude loads these as supporting context. lowercase for templates inside `<skill>/templates/` — skeletons to copy and fill in.
+- Output artifacts live under `docs/` in the repo root, never inside `.claude/`.
+- Status enums, frontmatter shape, and cross-doc linking rules are in [`docs/CONVENTIONS.md`](../docs/CONVENTIONS.md).
+- Domain vocabulary is in [`docs/CONTEXT.md`](../docs/CONTEXT.md). Terms there beat synonyms invented at the keyboard.
+- **Body size matches role, not importance.** Skills that *teach* an agent how to do something (e.g. `tdd`, `debug`, `security-review`) tend to be longer — pedagogy, anti-pattern callouts, examples. Skills that *orchestrate* (e.g. `tdd-rounds`) tend to be shorter — contracts, tables, failure modes. Don't pad an orchestration skill to match a teaching skill's length; it just adds noise.
+- **SKILL.md heading order is canonical.** See [`SKILL-TEMPLATE.md`](./SKILL-TEMPLATE.md). Keep `When to use` / `When to skip` early so routing decisions land before the body.
+
+## Adding a skill
+
+1. Copy [`SKILL-TEMPLATE.md`](./SKILL-TEMPLATE.md) to `<name>/SKILL.md` and fill in.
+2. Make the `description` sharp enough that Claude will pick the skill on the right triggers and skip it on the wrong ones — name trigger phrases AND skip conditions AND adjacent skills.
+3. Reference [`LANGUAGE.md`](./LANGUAGE.md) and [`formats/`](./formats/) rather than redefining shared terms or formats.
+4. Link any templates from `SKILL.md` so Claude can find them.
+5. Add the skill to **both** index tables above (by trigger phase AND by role).
+6. Add an entry to [TRIGGERS.md](./TRIGGERS.md) for routing.
+7. Update [WORKFLOWS.md](./WORKFLOWS.md) if the skill participates in a canonical workflow or as a cross-workflow pattern.
+. Update [WORKFLOWS.md](./WORKFLOWS.md) if the skill participates in a canonical workflow or as a cross-workflow pattern.