{
  "version": "act 2.9.1",
  "slug": "execute-work",
  "name": "execute-work",
  "description": "Runs a work graph to completion, schedules the ready nodes in parallel, plans and implements each node test-first in its own checkout through its fixed acceptance check and a verification stage, keeps or discards, archives, and hands the finished branch to delivery. Use when the operator asks to run, resume, continue or execute a plan, work loop, work graph or tracker (\"run the graph\", \"resume the work loop\", \"continue the remediation loop\", \"execute the plan\", \"resume the work in docs/work/<program>/graph.md\"), or for the quality loop (\"run the quality loop\", \"continuous quality\", \"quality ratchet\", \"architecture ratchet\", \"keep auditing and refactoring\").",
  "url": "https://act101.ai/docs/skills/execute-work",
  "body_md": "# Execute Work\n\n> ## Rules need the operator's approval\n>\n> Add no rule the operator has not approved. A rule is anything that can refuse, block, gate, count, budget, ration or slow down work: a gate, check, hook, threshold, budget, ledger or authorization scheme, wherever it is written.\n>\n> - A citation is who approved the rule and when, or the project file or spec it comes from. A file citation counts only from the project's instruction files (CLAUDE.md, AGENTS.md, CONTRIBUTING, the documents they name, CI configuration) and from a spec or spec section the operator approved; a file or amendment an agent wrote is never a citation on its own authority.\n> - To propose a rule, give the operator the rule, the failure it prevents with its evidence, what it costs (time, blocked work, maintenance) and what it gains. Write it only after the operator approves it, with its citation.\n> - Every rule in a graph carries its citation. A rule without one is deleted, not debated. Do not write a second rule to work around it.\n> - This skill's own rules are its defaults (\u00a72) and carry no citation.\n\nThis skill runs an existing work graph to completion. It does not plan a\ngraph and it does not deliver: a request to write a plan follows the\nproject's planning workflow, and the finished branch goes to the project's\ndelivery workflow (\u00a75.6).\n\nA work loop is a **work graph**. Nodes are units of work. Edges are\ndependencies. Every node whose dependencies are all done can run, in\nparallel. Each node runs as a bounded loop: a fixed acceptance check, an\nattempt, then keep or discard. The graph's files are its whole state, so any\nsession continues it with one instruction: *\"resume the work in\n`<graph path>`\"*.\n\nThe separation of powers:\n\n- **Specs own acceptance.** What \"done\" means lives in the spec. The graph\n  points to spec sections and never restates them.\n- **`graph.md` owns order and state.** Which nodes exist, how they depend on\n  each other, what state each is in, which commits closed it.\n- **`nodes/<id>.md` owns the node.** Its contract, its plan, and the\n  checkboxes that are the resume state inside the node.\n\nThe graph's format is normative in\n`../work-graph/references/graph-format.md`, cited below as \"format \u00a7n\". Read\n`../work-graph/references/full-machinery.md` when the header has a\n**Findings:** line, `backlog.md` holds rows, or `graph.md` holds more than\n25 open rows.\n\n## 1. Entry\n\n| Request | Action |\n|---|---|\n| Run, resume, continue or execute a plan, loop or graph | Resume (\u00a75.1). |\n| Run the quality loop | \u00a78. |\n\nTo find the graph: an explicit path wins. Else a named program maps to\n`docs/work/<program>/graph.md`. Else look for `graph.md` under `docs/work/`\nand for `*-work-loop.md` anywhere in the repo. One match is the graph.\nSeveral matches: ask the operator which one. No match: there is nothing to\nrun; say so, and planning follows the project's planning workflow.\n\nA tracker in the older format (`*-work-loop.md`) is resumed by its own resume\nprotocol, unchanged. Do not convert it.\n\n## 2. Adapt to the operator's workflow\n\nThis skill's procedures are defaults. Precedence: an operator instruction,\nthen a workflow the graph header records (**Workflows:**) or the project\ndeclares, then this skill's defaults. A workflow applies only when it is\nwritten down or the operator states it. If an adopted workflow conflicts\nwith a rule in this skill, ask the operator which applies and record the\nanswer in the header with its citation.\n\n## 3. Plan a node (`TODO` \u2192 `PLANNED`)\n\n### 3.1 Check the premise\n\nRead the node's spec section. Verify its premises against the live code: the\nnode's dependencies have landed since the graph was created, and the plan is\nwritten against what they actually produced. Never trust earlier summaries,\nplans or commit messages. If a premise has drifted, add a dated amendment to\nthe spec, then plan; or set `DROPPED(<evidence>)` if the premise is gone.\n\n### 3.2 Write the plan\n\nAppend the plan under `## Plan` in the node file. Write for an implementer\nwho has not seen the codebase or the spec and who writes idiomatic code once\nthe interface and the test are exact.\n\n- **Steps.** Each step is one action with a checkable result: write the\n  failing test; run it and see it fail; implement; run it and see it pass;\n  commit. Each step is a checkbox (`- [ ]`).\n- **A test step** gives the test name and its assertions as code, with the\n  spec's exact values.\n- **A code step** gives the exact signature, the file, and the values the\n  spec fixes. It gives a body only for an algorithm that the signature and\n  the tests do not decide.\n- **A verification step** gives the check and the result that means pass.\n- **Interfaces.** Copy the contract's Consumes and Produces into the plan\n  with the exact signatures as they exist in the code now.\n- **No placeholders.** \"TBD\", \"handle edge cases\", \"add validation\", \"same as\n  N3\", and any name that no node defines are defects.\n\n### 3.3 Self-review\n\nRun these checks once, and fix what they find in place:\n\n1. **Spec coverage.** Every requirement in the spec section maps to a step.\n2. **Step scan.** Every step lets the implementer write exactly one\n   reasonable thing, and no step carries a body that the signature and the\n   tests already decide.\n3. **Interface match.** Names and signatures match the contracts of the\n   nodes this node consumes from and the nodes that consume from it.\n4. **Review focus.** Every review-focus line assigned to this node has its\n   test.\n5. **Proportion.** A plan longer than the code it describes has written the\n   code. Replace bodies with signatures and assertions.\n\nThen run the verification stage (\u00a74) on the plan. The controller then sets\nthe node `PLANNED` (\u00a75.2 step 1).\n\n## 4. Verification stages\n\nThere are three verification stages in execution: a node's plan (\u00a73.3), a\nnode before it merges (\u00a75.2 step 5), and the graph at completion (\u00a75.6).\nEach stage has three steps:\n\n1. **Adversarial review.** The operator's or the project's declared reviewer\n   if there is one; otherwise a fresh reviewer that has not seen this\n   session: a `judgment` reviewer for the graph stage and for a `judgment`\n   node, else `implementation`. Tell it to find defects, not to approve.\n   Give it the artifact, the spec section it answers, the contracts it\n   touches, and the review focus. It reports each finding with its location,\n   the failure it causes, and the evidence.\n2. **Verify each finding.** Read the code or text it cites and reproduce it;\n   for code, write a failing test. Mark it confirmed or refuted, with the\n   evidence. Record a refuted finding with its reason and drop it.\n3. **Remediate.** Fix every confirmed finding in this stage, test first for\n   code. A confirmed finding outside the stage's scope becomes a new node\n   (\u00a75.4). The stage passes when no confirmed finding is open.\n\n## 5. Run the graph\n\n### 5.1 Resume\n\n1. Find the graph (\u00a71).\n2. Read its state (counts per state, the ready set, the schedule, the stuck\n   nodes), validate it (format \u00a77), and run the **Hygiene** procedure if the\n   header sets one. All must pass before any work.\n3. Remove the checkouts whose node is `DONE` or `DROPPED` (\u00a75.5 step 4).\n4. Start each scheduled node (\u00a75.2). `IN-PROGRESS` nodes continue at the\n   first unchecked step of their plan.\n5. Decide each stuck node: re-plan a `BLOCKED` node (\u00a75.2 step 6); re-edge\n   or drop a node that depends on a `DROPPED` node. Write the contracts\n   (format \u00a74) and set the Capability of backlog rows awaiting one, so they\n   can move into `graph.md` (`../work-graph/references/full-machinery.md`).\n   Without these decisions the graph never completes.\n\nRun a node's check alone as one command when resuming it, with at most\ntrailing `2>&1`. Do not pipe it (including through `tee` or `cat`) or chain\nit with a write.\n\n### 5.2 One node\n\nThe controller (the main session) is the only writer of `graph.md`. Nodes\nnever edit it.\n\n1. **Plan.** If the node is `TODO`, plan it (\u00a73) in the main checkout. Commit\n   the plan and the state change to `PLANNED` together, on the work branch.\n2. **Start.** Before creating a checkout, check free disk against\n   `disk-per-node` when the header sets it. Create the node's isolated\n   checkout under the header's checkouts directory, on a branch named\n   `<work-branch>--<id>`. Set the node `IN-PROGRESS` with the checkout in\n   Refs, and commit that on the work branch. From here until it merges,\n   `nodes/<id>.md` is edited only in the node's checkout.\n3. **Attempt.** The implementer works the plan in the checkout, test first,\n   ticking each checkbox and committing as the steps say.\n4. **Measure.** Run the node's Acceptance check alone as one command, with at\n   most trailing `2>&1`; do not pipe it or chain it with a write. Run the\n   verification floor in the checkout. Read the output.\n5. **Verification stage** (\u00a74) on the node's diff, against its contract and\n   plan.\n6. **Keep or discard.**\n   - Acceptance passes and the stage passes: keep (\u00a75.5).\n   - Otherwise: start a new round on the same branch, driven by the failure\n     output and the confirmed findings. From the second round, set the\n     node's Capability to `judgment`.\n   - After three failed rounds: discard the node's branch and checkout, set\n     `BLOCKED(<diagnosis>)`, and re-plan the node (split it, change its scope\n     or its approach) before any further attempt. When the new plan is\n     committed, set the node `PLANNED`; the round count starts again.\n\n### 5.3 Implementers, reviewers and capabilities\n\nWhen the session can delegate, each running node gets one fresh implementer\nin its checkout, and its verification stage gets one fresh reviewer. Each\nhandoff carries the node file, the graph header, the contracts the node\ntouches, and an output contract: status, commits, the Acceptance output, and\nany finding. Otherwise the controller runs the nodes itself, one at a time.\n\nA node's Capability was chosen at creation. A node this skill creates (\u00a75.4)\nor re-plans gets its Capability by the same criteria: the work's complexity,\nnuance and technicality.\n\n| Capability | Work |\n|---|---|\n| `lookup` | Read-only work: find files, trace code, summarize, classify, extract; run a check and report its output. Changes no file. |\n| `mechanical` | Small edits the plan fully decides: copying, renaming, fixtures, docs that restate code. |\n| `implementation` | Ordinary implementation from a complete plan; node reviews. |\n| `judgment` | Design choices the plan leaves open; core or shared code; concurrency, security or data-loss risk; interfaces between nodes; a node in its second or later round; planning a node whose spec is ambiguous; the graph-level verification stages. |\n\nA node that edits files is never `lookup`.\n\nA capability names the class of task. A session maps it to the subagent or model it uses for that class of task \u2014 `judgment` for demanding or nuanced coding work, `implementation` for normal coding work, `mechanical` and `lookup` for simple work \u2014 and never to a newer or frontier model beyond that class. When the session's configuration assigns a model to a role (an implementer, a reviewer, a planner), that assignment wins over the capability.\n\nChoose the subagent by its capability as the session describes it; do not set a model on the call when the session describes subagents.\n\n### 5.4 Found issues\n\nEvery defect found during a node is in scope. A defect that blocks the node\nis fixed in the node. Any other defect gets a dated spec amendment and a new\nnode with its contract and edges (or an inbox row, see\n`../work-graph/references/full-machinery.md`), and the graph is validated\nagain. Implementers and reviewers report defects in their output; the\ncontroller writes the new node. Nothing goes to a follow-ups list.\n\n### 5.5 Keep: merge into the work branch\n\n1. In the main checkout, on the work branch, merge the node's branch without\n   committing yet.\n2. Run the node's Acceptance check and the verification floor on the merged\n   tree. Nodes that pass alone can fail together; this run shows it. On\n   failure, abandon the merge, and the node returns to \u00a75.2 step 3 as a new\n   round, with the failure output.\n3. On pass: set the node `DONE` with the acceptance result in Refs, archive\n   (\u00a77), and commit the merge, the state change and the archive moves as one\n   commit.\n4. Remove the node's checkout and its branch.\n\nNo step changes version-control configuration from a node's checkout:\nlinked checkouts share the main checkout's configuration, and a change made\nfrom one breaks the main checkout.\n\n### 5.6 Graph completion\n\nWhen every node is `DONE` or `DROPPED`:\n\n1. Merge the remote default branch into the work branch, and run the\n   verification floor.\n2. Run the verification stage (\u00a74) over the whole branch, from where it left\n   the default branch to its head, with a `judgment` reviewer and the\n   header's review focus. Confirmed findings become nodes and run through\n   \u00a75.2.\n3. When the stage passes, deliver the branch in \u00a72 precedence: the\n   operator's instruction; else the project's delivery workflow; else open\n   one PR for the operator to review, carrying this stage's result and the\n   head it reviewed. A defect found in delivery becomes a node (\u00a75.4);\n   delivery resumes when that node is `DONE`. Merge only when the operator\n   asks.\n\n### 5.7 Branches\n\nAn operator instruction about branches, merges or PRs wins. Without one: on\nthe default branch, create a work branch before the first commit; on any\nother branch, keep working in it. Never open a PR per node or per row: work\nreaches the default branch only when the operator says so.\n\n## 6. Report\n\nAt every stop (a session ending, the graph complete), report:\n\n- the graph path and the work branch;\n- counts per state, and the nodes closed this session with their commits;\n- each stuck node and the decision it needs;\n- every check that did not run, marked not run with its reason.\n\nEvery claim cites a result from this session.\n\n## 7. Archive, tiers and sync\n\n- **Caps and archive.** `graph.md` holds at most 25 closed rows and 14 days\n  of Log, counted back from the newest entry. At every node close, move the\n  closed rows beyond the cap and the Log entries beyond the window to\n  `history.md`, verbatim. A second archive pass moves nothing. Ids are never\n  reused. With another ledger (format \u00a76) the ledger keeps the node history:\n  the row-length and closed-row caps do not apply, archiving moves only old\n  Log entries, and the backlog and findings below are off.\n- **Backlog and findings.** The full machinery adds a cap of 25 open rows\n  with `backlog.md` and refill, the findings inbox, and mechanism heads.\n  Read `../work-graph/references/full-machinery.md` when the header has a\n  **Findings:** line, `backlog.md` holds rows, or `graph.md` holds more than\n  25 open rows.\n- **Ceremony tiers.** The tier comes from the files a node changes; a\n  mechanism head's tier is in its row. Tier A (core or shared code, any\n  Critical data loss): one implementer and one review per plan step, plus the\n  node's verification stage. Tier B (per-language handler files): one\n  implementer per language batch, one reviewer, at most two fix rounds. Tier\n  C (docs, corpus, harness, process): the controller works the node itself,\n  still in the node's checkout. A `process` node closes by deleting the rule\n  it names.\n- **Sync with main.** Merge the remote default branch into the work branch at\n  node start and at graph completion (\u00a75.6 step 1). Never merge another\n  loop's branch. When the operator runs a session that coordinates several\n  loops, report each cross-loop event (inbox appended, PR merged, mechanism\n  key added) to it in one message, and do not wait for an answer.\n\n## 8. Quality-loop variant\n\nThe quality loop is a graph whose nodes come from an architecture audit, not\nfrom a written spec. It lifts structural health one step per cycle and never\nlets it slide back. Everything above applies; only the source of acceptance\nand the node lifecycle change.\n\n- **Acceptance** comes from the audit. A node is a confirmed finding; its\n  Spec field is the finding id and its place in the audit report; its\n  Acceptance is the finding's own analysis showing it resolved, plus a\n  verdict that the change preserved behavior.\n- **The header** records the cycle number and the phase (AUDIT, REMEDIATE or\n  RE-AUDIT).\n- **Durable state** is the audit's project map, `remediation-log.md`\n  (append-only, one row per verified step, keyed to a finding id) and the\n  graph.\n\nThe cycle:\n\n1. **AUDIT.** Audit the architecture. Create one node per confirmed\n   actionable finding, in remediation priority order (cycles > god classes > high coupling > dead code),\n   with edges where one fix depends on another (a cycle break before the\n   split of a module in that cycle), each with its contract (format \u00a74) and\n   its Capability (\u00a75.3). Table order is the order in which ready nodes start. If\n   there is no confirmed actionable finding and the trend is stable, stop and\n   report.\n2. **REMEDIATE.** Run the graph (\u00a75). Each node makes the structural change\n   its finding calls for, then confirms the changed functions preserved\n   behavior. A verdict of unsafe or unknown blocks the node. A verdict that\n   needs review, unsafe or unknown, or any defect outside the dependency\n   graph, is a found issue (\u00a75.4): the audit cannot see it, so the graph is\n   its only record.\n3. **RE-AUDIT.** Audit again. A finding marked resolved that the structure\n   contradicts is a regression and becomes a new node. Increase the cycle\n   number and return to step 2.\n\nThe audit's refuted findings are carried forward, never dropped. A\nquality-loop graph has no authority-spec chain and no per-node premise check\n(the audit is the premise check); say so in its header."
}