@shepai/cli 1.14.2 → 1.15.1

package/dist/src/infrastructure/services/agents/common/executors/mock-executor.service.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Mock Agent Executor
+ *
+ * Deterministic executor for E2E tests. Returns predictable responses
+ * so tests can assert on exact slugs, names, and descriptions.
+ *
+ * Activated via SHEP_MOCK_EXECUTOR=1 environment variable.
+ */
+import type { AgentType, AgentFeature } from '../../../../../domain/generated/output.js';
+import type { IAgentExecutor, AgentExecutionOptions, AgentExecutionResult, AgentExecutionStreamEvent } from '../../../../../application/ports/output/agents/agent-executor.interface.js';
+export declare class MockAgentExecutorService implements IAgentExecutor {
+    readonly agentType: AgentType;
+    execute(prompt: string, _options?: AgentExecutionOptions): Promise<AgentExecutionResult>;
+    executeStream(prompt: string, options?: AgentExecutionOptions): AsyncIterable<AgentExecutionStreamEvent>;
+    supportsFeature(_feature: AgentFeature): boolean;
+}
+//# sourceMappingURL=mock-executor.service.d.ts.map

package/dist/src/infrastructure/services/agents/common/executors/mock-executor.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-executor.service.d.ts","sourceRoot":"","sources":["../../../../../../../src/infrastructure/services/agents/common/executors/mock-executor.service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AACzF,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,yBAAyB,EAC1B,MAAM,4EAA4E,CAAC;AAwBpF,qBAAa,wBAAyB,YAAW,cAAc;IAC7D,QAAQ,CAAC,SAAS,EAAE,SAAS,CAA8B;IAErD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAevF,aAAa,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,qBAAqB,GAC9B,aAAa,CAAC,yBAAyB,CAAC;IAK3C,eAAe,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO;CAGjD"}

package/dist/src/infrastructure/services/agents/common/executors/mock-executor.service.js

