prjct-cli 1.11.0 → 1.12.0

package/core/__tests__/storage/subtask-handoff.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Subtask Handoff Tests (PRJ-262)
+ *
+ * Tests for mandatory subtask output and handoff:
+ * - SubtaskCompletionDataSchema validation
+ * - SubtaskSummarySchema required fields
+ * - validateSubtaskCompletion helper
+ * - Backward compatibility with old state.json
+ */
+
+import { describe, expect, it } from 'bun:test'
+import {
+  SubtaskCompletionDataSchema,
+  SubtaskSchema,
+  SubtaskSummarySchema,
+  validateSubtaskCompletion,
+} from '../../schemas/state'
+
+// =============================================================================
+// SubtaskSummarySchema — outputForNextAgent is now required
+// =============================================================================
+
+describe('SubtaskSummarySchema', () => {
+  const validSummary = {
+    title: 'Implement auth middleware',
+    description: 'Added JWT verification to all protected routes',
+    filesChanged: [
+      { path: 'src/middleware/auth.ts', action: 'created' as const },
+      { path: 'src/routes/api.ts', action: 'modified' as const },
+    ],
+    whatWasDone: ['Created JWT middleware', 'Applied to API routes'],
+    outputForNextAgent:
+      'Auth middleware is in place. Next subtask should add role-based access control.',
+  }
+
+  it('should parse a valid summary with all required fields', () => {
+    const result = SubtaskSummarySchema.parse(validSummary)
+    expect(result.outputForNextAgent).toBe(validSummary.outputForNextAgent)
+    expect(result.whatWasDone).toHaveLength(2)
+  })
+
+  it('should reject missing outputForNextAgent', () => {
+    const { outputForNextAgent, ...withoutOutput } = validSummary
+    expect(() => SubtaskSummarySchema.parse(withoutOutput)).toThrow()
+  })
+
+  it('should reject empty outputForNextAgent', () => {
+    expect(() => SubtaskSummarySchema.parse({ ...validSummary, outputForNextAgent: '' })).toThrow()
+  })
+
+  it('should reject empty whatWasDone array', () => {
+    expect(() => SubtaskSummarySchema.parse({ ...validSummary, whatWasDone: [] })).toThrow()
+  })
+
+  it('should allow optional notes', () => {
+    const result = SubtaskSummarySchema.parse({ ...validSummary, notes: 'Watch for rate limits' })
+    expect(result.notes).toBe('Watch for rate limits')
+  })
+
+  it('should allow missing notes', () => {
+    const result = SubtaskSummarySchema.parse(validSummary)
+    expect(result.notes).toBeUndefined()
+  })
+})
+
+// =============================================================================
+// SubtaskCompletionDataSchema — validates completion requirements
+// =============================================================================
+
+describe('SubtaskCompletionDataSchema', () => {
+  const validCompletion = {
+    output: 'Implemented auth middleware with JWT verification',
+    summary: {
+      title: 'Auth middleware',
+      description: 'JWT verification for protected routes',
+      filesChanged: [{ path: 'src/auth.ts', action: 'created' as const }],
+      whatWasDone: ['Created JWT middleware'],
+      outputForNextAgent: 'Middleware ready, add RBAC next.',
+    },
+  }
+
+  it('should parse valid completion data', () => {
+    const result = SubtaskCompletionDataSchema.parse(validCompletion)
+    expect(result.output).toBe(validCompletion.output)
+    expect(result.summary.outputForNextAgent).toBe('Middleware ready, add RBAC next.')
+  })
+
+  it('should reject missing output', () => {
+    const { output, ...withoutOutput } = validCompletion
+    expect(() => SubtaskCompletionDataSchema.parse(withoutOutput)).toThrow()
+  })
+
+  it('should reject empty output', () => {
+    expect(() => SubtaskCompletionDataSchema.parse({ ...validCompletion, output: '' })).toThrow()
+  })
+
+  it('should reject missing summary', () => {
+    expect(() => SubtaskCompletionDataSchema.parse({ output: 'some output' })).toThrow()
+  })
+
+  it('should reject summary without outputForNextAgent', () => {
+    const badSummary = { ...validCompletion.summary }
+    // @ts-expect-error - intentionally testing invalid data
+    delete badSummary.outputForNextAgent
+    expect(() => SubtaskCompletionDataSchema.parse({ output: 'ok', summary: badSummary })).toThrow()
+  })
+})
+
+// =============================================================================
+// validateSubtaskCompletion helper
+// =============================================================================
+
+describe('validateSubtaskCompletion', () => {
+  const validData = {
+    output: 'Task done',
+    summary: {
+      title: 'Test',
+      description: 'Testing',
+      filesChanged: [],
+      whatWasDone: ['Did the thing'],
+      outputForNextAgent: 'Context for next.',
+    },
+  }
+
+  it('should return success for valid data', () => {
+    const result = validateSubtaskCompletion(validData)
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.output).toBe('Task done')
+    }
+  })
+
+  it('should return errors for missing output', () => {
+    const result = validateSubtaskCompletion({ summary: validData.summary })
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      expect(result.errors.length).toBeGreaterThan(0)
+      expect(result.errors.some((e) => e.includes('output'))).toBe(true)
+    }
+  })
+
+  it('should return errors for empty whatWasDone', () => {
+    const result = validateSubtaskCompletion({
+      output: 'ok',
+      summary: { ...validData.summary, whatWasDone: [] },
+    })
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      expect(result.errors.some((e) => e.includes('whatWasDone'))).toBe(true)
+    }
+  })
+
+  it('should return errors for completely invalid data', () => {
+    const result = validateSubtaskCompletion({})
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      expect(result.errors.length).toBeGreaterThan(0)
+    }
+  })
+})
+
+// =============================================================================
+// Backward Compatibility
+// =============================================================================
+
+describe('backward compatibility', () => {
+  it('should parse old SubtaskSchema without summary or output', () => {
+    const oldSubtask = {
+      id: 'subtask-1',
+      description: 'Old subtask without handoff',
+      domain: 'backend',
+      agent: 'backend.md',
+      status: 'completed' as const,
+      dependsOn: [],
+      startedAt: '2026-01-01T00:00:00.000Z',
+      completedAt: '2026-01-01T01:00:00.000Z',
+      // No output, no summary — old format
+    }
+    const result = SubtaskSchema.parse(oldSubtask)
+    expect(result.output).toBeUndefined()
+    expect(result.summary).toBeUndefined()
+    expect(result.status).toBe('completed')
+  })
+
+  it('should parse pending subtask without completion fields', () => {
+    const pending = {
+      id: 'subtask-2',
+      description: 'Pending subtask',
+      domain: 'frontend',
+      agent: 'frontend.md',
+      status: 'pending' as const,
+      dependsOn: ['subtask-1'],
+    }
+    const result = SubtaskSchema.parse(pending)
+    expect(result.status).toBe('pending')
+    expect(result.output).toBeUndefined()
+    expect(result.summary).toBeUndefined()
+  })
+
+  it('should parse subtask with output but no summary (transition format)', () => {
+    const transitional = {
+      id: 'subtask-1',
+      description: 'Transitional format',
+      domain: 'backend',
+      agent: 'backend.md',
+      status: 'completed' as const,
+      dependsOn: [],
+      output: 'Done with basic output',
+      // No summary yet
+    }
+    const result = SubtaskSchema.parse(transitional)
+    expect(result.output).toBe('Done with basic output')
+    expect(result.summary).toBeUndefined()
+  })
+
+  it('should parse subtask with full handoff data', () => {
+    const withHandoff = {
+      id: 'subtask-1',
+      description: 'Full handoff format',
+      domain: 'backend',
+      agent: 'backend.md',
+      status: 'completed' as const,
+      dependsOn: [],
+      output: 'Implemented the feature',
+      summary: {
+        title: 'Backend API',
+        description: 'Created REST endpoints',
+        filesChanged: [{ path: 'src/api.ts', action: 'created' as const }],
+        whatWasDone: ['Created endpoints', 'Added validation'],
+        outputForNextAgent: 'API is ready at /api/v1. Add auth next.',
+      },
+    }
+    const result = SubtaskSchema.parse(withHandoff)
+    expect(result.summary?.outputForNextAgent).toBe('API is ready at /api/v1. Add auth next.')
+    expect(result.summary?.whatWasDone).toHaveLength(2)
+  })
+})

