aiwcli 0.10.2 → 0.11.0

package/dist/lib/template-installer.js

@@ -2,98 +2,6 @@ import { promises as fs } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { IdePathResolver } from './ide-path-resolver.js';
 import { pathExists } from './paths.js';
-import { mergeTemplateContent } from './template-merger.js';
-/**
- * Deep merge two settings objects, combining hook arrays.
- * Used to merge _shared/settings.json into .claude/settings.json
- */
-function deepMergeSettings(target, source) {
-    const result = { ...target };
-    for (const key of Object.keys(source)) {
-        // Skip comment fields
-        if (key.startsWith('$') || key.startsWith('_')) {
-            continue;
-        }
-        const sourceValue = source[key];
-        const targetValue = result[key];
-        if (key === 'hooks' && typeof sourceValue === 'object' && sourceValue !== null) {
-            // Special handling for hooks - merge by event type
-            result[key] = mergeHooks(targetValue || {}, sourceValue);
-        }
-        else if (Array.isArray(sourceValue) && Array.isArray(targetValue)) {
-            // Concatenate arrays
-            result[key] = [...targetValue, ...sourceValue];
-        }
-        else if (typeof sourceValue === 'object' && sourceValue !== null && typeof targetValue === 'object' && targetValue !== null) {
-            // Recursively merge objects
-            result[key] = deepMergeSettings(targetValue, sourceValue);
-        }
-        else {
-            // Override with source value
-            result[key] = sourceValue;
-        }
-    }
-    return result;
-}
-/**
- * Merge hook configurations, combining arrays for each event type.
- */
-function mergeHooks(target, source) {
-    const result = { ...target };
-    for (const eventType of Object.keys(source)) {
-        const targetHooks = result[eventType];
-        const sourceHooks = source[eventType];
-        if (targetHooks && sourceHooks) {
-            // Append source hooks to existing event type
-            result[eventType] = [...targetHooks, ...sourceHooks];
-        }
-        else if (sourceHooks) {
-            // New event type
-            result[eventType] = sourceHooks;
-        }
-    }
-    return result;
-}
-/**
- * Merge settings from a source settings.json file into the IDE settings file.
- * Reads from the provided source path and merges into .claude/settings.json at project root.
- *
- * @param targetDir - Project root directory
- * @param sourceSettingsPath - Absolute path to source settings.json file
- * @returns true if merge successful, false otherwise
- */
-async function mergeSharedSettingsFromSource(targetDir, sourceSettingsPath) {
-    const resolver = new IdePathResolver(targetDir);
-    const ideSettingsPath = resolver.getClaudeSettings();
-    // Check if source settings exists
-    if (!(await pathExists(sourceSettingsPath))) {
-        return false;
-    }
-    try {
-        // Read source settings
-        const sourceContent = await fs.readFile(sourceSettingsPath, 'utf8');
-        const sourceSettings = JSON.parse(sourceContent);
-        // Read IDE settings (create empty object if doesn't exist)
-        let ideSettings = {};
-        if (await pathExists(ideSettingsPath)) {
-            const ideContent = await fs.readFile(ideSettingsPath, 'utf8');
-            ideSettings = JSON.parse(ideContent);
-        }
-        else {
-            // Create .claude directory if it doesn't exist
-            await fs.mkdir(dirname(ideSettingsPath), { recursive: true });
-        }
-        // Merge source settings into IDE settings
-        const mergedSettings = deepMergeSettings(ideSettings, sourceSettings);
-        // Write merged settings back
-        await fs.writeFile(ideSettingsPath, JSON.stringify(mergedSettings, null, 4) + '\n', 'utf8');
-        return true;
-    }
-    catch {
-        // Silently fail on parse/write errors
-        return false;
-    }
-}
 /**
  * Check template installation status for a method.
  * Returns which items exist and which are missing.
@@ -186,32 +94,6 @@ export function shouldExclude(name) {
         return pattern.test(name);
     });
 }
-/**
- * Merge source directory into destination, skipping existing files.
- * Unlike copyDir, this preserves existing files in destination.
- *
- * @param src - Source directory path
- * @param dest - Destination directory path
- */
-async function mergeDirectory(src, dest) {
-    await fs.mkdir(dest, { recursive: true });
-    const entries = await fs.readdir(src, { withFileTypes: true });
-    for (const entry of entries) {
-        if (shouldExclude(entry.name))
-            continue;
-        const srcPath = join(src, entry.name);
-        const destPath = join(dest, entry.name);
-        if (entry.isDirectory()) {
-            await mergeDirectory(srcPath, destPath);
-        }
-        else {
-            // Skip if file already exists
-            if (!(await pathExists(destPath))) {
-                await fs.copyFile(srcPath, destPath);
-            }
-        }
-    }
-}
 /**
  * Copy directory recursively with proper error handling.
  * Excludes test files, cache directories, and output folders.
@@ -249,20 +131,45 @@ export async function copyDir(src, dest, excludeIdeFolders = false) {
     });
     await Promise.all(operations);
 }
+/**
+ * Merge source directory into destination, skipping existing files.
+ * Unlike copyDir, this preserves existing files in destination.
+ *
+ * @param src - Source directory path
+ * @param dest - Destination directory path
+ */
+async function mergeDirectory(src, dest) {
+    await fs.mkdir(dest, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    const ops = entries
+        .filter((entry) => !shouldExclude(entry.name))
+        .map(async (entry) => {
+        const srcPath = join(src, entry.name);
+        const destPath = join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await mergeDirectory(srcPath, destPath);
+        }
+        else if (!(await pathExists(destPath))) {
+            await fs.copyFile(srcPath, destPath);
+        }
+    });
+    await Promise.all(ops);
+}
 /**
  * Install template with IDE-specific folder selection.
- * Supports selective installation - only installs items that don't already exist.
  *
  * Template structure:
- * - Non-dot folders (e.g., _bmad/, GSR/) are installed if not already present
- * - Dot folders (e.g., .claude/, .windsurf/) are installed only if matching IDE flag and not already present
+ * - Non-dot folders (e.g., _bmad/, GSR/) → .aiwcli/ (always overwritten)
+ * - _shared/ → .aiwcli/_shared/ (always overwritten)
+ * - IDE dot folders (e.g., .claude/) → decomposed into method-owned subdirs
+ *
+ * Settings reconstruction is handled separately by the caller via reconstructIdeSettings().
  *
  * @param config - Installation configuration
- * @param skipExisting - If true, skip items that already exist (default: true for regeneration support)
- * @returns Installation result with list of installed and skipped folders
+ * @returns Installation result with list of installed folders
  * @throws Error if template doesn't exist or requested IDE folder not found
  */
