aiwcli 0.15.5 → 0.15.7

package/dist/templates/{_shared → core}/lib-ts/types.ts

@@ -5,128 +5,128 @@
  */
 
 // §1.1
-export type Mode = "idle" | "has_staged_work" | "active";
+export type Mode = "active" | "has_staged_work" | "idle";
 
 export interface ContextState {
-  id: string;
-  status: "active" | "completed";
-  summary: string;
-  method: string;
-  tags: string[];
   created_at: string;
+  /** @deprecated Use work_consumed instead */
+  handoff_consumed?: boolean;
+  handoff_path: null | string;
+  id: string;
   last_active: string;
+  last_session: LastSession | null;
+  method: string;
   mode: Mode;
-  plan_path: string | null;
-  plan_hash: string | null;
-  plan_signature: string | null;
-  plan_id: string | null;
+  next_artifact_type: "handoff" | "plan" | null;  // Explicit artifact type for has_staged_work mode
   plan_anchors: string[];
-  plan_hash_consumed: string | null;
-  handoff_path: string | null;
-  // Unified lifecycle fields (v0.13.0+)
-  work_consumed: boolean;  // Replaces plan_consumed + handoff_consumed
-  next_artifact_type: "plan" | "handoff" | null;  // Explicit artifact type for has_staged_work mode
   // Deprecated fields (kept for migration)
   /** @deprecated Use work_consumed instead */
   plan_consumed?: boolean;
-  /** @deprecated Use work_consumed instead */
-  handoff_consumed?: boolean;
+  plan_hash: null | string;
+  plan_hash_consumed: null | string;
+  plan_id: null | string;
+  plan_path: null | string;
+  plan_signature: null | string;
   session_ids: string[];
-  last_session: LastSession | null;
+  status: "active" | "completed";
+  summary: string;
+  tags: string[];
   tasks: Task[];
+  // Unified lifecycle fields (v0.13.0+)
+  work_consumed: boolean;  // Replaces plan_consumed + handoff_consumed
 }
 
 // §1.2
 export interface GitState {
   branch?: string;
-  uncommitted_files?: string[];
   last_commit_short?: string;
+  uncommitted_files?: string[];
 }
 
 export interface LastSession {
-  session_id?: string;
-  saved_at?: string;
-  save_reason?: string;
-  transcript_path?: string;
   context_remaining_pct?: number;
   context_warnings_fired?: number[];
   git_state?: GitState;
+  save_reason?: string;
+  saved_at?: string;
+  session_id?: string;
+  transcript_path?: string;
 }
 
 // §1.3
 export interface Task {
-  id: string;
-  subject: string;
-  description: string;
   active_form: string;
-  status: "pending" | "in_progress" | "completed" | "blocked";
+  completed_at: null | string;
   created_at: string;
-  completed_at: string | null;
+  description: string;
   evidence: string;
-  work_summary: string;
   files_changed: string[];
+  id: string;
   session_id?: string;
+  status: "blocked" | "completed" | "in_progress" | "pending";
+  subject: string;
+  work_summary: string;
 }
 
 // §1.4
 export interface IndexEntry {
-  summary: string;
-  mode: string;
   last_active: string;
+  mode: string;
+  summary: string;
 }
 
 export interface IndexFile {
-  version: "3.0";
-  updated_at: string;
-  sessions: Record<string, string>;
   contexts: Record<string, IndexEntry>;
+  sessions: Record<string, string>;
+  updated_at: string;
+  version: "3.0";
 }
 
 // §1.5
 export interface LogEntry {
-  ts: string;
-  level: "debug" | "info" | "warn" | "error";
+  component?: string;
+  data?: unknown;
   hook: string;
+  level: "debug" | "error" | "info" | "warn";
   msg: string;
-  component?: string;
-  data?: any;
   tb?: string;
+  ts: string;
 }
 
 // §1.6
 export interface HookInput {
-  hook_event_name: string;
-  tool_name?: string;
-  tool_input?: Record<string, any>;
-  tool_result?: string;
-  session_id?: string;
-  cwd?: string;
-  transcript_path?: string;
   context_window?: {
+    context_window_size?: number;
     current_usage?: {
+      cache_creation_input_tokens?: number;
       cache_read_input_tokens?: number;
       input_tokens?: number;
-      cache_creation_input_tokens?: number;
       output_tokens?: number;
     };
-    context_window_size?: number;
   };
+  cwd?: string;
+  hook_event_name: string;
   permission_mode?: string;
+  session_id?: string;
   source?: string;
+  tool_input?: Record<string, unknown>;
+  tool_name?: string;
+  tool_result?: string;
+  transcript_path?: string;
 }
 
 // §1.7 — Three hook output patterns (see hook-utils.ts for emit functions)
 export interface HookOutput {
+  // Pattern 2: Top-level decision (UserPromptSubmit, Stop, SubagentStop)
+  decision?: "block";
   // Pattern 1: hookSpecificOutput (PreToolUse, PostToolUse, UserPromptSubmit, etc.)
   hookSpecificOutput?: {
-    hookEventName?: string;
     additionalContext?: string;
-    permissionDecision?: "allow" | "deny" | "ask";
+    hookEventName?: string;
+    permissionDecision?: "allow" | "ask" | "deny";
     permissionDecisionReason?: string;
     updatedInput?: Record<string, unknown>;
   };
-  // Pattern 2: Top-level decision (UserPromptSubmit, Stop, SubagentStop)
-  decision?: "block";
   reason?: string;
 }
 