package/core/agentic/prompt-builder.ts

@@ -800,6 +800,24 @@ class PromptBuilder {
         if (currentSubtask.dependsOn.length > 0) {
           parts.push(`Dependencies: ${currentSubtask.dependsOn.join(', ')}\n`)
         }
+
+        // Inject previous subtask handoff for context continuity (PRJ-262)
+        if (currentSubtask.handoff) {
+          const h = currentSubtask.handoff
+          parts.push('\n### Previous Subtask Handoff\n\n')
+          parts.push(`**From:** ${h.fromSubtask}\n\n`)
+          parts.push('**What was done:**\n')
+          for (const item of h.whatWasDone) {
+            parts.push(`- ${item}\n`)
+          }
+          if (h.filesChanged.length > 0) {
+            parts.push('\n**Files changed:**\n')
+            for (const f of h.filesChanged) {
+              parts.push(`- \`${f.path}\` (${f.action})\n`)
+            }
+          }
+          parts.push(`\n**Context for this subtask:**\n${h.outputForNextAgent}\n`)
+        }
       }
       parts.push('\n')
     }

package/core/schemas/state.ts

@@ -44,11 +44,18 @@ export const SubtaskSummarySchema = z.object({
       action: z.enum(['created', 'modified', 'deleted']),
     })
   ),
