Understanding Workscopes

What Is a Workscope?

A workscope is a formally documented, immutable work assignment. It defines exactly what an AI assistant should accomplish in a single session, not a vague objective like “add authentication” but a precise set of numbered tasks drawn from the project’s own task lists.

Every workscope has a unique identifier based on when it was created, following a timestamp format like 20260215-143022. This identifier threads through the entire session: the work journal, the quality reviews, and the completion record all reference it. When you look back at your project’s history, every piece of work traces back to a specific workscope with a specific scope definition.

The workscope is captured in a file that lives permanently in your project’s archive. This file records what tasks were selected, how they were found (the navigation path through your project’s documentation), what phase they belong to, and what context documents are relevant. Once created, the file never changes. The AI cannot redefine its assignment mid-session, which prevents the scope creep that plagues unstructured AI interactions.¹² You know the pattern: you ask an assistant to fix a button and it redesigns the component system.

Immutability also creates an audit trail. The workscope file is a permanent record of what was attempted, when, and in what context. Combined with the work journal that the agent maintains throughout execution, you get traceability beyond what git provides. Git tells you what code changed. The workscope records tell you what the assignment was, what context was loaded, and what quality checks ran.

The workscope is the atomic unit of work in WSD. Everything else orbits around it.

Checkboxlists

If you have run workscope cycles through the Your First Project guide, you have already seen checkboxlists in action: your Action Plan is one. A checkboxlist is a hierarchical, numbered task list that tracks every piece of work in a project. Items are organized into phases, numbered according to their position in the hierarchy, and marked with a checkbox indicating their current status.

Each checkbox has one of five states:

• [ ] Unaddressed — The task has not been started. It is available for assignment.
• [%] Incomplete/Unverified — Work may exist for this task, but it needs a fresh review. For all practical purposes, the Task-Master treats this identically to [ ] — the agent assigned to it has full responsibility for ensuring the task is complete and correct, whether that means implementing from scratch or verifying and completing existing work.
• [*] Assigned — The task is currently claimed by an active workscope. Other workscopes cannot select it.
• [x] Completed — The task has been finished successfully.
• [-] Skipped — The task has been deliberately abandoned. Only the human developer can authorize this state.

The [%] state deserves particular attention because it is the most counterintuitive. It does not mean there is less work to be done, but rather indicates that “something exists here, but we are not confident it is correct or complete.” An agent receiving a [%] task works through it as if implementing from scratch, comparing against what exists at each step. If 100% of the work is already there and correct, the agent confirms it. If gaps exist, the agent fills them. This is useful both for work that is partially completed or work already performed (perhaps by a human developer) that requires the formal processing of a workscope cycle.

Checkboxlists use hierarchical numbering that mirrors their indentation structure. A task numbered 2.3.1 is the first subtask of the third item in Phase 2. Parent items reflect the state of their children — if any child is unaddressed, the parent shows as unaddressed too. If all children are completed or skipped, the parent inherits the appropriate terminal state.

In practice, this parent-child propagation creates a scannable progress map. Glancing at the top level of your Action Plan, you can immediately see which phases and features have remaining work and which are complete — without drilling into every individual task. When you see [ ] on a parent item, it signals that available work exists somewhere below. When you see [x], the entire branch is done. The checkboxlist is both a task tracker and a progress dashboard, updated automatically as workscopes complete.

Phases

Tasks within a checkboxlist are organized into phases — logical groupings of related work that are generally executed in sequence. Phase 1 might cover initial setup, Phase 2 might handle core implementation, Phase 3 might address testing and documentation. The numbering convention is straightforward: tasks in Phase 1 start with 1., tasks in Phase 2 start with 2., and so on.

Phases serve two purposes. First, they create natural breakpoints in the work. A developer can see at a glance which phase a project is in and what remains. Second, they provide a sizing mechanism for the Task-Master — when selecting work for a workscope, it considers phase boundaries as natural grouping hints.

One phase grouping deserves special mention. Phase 0 is reserved. It never appears in new checkboxlists and is never used for foundational or prerequisite work. Phase 0 is an emergency system for blocking issues discovered during implementation. When you discover a bug during Phase 3 work that prevents progress, you create a ticket for it and add a reference to Phase 0. Any unaddressed Phase 0 item blocks all regular-phase work in that checkboxlist until it is resolved. The Work Plan Documents guide covers Phase 0 in depth, including the stack behavior that emerges when blocking issues nest across documents.

