feat(domain): add prototype exploration mode for iterative visual prototyping

apis/json-schema/Feature.yaml

@@ -50,10 +50,10 @@ properties:
   repositoryId:
     $ref: UUID.yaml
     description: ID of the Repository entity this feature belongs to
-  fast:
-    type: boolean
-    default: false
-    description: When true, SDLC phases were skipped and the feature was implemented directly from the prompt
+  mode:
+    $ref: FeatureMode.yaml
+    default: Regular
+    description: "Execution mode determining the workflow: Regular (full SDLC), Fast (direct implementation), or Exploration (iterative prototyping)"
   push:
     type: boolean
     default: false
@@ -92,6 +92,17 @@ properties:
   worktreePath:
     type: string
     description: Absolute path to the git worktree for this feature
+  iterationCount:
+    type: integer
+    minimum: -2147483648
+    maximum: 2147483647
+    default: 0
+    description: Current feedback iteration count in exploration mode (0 when not exploring)
+  maxIterations:
+    type: integer
+    minimum: -2147483648
+    maximum: 2147483647
+    description: Maximum allowed iterations for exploration mode (only set when mode is Exploration)
   pr:
     $ref: PullRequest.yaml
     description: Pull request data (null until PR created)
@@ -116,7 +127,7 @@ required:
   - lifecycle
   - messages
   - relatedArtifacts
-  - fast
+  - mode
   - push
   - openPr
   - forkAndPr
@@ -126,6 +137,7 @@ required:
   - injectSkills
   - commitEvidence
   - approvalGates
+  - iterationCount
 allOf:
   - $ref: SoftDeletableEntity.yaml
 description: Central entity tracking a piece of work through the SDLC lifecycle (Aggregate Root)

apis/json-schema/FeatureMode.yaml

@@ -0,0 +1,8 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: FeatureMode.yaml
+type: string
+enum:
+  - Regular
+  - Fast
+  - Exploration
+description: Execution mode determining the feature's workflow and agent graph

apis/json-schema/SdlcLifecycle.yaml

@@ -12,6 +12,7 @@ enum:
   - Maintain
   - Blocked
   - Pending
+  - Exploring
   - Deleting
   - AwaitingUpstream
   - Archived

apis/json-schema/WorkflowConfig.yaml

@@ -55,10 +55,15 @@ properties:
   hideCiStatus:
     type: boolean
     description: "Hide CI status badges from UI (default: true)"
-  defaultFastMode:
-    type: boolean
-    default: true
-    description: "Default new features to fast mode (default: true)"
+  defaultMode:
+    type: string
+    default: Fast
+    description: "Default feature mode for new features: 'Regular', 'Fast', or 'Exploration' (default: 'Fast')"
+  explorationMaxIterations:
+    type: integer
+    minimum: -2147483648
+    maximum: 2147483647
+    description: "Maximum exploration feedback iterations (default: 10, 0 = unlimited)"
   autoArchiveDelayMinutes:
     type: integer
     minimum: -2147483648
@@ -73,5 +78,5 @@ required:
   - ciWatchEnabled
   - enableEvidence
   - commitEvidence
-  - defaultFastMode
+  - defaultMode
 description: Global workflow configuration defaults

packages/core/src/application/ports/output/agents/feature-agent-process.interface.ts

@@ -10,7 +10,7 @@
  * - Infrastructure layer provides concrete implementation
  */
 
-import type { ApprovalGates, AgentType } from '../../../../domain/generated/output.js';
+import type { ApprovalGates, AgentType, FeatureMode } from '../../../../domain/generated/output.js';
 
 /**
  * Service interface for feature agent background process management.
@@ -45,7 +45,7 @@ export interface IFeatureAgentProcessService {
       commitEvidence?: boolean;
       resumePayload?: string;
       agentType?: AgentType;
-      fast?: boolean;
+      mode?: FeatureMode;
       model?: string;
       resumeReason?: string;
     }

packages/core/src/application/ports/output/services/spec-initializer.interface.ts

@@ -24,20 +24,21 @@ export interface ISpecInitializerService {
    * - tasks.yaml
    * - feature.yaml
    *
-   * When mode is 'fast', only feature.yaml is created (no spec/research/plan/tasks).
+   * When mode is 'fast', only feature.yaml and spec.yaml are created.
+   * When mode is 'exploration', only feature.yaml is created.
    *
    * @param basePath - Directory to create specs/ in (typically the worktree path)
    * @param slug - Feature slug (kebab-case, e.g., "user-authentication")
    * @param featureNumber - Sequential feature number (will be zero-padded to 3 digits)
    * @param description - Feature description for template substitution
-   * @param mode - Optional mode; when 'fast', only feature.yaml is created
+   * @param mode - Optional mode; controls which template files are created
    * @returns The spec directory path and feature number used
    */
   initialize(
     basePath: string,
     slug: string,
     featureNumber: number,
     description: string,
-    mode?: 'fast'
+    mode?: 'fast' | 'exploration'
   ): Promise<SpecInitializerResult>;
 }

