@drisp/cli 0.4.2 → 0.4.4

package/dist/{chunk-GE6PPB6Z.js → chunk-5VK2ZMVV.js}

@@ -1,4 +1,4 @@
-// src/infra/plugins/workflowSourceResolution.ts
+// src/infra/plugins/workflowResolver.ts
 import fs2 from "fs";
 import path2 from "path";
 
@@ -28,15 +28,6 @@ function resolvePluginManifestPath(repoDir) {
 function resolveLegacyPluginManifestPath(repoDir) {
   return path.join(repoDir, ".claude-plugin", "marketplace.json");
 }
-function resolveWorkflowManifestPath(repoDir) {
-  const preferredManifestPath = path.join(
-    repoDir,
-    ".athena-workflow",
-    "marketplace.json"
-  );
-  const legacyManifestPath = resolveLegacyPluginManifestPath(repoDir);
-  return fs.existsSync(preferredManifestPath) ? preferredManifestPath : legacyManifestPath;
-}
 function readManifest(manifestPath) {
   if (!fs.existsSync(manifestPath)) {
     throw new Error(`Marketplace manifest not found: ${manifestPath}`);
@@ -105,67 +96,6 @@ function resolvePluginDirFromManifest(pluginName, repoDir, manifestPath) {
   }
   return pluginDir;
 }
-function resolveWorkflowEntryPath(entry, manifest, repoDir) {
-  if (typeof entry.source !== "string") {
-    throw new Error(
-      `Workflow "${entry.name}" uses a remote source type which is not supported.`
-    );
-  }
-  let sourcePath = entry.source;
-  const { workflowRoot } = manifest.metadata ?? {};
-  if (workflowRoot && !path.isAbsolute(sourcePath) && !sourcePath.startsWith("./") && !sourcePath.startsWith("../")) {
-    sourcePath = path.join(workflowRoot, sourcePath);
-  }
-  const workflowPath = path.resolve(repoDir, sourcePath);
-  if (!workflowPath.startsWith(repoDir + path.sep) && workflowPath !== repoDir) {
-    throw new Error(
-      `Workflow "${entry.name}" source resolves outside the marketplace repo: ${workflowPath}`
-    );
-  }
-  const resolvedWorkflowPath = preferCanonicalWorkflowPath(
-    repoDir,
-    workflowPath
-  );
-  if (!fs.existsSync(resolvedWorkflowPath)) {
-    throw new Error(`Workflow source not found: ${resolvedWorkflowPath}`);
-  }
-  return resolvedWorkflowPath;
-}
-function resolveWorkflowPathFromManifest(workflowName, repoDir, manifestPath) {
-  const manifest = readManifest(manifestPath);
-  const workflows = manifest.workflows ?? [];
-  const entry = workflows.find((w) => w.name === workflowName);
-  if (!entry) {
-    const available = workflows.map((w) => w.name).join(", ") || "(none)";
-    throw new Error(
-      `Workflow "${workflowName}" not found in marketplace manifest ${manifestPath}. Available workflows: ${available}`
-    );
-  }
-  return resolveWorkflowEntryPath(entry, manifest, repoDir);
-}
-function listWorkflowEntriesFromManifest(repoDir, manifestPath, source) {
-  const manifest = readManifest(manifestPath);
-  const workflows = manifest.workflows ?? [];
-  return workflows.filter(
-    (entry) => typeof entry.source === "string"
-  ).map((entry) => ({
-    name: entry.name,
-    description: entry.description,
-    version: entry.version,
-    workflowPath: resolveWorkflowEntryPath(entry, manifest, repoDir),
-    ref: source.kind === "remote" ? `${entry.name}@${source.owner}/${source.repo}` : void 0,
-    source
-  }));
-}
-function preferCanonicalWorkflowPath(repoDir, workflowPath) {
-  const relativePath = path.relative(repoDir, workflowPath);
-  const segments = relativePath.split(path.sep);
-  if (segments[0] !== ".workflows") {
-    return workflowPath;
-  }
-  const canonicalPath = path.join(repoDir, "workflows", ...segments.slice(1));
-  return fs.existsSync(canonicalPath) ? canonicalPath : workflowPath;
-}
 function isMarketplaceRef(entry) {
   return MARKETPLACE_REF_RE.test(entry);
 }
@@ -326,8 +256,86 @@ var WorkflowNotFoundError = class extends Error {
     this.searchedSources = searchedSources;
   }
 };
+var WorkflowVersionNotFoundError = class extends Error {
+  workflowName;
+  requestedVersion;
+  availableVersion;
+  sourceLabel;
+  constructor(workflowName, requestedVersion, availableVersion, sourceLabel) {
+    const availableText = availableVersion ? `found version ${availableVersion}` : "marketplace entry does not declare a version";
+    super(
+      `Workflow "${workflowName}" version ${requestedVersion} not found in ${sourceLabel} (${availableText}).`
+    );
+    this.name = "WorkflowVersionNotFoundError";
+    this.workflowName = workflowName;
+    this.requestedVersion = requestedVersion;
+    this.availableVersion = availableVersion;
+    this.sourceLabel = sourceLabel;
+  }
+};
 
-// src/infra/plugins/workflowSourceResolution.ts
+// src/infra/plugins/workflowResolver.ts
+function resolveWorkflowManifestPath(repoDir) {
+  const preferred = path2.join(repoDir, ".athena-workflow", "marketplace.json");
+  const legacy = path2.join(repoDir, ".claude-plugin", "marketplace.json");
+  return fs2.existsSync(preferred) ? preferred : legacy;
+}
+function preferCanonicalWorkflowPath(repoDir, workflowPath) {
+  const relativePath = path2.relative(repoDir, workflowPath);
+  const segments = relativePath.split(path2.sep);
+  if (segments[0] !== ".workflows") return workflowPath;
+  const canonical = path2.join(repoDir, "workflows", ...segments.slice(1));
+  return fs2.existsSync(canonical) ? canonical : workflowPath;
+}
+function resolveWorkflowEntryPath(entry, manifest, repoDir) {
+  if (typeof entry.source !== "string") {
+    throw new Error(
+      `Workflow "${entry.name}" uses a remote source type which is not supported.`
+    );
+  }
+  let sourcePath = entry.source;
+  const { workflowRoot } = manifest.metadata ?? {};
+  if (workflowRoot && !path2.isAbsolute(sourcePath) && !sourcePath.startsWith("./") && !sourcePath.startsWith("../")) {
+    sourcePath = path2.join(workflowRoot, sourcePath);
+  }
+  const workflowPath = path2.resolve(repoDir, sourcePath);
+  if (!workflowPath.startsWith(repoDir + path2.sep) && workflowPath !== repoDir) {
+    throw new Error(
+      `Workflow "${entry.name}" source resolves outside the marketplace repo: ${workflowPath}`
+    );
+  }
+  const resolved = preferCanonicalWorkflowPath(repoDir, workflowPath);
+  if (!fs2.existsSync(resolved)) {
+    throw new Error(`Workflow source not found: ${resolved}`);
+  }
+  return resolved;
+}
+function resolveWorkflowPathFromManifest(workflowName, repoDir, manifestPath) {
+  const manifest = readManifest(manifestPath);
+  const workflows = manifest.workflows ?? [];
+  const entry = workflows.find((w) => w.name === workflowName);
+  if (!entry) {
+    const available = workflows.map((w) => w.name).join(", ") || "(none)";
+    throw new Error(
+      `Workflow "${workflowName}" not found in marketplace manifest ${manifestPath}. Available workflows: ${available}`
+    );
+  }
+  return resolveWorkflowEntryPath(entry, manifest, repoDir);
+}
+function listWorkflowEntriesFromManifest(repoDir, manifestPath, source) {
+  const manifest = readManifest(manifestPath);
+  const workflows = manifest.workflows ?? [];
+  return workflows.filter(
+    (entry) => typeof entry.source === "string"
+  ).map((entry) => ({
+    name: entry.name,
+    description: entry.description,
+    version: entry.version,
+    workflowPath: resolveWorkflowEntryPath(entry, manifest, repoDir),
+    ref: source.kind === "remote" ? `${entry.name}@${source.owner}/${source.repo}` : void 0,
+    source
+  }));
+}
 function findMarketplaceRepoDir(startPath) {
   let currentDir = path2.resolve(startPath);
   for (; ; ) {
@@ -335,9 +343,7 @@ function findMarketplaceRepoDir(startPath) {
       return currentDir;
     }
     const parentDir = path2.dirname(currentDir);
-    if (parentDir === currentDir) {
-      return void 0;
-    }
+    if (parentDir === currentDir) return void 0;
     currentDir = parentDir;
   }
 }
@@ -359,11 +365,7 @@ function resolveWorkflowMarketplaceSource(source) {
       `Local marketplace not found from source: ${trimmed}. Expected a marketplace repo root or a path inside one.`
     );
   }
