do - SKILL.md Agent Skill

name: do disable-model-invocation: true argument-hint: " [worktree] [push] [pr] [every SCHEDULE] [now] | stop [query] | next [query] | now [query]" description: >- Lightweight task dispatcher for ad-hoc work: documentation, examples, refactoring, content updates. Supports scheduling with every/now/next/stop. Usage: /do [worktree] [push] [pr] [every SCHEDULE] [now] | stop | next.

/do <description> [worktree] [push] [pr] [every SCHEDULE] | stop [query] | next [query] | now [query] — Lightweight Task Dispatcher

Execute small, ad-hoc tasks with structured research, verification, and optional isolation or auto-push. Can be scheduled for recurring maintenance tasks. For work that doesn't warrant the full ceremony of /run-plan (plan phases) or /fix-issues (batch bug fixing).

Ultrathink throughout.

When to Use `/do`

Task	Use
Documentation, examples, presentations, screenshots	`/do`
Small refactors, one-off fixes, content updates	`/do`
Adding a new block type	`/add-block` (10-step workflow)
Newsletter entry	`/do` or `/doc newsletter`
Batch bug fixing (N issues)	`/fix-issues N`
Executing a plan phase	`/run-plan`
Multi-file feature work with dependencies	`/run-plan`

Rule of thumb: if the task needs a worktree, separate verification agent, and a persistent report file, it's too big for /do. Use /run-plan instead.

Arguments

/do <description> [worktree] [push] [pr] [every SCHEDULE] [now]
/do stop | next

description (required) — what to do, in natural language
worktree (optional) — isolate work in a named worktree at /tmp/<project>-do-<slug>/ for riskier or larger tasks. Without this flag, work happens directly on main.
push (optional) — auto-push to remote after verification passes. Upgrades verification to use a separate verification agent running /verify-changes. Push never happens without verification passing first.
pr (optional) — work in a named worktree on a named branch, then push and create a PR to main. Dispatches an implementation agent to do the work, waits for completion, rebases onto latest main, pushes, creates PR, and polls CI (report only).
every SCHEDULE (optional) — self-schedule recurring runs via cron:
- Accepts intervals: 4h, 2h, 30m, 12h
- Accepts time-of-day: day at 9am, day at 14:00, weekday at 9am
- Without now: schedules only, does NOT run immediately
- With now: schedules AND runs immediately
- Each run re-registers the cron (self-perpetuating)
- Cron is session-scoped — dies when the session dies
now (optional) — run immediately. When combined with every, runs immediately AND schedules. Without every, now is the default behavior.
stop — cancel /do cron(s). Bare /do stop → all crons. With query /do stop Check docs → targets matching cron.
next — check next fire time. Bare → all. With query → targeted.

Detection: If $ARGUMENTS starts with a quoted string ("..."), the quoted text is the description — skip meta-command detection entirely. This lets users escape edge cases like /do "Now fix the tooltip bug".

Otherwise, check the first word of $ARGUMENTS:

stop [query] — meta-command: cancel crons. Bare → all. With query → targeted.
next [query] — meta-command: show fire times. Bare → all. With query → targeted.
now [query] — meta-command: trigger immediately. Bare → all/ask. With query → targeted.

If the first word is NOT a meta-command, it's a regular task. Parse trailing flags from the END backward:

push — recognized at the end
worktree — recognized at the end
pr — recognized at the end (use extended pattern with .!? punctuation, since task descriptions are prose-like and "pr" may appear as "PR." at end of sentence)
every <schedule> — recognized at the end (e.g., every 4h, every day at 9am)
now — recognized at the end (only meaningful with every: run now AND schedule)

PR flag detection pattern (use extended .!? punctuation):

LANDING_MODE="default"
if [[ "$REMAINING" =~ (^|[[:space:]])[pP][rR]($|[[:space:]]|[.!?]) ]]; then
  LANDING_MODE="pr"
fi

Everything before the trailing flags is the task description.

This means:

/do stop — stop all /do crons
/do stop Check docs — stop the "Check docs" cron
/do next — show all fire times
/do next Check docs — show fire time for "Check docs"
/do now — trigger (if one) or ask (if multiple)
/do now Check docs — trigger the "Check docs" cron
/do Push the latest changes — description only, no flags
/do Update the presentation push — description + push flag
/do Fix the tooltip bug worktree push — description + both flags
/do Check docs every day at 9am — schedule "Check docs" daily
/do Add dark mode. pr — description + pr flag (PR mode)

Examples:

/do Add example models for Integrator and Derivative blocks
/do Sort the screenshots in session-sequence-snapshots
/do Refactor color constants in main.css worktree
/do Update the presentation with Phase 3 results push
/do Make sure docs are up to date every day at 9am
/do Check for broken links in examples every 12h now
/do Add dark mode to editor pr
/do next — all scheduled tasks
/do next Check docs — specific task
/do stop — cancel all
/do stop Check docs — cancel specific task

Meta-Commands: stop / next / now

These commands query or control /do crons. They work in two modes:

Bare (/do stop, /do next, /do now) — applies to ALL /do crons
Targeted (/do stop Check docs, /do next Check docs) — applies to the matching cron

Cron Matching (for targeted commands)

When a description is present with stop/next/now, find the matching cron by comparing the description against all /do cron prompts:

CronList → find all whose prompt starts with Run /do
Extract each cron's task description (strip Run /do prefix and trailing flags)
Fuzzy match: check if the user's description words appear in the cron's description (case-insensitive, order-independent). E.g., "Check docs" matches "Make sure docs are up to date" because both key words overlap. The user won't have tons of similar /do crons, so loose matching is fine.
One match → act on it. Multiple matches → list them, ask which one. No matches → report "no matching /do cron found."

Now

CronList → find /do crons (all, or matching if description given)
One cron: extract prompt, run immediately. Cron stays active.
Multiple (bare only): list them, ask which to trigger.
None: report No active /do cron to trigger. and exit.

CronList → find /do crons (all, or matching if description given)
For each, parse the cron expression and compute the next fire time. Use TZ=America/New_York date for the timezone. Show both relative and absolute:
Active /do crons:
1. ~~14h 47m (~~9:03 AM ET tomorrow, cron XXXX) Prompt: Run /do Make sure docs are up to date every day at 9am now
2. ~~3h 12m (~~8:15 PM ET, cron YYYY) Prompt: Run /do Check broken links every 4h now
None: No active /do cron in this session.
Exit.

Stop

CronList → find /do crons (all, or matching if description given)
Bare with one cron: delete it. Report what was cancelled.
Bare with multiple: list them, ask which to cancel (or "all").
Targeted: delete the matched cron. Report what was cancelled.
None: report "no active /do cron found."
Exit.

Phase 0 — Schedule (if `every` is present)

If $ARGUMENTS contains every <schedule>:

Parse the schedule — convert to a cron expression.

For interval-based schedules (4h, 12h): use the CURRENT minute as the offset so the first fire is a full interval from now. Check with date +%M:
- 4h at minute 9 → 9 */4 * * *
For time-of-day schedules: offset round minutes by a few:
- day at 9am → 3 9 * * *
- weekday at 9am → 3 9 * * 1-5
Deduplicate — CronList and check for existing /do crons. Extract the task description from each cron's prompt by stripping Run /do prefix and trailing flags (every, now, worktree, push).
- If an existing cron's extracted description exactly matches (case- insensitive) the new task's description, replace it (CronDelete + recreate). This is a re-registration of the same task.
- Otherwise, keep it — the user has multiple crons for different tasks.
- During an unattended cron fire (the invocation itself came from a cron), never ask the user — default to keeping both. During an interactive invocation, if descriptions are similar but not exact, list existing crons and ask: "Replace this one, or keep both?"
Construct the cron prompt. Always include now in the cron prompt so each cron fire runs immediately AND re-registers itself. Note: this now is for the CRON's invocation, not the current invocation:
```
Run /do <description> [worktree] [push] every <schedule> now
```
Create the cron — CronCreate with recurring: true.
Confirm with wall-clock time.
If now is present: proceed to Phase 1. If now is NOT present: Exit. The cron fires later.

If every is NOT present, skip this phase (bare invocation runs immediately).

Phase 1 — Understand & Research

Before touching anything:

Parse the task description — what is being asked? What files are involved? What's the expected outcome?
Identify relevant files and current state:
- Search for files related to the task (Glob, Grep)
- Read existing content that will be modified
- Check for related skills, conventions, or guidelines (e.g., model design rules for example models, newsletter format for entries)
Classify the change type — this determines verification intensity in Phase 3:
- Content only — markdown, images, presentations, documentation. No tests needed.
- Code — JavaScript, CSS, HTML, model files. Tests needed.
- Mixed — both content and code. Tests needed for code portion.
Plan the work — no formal document, just mental clarity on what to do and in what order. If the task is bigger than expected (would take 1000+ lines of changes, has complex dependencies), suggest /run-plan instead and ask the user.

Phase 1.5 — Argument Parsing (always before Phase 1 research)

Before any research or execution, parse flags from $ARGUMENTS.

Step 1: Check for pr flag (trailing, using extended punctuation pattern):

REMAINING="$ARGUMENTS"
LANDING_MODE="default"
if [[ "$REMAINING" =~ (^|[[:space:]])[pP][rR]($|[[:space:]]|[.!?]) ]]; then
  LANDING_MODE="pr"
  # Strip the pr token from description
  TASK_DESCRIPTION=$(echo "$REMAINING" | sed -E 's/(^|[[:space:]])[pP][rR]($|[[:space:]]|[.!?])/ /')
  TASK_DESCRIPTION=$(echo "$TASK_DESCRIPTION" | sed -E 's/^[[:space:]]+//;s/[[:space:]]+$//')
  if [ -z "$TASK_DESCRIPTION" ]; then
    echo "ERROR: Task description required. Usage: /do <task description> pr"
    exit 1
  fi
fi

If LANDING_MODE is not pr, then TASK_DESCRIPTION is the full $ARGUMENTS minus the other trailing flags (push, worktree, every ..., now).

Step 2: Check for worktree flag (trailing, plain word match):

if [[ "$REMAINING" =~ (^|[[:space:]])worktree($|[[:space:]]) ]]; then
  USE_WORKTREE=true
fi

Step 3: Check for push flag (trailing):

if [[ "$REMAINING" =~ (^|[[:space:]])push($|[[:space:]]) ]]; then
  USE_PUSH=true
fi

pr takes precedence: if LANDING_MODE="pr", ignore worktree and push flags.

Phase 2 — Execute

Choose execution path based on parsed flags:

Path A: PR mode (`pr` flag)

This path replaces the normal Phase 2–5 flow entirely. After the PR is created, skip to Phase 5 Report.

Step A1 — Compute task slug:

# N = min(4, word_count) words from TASK_DESCRIPTION
WORD_COUNT=$(echo "$TASK_DESCRIPTION" | wc -w)
N=$(( WORD_COUNT < 4 ? WORD_COUNT : 4 ))
TASK_SLUG=$(echo "$TASK_DESCRIPTION" | awk "{for(i=1;i<=$N;i++) printf \$i\"-\"; print \"\"}" \
  | sed -E 's/[^a-zA-Z0-9]+/-/g; s/-+/-/g; s/^-//; s/-$//' \
  | tr '[:upper:]' '[:lower:]' \
  | cut -c1-30 \
  | sed 's/-$//')

Step A2 — Collision check (BEFORE deriving BRANCH_NAME or WORKTREE_PATH):

PROJECT_NAME=$(basename "$(git rev-parse --show-toplevel)")
if [ -d "/tmp/${PROJECT_NAME}-do-${TASK_SLUG}" ]; then
  TASK_SLUG="${TASK_SLUG}-$(date +%s | tail -c 5)"
fi

Step A3 — Derive BRANCH_NAME and WORKTREE_PATH from (possibly suffixed) TASK_SLUG:

BRANCH_PREFIX=$(jq -r '.execution.branch_prefix // "feat/"' .claude/zskills-config.json 2>/dev/null || echo "feat/")
BRANCH_NAME="${BRANCH_PREFIX}do-${TASK_SLUG}"
WORKTREE_PATH="/tmp/${PROJECT_NAME}-do-${TASK_SLUG}"

Step A4 — ff-merge main + worktree creation:

git fetch origin main 2>/dev/null || true
git merge --ff-only origin/main 2>/dev/null \
  || echo "WARNING: local main not fast-forwarded — worktree uses local main as-is"
