agentxchain 0.8.6 → 0.8.8

package/src/lib/next-owner.js

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+export function resolveExpectedClaimer(root, config, lock = {}) {
+  const agents = Object.keys(config.agents || {});
+  if (agents.length === 0) return { next: null, source: 'none', raw: null };
+
+  const trigger = readTrigger(root);
+  if (
+    trigger &&
+    typeof trigger.turn_number === 'number' &&
+    trigger.turn_number === lock.turn_number &&
+    typeof trigger.agent === 'string' &&
+    agents.includes(trigger.agent)
+  ) {
+    return { next: trigger.agent, source: 'trigger', raw: trigger.agent };
+  }
+
+  return resolveNextAgent(root, config, lock);
+}
+
+export function resolveNextAgent(root, config, lock = {}) {
+  const agents = Object.keys(config.agents || {});
+  if (agents.length === 0) return { next: null, source: 'none', raw: null };
+
+  const talkFile = config.talk_file || 'TALK.md';
+  const talkPath = join(root, talkFile);
+  const fromTalk = parseNextOwnerFromTalk(talkPath, agents);
+  if (fromTalk) {
+    return { next: fromTalk, source: 'talk', raw: fromTalk };
+  }
+
+  if (config.rules?.strict_next_owner) {
+    return { next: null, source: 'strict-missing', raw: null };
+  }
+
+  const last = lock.last_released_by;
+  if (last && agents.includes(last)) {
+    const idx = agents.indexOf(last);
+    return { next: agents[(idx + 1) % agents.length], source: 'fallback-cyclic', raw: null };
+  }
+
+  return { next: agents[0], source: 'fallback-first', raw: null };
+}
+
+const NEXT_OWNER_PATTERNS = [
+  /^(?:-|\*)?\s*\**next\s*owner\**\s*:\s*(.+)$/i,
+  /^(?:-|\*)?\s*\**handoff\s*(?:to)?\**\s*:\s*(.+)$/i,
+  /^(?:-|\*)?\s*\**next\**\s*:\s*(.+)$/i,
+  /^(?:-|\*)?\s*\**hand\s*off\s*to\**\s*:\s*(.+)$/i,
+];
+
+function parseNextOwnerFromTalk(talkPath, validAgentIds) {
+  if (!existsSync(talkPath)) return null;
+
+  let text = '';
+  try {
+    text = readFileSync(talkPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  if (!text.trim()) return null;
+
+  const lines = text.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i].trim();
+    if (!line) continue;
+
+    for (const pattern of NEXT_OWNER_PATTERNS) {
+      const match = line.match(pattern);
+      if (!match) continue;
+
+      const candidate = normalizeAgentId(match[1]);
+      if (candidate && validAgentIds.includes(candidate)) {
+        return candidate;
+      }
+
+      const fuzzy = fuzzyMatchAgentId(match[1], validAgentIds);
+      if (fuzzy) return fuzzy;
+    }
+  }
+
+  return null;
+}
+
+function normalizeAgentId(raw) {
+  if (!raw) return null;
+  let value = String(raw).trim();
+  value = value.replace(/[`*_\[\]]/g, '').trim();
+  value = value.replace(/\(.*?\)/g, '').trim();
+  value = value.split(/[,\s]+/)[0];
+  value = value.toLowerCase();
+  return /^[a-z0-9_-]+$/.test(value) ? value : null;
+}
+
+function fuzzyMatchAgentId(raw, validAgentIds) {
+  if (!raw) return null;
+  const cleaned = String(raw).replace(/[`*_\[\]]/g, '').replace(/\(.*?\)/g, '').trim().toLowerCase();
+  for (const id of validAgentIds) {
+    if (cleaned.startsWith(id)) return id;
+    if (cleaned.includes(id)) return id;
+  }
+  return null;
+}
+
+function readTrigger(root) {
+  const triggerPath = join(root, '.agentxchain-trigger.json');
+  if (!existsSync(triggerPath)) return null;
+  try {
+    return JSON.parse(readFileSync(triggerPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+

package/src/lib/notify.js

@@ -1,24 +1,26 @@
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
+
+function sanitize(str) {
+  return String(str).replace(/[\\"]/g, ' ').replace(/'/g, ' ').slice(0, 200);
+}
 
 export function notifyHuman(message, title = 'AgentXchain') {
-  // Terminal bell
   process.stdout.write('\x07');
 
-  // macOS notification
+  const safeMsg = sanitize(message);
+  const safeTitle = sanitize(title);
+
   if (process.platform === 'darwin') {
     try {
-      execSync(`osascript -e 'display notification "${message}" with title "${title}"'`);
-    } catch {
-      // osascript not available or permission denied
-    }
+      execFileSync('osascript', [
+        '-e', `display notification "${safeMsg}" with title "${safeTitle}"`
+      ], { stdio: 'ignore' });
+    } catch {}
   }
 
-  // Linux notification
   if (process.platform === 'linux') {
     try {
-      execSync(`notify-send "${title}" "${message}"`);
-    } catch {
-      // notify-send not available
-    }
+      execFileSync('notify-send', [safeTitle, safeMsg], { stdio: 'ignore' });
+    } catch {}
   }
 }

package/src/lib/prompt-core.js

@@ -0,0 +1,108 @@
+/**
+ * Shared prompt building blocks used by seed-prompt.js, seed-prompt-polling.js,
+ * and generate-vscode.js. Single source of truth for protocol rules expressed
+ * in prompts.
+ */
+
+export function buildReadSection(config, opts = {}) {
+  const stateFile = config.state_file || 'state.md';
+  const historyFile = config.history_file || 'history.jsonl';
+  const logFile = config.log || 'log.md';
+  const talkFile = config.talk_file || 'TALK.md';
+  const useSplit = config.state_file || config.history_file;
+
+  if (useSplit) {
+    const lines = [
+      `"${stateFile}" — the living project state. Read fully. Primary context.`,
+      `"${historyFile}" — turn history. Read last 3 lines for recent context.`,
+    ];
+    if (opts.includeTalk) lines.push(`"${talkFile}" — team handoff updates. Read the latest 5 entries.`);
+    lines.push('lock.json — who holds the lock.');
+    lines.push('state.json — phase and blocked status.');
+    return `READ THESE FILES EVERY TURN:\n${lines.map(l => `- ${l}`).join('\n')}`;
+  }
+
+  const lines = [
+    `"${logFile}" — the message log. Read last few messages.`,
+  ];
+  if (opts.includeTalk) lines.push(`"${talkFile}" — team handoff updates. Read the latest 5 entries.`);
+  lines.push('lock.json — who holds the lock.');
+  lines.push('state.json — phase and blocked status.');
+  return `READ THESE FILES EVERY TURN:\n${lines.map(l => `- ${l}`).join('\n')}`;
+}
+
+export function buildWriteSection(agentId, agentDef, config, opts = {}) {
+  const stateFile = config.state_file || 'state.md';
+  const historyFile = config.history_file || 'history.jsonl';
+  const logFile = config.log || 'log.md';
+  const talkFile = config.talk_file || 'TALK.md';
+  const useSplit = config.state_file || config.history_file;
+  const agentIds = Object.keys(config.agents);
+
+  const steps = ['a. Do your actual work: write code, create files, run commands, make decisions.'];
+
+  if (useSplit) {
+    steps.push(`b. Update "${stateFile}" — OVERWRITE with current project state.`);
+    steps.push(`c. Append ONE line to "${historyFile}":\n   {"turn": N, "agent": "${agentId}", "summary": "what you did", "files_changed": [...], "verify_result": "pass|fail|skipped", "timestamp": "ISO8601"}`);
+    if (opts.includeTalk) {
+      steps.push(`d. Append ONE handoff entry to "${talkFile}" with:\n   Turn, Status, Decision, Action, Risks/Questions, Next owner.\n   IMPORTANT: "Next owner" must be a valid agent id from [${agentIds.join(', ')}].`);
+      steps.push('e. Update state.json if phase or blocked status changed.');
+    } else {
+      steps.push('d. Update state.json if phase or blocked status changed.');
+    }
+  } else {
+    steps.push(
+      `b. Append ONE message to ${logFile}:\n` +
+      `   ---\n` +
+      `   ### [${agentId}] (${agentDef.name}) | Turn N\n` +
+      `   **Status:** Current project state.\n` +
+      `   **Decision:** What you decided and why.\n` +
+      `   **Action:** What you did. Commands, files, results.\n` +
+      `   **Next:** What the next agent should focus on.`
+    );
+    if (opts.includeTalk) {
+      steps.push(`c. Append ONE handoff entry to "${talkFile}" with:\n   Turn, Status, Decision, Action, Risks/Questions, Next owner.\n   IMPORTANT: "Next owner" must be a valid agent id from [${agentIds.join(', ')}].`);
+      steps.push('d. Update state.json if phase or blocked status changed.');
+    } else {
+      steps.push('c. Update state.json if phase or blocked status changed.');
+    }
+  }
+
+  return `WRITE (in this order):\n${steps.join('\n')}`;
+}
+
+export function buildVerifySection(config) {
+  const verifyCmd = config.rules?.verify_command || null;
+  if (!verifyCmd) return '';
+  return `\nVERIFY (mandatory before release):\nRun: ${verifyCmd}\nIf it FAILS: fix the problem. Run again. Do NOT release with failing verification.\nIf it PASSES: report the result. Then release.`;
+}
+
+export function buildRulesSection(agentId, config) {
+  const maxClaims = config.rules?.max_consecutive_claims || 2;
+  return [
+    '- Never write files or code without holding the lock. Reading is always allowed.',
+    `- One git commit per turn: "Turn N - ${agentId} - description"`,
+    `- Max ${maxClaims} consecutive turns. If you have held the lock ${maxClaims} times in a row, do a short turn and release.`,
+    '- ALWAYS release the lock. A stuck lock blocks the entire team.',
+    '- ALWAYS find at least one problem, risk, or question about the previous work. Blind agreement is forbidden.',
+  ].join('\n');
+}
+
+export function buildPlanningDocsSection() {
+  return `PROJECT DOCUMENTATION (.planning/ folder):
+
+These files give you project context. Read the ones relevant to your role.
+
+- .planning/PROJECT.md — Vision, constraints, stack decisions. PM writes this.
+- .planning/REQUIREMENTS.md — Scoped requirements with acceptance criteria. PM writes this.
+- .planning/ROADMAP.md — Phased delivery plan. PM maintains this.
+- .planning/research/ — Domain research, prior art, technical investigation.
+- .planning/phases/ — Per-phase plans (PLAN.md), reviews (REVIEW.md), test results (TESTS.md), bugs (BUGS.md).
+- .planning/qa/TEST-COVERAGE.md — Which features are tested and how. QA maintains this.
+- .planning/qa/BUGS.md — Open and fixed bugs with reproduction steps. QA maintains this.
+- .planning/qa/UX-AUDIT.md — UX checklist and visual/usability issues. QA maintains this.
+- .planning/qa/ACCEPTANCE-MATRIX.md — Requirements mapped to test status. QA maintains this.
+- .planning/qa/REGRESSION-LOG.md — Fixed bugs and their regression tests.
+
+When your role requires it, CREATE or UPDATE these files.`;
+}

package/src/lib/safe-write.js

@@ -0,0 +1,44 @@
+import { writeFileSync, renameSync, mkdirSync, unlinkSync } from 'fs';
+import { join, dirname } from 'path';
+import { randomBytes } from 'crypto';
+
+/**
+ * Atomically write JSON to a file using write-to-temp-then-rename.
+ * renameSync is atomic on POSIX; on Windows it is close enough for
+ * single-process coordination (the only gap is cross-process, which
+ * we guard against at the protocol level).
+ */
+export function safeWriteJson(filePath, data) {
+  const dir = dirname(filePath);
+  const tmpName = `.tmp-${randomBytes(6).toString('hex')}.json`;
+  const tmpPath = join(dir, tmpName);
+
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n');
+
+  try {
+    renameSync(tmpPath, filePath);
+  } catch (err) {
+    try { unlinkSync(tmpPath); } catch {}
+    throw err;
+  }
+}
+
+/**
+ * Atomically write plain text to a file.
+ */
+export function safeWriteText(filePath, text) {
+  const dir = dirname(filePath);
+  const tmpName = `.tmp-${randomBytes(6).toString('hex')}`;
+  const tmpPath = join(dir, tmpName);
+
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(tmpPath, text);
+
+  try {
+    renameSync(tmpPath, filePath);
+  } catch (err) {
+    try { unlinkSync(tmpPath); } catch {}
+    throw err;
+  }
+}

package/src/lib/schema.js

@@ -0,0 +1,68 @@
+/**
+ * Lightweight schema validation for AgentXchain protocol files.
+ * No external dependencies — validates shape and types only.
+ */
+
+export function validateLockSchema(data) {
+  const errors = [];
+  if (data === null || typeof data !== 'object') {
+    return { ok: false, errors: ['lock.json must be a JSON object'] };
+  }
+  if (!('holder' in data)) errors.push('Missing field: holder');
+  else if (data.holder !== null && typeof data.holder !== 'string') errors.push('holder must be a string or null');
+  if (!('turn_number' in data)) errors.push('Missing field: turn_number');
+  else if (typeof data.turn_number !== 'number' || !Number.isInteger(data.turn_number)) errors.push('turn_number must be an integer');
+  if (!('last_released_by' in data)) errors.push('Missing field: last_released_by');
+  else if (data.last_released_by !== null && typeof data.last_released_by !== 'string') errors.push('last_released_by must be a string or null');
+  if (!('claimed_at' in data)) errors.push('Missing field: claimed_at');
+  else if (data.claimed_at !== null && typeof data.claimed_at !== 'string') errors.push('claimed_at must be a string or null');
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateStateSchema(data) {
+  const errors = [];
+  if (data === null || typeof data !== 'object') {
+    return { ok: false, errors: ['state.json must be a JSON object'] };
+  }
+  if (typeof data.phase !== 'string') errors.push('phase must be a string');
+  if (typeof data.blocked !== 'boolean' && data.blocked !== undefined) errors.push('blocked must be a boolean');
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateConfigSchema(data) {
+  const errors = [];
+  if (data === null || typeof data !== 'object') {
+    return { ok: false, errors: ['agentxchain.json must be a JSON object'] };
+  }
+  if (data.version !== 3) errors.push('version must be 3');
+  if (typeof data.project !== 'string' || !data.project.trim()) errors.push('project must be a non-empty string');
+  if (!data.agents || typeof data.agents !== 'object') {
+    errors.push('agents must be an object');
+  } else {
+    for (const [id, agent] of Object.entries(data.agents)) {
+      if (!/^[a-z0-9_-]+$/.test(id)) errors.push(`Invalid agent id: "${id}" (must be lowercase alphanumeric, hyphens, underscores)`);
+      if (!agent || typeof agent !== 'object') { errors.push(`Agent "${id}" must be an object`); continue; }
+      if (typeof agent.name !== 'string' || !agent.name.trim()) errors.push(`Agent "${id}": name must be a non-empty string`);
+      if (typeof agent.mandate !== 'string' || !agent.mandate.trim()) errors.push(`Agent "${id}": mandate must be a non-empty string`);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Safely parse JSON with schema validation.
+ * Returns { ok, data, errors }.
+ */
+export function safeParseJson(raw, validator) {
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    return { ok: false, data: null, errors: [`Invalid JSON: ${err.message}`] };
+  }
+  if (validator) {
+    const result = validator(data);
+    return { ok: result.ok, data, errors: result.errors };
+  }
+  return { ok: true, data, errors: [] };
+}

package/src/lib/seed-prompt-polling.js

@@ -1,63 +1,20 @@
-export function generatePollingPrompt(agentId, agentDef, config, projectRoot = '.') {
-  const logFile = config.log || 'log.md';
-  const talkFile = config.talk_file || 'TALK.md';
-  const maxClaims = config.rules?.max_consecutive_claims || 2;
-  const verifyCmd = config.rules?.verify_command || null;
-  const stateFile = config.state_file || 'state.md';
-  const historyFile = config.history_file || 'history.jsonl';
-  const useSplit = config.state_file || config.history_file;
+import {
+  buildReadSection,
+  buildWriteSection,
+  buildVerifySection,
+  buildRulesSection,
+  buildPlanningDocsSection,
+} from './prompt-core.js';
 
+export function generatePollingPrompt(agentId, agentDef, config, projectRoot = '.') {
   const agentIds = Object.keys(config.agents);
   const myIndex = agentIds.indexOf(agentId);
-  const prevAgent = myIndex === 0 ? null : agentIds[myIndex - 1];
-  const isFirstAgent = myIndex === 0;
-
-  const turnCondition = isFirstAgent
-    ? `It is YOUR turn when lock.json shows holder=null AND (last_released_by is null, "human", "system", OR the LAST agent in the rotation: "${agentIds[agentIds.length - 1]}")`
-    : `It is YOUR turn when lock.json shows holder=null AND last_released_by="${prevAgent}"`;
-
-  const readSection = useSplit
-    ? `READ THESE FILES:
-- "${stateFile}" — the living project state. Read fully. Primary context.
-- "${historyFile}" — turn history. Read last 3 lines for recent context.
-- "${talkFile}" — team handoff updates. Read the latest 5 entries.
-- lock.json — who holds the lock.
-- state.json — phase and blocked status.`
-    : `READ THESE FILES:
-- "${logFile}" — the message log. Read last few messages.
-- "${talkFile}" — team handoff updates. Read the latest 5 entries.
-- lock.json — who holds the lock.
-- state.json — phase and blocked status.`;
-
-  const writeSection = useSplit
-    ? `WRITE (in this order):
-a. Do your actual work: write code, create files, run commands, make decisions.
-b. Update "${stateFile}" — OVERWRITE with current project state.
-c. Append ONE line to "${historyFile}":
-   {"turn": N, "agent": "${agentId}", "summary": "what you did", "files_changed": [...], "verify_result": "pass|fail|skipped", "timestamp": "ISO8601"}
-d. Append ONE handoff entry to "${talkFile}" with:
-   Turn, Status, Decision, Action, Risks/Questions, Next owner.
-e. Update state.json if phase or blocked status changed.`
-    : `WRITE (in this order):
-a. Do your actual work: write code, create files, run commands, make decisions.
-b. Append ONE message to ${logFile}:
-   ---
-   ### [${agentId}] (${agentDef.name}) | Turn N
-   **Status:** Current project state.
-   **Decision:** What you decided and why.
-   **Action:** What you did. Commands, files, results.
-   **Next:** What the next agent should focus on.
-c. Append ONE handoff entry to "${talkFile}" with:
-   Turn, Status, Decision, Action, Risks/Questions, Next owner.
-d. Update state.json if phase or blocked status changed.`;
-
-  const verifySection = verifyCmd
-    ? `
-VERIFY (mandatory before release):
-Run: ${verifyCmd}
-If it FAILS: fix the problem. Run again. Do NOT release with failing verification.
-If it PASSES: report the result. Then release.`
-    : '';
+
+  const readSection = buildReadSection(config, { includeTalk: true });
+  const writeSection = buildWriteSection(agentId, agentDef, config, { includeTalk: true });
+  const verifySection = buildVerifySection(config);
+  const rulesSection = buildRulesSection(agentId, config);
+  const planningDocs = buildPlanningDocsSection();
 
   return `You are "${agentId}" — ${agentDef.name}.
 
@@ -74,22 +31,7 @@ PROJECT ROOT (strict boundary):
 
 ---
 
-PROJECT DOCUMENTATION (.planning/ folder):
-
-These files give you project context. Read the ones relevant to your role.
-
-- .planning/PROJECT.md — Vision, constraints, stack decisions. PM writes this.
-- .planning/REQUIREMENTS.md — Scoped requirements with acceptance criteria. PM writes this.
-- .planning/ROADMAP.md — Phased delivery plan. PM maintains this.
-- .planning/research/ — Domain research, prior art, technical investigation.
-- .planning/phases/ — Per-phase plans (PLAN.md), reviews (REVIEW.md), test results (TESTS.md), bugs (BUGS.md).
-- .planning/qa/TEST-COVERAGE.md — Which features are tested and how. QA maintains this.
-- .planning/qa/BUGS.md — Open and fixed bugs with reproduction steps. QA maintains this.
-- .planning/qa/UX-AUDIT.md — UX checklist and visual/usability issues. QA maintains this.
-- .planning/qa/ACCEPTANCE-MATRIX.md — Requirements mapped to test status. QA maintains this.
-- .planning/qa/REGRESSION-LOG.md — Fixed bugs and their regression tests.
-
-When your role requires it, CREATE or UPDATE these files.
+${planningDocs}
 
 GET SHIT DONE FRAMEWORK (mandatory):
 - Plan in waves and phases (not ad hoc tasks).
@@ -101,9 +43,9 @@ GET SHIT DONE FRAMEWORK (mandatory):
 
 ---
 
-TEAM ROTATION: ${agentIds.join(' → ')} → (repeat)
+TEAM IDS: ${agentIds.join(', ')}
 YOUR POSITION: ${agentId} (index ${myIndex} of ${agentIds.length})
-${turnCondition}
+Turn assignment is handoff-driven: previous owner writes "Next owner" in TALK.md.
 
 ---
 
@@ -115,11 +57,11 @@ TURN MODE (single turn only, referee wakes you again later):
    - Never run broad searches outside this project root.
 
 1. READ lock.json.
+   Also read .agentxchain-trigger.json when present.
 
 2. CHECK — is it my turn?
-   ${isFirstAgent
-    ? `- It is your turn only when lock holder is null and last_released_by is null/human/system/${agentIds[agentIds.length - 1]}.`
-    : `- It is your turn only when lock holder is null and last_released_by is "${prevAgent}".`}
+   - It is your turn when lock holder is null AND trigger.agent is "${agentId}".
+   - If trigger file is missing, you may still attempt claim; claim guardrails enforce expected next owner.
    - If NOT your turn: STOP. Do not claim lock and do not write files.
 
 3. CLAIM the lock:
@@ -144,10 +86,6 @@ TURN MODE (single turn only, referee wakes you again later):
 ---
 
 CRITICAL RULES:
-- Never write files or code without holding the lock. Reading is always allowed.
-- One git commit per turn: "Turn N - ${agentId} - description"
-- Max ${maxClaims} consecutive turns. If you have held the lock ${maxClaims} times in a row, do a short turn and release.
-- ALWAYS release the lock. A stuck lock blocks the entire team.
-- ALWAYS find at least one problem, risk, or question about the previous work. Blind agreement is forbidden.
+${rulesSection}
 - This session is SINGLE-TURN. After release, STOP and wait for the referee to wake you again.`;
 }

package/src/lib/seed-prompt.js

@@ -1,46 +1,17 @@
-export function generateSeedPrompt(agentId, agentDef, config) {
-  const logFile = config.log || 'log.md';
-  const maxClaims = config.rules?.max_consecutive_claims || 2;
-  const verifyCmd = config.rules?.verify_command || null;
-  const stateFile = config.state_file || 'state.md';
-  const historyFile = config.history_file || 'history.jsonl';
-  const useSplit = config.state_file || config.history_file;
-
-  const stateSection = useSplit
-    ? `READ THESE FILES EVERY TURN:
-- "${stateFile}" — the living project state. Read fully. Primary context.
-- "${historyFile}" — turn history. Read last 3 lines for recent context.
-- lock.json — who holds the lock.
-- state.json — phase and blocked status.`
-    : `READ THESE FILES EVERY TURN:
-- "${logFile}" — the message log. Read last few messages.
-- lock.json — who holds the lock.
-- state.json — phase and blocked status.`;
-
-  const writeSection = useSplit
-    ? `WRITE (in this order):
-a. Do your actual work: write code, create files, run commands, make decisions.
-b. Update "${stateFile}" — OVERWRITE with current project state.
-c. Append ONE line to "${historyFile}":
-   {"turn": N, "agent": "${agentId}", "summary": "what you did", "files_changed": [...], "verify_result": "pass|fail|skipped", "timestamp": "ISO8601"}
-d. Update state.json if phase or blocked status changed.`
-    : `WRITE (in this order):
-a. Do your actual work: write code, create files, run commands, make decisions.
-b. Append ONE message to ${logFile}:
-   ---
-   ### [${agentId}] (${agentDef.name}) | Turn N
-   **Status:** Current project state.
-   **Decision:** What you decided and why.
-   **Action:** What you did. Commands, files, results.
-   **Next:** What the next agent should focus on.
-c. Update state.json if phase or blocked status changed.`;
+import {
+  buildReadSection,
+  buildWriteSection,
+  buildVerifySection,
+  buildRulesSection,
+  buildPlanningDocsSection,
+} from './prompt-core.js';
 
-  const verifySection = verifyCmd
-    ? `\nVERIFY (mandatory):
-Before releasing the lock, run: ${verifyCmd}
-If it FAILS: fix the problem. Run again. Do NOT release with failing verification.
-If it PASSES: report the result. Then release.`
-    : '';
+export function generateSeedPrompt(agentId, agentDef, config) {
+  const readSection = buildReadSection(config);
+  const writeSection = buildWriteSection(agentId, agentDef, config);
+  const verifySection = buildVerifySection(config);
+  const rulesSection = buildRulesSection(agentId, config);
+  const planningDocs = buildPlanningDocsSection();
 
   return `You are "${agentId}" — ${agentDef.name}.
 
@@ -48,22 +19,9 @@ ${agentDef.mandate}
 
 ---
 
-PROJECT DOCUMENTATION (.planning/ folder):
-
-These files give you project context. Read the ones relevant to your role.
-
-- .planning/PROJECT.md — Vision, constraints, stack decisions. PM writes this.
-- .planning/REQUIREMENTS.md — Scoped requirements with acceptance criteria. PM writes this.
-- .planning/ROADMAP.md — Phased delivery plan. PM maintains this.
-- .planning/research/ — Domain research, prior art, technical investigation.
-- .planning/phases/ — Per-phase plans (PLAN.md), reviews (REVIEW.md), test results (TESTS.md), bugs (BUGS.md).
-- .planning/qa/TEST-COVERAGE.md — Which features are tested and how. QA maintains this.
-- .planning/qa/BUGS.md — Open and fixed bugs with reproduction steps. QA maintains this.
-- .planning/qa/UX-AUDIT.md — UX checklist and visual/usability issues. QA maintains this.
-- .planning/qa/ACCEPTANCE-MATRIX.md — Requirements mapped to test status. QA maintains this.
-- .planning/qa/REGRESSION-LOG.md — Fixed bugs and their regression tests.
+${planningDocs}
 
-When your role requires it, CREATE or UPDATE these files. The PM creates PROJECT.md, REQUIREMENTS.md, ROADMAP.md on the first turn. QA creates phase test files and updates the qa/ docs every turn. Dev reads plans and writes code. Eng Director reads code and writes reviews.
+The PM creates PROJECT.md, REQUIREMENTS.md, ROADMAP.md on the first turn. QA creates phase test files and updates the qa/ docs every turn. Dev reads plans and writes code. Eng Director reads code and writes reviews.
 
 ---
 
@@ -73,16 +31,12 @@ The AgentXchain Watch process coordinates your team. You don't poll or wait. Whe
 
 YOUR TURN:
 1. CLAIM: Write lock.json with holder="${agentId}", claimed_at=now. Re-read to confirm.
-2. READ: ${stateSection}
+2. READ: ${readSection}
 3. THINK: What did the previous agent do? What's most important for YOUR role? What's one risk?
 4. ${writeSection}${verifySection}
 5. RELEASE: Write lock.json: holder=null, last_released_by="${agentId}", turn_number=previous+1, claimed_at=null.
    THIS MUST BE THE LAST THING YOU WRITE.
 
 HARD RULES:
-- Never write without holding the lock.
-- One commit per turn: "Turn N - ${agentId} - description"
-- Max ${maxClaims} consecutive turns. If limit hit, do a short turn and release.
-- ALWAYS release the lock. A stuck lock kills the whole team.
-- ALWAYS find at least one problem, risk, or question about the previous work. Blind agreement is forbidden.`;
+${rulesSection}`;
 }