task-brief

1. Restate the real user goal, not just the surface wording.
2. Define the success criteria in observable terms.
3. Capture the deliverables the task is expected to produce.
4. Surface constraints that materially change execution.
5. Record short assumptions when the user has left gaps.
6. Ask at most one clarifying question when one critical unknown remains.
7. Make one lightweight judgment about whether the task needs design work.
8. After user confirmation, when persistence is warranted, create

   .agents/tasks/<task-id>/

   with a frozen

   brief.md

   and the first

   task_created

   journal entry.

task-brief

• route the task between design skills
• decompose the task into sub-tasks
• draw dependency diagrams
• write implementation steps
• propose migration sequencing
• default to codebase investigation just to sharpen the brief

systematic-debugging

task-brief

• requests with multiple sub-goals or unclear priority order
• requests that span domains (for example data + UI + API)
• requests where the stated problem may not be the real problem
• requests that will likely be handed off to another executor
• requests where missing context would force high-impact assumptions
• requests where the user explicitly asks for help clarifying the task itself

• single, unambiguous actions ("delete this function", "run the tests")
• requests where the intent is already clear and the execution path is obvious
• follow-up messages that only refine an existing task in progress
• requests that explicitly ask for a design tree or design-stage decomposition

• Missing parameter: you know the goal, but one detail is missing.
• Ambiguous intent: the goal could reasonably mean two substantially different things.
• Inaccurate goal: the user stated a solution, symptom, or oddly scoped target instead of the underlying goal.

1. Solution-as-goal: the user names a technique ("add Redis caching") rather than the problem it solves.
2. Symptom-as-goal: the user names an error state ("fix timeout errors") rather than the desired outcome.
3. Scope anomaly: the stated scope looks unnaturally narrow or broad for the problem.

• rewrite the

  User Goal

  around the best-guess underlying intent
• mark that guess as an assumption
• ask one clarifying question that confirms the real target

systematic-debugging

• No outer code block. Render the brief as plain markdown so headings, bold, and quote blocks display naturally.
• Upper tier (the TL;DR) — what the executor needs to grasp in five seconds:

  • User Goal

    rendered as a quote block with the verb-led sentence(s) bolded:

    State the real intent in 1-2 sentences. Start with a verb.

  • Deliverables

    as a short bulleted list.

  • Clarifying Question

    (only when one is needed) prefixed with

    ❓

    for visual salience.
• Divider (

  ---

  ) separates the upper tier from the lower tier.
• Lower tier (the rest) — context an executor consults as they work:

  • Success Criteria

    as bulleted observable checks.

  • Constraints

    as a flat bulleted list. Do not force

    Scope

    /

    Format

    /

    Risk

    /

    Other

    sub-categories; only break out a sub-label when the constraint is heterogeneous enough to need it.

  • Assumptions

    as a short bulleted list when the user left gaps.
  • Recommended next as one natural-language sentence stating whether to proceed directly, enter the design stage (with a brief reason), or pause for clarification.
• Skip empty fields entirely. Do not render

  Assumptions:

  with "(none)" — omit the heading.
• Do not render

  Task Type

  by default. It exists in the protocol as an anchor but adds little to the user view; surface it only when the executor genuinely needs to disambiguate.

• the underlying goal
• constraints that eliminate whole categories of solutions
• domain context that changes the execution path

• filler phrases
• repeated restatements of the same goal
• reasoning the executor does not need to act

• "make it better" -> identify the dimension: performance, readability, UX, security
• "something's wrong" -> specify observed vs. expected behavior
• "soon" / "quickly" -> ask for a concrete deadline only if it affects approach
• "the usual format" -> infer from context or mark it as an assumption
• "add Redis to the API" -> ask what problem the user is trying to solve

• if two substantially different interpretations are plausible, surface both explicitly
• ask one question that forces the choice
• defer deliverables that depend on that choice rather than guessing

• preserve the user's framing when it carries real intent
• do not invent goals or constraints the user did not imply
• if uncertain whether a detail matters, keep it and mark it as an assumption

• the task is multi-step (more than one major action)
• the task will produce a persistent artifact (design tree, plan, code branch, report)
• the brief recommends entering the design stage
• the user signals follow-up will continue across sessions

• the task is a single trivial action (rename, typo fix, run a known command)
• the user explicitly says they don't want a task record
• the work is already attached to an existing task — append to that task's journal instead

