substrate-ai 0.19.49 → 0.19.50

package/dist/cli/index.js

@@ -1862,6 +1862,72 @@ async function scaffoldClaudeMd(projectRoot, profile) {
 	await writeFile(claudeMdPath, newContent, "utf8");
 	logger$15.info({ claudeMdPath }, "Wrote substrate section to CLAUDE.md");
 }
+async function scaffoldAgentsMd(projectRoot, profile) {
+	const agentsMdPath = join(projectRoot, "AGENTS.md");
+	const pkgRoot = findPackageRoot(__dirname);
+	const templateName = "agents-md-substrate-section.md";
+	let templatePath = join(pkgRoot, "dist", "cli", "templates", templateName);
+	if (!existsSync$1(templatePath)) templatePath = join(pkgRoot, "src", "cli", "templates", templateName);
+	let sectionContent;
+	try {
+		sectionContent = await readFile(templatePath, "utf8");
+	} catch {
+		logger$15.warn({ templatePath }, "AGENTS.md substrate section template not found; skipping");
+		return;
+	}
+	const substrateVersion = readSubstrateVersion(pkgRoot);
+	sectionContent = sectionContent.replace("{{SUBSTRATE_VERSION}}", substrateVersion);
+	if (!sectionContent.endsWith("\n")) sectionContent += "\n";
+	const devNotesSection = buildStackAwareDevNotes(profile ?? null);
+	let existingContent = "";
+	let fileExists$1 = false;
+	try {
+		existingContent = await readFile(agentsMdPath, "utf8");
+		fileExists$1 = true;
+	} catch {}
+	let newContent;
+	if (!fileExists$1) newContent = devNotesSection ? devNotesSection + "\n\n" + sectionContent : sectionContent;
+	else if (existingContent.includes(CLAUDE_MD_START_MARKER)) newContent = existingContent.replace(new RegExp(`${CLAUDE_MD_START_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${CLAUDE_MD_END_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`), sectionContent.trimEnd());
+	else {
+		const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
+		newContent = existingContent + separator + sectionContent;
+	}
+	await writeFile(agentsMdPath, newContent, "utf8");
+	logger$15.info({ agentsMdPath }, "Wrote substrate section to AGENTS.md");
+}
+async function scaffoldGeminiMd(projectRoot, profile) {
+	const geminiMdPath = join(projectRoot, "GEMINI.md");
+	const pkgRoot = findPackageRoot(__dirname);
+	const templateName = "gemini-md-substrate-section.md";
+	let templatePath = join(pkgRoot, "dist", "cli", "templates", templateName);
+	if (!existsSync$1(templatePath)) templatePath = join(pkgRoot, "src", "cli", "templates", templateName);
+	let sectionContent;
+	try {
+		sectionContent = await readFile(templatePath, "utf8");
+	} catch {
+		logger$15.warn({ templatePath }, "GEMINI.md substrate section template not found; skipping");
+		return;
+	}
+	const substrateVersion = readSubstrateVersion(pkgRoot);
+	sectionContent = sectionContent.replace("{{SUBSTRATE_VERSION}}", substrateVersion);
+	if (!sectionContent.endsWith("\n")) sectionContent += "\n";
+	const devNotesSection = buildStackAwareDevNotes(profile ?? null);
+	let existingContent = "";
+	let fileExists$1 = false;
+	try {
+		existingContent = await readFile(geminiMdPath, "utf8");
+		fileExists$1 = true;
+	} catch {}
+	let newContent;
+	if (!fileExists$1) newContent = devNotesSection ? devNotesSection + "\n\n" + sectionContent : sectionContent;
+	else if (existingContent.includes(CLAUDE_MD_START_MARKER)) newContent = existingContent.replace(new RegExp(`${CLAUDE_MD_START_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${CLAUDE_MD_END_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`), sectionContent.trimEnd());
+	else {
+		const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
+		newContent = existingContent + separator + sectionContent;
+	}
+	await writeFile(geminiMdPath, newContent, "utf8");
+	logger$15.info({ geminiMdPath }, "Wrote substrate section to GEMINI.md");
+}
 async function scaffoldStatuslineScript(projectRoot) {
 	const pkgRoot = findPackageRoot(__dirname);
 	const templateName = "statusline.sh";
@@ -2441,6 +2507,8 @@ async function runInitAction(options) {
 		await initSchema(dbAdapter);
 		await dbAdapter.close();
 		await scaffoldClaudeMd(projectRoot, detectedProfile);
+		await scaffoldAgentsMd(projectRoot, detectedProfile);
+		await scaffoldGeminiMd(projectRoot, detectedProfile);
 		await scaffoldStatuslineScript(projectRoot);
 		await scaffoldClaudeSettings(projectRoot);
 		await scaffoldClaudeCommands(projectRoot, outputFormat);
@@ -2512,6 +2580,8 @@ async function runInitAction(options) {
 			}
 			process.stdout.write(`  Scaffolded:\n`);
 			process.stdout.write(`    CLAUDE.md             pipeline instructions for Claude Code\n`);
+			process.stdout.write(`    AGENTS.md             pipeline instructions for Codex CLI\n`);
+			process.stdout.write(`    GEMINI.md             pipeline instructions for Gemini CLI\n`);
 			process.stdout.write(`    .claude/commands/     /substrate-run, /substrate-supervisor, /substrate-metrics\n`);
 			process.stdout.write(`    .substrate/           config, database, routing policy\n`);
 			if (doltInitialized) process.stdout.write(`✓ Dolt state store initialized at .substrate/state/\n`);

package/dist/cli/templates/agents-md-substrate-section.md

@@ -0,0 +1,63 @@
+<!-- substrate:start -->
+<!-- substrate:version={{SUBSTRATE_VERSION}} -->
+## Substrate Pipeline
+
+This project uses Substrate for automated implementation pipelines. When asked to implement, build, or run the pipeline, go straight to running substrate. Do not explore the codebase, read source files, or plan the implementation yourself. Substrate orchestrates sub-agents that handle all of that.
+
+### Running the Pipeline
+
+Substrate auto-detects which pipeline phase to start from (analysis, planning, solutioning, implementation) and auto-discovers pending stories.
+
+```
+substrate run --events
+```
+
+To target specific stories:
+```
+substrate run --events --stories 1-1,1-2,1-3
+```
+
+If substrate needs input it can't auto-detect (e.g., a project concept for analysis), it will exit with a clear error message telling you what to provide.
+
+Scope warning: Without `--stories`, substrate auto-discovers ALL pending stories across ALL epics and may dispatch 30+ stories at once. For controlled runs, always specify story keys explicitly with `--stories`.
+
+Execution rules:
+- Pipeline runs take 5-40 minutes. Use long timeouts.
+- Never pipe substrate output to head, tail, grep, or any command that may close the pipe early.
+- For full event protocol and command reference: `substrate run --help-agent`
+
+### Monitoring
+
+Poll status periodically (every 60-90s):
+```
+substrate status --output-format json
+```
+
+Check process health:
+```
+substrate health --output-format json
+```
+
+### After Pipeline Completes
+
+1. Summarize results: X succeeded, Y failed, Z escalated
+2. Check metrics: `substrate metrics --output-format json`
+
+### Handling Escalations
+
+- On story escalation: read the flagged files and issues, propose a fix, ask the user before applying
+- On minor fix verdict (NEEDS_MINOR_FIXES): offer to fix automatically
+- On build verification failure: read the build output, diagnose the error, propose a fix
+- Never re-run a failed story without explicit user confirmation
+
+### Key Commands
+
+| Command | Purpose |
+|---|---|
+| `substrate run --events` | Run pipeline with NDJSON event stream |
+| `substrate status --output-format json` | Poll current pipeline state |
+| `substrate health --output-format json` | Check process health |
+| `substrate metrics --output-format json` | View historical run metrics |
+| `substrate resume` | Resume an interrupted pipeline run |
+| `substrate run --help-agent` | Full agent instruction reference |
+<!-- substrate:end -->

package/dist/cli/templates/gemini-md-substrate-section.md

@@ -0,0 +1,63 @@
+<!-- substrate:start -->
+<!-- substrate:version={{SUBSTRATE_VERSION}} -->
+## Substrate Pipeline
+
+This project uses Substrate for automated implementation pipelines. When asked to implement, build, or run the pipeline, go straight to running substrate. Do not explore the codebase, read source files, or plan the implementation yourself. Substrate orchestrates sub-agents that handle all of that.
+
+### Running the Pipeline
+
+Substrate auto-detects which pipeline phase to start from (analysis, planning, solutioning, implementation) and auto-discovers pending stories.
+
+```
+substrate run --events
+```
+
+To target specific stories:
+```
+substrate run --events --stories 1-1,1-2,1-3
+```
+
+If substrate needs input it can't auto-detect (e.g., a project concept for analysis), it will exit with a clear error message telling you what to provide.
+
+Scope warning: Without `--stories`, substrate auto-discovers ALL pending stories across ALL epics and may dispatch 30+ stories at once. For controlled runs, always specify story keys explicitly with `--stories`.
+
+Execution rules:
+- Pipeline runs take 5-40 minutes. Use long timeouts.
+- Never pipe substrate output to head, tail, grep, or any command that may close the pipe early.
+- For full event protocol and command reference: `substrate run --help-agent`
+
+### Monitoring
+
+Poll status periodically (every 60-90s):
+```
+substrate status --output-format json
+```
+
+Check process health:
+```
+substrate health --output-format json
+```
+
+### After Pipeline Completes
+
+1. Summarize results: X succeeded, Y failed, Z escalated
+2. Check metrics: `substrate metrics --output-format json`
+
+### Handling Escalations
+
+- On story escalation: read the flagged files and issues, propose a fix, ask the user before applying
+- On minor fix verdict (NEEDS_MINOR_FIXES): offer to fix automatically
+- On build verification failure: read the build output, diagnose the error, propose a fix
+- Never re-run a failed story without explicit user confirmation
+
+### Key Commands
+
+| Command | Purpose |
+|---|---|
+| `substrate run --events` | Run pipeline with NDJSON event stream |
+| `substrate status --output-format json` | Poll current pipeline state |
+| `substrate health --output-format json` | Check process health |
+| `substrate metrics --output-format json` | View historical run metrics |
+| `substrate resume` | Resume an interrupted pipeline run |
+| `substrate run --help-agent` | Full agent instruction reference |
+<!-- substrate:end -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.19.49",
+  "version": "0.19.50",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",