Do-Work Skill

A unified entry point for task capture and processing.

Actions:

• capture requests: Capture new tasks/requests → creates UR folder (verbatim input) + REQ files (queue items), always paired
• verify requests: Evaluate captured REQs against original input → quality check
• work: Process pending requests → executes the queue
• clarify questions: Batch-review Open Questions from completed work → user answers, confirms, or skips
• review work: Post-work review → requirements check, code review, acceptance testing, and testing suggestions
• present work: Client-facing deliverables → briefs, architecture diagrams, value propositions, Remotion videos
• cleanup: Consolidate archive → moves loose REQs into UR folders, closes completed URs
• commit: Commit uncommitted files → analyzes, groups atomically, traces to REQs

Core concept: The capture requests action always produces both a UR folder (preserving the original input) and REQ files (the queue items). Each REQ links back to its UR via user_request frontmatter. This pairing is mandatory for all requests — simple or complex.

Capture ≠ Execute. The capture requests action captures requests. The work action executes them. These are strictly separate operations. After capture finishes writing files and reporting back, STOP. Do not start processing the queue, do not begin implementation, do not "helpfully" transition into the work action. The user decides when to execute — always. The only exception is if the user explicitly says something like "add this and then run it" or "capture this and start working" in the same invocation.

Human time has two optimal windows. The system is designed to maximize the value of human attention:

1. Capture phase (capture requests action) — The user is present, actively thinking about the request. This is the best time for back-and-forth: clarifying ambiguities, resolving contradictions, making scope decisions. Use AskUserQuestion with concrete choices here. Every question must present options — never open-ended "what do you mean?" prompts.

2. Batch question review (clarify questions action) — After the build phase completes everything it can without feedback, any remaining pending-answers REQs are surfaced as a batch. The user reviews all builder-decided questions together, confirms or adjusts, and resolved REQs re-enter the queue.

Between these windows, the build phase runs autonomously. Builders never block on Open Questions — they mark them - [~] with best-judgment reasoning and create pending-answers follow-ups when they return via do work clarify.

Routing Decision

Step 1: Parse the Input

Examine what follows "do work":

Check these patterns in order — first match wins:

Priority	Pattern	Example	Route
1	Empty or bare invocation	do work	→ help menu
2	Action verbs only	do work run, do work go, do work start	→ work
3	Verify keywords	do work verify, do work verify requests, do work check, do work evaluate	→ verify requests
4	Clarify keywords	do work clarify, do work questions, do work pending	→ clarify questions
5	Review keywords	do work review, do work review work, do work review code, do work code review, do work audit code	→ review work
6	Present keywords	do work present, do work present work, do work showcase, do work deliver	→ present work
7	Cleanup keywords	do work cleanup, do work tidy, do work consolidate	→ cleanup
8	Commit keywords	do work commit, do work commit changes, do work save work	→ commit
9	Version keywords	do work version, do work update, do work check for updates	→ version
10	Changelog keywords	do work changelog, do work release notes, do work what's new, do work what's changed, do work updates, do work history	→ version
11	Descriptive content	do work add dark mode, do work [meeting notes], do work capture request [the request]	→ capture requests

Step 2: Preserve Payload

Critical rule: Never lose the user's content.

Single-word rule: A single word is either a known keyword or ambiguous — it is never "descriptive content."

• Matches a keyword in the routing table (e.g., "version", "verify", "cleanup") → route to that action directly.
• Doesn't match any keyword (e.g., "refactor", "optimize") → ambiguous. Ask: "Do you want to add '{word}' as a new request, or did you mean something else?"

Only route to capture requests when the input is clearly descriptive — multiple words, a sentence, a feature request, etc.

If routing is genuinely unclear AND multi-word content was provided:

• Default to capture requests (adding a task)
• Hold onto $ARGUMENTS
• If truly ambiguous, ask: "Add this as a request, or start the work loop?"
• User replies with just "add" or "work" → proceed with original content

Action Verbs (→ Work)

These signal "process the queue": run, go, start, begin, work, process, execute, build, continue, resume

Clarify Verbs (→ Clarify Questions)

