@kodrunhq/opencode-autopilot 1.12.2 → 1.14.0

package/src/orchestrator/handlers/architect.ts

@@ -27,11 +27,14 @@ export async function handleArchitect(
 	artifactDir: string,
 	_result?: string,
 ): Promise<DispatchResult> {
+	// _result is received from the orchestrator but completion is determined by
+	// artifact existence (design.md/critique.md), not by result truthiness.
+	// This preserves the three-step arena flow: proposals → critic → complete.
 	const phaseDir = getPhaseDir(artifactDir, "ARCHITECT");
 	const critiqueExists = await fileExists(join(phaseDir, "critique.md"));
 	const designExists = await fileExists(join(phaseDir, "design.md"));
 
-	// Step 3: critique or design exists -> complete
+	// Step 3: critique or design exists -> complete (idempotency on resume)
 	if (critiqueExists || designExists) {
 		return Object.freeze({
 			action: "complete" as const,
@@ -49,9 +52,9 @@ export async function handleArchitect(
 			action: "dispatch" as const,
 			agent: AGENT_NAMES.CRITIC,
 			prompt: [
-				`Review architecture proposals in phases/ARCHITECT/proposals/`,
-				`Read ${getArtifactRef("RECON", "report.md")} and ${getArtifactRef("CHALLENGE", "brief.md")} for context.`,
-				`Write comparative critique to ${getArtifactRef("ARCHITECT", "critique.md")}`,
+				`Review architecture proposals in ${proposalsDir}/`,
+				`Read ${getArtifactRef(artifactDir, "RECON", "report.md")} and ${getArtifactRef(artifactDir, "CHALLENGE", "brief.md")} for context.`,
+				`Write comparative critique to ${getArtifactRef(artifactDir, "ARCHITECT", "critique.md")}`,
 				`Include: strengths, weaknesses, recommendation, confidence (HIGH/MEDIUM/LOW).`,
 			].join("\n"),
 			phase: "ARCHITECT",
@@ -63,8 +66,8 @@ export async function handleArchitect(
 	await ensurePhaseDir(artifactDir, "ARCHITECT");
 	const reconEntries = filterByPhase(state.confidence, "RECON");
 	const depth = getMemoryTunedDepth(reconEntries, join(artifactDir, ".."));
-	const reconRef = getArtifactRef("RECON", "report.md");
-	const challengeRef = getArtifactRef("CHALLENGE", "brief.md");
+	const reconRef = getArtifactRef(artifactDir, "RECON", "report.md");
+	const challengeRef = getArtifactRef(artifactDir, "CHALLENGE", "brief.md");
 	const safeIdea = sanitizeTemplateContent(state.idea).replace(/[\r\n]+/g, " ");
 
 	if (depth === 1) {
@@ -74,7 +77,7 @@ export async function handleArchitect(
 			prompt: [
 				`Read ${reconRef} and ${challengeRef} for context.`,
 				`Design architecture for: ${safeIdea}`,
-				`Write design to ${getArtifactRef("ARCHITECT", "design.md")}`,
+				`Write design to ${getArtifactRef(artifactDir, "ARCHITECT", "design.md")}`,
 				`Include: component diagram, data flow, technology choices, confidence (HIGH/MEDIUM/LOW).`,
 			].join("\n"),
 			phase: "ARCHITECT",
@@ -90,7 +93,7 @@ export async function handleArchitect(
 				`Read ${reconRef} and ${challengeRef} for context.`,
 				`Design architecture for: ${safeIdea}`,
 				`Constraint: ${constraint}`,
-				`Write proposal to phases/ARCHITECT/proposals/proposal-${label}.md`,
+				`Write proposal to ${join(proposalsDir, `proposal-${label}.md`)}`,
 				`Include: component diagram, data flow, technology choices, confidence (HIGH/MEDIUM/LOW).`,
 			].join("\n"),
 		});

package/src/orchestrator/handlers/build.ts

@@ -55,9 +55,9 @@ function markTasksInProgress(tasks: readonly Task[], taskIds: readonly number[])
 /**
  * Build a prompt for a single task dispatch.
  */
-function buildTaskPrompt(task: Task): string {
-	const planRef = getArtifactRef("PLAN", "tasks.md");
-	const designRef = getArtifactRef("ARCHITECT", "design.md");
+function buildTaskPrompt(task: Task, artifactDir: string): string {
+	const planRef = getArtifactRef(artifactDir, "PLAN", "tasks.md");
+	const designRef = getArtifactRef(artifactDir, "ARCHITECT", "design.md");
 	return [
 		`Implement task ${task.id}: ${task.title}.`,
 		`Reference the plan at ${planRef}`,
@@ -110,7 +110,7 @@ function hasCriticalFindings(resultStr: string): boolean {
 	}
 }
 
-export const handleBuild: PhaseHandler = async (state, _artifactDir, result?) => {
+export const handleBuild: PhaseHandler = async (state, artifactDir, result?) => {
 	const { tasks, buildProgress } = state;
 
 	// Edge case: no tasks
@@ -159,6 +159,8 @@ export const handleBuild: PhaseHandler = async (state, _artifactDir, result?) =>
 		const blockedIds = nonDoneTasks.map((t) => t.id).join(", ");
 		return Object.freeze({
 			action: "error" as const,
+			phase: "BUILD",
+			message: `All remaining tasks are BLOCKED due to dependency cycles: [${blockedIds}]`,
 			progress: `All remaining tasks are BLOCKED due to dependency cycles: [${blockedIds}]`,
 			_stateUpdates: Object.freeze({
 				buildProgress: Object.freeze({
@@ -177,7 +179,7 @@ export const handleBuild: PhaseHandler = async (state, _artifactDir, result?) =>
 			const prompt = [
 				`CRITICAL review findings detected. Fix the following issues:`,
 				safeResult,
-				`Reference ${getArtifactRef("PLAN", "tasks.md")} for context.`,
+				`Reference ${getArtifactRef(artifactDir, "PLAN", "tasks.md")} for context.`,
 			].join(" ");
 
 			return Object.freeze({
@@ -225,7 +227,7 @@ export const handleBuild: PhaseHandler = async (state, _artifactDir, result?) =>
 			return Object.freeze({
 				action: "dispatch",
 				agent: AGENT_NAMES.BUILD,
-				prompt: buildTaskPrompt(task),
+				prompt: buildTaskPrompt(task, artifactDir),
 				phase: "BUILD",
 				progress: `Wave ${nextWave} — task ${task.id}`,
 				_stateUpdates: {
@@ -239,7 +241,7 @@ export const handleBuild: PhaseHandler = async (state, _artifactDir, result?) =>
 			action: "dispatch_multi",
 			agents: pendingTasks.map((task) => ({
 				agent: AGENT_NAMES.BUILD,
-				prompt: buildTaskPrompt(task),
+				prompt: buildTaskPrompt(task, artifactDir),
 			})),
 			phase: "BUILD",
 			progress: `Wave ${nextWave} — ${pendingTasks.length} concurrent tasks`,
@@ -285,7 +287,7 @@ export const handleBuild: PhaseHandler = async (state, _artifactDir, result?) =>
 			return Object.freeze({
 				action: "dispatch",
 				agent: AGENT_NAMES.BUILD,
-				prompt: buildTaskPrompt(next),
+				prompt: buildTaskPrompt(next, artifactDir),
 				phase: "BUILD",
 				progress: `Wave ${currentWave} — task ${next.id}`,
 				_stateUpdates: {
@@ -367,7 +369,7 @@ export const handleBuild: PhaseHandler = async (state, _artifactDir, result?) =>
 		return Object.freeze({
 			action: "dispatch",
 			agent: AGENT_NAMES.BUILD,
-			prompt: buildTaskPrompt(task),
+			prompt: buildTaskPrompt(task, artifactDir),
 			phase: "BUILD",
 			progress: `Wave ${currentWave} — task ${task.id}`,
 			_stateUpdates: {
@@ -386,7 +388,7 @@ export const handleBuild: PhaseHandler = async (state, _artifactDir, result?) =>
 		action: "dispatch_multi",
 		agents: pendingTasks.map((task) => ({
 			agent: AGENT_NAMES.BUILD,
-			prompt: buildTaskPrompt(task),
+			prompt: buildTaskPrompt(task, artifactDir),
 		})),
 		phase: "BUILD",
 		progress: `Wave ${currentWave} — ${pendingTasks.length} concurrent tasks`,

package/src/orchestrator/handlers/challenge.ts

@@ -1,4 +1,5 @@
 import { sanitizeTemplateContent } from "../../review/sanitize";
+import { fileExists } from "../../utils/fs-helpers";
 import { ensurePhaseDir, getArtifactRef } from "../artifacts";
 import type { PipelineState } from "../types";
 import { AGENT_NAMES, type DispatchResult } from "./types";
@@ -13,6 +14,11 @@ export async function handleChallenge(
 	result?: string,
 ): Promise<DispatchResult> {
 	if (result) {
+		// Warn if artifact wasn't written (best-effort — still complete the phase)
+		const artifactPath = getArtifactRef(artifactDir, "CHALLENGE", "brief.md");
+		if (!(await fileExists(artifactPath))) {
+			console.warn("[opencode-autopilot] CHALLENGE completed but artifact not found");
+		}
 		return Object.freeze({
 			action: "complete" as const,
 			phase: "CHALLENGE",
@@ -21,8 +27,8 @@ export async function handleChallenge(
 	}
 
 	await ensurePhaseDir(artifactDir, "CHALLENGE");
-	const reconRef = getArtifactRef("RECON", "report.md");
-	const outputRef = getArtifactRef("CHALLENGE", "brief.md");
+	const reconRef = getArtifactRef(artifactDir, "RECON", "report.md");
+	const outputPath = getArtifactRef(artifactDir, "CHALLENGE", "brief.md");
 
 	const safeIdea = sanitizeTemplateContent(state.idea).replace(/[\r\n]+/g, " ");
 
@@ -32,7 +38,7 @@ export async function handleChallenge(
 		prompt: [
 			`Read ${reconRef} for research context.`,
 			`Original idea: ${safeIdea}`,
-			`Propose up to 3 enhancements. Write ambitious brief to ${outputRef}`,
+			`Propose up to 3 enhancements. Write ambitious brief to ${outputPath}`,
 			`For each: name, user value, complexity (LOW/MEDIUM/HIGH), accept/reject rationale.`,
 		].join("\n"),
 		phase: "CHALLENGE",

package/src/orchestrator/handlers/plan.ts

@@ -2,7 +2,7 @@ import { getArtifactRef } from "../artifacts";
 import type { DispatchResult, PhaseHandler } from "./types";
 import { AGENT_NAMES } from "./types";
 
-export const handlePlan: PhaseHandler = async (_state, _artifactDir, result?) => {
+export const handlePlan: PhaseHandler = async (_state, artifactDir, result?) => {
 	if (result) {
 		return Object.freeze({
 			action: "complete",
@@ -11,8 +11,9 @@ export const handlePlan: PhaseHandler = async (_state, _artifactDir, result?) =>
 		} satisfies DispatchResult);
 	}
 
-	const architectRef = getArtifactRef("ARCHITECT", "design.md");
-	const challengeRef = getArtifactRef("CHALLENGE", "brief.md");
+	const architectRef = getArtifactRef(artifactDir, "ARCHITECT", "design.md");
+	const challengeRef = getArtifactRef(artifactDir, "CHALLENGE", "brief.md");
+	const tasksPath = getArtifactRef(artifactDir, "PLAN", "tasks.md");
 
 	const prompt = [
 		"Read the architecture design at",
@@ -20,7 +21,7 @@ export const handlePlan: PhaseHandler = async (_state, _artifactDir, result?) =>
 		"and the challenge brief at",
 		challengeRef,
 		"then produce a task plan.",
-		"Write tasks to phases/PLAN/tasks.md.",
+		`Write tasks to ${tasksPath}.`,
 		"Each task should have a 300-line diff max.",
 		"Assign wave numbers for parallel execution.",
 	].join(" ");

package/src/orchestrator/handlers/recon.ts

@@ -1,4 +1,5 @@
 import { sanitizeTemplateContent } from "../../review/sanitize";
+import { fileExists } from "../../utils/fs-helpers";
 import { ensurePhaseDir, getArtifactRef } from "../artifacts";
 import type { PipelineState } from "../types";
 import { AGENT_NAMES, type DispatchResult } from "./types";
@@ -13,6 +14,11 @@ export async function handleRecon(
 	result?: string,
 ): Promise<DispatchResult> {
 	if (result) {
+		// Warn if artifact wasn't written (best-effort — still complete the phase)
+		const artifactPath = getArtifactRef(artifactDir, "RECON", "report.md");
+		if (!(await fileExists(artifactPath))) {
+			console.warn("[opencode-autopilot] RECON completed but artifact not found");
+		}
 		return Object.freeze({
 			action: "complete" as const,
 			phase: "RECON",
@@ -20,8 +26,8 @@ export async function handleRecon(
 		});
 	}
 
-	const phaseDir = await ensurePhaseDir(artifactDir, "RECON");
-	const outputRef = getArtifactRef("RECON", "report.md");
+	await ensurePhaseDir(artifactDir, "RECON");
+	const outputPath = getArtifactRef(artifactDir, "RECON", "report.md");
 
 	const safeIdea = sanitizeTemplateContent(state.idea).replace(/[\r\n]+/g, " ");
 
@@ -29,9 +35,8 @@ export async function handleRecon(
 		action: "dispatch" as const,
 		agent: AGENT_NAMES.RECON,
 		prompt: [
-			`Research the following idea and write findings to ${outputRef}`,
+			`Research the following idea and write findings to ${outputPath}`,
 			`Idea: ${safeIdea}`,
-			`Output: ${phaseDir}/report.md`,
 			`Include: Market Analysis, Technology Options, UX Considerations, Feasibility Assessment, Confidence (HIGH/MEDIUM/LOW)`,
 		].join("\n"),
 		phase: "RECON",

package/src/orchestrator/handlers/retrospective.ts

@@ -105,7 +105,9 @@ export const handleRetrospective: PhaseHandler = async (_state, artifactDir, res
 
 	const artifactRefs = Object.entries(PHASE_ARTIFACTS)
 		.filter(([phase, files]) => files.length > 0 && phase !== "RETROSPECTIVE")
-		.flatMap(([phase, files]) => files.map((file) => getArtifactRef(phase as Phase, file)));
+		.flatMap(([phase, files]) =>
+			files.map((file) => getArtifactRef(artifactDir, phase as Phase, file)),
+		);
 
 	const prompt = [
 		"Analyze all phase artifacts:",

package/src/orchestrator/handlers/ship.ts

@@ -1,8 +1,8 @@
-import { getArtifactRef } from "../artifacts";
+import { getArtifactRef, getPhaseDir } from "../artifacts";
 import type { DispatchResult, PhaseHandler } from "./types";
 import { AGENT_NAMES } from "./types";
 
-export const handleShip: PhaseHandler = async (_state, _artifactDir, result?) => {
+export const handleShip: PhaseHandler = async (_state, artifactDir, result?) => {
 	if (result) {
 		return Object.freeze({
 			action: "complete",
@@ -11,10 +11,11 @@ export const handleShip: PhaseHandler = async (_state, _artifactDir, result?) =>
 		} satisfies DispatchResult);
 	}
 
-	const reconRef = getArtifactRef("RECON", "report.md");
-	const challengeRef = getArtifactRef("CHALLENGE", "brief.md");
-	const architectRef = getArtifactRef("ARCHITECT", "design.md");
-	const planRef = getArtifactRef("PLAN", "tasks.md");
+	const reconRef = getArtifactRef(artifactDir, "RECON", "report.md");
+	const challengeRef = getArtifactRef(artifactDir, "CHALLENGE", "brief.md");
+	const architectRef = getArtifactRef(artifactDir, "ARCHITECT", "design.md");
+	const planRef = getArtifactRef(artifactDir, "PLAN", "tasks.md");
+	const shipDir = getPhaseDir(artifactDir, "SHIP");
 
 	const prompt = [
 		"Review all prior phase artifacts:",
@@ -25,7 +26,7 @@ export const handleShip: PhaseHandler = async (_state, _artifactDir, result?) =>
 		"Produce walkthrough.md (architecture overview),",
 		"decisions.md (key decisions with rationale),",
 		"changelog.md (user-facing changes).",
-		"Write output to phases/SHIP/.",
+		`Write output to ${shipDir}/.`,
 	].join(" ");
 
 	return Object.freeze({

package/src/orchestrator/handlers/types.ts

@@ -22,6 +22,7 @@ export interface DispatchResult {
 	readonly progress?: string;
 	readonly message?: string;
 	readonly _stateUpdates?: Partial<PipelineState>;
+	readonly _userProgress?: string;
 }
 
 export type PhaseHandler = (

package/src/orchestrator/lesson-memory.ts

@@ -9,6 +9,7 @@
  * to prevent corruption.
  */
 
+import { randomBytes } from "node:crypto";
 import { readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { ensureDir, isEnoentError } from "../utils/fs-helpers";
@@ -76,7 +77,7 @@ export async function saveLessonMemory(memory: LessonMemory, projectRoot: string
 	const dir = join(projectRoot, ".opencode-autopilot");
 	await ensureDir(dir);
 	const memoryPath = join(dir, LESSON_FILE);
-	const tmpPath = `${memoryPath}.tmp.${Date.now()}`;
+	const tmpPath = `${memoryPath}.tmp.${randomBytes(8).toString("hex")}`;
 	await writeFile(tmpPath, JSON.stringify(validated, null, 2), "utf-8");
 	await rename(tmpPath, memoryPath);
 }

package/src/orchestrator/orchestration-logger.ts

@@ -0,0 +1,40 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+export interface OrchestrationEvent {
+	readonly timestamp: string;
+	readonly phase: string;
+	readonly action: "dispatch" | "dispatch_multi" | "complete" | "error" | "loop_detected";
+	readonly agent?: string;
+	readonly promptLength?: number;
+	readonly attempt?: number;
+	readonly message?: string;
+}
+
+const LOG_FILE = "orchestration.jsonl";
+
+/** Rate-limit: warn about log failures at most once per process. */
+let logWriteWarned = false;
+
+/**
+ * Append an orchestration event to the project-local JSONL log.
+ * Uses synchronous append to survive crashes. Best-effort — errors are swallowed.
+ */
+export function logOrchestrationEvent(artifactDir: string, event: OrchestrationEvent): void {
+	try {
+		mkdirSync(artifactDir, { recursive: true });
+		const logPath = join(artifactDir, LOG_FILE);
+		// Redact filesystem paths from message to avoid leaking sensitive directory info
+		const safe = event.message
+			? { ...event, message: event.message.replace(/[/\\][^\s"']+/g, "[PATH]") }
+			: event;
+		const line = `${JSON.stringify(safe)}\n`;
+		appendFileSync(logPath, line, "utf-8");
+	} catch (err) {
+		// Best-effort — never block the pipeline. Warn once so operators know logging is broken.
+		if (!logWriteWarned) {
+			logWriteWarned = true;
+			console.warn("[opencode-autopilot] orchestration log write failed:", err);
+		}
+	}
+}

package/src/orchestrator/phase.ts

@@ -1,5 +1,19 @@
 import type { Phase, PhaseStatus, PipelineState } from "./types";
 
+/** Maps each phase to its 1-based position for user-facing progress display. */
+export const PHASE_INDEX: Readonly<Record<Phase, number>> = Object.freeze({
+	RECON: 1,
+	CHALLENGE: 2,
+	ARCHITECT: 3,
+	EXPLORE: 4,
+	PLAN: 5,
+	BUILD: 6,
+	SHIP: 7,
+	RETROSPECTIVE: 8,
+} satisfies Record<Phase, number>);
+
+export const TOTAL_PHASES = 8;
+
 /**
  * Maps each phase to its valid successor. RETROSPECTIVE is terminal (null).
  */

package/src/orchestrator/schemas.ts

@@ -84,4 +84,5 @@ export const pipelineStateSchema = z.object({
 		reviewPending: false,
 	}),
 	failureContext: failureContextSchema.nullable().default(null),
+	phaseDispatchCounts: z.record(z.string().max(32), z.number().int().min(0).max(1000)).default({}),
 });

package/src/orchestrator/skill-injection.ts

@@ -11,9 +11,10 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { sanitizeTemplateContent } from "../review/sanitize";
 import {
-	buildMultiSkillContext,
+	buildAdaptiveSkillContext,
 	detectProjectStackTags,
 	filterSkillsByStack,
+	type SkillMode,
 } from "../skills/adaptive-injector";
 import { loadAllSkills } from "../skills/loader";
 import { isEnoentError } from "../utils/fs-helpers";
@@ -69,7 +70,11 @@ export function buildSkillContext(skillContent: string): string {
 export async function loadAdaptiveSkillContext(
 	baseDir: string,
 	projectRoot: string,
-	tokenBudget?: number,
+	options?: {
+		readonly phase?: string;
+		readonly budget?: number;
+		readonly mode?: SkillMode;
+	},
 ): Promise<string> {
 	try {
 		const skillsDir = join(baseDir, "skills");
@@ -81,10 +86,10 @@ export async function loadAdaptiveSkillContext(
 		if (allSkills.size === 0) return "";
 
 		const matchingSkills = filterSkillsByStack(allSkills, projectTags);
-		return buildMultiSkillContext(matchingSkills, tokenBudget);
-	} catch {
-		// Best-effort: all errors return empty string. Caller (injectSkillContext)
-		// logs the error — no need to re-throw since the call site is also best-effort.
+		return buildAdaptiveSkillContext(matchingSkills, options);
+	} catch (err) {
+		// Best-effort: all errors return empty string.
+		console.warn("[opencode-autopilot] adaptive skill load failed:", err);
 		return "";
 	}
 }

package/src/orchestrator/state.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from "node:crypto";
 import { readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { ensureDir, isEnoentError } from "../utils/fs-helpers";
@@ -45,7 +46,7 @@ export async function saveState(state: PipelineState, artifactDir: string): Prom
 	const validated = pipelineStateSchema.parse(state);
 	await ensureDir(artifactDir);
 	const statePath = join(artifactDir, STATE_FILE);
-	const tmpPath = `${statePath}.tmp.${Date.now()}`;
+	const tmpPath = `${statePath}.tmp.${randomBytes(8).toString("hex")}`;
 	await writeFile(tmpPath, JSON.stringify(validated, null, 2), "utf-8");
 	await rename(tmpPath, statePath);
 }

package/src/review/selection.ts

@@ -1,10 +1,8 @@
 /**
- * Two-pass deterministic agent selection for the review pipeline.
+ * Deterministic agent selection for the review pipeline.
  *
- * Pass 1: Stack gate -- agents with empty relevantStacks always pass;
- *         agents with non-empty relevantStacks require at least one match.
- * Pass 2: Diff relevance scoring -- currently used for future ordering,
- *         all stack-passing agents run regardless of score.
+ * Stack gate: agents with empty relevantStacks always pass;
+ * agents with non-empty relevantStacks require at least one match.
  */
 
 /** Minimal agent shape needed for selection (compatible with ReviewAgent from agents/). */
@@ -38,7 +36,7 @@ export interface SelectionResult {
  */
 export function selectAgents(
 	detectedStacks: readonly string[],
-	diffAnalysis: DiffAnalysisInput,
+	_diffAnalysis: DiffAnalysisInput,
 	agents: readonly SelectableAgent[],
 ): SelectionResult {
 	const stackSet = new Set(detectedStacks);
@@ -65,34 +63,8 @@ export function selectAgents(
 		}
 	}
 
-	// Pass 2: Compute relevance scores (stored for future ordering, no filtering)
-	// Scores are intentionally not used for filtering yet
-	for (const agent of selected) {
-		computeDiffRelevance(agent, diffAnalysis);
-	}
-
 	return Object.freeze({
 		selected: Object.freeze(selected),
 		excluded: Object.freeze(excluded),
 	});
 }
-
-/**
- * Compute diff-based relevance score for an agent.
- * Base score of 1.0 with bonuses for specific agent-analysis matches.
- * Used for future prioritization/ordering, not for filtering.
- */
-export function computeDiffRelevance(agent: SelectableAgent, analysis: DiffAnalysisInput): number {
-	let score = 1.0;
-
-	if (agent.name === "security-auditor") {
-		if (analysis.hasAuth) score += 0.5;
-		if (analysis.hasConfig) score += 0.3;
-	}
-
-	if (agent.name === "test-interrogator") {
-		if (!analysis.hasTests) score += 0.5;
-	}
-
-	return score;
-}

package/src/skills/adaptive-injector.ts

@@ -18,6 +18,24 @@ const DEFAULT_TOKEN_BUDGET = 8000;
 /** Rough estimate: 1 token ~ 4 chars */
 const CHARS_PER_TOKEN = 4;
 
+/**
+ * Maps pipeline phases to the skill names relevant for that phase.
+ * Skills not in the list for the current phase are excluded from injection,
+ * preventing the full 13-19KB per-skill content from bloating every dispatch.
+ */
+export const PHASE_SKILL_MAP: Readonly<Record<string, readonly string[]>> = Object.freeze({
+	RECON: ["plan-writing"],
+	CHALLENGE: ["plan-writing"],
+	ARCHITECT: ["plan-writing"],
+	PLAN: ["plan-writing", "plan-executing"],
+	BUILD: ["coding-standards", "tdd-workflow"],
+	SHIP: ["plan-executing"],
+	RETROSPECTIVE: [],
+	EXPLORE: [],
+});
+
+export type SkillMode = "summary" | "full";
+
 /**
  * Manifest files that indicate project stack.
  * Checks project root for these files to detect the stack.
@@ -121,14 +139,40 @@ export function filterSkillsByStack(
 	return filtered;
 }
 
+/**
+ * Build a compact summary for a single skill: frontmatter name + description
+ * (max 200 chars). Used in summary mode to avoid injecting full skill content.
+ */
+export function buildSkillSummary(skill: LoadedSkill): string {
+	const { name, description } = skill.frontmatter;
+	const safeName = sanitizeTemplateContent(name);
+	const safeDesc = sanitizeTemplateContent((description ?? "").slice(0, 200));
+	return `[Skill: ${safeName}]\n${safeDesc}`;
+}
+
+/**
+ * In full mode, truncate skill content at the first `## ` heading boundary
+ * that exceeds the per-skill character budget. Preserves structure instead
+ * of collapsing all newlines.
+ */
+function truncateAtSectionBoundary(content: string, maxChars: number): string {
+	if (content.length <= maxChars) return content;
+	const cutPoint = content.lastIndexOf("\n## ", maxChars);
+	if (cutPoint > 0) return content.slice(0, cutPoint);
+	return content.slice(0, maxChars);
+}
+
 /**
  * Build multi-skill context string with dependency ordering and token budget.
  * Skills are ordered by dependency (prerequisites first), then concatenated
  * until the token budget is exhausted.
+ *
+ * @param mode - "summary" emits only name + description (compact); "full" preserves structure
  */
 export function buildMultiSkillContext(
 	skills: ReadonlyMap<string, LoadedSkill>,
 	tokenBudget: number = DEFAULT_TOKEN_BUDGET,
+	mode: SkillMode = "summary",
 ): string {
 	if (skills.size === 0) return "";
 
@@ -151,17 +195,64 @@ export function buildMultiSkillContext(
 		const skill = skills.get(name);
 		if (!skill) continue;
 
-		const collapsed = skill.content.replace(/[\r\n]+/g, " ");
-		const header = `[Skill: ${name}]\n`;
+		let section: string;
+		if (mode === "summary") {
+			section = sanitizeTemplateContent(buildSkillSummary(skill));
+		} else {
+			// Full mode: preserve structure, truncate at section boundaries
+			const header = `[Skill: ${name}]\n`;
+			const perSkillBudget = Math.max(charBudget - totalChars - header.length, 0);
+			const truncated = truncateAtSectionBoundary(skill.content, perSkillBudget);
+			const sanitized = sanitizeTemplateContent(truncated);
+			section = `${header}${sanitized}`;
+		}
+
 		const separator = sections.length > 0 ? 2 : 0; // "\n\n"
-		const sectionCost = collapsed.length + header.length + separator;
+		const sectionCost = section.length + separator;
 		if (totalChars + sectionCost > charBudget) break;
 
-		const sanitized = sanitizeTemplateContent(collapsed);
-		sections.push(`${header}${sanitized}`);
+		sections.push(section);
 		totalChars += sectionCost;
 	}
 
 	if (sections.length === 0) return "";
 	return `\n\nSkills context (follow these conventions and methodologies):\n${sections.join("\n\n")}`;
 }
+
+/**
+ * Build adaptive skill context with optional phase filtering.
+ *
+ * When `phase` is provided, only skills listed in PHASE_SKILL_MAP for that
+ * phase are included (pipeline dispatch path). When omitted, all stack-filtered
+ * skills are included (direct chat injection path).
+ */
+export function buildAdaptiveSkillContext(
+	skills: ReadonlyMap<string, LoadedSkill>,
+	options?: {
+		readonly phase?: string;
+		readonly budget?: number;
+		readonly mode?: SkillMode;
+	},
+): string {
+	const phase = options?.phase;
+	const budget = options?.budget ?? DEFAULT_TOKEN_BUDGET;
+	const mode = options?.mode ?? "summary";
+
+	if (phase !== undefined) {
+		const allowedNames = PHASE_SKILL_MAP[phase] ?? [];
+		if (allowedNames.length === 0) return "";
+
+		const allowedSet = new Set(allowedNames);
+		const filtered = new Map<string, LoadedSkill>();
+		for (const [name, skill] of skills) {
+			if (allowedSet.has(name)) {
+				filtered.set(name, skill);
+			}
+		}
+
+		return buildMultiSkillContext(filtered, budget, mode);
+	}
+
+	// No phase -- include all provided skills (caller already stack-filtered)
+	return buildMultiSkillContext(skills, budget, mode);
+}

package/src/skills/loader.ts

@@ -84,5 +84,8 @@ export async function loadAllSkills(skillsDir: string): Promise<ReadonlyMap<stri
 		if (!isEnoentError(error)) throw error;
 	}
 
-	return skills;
+	// Sort alphabetically by name for deterministic ordering regardless of
+	// filesystem readdir order (which varies across OS and FS types).
+	const sorted = new Map([...skills.entries()].sort(([a], [b]) => a.localeCompare(b)));
+	return Object.freeze(sorted);
 }