-  whatWasDone: z.array(z.string()),
-  outputForNextAgent: z.string().optional(),
+  whatWasDone: z.array(z.string()).min(1),
+  outputForNextAgent: z.string().min(1),
   notes: z.string().optional(),
 })
 
+// Schema for validating completion data before persisting
+// Used by completeSubtask() to enforce mandatory handoff
+export const SubtaskCompletionDataSchema = z.object({
+  output: z.string().min(1, 'Subtask output is required'),
+  summary: SubtaskSummarySchema,
+})
+
 // Subtask schema for task fragmentation
 export const SubtaskSchema = z.object({
   id: z.string(), // subtask-xxx
@@ -169,6 +176,7 @@ export type ActivityType = z.infer<typeof ActivityTypeSchema>
 
 export type Subtask = z.infer<typeof SubtaskSchema>
 export type SubtaskSummary = z.infer<typeof SubtaskSummarySchema>
+export type SubtaskCompletionData = z.infer<typeof SubtaskCompletionDataSchema>
 export type SubtaskProgress = z.infer<typeof SubtaskProgressSchema>
 
 export type CurrentTask = z.infer<typeof CurrentTaskSchema>
@@ -197,6 +205,18 @@ export const parseQueue = (data: unknown): QueueJson => QueueJsonSchema.parse(da
 export const safeParseState = (data: unknown) => StateJsonSchema.safeParse(data)
 export const safeParseQueue = (data: unknown) => QueueJsonSchema.safeParse(data)
 
+/** Validate subtask completion data — returns errors or null */
+export const validateSubtaskCompletion = (
+  data: unknown
+): { success: true; data: SubtaskCompletionData } | { success: false; errors: string[] } => {
+  const result = SubtaskCompletionDataSchema.safeParse(data)
+  if (result.success) return { success: true, data: result.data }
+  return {
+    success: false,
+    errors: result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+  }
+}
+
 // =============================================================================
 // Defaults
 // =============================================================================

package/core/storage/state-storage.ts

@@ -14,9 +14,9 @@ import type {
   PreviousTask,
   StateJson,
   Subtask,
-  SubtaskSummary,
+  SubtaskCompletionData,
 } from '../schemas/state'
-import { StateJsonSchema } from '../schemas/state'
+import { StateJsonSchema, SubtaskCompletionDataSchema } from '../schemas/state'
 import { getTimestamp, toRelative } from '../utils/date-helper'
 import { md } from '../utils/markdown-builder'
 import type { WorkflowCommand } from '../workflow/state-machine'
@@ -497,14 +497,23 @@ class StateStorage extends StorageManager<StateJson> {
   }
 
   /**
-   * Complete current subtask and advance to next
-   * Returns the next subtask (or null if all complete)
+   * Complete current subtask and advance to next.
+   * Requires output and summary for mandatory handoff (PRJ-262).
+   * Returns the next subtask (or null if all complete).
    */
   async completeSubtask(
     projectId: string,
-    output?: string,
-    summary?: SubtaskSummary
+    completionData: SubtaskCompletionData
   ): Promise<Subtask | null> {
+    // Validate handoff data with Zod before persisting
+    const validation = SubtaskCompletionDataSchema.safeParse(completionData)
+    if (!validation.success) {
+      const errors = validation.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`)
+      throw new Error(`Subtask completion requires handoff data:\n${errors.join('\n')}`)
+    }
+
+    const { output, summary } = validation.data
+
     const state = await this.read(projectId)
     if (!state.currentTask?.subtasks) return null
 
@@ -512,7 +521,7 @@ class StateStorage extends StorageManager<StateJson> {
     const current = state.currentTask.subtasks[currentIndex]
     if (!current) return null
 
-    // Mark current as completed
+    // Mark current as completed with mandatory handoff
     const updatedSubtasks = [...state.currentTask.subtasks]
     updatedSubtasks[currentIndex] = {
       ...current,
@@ -548,12 +557,14 @@ class StateStorage extends StorageManager<StateJson> {
       lastUpdated: getTimestamp(),
     }))
 
-    // Publish event
+    // Publish event with handoff data
     await this.publishEvent(projectId, 'subtask.completed', {
       taskId: state.currentTask.id,
       subtaskId: current.id,
       description: current.description,
       output,
+      handoff: summary.outputForNextAgent,
+      filesChanged: summary.filesChanged.length,
       progress: { completed, total, percentage },
     })
 
@@ -592,6 +603,27 @@ class StateStorage extends StorageManager<StateJson> {
     return state.currentTask.subtasks[prevIndex] || null
   }
 
+  /**
+   * Get handoff from the most recently completed subtask (PRJ-262).
+   * Returns the summary.outputForNextAgent and related context,
+   * or null if no previous subtask or no handoff data.
+   */
+  async getPreviousHandoff(projectId: string): Promise<{
+    fromSubtask: string
+    outputForNextAgent: string
+    filesChanged: Array<{ path: string; action: string }>
+    whatWasDone: string[]
+  } | null> {
+    const prev = await this.getPreviousSubtask(projectId)
+    if (!prev?.summary?.outputForNextAgent) return null
+    return {
+      fromSubtask: prev.description,
+      outputForNextAgent: prev.summary.outputForNextAgent,
+      filesChanged: prev.summary.filesChanged,
+      whatWasDone: prev.summary.whatWasDone,
+    }
+  }
+
   /**
    * Get all subtasks
    */

package/core/types/agentic.ts

@@ -673,6 +673,13 @@ export interface OrchestratorSubtask {
   status: 'pending' | 'in_progress' | 'completed' | 'failed'
   dependsOn: string[]
   order: number
+  /** Handoff from previous subtask — injected into prompt for context continuity (PRJ-262) */
+  handoff?: {
+    fromSubtask: string
+    outputForNextAgent: string
+    filesChanged: Array<{ path: string; action: string }>
+    whatWasDone: string[]
+  }
 }
 
 /**

package/dist/bin/prjct.mjs

@@ -10212,7 +10212,7 @@ var init_shipped = __esm({
 
 // core/schemas/state.ts
 import { z as z14 } from "zod";
-var PrioritySchema, TaskTypeSchema, TaskSectionSchema, TaskStatusSchema, ActivityTypeSchema, SubtaskSummarySchema, SubtaskSchema, SubtaskProgressSchema, CurrentTaskSchema, PreviousTaskSchema, StateJsonSchema, QueueTaskSchema, QueueJsonSchema, StatsSchema, RecentActivitySchema, StateSchemaFull;
+var PrioritySchema, TaskTypeSchema, TaskSectionSchema, TaskStatusSchema, ActivityTypeSchema, SubtaskSummarySchema, SubtaskCompletionDataSchema, SubtaskSchema, SubtaskProgressSchema, CurrentTaskSchema, PreviousTaskSchema, StateJsonSchema, QueueTaskSchema, QueueJsonSchema, StatsSchema, RecentActivitySchema, StateSchemaFull;
 var init_state = __esm({
   "core/schemas/state.ts"() {
     "use strict";
@@ -10244,10 +10244,14 @@ var init_state = __esm({
           action: z14.enum(["created", "modified", "deleted"])
         })
       ),
-      whatWasDone: z14.array(z14.string()),
-      outputForNextAgent: z14.string().optional(),
+      whatWasDone: z14.array(z14.string()).min(1),
+      outputForNextAgent: z14.string().min(1),
       notes: z14.string().optional()
     });
+    SubtaskCompletionDataSchema = z14.object({
+      output: z14.string().min(1, "Subtask output is required"),
+      summary: SubtaskSummarySchema
+    });
     SubtaskSchema = z14.object({
       id: z14.string(),
       // subtask-xxx
@@ -13259,10 +13263,18 @@ var init_state_storage = __esm({
         });
       }
       /**
-       * Complete current subtask and advance to next
-       * Returns the next subtask (or null if all complete)
+       * Complete current subtask and advance to next.
+       * Requires output and summary for mandatory handoff (PRJ-262).
+       * Returns the next subtask (or null if all complete).
        */
-      async completeSubtask(projectId, output, summary) {
+      async completeSubtask(projectId, completionData) {
+        const validation = SubtaskCompletionDataSchema.safeParse(completionData);
+        if (!validation.success) {
+          const errors = validation.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`);
+          throw new Error(`Subtask completion requires handoff data:
+${errors.join("\n")}`);
+        }
+        const { output, summary } = validation.data;
         const state = await this.read(projectId);
         if (!state.currentTask?.subtasks) return null;
         const currentIndex = state.currentTask.currentSubtaskIndex || 0;
@@ -13302,6 +13314,8 @@ var init_state_storage = __esm({
           subtaskId: current.id,
           description: current.description,
           output,
+          handoff: summary.outputForNextAgent,
+          filesChanged: summary.filesChanged.length,
           progress: { completed, total, percentage }
         });
         return nextIndex < total ? updatedSubtasks[nextIndex] : null;
@@ -13334,6 +13348,21 @@ var init_state_storage = __esm({
         if (prevIndex < 0) return null;
         return state.currentTask.subtasks[prevIndex] || null;
       }
+      /**
+       * Get handoff from the most recently completed subtask (PRJ-262).
+       * Returns the summary.outputForNextAgent and related context,
+       * or null if no previous subtask or no handoff data.
+       */
+      async getPreviousHandoff(projectId) {
+        const prev = await this.getPreviousSubtask(projectId);
+        if (!prev?.summary?.outputForNextAgent) return null;
+        return {
+          fromSubtask: prev.description,
+          outputForNextAgent: prev.summary.outputForNextAgent,
+          filesChanged: prev.summary.filesChanged,
+          whatWasDone: prev.summary.whatWasDone
+        };
+      }
       /**
        * Get all subtasks
        */
@@ -16386,6 +16415,29 @@ Read files before modifying.
 `);
             if (currentSubtask.dependsOn.length > 0) {
               parts.push(`Dependencies: ${currentSubtask.dependsOn.join(", ")}
+`);
+            }
+            if (currentSubtask.handoff) {
+              const h = currentSubtask.handoff;
+              parts.push("\n### Previous Subtask Handoff\n\n");
+              parts.push(`**From:** ${h.fromSubtask}
+
+`);
+              parts.push("**What was done:**\n");
+              for (const item of h.whatWasDone) {
+                parts.push(`- ${item}
+`);
+              }
+              if (h.filesChanged.length > 0) {
+                parts.push("\n**Files changed:**\n");
+                for (const f of h.filesChanged) {
+                  parts.push(`- \`${f.path}\` (${f.action})
+`);
+                }
+              }
+              parts.push(`
+**Context for this subtask:**
+${h.outputForNextAgent}
 `);
             }
           }