-  return {
-    kind: "local",
-    path: resolvedPath,
-    repoDir
-  };
+  return { kind: "local", path: resolvedPath, repoDir };
 }
 function listMarketplaceWorkflows(owner, repo) {
   requireGitForMarketplace("workflows");
@@ -391,47 +393,11 @@ function resolveMarketplaceWorkflow(ref) {
     resolveWorkflowManifestPath(repoDir)
   );
 }
-var WorkflowVersionNotFoundError = class extends Error {
-  workflowName;
-  requestedVersion;
-  availableVersion;
-  sourceLabel;
-  constructor(workflowName, requestedVersion, availableVersion, sourceLabel) {
-    const availableText = availableVersion ? `found version ${availableVersion}` : "marketplace entry does not declare a version";
-    super(
-      `Workflow "${workflowName}" version ${requestedVersion} not found in ${sourceLabel} (${availableText}).`
-    );
-    this.name = "WorkflowVersionNotFoundError";
-    this.workflowName = workflowName;
-    this.requestedVersion = requestedVersion;
-    this.availableVersion = availableVersion;
-    this.sourceLabel = sourceLabel;
-  }
-};
-function parseBareWorkflowName(source) {
-  const atIdx = source.indexOf("@");
-  if (atIdx <= 0 || atIdx === source.length - 1) {
-    return { bareName: source, pinnedVersion: void 0 };
-  }
-  const suffix = source.slice(atIdx + 1);
-  if (suffix.includes("/")) {
-    return { bareName: source, pinnedVersion: void 0 };
-  }
-  return {
-    bareName: source.slice(0, atIdx),
-    pinnedVersion: suffix
-  };
-}
 function gatherMarketplaceWorkflowSources(source) {
   const trimmed = source.trim();
   const resolvedPath = path2.resolve(trimmed);
   if (fs2.existsSync(resolvedPath) && fs2.statSync(resolvedPath).isFile()) {
-    return [
-      {
-        kind: "filesystem",
-        workflowPath: fs2.realpathSync(resolvedPath)
-      }
-    ];
+    return [{ kind: "filesystem", workflowPath: fs2.realpathSync(resolvedPath) }];
   }
   if (!fs2.existsSync(resolvedPath) && isMarketplaceSlug(trimmed)) {
     const slashIdx = trimmed.indexOf("/");
@@ -477,6 +443,17 @@ function gatherMarketplaceWorkflowSources(source) {
     workflowPath: entry.workflowPath
   }));
 }
+function parseBareWorkflowName(source) {
+  const atIdx = source.indexOf("@");
+  if (atIdx <= 0 || atIdx === source.length - 1) {
+    return { bareName: source, pinnedVersion: void 0 };
+  }
+  const suffix = source.slice(atIdx + 1);
+  if (suffix.includes("/")) {
+    return { bareName: source, pinnedVersion: void 0 };
+  }
+  return { bareName: source.slice(0, atIdx), pinnedVersion: suffix };
+}
 function resolvedSourceLabel(s) {
   if (s.kind === "marketplace-remote") return `marketplace ${s.slug}`;
   if (s.kind === "marketplace-local") return `local marketplace ${s.repoDir}`;
@@ -1570,7 +1547,7 @@ import fs10 from "fs";
 import path8 from "path";
 
 // src/core/workflows/stateMachine.md
-var stateMachine_default = "# Stateless Session Protocol\n\nYou operate in stateless sessions managed by a workflow runner. Each session is a fresh process with no memory of prior sessions. The **tracker file** is your only continuity \u2014 it's how you talk to your future self.\n\n## Execution Model\n\nThe runner spawns `claude -p` sessions in a loop:\n\n- **Session 1**: You receive the user's original request.\n- **Sessions 2+**: You receive a continuation prompt directing you to read the tracker.\n- **Between sessions**: The runner inspects the tracker for terminal markers. If found, or if the max iteration cap is reached, the loop ends. The tracker is preserved for resume, audit, and debugging.\n\n### Terminal Markers\n\nBy default, workflows use these tracker markers:\n\n- `<!-- WORKFLOW_COMPLETE -->`\n- `<!-- WORKFLOW_BLOCKED -->`\n- `<!-- WORKFLOW_BLOCKED: reason -->`\n\nWorkflows may override the default marker strings via configuration. Use the markers configured for the current workflow.\n\nRules:\n\n- Only the last non-empty line of the tracker is treated as authoritative\n- Marker-like text earlier in the tracker, including notes, examples, or quoted instructions, is ignored\n- Write `WORKFLOW_COMPLETE` only when the workflow's completion criteria have been fully verified\n- Write `WORKFLOW_BLOCKED` only when progress cannot continue in the current workflow without external intervention or a workflow-defined stop condition has been reached\n- Include a concrete reason after the colon whenever possible, but `<!-- WORKFLOW_BLOCKED -->` without a reason is still valid\n\n### Tracker Path\n\nBy default, the tracker file lives at `.athena/<session_id>/tracker.md` in the project root, where `<session_id>` is the current Athena session ID. This session-scoped path allows multiple workflows to run concurrently and makes resume reliable. The runner provides the session ID \u2014 do not generate one yourself.\n\nWorkflows may override the default tracker path via configuration. Read and write the tracker at the configured path for the current workflow.\n\n**Assume interruption.** Your context window can reset at any moment \u2014 the runner may kill a session that's taking too long, or you may hit token limits mid-task. Any progress not written to the tracker is gone. This isn't a theoretical risk; it's the normal operating mode.\n\n## Session Protocol\n\nEvery session follows four phases: **Read**, **Orient**, **Execute**, **End**.\n\n### Phase 1 \u2014 Read the Tracker\n\nRead the tracker file at the configured tracker path for the current workflow. By default this is `.athena/<session_id>/tracker.md`.\n\n- **Contains `<!-- TRACKER_SKELETON -->`**: This is session 1. The runner created a skeleton tracker with the goal and session metadata. Proceed to Phase 2 (Orient) \u2014 replace the skeleton with a real tracker. **You must do this even if the entire request can be satisfied in a single turn.** Write a minimal tracker (what was asked, what was done, the outcome) and then append `<!-- WORKFLOW_COMPLETE -->`. Leaving the skeleton in place causes the runner to classify the session as a failure.\n- **Otherwise**: This is a continuation session. The tracker contains everything prior sessions learned and decided. Skip to Phase 3 (Execute) using the tracker's context.\n\nWhy read first: without the tracker, you'll duplicate work already done or contradict decisions made in prior sessions. The tracker is the single source of truth across sessions.\n\n### Phase 2 \u2014 Orient (Session 1 Only)\n\n#### 2a. Create the tracker immediately\n\nWrite a skeleton tracker as your first write operation, before doing any domain work. Even a minimal tracker with just the goal and \"orientation in progress\" provides continuity if the session is interrupted during setup.\n\nThe tracker must always answer four questions for any future session:\n\n1. What are we trying to accomplish?\n2. What has been completed so far?\n3. What work is left?\n4. What should the next session do first?\n\nThese answers are the contract between sessions. The exact section headings may vary by workflow, but the tracker must make all four answers explicit and easy to find. A future session reading this tracker has no other context \u2014 if something isn't here, it doesn't exist.\n\n#### 2b. Workflow-specific orientation\n\nExecute the orientation steps defined by the workflow. These vary by domain \u2014 a test-writing workflow explores the product in a browser; a migration workflow audits the database schema. The workflow defines what orientation means.\n\n#### 2c. Create a task plan\n\nRefine the skeleton tracker into granular, verifiable checkpoints based on what orientation revealed. Each task should be a concrete unit of progress, not a vague phase. Include verification steps (running checks, reviewing output), not just implementation. Vague tasks like \"write tests\" can't be meaningfully resumed by a future session that has no idea what \"write tests\" means in this context.\n\n#### 2d. Update the tracker\n\nAfter orientation, ensure the tracker captures: the goal, what was discovered, what's planned, and what the next session should do first. Record concrete observations \u2014 what you actually saw, not what you assumed. Assumptions that turn out wrong waste entire future sessions on rework.\n\n### Phase 3 \u2014 Execute\n\nWork through tasks, advancing the plan step by step.\n\n#### Load skills before acting\n\nIf the workflow defines a skill table, load the relevant skill before each activity. Skills carry implementation details \u2014 scaffolding steps, authentication strategies, locator rules, anti-patterns, code templates \u2014 that would otherwise be lost between sessions. This prompt defines the protocol; skills define how to execute each step.\n\n#### Follow the workflow's sequence\n\nExecute in the order the workflow prescribes. Not every session covers all steps \u2014 pick up where the tracker says rather than restarting the flow.\n\n#### Delegate heavy work\n\nUse subagents via the Task tool to offload heavy exploration or generation, preserving your main context for orchestration. Pass file paths, conventions, and concrete output expectations. Instruct subagents to load the appropriate skill.\n\nRespect the workflow's **delegation constraints** \u2014 some operations must run in the main agent because their output serves as proof or because the main agent needs to interpret results in context.\n\n#### Execute quality gates\n\nIf the workflow defines quality gates, execute them in order. Do not skip gates \u2014 they exist because prior experience showed that skipping them leads to cascading rework. If a gate returns a failing verdict, address the issues and re-run the gate before proceeding.\n\nRespect the workflow's **retry limits** for failing steps. Repeated failures usually signal a deeper issue that another retry won't fix.\n\n#### Update the tracker as you work\n\nTreat tracker updates as defensive checkpoints against three failure modes: the runner killing your session, your context collapsing under tool-output load, and you simply forgetting an hour from now what you just learned. The right cadence sits between \"every tool call\" (noisy, wastes tokens, turns the tracker into a log) and \"at the end of the session\" (everything is lost if you die mid-task).\n\nUpdate the tracker whenever any of the following happens \u2014 these are the checkpoints, not \"felt like a good moment\":\n\n- **You finished a discrete unit of work.** A file written, a fix applied, a test run, a quality gate passed. The tracker should reflect the new reality before you start the next unit, not after several units have piled up.\n- **You learned something a future session can't cheaply rederive.** An API quirk, a config field that turned out to matter, a dead end you've now ruled out, a decision between two approaches. Insights are tracker-worthy even when no code changed \u2014 losing them costs the next session a full re-exploration. The tracker is your knowledge ledger, not just a task log.\n- **You're about to do something risky or long-running.** Dispatching a subagent, kicking off a long build, calling a flaky external service, starting a large refactor. If that operation kills your session, only what's already in the tracker survives. Write first, then act.\n- **Your plan changed.** A task got resequenced, a new task surfaced, a planned task turned out to be unnecessary. Stale plans poison continuation sessions \u2014 the tracker must reflect what you'll actually do next, not what you thought five steps ago.\n- **You've been working a while without writing.** If you can't remember when you last touched the tracker, you've gone too long. A short defensive update (\"currently doing X, last completed Y, next is Z\") beats nothing.\n\nWhat an update contains depends on the trigger, but always cover: what changed (work or knowledge), what's now next, and any caveat the next session needs to know. Avoid transcribing tool calls \u2014 the tracker is a contract with your future self, not a replay log.\n\nThe cost of one extra tracker update is a few tokens. The cost of dying without one is a whole wasted session rediscovering what you already knew. Bias toward writing.\n\n#### Task visibility\n\nThe tracker contains the authoritative task plan \u2014 it persists across sessions. Your harness's task UI is only a live projection of that plan, visible to the user in their CLI widget. It is session-scoped and does not survive process exit.\n\n**The relationship:** tracker is the source of truth, task tools are the display.\n\n{{TASK_TOOL_INSTRUCTIONS}}\n\n- **Session 1 (Orient):** After creating the task plan in the tracker, project each task into the task management tools so the user can see progress in real time.\n- **Session 2+ (Resume):** After reading the tracker, recreate the task projection from the tracker's plan. Set statuses to match what the tracker says is done, remaining, and next. The user sees consistent progress across sessions.\n- **During work:** Update both \u2014 the task tools for immediate UI feedback, the tracker for persistence. When a task completes, mark it done in the task tools and record it in the tracker in the same working phase.\n\nThis gives the user a consistent view of progress in their CLI regardless of which session they're in, while the tracker remains the durable contract between sessions.\n\n### Phase 4 \u2014 End of Session\n\n1. Ensure the tracker reflects all progress, discoveries, and blockers.\n2. Write clear instructions for what the next session should do first.\n3. If all work is complete and verified: write `<!-- WORKFLOW_COMPLETE -->` at the end of the tracker.\n4. If an unrecoverable blocker prevents progress: write `<!-- WORKFLOW_BLOCKED -->` or `<!-- WORKFLOW_BLOCKED: reason -->` at the end of the tracker.\n\nDo not write terminal markers prematurely. The runner trusts markers unconditionally \u2014 a premature marker kills the loop before work is done, and there's no automatic recovery.\n\n## Session Bounding\n\nEach fresh session starts with a clean context window and a compact tracker \u2014 effectively a self-compaction. As you work, your context fills with tool outputs, exploration results, and intermediate state. The longer you run, the more attention is spread across tokens that are no longer relevant, degrading your precision on the work that matters now.\n\nWork on a bounded chunk per session. Ending early and letting the next session pick up from a clean tracker is almost always better than pushing through with a heavy context.\n\nHeuristics for when to checkpoint and end:\n\n- After completing a quality gate \u2014 natural boundary\n- After crossing multiple phases (e.g., explored + planned + wrote specs) \u2014 stop before pushing into the next\n- When you notice your context is heavy with tool outputs from earlier work\n\n## Guardrails\n\nQuick-reference checklist \u2014 each of these is explained in detail above:\n\n- Read the tracker before doing anything else\n- Replace the skeleton immediately \u2014 even for simple requests. Write minimal tracker content (what was asked, what was done, outcome) and then the terminal marker before the session ends.\n- Update the tracker on concrete triggers (unit of work done, insight learned, risky operation pending, plan changed) \u2014 not on a vague sense of \"meaningful progress\"\n- Project the tracker's task plan into task management tools at session start\n- Update both task tools and tracker as milestones complete\n- Load the relevant skill before each activity\n- Do not write the completion marker until all work is verified\n- Respect the workflow's delegation constraints and retry limits\n";
+var stateMachine_default = "# Stateless Session Protocol\n\nYou run in a stateless loop. Each session is a fresh process with no memory of prior sessions. **The tracker file is your only continuity** \u2014 read it, work, write it. Assume interruption: the runner may kill a long session, your context may collapse under tool output, you may hit token limits mid-task. Anything not in the tracker is gone.\n\n## First action, every session\n\n1. Read the tracker at the configured path (default: `.athena/<session_id>/tracker.md`). The runner provides the session ID \u2014 do not invent one.\n2. If the tracker contains `<!-- TRACKER_SKELETON -->` \u2192 this is session 1, run [**Orient**](#orient-session-1).\n3. Otherwise \u2192 this is a continuation, run [**Execute**](#execute-session-2) from where the tracker says, not from the start of the flow.\n\nReading first prevents two failure modes that waste whole sessions: redoing work already done, or contradicting decisions a prior session made.\n\n## Tracker contract\n\nThe tracker must always answer four questions:\n\n1. What are we trying to accomplish?\n2. What has been done?\n3. What's left?\n4. What should the next session do first?\n\nA future session has no other context. If something isn't here, it doesn't exist. Section headings may vary by workflow, but these four answers must be explicit and easy to find.\n\n### Terminal markers\n\nDefault markers (workflows may override \u2014 use the markers configured for the active workflow):\n\n- `<!-- WORKFLOW_COMPLETE -->` \u2014 all work done and verified\n- `<!-- WORKFLOW_BLOCKED -->` or `<!-- WORKFLOW_BLOCKED: reason -->` \u2014 cannot proceed without external intervention\n\nRules:\n\n- Only the last non-empty line of the tracker is authoritative. Marker-like text in notes, examples, or quoted instructions earlier in the file is ignored.\n- The runner trusts markers unconditionally. A premature marker ends the loop with no automatic recovery \u2014 write one only when its criteria are fully met.\n- Include a concrete reason after `WORKFLOW_BLOCKED:` whenever possible; the bare form is still valid.\n\n## Phases\n\n### Orient (session 1)\n\n1. **Replace the skeleton immediately**, before any domain work. Even a three-line tracker (goal + \"orienting\") protects you if the session dies during setup.\n2. Run the workflow's orientation steps. These vary by domain \u2014 a test-writing workflow explores the product in a browser; a migration workflow audits the schema. The workflow defines what orientation means.\n3. Refine the tracker into a granular plan. Each task a concrete, verifiable unit of work, including verification steps (running checks, reviewing output) \u2014 not just implementation. Vague tasks (\"write tests\") cannot be meaningfully resumed by a future session that has no idea what they mean here.\n4. Record concrete observations \u2014 what you actually saw, not what you assumed. Wrong assumptions burn entire future sessions on rework.\n5. **Single-turn requests still go through this phase.** If the entire request is satisfied in one turn, write a minimal tracker (what was asked, what was done, the outcome) and append `<!-- WORKFLOW_COMPLETE -->`. Leaving the skeleton in place causes the runner to classify the session as a failure.\n\n### Execute (session 2+)\n\n- Work from where the tracker says, in the workflow's prescribed sequence. Not every session covers every step.\n- If the workflow defines a skill table, **load the relevant skill before each activity**. Skills carry the implementation detail (scaffolding steps, locator rules, anti-patterns, code templates) that this protocol intentionally doesn't repeat.\n- Delegate heavy exploration or generation to subagents via the Task tool. Pass file paths, conventions, and concrete output expectations; tell them which skill to load. Respect the workflow's **delegation constraints** \u2014 some operations must run in the main agent because their output is proof, or because the main agent needs to interpret results in context.\n- Run quality gates in order. Do not skip \u2014 they exist because skipping cascades into rework. On a failing verdict, address the issues and re-run before proceeding. Respect the workflow's **retry limits**: repeated failure usually signals a deeper issue another retry won't fix.\n\n### End\n\n1. Tracker reflects all progress, discoveries, and blockers.\n2. Tracker says clearly what the next session should do first.\n3. If all work is verified: append the completion marker.\n4. If an unrecoverable blocker prevents progress: append the blocked marker, with a reason if you have one.\n\n## When to write the tracker\n\nWrite on **concrete triggers**, not on a vague sense of \"meaningful progress.\" The right cadence sits between every-tool-call (noisy log, wastes tokens) and end-of-session (everything lost if you die mid-task).\n\n- **Discrete unit done** \u2014 file written, fix applied, test run, gate passed. Reflect the new reality before starting the next unit.\n- **Insight learned** \u2014 API quirk, config field that turned out to matter, dead end ruled out, decision between two approaches. Insights are tracker-worthy even when no code changed; rediscovering them costs the next session a full re-exploration. The tracker is a knowledge ledger, not just a task log.\n- **About to do something risky or long-running** \u2014 subagent dispatch, long build, flaky external call, large refactor. Write _first_, then act. If the operation kills your session, only what's on disk survives.\n- **Plan changed** \u2014 task resequenced, new task surfaced, planned task no longer needed. Stale plans poison continuation sessions.\n- **You haven't written in a while** \u2014 if you can't remember the last update, you've gone too long. A short defensive update (\"doing X, last completed Y, next is Z\") beats nothing.\n\nEach update covers: what changed (work or knowledge), what's now next, and any caveat the next session needs. Don't transcribe tool calls \u2014 the tracker is a contract with your future self, not a replay log.\n\nThe cost of one extra tracker update is a few tokens. The cost of dying without one is a whole wasted session. Bias toward writing.\n\n## Task UI projection\n\nThe tracker is the durable source of truth. Your harness's task tools are a session-scoped UI projection of the same plan, shown to the user in their CLI widget. They do not survive process exit.\n\n{{TASK_TOOL_INSTRUCTIONS}}\n\n- **Session 1, after orientation:** project the tracker's task plan into the task tools.\n- **Session 2+, after reading the tracker:** recreate the projection from the tracker; do not assume task IDs from prior sessions still exist.\n- **During work:** update both \u2014 the task tools for immediate UI feedback, the tracker for persistence \u2014 in the same working phase.\n\n## Session bounding\n\nEach fresh session starts with a clean context window and a compact tracker \u2014 effectively self-compaction. As you work, context fills with tool outputs and intermediate state. The longer you run, the more attention is spread across tokens that are no longer relevant, degrading precision on the work that matters now.\n\nWork a bounded chunk per session. Ending early and letting the next session pick up from a clean tracker is almost always better than pushing through with a heavy context. Natural checkpoints:\n\n- After a quality gate\n- After crossing multiple phases (explored \u2192 planned \u2192 wrote specs) \u2014 stop before pushing into the next\n- When your context is visibly heavy with tool output from earlier work\n\n## Quick reference\n\n- [ ] Read the tracker before doing anything else\n- [ ] Replace the skeleton immediately, even for single-turn requests\n- [ ] Update on concrete triggers \u2014 unit done, insight learned, risky op pending, plan changed\n- [ ] Project the tracker plan into task tools at session start; keep both in sync as work lands\n- [ ] Load the workflow's skill before each activity\n- [ ] Run quality gates in order; respect delegation constraints and retry limits\n- [ ] Write the completion marker only when all work is verified\n- [ ] Checkpoint and end before context goes stale\n";
 
 // src/core/workflows/stateMachine.ts
 function buildTaskToolInstructions(harness) {
@@ -2118,4 +2095,4 @@ export {
   compileWorkflowPlan,
   collectMcpServersWithOptions
 };
-//# sourceMappingURL=chunk-GE6PPB6Z.js.map
+//# sourceMappingURL=chunk-5VK2ZMVV.js.map