pantheon-opencode 1.6.0-beta.1 → 1.6.0-beta.11

package/scripts/build-agents-md.mjs

@@ -1,42 +1,111 @@
 #!/usr/bin/env node
 /**
- * build-agents-md.mjs — Generate the repo AGENTS.md from canonical sources.
+ * build-agents-md.mjs — Generate BOTH AGENTS.md artifacts from canonical sources.
  *
- * AGENTS.md is the single instruction file BOTH OpenCode V1 and V2 load
- * (V1 auto-discovers it, V2 loads it explicitly; the `instructions` config
- * key is accepted-but-ignored by V2). To keep instruction content in parity
- * across both versions without duplication, this script consolidates:
+ * AGENTS.md files are instruction files BOTH OpenCode V1 and V2 load (V1
+ * auto-discovers them, V2 loads them explicitly; the `instructions` config
+ * key is accepted-but-ignored by V2). Every session pays for global AND
+ * project AGENTS.md content, so a single duplicated file is paid twice per
+ * session. To keep the payload disjoint (beta-10 latency slice, phase 1),
+ * this script emits TWO artifacts in ONE pass over the same sources:
  *
- *   (a) a static header (project description + agent table + setup notes)
- *   (b) every src/instructions/*.instructions.md body, embedded under a
- *       `## <name>` section marker (name taken from frontmatter)
+ *   AGENTS.md         — repo-specific setup only (build commands, sandbox
+ *                       rules, conventions). Loaded by sessions in THIS repo.
+ *   AGENTS.global.md  — repo-agnostic content only (agent table + shared
+ *                       instruction bodies embedded under a `## <name>`
+ *                       section marker). The installer/sync emits this into
+ *                       the user's global config dir as AGENTS.md.
  *
- * into one generated AGENTS.md. src/instructions/*.instructions.md remains
- * the source of truth — AGENTS.md is a committed build artifact, never
- * hand-edited.
+ * Zero overlap: each rule lives in exactly one artifact. Agent-scoped
+ * instruction bodies are still rendered into only their matching agent
+ * prompt. The instruction files remain the source of truth; both artifacts
+ * are committed build artifacts, never hand-edited. Each carries a version
+ * header (generated-at + short git sha) so a stale artifact is detectable;
+ * `--check` ignores that volatile line and byte-compares everything else.
  *
  * Usage:
- *   node scripts/build-agents-md.mjs            # write AGENTS.md to repo root
- *   node scripts/build-agents-md.mjs --check    # exit 1 if AGENTS.md is stale
+ *   node scripts/build-agents-md.mjs            # write both artifacts
+ *   node scripts/build-agents-md.mjs --check    # exit 1 if either is stale
  *
  * No runtime dependencies (Node >= 18, stdlib only). Idempotent: running it
- * twice produces byte-identical output.
+ * twice produces byte-identical output (the version header is derived from
+ * git, not the wall clock).
  */
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { ACTIONS, isRecording, recordChange } from './install/plan.mjs'
+
 const __dirname = dirname(fileURLToPath(import.meta.url))
 export const ROOT = join(__dirname, '..')
 const INSTRUCTIONS_DIR = join(ROOT, 'src', 'instructions')