packages/core/src/application/use-cases/agents/approve-agent-run.use-case.ts

@@ -15,7 +15,7 @@ import type { IAgentRunRepository } from '../../ports/output/agents/agent-run-re
 import type { IFeatureAgentProcessService } from '../../ports/output/agents/feature-agent-process.interface.js';
 import type { IPhaseTimingRepository } from '../../ports/output/agents/phase-timing-repository.interface.js';
 import type { IFeatureRepository } from '../../ports/output/repositories/feature-repository.interface.js';
-import { AgentRunStatus } from '../../../domain/generated/output.js';
+import { AgentRunStatus, FeatureMode } from '../../../domain/generated/output.js';
 import type { PrdApprovalPayload } from '../../../domain/generated/output.js';
 import {
   writeSpecFileAtomic,
@@ -139,7 +139,7 @@ export class ApproveAgentRunUseCase {
         ...(payload ? { resumePayload: JSON.stringify(payload) } : {}),
         agentType: run.agentType,
         ...(run.modelId ? { model: run.modelId } : {}),
-        ...(feature?.fast ? { fast: true } : {}),
+        ...(feature?.mode && feature.mode !== FeatureMode.Regular ? { mode: feature.mode } : {}),
       }
     );
 

packages/core/src/application/use-cases/agents/reject-agent-run.use-case.ts

@@ -14,7 +14,7 @@ import type { IAgentRunRepository } from '../../ports/output/agents/agent-run-re
 import type { IFeatureAgentProcessService } from '../../ports/output/agents/feature-agent-process.interface.js';
 import type { IPhaseTimingRepository } from '../../ports/output/agents/phase-timing-repository.interface.js';
 import type { IFeatureRepository } from '../../ports/output/repositories/feature-repository.interface.js';
-import { AgentRunStatus } from '../../../domain/generated/output.js';
+import { AgentRunStatus, FeatureMode } from '../../../domain/generated/output.js';
 import type {
   PrdRejectionPayload,
   RejectionFeedbackEntry,
@@ -167,7 +167,7 @@ export class RejectAgentRunUseCase {
         resumePayload: JSON.stringify(rejectionPayload),
         agentType: run.agentType,
         ...(run.modelId ? { model: run.modelId } : {}),
-        ...(feature.fast ? { fast: true } : {}),
+        ...(feature.mode !== FeatureMode.Regular ? { mode: feature.mode } : {}),
       }
     );
 

packages/core/src/application/use-cases/features/adopt-branch.use-case.ts

@@ -13,7 +13,7 @@
 import { injectable, inject } from 'tsyringe';
 import { randomUUID } from 'node:crypto';
 import type { Feature, PullRequest } from '../../../domain/generated/output.js';
-import { SdlcLifecycle, PrStatus } from '../../../domain/generated/output.js';
+import { SdlcLifecycle, PrStatus, FeatureMode } from '../../../domain/generated/output.js';
 import type { IFeatureRepository } from '../../ports/output/repositories/feature-repository.interface.js';
 import type { IRepositoryRepository } from '../../ports/output/repositories/repository-repository.interface.js';
 import type { IWorktreeService } from '../../ports/output/services/worktree-service.interface.js';
@@ -114,7 +114,8 @@ export class AdoptBranchUseCase {
       lifecycle,
       messages: [],
       relatedArtifacts: [],
-      fast: false,
+      mode: FeatureMode.Regular,
+      iterationCount: 0,
       push: false,
       openPr: hasOpenPr,
       forkAndPr: false,

packages/core/src/application/use-cases/features/check-and-unblock-features.use-case.ts

@@ -16,7 +16,7 @@
  */
 
 import { injectable, inject } from 'tsyringe';
-import { SdlcLifecycle } from '../../../domain/generated/output.js';
+import { SdlcLifecycle, FeatureMode } from '../../../domain/generated/output.js';
 import type { IFeatureRepository } from '../../ports/output/repositories/feature-repository.interface.js';
 import type { IFeatureAgentProcessService } from '../../ports/output/agents/feature-agent-process.interface.js';
 import { POST_IMPLEMENTATION } from '../../../domain/lifecycle-gates.js';
@@ -72,7 +72,7 @@ export class CheckAndUnblockFeaturesUseCase {
             ciWatchEnabled: child.ciWatchEnabled,
             enableEvidence: child.enableEvidence,
             commitEvidence: child.commitEvidence,
-            ...(child.fast ? { fast: true } : {}),
+            ...(child.mode !== FeatureMode.Regular ? { mode: child.mode } : {}),
           }
         );
       }

packages/core/src/application/use-cases/features/create/create-feature.use-case.ts