-export async function installTemplate(config, skipExisting = true) {
+export async function installTemplate(config) {
     const { templateName, targetDir, ides, templatePath } = config;
     // Verify template exists
     try {
@@ -295,108 +202,77 @@ export async function installTemplate(config, skipExisting = true) {
             `Available: ${availableIdes.join(', ')}`);
     }
     const installedFolders = [];
-    const skippedFolders = [];
-    const mergedFolders = [];
-    let mergedFileCount = 0;
     // Create .aiwcli container folder for method-specific files
     const resolver = new IdePathResolver(targetDir);
     const containerDir = resolver.getAiwcliContainer();
     await fs.mkdir(containerDir, { recursive: true });
-    // Install non-dot folders into .aiwcli/ container (skip if already exist and skipExisting is true)
+    // Install non-dot folders into .aiwcli/ container (always overwrite)
     const nonDotInstalls = nonDotFolders.map(async (folder) => {
         const srcPath = join(templatePath, folder);
-        // Destination is inside .aiwcli/ container
         const destPath = join(containerDir, folder);
-        if (skipExisting && (await pathExists(destPath))) {
-            return { folder, skipped: true };
-        }
         await copyDir(srcPath, destPath);
-        return { folder, skipped: false };
+        return folder;
     });
     const nonDotResults = await Promise.all(nonDotInstalls);
-    for (const result of nonDotResults) {
-        if (result.skipped) {
-            skippedFolders.push(result.folder);
-        }
-        else {
-            installedFolders.push(result.folder);
-        }
-    }
+    installedFolders.push(...nonDotResults);
     // Install root-level _shared directory (shared across all templates)
-    // This is at templates/_shared, not inside the specific template directory
     // Exclude IDE config folders (.claude, .windsurf) - they are used for settings merging only
     const templatesRoot = dirname(templatePath);
     const rootSharedSrc = join(templatesRoot, '_shared');
     const rootSharedDest = join(containerDir, '_shared');
     if (await pathExists(rootSharedSrc)) {
-        if (skipExisting && (await pathExists(rootSharedDest))) {
-            skippedFolders.push('_shared');
-        }
-        else {
-            await copyDir(rootSharedSrc, rootSharedDest, true); // excludeIdeFolders = true
-            installedFolders.push('_shared');
-        }
-        // Merge shared IDE folders (commands, workflows) into project IDE folders
-        // This handles _shared/.claude/, _shared/.windsurf/, etc.
+        await copyDir(rootSharedSrc, rootSharedDest, true); // excludeIdeFolders = true
+        installedFolders.push('_shared');
+        // Copy shared IDE content (e.g., _shared/.claude/commands/handoff.md)
+        // These are non-method-owned files that live in IDE folders
         const sharedIdeInstalls = ides.map(async (ide) => {
             const sharedIdeFolder = join(rootSharedSrc, `.${ide}`);
             if (await pathExists(sharedIdeFolder)) {
                 const destIdeFolder = resolver.getIdeDir(ide);
                 await fs.mkdir(destIdeFolder, { recursive: true });
-                // Recursively copy, but skip files that already exist
+                // Merge shared IDE content, skipping files that already exist
                 await mergeDirectory(sharedIdeFolder, destIdeFolder);
             }
         });
         await Promise.all(sharedIdeInstalls);
     }
-    // Install matching IDE folders
-    // If folder exists, merge content recursively by looking for method name folders
+    // Install method-owned IDE content (decomposed approach)
+    // Instead of copying entire .claude/ from template, only copy method-namespaced subdirectories
     const ideInstalls = ides.map(async (ide) => {
         const folderName = dotFolders.get(ide);
-        if (folderName) {
-            const srcPath = join(templatePath, folderName);
-            const destPath = resolver.getIdeDir(ide);
-            if (await pathExists(destPath)) {
-                if (skipExisting) {
-                    // Folder exists - merge template content by finding method-named folders
-                    const mergeResult = await mergeTemplateContent(srcPath, destPath, templateName);
-                    return {
-                        folder: folderName,
-                        skipped: false,
-                        merged: true,
-                        mergedFiles: mergeResult.copiedFiles.length,
-                    };
-                }
-                // skipExisting is false, so overwrite
-                await copyDir(srcPath, destPath);
-                return { folder: folderName, skipped: false, merged: false, mergedFiles: 0 };
+        if (!folderName)
+            return null;
+        const srcIdePath = join(templatePath, folderName);
+        const destIdePath = resolver.getIdeDir(ide);
+        await fs.mkdir(destIdePath, { recursive: true });
+        // Scan the template IDE folder for subdirectories and copy method-owned content
+        const ideEntries = await fs.readdir(srcIdePath, { withFileTypes: true });
+        const subdirOps = ideEntries
+            .filter((entry) => entry.isDirectory())
+            .map(async (entry) => {
+            const subdirSrc = join(srcIdePath, entry.name);
+            const subdirDest = join(destIdePath, entry.name);
+            // Check for method-namespaced child within this subdirectory
+            const methodChildSrc = join(subdirSrc, templateName);
+            if (await pathExists(methodChildSrc)) {
+                // Copy only the method-namespaced subdirectory (overwrite)
+                const methodChildDest = join(subdirDest, templateName);
+                await copyDir(methodChildSrc, methodChildDest);
             }
-            await copyDir(srcPath, destPath);
-            return { folder: folderName, skipped: false, merged: false, mergedFiles: 0 };
-        }
-        return null;
+            else {
+                // No method-namespaced child — copy the entire subdirectory, merging with existing
+                await mergeDirectory(subdirSrc, subdirDest);
+            }
+        });
+        await Promise.all(subdirOps);
+        return folderName;
     });
     const ideResults = (await Promise.all(ideInstalls)).filter((result) => result !== null);
-    for (const result of ideResults) {
-        if (result.merged) {
-            mergedFolders.push(result.folder);
-            mergedFileCount += result.mergedFiles;
-        }
-        else if (result.skipped) {
-            skippedFolders.push(result.folder);
-        }
-        else {
-            installedFolders.push(result.folder);
-        }
-    }
-    // Settings merging is now handled by the caller via mergeMethodsSettings()
-    // This allows unified merging of _shared + method-specific settings
+    installedFolders.push(...ideResults);
+    // Settings reconstruction is handled by the caller via reconstructIdeSettings()
     return {
         installedFolders,
-        skippedFolders,
-        mergedFolders,
-        mergedFileCount,
-        sharedSettingsMerged: false, // Deprecated, kept for backwards compatibility
+        sharedSettingsMerged: false,
         templatePath,
     };
 }

package/dist/lib/template-settings-reconstructor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Unified reconstruction of shared IDE settings files.
+ *
+ * Both `aiw init` and `aiw clear` use the same operation: reconstruct shared
+ * settings from the union of all active templates. Install adds a template to
+ * the list; clear removes one. The reconstruction logic is identical.
+ *
+ * Template files fall into two categories:
+ * 1. **Method-owned** — lives in method-namespaced paths (e.g., `.claude/commands/cc-native/`),
+ *    owned exclusively by one template. Handled by copy/delete, not by this module.
+ * 2. **Shared** — lives in common locations (e.g., `settings.json`), multiple templates
+ *    contribute. Handled by this module via reconstruction from source.
+ *
+ * @module lib/template-settings-reconstructor
+ */
+/**
+ * Reconstruct .claude/settings.json and .windsurf/hooks.json from the union
+ * of all specified templates.
+ *
+ * The function:
+ * 1. Starts with empty settings
+ * 2. Merges _shared template settings (always included)
+ * 3. For each active template, merges its template-source settings
+ * 4. Writes the result to the IDE settings file
+ *
+ * Uses mergeClaudeSettings() from hooks-merger.ts for dedup-aware merging.
+ *
+ * Install calls: reconstructIdeSettings(targetDir, [...existingTemplates, newTemplate], ides)
+ * Clear calls:   reconstructIdeSettings(targetDir, existingTemplates.filter(t => t !== removed), ides)
+ *
+ * @param targetDir - Project root directory
+ * @param activeTemplates - Template names to include (e.g., ['cc-native', 'bmad'])
+ * @param ides - IDEs to reconstruct for (e.g., ['claude', 'windsurf'])
+ */
+export declare function reconstructIdeSettings(targetDir: string, activeTemplates: string[], ides: string[]): Promise<void>;

package/dist/lib/template-settings-reconstructor.js

@@ -0,0 +1,130 @@
+/**
+ * Unified reconstruction of shared IDE settings files.
+ *
+ * Both `aiw init` and `aiw clear` use the same operation: reconstruct shared
+ * settings from the union of all active templates. Install adds a template to
+ * the list; clear removes one. The reconstruction logic is identical.
+ *
+ * Template files fall into two categories:
+ * 1. **Method-owned** — lives in method-namespaced paths (e.g., `.claude/commands/cc-native/`),
+ *    owned exclusively by one template. Handled by copy/delete, not by this module.
+ * 2. **Shared** — lives in common locations (e.g., `settings.json`), multiple templates
+ *    contribute. Handled by this module via reconstruction from source.
+ *
+ * @module lib/template-settings-reconstructor
+ */
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mergeClaudeSettings } from './hooks-merger.js';
+import { IdePathResolver } from './ide-path-resolver.js';
+import { readClaudeSettings, writeClaudeSettings } from './settings-hierarchy.js';
+import { getTemplatePath } from './template-resolver.js';
+import { getTargetHooksFile, readWindsurfHooks, writeWindsurfHooks } from './windsurf-hooks-hierarchy.js';
+import { mergeWindsurfHooks } from './windsurf-hooks-merger.js';
+/**
+ * Get the path to the _shared template directory.
+ *
+ * @returns Absolute path to the _shared template
+ */
+function getSharedTemplatePath() {
+    const currentFilePath = fileURLToPath(import.meta.url);
+    const currentDir = dirname(currentFilePath);
+    return join(currentDir, '..', 'templates', '_shared');
+}
+/**
+ * Reconstruct .claude/settings.json and .windsurf/hooks.json from the union
+ * of all specified templates.
+ *
+ * The function:
+ * 1. Starts with empty settings
+ * 2. Merges _shared template settings (always included)
+ * 3. For each active template, merges its template-source settings
+ * 4. Writes the result to the IDE settings file
+ *
+ * Uses mergeClaudeSettings() from hooks-merger.ts for dedup-aware merging.
+ *
+ * Install calls: reconstructIdeSettings(targetDir, [...existingTemplates, newTemplate], ides)
+ * Clear calls:   reconstructIdeSettings(targetDir, existingTemplates.filter(t => t !== removed), ides)
+ *
+ * @param targetDir - Project root directory
+ * @param activeTemplates - Template names to include (e.g., ['cc-native', 'bmad'])
+ * @param ides - IDEs to reconstruct for (e.g., ['claude', 'windsurf'])
+ */
+export async function reconstructIdeSettings(targetDir, activeTemplates, ides) {
+    const sharedTemplatePath = getSharedTemplatePath();
+    if (ides.includes('claude')) {
+        await reconstructClaudeSettings(targetDir, activeTemplates, sharedTemplatePath);
+    }
+    if (ides.includes('windsurf')) {
+        await reconstructWindsurfHooks(targetDir, activeTemplates, sharedTemplatePath);
+    }
+}
+/**
+ * Reconstruct .claude/settings.json from scratch using template sources.
+ */
+async function reconstructClaudeSettings(targetDir, activeTemplates, sharedTemplatePath) {
+    const resolver = new IdePathResolver(targetDir);
+    const settingsPath = resolver.getClaudeSettings();
+    // Read existing settings to preserve non-template fields (methods tracking, etc.)
+    const existingSettings = await readClaudeSettings(settingsPath);
+    // Preserve the methods tracking from existing settings
+    const methodsTracking = existingSettings?.methods;
+    // Start from empty and merge all template settings
+    let reconstructed = {};
+    // 1. Merge _shared template settings
+    const sharedSettingsPath = join(sharedTemplatePath, '.claude', 'settings.json');
+    const sharedSettings = await readClaudeSettings(sharedSettingsPath);
+    if (sharedSettings) {
+        reconstructed = mergeClaudeSettings(reconstructed, sharedSettings);
+    }
+    // 2. Merge each active template's settings (sequential for deterministic merge order)
+    for (const template of activeTemplates) {
+        try {
+            const templatePath = await getTemplatePath(template); // eslint-disable-line no-await-in-loop
+            const templateSettingsPath = join(templatePath, '.claude', 'settings.json');
+            const templateSettings = await readClaudeSettings(templateSettingsPath); // eslint-disable-line no-await-in-loop
+            if (templateSettings) {
+                reconstructed = mergeClaudeSettings(reconstructed, templateSettings);
+            }
+        }
+        catch {
+            // Template not found — skip
+        }
+    }
+    // 3. Restore methods tracking
+    if (methodsTracking && Object.keys(methodsTracking).length > 0) {
+        reconstructed.methods = methodsTracking;
+    }
+    // 4. Write reconstructed settings
+    await writeClaudeSettings(settingsPath, reconstructed);
+}
+/**
+ * Reconstruct .windsurf/hooks.json from scratch using template sources.
+ */
+async function reconstructWindsurfHooks(targetDir, activeTemplates, sharedTemplatePath) {
+    const hooksPath = getTargetHooksFile(targetDir);
+    // Start from empty
+    let reconstructed = { hooks: {} };
+    // 1. Merge _shared template hooks
+    const sharedHooksPath = join(sharedTemplatePath, '.windsurf', 'hooks.json');
+    const sharedHooks = await readWindsurfHooks(sharedHooksPath);
+    if (sharedHooks) {
+        reconstructed = mergeWindsurfHooks(reconstructed, sharedHooks);
+    }
+    // 2. Merge each active template's hooks (sequential for deterministic merge order)
+    for (const template of activeTemplates) {
+        try {
+            const templatePath = await getTemplatePath(template); // eslint-disable-line no-await-in-loop
+            const templateHooksPath = join(templatePath, '.windsurf', 'hooks.json');
+            const templateHooks = await readWindsurfHooks(templateHooksPath); // eslint-disable-line no-await-in-loop
+            if (templateHooks) {
+                reconstructed = mergeWindsurfHooks(reconstructed, templateHooks);
+            }
+        }
+        catch {
+            // Template not found — skip
+        }
+    }
+    // 3. Write reconstructed hooks
+    await writeWindsurfHooks(hooksPath, reconstructed);
+}

package/dist/templates/CLAUDE.md

@@ -22,9 +22,9 @@ Each template installs into `.aiwcli/` (method files) and `.{ide}/` (IDE integra
 ```
 packages/cli/src/templates/
 ├── _shared/                          # Cross-method infrastructure (installed by all methods)
-│   ├── hooks/                        # Shared hook scripts (context, tasks, sessions)
-│   └── lib/                          # Shared Python libraries
-│       ├── base/                     #   Core: atomic_write, constants, inference, utils
+│   ├── hooks-ts/                     # Shared TypeScript hook scripts (context, tasks, sessions)
+│   └── lib-ts/                       # Shared TypeScript libraries
+│       ├── base/                     #   Core: atomic-write, constants, inference, utils
 │       ├── context/                  #   Context CRUD, selection, formatting, plans, tasks
 │       ├── handoff/                  #   Session handoff document generation
 │       └── templates/                #   Output formatters, plan context templates
@@ -85,7 +85,7 @@ When multiple templates install, settings.json files merge:
 
 ## Hooks
 
-**Location:** Hooks live in `.aiwcli/_shared/hooks/` (cross-method) and `.aiwcli/_{method}/hooks/` (method-specific). They are configured in `.{ide}/settings.json`, not placed in IDE directories.
+**Location:** Hooks live in `.aiwcli/_shared/hooks-ts/` (cross-method, TypeScript) and `.aiwcli/_{method}/hooks/` (method-specific). They are configured in `.{ide}/settings.json`, not placed in IDE directories.
 
 **Configuration:**
 ```json
@@ -93,14 +93,14 @@ When multiple templates install, settings.json files merge:
   "hooks": {
     "PostToolUse": [{
       "matcher": "Write",
-      "hooks": [{ "type": "command", "command": "python .aiwcli/_cc-native/hooks/cc-native-plan-review.py", "timeout": 300000 }]
+      "hooks": [{ "type": "command", "command": "bun run .aiwcli/_cc-native/hooks/cc-native-plan-review.ts", "timeout": 300000 }]
     }]
   }
 }
 ```
 
 **Requirements:**
-- Prefix method-specific hooks with method name (e.g., `cc-native-plan-review.py`)
+- Prefix method-specific hooks with method name (e.g., `cc-native-plan-review.ts`)
 - Use relative paths from project root
 - Write outputs to `_output/{method}/`
 - Specify timeouts
@@ -161,7 +161,7 @@ Load and execute `_{method}/workflows/{name}.md`.
 | Template file | `UPPERCASE.md.template` | `PROJECT.md.template` |
 | Workflow file | `kebab-case.md` | `new-project.md` |
 | Output file | `UPPERCASE.md` | `PROJECT.md` |
-| Hook file | `{method}-{name}.{ext}` | `gsd-plan-review.py` |
+| Hook file | `{method}-{name}.{ext}` | `gsd-plan-review.ts` |
 | Settings key | `{method}` | `"gsd": {}` |
 | Readme | `{METHOD}-README.md` | `GSD-README.md` |
 
@@ -202,4 +202,4 @@ Load and execute `_{method}/workflows/{name}.md`.
 - Full workflows in IDE command files
 - Hardcoded paths without method namespace
 - Putting hook scripts directly in IDE directories (`.claude/hooks/`)
-- Creating `_shared/` directories inside method templates (e.g., `cc-native/_shared/`). All shared code lives in `packages/cli/src/templates/_shared/`. Method templates reference shared code via sys.path at runtime, not by copying.
+- Creating `_shared/` directories inside method templates (e.g., `cc-native/_shared/`). All shared code lives in `packages/cli/src/templates/_shared/`. Method templates reference shared code via imports at runtime, not by copying.

package/dist/templates/_shared/.claude/commands/handoff-resume.md

@@ -0,0 +1,64 @@
+# Resume Handoff
+
+Restore session context from a handoff document programmatically, then create actionable ISC tasks so work continues without re-discovering what was already learned.
+
+## Arguments
+
+- `$ARGUMENTS` - Optional path to a handoff folder or index.md. If omitted, auto-discovers the most recent handoff from the active context.
+
+## Instructions
+
+### Step 1: Gather Context via Script
+
+Run the resume script to collect and format all handoff sections:
+
+**If `$ARGUMENTS` is provided:**
+```bash
+bun .aiwcli/_shared/scripts/resume_handoff.ts "$ARGUMENTS"
+```
+
+**If `$ARGUMENTS` is empty:**
+The script auto-discovers the active context ID programmatically — no manual lookup needed:
+```bash
+bun .aiwcli/_shared/scripts/resume_handoff.ts
+```
+
+Present the script's output to the conversation. The output is already structured in priority order (dead ends first, then pending items, decisions, git delta, completed work, context notes).
+
+If the script exits with an error, show the error message and stop.
+
+### Step 2: Create ISC Tasks
+
+Convert each actionable item from the script output into a task via `TaskCreate`:
+- Each pending issue from the **Pending Items** section
+- Each remaining plan item from the **Plan — Remaining Items** section
+
+Each task follows ISC format — ~8 words, states a desired end-state (not an action), and is binary testable in 2 seconds.
+
+**Example:**
+
+| Source | ISC Task |
+|--------|----------|
+| Pending: "Fix race condition in SessionStore" | "SessionStore handles concurrent access without race conditions" |
+| Plan remaining: "Add retry logic to API client" | "API client retries failed requests with exponential backoff" |
+| Next step: "Write tests for auth flow" | "Auth flow has passing integration test coverage" |
+
+### Step 3: Confirm Ready
+
+After creating tasks, run `TaskList` and confirm ready to continue.
+
+## Constraints
+
+- Dead ends are presented verbatim from the script output — never summarize or omit entries
+- ISC tasks use ~8-word end-state format, not action descriptions
+- Skip missing files gracefully (the script handles this)
+- If the script warns about staleness (>7 days), surface the warning prominently
+
+## Success Criteria
+
+- [ ] Script ran successfully and output the structured briefing
+- [ ] Dead ends visible in conversation (not summarized)
+- [ ] Pending items converted to ISC tasks via TaskCreate
+- [ ] Plan completion percentage visible (if plan exists)
+- [ ] Git delta visible
+- [ ] Tasks confirmed via TaskList