git worktree prune
git worktree add -b "$BRANCH_NAME" "$WORKTREE_PATH" main 2>/dev/null \
  || git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"

Step A5 — Write tracking marker immediately after worktree creation:

PIPELINE_ID="do.${TASK_SLUG}"
echo "$PIPELINE_ID" > "$WORKTREE_PATH/.zskills-tracked"

Do NOT echo ZSKILLS_PIPELINE_ID=do.${TASK_SLUG} in the main session — write only to the worktree file.

Step A6 — Dispatch implementation agent (wait for completion):

Before dispatching: Check agents.min_model in .claude/zskills-config.json. If set, use that model or higher (ordinal: haiku=1 < sonnet=2 < opus=3). Never dispatch with a lower-ordinal model than the configured minimum.

Dispatch an Agent (without isolation: "worktree" — the worktree already exists) with this prompt:

You are implementing: $TASK_DESCRIPTION

FIRST: cd $WORKTREE_PATH
All work happens in that directory. Do NOT work in any other directory.
You are on branch $BRANCH_NAME (already checked out in the worktree).

Implement the task. Commit changes when done:
- Stage files by name (not git add .)
- Do NOT commit to main
- Commit message should summarize what was implemented

Check agents.min_model in .claude/zskills-config.json before dispatching
any sub-agents. Use that model or higher (haiku=1 < sonnet=2 < opus=3).

Wait for the implementation agent to complete. If the agent reports failure or exits without committing:

cat > "$WORKTREE_PATH/.landed" <<LANDED
status: conflict
date: $(TZ=America/New_York date -Iseconds)
source: do
branch: $BRANCH_NAME
LANDED

Exit with error directing the user to inspect $WORKTREE_PATH.

Step A7 — Rebase + push + PR creation (after implementation agent completes):

cd "$WORKTREE_PATH"
# Rebase onto latest main before push
git fetch origin main
git rebase origin/main || { echo "ERROR: Rebase conflict. Resolve manually in $WORKTREE_PATH."; exit 1; }

git push -u origin "$BRANCH_NAME"

# PR body: explicit title and body, not --fill
PR_TITLE="do: $(echo "$TASK_DESCRIPTION" | cut -c1-60)"
PR_BODY="Task: ${TASK_DESCRIPTION}

Worktree: ${WORKTREE_PATH}
Commits: $(git log origin/main..HEAD --format='%h %s' | head -10)"

EXISTING_PR=$(gh pr list --head "$BRANCH_NAME" --json number --jq '.[0].number' 2>/dev/null)
if [ -n "$EXISTING_PR" ]; then
  PR_URL=$(gh pr view "$EXISTING_PR" --json url --jq '.url')
  echo "PR already exists: $PR_URL"
else
  PR_URL=$(gh pr create --base main --head "$BRANCH_NAME" \
    --title "$PR_TITLE" --body "$PR_BODY")
  echo "Created PR: $PR_URL"
fi

Step A8 — CI poll (report only, no fix cycle):

if [ -n "$PR_URL" ]; then
  PR_NUMBER=$(gh pr view "$PR_URL" --json number --jq '.number')
  CHECK_COUNT=0
  for _i in 1 2 3; do
    CHECK_COUNT=$(gh pr checks "$PR_NUMBER" --json name --jq 'length' 2>/dev/null || echo "0")
    [ "$CHECK_COUNT" != "0" ] && break
    sleep 10
  done
  CI_STATUS="none"
  if [ "$CHECK_COUNT" != "0" ]; then
    if timeout 600 gh pr checks "$PR_NUMBER" --watch 2>/dev/null; then
      CI_STATUS="passed"
      echo "CI checks passed."
    else
      CI_STATUS="failed"
      echo "CI checks failed. Inspect the PR to diagnose failures."
    fi
  fi
fi

Step A9 — Write .landed marker:

# Check if PR was auto-merged
PR_STATE=$(gh pr view "$PR_URL" --json state --jq '.state' 2>/dev/null || echo "OPEN")
if [ "$PR_STATE" = "MERGED" ]; then
  LANDED_STATUS="landed"
