tasks-execute
Skill4 starsChanged 41 days agoMITView on GitHub
Use when someone wants an agent to work through an ArchDev Tasks epic — pick ready tasks, lease each one, keep a lease heartbeat running the whole time, implement and verify, commit, push and open a pull request, close, and continue to the next task. Triggers include "work the epic", "execute these tasks", "pick up the next task", "run the plan", or /tasks-execute <epic>.
- Commits and pushes
In this repository6 other files it gives its agents.
- archdevSkill
- eval-reviewSkill
- plan-collabSkill
- shotsSkill
- tasks-auditSkill
- tasksSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
39 rules. About 0 are common, 24 are distinctive, and 15 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈24
Distinctive · estimate
This author's own choices. Worth a look.
15
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
Use the archdev CLI for every Tasks operation.
- Very specific: line 31
Follow the archdev skill for activity reporting.
- Very specific: line 55
If the archdev skill is installed, load it too.
- Distinctive: line 74
Read the repository's agent instructions (AGENTS.md, CLAUDE.md) before editing.
- Very specific: line 78
Write a small state file outside the checkout, for example ~/.archdev/task-execute/<epic-slug>.json (mkdir -p ~/.archdev/task-execute …
- Distinctive: line 93
Read it fully before claiming:
- Distinctive: line 102
If the task cannot be done as written (contradiction, missing access, a decision only a human can make), do not claim it.
- Very specific: line 117
Keep lease.lease_id, lease.session_id and lease.expires_at from the response.
- Distinctive: line 126
Start the heartbeat immediately after the claim succeeds.
- Very specific: line 164
Claude Code: run it with the Bash tool, run_in_background: true and the maximum timeout (7200000 ms).
- Very specific: line 167
Read its output from the output file path the tool returns (for example tail -n 1 <output file>).
- Very specific: line 169
Stop it with the harness's stop tool for background tasks (for example TaskStop with the recorded ID).
- Very specific: line 174
If a Monitor tool is available, use it as well to watch the output for lease_lost, heartbeat_error and renew_failed lines.
- Distinctive: line 176
Codex, Grok and other harnesses: use the harness's persistent or background process facility if it has one.
- Very specific: line 187
Stop it with kill <pid> (SIGTERM).
- Very specific: line 192
Before each of these steps, read the newest heartbeat line and confirm the process is alive, the line is renewed, and its at is within …
- Distinctive: line 196
before the first edit
- Distinctive: line 197
before running long verification
- Distinctive: line 199
before git push or opening a PR
- Very specific: line 202
If the line is older, the process is gone, or the line is anything other than renewed, run the lease-lost steps below.
- Distinctive: line 207
Stop editing. Do not commit, push or close.
- Distinctive: line 231
Do not request a long lease (up to 3600s) to avoid running a heartbeat.
- Distinctive: line 232
Use 300s with a 60s interval unless the user says otherwise.
- Distinctive: line 236
Stop the heartbeat only as part of closing (§6) or giving the task back (§7), right before that command, never earlier.
- Distinctive: line 243
Follow the task's implementation plan, acceptance and verification.
- Distinctive: line 249
Run the verification the task names: its canonical end-to-end test, focused tests, and the repository's pre-commit gates.
- Distinctive: line 268
Commit only that task's files, on the branch the repository rules require, using the task title and ID in the message:
- Very specific: line 275
Never bypass hooks (--no-verify).
- Distinctive: line 299
Do not wait for CI before moving on: CI runs the full suites while you work the next task.
- Distinctive: line 311
If the close fails, restart the heartbeat with the same IDs before you retry or investigate.
- Very specific: line 313
Run "$archdev" presence clear if you set presence.
- Distinctive: line 320
When you cannot finish (blocked, needs a human, out of scope, or the user redirects you):
- Distinctive: line 329
Stop the heartbeat, then release:
- Very specific: line 333
Run presence clear if you set presence, and update the state file.
- Distinctive: line 337
Read the state file.
- Distinctive: line 342
Failure: follow the lease-lost steps in §4.
- Distinctive: line 346
Read the task's newest comments before editing, in case someone changed the plan while you were away.
- Distinctive: line 351
Stop when the epic has no ready tasks left, when the user stops you, or when a blocker needs them.
- Distinctive: line 363
PRs: every PR opened, its base (stacked or default branch), its merge order, and CI status.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Execute an epic
Work an ArchDev Tasks epic one task at a time. Each task follows the same loop:
pick ready task → claim lease → start heartbeat → work → verify
↑ ↓
next ready task ← close ← stop heartbeat ← comment ← push + PR ← commitTwo rules matter more than anything else in this skill:
- Never work on a task you have not leased. The claim is the only
ownership gate. A
readylisting is a snapshot, not ownership. - Never hold a lease without a running heartbeat. Leases expire (60s to 1h). Without renewal another session can claim the task while you are still editing it, and your commit then lands on work someone else owns.
Use the archdev CLI for every Tasks operation. Prefer --json for output
you parse. The CLI is the authority when it disagrees with this file:
read "$archdev" tasks guide once per session.
Activity and risk ownership
Follow the archdev skill for activity reporting. Plan/task lifecycle events
retain their risk.plan / risk.task assessments. Server automation owns hosted
PR and code-region grading: report PR events without fetching, waiting for,
reusing, or attaching a server grade. No local assessment, annotation or stop
hold is required.
0. Connect
Resolve the absolute directory containing this SKILL.md and run its
bootstrap. It installs or updates ArchDev when the binary is missing or
lacks tasks heartbeat; get approval before installing or upgrading
software. Capture stdout, which is the executable's absolute path.
archdev="$(bash /absolute/path/to/tasks-execute/scripts/bootstrap.sh)" # Bash/Zsh
set archdev (bash /absolute/path/to/tasks-execute/scripts/bootstrap.sh) # Fish
$archdev = & powershell -NoProfile -File 'C:\path\to\tasks-execute\scripts\bootstrap.ps1'Then:
"$archdev" auth status. If signed out, run"$archdev" auth loginand let the human finish browser sign-in."$archdev" tasks guide. Read it in full.- If the
archdevskill is installed, load it too. It covers lifecycle posts, presence and PR bookkeeping that this skill refers to.
1. Pin down the epic and the scope
The user names an epic (the Task epic label) or a plan. Resolve it before
claiming anything.
- Find the owner scope:
--team <id>,--user <id>(default: you), or--org <id>. If the user did not say and more than one fits, ask. Never guess an ID. - List the whole epic, including done work, so you know the shape:
Page with"$archdev" --json tasks list --epic "<epic>" [--team <id>] --limit 100 "$archdev" --json tasks ready --explain --epic "<epic>" [--team <id>]--after-cursorwhen a page is full. - Note which tasks are tagged
humanorpost_deploy. Do not claim those: a person or a production observation closes them. Report them at the end. - Read the repository's agent instructions (
AGENTS.md,CLAUDE.md) before editing. They decide branch, commit, push and test rules. Where they are stricter than this skill, they win.
Write a small state file outside the checkout, for example
~/.archdev/task-execute/<epic-slug>.json (mkdir -p ~/.archdev/task-execute
first), holding the epic, scope, and
for each claimed task its task_id, lease_id, session_id,
session_name, and heartbeat log path. Rewrite it on every claim, release
and close. It is how you resume after a crash or context reset (§8). It
contains no secrets; still keep it out of the repository.
2. Pick the next task
- Re-read readiness every time. Never reuse an old listing:
"$archdev" --json tasks ready --epic "<epic>" [scope]. - Choose the highest-priority ready task (lowest
prioritynumber), then the oldest. Work one task at a time unless the user asked for parallel workers. - Read it fully before claiming:
Comments carry pause reasons, human answers and earlier attempts. The description carries the objective, acceptance, verification and the"$archdev" --json tasks show <task-id> "$archdev" --json tasks comments <task-id> --all "$archdev" --json tasks deps list <task-id>## Implementation plan. - If the task cannot be done as written (contradiction, missing access, a decision only a human can make), do not claim it. Comment the exact question on the task, tell the user, and pick another ready task.
3. Claim the lease
"$archdev" --json tasks claim <task-id> \
--session-name "<harness>:<branch>:<task-id>:<random 6 chars>" \
--harness <claude|codex|grok|...> \
--lease-duration-seconds 300- The random suffix makes the session name unique, so you can recognise your
own lease in
tasks showlater. - Keep
lease.lease_id,lease.session_idandlease.expires_atfrom the response. Write them to the state file before doing anything else. - A conflict error means another session holds the task. Do not retry in a loop and never try to take it over. Pick another ready task.
- Go straight to §4. Mark the task in progress and set presence only after the heartbeat is running.
4. Start the heartbeat (before any other work)
Start the heartbeat immediately after the claim succeeds. Do not read code, plan, or edit anything first.
"$archdev" --json tasks heartbeat <task-id> \
--lease-id <lease-id> --session-id <session-id> \
--interval-seconds 60 --lease-duration-seconds 300It renews the lease every 60s for 300s. It needs native ArchDev Tasks leases and refuses other task backends. It writes one JSON line per event to stdout; errors also go to stderr as plain text:
event | Meaning | What you do |
renewed | Lease extended to expires_at | Nothing |
renew_failed | Transient failure (network, timeout, 5xx, rate limit); still retrying | Watch. Do not commit or close until a renewed follows |
lease_lost | reason: "lost": the backend refused the lease (expired, held by someone else, or the task is gone). reason: "expired": no renewal succeeded for a full lease duration, so the lease is presumed lost. Exits with code 3 | Stop work on this task now (see below) |
heartbeat_error | A request the backend will never accept (signed out, invalid parameters). Exits with code 1 | Stop work, fix the cause (for example auth login), then confirm with tasks renew |
stopped | You stopped it | Expected before close or release |
Then, with the heartbeat running:
"$archdev" --json tasks update <task-id> --status in_progress \
--lease-id <lease-id> --session-id <session-id>Set presence only for an accessible team-owned task, and only if
"$archdev" presence --help lists update:
"$archdev" presence update --task <task-id>. Personal tasks stay private:
never publish their IDs through presence.
Run it so the harness tells you when it dies
The heartbeat must keep running in the background for as long as you hold the task, and you must find out when it exits.
- Claude Code: run it with the Bash tool,
run_in_background: trueand the maximumtimeout(7200000 ms). Record the background task ID it returns in the state file. The harness re-invokes you when it exits.- Read its output from the output file path the tool returns (for example
tail -n 1 <output file>). Do not read the whole file into context. - Stop it with the harness's stop tool for background tasks (for example
TaskStopwith the recorded ID). - Background runs have a time limit. When the notification says it stopped because of the limit and you still hold the task, restart it straight away with the same lease and session IDs.
- If a Monitor tool is available, use it as well to watch the output for
lease_lost,heartbeat_errorandrenew_failedlines.
- Read its output from the output file path the tool returns (for example
- Codex, Grok and other harnesses: use the harness's persistent or
background process facility if it has one. Otherwise start it detached,
with stdout and stderr in separate files so the event log stays JSONL:
Stop it withmkdir -p "$HOME/.archdev/task-execute" nohup "$archdev" --json tasks heartbeat <task-id> --lease-id <lease-id> \ --session-id <session-id> \ >"$HOME/.archdev/task-execute/<task-id>.heartbeat.jsonl" \ 2>"$HOME/.archdev/task-execute/<task-id>.heartbeat.err" & echo $! # record this PID in the state filekill <pid>(SIGTERM). Checkkill -0 <pid>to see whether it is still alive.
Check the heartbeat at every gate
Before each of these steps, read the newest heartbeat line and confirm the
process is alive, the line is renewed, and its at is within about two
intervals (two minutes at the defaults):
- before the first edit
- before running long verification
- before
git commit - before
git pushor opening a PR - before
tasks close
If the line is older, the process is gone, or the line is anything other
than renewed, run the lease-lost steps below.
When the lease is lost or the heartbeat is dead
- Stop editing. Do not commit, push or close.
- Probe ownership with your stored IDs:
"$archdev" --json tasks renew <task-id> --lease-id <lease-id> --session-id <session-id>- It succeeds: you still hold the task. Restart the heartbeat with the same IDs and continue.
- It fails with a conflict ("Task lease has expired" or "Task lease
does not match the current holder"): your lease is gone. The second
message also appears when nobody holds the task, so check:
"$archdev" --json tasks show <task-id>and look atcurrent_lease.- Empty: claim again with new IDs (§3), start a new heartbeat, and check the working tree still matches what you expect before going on.
- Another
session_name: someone else owns the task now, and your work on it is no longer authoritative. Comment where your partial work is (branch name, stash tag, or WIP commit SHA), tell the user, and move to another ready task. Never push over the other session's work.
- It fails with an authentication or other error: fix that first (for
example
auth login), then probe again.
Rules
- One heartbeat per held lease, never zero.
- Do not request a long lease (up to 3600s) to avoid running a heartbeat. Use 300s with a 60s interval unless the user says otherwise. Allowed durations are 60 to 3600 seconds.
--interval-secondsmust be shorter than--lease-duration-seconds. Keep it at a third of the duration or less.- Stop the heartbeat only as part of closing (§6) or giving the task back (§7), right before that command, never earlier.
5. Do the work
- Report the start if the
archdevskill's lifecycle posts are in use:"$archdev" log post --project <id> --kind start "<what this task delivers>". - Follow the task's implementation plan, acceptance and verification. They are the contract. If they turn out to be wrong, comment what you found and why, and adjust within the objective. Ask the user before changing scope.
- Record durable progress on the task at real milestones, not every step:
"$archdev" tasks comment <task-id> "<decision, finding, or blocker>". - Run the verification the task names: its canonical end-to-end test, focused tests, and the repository's pre-commit gates. A task is not done until they pass, or until the gap is written down on the task with the reason.
- Two failed attempts on the same failure means change approach, not try a third time. If you are still stuck, use §7.
6. Commit, push, open a PR, then close
This skill carries each task through to a pull request. Invoking it on an epic is the user's explicit request to commit, push and open a PR for each finished task. Skip pushing only when the user said so for this run ("commit only", "don't push"), or when the repository instructions forbid agent pushes; then stop at the commit and say so in the report. Repository instructions still decide the branch, commit format, PR format and whether PRs open ready or as drafts. If they forbid agent commits outright, stop at verified, uncommitted work and ask.
- Gate check: the heartbeat's newest line is
renewed(§4). - Commit only that task's files, on the branch the repository rules
require, using the task title and ID in the message:
Never bypass hooks (<type>(<area>): <task title> Task: <task-id>--no-verify). If a hook fails, fix the cause. - Pick the PR base before pushing:
- The task's prerequisites are merged (or it has none): branch from
the remote default branch (
git fetch origin <default>, then rebase ontoorigin/<default>) and open the PR against it. - A prerequisite's PR is still open and this task builds on its
code: stack. Base this branch and the PR on the prerequisite's branch,
and put
Merge order: after #<n>at the top of the PR body. - A base PR merged while you worked (its branch is gone, or
gh pr createsays the base is not a branch): rebase only your own commits onto the default branch (git rebase --onto origin/<default> <old-base-tip>), run a compile/lint check, push with--force-with-lease, and open the PR against the default branch.
- The task's prerequisites are merged (or it has none): branch from
the remote default branch (
- Gate check, then push the branch and open one PR per task. Use the repository's PR template and rules (title, required first line, problem, what changed, testing with the canonical end-to-end proof, risk). Name the task and link it. Never push over someone else's branch.
- Link the PR to the task and record the result:
Then run the PR bookkeeping the"$archdev" tasks links add <task-id> <pr-url> --type pull_request "$archdev" tasks comment <task-id> "PR <url>: <sha> on <branch>. Verified by <test names>."archdevskill requires for any PR head you moved. - Do not wait for CI before moving on: CI runs the full suites while you work the next task. Locally, run the focused tests and gates the task names (§5), not every suite. Check the PR's CI when you finish the epic (§9), or sooner if the next task stacks on it, and fix failures on the same branch.
- Gate check again, then stop the heartbeat and close, fenced with your
lease. The last renewal leaves minutes on the lease, which is plenty for
the close. Stopping first means the heartbeat never reports your own close
as a lost lease.
If the close fails, restart the heartbeat with the same IDs before you retry or investigate."$archdev" --json tasks close <task-id> --lease-id <lease-id> --session-id <session-id> - Run
"$archdev" presence clearif you set presence. Update the state file with the task's PR URL. - Go back to §2. Closing a task can make its dependents ready; a dependent that builds on this task's code stacks on its PR (step 3).
7. Give a task back
When you cannot finish (blocked, needs a human, out of scope, or the user redirects you):
- Comment the state: what is done, where it lives (branch or SHA), what remains, and the exact question if one exists.
- Reopen it while still fenced:
"$archdev" --json tasks update <task-id> --status open --lease-id <lease-id> --session-id <session-id> - Stop the heartbeat, then release:
"$archdev" --json tasks release <task-id> --lease-id <lease-id> --session-id <session-id> - Run
presence clearif you set presence, and update the state file.
8. Resume after a crash or context reset
- Read the state file.
- For each task it lists as held, probe with the stored IDs:
"$archdev" --json tasks renew <task-id> --lease-id <lease-id> --session-id <session-id>.- Success: the lease is still yours. Start a heartbeat with the same IDs straight away (§4), then continue.
- Failure: follow the lease-lost steps in §4. They cover an expired lease, a new owner, and auth errors.
- Clean up anything the crash left running: a heartbeat PID or background task for a task you no longer hold.
- Read the task's newest comments before editing, in case someone changed the plan while you were away.
9. Finish
Stop when the epic has no ready tasks left, when the user stops you, or when a blocker needs them. Before you report, check that no heartbeat is still running for a task you closed or released.
Report back in this form:
- Done: task, commit SHA, PR link and its CI state, and the verification that proved it.
- Given back: task, why, and the question it needs answered.
- Blocked or not started: task and its blockers, from
tasks ready --explain --epic "<epic>". - For a human: tasks tagged
humanorpost_deploy. - PRs: every PR opened, its base (stacked or default branch), its merge order, and CI status. Check CI on each before reporting and fix failures on the same branch. If pushing was skipped, say so and list the unpushed branches.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