These signal "review pending questions": clarify, answers, questions, pending, pending answers, blocked, what's blocked, what needs answers

Note: This routes to the work action with mode: clarify — see work.md "Clarify Questions" section.

Verify Verbs (→ Verify Requests)

These signal "check request quality": verify, verify requests, check, evaluate, review requests, review reqs, audit

Note: "check" routes to verify requests ONLY when used alone or with a target (e.g., "do work check UR-003"). When followed by descriptive content it routes to capture requests (e.g., "do work check if the button works" → capture requests).

Note: "audit" alone routes to verify requests. "audit code" and "audit implementation" route to review work (see Review Verbs below).

Review Verbs (→ Review Work)

These signal "review the completed work": review, review work, review code, code review, audit code, audit implementation, review REQ-NNN, review UR-NNN

Note: "review requests" and "review reqs" route to verify requests (priority 4), not review work. "review" alone or followed by a target/code-related word routes to review work (priority 5). The review work action also runs automatically as part of the work pipeline — see work.md Step 7.

Present Verbs (→ Present Work)

These signal "generate client-facing deliverables": present, present work, showcase, deliver, pitch, client brief

Note: do work present (no target) presents the most recent completed UR. do work present all or do work present portfolio enters portfolio mode. do work present UR-003 or do work present REQ-005 targets specific work.

Cleanup Verbs (→ Cleanup)

These signal "consolidate the archive": cleanup, clean up, tidy, consolidate, organize archive, fix archive

Commit Verbs (→ Commit)

These signal "commit uncommitted files atomically": commit, commit changes, commit files, save changes, save work

Changelog Verbs (→ Version)

These signal "show release notes": changelog, release notes, what's new, what's changed, updates, history

Note: "updates" (plural) routes to changelog display. "update" (singular) routes to update check. Both are handled by the version action.

Content Signals (→ Capture Requests)

These signal "add a new task":

• Descriptive text beyond a single verb
• Feature requests, bug reports, ideas
• Screenshots or context
• "add", "create", "I need", "we should"

Examples

Help Menu (bare invocation)

When invoked with no arguments (do work), show a help menu with available actions and example prompts:

do-work — task queue for agentic coding tools

  Capture requests:
    do work add dark mode to settings
    do work the search is slow and the header is misaligned
    do work [paste meeting notes, specs, or a screenshot]

  Process the queue:
    do work run

  Verify & review:
    do work verify requests     Check capture quality against original input
    do work review work         Review completed work (requirements + code + acceptance)

  Present to client:
    do work present work        Generate client brief, architecture, video, and interactive HTML explainer
    do work present all         Portfolio summary of all completed work

  Other actions:
    do work clarify             Answer pending questions from completed work
    do work cleanup             Consolidate the archive
    do work commit              Analyze and commit uncommitted files atomically
    do work version             Check version / updates
    do work changelog           Show release notes

Do not ask "Start the work loop?" — just print the help menu and wait.

Routes to Work

• do work run → Starts work action immediately
• do work go → Starts work action immediately

Routes to Clarify Questions

• do work clarify → Presents all pending-answers REQs for batch review
• do work questions → Same as clarify
• do work answers → Same as clarify
• do work pending → Same as clarify
• do work what's blocked → Same as clarify

Routes to Verify Requests

• do work verify requests → Evaluates most recent UR's REQs
• do work verify → Evaluates most recent UR's REQs
• do work verify UR-003 → Evaluates specific UR
• do work check REQ-018 → Evaluates the UR that REQ-018 belongs to
• do work evaluate → Evaluates most recent UR's REQs
• do work review requests → Evaluates most recent UR's REQs

Routes to Review Work

• do work review work → Reviews the most recently completed REQ
• do work review → Reviews the most recently completed REQ
• do work review REQ-005 → Reviews a specific completed REQ
• do work review UR-003 → Reviews all completed REQs under that UR
• do work code review → Reviews the most recently completed REQ
• do work review code → Reviews the most recently completed REQ

Routes to Present Work

• do work present work → Generates deliverables for most recently completed UR
• do work present → Same as present work
• do work present UR-003 → Generates deliverables for specific UR
• do work present REQ-005 → Generates deliverables for specific REQ
• do work present all → Portfolio summary of all completed work
• do work present portfolio → Same as present all
• do work showcase → Same as present work