-const AGENTS_MD_PATH = join(ROOT, 'AGENTS.md')
+export const AGENTS_MD_PATH = join(ROOT, 'AGENTS.md')
+export const AGENTS_GLOBAL_MD_PATH = join(ROOT, 'AGENTS.global.md')
+
+// ---------------------------------------------------------------------------
+// Managed region — both artifacts are fully machine-generated; the sentinels
+// let the installer refresh the region while preserving any user content
+// around it (conservative migration: non-managed content is never deleted).
+// ---------------------------------------------------------------------------
+export const MANAGED_BEGIN =
+  '<!-- pantheon:generated:begin — Pantheon-managed region; regenerated on install/upgrade, never edit inside -->'
+export const MANAGED_END =
+  '<!-- pantheon:generated:end — user content outside this region is preserved verbatim -->'
+
+/** Header comment every generator version has emitted, old and new. */
+const GENERATED_BY = '<!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->'
+const VERSION_LINE_RE = /^<!-- pantheon:agents-md v2 artifact=(?:global|project) [^\n]*-->$/gm
+
+/**
+ * Normalize the volatile version line so `--check` can byte-compare content
+ * across commits (the sha/generated-at intentionally lag HEAD by one commit).
+ *
+ * @param {string} content - Artifact content
+ * @returns {string} Content with the version line reduced to a fixed stub
+ */
+export function stripVersionLine(content) {
+  return content.replace(VERSION_LINE_RE, '<!-- pantheon:agents-md v2 -->')
+}
+
+/**
+ * Short git sha + commit date of HEAD — deterministic per commit, so the
+ * version header never breaks byte-determinism while still dating artifacts.
+ * Falls back to "unknown" outside a git worktree (npm tarball installs).
+ *
+ * @param {string} [root] - Repository root to run git in
+ * @returns {{ sha: string, date: string }}
+ */
+export function readGitInfo(root = ROOT) {
+  try {
+    const opts = { cwd: root, encoding: 'utf8' }
+    return {
+      sha: execFileSync('git', ['rev-parse', '--short=7', 'HEAD'], opts).trim(),
+      date: execFileSync('git', ['log', '-1', '--format=%cI'], opts).trim(),
+    }
+  } catch {
+    return { sha: 'unknown', date: 'unknown' }
+  }
+}
+
+/**
+ * The `pantheon:agents-md` version line embedded in every artifact.
+ *
+ * @param {'global' | 'project'} artifact - Which artifact the line stamps
+ * @param {{ sha: string, date: string }} git - Git info from readGitInfo()
+ * @returns {string}
+ */
+function versionLine(artifact, git) {
+  return `<!-- pantheon:agents-md v2 artifact=${artifact} generated-at=${git.date} sha=${git.sha} -->`
+}
 
 // ---------------------------------------------------------------------------
-// Static header — preserved verbatim from the original AGENTS.md (agent table,
-// setup notes, sandbox rules, conventions). Backticks are escaped for the
-// template literal.
+// Static headers — GLOBAL is repo-agnostic (safe for any project), PROJECT is
+// repo-specific (this repository's setup). Zero overlap by construction.
+// Backticks are escaped for the template literal.
 // ---------------------------------------------------------------------------
-const STATIC_HEADER = `# Pantheon Agent System — OpenCode
+const GLOBAL_HEADER = `# Pantheon Agent System — OpenCode
 
 This project uses the Pantheon multi-agent framework with 14 specialized agents.
 
@@ -44,21 +113,30 @@ This project uses the Pantheon multi-agent framework with 14 specialized agents.
 
 | Agent | Role |
 |-------|------|
-| @aphrodite | Frontend specialist — React 19, TypeScript strict, WCAG accessibility, responsive design, TDD, modern API patterns, deprecated npm detection. Calls apollo for discovery, sends to themis for review. |
+| @aphrodite | Frontend specialist — React 19, TypeScript strict, WCAG accessibility, responsive design, TDD, modern API patterns, deprecated npm detection. Uses discovery/review proportionally to scope and risk. |
 | @apollo | Read-only investigation scout — 3–10 parallel searches across codebase, external docs, and GitHub. Called by: athena, zeus, hermes, aphrodite, demeter. No edits, no commands. |
 | @athena | Strategic planner & architect — research-first, plan-only, never implements. Plans include quality gates (ruff/Biome, dep detection, LTS policy). Calls apollo for discovery. |
-| @demeter | Database specialist — SQLAlchemy 2.0, Alembic, query optimization, N+1 prevention, TDD migrations, modern DB libs. Calls apollo for discovery, sends to themis. |
+| @demeter | Database specialist — SQLAlchemy 2.0, Alembic, query optimization, N+1 prevention, TDD migrations, modern DB libs. Preserves review gates for schema/data changes. |
 | @gaia | Remote sensing domain specialist — satellite image processing, spectral analysis, SAR, change detection, time series, ML/DL classification. Read-only analysis of geospatial data. |
 | @hephaestus | AI tooling & pipelines specialist — LangChain/LangGraph chains, RAG architecture, vector stores, embedding strategies. Forges AI infrastructure. Calls apollo, sends to themis. |
