substrate-ai 0.1.18 → 0.1.20

package/README.md

@@ -4,9 +4,9 @@
 
 # Substrate
 
-Autonomous software development pipeline powered by multi-agent orchestration. Substrate takes a project idea from concept through analysis, planning, architecture, implementation, and code review — coordinating CLI-based AI agents (Claude Code, Codex, Gemini CLI) to do the work.
+Substrate is an autonomous software development pipeline. Describe your project in plain language and Substrate handles the rest — coordinating multiple AI coding agents (Claude Code, Codex, Gemini CLI) working in parallel across isolated branches to take your idea from concept through implementation and code review.
 
-Substrate follows a modular monolith pattern running as a single Node.js process. The orchestrator never calls LLMs directly — all intelligent work is delegated to CLI agents running as child processes in isolated git worktrees. The autonomous pipeline compiles BMAD methodology workflows into token-efficient agent dispatches.
+Unlike API-based orchestrators, Substrate routes work through the CLI tools you already have installed, maximizing your existing AI subscriptions before falling back to pay-per-token billing. Runs are persistent and resumable — no lost work, no re-execution waste, full cost visibility across every provider.
 
 ## Prerequisites
 

package/dist/cli/index.js

@@ -7214,6 +7214,13 @@ const DEFAULT_TIMEOUTS = {
 * Only defined for task types that benefit from explicit turn budgets.
 */
 const DEFAULT_MAX_TURNS = {
+	"analysis": 15,
+	"planning": 20,
+	"architecture": 25,
+	"story-generation": 30,
+	"readiness-check": 20,
+	"elicitation": 15,
+	"critique": 15,
 	"dev-story": 75,
 	"major-rework": 50,
 	"code-review": 25,
@@ -7900,6 +7907,23 @@ function createDecision(db, input) {
 	return row;
 }
 /**
+* Insert or update a decision record.
+* If a decision with the same pipeline_run_id, category, and key already exists,
+* update its value and rationale. Otherwise, insert a new record.
+*/
+function upsertDecision(db, input) {
+	const validated = CreateDecisionInputSchema.parse(input);
+	const existing = db.prepare("SELECT * FROM decisions WHERE pipeline_run_id = ? AND category = ? AND key = ? LIMIT 1").get(validated.pipeline_run_id ?? null, validated.category, validated.key);
+	if (existing) {
+		updateDecision(db, existing.id, {
+			value: validated.value,
+			rationale: validated.rationale ?? void 0
+		});
+		return db.prepare("SELECT * FROM decisions WHERE id = ?").get(existing.id);
+	}
+	return createDecision(db, input);
+}
+/**
 * Get all decisions for a given phase, ordered by created_at ascending.
 */
 function getDecisionsByPhase(db, phase) {
@@ -7915,6 +7939,26 @@ function getDecisionsByPhaseForRun(db, runId, phase) {
 	return stmt.all(runId, phase);
 }
 /**
+* Update a decision's value and/or rationale and set updated_at.
+*/
+function updateDecision(db, id, updates) {
+	const setClauses = [];
+	const values = [];
+	if (updates.value !== void 0) {
+		setClauses.push("value = ?");
+		values.push(updates.value);
+	}
+	if (updates.rationale !== void 0) {
+		setClauses.push("rationale = ?");
+		values.push(updates.rationale);
+	}
+	if (setClauses.length === 0) return;
+	setClauses.push("updated_at = datetime('now')");
+	values.push(id);
+	const stmt = db.prepare(`UPDATE decisions SET ${setClauses.join(", ")} WHERE id = ?`);
+	stmt.run(...values);
+}
+/**
 * Insert a new requirement with status = 'active'.
 */
 function createRequirement(db, input) {
@@ -11835,12 +11879,14 @@ function createQualityGate(config) {
 
 //#endregion
 //#region src/modules/phase-orchestrator/phases/solutioning.ts
-/** Maximum total prompt token budget for architecture generation (3,000 tokens × 4 chars = 12,000 chars) */
-const MAX_ARCH_PROMPT_TOKENS = 3e3;
-const MAX_ARCH_PROMPT_CHARS = MAX_ARCH_PROMPT_TOKENS * 4;
-/** Maximum total prompt token budget for story generation (4,000 tokens × 4 chars = 16,000 chars) */
-const MAX_STORY_PROMPT_TOKENS = 4e3;
-const MAX_STORY_PROMPT_CHARS = MAX_STORY_PROMPT_TOKENS * 4;
+/** Base token budget for architecture generation (covers template + requirements) */
+const BASE_ARCH_PROMPT_TOKENS = 3e3;
+/** Base token budget for story generation (covers template + requirements + architecture) */
+const BASE_STORY_PROMPT_TOKENS = 4e3;
+/** Additional tokens per architecture decision injected into story generation prompt */
+const TOKENS_PER_DECISION = 100;
+/** Absolute maximum prompt tokens (model context safety margin) */
+const ABSOLUTE_MAX_PROMPT_TOKENS = 12e3;
 /** Placeholder in architecture prompt template */
 const REQUIREMENTS_PLACEHOLDER = "{{requirements}}";
 /** Amendment context framing block prefix */
@@ -11854,6 +11900,58 @@ const STORY_REQUIREMENTS_PLACEHOLDER = "{{requirements}}";
 const STORY_ARCHITECTURE_PLACEHOLDER = "{{architecture_decisions}}";
 /** Gap analysis placeholder used in retry prompt */
 const GAP_ANALYSIS_PLACEHOLDER = "{{gap_analysis}}";
+/** Priority order for decision categories when summarizing (higher priority kept first) */
+const DECISION_CATEGORY_PRIORITY = [
+	"data",
+	"auth",
+	"api",
+	"frontend",
+	"infra",
+	"observability",
+	"ci"
+];
+/**
+* Calculate the dynamic prompt token budget based on the number of decisions
+* that will be injected into the prompt.
+*
+* @param baseBudget - Base token budget for the phase
+* @param decisionCount - Number of decisions to inject
+* @returns Calculated token budget, capped at ABSOLUTE_MAX_PROMPT_TOKENS
+*/
+function calculateDynamicBudget(baseBudget, decisionCount) {
+	const budget = baseBudget + decisionCount * TOKENS_PER_DECISION;
+	return Math.min(budget, ABSOLUTE_MAX_PROMPT_TOKENS);
+}
+/**
+* Summarize architecture decisions into compact key:value one-liners,
+* dropping rationale and optionally dropping lower-priority categories
+* to fit within a character budget.
+*
+* @param decisions - Full architecture decisions from the decision store
+* @param maxChars - Maximum character budget for the summarized output
+* @returns Compact summary string
+*/
+function summarizeDecisions(decisions, maxChars) {
+	const sorted = [...decisions].sort((a, b) => {
+		const aCat = (a.category ?? "").toLowerCase();
+		const bCat = (b.category ?? "").toLowerCase();
+		const aIdx = DECISION_CATEGORY_PRIORITY.indexOf(aCat);
+		const bIdx = DECISION_CATEGORY_PRIORITY.indexOf(bCat);
+		const aPri = aIdx === -1 ? DECISION_CATEGORY_PRIORITY.length : aIdx;
+		const bPri = bIdx === -1 ? DECISION_CATEGORY_PRIORITY.length : bIdx;
+		return aPri - bPri;
+	});
+	const lines = ["## Architecture Decisions (Summarized)"];
+	let currentLength = lines[0].length;
+	for (const d of sorted) {
+		const truncatedValue = d.value.length > 120 ? d.value.slice(0, 117) + "..." : d.value;
+		const line = `- ${d.key}: ${truncatedValue}`;
+		if (currentLength + line.length + 1 > maxChars) break;
+		lines.push(line);
+		currentLength += line.length + 1;
+	}
+	return lines.join("\n");
+}
 /**
 * Format functional and non-functional requirements from the planning phase
 * into a compact text block suitable for prompt injection.
@@ -11932,17 +12030,19 @@ async function runArchitectureGeneration(deps, params) {
 	const template = await pack.getPrompt("architecture");
 	const formattedRequirements = formatRequirements(db, runId);
 	let prompt = template.replace(REQUIREMENTS_PLACEHOLDER, formattedRequirements);
+	const dynamicBudgetTokens = calculateDynamicBudget(BASE_ARCH_PROMPT_TOKENS, 0);
+	const dynamicBudgetChars = dynamicBudgetTokens * 4;
 	if (amendmentContext !== void 0 && amendmentContext !== "") {
 		const framingLen = AMENDMENT_CONTEXT_HEADER.length + AMENDMENT_CONTEXT_FOOTER.length;
-		const availableForContext = MAX_ARCH_PROMPT_CHARS - prompt.length - framingLen - TRUNCATED_MARKER.length;
+		const availableForContext = dynamicBudgetChars - prompt.length - framingLen - TRUNCATED_MARKER.length;
 		let contextToInject = amendmentContext;
 		if (availableForContext <= 0) contextToInject = "";
 		else if (amendmentContext.length > availableForContext) contextToInject = amendmentContext.slice(0, availableForContext) + TRUNCATED_MARKER;
 		if (contextToInject !== "") prompt += AMENDMENT_CONTEXT_HEADER + contextToInject + AMENDMENT_CONTEXT_FOOTER;
 	}
 	const estimatedTokens = Math.ceil(prompt.length / 4);
-	if (estimatedTokens > MAX_ARCH_PROMPT_TOKENS) return {
-		error: `Architecture prompt exceeds token budget: ${estimatedTokens} tokens (max ${MAX_ARCH_PROMPT_TOKENS})`,
+	if (estimatedTokens > dynamicBudgetTokens) return {
+		error: `Architecture prompt exceeds token budget: ${estimatedTokens} tokens (max ${dynamicBudgetTokens})`,
 		tokenUsage: zeroTokenUsage
 	};
 	const handle = dispatcher.dispatch({
@@ -11974,7 +12074,7 @@ async function runArchitectureGeneration(deps, params) {
 		tokenUsage
 	};
 	const decisions = parsed.architecture_decisions;
-	for (const decision of decisions) createDecision(db, {
+	for (const decision of decisions) upsertDecision(db, {
 		pipeline_run_id: runId,
 		phase: "solutioning",
 		category: "architecture",
@@ -12017,20 +12117,34 @@ async function runStoryGeneration(deps, params, gapAnalysis) {
 	};
 	const template = await pack.getPrompt("story-generation");
 	const formattedRequirements = formatRequirements(db, runId);
-	const formattedArchitecture = formatArchitectureDecisions(db, runId);
+	const archDecisions = getDecisionsByPhaseForRun(db, runId, "solutioning").filter((d) => d.category === "architecture");
+	const dynamicBudgetTokens = calculateDynamicBudget(BASE_STORY_PROMPT_TOKENS, archDecisions.length);
+	const dynamicBudgetChars = dynamicBudgetTokens * 4;
+	let formattedArchitecture = formatArchitectureDecisions(db, runId);
 	let prompt = template.replace(STORY_REQUIREMENTS_PLACEHOLDER, formattedRequirements).replace(STORY_ARCHITECTURE_PLACEHOLDER, formattedArchitecture);
 	if (gapAnalysis !== void 0) prompt = prompt.replace(GAP_ANALYSIS_PLACEHOLDER, gapAnalysis);
 	if (amendmentContext !== void 0 && amendmentContext !== "") {
 		const framingLen = AMENDMENT_CONTEXT_HEADER.length + AMENDMENT_CONTEXT_FOOTER.length;
-		const availableForContext = MAX_STORY_PROMPT_CHARS - prompt.length - framingLen - TRUNCATED_MARKER.length;
+		const availableForContext = dynamicBudgetChars - prompt.length - framingLen - TRUNCATED_MARKER.length;
 		let contextToInject = amendmentContext;
 		if (availableForContext <= 0) contextToInject = "";
 		else if (amendmentContext.length > availableForContext) contextToInject = amendmentContext.slice(0, availableForContext) + TRUNCATED_MARKER;
 		if (contextToInject !== "") prompt += AMENDMENT_CONTEXT_HEADER + contextToInject + AMENDMENT_CONTEXT_FOOTER;
 	}
-	const estimatedTokens = Math.ceil(prompt.length / 4);
-	if (estimatedTokens > MAX_STORY_PROMPT_TOKENS) return {
-		error: `Story generation prompt exceeds token budget: ${estimatedTokens} tokens (max ${MAX_STORY_PROMPT_TOKENS})`,
+	let estimatedTokens = Math.ceil(prompt.length / 4);
+	if (estimatedTokens > dynamicBudgetTokens) {
+		const availableForDecisions = dynamicBudgetChars - (prompt.length - formattedArchitecture.length);
+		formattedArchitecture = summarizeDecisions(archDecisions.map((d) => ({
+			key: d.key,
+			value: d.value,
+			category: d.category
+		})), Math.max(availableForDecisions, 200));
+		prompt = template.replace(STORY_REQUIREMENTS_PLACEHOLDER, formattedRequirements).replace(STORY_ARCHITECTURE_PLACEHOLDER, formattedArchitecture);
+		if (gapAnalysis !== void 0) prompt = prompt.replace(GAP_ANALYSIS_PLACEHOLDER, gapAnalysis);
+		estimatedTokens = Math.ceil(prompt.length / 4);
+	}
+	if (estimatedTokens > dynamicBudgetTokens) return {
+		error: `Story generation prompt exceeds token budget: ${estimatedTokens} tokens (max ${dynamicBudgetTokens})`,
 		tokenUsage: zeroTokenUsage
 	};
 	const handle = dispatcher.dispatch({
@@ -12063,7 +12177,7 @@ async function runStoryGeneration(deps, params, gapAnalysis) {
 	};
 	const epics = parsed.epics;
 	for (const [epicIndex, epic] of epics.entries()) {
-		createDecision(db, {
+		upsertDecision(db, {
 			pipeline_run_id: runId,
 			phase: "solutioning",
 			category: "epics",
@@ -12073,7 +12187,7 @@ async function runStoryGeneration(deps, params, gapAnalysis) {
 				description: epic.description
 			})
 		});
-		for (const story of epic.stories) createDecision(db, {
+		for (const story of epic.stories) upsertDecision(db, {
 			pipeline_run_id: runId,
 			phase: "solutioning",
 			category: "stories",
@@ -12200,7 +12314,23 @@ async function runSolutioningPhase(deps, params) {
 	let totalInput = 0;
 	let totalOutput = 0;
 	try {
-		const archResult = await runArchitectureGeneration(deps, params);
+		const existingArchArtifact = getArtifactByTypeForRun(deps.db, params.runId, "solutioning", "architecture");
+		let archResult;
+		if (existingArchArtifact) {
+			const existingDecisions = getDecisionsByPhaseForRun(deps.db, params.runId, "solutioning").filter((d) => d.category === "architecture");
+			archResult = {
+				decisions: existingDecisions.map((d) => ({
+					key: d.key,
+					value: d.value,
+					rationale: d.rationale ?? ""
+				})),
+				artifactId: existingArchArtifact.id,
+				tokenUsage: {
+					input: 0,
+					output: 0
+				}
+			};
+		} else archResult = await runArchitectureGeneration(deps, params);
 		totalInput += archResult.tokenUsage.input;
 		totalOutput += archResult.tokenUsage.output;
 		if ("error" in archResult) return {
@@ -13824,6 +13954,7 @@ async function runFullPipeline(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, runId, { status: "failed" });
 					const errorMsg = `Analysis phase failed: ${result.error ?? "unknown error"}${result.details ? ` — ${result.details}` : ""}`;
 					if (outputFormat === "human") process.stderr.write(`Error: ${errorMsg}\n`);
 					else process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -13846,6 +13977,7 @@ async function runFullPipeline(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, runId, { status: "failed" });
 					const errorMsg = `Planning phase failed: ${result.error ?? "unknown error"}${result.details ? ` — ${result.details}` : ""}`;
 					if (outputFormat === "human") process.stderr.write(`Error: ${errorMsg}\n`);
 					else process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -13868,6 +14000,7 @@ async function runFullPipeline(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, runId, { status: "failed" });
 					const errorMsg = `Solutioning phase failed: ${result.error ?? "unknown error"}${result.details ? ` — ${result.details}` : ""}`;
 					if (outputFormat === "human") process.stderr.write(`Error: ${errorMsg}\n`);
 					else process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -14141,6 +14274,7 @@ async function runFullPipelineFromPhase(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, runId, { status: "failed" });
 					const errorMsg = `Analysis phase failed: ${result.error ?? "unknown error"}`;
 					if (outputFormat === "human") process.stderr.write(`Error: ${errorMsg}\n`);
 					else process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -14160,6 +14294,7 @@ async function runFullPipelineFromPhase(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, runId, { status: "failed" });
 					const errorMsg = `Planning phase failed: ${result.error ?? "unknown error"}`;
 					if (outputFormat === "human") process.stderr.write(`Error: ${errorMsg}\n`);
 					else process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -14179,6 +14314,7 @@ async function runFullPipelineFromPhase(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, runId, { status: "failed" });
 					const errorMsg = `Solutioning phase failed: ${result.error ?? "unknown error"}`;
 					if (outputFormat === "human") process.stderr.write(`Error: ${errorMsg}\n`);
 					else process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -14552,6 +14688,7 @@ async function runAmendCommand(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, amendmentRunId, { status: "failed" });
 					process.stderr.write(`Error: Analysis phase failed: ${result.error ?? "unknown error"}${result.details ? ` — ${result.details}` : ""}\n`);
 					return 1;
 				}
@@ -14573,6 +14710,7 @@ async function runAmendCommand(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, amendmentRunId, { status: "failed" });
 					process.stderr.write(`Error: Planning phase failed: ${result.error ?? "unknown error"}${result.details ? ` — ${result.details}` : ""}\n`);
 					return 1;
 				}
@@ -14594,6 +14732,7 @@ async function runAmendCommand(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, amendmentRunId, { status: "failed" });
 					process.stderr.write(`Error: Solutioning phase failed: ${result.error ?? "unknown error"}${result.details ? ` — ${result.details}` : ""}\n`);
 					return 1;
 				}
@@ -15757,6 +15896,12 @@ function registerMonitorCommand(program, version = "0.0.0", projectRoot = proces
 //#endregion
 //#region src/cli/index.ts
 process.setMaxListeners(30);
+process.stdout.on("error", (err) => {
+	if (err.code === "EPIPE") process.exit(0);
+});
+process.stderr.on("error", (err) => {
+	if (err.code === "EPIPE") process.exit(0);
+});
 const logger = createLogger("cli");
 /** Resolve the package.json path relative to this file */
 async function getPackageVersion() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",
@@ -64,6 +64,7 @@
     "js-yaml": "^4.1.1",
     "pino": "^9.6.0",
     "semver": "^7.6.3",
+    "substrate-ai": "^0.1.19",
     "zod": "^4.3.6"
   },
   "devDependencies": {