Work Plan Documents

What Is a Work Plan Document?

Most software projects have specifications — documents that describe what should be built, how components should interact, what the requirements are. These specifications are valuable, but they share a common limitation: they sit apart from the work. The specification says what to build. A separate task tracker or project board says what to do next. The two systems coexist but don’t truly integrate, and the gap between them is where context gets lost, priorities drift, and work falls through cracks. This is known as the requirements traceability problem.¹²

A Work Plan Document (WPD) aims to mitigate this gap by combining both functions into a single artifact. A WPD is a document that contains a specification (the description, requirements, design rationale) and a checkboxlist that breaks the work into concrete, assignable tasks organized into phases. The specification and the task list live together, in the same file, governed by the same version control history.

This combination is what makes WPDs executable documentation.³⁴ They are structured instructions that the Task-Master can parse, the agent team can execute, and the developer can track. When a WPD’s checkboxlist is complete, the work described by its specification is done. There is no separate system to reconcile.

WSD uses four types of Work Plan Documents, each serving a different scope:

The Action Plan is the root WPD for the entire project. It lives at docs/core/Action-Plan.md and contains the highest-level breakdown of everything the project needs to accomplish. Its checkboxlist is the starting point for every workscope search.

Feature Overviews are WPDs for substantial features. Each lives in its own directory under docs/features/ and contains a feature specification paired with a Feature Implementation Plan (FIP) — the checkboxlist that decomposes the feature into implementable phases and tasks.

Tickets are WPDs for narrower-scope work: bug fixes, investigations, small alterations, refactoring tasks. They live in docs/tickets/open/ while active and move to docs/tickets/closed/ when complete. Tickets follow the same specification-plus-checkboxlist structure as Feature Overviews, just for smaller units of work.

Workbench Artifacts are temporary documents created in docs/workbench/, some of which could be structured as WPDs. These are useful for investigations, audits, or other focused work that needs a checkboxlist but doesn’t rise to the level of a feature or ticket. These are working documents — they may be promoted to permanent locations or archived when their purpose is fulfilled.

The Action Plan

The Action Plan is the root of your project’s work hierarchy. Every piece of work in the project connects to it, either directly as a task in its checkboxlist or indirectly through a chain of references that ultimately leads back to it.

When you create a project’s Action Plan during setup, you are defining the high-level shape of everything that needs to happen. The phases might represent major milestones: Phase 1 for foundational setup, Phase 2 for core feature implementation, Phase 3 for testing infrastructure, and so on. Within each phase, items might be directly actionable tasks or references to other documents where the detailed work lives. The Action Plan ends up functioning as a table of contents where each entry links to a document with its own detailed task list, all navigable by the agent team.

The Action Plan is also a progress indicator. Because parent task states reflect their children’s states, you can glance at the top-level items and immediately see which areas of the project have remaining work and which are complete. A feature that’s fully implemented shows as completed in the Action Plan even though the actual tasks were tracked in the feature’s own checkboxlist.

Features and Tickets

Feature Overviews and Tickets are where most of the detailed work lives. They extend the Action Plan by providing the granularity that a high-level project plan cannot.

A Feature Overview is the primary specification for a feature. It contains everything an agent needs to understand the feature: what it does, why it exists, how it should behave, what design decisions were made, and how it integrates with the rest of the system. At the end of the specification, the Feature Implementation Plan (FIP) breaks the feature into phases and tasks. The FIP is where the actual implementable work is defined: specific, concrete tasks that can be selected for workscopes. The Organizing Your Project guide covers the practical workflow for creating features and linking them into the Action Plan.

Tickets serve a similar purpose for smaller-scope work: bugs, refactoring opportunities, and small investigations. Each ticket is a WPD with a description of the issue and a checkboxlist for resolving it. Tickets live in docs/tickets/open/ while active and move to docs/tickets/closed/ when the Task-Master completes their final items. The Organizing Your Project guide covers ticket creation and management in detail.

Ticket placement matters. A bug discovered in the caching feature should be referenced in the caching feature’s Phase 0, not in the root Action Plan’s Phase 0. This scoping ensures that the blocking issue affects only the work it actually blocks, rather than halting the entire project. The root Action Plan’s Phase 0 is reserved for issues that genuinely affect the project at the highest level.

Tickets can also nest. A ticket investigating one issue might discover a deeper problem that spawns its own ticket. The original ticket references the new one in its Phase 0, creating a stack of blocking work that resolves naturally from the bottom up.

The WPD Tree

The Action Plan, Feature Overviews, Tickets, and workbench artifacts connect to each other through cross-document references, forming a navigable hierarchy called the WPD Tree.

The mechanism is simple. A task in one checkboxlist can reference another document by including a parenthetical link: [ ] **3.5** - Implement caching (see docs/features/caching/Caching-Overview.md). This reference creates a parent-child relationship between the task and the linked document’s checkboxlist. The task in the Action Plan is the parent; the tasks in the caching feature’s FIP are the children.

This relationship has practical consequences. State propagation flows bidirectionally through the hierarchy. If the caching feature’s FIP has unfinished items, the parent task in the Action Plan stays unaddressed — even if no one has explicitly touched the Action Plan. When all items in the caching feature’s FIP are completed or skipped, the parent task in the Action Plan reflects that completion automatically. You never need to manually update the Action Plan to say “caching is done.” The system propagates that state for you.