@@ -31050,7 +31102,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "prjct-cli",
-      version: "1.11.0",
+      version: "1.12.0",
       description: "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
       main: "core/index.ts",
       bin: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
   "main": "core/index.ts",
   "bin": {

package/templates/commands/done.md

@@ -43,34 +43,102 @@ IF currentTask.subtasks exists AND has items:
         - label: "Continue current"
           description: "Keep working on this subtask"
 
-    IF "Next subtask":
-      # Mark current subtask as completed
+    IF "Continue current":
+      OUTPUT: "Continuing: {current subtask}"
+      STOP
+
+    IF "Next subtask" OR "Complete all remaining":
+      # ═══════════════════════════════════════════════════════════════
+      # MANDATORY HANDOFF COLLECTION (PRJ-262)
+      # Every subtask MUST provide handoff data before completing.
+      # This enables the next subtask to start with full context.
+      # ═══════════════════════════════════════════════════════════════
+
+      GOTO: Step 3.5 (Collect Handoff)
+
+      # After collecting handoff, mark current subtask as completed:
       currentTask.subtasks[currentSubtaskIndex].status = "completed"
-      currentTask.currentSubtaskIndex++
-      currentTask.subtasks[currentSubtaskIndex].status = "active"
-      currentTask.description = currentTask.subtasks[currentSubtaskIndex].description
+      currentTask.subtasks[currentSubtaskIndex].output = "{handoff.output}"
+      currentTask.subtasks[currentSubtaskIndex].summary = {
+        "title": "{current subtask description}",
+        "description": "{what was accomplished}",
+        "filesChanged": [{path, action}...],
+        "whatWasDone": ["item1", "item2", ...],
+        "outputForNextAgent": "{context for next subtask}",
+        "notes": "{optional notes}"
+      }
 
-      WRITE state.json
+      IF "Next subtask":
+        currentTask.currentSubtaskIndex++
+        currentTask.subtasks[currentSubtaskIndex].status = "active"
+        currentTask.description = currentTask.subtasks[currentSubtaskIndex].description
 
-      OUTPUT:
-      """
-      ✅ Subtask complete: {completed subtask}
+        WRITE state.json
 
-      Progress: {completed}/{total} subtasks
+        # Show previous subtask handoff to establish context
+        OUTPUT:
+        """
+        ✅ Subtask complete: {completed subtask}
 
-      Current: {next subtask description}
+        Progress: {completed}/{total} subtasks
 
-      Next: Continue working, then `p. done`
-      """
-      STOP
+        ### Handoff
+        {outputForNextAgent}
 
-    IF "Continue current":
-      OUTPUT: "Continuing: {current subtask}"
-      STOP
+        Current: {next subtask description}
+
+        Next: Continue working, then `p. done`
+        """
+        STOP
+
+      # If "Complete all" - fall through to complete task (handoff still collected)
+```
+
+## Step 3.5: Collect Handoff (MANDATORY for subtask completion)
+
+**⛔ DO NOT skip this step. Every subtask completion MUST include handoff data.**
 
-    # If "Complete all" - fall through to complete task
+The LLM should analyze the work done during this subtask and produce:
+
+### 1. Get Files Changed
+
+```bash
+# Files changed during this subtask (uncommitted + recent commits on branch)
+git diff --name-only HEAD 2>/dev/null
+git diff --name-only --cached 2>/dev/null
 ```
 
+Categorize each file as `created`, `modified`, or `deleted`.
+
+### 2. Summarize Work Done
+
+Based on the code changes and task context, produce:
+- **whatWasDone**: Array of 1-5 bullet points describing key accomplishments
+- **outputForNextAgent**: A paragraph explaining context the next subtask needs:
+  - What was built/changed and why
+  - Key decisions made and their rationale
+  - Any patterns established that subsequent work should follow
+  - Known issues or edge cases to watch for
+
+### 3. Validation
+
+```
+IF whatWasDone is empty:
+  ⛔ STOP. At least one item is required.
+  Re-analyze the work and provide at minimum 1 bullet point.
+
+IF outputForNextAgent is empty:
+  ⛔ STOP. Context for next subtask is required.
+  Even if this is the last subtask, provide a summary for the done/ship step.
+```
+
+### 4. Store Handoff
+
+The handoff data is stored in the subtask's `summary` field in state.json.
+This data persists across sessions and feeds into the next subtask's prompt context.
+
+---
+
 ## Step 4: Complete Task
 
 Generate timestamp: