{
  "version": "act 2.9.1",
  "slug": "plan-work",
  "name": "plan-work",
  "description": "Plans work as a resumable work graph of nodes with contracts, dependencies and fixed acceptance checks, cut from an approved design, reviewed, validated and committed for execution. Use when the operator asks to write a plan, plan a change, break work down or turn a spec into tasks before writing code (\"write a plan\", \"plan this\", \"implementation plan\", \"break this down\"), or to create or set up a work loop, work graph or tracker (\"create a work loop for this spec\", \"set up a tracker\", \"make this resumable\").",
  "url": "https://act101.ai/docs/skills/plan-work",
  "body_md": "# Plan 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 answers \"how do we build this approved design\". It ends with a\ncommitted, validated work graph. It does not run the graph: running,\nresuming and continuing a graph follow the project's execution workflow.\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\". The\ntemplates `graph-template.md` and `node-template.md` and the ledger contract\n`ledgers.md` sit beside it.\n\n## 1. Entry\n\n| Request | Action |\n|---|---|\n| Write a plan, plan this, break this down, turn this spec into tasks | Create the graph (\u00a73). Then stop and ask the operator to review it (\u00a76). |\n| Create a work loop, set up a graph or a tracker | Create the graph (\u00a73). Then hand over (\u00a76): the request includes running it. |\n\nA graph lives in `docs/work/<program>/` unless the project has a\nconvention. When a graph for the program already exists there, do not create\na second one: say so and hand over (\u00a76).\n\nA small change gets a small graph. One node is a valid graph.\n\n## 2. Adapt to the operator's workflow\n\nThis skill's procedures are defaults. Where the operator has chosen a\nworkflow for part of the work, use it.\n\n1. **Find out what exists.** At creation, read the project's instructions\n   (CLAUDE.md, AGENTS.md, CONTRIBUTING and the documents they name). Look\n   for: a ticket or issue lifecycle, a planning or review workflow, branch\n   and PR conventions, and a ledger the operator uses.\n2. **Do not presume.** A workflow applies only when it is written down or the\n   operator states it. Infer nothing from a name or a habit.\n3. **Record it.** Add a `**Workflows:**` line to the graph header, one entry\n   per adopted workflow: what it governs, then its citation. Map a ticket\n   lifecycle in `ledger.md` (format \u00a76): for each state change, what the\n   lifecycle requires.\n4. **Precedence.** An operator instruction, then a workflow the project\n   declares, then this skill's defaults. If an adopted workflow conflicts\n   with a rule in this skill, ask the operator which applies and record the\n   answer with its citation.\n\n## 3. Create a graph\n\n1. **Gather inputs.** The authority specs, the verification floor, the\n   project's hard rules, the run settings, and what \u00a72 finds. An approved\n   design document is an authority spec. When the request's intent, scope or\n   constraints are not settled, get an approved design before you cut nodes,\n   in \u00a72 precedence: the operator's instruction; else the project's design\n   workflow; else agree intent, scope and constraints with the operator and\n   write them to a spec. Take what the repo and the conversation give. Ask\n   for the rest, one question at a time.\n2. **Map the files.** List the files the work creates or changes and what\n   each is responsible for. Decide the decomposition here: one clear\n   responsibility per file; files that change together live together; follow\n   the codebase's existing patterns.\n3. **Cut the nodes.** A node is the smallest unit that has its own\n   acceptance check and that a reviewer could reject while approving its\n   neighbour. Fold setup, configuration and documentation into the node\n   whose deliverable needs them. Every spec item gets a node now, including\n   later ones, so \"first ready node\" always answers what to do next.\n4. **Draw the edges.** A node depends on another only when it consumes what\n   that node produces or changes a file that node creates. An edge that is\n   not a real dependency removes parallelism.\n5. **Choose each node's capability** (\u00a74).\n6. **Write the contracts** (format \u00a74) and the header (format \u00a72).\n7. **Self-review** the graph, and fix what you find in place:\n   1. **Spec coverage.** Every requirement in every authority spec maps to a\n      node.\n   2. **Interface match.** Every Consumes resolves to a Produces of a node\n      the consumer depends on, with the signature as it exists in the code\n      now or as the producing node's contract states it.\n   3. **Review focus.** Every review-focus line names the node that owns its\n      test.\n   4. **Proportion.** A contract that describes the code instead of its\n      interface has written the code. Replace bodies with signatures and\n      acceptance checks.\n8. **Verification stage** (\u00a75) on the header, the nodes and the edges.\n9. **Validate** the graph (format \u00a77).\n10. **Commit** the graph files together, on a work branch. An operator\n    instruction about branches wins. Without one: on the default branch,\n    create a work branch before the first commit; on any other branch, keep\n    working in it. If the checkouts directory is not ignored by version\n    control, ignore it in the same commit, so a merge never stages a\n    checkout.\n\n## 4. Capabilities\n\nA node's capability is chosen at creation by the work's complexity, nuance\nand 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. Verification stage\n\nThe 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, with the `judgment` capability. Tell it to find defects, not to\n   approve. Give it the graph, the authority specs it answers, and the review\n   focus. It reports each finding with its location, the failure it causes,\n   and the evidence.\n2. **Verify each finding.** Read the spec or graph text it cites and\n   reproduce it. Mark it confirmed or refuted, with the evidence. Record a\n   refuted finding with its reason and drop it.\n3. **Remediate.** Fix every confirmed finding in the graph: a missing node, a\n   wrong or missing edge, an unresolved Consumes, a contract that restates\n   the spec or writes the code. The stage passes when no confirmed finding\n   is open.\n\n## 6. Hand over\n\nIf the request was to write a plan, give the operator the graph path and ask\nthem to review it. Nothing runs before they answer.\n\nOtherwise give the operator the graph path and the work branch. Execution\nfollows the project's execution workflow, or the operator's instruction. To\ncontinue in any session: *\"resume the work in `<graph path>`\"*.\n\n## 7. Report\n\nAt hand-over, report:\n\n- the graph path and the work branch;\n- the node count, the ready set, and the authority specs;\n- each choice made as the author's call, so the operator can check it;\n- every check that did not run, marked not run with its reason.\n\nEvery claim cites a result from this session."
}