elif [ "$CI_STATUS" = "failed" ]; then
  LANDED_STATUS="pr-ci-failing"
else
  LANDED_STATUS="pr-ready"
fi

cat > "$WORKTREE_PATH/.landed" <<LANDED
status: $LANDED_STATUS
date: $(TZ=America/New_York date -Iseconds)
source: do
branch: $BRANCH_NAME
pr: $PR_URL
LANDED

After writing .landed, output the Phase 5 PR report and exit (skip Phases 3-4).

Path B: Worktree mode (`worktree` flag, no `pr`)

Create a named worktree at ../do-<slug>/ using manual git worktree add:

# Compute slug from task description
WORD_COUNT=$(echo "$TASK_DESCRIPTION" | wc -w)
N=$(( WORD_COUNT < 4 ? WORD_COUNT : 4 ))
TASK_SLUG=$(echo "$TASK_DESCRIPTION" | awk "{for(i=1;i<=$N;i++) printf \$i\"-\"; print \"\"}" \
  | sed -E 's/[^a-zA-Z0-9]+/-/g; s/-+/-/g; s/^-//; s/-$//' \
  | tr '[:upper:]' '[:lower:]' \
  | cut -c1-30 \
  | sed 's/-$//')
WORKTREE_PATH="../do-${TASK_SLUG}"
# Collision check
if [ -d "$WORKTREE_PATH" ]; then
  TASK_SLUG="${TASK_SLUG}-$(date +%s | tail -c 5)"
  WORKTREE_PATH="../do-${TASK_SLUG}"
fi
git worktree add "$WORKTREE_PATH"

Do the work inside the worktree. The verification agent commits after tests pass (one logical unit per commit).

Path C: Direct (default, no `pr`, no `worktree`)

Work directly on main.

Follow existing conventions in all paths:

Example models → /model-design skill guidelines
Newsletter entries → existing NEWSLETTER.md format
Documentation → existing doc style in the repo
Code → existing patterns in the codebase

Commit discipline (Paths B and C):

On main (Path C): commit when the work is complete. Clean, descriptive message. npm run test:all before committing if code was touched. If tests fail after two fix attempts on the same error, STOP — report what you tried and let the user decide.
In worktree (Path B): the verification agent commits after tests pass. One logical unit per commit.

Phase 3 — Verify

Verification intensity matches the change type (from Phase 1):

Content-only changes (md, jpg, png, presentations)

Spot-check: formatting, links, file organization, image references
Do NOT run tests — running 4,000+ tests for a markdown edit is wasteful, and pre-existing failures would block the task unnecessarily
If push is present: dispatch a separate verification agent. Tell the agent explicitly: "These are content-only changes (no code). Review the diff for correctness and completeness — do NOT run npm test or npm run test:all. Your job is: do these changes make sense? Are the right files included? Anything accidentally staged? Formatting correct?" Do NOT invoke /verify-changes for content-only pushes — it will run the full test suite regardless. Instead, dispatch a plain review agent.

Code changes (js, css, html)

Run npm run test:all — all suites must pass, not just unit tests.
If tests fail: fix them. Do not check if failures are pre-existing. Do not stash, checkout old commits, or create comparison worktrees. If you touched code and tests fail, they're yours to fix. (See CLAUDE.md: "NEVER modify the working tree to check if a failure is pre-existing.")
If push is present: dispatch a separate verification agent running /verify-changes. This is the full 7-phase verification: diff review, test coverage audit, npm run test:all, manual verification if UI, fix problems, re-verify until clean. Push only happens if this agent reports clean.

Mixed changes

Run tests for the code portion
Spot-check the content portion
If push: full /verify-changes via separate agent

Phase 4 — Push (if `push` flag present, Path C/B only)

Only reached if Phase 3 verification passed. Not applicable to PR mode (Path A — PR mode has its own push in Phase 2 Step A7).

If on main (Path C):
```
git push
```
If in worktree (Path B): cherry-pick to main first, then push:
- Protect uncommitted work on main (git stash -u if needed)
- Cherry-pick worktree commits to main sequentially
- If any cherry-pick conflicts: abort and clean up:
```
git cherry-pick --abort
```
  Restore stash if one was created (git stash pop). If /do has an active cron, kill it (CronList + CronDelete any whose prompt starts with Run /do). Report the conflict to the user. Do NOT force-push or resolve automatically.