The WPD tree can extend to arbitrary depth. The Action Plan references a feature spec. The feature spec references a ticket discovered during implementation. The ticket references another ticket discovered during the first ticket’s investigation. Each level adds specificity, and the Task-Master navigates this entire hierarchy using depth-first search to find the deepest available work.

The value of the WPD tree is in the emergent structure that arises from many connections. After working with a project for a while, you develop an ambient awareness of the tree’s shape. You know that Phase 4 of the Action Plan contains the API features, that each feature has its own specification with a multi-phase implementation plan, and that tickets pop up when issues are discovered during implementation. This awareness is not something you need to memorize — it develops naturally through repeated interaction with the system.

Software engineering is, in many ways, the management of cycles within cycles.⁵

Navigation Pointers vs. Leaf Tasks

The WPD tree works because of a fundamental distinction between two types of tasks in a checkboxlist.

Navigation pointers are tasks that reference another document. They contain a parenthetical like “(see docs/features/…)” or “(see docs/tickets/open/…)”. A navigation pointer says “the actual work lives in the linked document.” It serves as a tracking node: its state reflects the state of the work in the linked document, and it provides a connection point in the WPD tree. Navigation pointers are never assigned as work. They are waypoints, not destinations.

Leaf tasks are specific, concrete actions with clear completion criteria. “Add validation to the configuration parser.” “Write integration tests for the caching layer.” “Update the API schema to include the new endpoint.” These are the tasks that workscopes are made of.

This distinction matters because it determines how you structure your Action Plan. High-level items in the Action Plan are typically navigation pointers — they point to Feature Overviews or tickets where the detailed work lives. The actual implementable tasks are leaf nodes deep in the tree, within the FIPs of individual features or the checkboxlists of individual tickets. The Action Plan provides the navigable overview; the linked documents provide the executable detail.

Phase 0: The Emergency System

Phase 0 is the most commonly misunderstood concept in WSD’s task system, and getting it right matters because it affects how the Task-Master prioritizes all work in a checkboxlist.

Phase 0 is not for foundational work. It is not “Phase 0: Setup” or “Phase 0: Prerequisites.” When you create a new checkboxlist, it should begin with Phase 1. Phase 0 is a reserved section that only appears when something goes wrong — a dedicated emergency system for blocking issues discovered during implementation.

Here is a typical scenario. You are implementing Phase 3 of a feature when you discover that the data model design from Phase 1 has a flaw that prevents your current work from proceeding. You cannot fix it within your current workscope because it requires a focused investigation and possibly a redesign. So you open a ticket describing the issue and add a reference to it in Phase 0 of the feature’s checkboxlist.

This creates a natural stack behavior. Imagine a feature is being implemented when a blocking bug is discovered — that bug goes into the feature’s Phase 0. While investigating the bug, the developer discovers a deeper issue in a shared utility — that spawns a new ticket, which gets referenced in the Action Plan’s Phase 0. Now the Action Plan’s Phase 0 blocks everything until the utility issue is resolved. Once it is fixed and the ticket is closed, the Action Plan’s Phase 0 clears, which unblocks the feature’s bug fix, which once resolved clears the feature’s Phase 0, which unblocks the original implementation work. The stack unwinds naturally as each issue is resolved.

Scoping Phase 0 items narrowly is important. A bug in the caching feature belongs in the caching feature’s Phase 0, not in the root Action Plan’s Phase 0. If you put it in the Action Plan, it blocks all project work — not just caching. If you put it in the caching feature’s checkboxlist, it blocks only caching work while the rest of the project continues. Place Phase 0 items at the most specific level that accurately represents what they actually block.

Phase 0 also serves as an archaeological record. Looking back at a completed feature’s Phase 0 tells you what blocking issues were encountered and resolved during implementation — a narrative of the challenges that shaped the final design. An empty Phase 0 (or no Phase 0 at all) means the implementation went smoothly. A Phase 0 with several resolved items tells you what problems were encountered and solved along the way.

The WPD tree gives your project a navigable work hierarchy — but those documents need somewhere to live. The Action Plan, Feature Overviews, Tickets, working notes, standards, reports, and temporary artifacts all have different audiences, lifecycles, and management needs. The next guide covers the documentation system: the directory architecture that organizes all of this information so that agents can find the right context at the right time.

Footnotes

1. O. Gotel and A. Finkelstein, “An Analysis of the Requirements Traceability Problem,” in Proc. IEEE Int. Conf. Requirements Engineering, 1994, pp. 94-101. ↩

2. P. Rempel and P. Mader, “Preventing Defects: The Impact of Requirements Traceability Completeness on Software Quality,” IEEE Trans. Software Eng., vol. 43, no. 8, pp. 777-797, Aug. 2017. ↩

3. D. E. Knuth, “Literate Programming,” Comput. J., vol. 27, no. 2, pp. 97-111, 1984. ↩

4. G. Adzic, Specification by Example. Shelter Island, NY: Manning, 2011. ↩

5. The industry folk term for this recursive nesting is “yak shaving.” See S. Hanselman, “Yak Shaving Defined,” hanselman.com. [Online]. Available: https://www.hanselman.com/blog/yak-shaving-defined-ill-get-that-done-as-soon-as-i-shave-this-yak. ↩