mervexai 0.0.97

package/src/tool/skill.ts

@@ -0,0 +1,81 @@
+import path from "path"
+import { Effect, Schema } from "effect"
+import { Ripgrep } from "@msrfteam/core/ripgrep"
+import { Skill } from "../skill"
+import { SkillRestriction } from "../skill/restriction"
+import * as Tool from "./tool"
+import DESCRIPTION from "./skill.txt"
+
+export const Parameters = Schema.Struct({
+  name: Schema.String.annotate({ description: "The name of the skill from available_skills" }),
+})
+
+export const SkillTool = Tool.define(
+  "skill",
+  Effect.gen(function* () {
+    const skill = yield* Skill.Service
+    const ripgrep = yield* Ripgrep.Service
+    const restriction = yield* SkillRestriction.Service
+
+    return {
+      description: DESCRIPTION,
+      parameters: Parameters,
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          const info = yield* skill
+            .require(params.name)
+            .pipe(Effect.catchTag("Skill.NotFoundError", (error) => Effect.die(new Error(error.message))))
+
+          yield* ctx.ask({
+            permission: "skill",
+            patterns: [params.name],
+            always: [params.name],
+            metadata: {},
+          })
+
+          if (info.allowedTools?.length) {
+            yield* restriction.setRestriction(ctx.sessionID, info.allowedTools)
+          } else {
+            yield* restriction.clearRestriction(ctx.sessionID)
+          }
+
+          const dir = path.dirname(info.location)
+          const base = dir
+          const files = yield* ripgrep.find({
+            cwd: dir,
+            pattern: "!**/SKILL.md",
+            hidden: true,
+            follow: false,
+            signal: ctx.abort,
+            limit: 10,
+          })
+
+          return {
+            title: `Loaded skill: ${info.name}`,
+            output: [
+              `<skill_content name="${info.name}">`,
+              `# Skill: ${info.name}`,
+              "",
+              info.content.trim(),
+              "",
+              ...(info.allowedTools?.length
+                ? [`This skill is restricted to these tools only: ${info.allowedTools.join(", ")}`]
+                : []),
+              `Base directory for this skill: ${base}`,
+              "Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.",
+              "Note: file list is sampled.",
+              "",
+              "<skill_files>",
+              files.map((file) => `<file>${path.resolve(dir, file.path)}</file>`).join("\n"),
+              "</skill_files>",
+              "</skill_content>",
+            ].join("\n"),
+            metadata: {
+              name: info.name,
+              dir,
+            },
+          }
+        }).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/tool/skill.txt

@@ -0,0 +1,5 @@
+Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.
+
+Use this tool to inject the skill's instructions and resources into current conversation. The output may contain detailed workflow guidance as well as references to scripts, files, etc in the same directory as the skill.
+
+The skill name must match one of the skills listed in your system prompt.

package/src/tool/task.ts

@@ -0,0 +1,461 @@
+import * as Tool from "./tool"
+import DESCRIPTION from "./task.txt"
+import { SessionV1 } from "@msrfteam/core/v1/session"
+import { BackgroundJob } from "@/background/job"
+import { Session } from "@/session/session"
+import { SessionID, MessageID } from "../session/schema"
+import { MessageV2 } from "../session/message-v2"
+import { Agent } from "../agent/agent"
+import { deriveSubagentSessionPermission } from "../agent/subagent-permissions"
+import type { SessionPrompt } from "../session/prompt"
+import { Config } from "@/config/config"
+import { ProviderV2 } from "@msrfteam/core/provider"
+import { ModelV2 } from "@msrfteam/core/model"
+import { Effect, Exit, Schema, Scope } from "effect"
+import { EffectBridge } from "@/effect/bridge"
+import { Database } from "@msrfteam/core/database/database"
+
+export interface TaskPromptOps {
+  cancel(sessionID: SessionID): Effect.Effect<void>
+  resolvePromptParts(template: string): Effect.Effect<SessionPrompt.PromptInput["parts"]>
+  prompt(input: SessionPrompt.PromptInput): Effect.Effect<SessionV1.WithParts>
+}
+
+const id = "task"
+
+const ALL_TOOL_PERMISSIONS = [
+  "read",
+  "edit",
+  "glob",
+  "grep",
+  "list",
+  "bash",
+  "task",
+  "external_directory",
+  "todowrite",
+  "question",
+  "webfetch",
+  "websearch",
+  "lsp",
+  "doom_loop",
+  "skill",
+  "apply_patch",
+  "write",
+]
+const BACKGROUND_DESCRIPTION = [
+  "Background mode: background=true launches the subagent asynchronously and returns immediately.",
+  "Foreground is the default; use it when you need the result before continuing.",
+  "Use background only for independent work that can run while you continue elsewhere.",
+  "You will be notified automatically when it finishes.",
+].join(" ")
+const BACKGROUND_STARTED = [
+  "The task is working in the background. You will be notified automatically when it finishes.",
+  "DO NOT sleep, poll for progress, ask the task for status, or duplicate this task's work — avoid working with the same files or topics it is using.",
+  "Work on non-overlapping tasks, or briefly tell the user what you launched and end your response.",
+].join("\n")
+const BACKGROUND_UPDATED = [
+  "Additional context sent to the running background task.",
+  "The task is still working in the background. You will be notified automatically when it finishes.",
+  "DO NOT sleep, poll for progress, ask the task for status, or duplicate this task's work — avoid working with the same files or topics it is using.",
+  "Work on non-overlapping tasks, or briefly tell the user what you sent and end your response.",
+].join("\n")
+
+const BaseParameterFields = {
+  description: Schema.String.annotate({ description: "A short (3-5 words) description of the task" }),
+  prompt: Schema.String.annotate({ description: "The task for the agent to perform" }),
+  subagent_type: Schema.String.annotate({ description: "The type of specialized agent to use for this task" }),
+  task_id: Schema.optional(Schema.String).annotate({
+    description:
+      "This should only be set if you mean to resume a previous task (you can pass a prior task_id and the task will continue the same subagent session as before instead of creating a fresh one)",
+  }),
+  command: Schema.optional(Schema.String).annotate({ description: "The command that triggered this task" }),
+  fork_turns: Schema.optional(Schema.String).annotate({
+    description:
+      'Only valid with subagent_type="fork". Omit it or use "all" for the full parent conversation, or use a positive integer string such as "3" for the most recent three real user turns. Tool responses and pure system reminders do not count as turns.',
+  }),
+  fork_tools: Schema.optional(Schema.mutable(Schema.Array(Schema.String))).annotate({
+    description:
+      'Only valid with subagent_type="fork". Restricts execution to exact canonical tool names or MCP server patterns while keeping the fork\'s current model-visible tool declarations unchanged for prompt-cache sharing. Forks never execute the question tool; omit to allow every other inherited tool, or use an empty array to reject every tool call.',
+  }),
+  model: Schema.optional(Schema.String).annotate({
+    description:
+      'Override the model for this subagent as "providerID/modelID" (e.g. "anthropic/claude-sonnet-4-5"). Omit to use the agent default, or the parent model when the agent has none. Route cheap subtasks to small models and hard ones to frontier models.',
+  }),
+}
+
+export const Parameters = Schema.Struct({
+  ...BaseParameterFields,
+  background: Schema.optional(Schema.Boolean).annotate({
+    description:
+      "Run the agent in the background. You will be notified when it completes. DO NOT sleep, poll, or proactively check on its progress",
+  }),
+})
+
+function parseModelRef(ref: string) {
+  const sep = ref.indexOf("/")
+  if (sep === -1) return undefined
+  const providerID = ref.slice(0, sep).trim()
+  const modelID = ref.slice(sep + 1).trim()
+  if (!providerID || !modelID) return undefined
+  return { providerID: ProviderV2.ID.make(providerID), modelID: ModelV2.ID.make(modelID) }
+}
+
+function buildForkContext(messages: Iterable<SessionV1.WithParts>, forkTurns: string | undefined): string {
+  const msgs = Array.from(messages)
+  if (forkTurns === "all" || !forkTurns) {
+    const lines = formatMessages(msgs)
+    return lines.length > 0
+      ? `<fork_context>\nParent conversation (full history):\n${lines.join("\n")}\n</fork_context>\n\n`
+      : ""
+  }
+  const numTurns = parseInt(forkTurns, 10)
+  if (!Number.isFinite(numTurns) || numTurns < 1) return ""
+
+  const realUserMsgs: SessionV1.WithParts[] = []
+  const all = msgs.slice().reverse()
+  for (const msg of all) {
+    if (msg.info.role !== "user") continue
+    const isReal = msg.parts.some((p) => p.type !== "text" || !("synthetic" in p) || !p.synthetic)
+    if (!isReal) continue
+    realUserMsgs.push(msg)
+    if (realUserMsgs.length >= numTurns) break
+  }
+  realUserMsgs.reverse()
+
+  const firstId = realUserMsgs[0]?.info.id
+  const start = firstId ? msgs.findIndex((m) => m.info.id === firstId) : -1
+  const filtered = start === -1 ? msgs : msgs.slice(start)
+  const lines = formatMessages(filtered)
+  return lines.length > 0
+    ? `<fork_context>\nParent conversation (last ${numTurns} turn(s)):\n${lines.join("\n")}\n</fork_context>\n\n`
+    : ""
+}
+
+function formatMessages(msgs: SessionV1.WithParts[]): string[] {
+  const lines: string[] = []
+  for (const msg of msgs) {
+    const role = msg.info.role === "user" ? "user" : "assistant"
+    const texts = msg.parts
+      .filter((p): p is SessionV1.TextPart => p.type === "text")
+      .map((p) => p.text)
+      .join("\n")
+    if (!texts.trim()) continue
+    lines.push(`${role}: ${texts.trim()}`)
+  }
+  return lines
+}
+
+function renderOutput(input: {
+  sessionID: SessionID
+  state: "running" | "completed" | "error"
+  summary?: string
+  text: string
+}) {
+  const tag = input.state === "error" ? "task_error" : "task_result"
+  return [
+    `<task id="${input.sessionID}" state="${input.state}">`,
+    ...(input.summary ? [`<summary>${input.summary}</summary>`] : []),
+    `<${tag}>`,
+    input.text,
+    `</${tag}>`,
+    "</task>",
+  ].join("\n")
+}
+
+export const TaskTool = Tool.define(
+  id,
+  Effect.gen(function* () {
+    const agent = yield* Agent.Service
+    const background = yield* BackgroundJob.Service
+    const config = yield* Config.Service
+    const sessions = yield* Session.Service
+    const scope = yield* Scope.Scope
+    const database = yield* Database.Service
+
+    const run = Effect.fn("TaskTool.execute")(function* (
+      params: Schema.Schema.Type<typeof Parameters>,
+      ctx: Tool.Context,
+    ) {
+      const cfg = yield* config.get()
+      const runInBackground = params.background === true
+
+      const parent = yield* sessions.get(ctx.sessionID)
+      let current = parent
+      let depth = 0
+      while (current.parentID) {
+        depth++
+        current = yield* sessions.get(current.parentID)
+      }
+      if (depth >= (cfg.subagent_depth ?? 1)) {
+        return yield* Effect.fail(
+          new Error(
+            `Subagent depth limit reached (${cfg.subagent_depth ?? 1}). Increase "subagent_depth" to allow nested subagents.`,
+          ),
+        )
+      }
+
+      if (!ctx.extra?.bypassAgentCheck) {
+        yield* ctx.ask({
+          permission: id,
+          patterns: [params.subagent_type],
+          always: ["*"],
+          metadata: {
+            description: params.description,
+            subagent_type: params.subagent_type,
+          },
+        })
+      }
+
+      const next = yield* agent.get(params.subagent_type)
+      if (!next) {
+        return yield* Effect.fail(new Error(`Unknown agent type: ${params.subagent_type} is not a valid agent type`))
+      }
+
+      const buildForkPrompt = Effect.fn("TaskTool.buildForkPrompt")(function* () {
+        if (!(next.name === "fork")) return params.prompt
+        const msgs = yield* sessions.messages({ sessionID: ctx.sessionID }).pipe(Effect.catchCause(() => Effect.succeed([])))
+        const context = buildForkContext(msgs, params.fork_turns)
+        return context + params.prompt
+      })
+
+      const session = params.task_id
+        ? yield* sessions.get(SessionID.make(params.task_id)).pipe(Effect.catchCause(() => Effect.succeed(undefined)))
+        : undefined
+      const childPermission = deriveSubagentSessionPermission({
+        parentSessionPermission: parent.permission ?? [],
+        subagent: next,
+      })
+      const childToolDenies = [
+        ...(next.permission.some((rule) => rule.permission === "todowrite")
+          ? []
+          : [{ permission: "todowrite" as const, pattern: "*" as const, action: "deny" as const }]),
+        ...(next.permission.some((rule) => rule.permission === id)
+          ? []
+          : [{ permission: id, pattern: "*" as const, action: "deny" as const }]),
+        ...(cfg.experimental?.primary_tools?.map((permission) => ({
+          permission,
+          pattern: "*" as const,
+          action: "deny" as const,
+        })) ?? []),
+        ...(next.name === "fork" && params.fork_tools
+          ? ALL_TOOL_PERMISSIONS.filter((permission) => !params.fork_tools?.includes(permission)).map(
+              (permission) => ({ permission, pattern: "*" as const, action: "deny" as const }),
+            )
+          : []),
+      ]
+      const nextSession =
+        session ??
+        (yield* sessions.create({
+          parentID: ctx.sessionID,
+          title: params.description + ` (@${next.name} subagent)`,
+          agent: next.name,
+          permission: [
+            ...childPermission,
+            ...childToolDenies.filter(
+              (deny) =>
+                !childPermission.some(
+                  (rule) =>
+                    rule.permission === deny.permission && rule.pattern === deny.pattern && rule.action === deny.action,
+                ),
+            ),
+          ],
+        }))
+
+      const msg = yield* MessageV2.get({ sessionID: ctx.sessionID, messageID: ctx.messageID }).pipe(
+        Effect.provideService(Database.Service, database),
+        Effect.orDie,
+      )
+      if (msg.info.role !== "assistant") return yield* Effect.fail(new Error("Not an assistant message"))
+      const variant = msg.info.variant
+
+      const overrideModel = params.model ? parseModelRef(params.model) : undefined
+      const model = overrideModel ?? next.model ?? {
+        modelID: msg.info.modelID,
+        providerID: msg.info.providerID,
+      }
+      const metadata = {
+        parentSessionId: ctx.sessionID,
+        sessionId: nextSession.id,
+        model,
+        ...(runInBackground ? { background: true } : {}),
+      }
+
+      yield* ctx.metadata({
+        title: params.description,
+        metadata,
+      })
+
+      const ops = ctx.extra?.promptOps as TaskPromptOps
+      if (!ops) return yield* Effect.fail(new Error("TaskTool requires promptOps in ctx.extra"))
+
+      const forkPrompt = yield* buildForkPrompt()
+      const runTask = Effect.fn("TaskTool.runTask")(function* () {
+        const parts = yield* ops.resolvePromptParts(forkPrompt)
+        const result = yield* ops.prompt({
+          messageID: MessageID.ascending(),
+          sessionID: nextSession.id,
+          model: {
+            modelID: model.modelID,
+            providerID: model.providerID,
+          },
+          variant: (next.model ?? overrideModel) ? undefined : variant,
+          agent: next.name,
+          parts,
+        })
+        if (result.info.role === "assistant" && result.info.error) {
+          const message =
+            "message" in result.info.error.data && typeof result.info.error.data.message === "string"
+              ? result.info.error.data.message
+              : result.info.error.name
+          return yield* Effect.fail(new Error(`Subagent failed (task_id: ${nextSession.id}): ${message}`))
+        }
+        const failed = result.parts.findLast((item) => item.type === "tool" && item.state.status === "error")
+        if (failed?.type === "tool" && failed.state.status === "error") {
+          return yield* Effect.fail(new Error(`Subagent failed (task_id: ${nextSession.id}): ${failed.state.error}`))
+        }
+        return result.parts.findLast((item) => item.type === "text")?.text ?? ""
+      })
+
+      const inject = Effect.fn("TaskTool.injectBackgroundResult")(function* (
+        state: "completed" | "error",
+        text: string,
+      ) {
+        const currentParent = yield* sessions.get(ctx.sessionID)
+        yield* ops
+          .prompt({
+            sessionID: ctx.sessionID,
+            agent: currentParent.agent ?? ctx.agent,
+            variant,
+            parts: [
+              {
+                type: "text",
+                synthetic: true,
+                text: renderOutput({
+                  sessionID: nextSession.id,
+                  state,
+                  summary:
+                    state === "completed"
+                      ? `Background task completed: ${params.description}`
+                      : `Background task failed: ${params.description}`,
+                  text,
+                }),
+              },
+            ],
+          })
+          .pipe(Effect.ignore, Effect.forkIn(scope, { startImmediately: true }))
+      })
+
+      const notify = Effect.fn("TaskTool.notifyBackgroundResult")(function* (jobID: string) {
+        yield* background.wait({ id: jobID }).pipe(
+          Effect.flatMap((result) => {
+            if (result.info?.status === "completed") return inject("completed", result.info.output ?? "")
+            if (result.info?.status === "error") return inject("error", result.info.error ?? "")
+            return Effect.void
+          }),
+          Effect.forkIn(scope, { startImmediately: true }),
+        )
+      })
+
+      if (yield* background.extend({ id: nextSession.id, run: runTask() })) {
+        return {
+          title: params.description,
+          metadata: {
+            ...metadata,
+            background: true,
+            jobId: nextSession.id,
+          },
+          output: renderOutput({
+            sessionID: nextSession.id,
+            state: "running",
+            summary: "Background task updated",
+            text: BACKGROUND_UPDATED,
+          }),
+        }
+      }
+
+      const info = yield* background.start({
+        id: nextSession.id,
+        type: id,
+        title: params.description,
+        metadata,
+        onPromote: Effect.all([
+          ctx.metadata({
+            title: params.description,
+            metadata: { ...metadata, background: true, jobId: nextSession.id },
+          }),
+          notify(nextSession.id),
+        ]),
+        run: runTask().pipe(Effect.onInterrupt(() => ops.cancel(nextSession.id))),
+      })
+
+      function backgroundResult() {
+        return {
+          title: params.description,
+          metadata: {
+            ...metadata,
+            background: true,
+            jobId: info.id,
+          },
+          output: renderOutput({
+            sessionID: nextSession.id,
+            state: "running",
+            summary: "Background task started",
+            text: BACKGROUND_STARTED,
+          }),
+        }
+      }
+
+      if (runInBackground) {
+        yield* notify(info.id)
+        return backgroundResult()
+      }
+
+      const runCancel = yield* EffectBridge.make()
+      const cancel = ops.cancel(nextSession.id)
+
+      function onAbort() {
+        runCancel.fork(cancel)
+      }
+
+      return yield* Effect.acquireUseRelease(
+        Effect.sync(() => {
+          ctx.abort.addEventListener("abort", onAbort)
+        }),
+        () =>
+          Effect.gen(function* () {
+            const result = yield* Effect.raceFirst(
+              background.wait({ id: nextSession.id }).pipe(Effect.map((waited) => waited.info)),
+              background.waitForPromotion(nextSession.id),
+            )
+            if (result?.metadata?.background === true) return backgroundResult()
+            if (result?.status === "error") return yield* Effect.fail(new Error(result.error ?? "Task failed"))
+            if (result?.status === "cancelled") return yield* Effect.fail(new Error("Task cancelled"))
+            return {
+              title: params.description,
+              metadata,
+              output: renderOutput({ sessionID: nextSession.id, state: "completed", text: result?.output ?? "" }),
+            }
+          }),
+        (_, exit) =>
+          Effect.gen(function* () {
+            if (Exit.hasInterrupts(exit))
+              yield* Effect.all([cancel, background.cancel(nextSession.id)], { discard: true })
+          }).pipe(
+            Effect.ensuring(
+              Effect.sync(() => {
+                ctx.abort.removeEventListener("abort", onAbort)
+              }),
+            ),
+          ),
+      )
+    })
+
+    return {
+      description: [DESCRIPTION, BACKGROUND_DESCRIPTION].join("\n\n"),
+      parameters: Parameters,
+      jsonSchema: undefined,
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
+        run(params, ctx).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/tool/task.txt

@@ -0,0 +1,21 @@
+Launch a new agent to handle complex, multistep tasks autonomously.
+
+When using the Task tool, you must specify a subagent_type parameter to select which agent type to use.
+
+Use the model parameter ("providerID/modelID") to route subtasks to different models: cheap research to small fast models, hard reasoning to frontier models. Omit it to inherit the agent default or parent model.
+
+When NOT to use the Task tool:
+- If you want to read a specific file path, use the Read or Glob tool instead of the Task tool, to find the match more quickly
+- If you are searching for a specific class definition like "class Foo", use the Grep tool instead, to find the match more quickly
+- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Task tool, to find the match more quickly
+- If no available agent is a good fit for the task, use other tools directly
+
+
+Usage notes:
+1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+2. Once you have delegated work to an agent, do not duplicate that work yourself. Continue with non-overlapping tasks, or wait for the result. For background tasks, you will be notified automatically when the result is ready.
+3. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result. The output includes a task_id you can reuse later to continue the same subagent session.
+4. Each agent invocation starts with a fresh context unless you provide task_id to resume the same subagent session (which continues with its previous messages and tool outputs). When starting fresh, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
+5. The agent's outputs should generally be trusted
+6. Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent. Tell it how to verify its work if possible (e.g., relevant test commands).
+7. If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.

package/src/tool/todo.ts

@@ -0,0 +1,46 @@
+import { Effect, Schema } from "effect"
+import * as Tool from "./tool"
+import DESCRIPTION_WRITE from "./todowrite.txt"
+import { Todo } from "../session/todo"
+
+export const Parameters = Schema.Struct({
+  todos: Schema.mutable(Schema.Array(Todo.Info)).annotate({ description: "The updated todo list" }),
+})
+
+type Metadata = {
+  todos: Todo.Info[]
+}
+
+export const TodoWriteTool = Tool.define<typeof Parameters, Metadata, Todo.Service>(
+  "todowrite",
+  Effect.gen(function* () {
+    const todo = yield* Todo.Service
+
+    return {
+      description: DESCRIPTION_WRITE,
+      parameters: Parameters,
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context<Metadata>) =>
+        Effect.gen(function* () {
+          yield* ctx.ask({
+            permission: "todowrite",
+            patterns: ["*"],
+            always: ["*"],
+            metadata: {},
+          })
+
+          yield* todo.update({
+            sessionID: ctx.sessionID,
+            todos: params.todos,
+          })
+
+          return {
+            title: `${params.todos.filter((x) => x.status !== "completed").length} todos`,
+            output: JSON.stringify(params.todos, null, 2),
+            metadata: {
+              todos: params.todos,
+            },
+          }
+        }),
+    } satisfies Tool.DefWithoutID<typeof Parameters, Metadata>
+  }),
+)

package/src/tool/todowrite.txt

@@ -0,0 +1,44 @@
+Create and maintain a structured task list for the current coding session. Tracks progress, organizes multi-step work, and surfaces status to the user.
+
+## When to use
+Use proactively when:
+- The task requires 3+ distinct steps or actions (not just 3 tool calls for a single conceptual step)
+- The work is non-trivial and benefits from planning
+- The user provides multiple tasks (numbered or comma-separated) or explicitly asks for a todo list
+- New instructions arrive - capture them as todos
+- You start a task - mark it `in_progress` (only one at a time) before working
+- You finish a task - mark it `completed` and add any follow-ups discovered during the work
+
+## When NOT to use
+Skip when:
+- The work is a single, straightforward task (or <3 trivial steps)
+- The request is purely informational or conversational
+- Tracking adds no organizational value
+
+## States
+- `pending` - not started
+- `in_progress` - actively working (exactly ONE at a time)
+- `completed` - finished successfully
+- `cancelled` - no longer needed
+
+## Rules
+- Update status in real time; don't batch completions
+- Mark `completed` only after the required work is actually done, including any required verification. Never based on intent.
+- Keep exactly one `in_progress` while work remains
+- If blocked or partial, keep it `in_progress` and add a follow-up todo describing the blocker
+- Preserve user-provided commands verbatim (flags, args, order)
+- Items should be specific and actionable; break large work into smaller steps
+
+## Examples
+
+Use it:
+- "Add a dark mode toggle and run the tests" -> multi-step feature + explicit verification
+- "Rename getCwd -> getCurrentWorkingDirectory across the repo" -> grep reveals 15 occurrences in 8 files
+- "Implement registration, catalog, cart, checkout" -> multiple complex features
+
+Skip it:
+- "How do I print Hello World in Python?" -> informational
+- "Add a comment to calculateTotal" -> single edit
+- "Run npm install and tell me what happened" -> one command
+
+When in doubt, use it.