• Propose a slug derived from the

  User Goal

  : ASCII kebab-case, ≤ 6 words, ≤ 60 characters.
• If the user supplies their own slug, use the user's slug verbatim.
• The user's slug always wins over the proposal — do not auto-edit it for "kebab-case correctness" if it's already legible.

1. Create directory

   .agents/tasks/<task-id>/

   plus

   artifacts/

   subdirectory.
2. Write

   brief.md

   with the brief content (the canonical anchored fields, no rendering decoration).
3. Write the first journal entry to

   journal.md

   :

   ## <ISO8601> — task-brief
   task_created: brief.md
   slug derived from "<short reason>"

4. Update

   .agents/tasks/.current

   to point at the new task id.

brief.md

refined:

brief.md

task-journal

"Extract all TODO comments from the codebase and output them as a markdown list grouped by file."

Collect every TODO comment across the codebase and produce a readable markdown list grouped by file.

• Markdown list of TODO comments grouped by file, each entry with file path and line number

• Output groups TODO entries by file
• Each entry includes a line number
• Output covers the entire repository

• Output format: markdown
• Scope: entire repository

• "TODO" matches the literal strings

  TODO

  or

  TODO:

"I need to migrate our auth system to JWT. Can you help me figure out what needs to change?"

Identify what needs to change to migrate the current authentication system to JWT-based auth, before scoping the migration itself.

• Auth migration change brief covering affected components and migration target

• Affected auth components are identified
• Migration target is concrete enough to begin design or impact analysis

• Scope is limited to authentication-related behavior
• Do not assume a stateless-token migration path if the current system is session-based or third-party managed

• "JWT" means standard stateless tokens rather than JWE

"Build me a dashboard that shows real-time sales data pulled from our Postgres DB, with a chart for daily revenue and a table for top 10 products. It should update every 30 seconds and be shareable via a link."

Build a shareable dashboard that displays live sales data from Postgres, including a daily revenue chart and a top-products table that refresh every 30 seconds.

• Live sales dashboard with daily revenue chart and top-10 products table
• Shareable URL for accessing the dashboard

• Dashboard shows daily revenue and top-10 products from live data
• Dashboard refreshes every 30 seconds
• Dashboard is reachable through a stable URL

• Browser-based UI only
• No database writes from the dashboard
• No credential exposure in client-side code

• Postgres already exposes the fields needed for revenue aggregation and top-product ranking

"Our API docs are a mess - can you help fix them?"

Improve the API documentation, but disambiguate between two materially different outcomes before any work begins: rewriting the documentation content vs. changing the documentation tooling or site structure.

• Deferred until the direction is confirmed

• Intended direction is confirmed before work starts

• Scope is limited to public API documentation
• External developer experience may be affected by public doc changes

• "API docs" refers to developer-facing HTTP API documentation rather than internal notes

"Add Redis caching to our API endpoints."

Reduce API latency or backend load. Redis caching is the user's proposed technique, but the underlying goal is performance — the actual bottleneck has not been confirmed.

• Performance-problem brief that names the actual bottleneck

• Real performance problem is identified
• Task target is reframed around the actual bottleneck rather than a preselected technique

• Scope is limited to API behavior
• Do not assume caching is appropriate before the bottleneck is known

• The user wants better performance but has not confirmed where the bottleneck is

1. Standalone: an executor can start correctly from the brief alone, or knows the one question that must be answered first.
2. Intent-preserving: the

   User Goal

   captures what the user actually wants, not just what they said.
3. Constraint-complete: missing any included constraint would materially risk wrong-path execution.
4. Non-padded: the brief stays short when the task is simple. Empty fields are omitted entirely.
5. Actionable deliverables: each deliverable is a concrete artifact or outcome.
6. Goal-honest: the brief reframes solution-as-goal and symptom-as-goal requests honestly.
7. Scope-clean: the brief does not drift into design routing, decomposition, or implementation planning.
8. Single-question discipline: when clarification is needed, the brief asks one focused question, not a questionnaire.
9. Creation discipline: a task directory is created only after the user confirms, with a slug they accepted or supplied.

• it restates the user's message in different words without adding clarity
• it introduces goals or constraints the user did not imply
• it turns a simple request into a long clarification session
• it drifts into design trees, sub-task decomposition, or implementation plans
• it creates a task directory silently or against the user's wishes