- Restore stash if one was created
- Push main
- Report what was pushed (commit hashes, branch)
If verification failed: do NOT push. Report the verification findings and stop.

Phase 5 — Report

Brief inline output. No persistent report file.

On main (no worktree, no push):

Done. [1-2 sentence summary of what was done]
Changed: file1.js, file2.md (+N lines)
Committed: abc1234 — "commit message"

On main with push:

Done and pushed. [1-2 sentence summary]
Changed: file1.js, file2.md (+N lines)
Committed: abc1234 — "commit message"
Pushed to: origin/main
Verification: clean (npm run test:all passed, /verify-changes clean)

In worktree (no push):

Done. [1-2 sentence summary]
Worktree: ../do-<slug>/
Branch: do/<slug>
Commits: abc1234, def5678
To land: git cherry-pick abc1234 def5678
To discard: git worktree remove ../do-<slug>/

In worktree with push:

Done and pushed. [1-2 sentence summary]
Cherry-picked to main: abc1234, def5678
Pushed to: origin/main
Verification: clean (/verify-changes clean)
Worktree: ../do-<slug>/ (can be removed)

PR mode (pr flag):

Done. [1-2 sentence summary of what was implemented]
PR: <PR_URL>
Branch: <BRANCH_NAME>
Worktree: <WORKTREE_PATH>
CI: passed | failed | no checks
Status: pr-ready | pr-ci-failing | landed

Error Handling

Test failures (code changes): stop, fix the code, re-test. Never weaken tests. Never check if failures are pre-existing.
Content issues: stop, fix formatting/links/references, re-check.
Cherry-pick conflict (worktree + push): stop, report the conflict. Do not resolve automatically — conflicts need human judgment.
Push failure (auth, remote, etc.): stop, report the error.
Task is bigger than expected: stop, suggest /run-plan instead. Ask the user before continuing.
PR mode: rebase conflict: write .landed with status: conflict, report to user, direct them to inspect $WORKTREE_PATH.
PR mode: CI failure: write .landed with status: pr-ci-failing, report the failure. Do NOT dispatch fix agents.
PR mode: implementation agent fails without committing: write .landed with status: conflict and exit with an error message.
If stuck on anything: report the state and ask the user for guidance. Do not retry the same approach in a loop.

Key Rules

Match verification to change type — content-only tasks skip tests. Code tasks run tests. Push upgrades to full /verify-changes.
Never weaken tests — fix the code, not the test.
Never modify the working tree to check pre-existing failures — if you touched code and tests fail, fix them. No stash-and-compare, no checkout-old-commit, no comparison worktrees.
Protect other agents' work — do not commit unrelated changes that happen to be in the working tree. Stage only files related to the task.
Worktree naming (worktree flag) — use ../do-<slug>/ where <slug> is a short kebab-case description derived from the task (e.g., do-sort-screenshots, do-integrator-examples). Include a timestamp suffix if a worktree with that name already exists. Uses manual git worktree add — NOT isolation: "worktree".
Worktree naming (pr flag) — use /tmp/<project>-do-<slug>/ with a named branch <branch_prefix>do-<slug>. Both BRANCH_NAME and WORKTREE_PATH derive from TASK_SLUG (after any collision suffix).
No persistent report files — /do outputs results inline. It does NOT write SPRINT_REPORT.md, PLAN_REPORT.md, or any other report file. The commit is the artifact.
Push requires verification — push always dispatches a separate verification agent before pushing. No exceptions.
PR mode CI is report-only — /do pr polls CI and reports status. It does NOT dispatch fix agents. For automated fix cycles, use /run-plan or /fix-issues in PR mode.
PR body uses git log origin/main..HEAD — never git log main..HEAD (local main may be stale after rebase).
PR titles and bodies are explicit — never use --fill in gh pr create.
Slug collision suffix targets TASK_SLUG itself — not just WORKTREE_PATH. Both BRANCH_NAME and WORKTREE_PATH must pick up the suffix.
Respect CLAUDE.md — all standard rules apply (no external deps, no bundlers, no weakened tests, etc.)

do