-| @hermes | Backend specialist — FastAPI, Python, async, TDD (RED→GREEN→REFACTOR), modern Python stdlib, obsolete lib detection. Calls apollo for discovery, sends to themis. |
+| @hermes | Backend specialist — FastAPI, Python, async, TDD (RED→GREEN→REFACTOR), modern Python stdlib, obsolete lib detection. Uses discovery/review proportionally to scope and risk. |
 | @iris | GitHub operations specialist — branches, pull requests, issues, releases, tags. Called by zeus after review. Never pushes or merges without explicit human approval. Integrates with VS Code GitHub Pull Requests extension. |
 | @mnemosyne | Memory bank quality owner — initializes .pantheon/memory-bank/, writes ADRs and task records on explicit request. Called by zeus. Never invoked automatically after phases. |
 | @nyx | Observability & monitoring specialist — OpenTelemetry tracing, token/cost tracking, agent performance analytics, LangSmith integration. Calls apollo for discovery, sends to themis. |
 | @prometheus | Infrastructure + model provider specialist — Docker, CI/CD, multi-model routing, cost optimization, provider abstraction |
 | @talos | Hotfix express lane — direct fixes for small bugs, CSS, typos, minor logic. No TDD ceremony, no orchestration overhead. Standalone, no subagents. Escalates complex issues to zeus. |
-| @themis | Quality & security gate — ruff/Biome linting, dead/legacy code detection, OWASP Top 10, coverage >80%, correctness, deprecation audit. Called by implementers; escalates blockers to zeus. |
+| @themis | Quality & security gate — ruff/Biome linting, dead/legacy code detection, OWASP Top 10, applicable coverage requirements, correctness, deprecation audit. Reviews material/sensitive changes. |
 | @zeus | Central orchestrator — never implements. Delegates to: athena, apollo, hermes, aphrodite, demeter, prometheus, themis, iris, mnemosyne, talos, hephaestus, nyx |
 
+Repository-specific setup and conventions live in each project's own AGENTS.md; this global file carries only the rules shared by every Pantheon session, so nothing is ever loaded twice.
+`
+
+const PROJECT_HEADER = `# Pantheon — Repository Setup
+
+Shared Pantheon rules (agent table, return format, memory protocol, YAGNI,
+communication rules) live in the global \`~/.config/opencode/AGENTS.md\`; this
+file carries only repository-specific setup so no rule is loaded twice.
+
 ## OpenCode Setup
 
 See [INSTALLATION.md](docs/INSTALLATION.md) for setup instructions.
@@ -78,13 +156,22 @@ Para validar a instalação global do pacote pantheon-opencode COMO UM USUÁRIO
 
 ## Conventions
 
-- TDD: Write failing test first, then implement
-- Coverage minimum: 80%
+- TDD: RED→GREEN→REFACTOR for testable behavior; use focused checks for micro-edits
+- Honor repository coverage thresholds when relevant; preserve stronger auth/security/data-integrity gates
 - Async/await on all I/O
 - Type hints on all functions
 - PRs always update the README — every pull request must document newly added features, behaviors, env vars, or commands in the README before being opened.
 `
 
+const INSTRUCTIONS_PREAMBLE = `---
+
+# Agent Instructions
+
+The following sections are consolidated from \`src/instructions/*.instructions.md\`
+so both OpenCode V1 (auto-loads AGENTS.md) and V2 (loads AGENTS.md, ignores the
+\`instructions\` config key) receive identical shared rules. Agent-scoped rules
+are rendered into only the matching installed agent prompts.`
+
 // ---------------------------------------------------------------------------
 // Frontmatter parsing (stdlib only — no yaml dependency)
 // ---------------------------------------------------------------------------
@@ -92,20 +179,41 @@ Para validar a instalação global do pacote pantheon-opencode COMO UM USUÁRIO
 /**
  * Parse YAML-ish frontmatter from an instruction file.
  *
- * Only the `name` field is extracted (single-line scalar). The frontmatter
- * block itself is stripped from the embedded body.
+ * Preserve the file-scope `applyTo` glob separately from the explicit
+ * `agents` selectors. In particular, a Python workspace glob is never
+ * interpreted as an agent name. The frontmatter block is stripped from
+ * the embedded body.
  *
  * @param {string} content - Raw file content
- * @returns {{ name: string, body: string } | null}
+ * @returns {{ name: string, body: string, applyTo: string | null,
+ *   agents: string[], fallback: string | null, appliesToAgent: (name: string) => boolean } | null}
  */
