Timebox Evolver

Execute timeboxed work without idle waiting. Drive decisions by remaining time and evidence.

Core intent

• Enforce a real time budget.
• Preserve agent autonomy in how work is done.
• Avoid passive waiting.
• Produce auditable evidence and an actionable stop state.

Execution protocol

1. Start run with timebox_run.py to create run.start and capture policy.
2. Work in iterative cycles. A cycle is flexible, but should usually include:
   • round.plan
   • one or more execution events (round.impl, round.test, analysis.note, artifact.update, progress.update)
   • round.self_check
   • round.next_plan
   • round.end
3. At each policy checkpoint (or when uncertain), call timebox_status.py and choose one action:
   • execute_next_round (insufficient progress, continue depth)
   • close_open_loops (stabilize and verify)
   • finalize_and_end (ship result and stop)
4. Never idle-wait for the clock. If blocked, switch to highest-value fallback (verification, docs, handoff, risk list, next-step plan).
5. End run with timebox_end.py to write deterministic worked_seconds and stop_ts.
6. Validate with timebox_validate.py. If validation fails, do not claim completion.
7. Classify and adapt policy from historical runs.
8. For parallel decomposition, spawn child runs with inherited root_run_id/run_group_id, then join and group-validate before final report.
9. Keep outputs under output_root; validation fails on paths outside whitelist.

Time-aware decision rules

• Early phase (<40% elapsed): maximize useful work and reduce unknowns.
• Mid phase (40%-80% elapsed): converge, verify, cut low-value branches.
• Late phase (>80% elapsed): prioritize shipping and clean handoff.
• If remaining time is short and goal is unfinished, stop with explicit residual scope and next action.

Task-type adaptation

Task type is auto-classified (research, coding, writing, analysis, ops, general) and policy overrides can be loaded from timebox.config.json.

Use different evidence emphasis per task type:

• Research: source notes, synthesis, confidence gaps.
• Coding: diffs, tests, regression risk.
• Writing: draft delta, quality checks, unresolved edits.
• Analysis: assumptions, metrics, decision boundaries.
• Ops: runbook steps, validation outputs, rollback notes.

Commands

# Start one run
python3 skills/timebox-evolver/scripts/timebox_run.py \
  --task "Implement feature X" \
  --minutes 25 \
  --workdir /home/openclaw/.openclaw/workspace \
  --logdir /home/openclaw/.openclaw/workspace/memory/timebox-runs

# Append event evidence
python3 skills/timebox-evolver/scripts/timebox_log_event.py <run_log> round.plan '{"goal":"define scope"}'
python3 skills/timebox-evolver/scripts/timebox_log_event.py <run_log> round.impl '{"change":"implemented parser"}'
python3 skills/timebox-evolver/scripts/timebox_log_event.py <run_log> round.self_check '{"summary":"tests green"}'
python3 skills/timebox-evolver/scripts/timebox_log_event.py <run_log> round.next_plan '{"next":"add edge cases"}'
python3 skills/timebox-evolver/scripts/timebox_log_event.py <run_log> round.end '{}'

# Check status and next action suggestion
python3 skills/timebox-evolver/scripts/timebox_status.py <run_log> --json

# End run
python3 skills/timebox-evolver/scripts/timebox_end.py <run_log> \
  --summary "Delivered parser + tests; pending perf tuning" \
  --blocker none

# Validate
python3 skills/timebox-evolver/scripts/timebox_validate.py <run_log>

# Classify quality
python3 skills/timebox-evolver/scripts/timebox_classify.py <run_log>

# Adapt policy from recent runs
python3 skills/timebox-evolver/scripts/timebox_adapt.py \
  --dir /home/openclaw/.openclaw/workspace/memory/timebox-runs \
  --limit 20 --write-config

# Openclaw bridge (single entrypoint)
python3 skills/timebox-evolver/scripts/timebox_bootstrap.py --create-dirs --write-config
python3 skills/timebox-evolver/scripts/timebox_preflight.py --env-file ./.timebox-openclaw.env --smoke-test
python3 skills/timebox-evolver/scripts/timebox_job_driver.py start --task "Implement feature X" --minutes 25
python3 skills/timebox-evolver/scripts/timebox_job_driver.py tick --run-log <run_log>
python3 skills/timebox-evolver/scripts/timebox_job_driver.py budget --parent-run-log <run_log>
python3 skills/timebox-evolver/scripts/timebox_job_driver.py spawn --parent-run-log <run_log> --task "subtask Y"
python3 skills/timebox-evolver/scripts/timebox_job_driver.py join --run-log <child_run_log> --require-ended --validate
python3 skills/timebox-evolver/scripts/timebox_job_driver.py validate-group --run-log <run_log> --allow-cancelled --require-all-ended
python3 skills/timebox-evolver/scripts/timebox_job_driver.py collect --run-log <run_log> --format markdown --output <collect.md>
python3 skills/timebox-evolver/scripts/timebox_job_driver.py end --run-log <run_log> --summary "what was delivered" --validate --if-open
python3 skills/timebox-evolver/scripts/timebox_job_driver.py adapt --logdir /home/openclaw/.openclaw/workspace/memory/timebox-runs --limit 20 --write-config
python3 skills/timebox-evolver/scripts/timebox_job_driver.py recover --logdir /home/openclaw/.openclaw/workspace/memory/timebox-runs --stale-seconds 900 --limit 50

Openclaw integration template

For copy-ready scheduler hooks, use:

• references/openclaw-integration-template.md
• The bridge supports --env-file plus environment-variable fallbacks (JOB_TASK, JOB_MINUTES, RUN_LOG, JOB_SUMMARY).
• When parsing run-log outputs programmatically, prefer *_JSON keys (RUN_LOG_JSON, EXPORT_RUN_LOG_JSON, EXPORT_CHILD_RUN_LOG_JSON) for encoding-safe paths.
• start auto-recovers stale unfinished runs by default (can be disabled via TIMEBOX_AUTO_RECOVER=false).
• SubAgent defaults are env-driven (TIMEBOX_CHILD_RESERVE_SECONDS, TIMEBOX_CHILD_MIN_BUDGET_SECONDS, TIMEBOX_SEARCH_ROOT).
• Optional convenience wrapper: timebox_pipeline.py (init/begin/check/finish/maintain/budget/spawn/join/cancel/group-validate/collect), while all low-level commands remain available.

Required reporting

Always report:

• worked_seconds
• rounds
• key deliverables (diff/tests/docs/findings)
• unfinished scope and next concrete step
• policy adjustment suggestion for next run