@@ -142,62 +142,63 @@ export interface PermissionRequestOutput {
 
 // §1.8
 export interface InferenceResult {
-  success: boolean;
-  output: string;
   error?: string;
   latency_ms: number;
+  output: string;
+  success: boolean;
 }
 
 // §1.9
 export interface HandoffDocument {
+  active_tasks: Task[];
+  completed_tasks_this_session: Array<{ subject: string }>;
+  context_folder: string;
   context_id: string;
   context_summary: string;
-  session_id: string;
-  reason: string;
   created_at: string;
-  plan_path: string | null;
-  context_folder: string;
   events_log_path: string;
-  active_tasks: Task[];
-  completed_tasks_this_session: Array<{ subject: string }>;
-  work_summary: string;
-  next_steps: string[];
+  file_path: null | string;
   important_notes: string[];
-  file_path: string | null;
+  next_steps: string[];
+  plan_path: null | string;
+  reason: string;
+  session_id: string;
+  work_summary: string;
 }
 
 // §1.10
 export interface HandoffSections {
-  index: string | null;
-  deadEnds: string | null;
-  pending: string | null;
-  plan: string | null;
-  decisions: string | null;
-  completedWork: string | null;
-  context: string | null;
+  completedWork: null | string;
+  context: null | string;
+  deadEnds: null | string;
+  decisions: null | string;
+  index: null | string;
+  pending: null | string;
+  plan: null | string;
 }
 
 // §1.11
 export interface CaretCommand {
   ends: string[];
-  select: string | null;
-  new_context_desc: string | null;
+  new_context_desc: null | string;
   remaining_prompt: string;
+  select: null | string;
 }
 
 // §1.12 — Preflight types (shared across hooks)
-// Re-exported from base/preflight.ts for convenience
-export type { PreflightCommandConfig, PreflightCheckResult } from "./base/preflight.js";
+// Re-exported from runtime/preflight.ts for convenience
+export type { PreflightCheckResult, PreflightCommandConfig } from "./runtime/preflight.js";
 
 // §1.13 — Agent configuration (shared across templates)
 
 /** Configuration for a CLI review agent */
 export interface AgentConfig {
-  name: string;
-  model: string;
-  provider: string; // e.g. "claude" | "codex" — assigned at runtime by assignModelsToAgents()
-  focus: string;
   categories: string[];
   description: string;
+  focus: string;
+  model: string;
+  name: string;
+  provider: string; // e.g. "claude" | "codex" — assigned at runtime by assignModelsToAgents()
   system_prompt: string; // Markdown body content for --system-prompt
 }
+

package/dist/templates/core/scripts/resolve-run.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env bun
+/**
+ * Cross-platform project root resolver for hook and status line commands.
+ *
+ * Finds the project root, sets cwd, then dynamically imports the target script
+ * in-process (no second bun spawn). stdin/stdout/stderr pass through naturally.
+ *
+ * Root detection strategy (fastest first):
+ *   1. Derive from this script's own location (O(1) — no I/O)
+ *   2. Walk up from cwd to find .aiwcli/ anchor (O(depth) — a few stat calls)
+ *
+ * Usage:    bun .aiwcli/_core/scripts/resolve-run.ts .aiwcli/_core/hooks-ts/hook.ts
+ */
+import * as fs from "node:fs";
+import path from "node:path";
+
+function findProjectRoot(): string {
+  // 1. Derive from script location: .aiwcli/_core/scripts/resolve-run.ts → 3 levels up
+  const derived = path.resolve(import.meta.dir, "..", "..", "..");
+  if (fs.existsSync(path.join(derived, ".aiwcli"))) return derived;
+
+  // 2. Walk up from cwd to find .aiwcli/ anchor
+  let dir = process.cwd();
+  while (true) {
+    if (fs.existsSync(path.join(dir, ".aiwcli"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return process.cwd(); // last resort
+}
+
+const target = process.argv[2];
+if (!target) {
+  process.stderr.write("resolve-run: missing script path argument\n");
+  process.exit(1);
+}
+
+const root = findProjectRoot();
+const fullPath = path.resolve(root, target);
+
+if (!fs.existsSync(fullPath)) {
+  process.stderr.write(`resolve-run: script not found: ${fullPath}\n`);
+  process.exit(1);
+}
+
+// Set up environment before importing the hook
+process.env.AIW_CALLER_CWD = process.cwd();
+
+// Scope FORCE_COLOR to status line only — other hooks may emit structured
+// output that should not contain ANSI escape codes.
+if (fullPath.endsWith("status_line.ts")) {
+  process.env.FORCE_COLOR ??= "2";
+}
+
+process.chdir(root);
+await import(fullPath);
+
+
+

package/dist/templates/{_shared → core}/scripts/resolve_context.ts

@@ -3,7 +3,7 @@
  * Resolve and print the active context ID.
  *
  * Usage:
- *   bun .aiwcli/_shared/scripts/resolve_context.ts
+ *   bun .aiwcli/_core/scripts/resolve_context.ts
  *
  * Prints the context ID to stdout. Exits 1 if no active context found.
  * Used by command templates (/handoff, /handoff-resume) to programmatically
@@ -11,9 +11,9 @@
  *
  * Requires CLAUDE_SESSION_ID environment variable (set by Claude Code).
  */
-import { getProjectRoot } from "../lib-ts/base/constants.js";
-import { eprint } from "../lib-ts/base/utils.js";
 import { getContextBySessionId } from "../lib-ts/context/context-store.js";
+import { getProjectRoot } from "../lib-ts/runtime/constants.js";
+import { eprint } from "../lib-ts/runtime/utils.js";
 
 const projectRoot = getProjectRoot(process.cwd());
 const sessionId = process.env.CLAUDE_SESSION_ID;

package/dist/templates/{_shared → core}/scripts/status_line.ts

@@ -12,7 +12,8 @@
 import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import { homedir } from "node:os";
-import * as path from "node:path";
+import path from "node:path";
+
 import type { ContextState } from "../lib-ts/types.js";
 
 // PAI infrastructure imports — graceful fallback when libs aren't available
@@ -25,7 +26,7 @@ let saveState: (id: string, state: ContextState) => void = () => {};
 let findLatestPlan: (contextId: string) => string | null = () => null;
 
 try {
-	const hookUtils = await import("../lib-ts/base/hook-utils.js");
+	const hookUtils = await import("../lib-ts/hooks/hook-utils.js");
 	CONTEXT_BASELINE_TOKENS = hookUtils.CONTEXT_BASELINE_TOKENS;
 } catch {
 	/* PAI hook-utils not available */
@@ -52,7 +53,7 @@ try {
 // Path setup
 // ---------------------------------------------------------------------------
 const SCRIPT_DIR = path.dirname(new URL(import.meta.url).pathname);
-// Resolve project root from script location (.aiwcli/_shared/scripts/) so paths
+// Resolve project root from script location (.aiwcli/_core/scripts/) so paths
 // work even when cwd has drifted via `cd` in a Bash tool call.
 const PROJECT_ROOT = path.resolve(SCRIPT_DIR, "..", "..", "..");
 const OUTPUT_DIR = path.join(PROJECT_ROOT, "_output");
@@ -213,19 +214,18 @@ function renderContextBar(width: number, pct: number): [string, string] {
 // Display width helper — accounts for wide Unicode and ANSI escapes
 // ---------------------------------------------------------------------------
 
-// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape stripping requires \x1b
-const ANSI_RE = /\x1b\[[0-9;]*m/g;
+const ANSI_RE = new RegExp(`${String.raw`\u001B`}\\[[0-9;]*m`, "g");
 
 function isWideChar(cp: number): boolean {
 	return (
-		cp === 0x26c1 || // ⛁ draughts man
-		cp === 0x23f1 || // ⏱ stopwatch
-		(cp >= 0x2600 && cp <= 0x26ff) || // misc symbols
-		(cp >= 0x2700 && cp <= 0x27bf) || // dingbats
-		(cp >= 0x1f300 && cp <= 0x1faff) || // emoji
-		(cp >= 0xfe00 && cp <= 0xfe0f) || // variation selectors
-		(cp >= 0x4e00 && cp <= 0x9fff) || // CJK
-		(cp >= 0x3000 && cp <= 0x303f) // CJK symbols
+		cp === 0x26_c1 || // ⛁ draughts man
+		cp === 0x23_f1 || // ⏱ stopwatch
+		(cp >= 0x26_00 && cp <= 0x26_ff) || // misc symbols
+		(cp >= 0x27_00 && cp <= 0x27_bf) || // dingbats
+		(cp >= 0x1_f3_00 && cp <= 0x1_fa_ff) || // emoji
+		(cp >= 0xfe_00 && cp <= 0xfe_0f) || // variation selectors
+		(cp >= 0x4e_00 && cp <= 0x9f_ff) || // CJK
+		(cp >= 0x30_00 && cp <= 0x30_3f) // CJK symbols
 	);
 }
 
@@ -404,7 +404,7 @@ function runGit(args: string[], cwd: string, timeout = 2000): string | null {
 		const result = execFileSync("git", args, {
 			cwd,
 			timeout,
-			encoding: "utf-8",
+			encoding: "utf8",
 			stdio: ["pipe", "pipe", "pipe"],
 			windowsHide: true,
 		});
@@ -687,12 +687,15 @@ function renderContextManager(
 	// Note: termWidth not available here — caller truncates via main()
 	switch (mode) {
 		case "micro":
-		case "nano":
+		case "nano": {
 			return `${CTX_ACCENT}\u25C6${RESET} ${SLATE_400}${truncatedId}${RESET}${modeBadge}`;
-		case "mini":
+		}
+		case "mini": {
 			return `${CTX_ACCENT}\u25C6${RESET} ${SLATE_400}${truncatedId}${RESET}${modeBadge}${planPart}`;
-		default:
+		}
+		default: {
 			return `${CTX_ACCENT}\u25C6${RESET} ${CTX_SECONDARY}Context:${RESET} ${SLATE_300}${truncatedId}${RESET}${modeBadge}${planPart}`;
+		}
 	}
 }
 
@@ -715,7 +718,7 @@ interface StatuslineCache {
 function loadCache(): StatuslineCache {
 	try {
 		if (fs.existsSync(STATUSLINE_CACHE)) {
-			return JSON.parse(fs.readFileSync(STATUSLINE_CACHE, "utf-8"));
+			return JSON.parse(fs.readFileSync(STATUSLINE_CACHE, "utf8"));
 		}
 	} catch {
 		/* ignore */
@@ -726,7 +729,7 @@ function loadCache(): StatuslineCache {
 function saveCache(cache: StatuslineCache): void {
 	try {
 		fs.mkdirSync(path.dirname(STATUSLINE_CACHE), { recursive: true });
-		fs.writeFileSync(STATUSLINE_CACHE, JSON.stringify(cache, null, 2), "utf-8");
+		fs.writeFileSync(STATUSLINE_CACHE, JSON.stringify(cache, null, 2), "utf8");
 	} catch {
 		/* ignore */
 	}
@@ -810,7 +813,7 @@ function main(): void {
 	// Read JSON from stdin
 	let inputData: StatusLineInput;
 	try {
-		inputData = JSON.parse(fs.readFileSync(0, "utf-8")) as StatusLineInput;
+		inputData = JSON.parse(fs.readFileSync(0, "utf8")) as StatusLineInput;
 	} catch {
 		inputData = {};
 	}
@@ -898,3 +901,5 @@ function main(): void {
 }
 
 main();
+
+

package/dist/templates/core/skills/codex/CLAUDE.md

@@ -0,0 +1,78 @@
+# Codex Skill
+
+Launch Codex CLI in a visible pane (tmux on Unix, Windows Terminal/window fallback on native Windows) and pass the prompt at process start.
+
+## Directory Structure
+
+```
+codex/
+├── CLAUDE.md       ← This file
+├── SKILL.md        ← Skill metadata (user-invocable)
+├── lib/
+│   └── codex-watcher.ts  ← Reusable watch/summarize library
+└── scripts/
+    ├── launch-codex.ts   ← Single entry point (launch + optional watch)
+    └── watch-codex.ts    ← Standalone watch mode
+```
+
+## Script: launch-codex.ts
+
+> Note: This file documents template source paths (`.aiwcli/_core/...`). During installation, settings command paths are normalized to runtime `.aiwcli/_core/...`.
+
+**Usage:**
+```bash
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_core/skills/codex/scripts/launch-codex.ts [--model <tier|id>] [--sandbox <sandbox-mode>] [--prompt <text>] [--no-yolo] [--no-watch] [--context <id>] plan
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_core/skills/codex/scripts/launch-codex.ts [--model <tier|id>] [--sandbox <sandbox-mode>] [--prompt <text>] [--no-yolo] [--no-watch] [--context <id>] --file <path>
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_core/skills/codex/scripts/launch-codex.ts [--model <tier|id>] [--sandbox <sandbox-mode>] [--prompt <text>] [--no-yolo] [--no-watch] [--context <id>] <inline text...>
+```
+
+**Args:**
+- `plan` — discover active plan via context system, build a bootstrap startup prompt that includes the plan filepath (Codex reads that file directly)
+- `--file <path>` — build a bootstrap startup prompt that includes the file path (Codex reads that file directly)
+- `<text...>` — join remaining args as inline prompt
+- `--model <alias|tier|id>` — Aliases: `spark` → `gpt-5.3-codex-spark`, `codex` → `gpt-5.4`, `gpt` → `gpt-5.4`. Tiers: `fast`/`standard`/`smart` (resolved via `resolveModelForProvider()`). Or a full model ID.
+- `--sandbox <mode>` — `read-only`, `workspace-write`, or `danger-full-access`. Default is `danger-full-access`.
+- `--prompt <text>` — append extra instructions. In `plan` and `--file` modes, these are embedded into a bootstrap temp file alongside the target path.
+- `--no-yolo` — Disable YOLO mode (`--dangerously-bypass-approvals-and-sandbox`).
+- `--no-watch` — Disable watch/summarize mode.
+
+**Plan discovery order:**
+1. `CLAUDE_SESSION_ID` env → `getContextBySessionId()` → `findLatestPlan(contextId)`
+2. Fallback: scan `_output/contexts/*/plans/*.md` by mtime
+
+**Dependencies:**
+- `runtime/aiw-cli.ts` — shells out to `aiw launch` for pane management (no direct tmux imports)
+- `runtime/cli-args.ts` — model/sandbox/yolo CLI arg generation
+- `context/*` — context lookup, formatting, plan discovery
+
+**Watch behavior (single entry point):**
+- Watch is enabled by default.
+- `launch-codex.ts` launches Codex, waits for completion (pane close or sentinel), and prints a summary.
+- Summary cascade:
+  1. Session-file summary (`summarizeViaSessionFile`): Codex CLI Spark primary, `fast` tier (Haiku) fallback
+  2. `codex exec resume <session_id>` summary (output file, then stdout/stderr parse fallback)
+  3. Transcript-line fallback
+  4. Static `Summary unavailable` message
+- Summary persistence:
+  - `persistSummary()` in `codex-watcher.ts` writes to `os.tmpdir()/codex-summary-<ts>-<id>.md`
+  - Called before stdout output — temp file survives even if background task capture fails
+  - Best-effort: logs warning on failure, returns null, stdout output still proceeds
+  - File path printed as `[summary_file:<path>]` marker for automated retrieval
+
+**Design decisions:**
+- Prompt is delivered at launch time (no tmux buffer paste/capture workflow)
+- Pane backend detection delegated to `aiw launch` (tmux in-session only → inline exec fallback)
+- `core` source only — runtime execution resolves to `.aiwcli/_core`
+- Watch path is best-effort and does not change launch success semantics
+
+## Library: lib/codex-watcher.ts
+
+Reusable side-effect-free watch/summarize functions used by launch flow:
+- `waitForPaneClose(target, timeoutMs?)` where `target` can be tmux pane id or `{ backend, paneId, sentinelPath }`
+- `summarizeViaSessionFile(sessionFile)`
+- `summarizeViaResume(sessionId)`
+- `summarizeFromSessionFileFallback(sessionFile)`
+- `collectTranscriptLines(sessionFile)`
+
+Constants and helper utilities are exported for reuse and testing (`POLL_INTERVAL_MS`, `SUMMARY_UNAVAILABLE_MESSAGE`, `normalizeText`, `looksLikeBadSummary`, etc.).
+

package/dist/templates/{_shared → core}/skills/codex/SKILL.md

@@ -9,19 +9,31 @@ The script blocks until Codex exits and prints a session summary. Run with Bash
 ## Command
 
 ```
-bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts [flags] <mode>
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_core/skills/codex/scripts/launch-codex.ts [flags] <mode>
 ```
 
 **Modes:** `plan` | `--file <path>` | `<inline text...>`
 
+`plan` and `--file` modes pass a filepath-first bootstrap prompt so Codex reads the file from disk instead of relying on a pasted full document.
+
 **Flags:**
 - `--context <id>` — Project orientation for the sub-agent. Pass when implementing a plan so Codex understands the project structure.
-- `--prompt <text>` — Scope the agent's work. Direct each instance to a specific plan section or task.
-- `--model <name>` — Aliases: `spark`, `codex`, `gpt`. Tiers: `fast`, `standard`, `smart`. Or any full model ID.
+- `--prompt <text>` — Add extra instructions. In `plan`/`--file` mode, this is embedded into the bootstrap temp file with the target path.
+- `--model <name>` — Aliases: `spark`, `codex`, `gpt`. Tiers: `fast`, `standard`, `smart`. Or unknown full model ID.
 - `--sandbox <mode>` — `read-only`, `workspace-write`, `danger-full-access`.
 - `--no-yolo` — Disable YOLO mode (on by default).
 - `--no-watch` — Fire-and-forget: exit immediately after launch, skip waiting for summary.
 
+## Retrieving Results
+
+The script prints a summary to stdout and writes it to a temp file.
+
+**Primary:** Check TaskOutput for the background task — the summary and file path are inline.
+
+**Fallback (if TaskOutput is empty):** Look for the `[summary_file:<path>]` line in the output. If found, read that file path directly. The temp file persists independently of Claude Code's background task capture.
+
+If neither is available, check `_output/hook-log.jsonl` for `codex-capture` or `codex-skill` entries for diagnostics.
+
 ## Delegation Patterns
 
 ### One-shot
@@ -29,24 +41,14 @@ bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-cod
 For small or tightly coupled plans. One sub-agent implements the whole plan.
 
 ```bash
-bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts --context <ctx-id> plan
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_core/skills/codex/scripts/launch-codex.ts --context <ctx-id> plan
 ```
 
 Run with `run_in_background: true`. Wait for the summary. Review the changes.
 
 ### Parallel
 
-For plans with independent sections. Each sub-agent owns one section, scoped by `--prompt`.
-
-```bash
-# Sub-agent A — section 1
-bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts \
-  --context <ctx-id> --prompt "Implement section 1: Extract watch logic into lib/codex-watcher.ts" plan
-
-# Sub-agent B — section 3
-bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts \
-  --context <ctx-id> --prompt "Implement section 3: Update launch-codex.ts arg parsing" plan
-```
+For plans with independent sections, create small section-brief files and launch one sub-agent per brief with `--file`.
 
 Run each with `run_in_background: true`. Summaries arrive as separate background task notifications. When all complete, review for conflicts between agents, then verify with tests or import checks.
 
@@ -55,10 +57,10 @@ Run each with `run_in_background: true`. Summaries arrive as separate background
 For tasks outside a plan. Pass inline text or a file path.
 
 ```bash
-bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts \
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_core/skills/codex/scripts/launch-codex.ts \
   "Fix the failing test in auth.ts"
 
-bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts \
+bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_core/skills/codex/scripts/launch-codex.ts \
   --file path/to/task-description.md
 ```
 
@@ -67,5 +69,6 @@ bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-cod
 - **Delegate implementation.** If the work involves writing code and Codex can handle it, send it to Codex.
 - **Split independent sections** into parallel sub-agents for faster execution.
 - **Pass `--context`** when implementing a plan — Codex needs project orientation to make good decisions.
-- **Scope with `--prompt`** when running parallel agents — each sub-agent performs better when it knows exactly which section it owns.
+- **Scope parallel agents with separate `--file` briefs** so each sub-agent has an explicit task boundary.
 - **Review results** when summaries arrive. Check for merge conflicts between parallel agents, then verify with `tsc --noEmit`, tests, or manual inspection.
+