Routes to Cleanup

• do work cleanup → Consolidates archive, closes completed URs
• do work tidy → Same as cleanup
• do work consolidate → Same as cleanup

Routes to Commit

• do work commit → Analyzes and commits all uncommitted files atomically
• do work commit changes → Same as commit
• do work save work → Same as commit

Routes to Changelog (via Version)

• do work changelog → Displays changelog (newest at bottom)
• do work release notes → Same as changelog
• do work what's new → Same as changelog
• do work updates → Same as changelog
• do work history → Same as changelog

Routes to Capture Requests

• do work add dark mode → Creates REQ file + UR folder
• do work the button is broken → Creates REQ file + UR folder
• do work [400 words] → Creates REQ files + UR folder with full verbatim input

Payload Preservation Rules

When clarification is needed but content was provided:

1. Do not lose $ARGUMENTS - keep the full payload in context
2. Ask a simple question: "Add this as a request, or start the work loop?"
3. Accept minimal replies: User says just "add" or "work"
4. Proceed with original content: Apply the chosen action to the stored arguments
5. Never ask the user to re-paste content

This enables a two-phase commit pattern:

1. Capture intent payload
2. Confirm action

Action Dispatch

Each action has an action file with full instructions. How you execute it depends on your environment's capabilities.

Action	Action file	Context to pass
capture requests	./actions/capture.md	Full user input text
work	./actions/work.md	(none needed)
clarify questions	./actions/work.md	mode: clarify
verify requests	./actions/verify-requests.md	Target UR/REQ or "most recent"
review work	./actions/review-work.md	Target REQ/UR or "most recent"
present work	./actions/present-work.md	Target REQ/UR, "most recent", or "all"
cleanup	./actions/cleanup.md	(none needed)
commit	./actions/commit.md	(none needed)
version	./actions/version.md	$ARGUMENTS

If subagents are available

Dispatch each action to a subagent. The subagent reads the action file and executes it — the main thread only sees the routing decision and the returned summary.

• work and cleanup: Run in the background if your environment supports it. Print a status line (e.g., "Work queue processing in background...") and return control to the user immediately.
• capture requests, clarify questions, verify requests, review work, present work, version: Run in the foreground (blocking). These need user interaction or produce small immediate output.
• Screenshots (capture requests only): Subagents can't see images from the main conversation. Before dispatching, save screenshots to do-work/user-requests/.pending-assets/screenshot-{n}.png, write a text description of each, and include the paths + descriptions in the subagent prompt.

If subagents are not available

Read the action file directly and follow its instructions in the current session. The action files are designed to work as standalone prompts — no subagent infrastructure required.

On failure

Report the error to the user. Do not retry automatically.

Suggest Next Steps

After every action completes, suggest the next logical prompts the user might want to run. Use fully qualified action names so the user can copy-paste directly.

After capture requests:

Next steps:
  do work verify requests     Check capture quality before building
  do work run                 Start processing the queue

After work (queue processing):

Next steps:
  do work review work         Review the completed work
  do work present work        Generate client-facing deliverables
  do work clarify             Answer any pending questions

After verify requests:

Next steps:
  do work run                 Start processing the queue
  do work [describe changes]  Capture additional requests

After review work:

Next steps:
  do work present work        Generate client-facing deliverables
  do work run                 Process follow-up REQs (if any were created)
  do work [describe changes]  Capture new requests

After present work:

Next steps:
  do work present all         Generate portfolio summary (if multiple URs completed)
  do work [describe changes]  Capture new requests

After commit:

Next steps:
  do work review work         Review the committed changes
  do work [describe changes]  Capture new requests

After clarify questions:

Next steps:
  do work run                 Process answered questions
  do work clarify             Continue answering (if skipped any)

Rules:

• Only suggest prompts that provide value given the current state (e.g., don't suggest do work run if the queue is empty)
• Use the full action name (verify requests, not just verify; review work, not just review)
• Keep it to 2-3 suggestions max — don't overwhelm
• Format as a simple list the user can scan and copy