@@ -22,6 +22,7 @@ import type { Feature } from '../../../../domain/generated/output.js';
 import {
   SdlcLifecycle,
   AgentRunStatus,
+  FeatureMode,
   type AgentType,
 } from '../../../../domain/generated/output.js';
 import type { IFeatureRepository } from '../../../ports/output/repositories/feature-repository.interface.js';
@@ -86,9 +87,13 @@ export class CreateFeatureUseCase {
    * No AI calls, no git operations — just DB writes.
    */
   async createRecord(input: CreateFeatureInput): Promise<CreateRecordResult> {
-    let initialLifecycle: SdlcLifecycle = input.fast
-      ? SdlcLifecycle.Implementation
-      : SdlcLifecycle.Requirements;
+    const effectiveMode = input.mode ?? FeatureMode.Regular;
+    let initialLifecycle: SdlcLifecycle =
+      effectiveMode === FeatureMode.Exploration
+        ? SdlcLifecycle.Exploring
+        : effectiveMode === FeatureMode.Fast
+          ? SdlcLifecycle.Implementation
+          : SdlcLifecycle.Requirements;
     let shouldSpawn = true;
     let effectiveRepoPath = input.repositoryPath.replace(/\\/g, '/');
 
@@ -173,7 +178,7 @@ export class CreateFeatureUseCase {
       lifecycle: initialLifecycle,
       messages: [],
       relatedArtifacts: [],
-      fast: input.fast ?? false,
+      mode: effectiveMode,
       push: input.push ?? false,
       openPr: input.openPr ?? false,
       forkAndPr: input.forkAndPr ?? false,
@@ -187,6 +192,10 @@ export class CreateFeatureUseCase {
         allowPlan: false,
         allowMerge: false,
       },
+      iterationCount: 0,
+      ...(effectiveMode === FeatureMode.Exploration && {
+        maxIterations: getSettings().workflow.explorationMaxIterations ?? 10,
+      }),
       agentRunId: runId,
       specPath: '',
       repositoryId: repository.id,
@@ -278,7 +287,11 @@ export class CreateFeatureUseCase {
       slug,
       featureNumber,
       input.userInput,
-      input.fast ? 'fast' : undefined
+      feature.mode === FeatureMode.Fast
+        ? 'fast'
+        : feature.mode === FeatureMode.Exploration
+          ? 'exploration'
+          : undefined
     );
 
     // Commit pending attachments if sessionId was provided (web UI flow)
@@ -387,7 +400,7 @@ export class CreateFeatureUseCase {
           ciWatchEnabled: input.ciWatchEnabled ?? true,
           enableEvidence: input.enableEvidence ?? false,
           commitEvidence: input.commitEvidence ?? false,
-          ...(input.fast ? { fast: true } : {}),
+          ...(feature.mode !== FeatureMode.Regular ? { mode: feature.mode } : {}),
           ...(input.agentType ? { agentType: input.agentType as AgentType } : {}),
           ...(input.model ? { model: input.model } : {}),
         }

packages/core/src/application/use-cases/features/create/types.ts

@@ -1,4 +1,5 @@
 import type { ApprovalGates, Attachment, Feature } from '../../../../domain/generated/output.js';
+import { type FeatureMode } from '../../../../domain/generated/output.js';
 
 export interface CreateFeatureInput {
   userInput: string;
@@ -12,8 +13,8 @@ export interface CreateFeatureInput {
   name?: string;
   /** Pre-supplied description (skips AI metadata extraction for description). */
   description?: string;
-  /** When true, skip SDLC phases and implement directly from the user prompt. */
-  fast?: boolean;
+  /** Execution mode: Regular (full SDLC), Fast (direct implementation), or Exploration (iterative prototyping). */
+  mode?: FeatureMode;
   /** Fork repo and create PR to upstream at merge time (default: false). */
   forkAndPr?: boolean;
   /** Commit specs/evidences into the repo (default: true, auto-false when forkAndPr). */

packages/core/src/application/use-cases/features/delete-feature.use-case.ts

@@ -14,6 +14,9 @@
  */
 
 import { injectable, inject } from 'tsyringe';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { unlink } from 'node:fs/promises';
 import type { Feature } from '../../../domain/generated/output.js';
 import { AgentRunStatus, PrStatus, SdlcLifecycle } from '../../../domain/generated/output.js';
 import type { IFeatureRepository } from '../../ports/output/repositories/feature-repository.interface.js';
@@ -137,6 +140,16 @@ export class DeleteFeatureUseCase {
         }
         await this.runRepo.updateStatus(run.id, AgentRunStatus.cancelled);
       }
+
+      // Clean up checkpoint database file (used by LangGraph for state persistence)
+      if (run?.threadId) {
+        const checkpointPath = join(homedir(), '.shep', 'checkpoints', `${run.threadId}.db`);
+        try {
+          await unlink(checkpointPath);
+        } catch {
+          // Checkpoint file may not exist or already be removed
+        }
+      }
     }
 
     // Cleanup worktree and branches directly using the feature data we already