@nghyane/arcane 0.1.7 → 0.1.10

package/CHANGELOG.md

@@ -1,3 +1,9 @@
 # Changelog
 
 ## [Unreleased]
+
+## [0.1.8] - 2026-02-22
+
+### Changed
+
+- Read VERSION from own package.json instead of shared utils package

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@nghyane/arcane",
-	"version": "0.1.7",
+	"version": "0.1.10",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/nghyane/arcane",
 	"author": "Can Bölük",
@@ -44,12 +44,12 @@
 	},
 	"dependencies": {
 		"@mozilla/readability": "0.6.0",
-		"@nghyane/arcane-stats": "^0.1.7",
-		"@nghyane/arcane-agent": "^0.1.7",
-		"@nghyane/arcane-codemode": "^0.1.7",
-		"@nghyane/arcane-ai": "^0.1.7",
+		"@nghyane/arcane-stats": "^0.1.8",
+		"@nghyane/arcane-agent": "^0.1.8",
+		"@nghyane/arcane-codemode": "^0.1.9",
+		"@nghyane/arcane-ai": "^0.1.8",
 		"@nghyane/arcane-natives": "^0.1.7",
-		"@nghyane/arcane-tui": "^0.1.7",
+		"@nghyane/arcane-tui": "^0.1.8",
 		"@nghyane/arcane-utils": "^0.1.6",
 		"@sinclair/typebox": "^0.34.48",
 		"@xterm/headless": "^6.0.0",

package/src/cli/update-cli.ts

@@ -8,9 +8,10 @@ import { execSync, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import { pipeline } from "node:stream/promises";
 import { isEnoent } from "@nghyane/arcane-utils";
-import { APP_NAME, VERSION } from "@nghyane/arcane-utils/dirs";
+import { APP_NAME } from "@nghyane/arcane-utils/dirs";
 import chalk from "chalk";
 import { theme } from "../modes/theme/theme";
+import { VERSION } from "../version";
 
 /**
  * Detect if we're running as a Bun compiled binary.

package/src/cli.ts

@@ -4,7 +4,8 @@
  * lightweight CLI runner from pi-utils.
  */
 import { type CommandEntry, run } from "@nghyane/arcane-utils/cli";
-import { APP_NAME, VERSION } from "@nghyane/arcane-utils/dirs";
+import { APP_NAME } from "@nghyane/arcane-utils/dirs";
+import { VERSION } from "./version";
 
 // Detect known Bun errata that cause TUI crashes (e.g. Bun.stringWidth mishandling OSC sequences).
 if (Bun.stringWidth("\x1b[0m\x1b]8;;\x07") !== 0) {

package/src/config/settings-schema.ts

@@ -548,16 +548,6 @@ export const SETTINGS_SCHEMA = {
 			submenu: true,
 		},
 	},
-	"task.maxRecursionDepth": {
-		type: "number",
-		default: 2,
-		ui: {
-			tab: "tools",
-			label: "Task max recursion depth",
-			description: "How many levels deep subagents can spawn their own subagents",
-			submenu: true,
-		},
-	},
 	"task.disabledAgents": {
 		type: "array",
 		default: [] as string[],

package/src/debug/system-info.ts

@@ -2,7 +2,8 @@
  * System information collection for debug reports.
  */
 import * as os from "node:os";
-import { getProjectDir, VERSION } from "@nghyane/arcane-utils/dirs";
+import { getProjectDir } from "@nghyane/arcane-utils/dirs";
+import { VERSION } from "../version";
 
 export interface SystemInfo {
 	os: string;

package/src/discovery/helpers.ts

@@ -232,12 +232,7 @@ export function parseAgentFields(frontmatter: Record<string, unknown>): ParsedAg
 		return null;
 	}
 
-	let tools = parseArrayOrCSV(frontmatter.tools);
-
-	// Subagents with output schema need submit_result to return structured data
-	if (tools && frontmatter.output && !tools.includes("submit_result")) {
-		tools = [...tools, "submit_result"];
-	}
+	const tools = parseArrayOrCSV(frontmatter.tools);
 
 	const model = parseModelList(frontmatter.model);
 	const thinkingLevel = parseThinkingLevel(frontmatter);

package/src/index.ts

@@ -7,7 +7,7 @@ export { StringEnum } from "@nghyane/arcane-ai";
 export { Container, Markdown, Spacer, Text } from "@nghyane/arcane-tui";
 // Logging
 export { logger } from "@nghyane/arcane-utils";
-export { getAgentDir, VERSION } from "@nghyane/arcane-utils/dirs";
+export { getAgentDir } from "@nghyane/arcane-utils/dirs";
 export { formatKeyHint, formatKeyHints } from "./config/keybindings";
 export { ModelRegistry } from "./config/model-registry";
 // Prompt templates
@@ -179,6 +179,7 @@ export {
 	loadSshTool,
 	PythonTool,
 	ReadTool,
+	type SubagentContext,
 	type ToolSession,
 	WriteTool,
 } from "./sdk";
@@ -273,3 +274,4 @@ export {
 	type WriteToolDetails,
 	type WriteToolInput,
 } from "./tools";
+export { VERSION } from "./version";

package/src/main.ts

@@ -12,7 +12,7 @@ import * as path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { type ImageContent, supportsXhigh } from "@nghyane/arcane-ai";
 import { $env, postmortem } from "@nghyane/arcane-utils";
-import { getProjectDir, setProjectDir, VERSION } from "@nghyane/arcane-utils/dirs";
+import { getProjectDir, setProjectDir } from "@nghyane/arcane-utils/dirs";
 import chalk from "chalk";
 import type { Args } from "./cli/args";
 import { processFileArguments } from "./cli/file-processor";
@@ -33,6 +33,7 @@ import { type SessionInfo, SessionManager } from "./session/session-manager";
 import { resolvePromptInput } from "./system-prompt";
 import { getChangelogPath, getNewEntries, parseChangelog } from "./utils/changelog";
 import { printTimings, time } from "./utils/timings";
+import { VERSION } from "./version";
 
 /** Conditional startup debug prints (stderr) when ARCANE_DEBUG_STARTUP is set */
 const debugStartup = $env.ARCANE_DEBUG_STARTUP

package/src/memories/index.ts

@@ -121,12 +121,12 @@ export function startMemoryStartupTask(options: {
 	settings: Settings;
 	modelRegistry: ModelRegistry;
 	agentDir: string;
-	taskDepth: number;
+	isSubagent: boolean;
 }): void {
-	const { session, settings, modelRegistry, agentDir, taskDepth } = options;
+	const { session, settings, modelRegistry, agentDir, isSubagent } = options;
 	const cfg = loadMemoryConfig(settings);
 	if (!cfg.enabled) return;
-	if (taskDepth > 0) return;
+	if (isSubagent) return;
 	if (!session.sessionManager.getSessionFile()) return;
 
 	const dbPath = getAgentDbPath(agentDir);

package/src/modes/components/settings-defs.ts

@@ -85,14 +85,6 @@ const OPTION_PROVIDERS: Partial<Record<SettingPath, OptionProvider>> = {
 		{ value: "32", label: "32 tasks" },
 		{ value: "64", label: "64 tasks" },
 	],
-	// Task max recursion depth
-	"task.maxRecursionDepth": [
-		{ value: "-1", label: "Unlimited" },
-		{ value: "0", label: "None" },
-		{ value: "1", label: "Single" },
-		{ value: "2", label: "Double" },
-		{ value: "3", label: "Triple" },
-	],
 	// Todo max reminders
 	"todo.reminders.max": [
 		{ value: "1", label: "1 reminder" },

package/src/patch/applicator.ts

@@ -890,10 +890,11 @@ function applyCharacterMatch(
 	const adjustedNewText = adjustIndentation(normalizedOldText, matchOutcome.match.actualText, newText);
 
 	const warnings: string[] = [];
-	if (matchOutcome.dominantFuzzy && matchOutcome.match) {
+	if (matchOutcome.match && matchOutcome.match.confidence < 0.97) {
 		const similarity = Math.round(matchOutcome.match.confidence * 100);
+		const qualifier = matchOutcome.dominantFuzzy ? "Dominant fuzzy" : "Fuzzy";
 		warnings.push(
-			`Dominant fuzzy match selected in ${path} near line ${matchOutcome.match.startLine} (${similarity}% similar).`,
+			`${qualifier} match applied in ${path} near line ${matchOutcome.match.startLine} (${similarity}% similar).`,
 		);
 	}
 
@@ -1152,9 +1153,16 @@ function computeReplacements(
 
 		const found = searchResult.index;
 
-		if (searchResult.strategy === "fuzzy-dominant") {
+		if (
+			searchResult.strategy === "prefix" ||
+			searchResult.strategy === "substring" ||
+			searchResult.strategy === "fuzzy" ||
+			searchResult.strategy === "fuzzy-dominant"
+		) {
 			const similarity = Math.round(searchResult.confidence * 100);
-			warnings.push(`Dominant fuzzy match selected in ${path} near line ${found + 1} (${similarity}% similar).`);
+			warnings.push(
+				`Non-exact match applied in ${path} near line ${found + 1} (${similarity}% similar, strategy: ${searchResult.strategy}).`,
+			);
 		}
 
 		// Reject if match is ambiguous (prefix/substring matching found multiple matches)

package/src/prompts/agents/task.md

@@ -8,7 +8,7 @@ Finish only the assigned work and return the minimum useful result.
 - Avoid full-file reads unless necessary.
 - Prefer edits to existing files over creating new ones.
 - NEVER create documentation files (*.md) unless explicitly requested.
-- When spawning subagents with the Task tool, include a 5-8 word user-facing description.
+- When done, write a concise summary of what you did as your final response. This is your output.
 - Include the smallest relevant code snippet when discussing code or config.
 - Follow the main agent's instructions.
 </directives>

package/src/prompts/system/subagent-system-prompt.md

@@ -11,20 +11,8 @@ For additional parent conversation context, check {{contextFile}} (`tail -100` o
 {{/if}}
 
 <critical>
-- MUST call `submit_result` exactly once when finished. No JSON in text. No plain-text summary. Pass result via `data` parameter.
-- Todo tracking is parent-owned. Do not create or maintain a separate todo list in this subagent.
-{{#if outputSchema}}
-- If cannot complete, call `submit_result` with `status="aborted"` and error message. Do not provide success result or pretend completion.
-{{else}}
-- If cannot complete, call `submit_result` with `status="aborted"` and error message. Do not claim success.
-{{/if}}
-{{#if outputSchema}}
-- `data` parameter MUST be valid JSON matching TypeScript interface:
-```ts
-{{jtdToTypeScript outputSchema}}
-```
-{{/if}}
-- If cannot complete, call `submit_result` exactly once with result indicating failure/abort status (use failure/notes field if available). Do not claim success.
+- When done, stop. Your final text response is your output — the parent receives it as the task result.
+- If cannot complete, report failure clearly in your final response. Do not claim success.
 - Do NOT abort due to uncertainty or missing info that can be obtained via tools or repo context. Use `find`/`grep`/`read` first, then proceed with reasonable defaults if multiple options are acceptable.
 - Aborting is only acceptable when truly blocked after exhausting tools and reasonable attempts. If you abort, include what you tried and the exact blocker in the result.
 - Keep going until request is fully fulfilled. This matters.

package/src/prompts/system/system-prompt.md

@@ -115,8 +115,17 @@ The question is not "does this work?" but "under what conditions? What happens o
 - Skip entirely for single-step or trivial requests.
 
 {{#has tools "task"}}
-### Parallel Execution
-Use the Task tool when work genuinely forks into independent streams:
+### Delegation
+You have subagents. Pick the right one:
+- "I need to think through architecture/plan" → **Oracle**
+- "I need to understand unfamiliar code" → **Explore / Librarian**
+- "I know what to do, need parallel execution" → **Task tool**
+
+Workflow for complex work: Oracle (plan) → Explore (validate scope) → Task (execute).
+
+Task tool is a fire-and-forget executor — a productive junior engineer who cannot ask follow-ups once started. Prompt it with detailed instructions, enumerate deliverables, include constraints and verification steps.
+
+Use Task tool when work genuinely forks into independent streams:
 - Editing 4+ files with no dependencies between edits
 - Investigating 2+ independent subsystems
 - Work that decomposes into pieces not needing each other's results
@@ -231,18 +240,7 @@ Current date: {{date}}
 
 {{#has tools "task"}}
 <parallel_reflex>
-When work forks, you fork.
-
-Notice the sequential habit:
-- Comfort in doing one thing at a time
-- Illusion that order = correctness
-- Assumption that B depends on A
-  **Use Task tool when:**
-- Editing 4+ files with no dependencies between edits
-- Investigating 2+ independent subsystems
-- Work decomposes into pieces not needing each other's results
-
-Sequential work requires justification. If you cannot articulate why B depends on A → parallelize.
+When work forks, you fork. Sequential work requires justification — if you cannot articulate why B depends on A, parallelize via Task tool.
 </parallel_reflex>
 {{/has}}
 

package/src/prompts/tools/task.md

@@ -1,18 +1,12 @@
 # Task
 
-Launch subagents to execute parallel, well-scoped tasks.
+Launch a fire-and-forget subagent to execute well-scoped work. Think of it as a productive junior engineer who cannot ask follow-ups once started.
+- **Use for**: Multi-file implementations, cross-layer refactors, mass migrations, boilerplate generation
+- **Don't use for**: Exploratory work, architectural decisions, single-file edits, reading a file
 
-## What subagents inherit automatically
-Subagents receive the **full system prompt**, including AGENTS.md, context files, and skills. Do NOT repeat project rules, coding conventions, or style guidelines in `context` — they already have them.
+## Subagent capabilities
 
-## What subagents do NOT have
-Subagents have no access to your conversation history. They don't know:
-- Decisions you made but didn't write down
-- Which approach you chose among alternatives
-- What you learned from reading files during this session
-- Requirements the user stated only in conversation
-
-Subagents CAN grep the parent conversation file for supplementary details.
+Subagents receive the **full system prompt**, including AGENTS.md, context files, and skills. They have no access to your conversation history — they don't know decisions you made, approaches you chose, or requirements stated only in conversation. Subagents CAN grep the parent conversation file for supplementary details.
 ---
 
 ## Parameters
@@ -22,35 +16,18 @@ Subagents CAN grep the parent conversation file for supplementary details.
 Shared background prepended verbatim to every task `assignment`. Use only for session-specific information subagents lack.
 
 <critical>
-Do NOT include project rules, coding conventions, or style guidelines — subagents already have AGENTS.md and context files in their system prompt. Repeating them wastes tokens and inflates context. Restating any rule from AGENTS.md in `context` is a bug — treat it like a lint error.
+Do NOT include project rules, coding conventions, or style guidelines — subagents already have AGENTS.md. Restating any rule from AGENTS.md in `context` is a bug.
 </critical>
-**Before writing each line of context, ask:** "Would this sentence be true for ANY task in this repo, or only for THIS specific batch?" If it applies to any task → it's a project rule → the subagent already has it → delete the line.
-
-WRONG — restating project rules the subagent already has:
-```
-## Constraints
-- Use X import style, not Y (per AGENTS.md)
-- Use Z for private fields per AGENTS.md
-- Run the formatter after changes
-- Follow the logging convention
-```
-Every line above restates a project convention. The subagent reads AGENTS.md. Delete them all.
-
-RIGHT — only session-specific decisions the subagent cannot infer from project files:
-```
-## Constraints
-- We decided to use approach A over B (session decision)
-- The migration target type is `Foo` from `bar` package (looked up this session)
-```
+**Before writing each line of context, ask:** "Would this sentence be true for ANY task in this repo, or only for THIS specific batch?" If it applies to any task → the subagent already has it → delete the line.
 
 Use template; omit non-applicable sections:
 
 ````
 ## Goal
-One sentence: batch accomplishes together.
+One sentence: what the batch accomplishes together.
 
 ## Non-goals
-Explicitly exclude tempting scope — what tasks must not touch/attempt.
+Explicitly exclude tempting scope — what tasks must not touch.
 
 ## Constraints
 - Task-specific MUST / MUST NOT rules not already in AGENTS.md
@@ -58,49 +35,43 @@ Explicitly exclude tempting scope — what tasks must not touch/attempt.
 
 ## Reference Files
 - `path/to/file.ext` — pattern demo
-- `path/to/other.ext` — reuse or avoid
 
 ## API Contract (if tasks produce/consume shared interface)
 ```language
-// Exact type definitions, function signatures, interface shapes
+// Exact type definitions, function signatures
 ```
 
 ## Acceptance (global)
 - Definition of "done" for batch
-- Note: build/test/lint verification happens AFTER all tasks complete — not inside tasks (see below)
+- For parallel tasks, build/test/lint verification happens AFTER all tasks complete — not inside tasks. Single tasks may self-verify.
 ````
-**Belongs in `context`**: task-specific goal, non-goals, session decisions, reference paths, shared type definitions, API contracts, global acceptance commands — anything 2+ tasks need that isn't already in AGENTS.md.
-**Rule of thumb:** if repeat in 2+ tasks, belongs in `context`.
-**Does NOT belong in `context`**: project rules already in AGENTS.md/context files, per-task file lists, one-off requirements (go in `assignment`), and strict response contracts that only apply to one task.
+**Belongs in `context`**: session decisions, reference paths, shared type definitions, API contracts, global acceptance — anything 2+ tasks need that isn't in AGENTS.md.
+**Does NOT belong**: project rules from AGENTS.md, per-task file lists, one-off requirements (go in `assignment`).
 
 ### `tasks` (required)
 
-Array tasks execute in parallel.
+Array of tasks that execute in parallel.
 
 |Field|Required|Purpose|
 |---|---|---|
-|`id`|✓|CamelCase identifier, max 32 chars|
-|`description`|✓|Short one-liner for UI display only — not seen by subagent|
-|`assignment`|✓|Complete per-task instructions. See [Writing an assignment](#writing-an-assignment).|
-|`skills`||Skill names preload. Use only when changes correctness — don’t spam every task.|
-
-Outputs are free-form text/JSON from each subtask. If you need strict structure, define it clearly inside each `assignment` and validate at the caller.
+|`id`|yes|CamelCase identifier, max 32 chars|
+|`description`|yes|Short one-liner for UI display only — not seen by subagent|
+|`assignment`|yes|Complete per-task instructions (see below)|
+|`skills`||Skill names to preload. Use only when it changes correctness.|
 ---
 
 ## Writing an assignment
 
-<critical>## Task scope
-
-`assignment` must contain enough info for agent to act **without asking a clarifying question**.
-**Minimum bar:** assignment under ~8 lines or missing acceptance criteria = too vague. One-liners guaranteed failure.
+<critical>
+`assignment` must contain enough info for the subagent to act **without asking a clarifying question**. One-liners guarantee failure.
 
-Use structure every assignment:
+Use this structure:
 
 ```
 ## Target
 - Files: exact path(s)
 - Symbols/entrypoints: specific functions, types, exports
-- Non-goals: what task must NOT touch (prevents scope creep)
+- Non-goals: what task must NOT touch
 
 ## Change
 - Step-by-step: add/remove/rename/restructure
@@ -108,168 +79,68 @@ Use structure every assignment:
 
 ## Edge Cases / Don't Break
 - Tricky case 1: ...
-- Tricky case 2: ...
-- Existing behavior must survive: ...
+- Existing behavior that must survive: ...
 
 ## Acceptance (task-local)
 - Expected behavior or observable result
-- DO NOT include project-wide build/test/lint commands (see below)
+- For parallel tasks: DO NOT include project-wide build/test/lint commands
 ```
 
-`context` carries shared background. `assignment` carries only delta: file-specific instructions, local edge cases, per-task acceptance checks. Never duplicate shared constraints across assignments.
-
-### Anti-patterns (ban these)
-**Vague assignments** — agent guesses wrong or stalls:
-- "Refactor this to be cleaner."
-- "Migrate to N-API."
-- "Fix the bug in streaming."
-- "Update all constructors in `src/**/*.ts`."
-**Vague context** — forces agent invent conventions:
-- "Use existing patterns."
-- "Follow conventions."
-- "No WASM."
-**Redundant context** — wastes tokens repeating what subagents already have:
-- Restating AGENTS.md rules (coding style, import conventions, formatting commands, logger usage, etc.)
-- Repeating project constraints from context files
-- Listing tool/framework preferences already documented in the repo
-
-If a constraint appears in AGENTS.md, it MUST NOT appear in `context`. The subagent has the full system prompt.
-
-If tempted to write above, expand using templates.
-**Test/lint commands in parallel tasks** — edit wars:
-Parallel agents share working tree. If two agents run `bun check` or `bun test` concurrently, they see each other's half-finished edits, "fix" phantom errors, loop. **Never tell parallel tasks run project-wide build/test/lint commands.** Each task edits, stops. Caller verifies after all tasks complete.
-**If you can't specify scope yet**, create **Discovery task** first: enumerate files, find callsites, list candidates. Then fan out with explicit paths.
+`context` carries shared background. `assignment` carries only delta: file-specific instructions, local edge cases, per-task acceptance.
 
 ### Delegate intent, not keystrokes
 
-Your role as tech lead: set direction, define boundaries, call out pitfalls — then get out of way. Don’t read every file, decide every edit, dictate line-by-line. That makes you bottleneck; agent typist.
-**Be specific about:** constraints, naming conventions, API contracts, "don’t break" items, acceptance criteria.
-**Delegate:** code reading, approach selection, exact edit locations, implementation details. Agent has tools, can reason about code.
-
-Micromanaging (you think, agent types):
-```
-assignment: "In src/api/handler.ts, line 47, change `throw err` to `throw new ApiError(err.message, 500)`.
-On line 63, wrap fetch call try/catch return 502 on failure.
-On line 89, add null check before accessing resp.body..."
-```
-
-Delegating (agent thinks within constraints):
-```
-assignment: "## Target\n- Files: src/api/handler.ts\n\n## Change\nImprove error handling: replace raw throws
-with typed ApiError instances, add try/catch around external calls, guard against null responses.\n\n
-## Edge Cases / Don't Break\n- Existing error codes in tests must still match\n
-- Don't change public function signatures"
-```
-
-First style wastes your time, brittle if code shifts. Second gives agent room to do work.
+Your role is tech lead: set direction, define boundaries, call out pitfalls — then get out of the way. Don't dictate line-by-line edits.
+**Be specific about:** constraints, naming, API contracts, "don't break" items, acceptance criteria.
+**Delegate:** code reading, approach selection, exact edit locations, implementation details.
 </critical>
 
-## Example
-
-<example type="bad" label="Duplicated context inflates tokens">
-<tasks>
-  <task name="Grep">
-    <description>Port grep module from WASM to N-API...</description>
-    <assignment>Port grep module from WASM to N-API... (same blob repeated)</assignment>
-</task>
-</tasks>
-</example>
-
-<example type="good" label="Shared rules in context, only deltas in assignment">
-<context>
-## Goal
-Port WASM modules to N-API, matching existing arcane-natives conventions.
-
-## Non-goals
-Do not touch TS bindings or downstream consumers — separate phase.
-
-## Constraints
-- MUST use `#[napi]` attribute macro on all exports
-- MUST return `napi::Result<T>` for fallible ops; never panic
-- MUST use `spawn_blocking` for filesystem I/O or >1ms work
-...
-
-## Acceptance (global)
-- Caller verifies after all tasks: `cargo test -p arcane-natives` and `cargo build -p arcane-natives` with no warnings
-- Individual tasks must NOT run these commands themselves
-</context>
-
-<tasks>
-  <task name="PortGrep">
-    <description>Port grep module to N-API</description>
-    <assignment>
-## Target
-- Files: `src/grep.rs`, `src/lib.rs` (registration only)
-- Symbols: search, search_multi, compile_pattern
-
-## Change
-- Implement three N-API exports in grep.rs:
-  - `search(pattern: JsString, path: JsString, env: Env) -> napi::Result<Vec<Match>>`
-...
-
-## Acceptance (task-local)
-- Three functions exported with correct signatures (caller verifies build after all tasks)
-</assignment>
-</task>
-
-  <task name="PortHighlight">
-    <description>Port highlight module to N-API</description>
-    <assignment>
-## Target
-- Files: `src/highlight.rs`, `src/lib.rs` (registration only)
-...
-</assignment>
-</task>
-</tasks>
-</example>
+### Anti-patterns
+**Vague assignments** — subagent guesses wrong or stalls:
+- "Refactor this to be cleaner."
+- "Fix the bug in streaming."
+- "Update all constructors in `src/**/*.ts`."
+**Test/lint in parallel tasks** — edit wars:
+Parallel agents share working tree. If two agents run `bun check` concurrently, they see each other's half-finished edits, "fix" phantom errors, loop. **Never tell parallel tasks to run project-wide build/test/lint.** Each task edits, stops. Caller verifies after all complete. Single-task launches may include verification.
+**If you can't specify scope yet**, create a **Discovery task** first: enumerate files, find callsites, list candidates. Then fan out with explicit paths.
 ---
 
 ## Task scope
 
-Each task small, well-defined scope — **at most 3–5 files**.
-**Signs task too broad:**
-- File paths use globs (`src/**/*.ts`) instead of explicit names
-- Assignment says "update all" / "migrate everything" / "refactor across"
-- Scope covers entire package or directory tree
-**Fix:** enumerate files first (grep/glob discovery), then fan out one task per file or small cluster.
+Each task: small, well-defined — **at most 3-5 files**.
+**Signs task is too broad:** file paths use globs, assignment says "update all" / "migrate everything", scope covers entire package.
+**Fix:** enumerate files first (grep/glob), then fan out one task per file or small cluster.
 ---
 
 ## Parallelization
 **Test:** Can task B produce correct output without seeing task A's result?
 - **Yes** → parallelize
-- **No** → run sequentially (A completes, then launch B with A output in context)
+- **No** → sequential (A completes, then launch B with A's output in context)
 
 ### Must be sequential
 
 |First|Then|Reason|
 |---|---|---|
 |Define types/interfaces|Implement consumers|Consumers need contract|
-|Create API exports|Write bindings/callers|Callers need export names/signatures|
-|Scaffold structure|Implement bodies|Bodies need shape|
+|Create API exports|Write bindings/callers|Callers need signatures|
 |Core module|Dependent modules|Dependents import from core|
-|Schema/DB migration|Application logic|Logic depends on new schema shape|
 
 ### Safe to parallelize
 - Independent modules, no cross-imports
 - Tests for already-implemented code
 - Isolated file-scoped refactors
-- Documentation for stable APIs
-
-### Phased execution
 
-Layered work with dependencies:
-**Phase 1 — Foundation** (do yourself or single task): define interfaces, create scaffolds, establish API shape. Never fan out until contract known.
-**Phase 2 — Parallel implementation**: fan out tasks consuming same known interface. Include Phase 1 API contract in `context`.
+### Multi-phase pattern
+**Phase 1 — Sequential**: define shared contracts (types, interfaces, schemas).
+**Phase 2 — Parallel**: fan out tasks consuming same known interface.
 **Phase 3 — Integration** (do yourself): wire modules, fix mismatches, verify builds.
-**Phase 4 — Dependent layer**: fan out tasks consuming Phase 2 outputs.
 ---
 
 ## Pre-flight checklist
 
 Before calling tool, verify:
-- [ ] `context` includes only session-specific info not already in AGENTS.md/context files
-- [ ] Each `assignment` follows assignment template — not one-liner
-- [ ] Each `assignment` includes edge cases / "don’t break" items
-- [ ] Tasks truly parallel (no hidden dependencies)
-- [ ] Scope small, file paths explicit (no globs)
-- [ ] No task runs project-wide build/test/lint — you do after all tasks complete
+- [ ] `context` includes only session-specific info not already in AGENTS.md
+- [ ] Each assignment has Target, Change, Edge Cases, Acceptance sections
+- [ ] Assignments reference exact file paths (no globs)
+- [ ] Scope small, file paths explicit
+- [ ] Parallel tasks don't run project-wide build/test/lint — you do after all tasks complete (single tasks may self-verify)

package/src/prompts/tools/todo-write.md

@@ -18,11 +18,11 @@ Use proactively:
 	 - in_progress: working
 	 - completed: finished
 2. **Task Management**:
-   - Update status in real time
-   - Mark complete IMMEDIATELY after finishing (no batching)
-   - Keep exactly ONE task in_progress at a time
+   - Update status each turn
+   - Mark completed after each code execution finishes — do not defer to a later turn
+   - Multiple tasks may be in_progress simultaneously when working in parallel
    - Remove tasks no longer relevant
-   - Complete tasks in list order (do not mark later tasks completed while earlier tasks remain incomplete)
+   - Mark tasks completed as they finish, regardless of list order
 3. **Task Completion Requirements**:
    - ONLY mark completed when FULLY accomplished
    - On errors/blockers/inability to finish, keep in_progress