plandesk-timebox
Paces a long run in fixed intervals over a work list: works items until the interval expires, verifies what actually completed, reports at every boundary, and starts the next interval while work remains. Chain it onto another skill ("/plandesk-timebox 25m /plandesk-foreman next") or run it over a list. Use when asked to timebox, pomodoro, work in sprints or intervals, check in every N minutes, or report progress on a schedule.
- License 许可
- MIT
- 最近更新
- 2026-10-04
- Stars
- ★ 16
- Forks
- 1
01 前言 Front Matter
- name
- plandesk-timebox
- description
- Paces a long run in fixed intervals over a work list: works items until the interval expires, verifies what actually completed, reports at every boundary, and starts the next interval while work remains. Chain it onto another skill ("/plandesk-timebox 25m /plandesk-foreman next") or run it over a list. Use when asked to timebox, pomodoro, work in sprints or intervals, check in every N minutes, or report progress on a schedule.
- argument-hint
- [<interval, e.g. 25m>] [<a skill invocation, or a list of work items>]
- user-invocable
- true
03 SKILL.md 正文
Work in timeboxes
A pacing posture, not a task. It wraps a run in fixed intervals so a long session surfaces on a cadence instead of disappearing for an hour and coming back with a wall of diff.
The work list is yours, not the board's. Timebox drives what you handed it — a list of things you want done, in the order you want them. It can be pointed at the board when you ask for that explicitly, but it never goes shopping for work on its own.
How to chain it
/plandesk-timebox 25m /plandesk-foreman next # a box per board item
/plandesk-timebox 50m # bare: paces the list you give it
/plandesk-timebox 25m clear the board # explicit opt-in to board-driven work
/plandesk-autonomy /plandesk-timebox 25m /plandesk-foreman next
# no permission pauses, plus a surfacing cadence
Stacking with autonomy is the common pairing and the two do different jobs: autonomy removes the pause between steps, timebox adds a rhythm and a report. Neither grants a permission the wrapped skill didn't already have.
Harness primitives — use what the runtime gives you
Timebox is harness-neutral. Prefer the scheduler and shell tools your runtime exposes; fall back to the portable stamp when it does not. Never poll — do not schedule short wakeups to check on background work the dispatch monitor already watches; that is wasted work (heartbeat.md).
| capability | Cursor | Claude Code | Codex | Pi | OpenCode |
|---|---|---|---|---|---|
| work-list scratchpad | TaskCreate / TaskList / TaskUpdate |
same harness task tools | .agents/factory/runs/tasks-<task>.md |
TaskCreate (pi-loop fallback) or pi-tasks |
session notes / plugin tasks |
| background command | Shell run_in_background + Await |
Bash run_in_background |
background flag if present | MonitorCreate (pi-loop) |
/background (monitor plugin) |
| one-shot resume | backgrounded sleep sentinel (see Cursor specifics) |
ScheduleWakeup |
— (use external cron) | schedule_loop_wakeup / LoopCreate (extensions) |
ScheduleWakeup (opencode-routines) |
| recurring loop | — | /loop + ScheduleWakeup |
.codex/automations/*.toml |
LoopCreate / /loop (pi-loop) |
LoopCreate / /loop (routines plugin) |
| portable clock | date +%s at item boundaries |
same | same | same | same |
Common pattern that works everywhere:
- List on the harness —
TaskCreateone task per work item (lead session) or.agents/factory/runs/tasks-<task>.md(delegated worker). Add a meta tasktimebox:stateholding box number,box_startepoch, and interval seconds. - Clock at boundaries — after each item, read elapsed with
date +%sagainstbox_start. This is the universal fallback and always binds. - Scheduler when present — if the runtime exposes
ScheduleWakeup(or Pi / OpenCode loop tools), use it only to resume this run across turns after a checkpoint — not to re-fire an expensive slash command verbatim. - Background through the harness — dispatch workers with
run_in_background(never&/nohup); completion is the result file (.agents/factory/runs/result-<task>.json), watched by the monitor armed at dispatch —Awaitthe monitor shell, and treat the harness's own exit notification as a hint only. See protocol.md.
Cursor specifics. There is no scheduler tool, but there is a working box timer: at each box start, background a sentinel shell —
sleep {interval_seconds} && echo "TIMEBOX: box {n} boundary"
— with run_in_background (block_until_ms 0). Its completion notification is
delivered even after your turn ends and resumes the run, so a box boundary
can wake you instead of relying on you noticing the stamp. This is the
documented sleep-and-echo self-notification pattern, not polling: one shell
per box, armed once, disarmed (kill the pid) when the list empties early. The
date +%s stamp at item boundaries stays the authority on whether the box has
actually expired — the sentinel is the wakeup, not the clock.
Claude Code specifics. ScheduleWakeup clamps delaySeconds to 60–3600.
Pass a plain continuation prompt ("Continue timebox box 3; pick up item X from
TaskList"), never a /-prefixed slash command — re-firing those duplicates
expensive work. End the loop with stop: true when the list is empty. Foreground
sleep for the full interval is blocked; use the scheduler or keep working and
check the stamp at item boundaries.
Codex specifics. No in-session scheduler in mainline Codex today. Pace with
date +%s inside the session, or stand up .codex/automations/*.toml /
external cron for durable recurring runs outside this skill.
Pi / OpenCode specifics. Loop extensions (pi-loop, opencode-routines)
are the richest schedulers — prefer fixed-interval LoopCreate over self-paced
re-scheduling when you want a predictable pomodoro cadence. Coalesced delivery
while busy is correct: the box boundary fires when the in-flight item finishes.
Set up the run
- Get the work list. Ask for it if it wasn't given: a list of items, a file
to work through, or a scope of changes. Write it down as harness tasks
(
TaskCreate) — one per item, plustimebox:state(box number, start epoch, interval). If the user said "clear the board" or named the board explicitly, the list isget_next_task— but only then. - Set the interval. Default 25 minutes when unspecified. Parse user input:
25m,1h,90 minutes→ seconds once at setup. "Work for an hour" means one 60-minute box, not three of twenty. - Stamp the clock.
Ifdate +%s # box_start; persist in timebox:state and/or TaskUpdate metadataScheduleWakeup/ loop tools are available and the run may span multiple turns, also recordbox_end = box_start + interval_secondsso the wakeup prompt knows which box to report. - Say the plan back in one line: the interval, the item count, and what happens at the first boundary. A run nobody can predict is a run nobody can interrupt at a good moment.
The cycle
box_start = read from timebox:state (or date +%s on first box)
arm the box timer if the harness has one # Cursor: sentinel sleep; Claude: ScheduleWakeup
loop:
item = next pending harness task (skip timebox:state)
if item is null:
stop — the list is done; final report; disarm timer / ScheduleWakeup stop
work(item) # the wrapped skill's own procedure, in full
verify(item) # its own completion check — exit codes, not claims
TaskUpdate(item, completed) # or mark Done in .agents/factory/runs/tasks-*.md
commit/checkpoint(item) # leave nothing half-applied
if (date +%s) - box_start >= interval_seconds:
checkpoint_report() # see the template below — then KEEP GOING
increment box number in timebox:state
box_start = date +%s
re-arm the box timer for the new box
continue loop # same turn — the report is not a turn boundary
Inside a box with a background dispatch: background the worker per
protocol.md, keep working on what you can in the
foreground, and Await (or watch .agents/factory/runs/result-<task>.json) for completion —
do not schedule timer polls for it. The box timer and the worker timer are
independent; an expiring box still lets the in-flight item finish first.
The boundary rule — the timer is a checkpoint, not a kill signal
When the interval expires mid-item, let the item finish. Then verify, commit, mark the harness task complete, and only then checkpoint.
This is the whole design decision, and the reason is concrete: cutting a run mid-item strands work in exactly the state that is hardest to recover — a worker part-way through a change, nothing staged, nothing verified, and a report that cannot honestly say what landed. A box that runs four minutes long costs four minutes. A box that cuts clean through a dispatch costs the item.
So the interval governs how often you surface, never where the work stops. If an item is so large that it routinely blows the box, that is a sizing problem — say so at the checkpoint and suggest splitting it, rather than shrinking the box until it cuts.
The checkpoint report
At each boundary, keep it short enough to read on a phone:
Box N (25m) — 3 items, 2 done, 1 carried
done <item> — <what proves it: command + exit code>
done <item> — <proof>
carried <item> — <where it stands, what is next>
Next box: <what it will pick up>. Remaining: <count>.
Report what is proven, not what was attempted. An item without a verification
result is carried, not done — this is the check the interval exists to
force, and reporting an unverified item as done makes every later box's report
worthless.
Then continue into the next box in the same turn — do not end your turn after a checkpoint. Ending the turn is how a run silently converts a report into a permission request: in a harness with no scheduler, nothing wakes you, and the run dies with "say continue for box 3" — which is exactly the pause the wrapper was invoked to remove. Never write "say continue", "shall I proceed", or any variant; the only legitimate turn-enders are the stop conditions below. The checkpoint is a surfacing moment, not a permission request: the human reads it if they are there and interrupts if they want to — interruption is their affordance, not something you solicit. Lane gates still bind — see lanes.md and autonomy.
Breaks
After four boxes, take a longer checkpoint: re-read the work list (TaskList or
.agents/factory/runs/tasks-*.md) against what actually landed, drop items that are now moot,
and say whether the remaining list still matches what the user wanted. Long runs
drift — the plan made sense ninety minutes ago and the fourth box is where that
is worth checking.
This is the agent's version of the pomodoro break. It is not idle time; it is the moment the list gets re-derived from reality rather than from memory.
When to stop instead of starting another box
- The list is empty. Report and end — do not go looking for adjacent work. Disarm
any loop /
ScheduleWakeupwithstop: trueorLoopDelete. - Every remaining item is blocked, or gated on input you cannot obtain. Report what is blocking and on whom.
- Two consecutive boxes closed nothing. Something is wrong with the sizing, the environment, or the plan; another box will not fix it. Say what you observed and stop.
- The user asked for a fixed number of boxes and you have finished them.
Gotchas
- Timeboxing paces work; it does not authorize any. A wrapped skill's lane gates and boundaries bind unchanged — see autonomy.
date +%salways works; schedulers are optional. Do not fail to timebox becauseScheduleWakeupis absent — the stamp at item boundaries is the portable core.- Never poll background work on a timer. The dispatch monitor watches the result file and reports completion (protocol.md); heartbeat wakeups are for stall detection only (heartbeat.md).
- The clock is read at boundaries, so it is only as granular as your items. One 90-minute item inside a 25-minute box produces one box, not four — that is correct behavior, and the checkpoint should name it as a sizing problem.
- Do not let the box become a deadline the work is rushed to fit. Skipping verification to land inside the interval defeats the entire point; the box is a reporting rhythm, not a budget.
- A checkpoint is not a turn boundary. If you catch yourself typing "say continue" or "ready for box N?", delete it and start the next item — the human interrupts when they want to; you never solicit it.
- Harness tasks are the per-session scratchpad for the list. If the run is board-driven, the board stays the source of truth and the harness list is re-derived from it after any compaction.
References
autonomy (the posture this most often stacks with);
foreman (the usual inner skill);
protocol.md (background dispatch + stall detection);
heartbeat.md (why not to poll);
lanes.md (gates a checkpoint never overrides);
.agents/factory/hooks/ (board re-anchor after compaction — re-read TaskList).
04 同仓库更多 Skills
connecting-agents
Agent conventions for Plan Desk MCP — task labels, docs, notes, files, artifacts, sharing, edges, and agent runs.
.plandesk
暂无简介
plandesk
暂无简介
plandesk-timebox
暂无简介
plandesk-standup
暂无简介
plandesk-standdown
暂无简介