-function parseInstruction(content) {
+export function parseInstruction(content) {
   const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/)
   if (!match) return null
   const fm = match[1]
   const nameMatch = fm.match(/^name:\s*["']?([^"'\r\n]+)["']?\s*$/m)
   if (!nameMatch) return null
+  const applyToMatch = fm.match(/^applyTo:\s*["']?([^"'\r\n]+)["']?\s*$/m)
+  const agentsMatch = fm.match(/^agents:\s*\[([^\]\r\n]*)\]\s*$/m)
+  const agents = agentsMatch
+    ? agentsMatch[1]
+        .split(',')
+        .map((agent) => agent.trim().replace(/^(["'])(.*)\1$/, '$2'))
+        .filter(Boolean)
+    : fm.match(/^agents:/m)
+      ? [] // Malformed explicit selector: fail closed; never make it global.
+      : applyToMatch
+        ? [] // File-scoped instructions need an explicit agent association.
+        : ['*'] // Legacy instructions without selectors remain shared.
+  const fallbackMatch = fm.match(/^fallback:\s*["']?([^"'\r\n]+)["']?\s*$/m)
+  const appliesToAgent = (agent) => agents.includes('*') || agents.includes(agent)
   return {
     name: nameMatch[1].trim(),
+    applyTo: applyToMatch?.[1].trim() ?? null,
+    agents,
+    fallback: fallbackMatch?.[1].trim() ?? null,
+    appliesToAgent,
     body: `${content.slice(match[0].length).trimEnd()}\n`,
   }
 }
@@ -114,7 +222,8 @@ function parseInstruction(content) {
  * Read all src/instructions/*.instructions.md files, sorted by filename for
  * deterministic output.
  *
- * @returns {Array<{ file: string, name: string, body: string }>}
+ * @returns {Array<{ file: string, name: string, body: string, applyTo: string | null,
+ *   agents: string[], fallback: string | null, appliesToAgent: (name: string) => boolean }>}
  */
 export function readInstructions() {
   if (!existsSync(INSTRUCTIONS_DIR)) return []
@@ -135,28 +244,29 @@ export function readInstructions() {
 // ---------------------------------------------------------------------------
 
 /**
- * Generate the full AGENTS.md content.
+ * Generate the GLOBAL AGENTS.md content (repo-agnostic): agent table + the
+ * shared instruction bodies. This is the content installed into the user's
+ * global config dir as AGENTS.md.
  *
- * @param {Array<{ file: string, name: string, body: string }>} instructions
+ * @param {Array<{ file: string, name: string, body: string, agents?: string[] }>} instructions
+ * @param {{ sha: string, date: string }} git - Git info from readGitInfo()
  * @returns {string}
  */
-export function generateAgentsMd(instructions) {
+export function generateGlobalAgentsMd(instructions, git = readGitInfo()) {
+  const sharedInstructions = instructions.filter(
+    (instr) => !instr.agents || instr.agents.includes('*'),
+  )
   const sections = [
-    '<!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->',
-    '<!-- Source of truth: src/instructions/*.instructions.md (AGENTS.md is a committed build artifact). -->',
-    '',
-    STATIC_HEADER.trimEnd(),
-    '',
-    '---',
+    MANAGED_BEGIN,
+    GENERATED_BY,
+    '<!-- Source of truth: src/instructions/*.instructions.md + the static sections in this script. -->',
+    versionLine('global', git),
     '',
-    '# Agent Instructions',
-    '',
-    'The following sections are consolidated from `src/instructions/*.instructions.md`',
-    'so both OpenCode V1 (auto-loads AGENTS.md) and V2 (loads AGENTS.md, ignores the',
-    '`instructions` config key) receive identical instruction content.',
+    GLOBAL_HEADER.trimEnd(),
+    INSTRUCTIONS_PREAMBLE,
     '',
   ]
-  for (const instr of instructions) {
+  for (const instr of sharedInstructions) {
     sections.push(
       `<!-- Source: src/instructions/${instr.file} -->`,
       `## ${instr.name}`,
@@ -165,9 +275,248 @@ export function generateAgentsMd(instructions) {
       '',
     )
   }
+  sections.push(MANAGED_END)
   return `${sections.join('\n').trimEnd()}\n`
 }
 
+/**
+ * Generate the PROJECT AGENTS.md content (repo-specific setup only). Shared
+ * rules deliberately live in the global artifact so a session never pays for
+ * the same rule twice.
+ *
+ * @param {{ sha: string, date: string }} git - Git info from readGitInfo()
+ * @returns {string}
+ */
+export function generateProjectAgentsMd(git = readGitInfo()) {
+  const sections = [
+    MANAGED_BEGIN,
+    GENERATED_BY,
+    '<!-- Source of truth: the static project sections in scripts/build-agents-md.mjs. -->',
+    versionLine('project', git),
+    '',
+    PROJECT_HEADER.trimEnd(),
+    MANAGED_END,
+  ]
+  return `${sections.join('\n').trimEnd()}\n`
+}
+
+// ---------------------------------------------------------------------------
+// Managed-region writer — shared by the installer (scripts/install/opencode.mjs)
+// and the postinstall freshness sync (scripts/sync-artifacts.mjs).
+// ---------------------------------------------------------------------------
+
+/**
+ * Write an AGENTS.md artifact conservatively:
+ *
+ *   - missing target          → write generated content ('created')
+ *   - managed region present  → replace ONLY the region; any user content
+ *                               around it is preserved ('updated' when the
+ *                               file is pure managed content, 'merged' when
+ *                               foreign content was kept)
+ *   - legacy generated file   → the whole file is machine-generated per its
+ *                               own header; upgrade in place ('upgraded')
+ *   - foreign file            → never clobber: append the managed region
+ *                               below the user's content ('merged')
+ *
+ * Byte-compare idempotent: identical content returns 'skipped' untouched.
+ *
+ * @param {string} filePath - Destination AGENTS.md path
+ * @param {string} generated - Generated artifact content (incl. sentinels)
+ * @param {boolean} [dryRun=false] - Do not write when true
+ * @returns {'created' | 'skipped' | 'updated' | 'upgraded' | 'merged'}
+ */
+export function writeAgentsMdManaged(filePath, generated, dryRun = false, recorder = null) {
+  const existing = existsSync(filePath) ? readFileSync(filePath, 'utf8') : null
+  if (existing === null) {
+    if (!dryRun) {
+      mkdirSync(dirname(filePath), { recursive: true })
+      writeFileSync(filePath, generated, 'utf8')
+    }
+    recordChange(
+      { path: filePath, action: ACTIONS.CREATE, bytes: Buffer.byteLength(generated, 'utf8') },
+      recorder,
+    )
+    return 'created'
+  }
+  if (existing === generated) {
+    recordChange(
+      { path: filePath, action: ACTIONS.UNCHANGED, bytes: Buffer.byteLength(existing, 'utf8') },
+      recorder,
+    )
+    return 'skipped'
+  }
+
+  const begin = existing.indexOf(MANAGED_BEGIN)
+  const end = existing.indexOf(MANAGED_END)
+  if (begin !== -1 && end !== -1 && end > begin) {
+    const before = existing.slice(0, begin)
+    const after = existing.slice(end + MANAGED_END.length)
+    const next = `${before}${generated}${after}`
+    if (next === existing) {
+      recordChange(
+        { path: filePath, action: ACTIONS.UNCHANGED, bytes: Buffer.byteLength(existing, 'utf8') },
+        recorder,
+      )
+      return 'skipped'
+    }
+    if (!dryRun) writeFileSync(filePath, next, 'utf8')
+    recordChange(
+      { path: filePath, action: ACTIONS.UPDATE, bytes: Buffer.byteLength(next, 'utf8') },
+      recorder,
+    )
+    return before.trim() === '' && after.trim() === '' ? 'updated' : 'merged'
+  }
+
+  if (existing.startsWith(GENERATED_BY)) {
+    // Legacy format: the header declares the whole file machine-generated.
+    if (!dryRun) writeFileSync(filePath, generated, 'utf8')
+    recordChange(
+      { path: filePath, action: ACTIONS.UPDATE, bytes: Buffer.byteLength(generated, 'utf8') },
+      recorder,
+    )
+    return 'upgraded'
+  }
+
+  // Foreign content: preserve it verbatim and append the managed region.
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n'
+  const payload = `${existing}${separator}${generated}`
+  if (!dryRun) {
+    writeFileSync(filePath, payload, 'utf8')
+  }
+  recordChange(
+    { path: filePath, action: ACTIONS.UPDATE, bytes: Buffer.byteLength(payload, 'utf8') },
+    recorder,
+  )
+  return 'merged'
+}
+
+const GENERATED_AGENT_BLOCK =
+  /\n?<!-- Pantheon selective instructions: generated -->[\s\S]*?<!-- \/Pantheon selective instructions -->\n?/g
+
+/**
+ * Render the agent-specific instruction set into the supported agent prompt.
+ * The shared rules remain in AGENTS.md; file globs are retained as scope
+ * guidance and are never used as agent selectors.
+ *
+ * @param {string} agentName - Canonical agent name from the prompt filename
+ * @param {string} prompt - Canonical source agent prompt
+ * @param {Array<{ file: string, name: string, body: string, applyTo?: string | null,
+ *   agents?: string[], fallback?: string | null }>} instructions
+ * @returns {string}
+ */
+export function generateAgentPrompt(agentName, prompt, instructions = readInstructions()) {
+  const basePrompt = prompt.replace(GENERATED_AGENT_BLOCK, '').trimEnd()
+  const selected = instructions.filter(
+    (instr) => instr.agents && !instr.agents.includes('*') && instr.agents.includes(agentName),
+  )
+  if (selected.length === 0) {
+    return [
+      basePrompt,
+      '',
+      '<!-- Pantheon selective instructions: generated -->',
+      'No agent-specific instructions are assigned; follow the shared rules in AGENTS.md.',
+      '<!-- /Pantheon selective instructions -->',
+      '',
+    ].join('\n')
+  }
+
+  const sections = selected.map((instr) => {
+    const scope = instr.applyTo
+      ? `\n\n> Apply only when a target workspace file matches \`${instr.applyTo}\`.`
+      : ''
+    const fallback =
+      instr.fallback === 'shared'
+        ? '\n\n> For work outside this scope, use the shared rules in AGENTS.md.'
+        : ''
+    return [
+      `<!-- Source: src/instructions/${instr.file} -->`,
+      `## ${instr.name}${scope}`,
+      '',
+      `${instr.body.trimEnd()}${fallback}`,
+    ].join('\n')
+  })
+  return [
+    basePrompt,
+    '',
+    '<!-- Pantheon selective instructions: generated -->',
+    sections.join('\n\n'),
+    '<!-- /Pantheon selective instructions -->',
+    '',
+  ].join('\n')
+}
+
+/**
+ * Copy agent prompts with scoped instructions embedded in each actual prompt.
+ * Used by both init and postinstall sync so the installed runtime receives the
+ * same selection without a per-turn injection hook.
+ *
+ * @param {string} sourceDir - Canonical src/agents directory
+ * @param {string} targetDir - OpenCode agents directory
+ * @param {boolean} dryRun - Do not write when true
+ * @param {boolean} existingOnly - Refresh installed prompts without adding missing agents
+ * @param {(change: object) => void} [recorder] - optional change recorder for --dry-run preview
+ * @returns {{ created: number, skipped: number }}
+ */
+export function copyAgentPrompts(
+  sourceDir,
+  targetDir,
+  dryRun = false,
+  existingOnly = false,
+  recorder = null,
+) {
+  const instructions = readInstructions()
+  if (!dryRun && !existingOnly) mkdirSync(targetDir, { recursive: true })
+  let created = 0
+  let skipped = 0
+  for (const file of readdirSync(sourceDir)
+    .filter((entry) => entry.endsWith('.md'))
+    .sort()) {
+    if (file.toLowerCase() === 'readme.md') continue
+    const sourcePath = join(sourceDir, file)
+    if (!statSync(sourcePath).isFile()) continue
+    const agentName = file.replace(/\.md$/, '')
+    const output = generateAgentPrompt(agentName, readFileSync(sourcePath, 'utf8'), instructions)
+    const targetPath = join(targetDir, file)
+    if (existingOnly && !existsSync(targetPath)) continue
+    const existing = existsSync(targetPath) ? readFileSync(targetPath, 'utf8') : null
+    if (existing === output) {
+      skipped++
+      if (isRecording(recorder)) {
+        recordChange(
+          { path: targetPath, action: ACTIONS.UNCHANGED, bytes: Buffer.byteLength(output, 'utf8') },
+          recorder,
+        )
+      }
+    } else {
+      if (!dryRun) writeFileSync(targetPath, output, 'utf8')
+      created++
+      if (isRecording(recorder)) {
+        recordChange(
+          {
+            path: targetPath,
+            action: existing === null ? ACTIONS.CREATE : ACTIONS.UPDATE,
+            bytes: Buffer.byteLength(output, 'utf8'),
+          },
+          recorder,
+        )
+      }
+    }
+  }
+  return { created, skipped }
+}
+
+/**
+ * Count LF-delimited logical lines without assuming a trailing newline.
+ *
+ * @param {string} content - File content
+ * @returns {number}
+ */
+export function logicalLineCount(content) {
+  if (content.length === 0) return 0
+  const separators = content.match(/\n/g)?.length ?? 0
+  return separators + (content.endsWith('\n') ? 0 : 1)
+}
+
 // ---------------------------------------------------------------------------
 // CLI entry point
 // ---------------------------------------------------------------------------
@@ -175,23 +524,46 @@ export function generateAgentsMd(instructions) {
 function main() {
   const checkOnly = process.argv.includes('--check')
   const instructions = readInstructions()
-  const content = generateAgentsMd(instructions)
+  const sharedCount = instructions.filter(
+    (instr) => !instr.agents || instr.agents.includes('*'),
+  ).length
+  const global = generateGlobalAgentsMd(instructions)
+  const project = generateProjectAgentsMd()
 
   if (checkOnly) {
-    const existing = existsSync(AGENTS_MD_PATH) ? readFileSync(AGENTS_MD_PATH, 'utf8') : ''
-    if (existing !== content) {
-      console.error(`❌ AGENTS.md is stale — run: node scripts/build-agents-md.mjs`)
+    const stale = []
+    const existingGlobal = existsSync(AGENTS_GLOBAL_MD_PATH)
+      ? readFileSync(AGENTS_GLOBAL_MD_PATH, 'utf8')
+      : ''
+    const existingProject = existsSync(AGENTS_MD_PATH) ? readFileSync(AGENTS_MD_PATH, 'utf8') : ''
+    if (stripVersionLine(existingGlobal) !== stripVersionLine(global)) {
+      stale.push('AGENTS.global.md')
+    }
+    if (stripVersionLine(existingProject) !== stripVersionLine(project)) {
+      stale.push('AGENTS.md')
+    }
+    if (stale.length > 0) {
+      console.error(
+        `❌ ${stale.join(' and ')} ${
+          stale.length > 1 ? 'are' : 'is'
+        } stale — run: node scripts/build-agents-md.mjs`,
+      )
       process.exit(1)
     }
-    console.log(`✅ AGENTS.md is up to date (${instructions.length} instruction sections)`)
+    console.log(
+      `✅ AGENTS.md and AGENTS.global.md are up to date (${sharedCount} shared instruction sections)`,
+    )
     return
   }
 
-  writeFileSync(AGENTS_MD_PATH, content, 'utf8')
-  const lines = content.split('\n').length
+  writeFileSync(AGENTS_GLOBAL_MD_PATH, global, 'utf8')
+  writeFileSync(AGENTS_MD_PATH, project, 'utf8')
   console.log(
-    `✅ Generated AGENTS.md (${instructions.length} instruction sections, ${lines} lines)`,
+    `✅ Generated AGENTS.md (${logicalLineCount(project)} lines) + AGENTS.global.md ` +
+      `(${logicalLineCount(global)} lines, ${sharedCount} shared instruction sections)`,
   )
 }
 
-main()
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main()
+}