@@ -0,0 +1,49 @@
+/**
+ * Mock Agent Executor
+ *
+ * Deterministic executor for E2E tests. Returns predictable responses
+ * so tests can assert on exact slugs, names, and descriptions.
+ *
+ * Activated via SHEP_MOCK_EXECUTOR=1 environment variable.
+ */
+function toSlug(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+function toTitleCase(text) {
+    return text.replace(/\b\w/g, (c) => c.toUpperCase());
+}
+/**
+ * Extract the quoted user input from the metadata generation prompt.
+ * Prompt format: `Generate feature metadata from this user request:\n"<input>"\n...`
+ */
+function extractUserInput(prompt) {
+    const match = prompt.match(/user request:\n"(.+?)"\n/s);
+    return match ? match[1] : null;
+}
+export class MockAgentExecutorService {
+    agentType = 'claude-code';
+    async execute(prompt, _options) {
+        const userInput = extractUserInput(prompt);
+        if (userInput) {
+            const slug = toSlug(userInput);
+            const name = toTitleCase(userInput);
+            return {
+                result: JSON.stringify({ slug, name, description: userInput }),
+            };
+        }
+        // Default fallback for any other prompt
+        return { result: '{}' };
+    }
+    async *executeStream(prompt, options) {
+        const result = await this.execute(prompt, options);
+        yield { type: 'result', content: result.result, timestamp: new Date() };
+    }
+    supportsFeature(_feature) {
+        return false;
+    }
+}

package/dist/src/infrastructure/services/agents/feature-agent/feature-agent-graph.d.ts

@@ -0,0 +1,244 @@
+import { type BaseCheckpointSaver } from '@langchain/langgraph';
+import type { IAgentExecutor } from '../../../../application/ports/output/agents/agent-executor.interface.js';
+export { FeatureAgentAnnotation, type FeatureAgentState } from './state.js';
+/**
+ * Factory function that creates and compiles the feature-agent LangGraph.
+ *
+ * The graph defines a linear SDLC workflow:
+ *   analyze → requirements → research → plan → implement
+ *
+ * Each node delegates work to the injected IAgentExecutor (e.g. Claude Code).
+ *
+ * @param executor - The agent executor to delegate prompt execution to
+ * @param checkpointer - Optional checkpoint saver for state persistence
+ * @returns A compiled LangGraph ready to be invoked
+ */
+export declare function createFeatureAgentGraph(executor: IAgentExecutor, checkpointer?: BaseCheckpointSaver): import("@langchain/langgraph").CompiledStateGraph<{
+    featureId: string;
+    repositoryPath: string;
+    specDir: string;
+    worktreePath: string;
+    currentNode: string;
+    error: string | null;
+    approvalMode: string | undefined;
+    messages: string[];
+}, {
+    featureId?: string | undefined;
+    repositoryPath?: string | undefined;
+    specDir?: string | undefined;
+    worktreePath?: string | undefined;
+    currentNode?: string | undefined;
+    error?: string | null | undefined;
+    approvalMode?: string | undefined;
+    messages?: string[] | undefined;
+}, "__start__" | "analyze" | "requirements" | "research" | "plan" | "implement", {
+    featureId: {
+        (): import("@langchain/langgraph").LastValue<string>;
+        (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+        Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+    };
+    repositoryPath: {
+        (): import("@langchain/langgraph").LastValue<string>;
+        (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+        Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+    };
+    specDir: {
+        (): import("@langchain/langgraph").LastValue<string>;
+        (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+        Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+    };
+    worktreePath: {
+        (): import("@langchain/langgraph").LastValue<string>;
+        (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+        Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+    };
+    currentNode: {
+        (): import("@langchain/langgraph").LastValue<string>;
+        (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+        Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+    };
+    error: import("@langchain/langgraph").BinaryOperatorAggregate<string | null, string | null>;
+    approvalMode: import("@langchain/langgraph").BinaryOperatorAggregate<string | undefined, string | undefined>;
+    messages: import("@langchain/langgraph").BinaryOperatorAggregate<string[], string[]>;
+}, {
+    featureId: {
+        (): import("@langchain/langgraph").LastValue<string>;
+        (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+        Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+    };
+    repositoryPath: {
+        (): import("@langchain/langgraph").LastValue<string>;
+        (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+        Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+    };
+    specDir: {
+        (): import("@langchain/langgraph").LastValue<string>;
+        (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+        Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+    };
+    worktreePath: {
+        (): import("@langchain/langgraph").LastValue<string>;
+        (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+        Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+    };
+    currentNode: {
+        (): import("@langchain/langgraph").LastValue<string>;
+        (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+        Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+    };
+    error: import("@langchain/langgraph").BinaryOperatorAggregate<string | null, string | null>;
+    approvalMode: import("@langchain/langgraph").BinaryOperatorAggregate<string | undefined, string | undefined>;
+    messages: import("@langchain/langgraph").BinaryOperatorAggregate<string[], string[]>;
+}, import("@langchain/langgraph").StateDefinition, {
+    analyze: Partial<import("@langchain/langgraph").StateType<{
+        featureId: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        repositoryPath: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        specDir: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        worktreePath: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        currentNode: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        error: import("@langchain/langgraph").BinaryOperatorAggregate<string | null, string | null>;
+        approvalMode: import("@langchain/langgraph").BinaryOperatorAggregate<string | undefined, string | undefined>;
+        messages: import("@langchain/langgraph").BinaryOperatorAggregate<string[], string[]>;
+    }>>;
+    requirements: Partial<import("@langchain/langgraph").StateType<{
+        featureId: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        repositoryPath: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        specDir: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        worktreePath: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        currentNode: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        error: import("@langchain/langgraph").BinaryOperatorAggregate<string | null, string | null>;
+        approvalMode: import("@langchain/langgraph").BinaryOperatorAggregate<string | undefined, string | undefined>;
+        messages: import("@langchain/langgraph").BinaryOperatorAggregate<string[], string[]>;
+    }>>;
+    research: Partial<import("@langchain/langgraph").StateType<{
+        featureId: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        repositoryPath: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        specDir: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        worktreePath: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        currentNode: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        error: import("@langchain/langgraph").BinaryOperatorAggregate<string | null, string | null>;
+        approvalMode: import("@langchain/langgraph").BinaryOperatorAggregate<string | undefined, string | undefined>;
+        messages: import("@langchain/langgraph").BinaryOperatorAggregate<string[], string[]>;
+    }>>;
+    plan: Partial<import("@langchain/langgraph").StateType<{
+        featureId: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        repositoryPath: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        specDir: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        worktreePath: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        currentNode: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        error: import("@langchain/langgraph").BinaryOperatorAggregate<string | null, string | null>;
+        approvalMode: import("@langchain/langgraph").BinaryOperatorAggregate<string | undefined, string | undefined>;
+        messages: import("@langchain/langgraph").BinaryOperatorAggregate<string[], string[]>;
+    }>>;
+    implement: Partial<import("@langchain/langgraph").StateType<{
+        featureId: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        repositoryPath: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        specDir: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        worktreePath: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        currentNode: {
+            (): import("@langchain/langgraph").LastValue<string>;
+            (annotation: import("@langchain/langgraph").SingleReducer<string, string>): import("@langchain/langgraph").BinaryOperatorAggregate<string, string>;
+            Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
+        };
+        error: import("@langchain/langgraph").BinaryOperatorAggregate<string | null, string | null>;
+        approvalMode: import("@langchain/langgraph").BinaryOperatorAggregate<string | undefined, string | undefined>;
+        messages: import("@langchain/langgraph").BinaryOperatorAggregate<string[], string[]>;
+    }>>;
+}, unknown, unknown>;
+//# sourceMappingURL=feature-agent-graph.d.ts.map

package/dist/src/infrastructure/services/agents/feature-agent/feature-agent-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-agent-graph.d.ts","sourceRoot":"","sources":["../../../../../../src/infrastructure/services/agents/feature-agent/feature-agent-graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+DAA+D,CAAC;AASpG,OAAO,EAAE,sBAAsB,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,cAAc,EACxB,YAAY,CAAC,EAAE,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAgBnC"}

package/dist/src/infrastructure/services/agents/feature-agent/feature-agent-graph.js

@@ -0,0 +1,36 @@
+import { StateGraph, START, END } from '@langchain/langgraph';
+import { FeatureAgentAnnotation } from './state.js';
+import { createAnalyzeNode } from './nodes/analyze.node.js';
+import { createRequirementsNode } from './nodes/requirements.node.js';
+import { createResearchNode } from './nodes/research.node.js';
+import { createPlanNode } from './nodes/plan.node.js';
+import { createImplementNode } from './nodes/implement.node.js';
+// Re-export state types for consumers
+export { FeatureAgentAnnotation } from './state.js';
+/**
+ * Factory function that creates and compiles the feature-agent LangGraph.
+ *
+ * The graph defines a linear SDLC workflow:
+ *   analyze → requirements → research → plan → implement
+ *
+ * Each node delegates work to the injected IAgentExecutor (e.g. Claude Code).
+ *
+ * @param executor - The agent executor to delegate prompt execution to
+ * @param checkpointer - Optional checkpoint saver for state persistence
+ * @returns A compiled LangGraph ready to be invoked
+ */
+export function createFeatureAgentGraph(executor, checkpointer) {
+    const graph = new StateGraph(FeatureAgentAnnotation)
+        .addNode('analyze', createAnalyzeNode(executor))
+        .addNode('requirements', createRequirementsNode(executor))
+        .addNode('research', createResearchNode(executor))
+        .addNode('plan', createPlanNode(executor))
+        .addNode('implement', createImplementNode(executor))
+        .addEdge(START, 'analyze')
+        .addEdge('analyze', 'requirements')
+        .addEdge('requirements', 'research')
+        .addEdge('research', 'plan')
+        .addEdge('plan', 'implement')
+        .addEdge('implement', END);
+    return graph.compile({ checkpointer });
+}

package/dist/src/infrastructure/services/agents/feature-agent/feature-agent-process.service.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Feature Agent Process Service
+ *
+ * Infrastructure implementation of IFeatureAgentProcessService.
+ * Manages background worker processes for feature agent execution
+ * using Node.js child_process.fork().
+ */
+import type { IFeatureAgentProcessService } from '../../../../application/ports/output/agents/feature-agent-process.interface.js';
+import type { IAgentRunRepository } from '../../../../application/ports/output/agents/agent-run-repository.interface.js';
+export declare class FeatureAgentProcessService implements IFeatureAgentProcessService {
+    private readonly runRepository;
+    constructor(runRepository: IAgentRunRepository);
+    spawn(featureId: string, runId: string, repoPath: string, specDir: string, worktreePath?: string, options?: {
+        approvalMode?: string;
+        resume?: boolean;
+    }): number;
+    isAlive(pid: number): boolean;
+    checkAndMarkCrashed(runId: string): Promise<void>;
+}
+//# sourceMappingURL=feature-agent-process.service.d.ts.map

package/dist/src/infrastructure/services/agents/feature-agent/feature-agent-process.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-agent-process.service.d.ts","sourceRoot":"","sources":["../../../../../../src/infrastructure/services/agents/feature-agent/feature-agent-process.service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,sEAAsE,CAAC;AACxH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qEAAqE,CAAC;AAa/G,qBAAa,0BAA2B,YAAW,2BAA2B;IAChE,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,mBAAmB;IAE/D,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GACpD,MAAM;IA4CT,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IASvB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAexD"}

package/dist/src/infrastructure/services/agents/feature-agent/feature-agent-process.service.js

@@ -0,0 +1,90 @@
+/**
+ * Feature Agent Process Service
+ *
+ * Infrastructure implementation of IFeatureAgentProcessService.
+ * Manages background worker processes for feature agent execution
+ * using Node.js child_process.fork().
+ */
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fork } from 'node:child_process';
+import { join } from 'node:path';
+import { openSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { mkdirSync } from 'node:fs';
+import { AgentRunStatus } from '../../../../domain/generated/output.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Terminal statuses that should not be updated */
+const TERMINAL_STATUSES = new Set([
+    AgentRunStatus.completed,
+    AgentRunStatus.failed,
+    AgentRunStatus.interrupted,
+    AgentRunStatus.cancelled,
+]);
+export class FeatureAgentProcessService {
+    runRepository;
+    constructor(runRepository) {
+        this.runRepository = runRepository;
+    }
+    spawn(featureId, runId, repoPath, specDir, worktreePath, options) {
+        const workerPath = join(__dirname, 'feature-agent-worker.js');
+        const args = [
+            '--feature-id',
+            featureId,
+            '--run-id',
+            runId,
+            '--repo',
+            repoPath,
+            '--spec-dir',
+            specDir,
+        ];
+        if (worktreePath) {
+            args.push('--worktree-path', worktreePath);
+        }
+        if (options?.approvalMode) {
+            args.push('--approval-mode', options.approvalMode);
+        }
+        if (options?.resume) {
+            args.push('--resume');
+        }
+        // Create log file for worker output (for debugging)
+        const logsDir = join(homedir(), '.shep', 'logs');
+        mkdirSync(logsDir, { recursive: true });
+        const logPath = join(logsDir, `worker-${runId}.log`);
+        const logFd = openSync(logPath, 'a');
+        const child = fork(workerPath, args, {
+            detached: true,
+            stdio: ['ignore', logFd, logFd, 'ipc'],
+        });
+        if (!child.pid) {
+            throw new Error('Failed to spawn feature agent worker: no PID returned');
+        }
+        // Disconnect IPC so parent can exit cleanly without breaking the child
+        child.disconnect();
+        child.unref();
+        return child.pid;
+    }
+    isAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async checkAndMarkCrashed(runId) {
+        const run = await this.runRepository.findById(runId);
+        if (!run || !run.pid || TERMINAL_STATUSES.has(run.status)) {
+            return;
+        }
+        if (!this.isAlive(run.pid)) {
+            const now = new Date().toISOString();
+            await this.runRepository.updateStatus(runId, AgentRunStatus.interrupted, {
+                error: `Agent process (PID ${run.pid}) crashed or was killed`,
+                completedAt: now,
+                updatedAt: now,
+            });
+        }
+    }
+}

package/dist/src/infrastructure/services/agents/feature-agent/feature-agent-worker.d.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * Feature Agent Worker
+ *
+ * Background worker entry point that runs as a child process via fork().
+ * Initializes DI, creates the feature agent graph, and executes it.
+ * Sends periodic heartbeats so the CLI can detect stuck/crashed workers.
+ *
+ * CLI Args: --feature-id <id> --run-id <id> --repo <path> --spec-dir <path>
+ */
+import 'reflect-metadata';
+export interface WorkerArgs {
+    featureId: string;
+    runId: string;
+    repo: string;
+    specDir: string;
+    worktreePath?: string;
+    approvalMode?: string;
+    resume?: boolean;
+}
+/**
+ * Parse CLI arguments into a WorkerArgs object.
+ * Throws if any required argument is missing.
+ */
+export declare function parseWorkerArgs(args: string[]): WorkerArgs;
+/**
+ * Run the feature agent worker with the given arguments.
+ * Initializes DI, creates the graph, and executes it.
+ */
+export declare function runWorker(args: WorkerArgs): Promise<void>;
+//# sourceMappingURL=feature-agent-worker.d.ts.map

package/dist/src/infrastructure/services/agents/feature-agent/feature-agent-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-agent-worker.d.ts","sourceRoot":"","sources":["../../../../../../src/infrastructure/services/agents/feature-agent/feature-agent-worker.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AAEH,OAAO,kBAAkB,CAAC;AAc1B,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA4B1D;AAgCD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAqH/D"}