One structural rule is worth internalizing early: a checkboxlist must be a cohesive, uninterrupted list of tasks. Once the first phase header appears, the list should contain only phase headers and task items until it ends. Explanatory text, analysis, and rationale belong in separate sections of the document, not embedded between tasks. This separation keeps the checkboxlist clean for both the Task-Master’s algorithmic parsing and human scanning. Context and reasoning go above the checkboxlist; the checkboxlist itself is pure, actionable structure.

How Work Gets Assigned

The Task-Master assigns workscopes by traversing the WPD tree using a depth-first search. Starting from the Action Plan, it checks Phase 0 first (because Phase 0 items are blocking). If Phase 0 is clear, it moves to the regular phases in order, looking for the first unaddressed or incomplete task. If that task is a navigation pointer — a reference to another document, a concept the Work Plan Documents guide covers in depth — the Task-Master follows the link and continues searching there. It keeps navigating deeper until it reaches actionable leaf tasks: specific, concrete work items that an agent can execute directly.

To make this concrete: the Task-Master might start at the Action Plan and find that Phase 3 is the first phase with available work. It encounters item 3.5, which says “Implement caching (see docs/features/caching/Caching-Overview.md).” This is a navigation pointer — not work to be assigned, but a link to follow. The Task-Master opens the caching Feature Overview, finds its checkboxlist, checks Phase 0 (clear), and discovers that Phase 2 has available items: tasks 2.4, 2.5, and 2.6. These are leaf tasks — specific actions like “add cache invalidation logic” and “write integration tests for the cache layer.” The Task-Master evaluates whether they form an appropriate workscope. The navigation path — Action Plan → Caching Feature Overview → Phase 2 — is recorded in the workscope file so that every agent involved knows exactly how the work was found.

Once the Task-Master reaches leaf tasks, it assesses whether they form an appropriate workscope. A single task with substantial subtasks might be a workscope on its own. A cluster of related tasks from the same phase might be grouped together if they form a coherent unit: tasks that build on each other, or that together bring a feature to a testable state. The goal is work that is large enough to be meaningful but small enough that the AI assistant can complete it thoroughly in one session. In practice, this means a workscope of moderate complexity: enough to accomplish something real, not so much that the AI loses track of details as its context window fills.³⁴ If the available tasks are too large for a single session, the Task-Master selects a subset. If they are too small, it may group siblings together. The sizing accounts for the complexity of the work, whether tasks have dependencies, and whether the result would be coherent enough to review and commit as a unit.

The Task-Master also respects the [*] state. If another workscope has already claimed certain tasks, those tasks are unavailable. The Task-Master skips them and continues searching for unclaimed work. This coordination mechanism enables parallel workscope sessions on the same project without conflicts — each session gets its own non-overlapping slice of work, and no manual coordination is required.

You can guide the Task-Master with directives — telling it to focus on a specific area, skip certain items, or select particular tasks. A directive like /wsd:init Just do 2.4 and 2.5 constrains the selection to those specific items. /wsd:init Skip to Phase 3 overrides the normal sequential order. /wsd:init Work on the caching feature points the Task-Master toward a specific branch of the hierarchy. In the default mode, without a directive, the algorithm is fully automatic: it reads the current state of the project’s checkboxlists and determines the next appropriate piece of work without human intervention.

The complete specification of the selection algorithm, including sizing guidelines and comprehensive examples, lives in the Workscope System documentation (docs/read-only/Workscope-System.md) within your WSD installation. For daily use, the practical understanding is sufficient: the Task-Master reads your task lists, follows links to find the deepest available work, selects an appropriately sized chunk, and creates an immutable workscope file that defines the assignment.

But where does this work come from? The task lists that drive workscope assignment are part of a larger organizational structure. The next guide explores Work Plan Documents: the hierarchy of executable planning documents that forms the navigable backbone of your entire project.

Footnotes

1. A. Kumar, Y. Bajpai, S. Gulwani, G. Soares, and E. Murphy-Hill, “Why AI Agents Still Need You: Findings from Developer-Agent Collaborations in the Wild,” in Proc. 40th IEEE/ACM Int. Conf. Automated Software Engineering (ASE), 2025, pp. 432-444. ↩

2. @svpino, X (formerly Twitter). [Online]. Available: https://x.com/svpino/status/1978798588810703342 ↩

3. N. F. Liu et al., “Lost in the Middle: How Language Models Use Long Contexts,” Trans. Assoc. Comput. Linguist., vol. 12, pp. 157-173, 2024. ↩

4. Y. Du et al., “Context Length Alone Hurts LLM Performance Despite Perfect Retrieval,” in Findings of EMNLP, 2025. [Online]. Available: https://arxiv.org/abs/2510.05381 ↩