Organizing Your Project
Structure your Action Plan, create feature specifications, manage tickets, and use the workbench.
Writing Your Action Plan
The Action Plan at docs/core/Action-Plan.md is the root of your entire project’s work hierarchy. Every workscope, every feature, every ticket traces back up the WPD Tree to an entry in this document. Writing a good Action Plan matters because the structure you choose here shapes how the Task-Master assigns work for the life of the project.
An Action Plan is a checkboxlist organized into phases. Each phase groups related work under a descriptive heading, and each task within a phase is numbered hierarchically. If you followed the Your First Project guide, you created an initial Action Plan during setup, and the Core Concepts guides have since equipped you with the full vocabulary behind that experience: workscopes, checkboxlists, the WPD tree, and the documentation hierarchy. That Action Plan is now the living document that drives your project forward. As the project grows, you will return to it frequently, adding new phases, inserting features, and adjusting the structure to reflect the evolving reality of the work.
The most important structural decision in an Action Plan is the distinction between leaf tasks and navigation pointers, a concept covered in detail in the Understanding Workscopes guide. In brief: a leaf task is concrete, actionable work that an agent executes directly. A navigation pointer references another document (e.g., - [ ] **3.5** - Implement caching (see docs/features/caching/Caching-Overview.md)), signaling that the actual work lives elsewhere and the Task-Master should follow the link.
This distinction shapes how you structure your Action Plan. Most mature projects use a mix: some phases contain direct leaf tasks (especially early setup and configuration work), while others consist primarily of navigation pointers to feature specifications that contain their own multi-phase implementation plans. If your Action Plan contains only leaf tasks, every workscope draws directly from it. If it contains navigation pointers, the Action Plan becomes a high-level map and the detailed work lives in the linked documents.
When sizing phases, the system aims for coherent groupings rather than uniform size. A phase that covers “initial project setup” might have five tasks. A phase that covers “API implementation” might be a single navigation pointer to a feature specification that itself contains thirty tasks across four phases. The Action Plan’s job is to organize the project’s major arcs of work, not to enumerate every individual step. That level of detail belongs in the linked documents.
Agents know to keep the checkboxlist itself clean and uninterrupted. Headers should be placed immediately followed by their tasks, with no explanatory text between them. If a phase needs context — rationale for the ordering, dependencies between tasks, design considerations, that information will be placed in a section above the checkboxlist. The checkboxlist is a structural artifact that the Task-Master parses; mixing prose into it breaks the cohesion that makes the system work. As described in the Understanding Workscopes guide, this content separation is a fundamental rule of the checkboxlist system.
Creating Features
When your project reaches the point where a piece of work deserves its own specification (a new capability or a significant component) you create a feature. Features live in docs/features/ and each one gets its own directory containing a Feature Overview specification and optionally additional supporting documents.
The workflow begins in a design session. Start a new Claude Code session and run /wsd:init --custom to get a User Agent that understands the WSD system but is free to work on whatever you direct. Describe what you want to build. Discuss the design interactively. Explore edge cases, identify conflicts with existing systems, work through the architectural decisions. This is where the real engineering thinking happens. The AI is a collaborator in this conversation, but you are the designer.
When the plan is solid and the key decisions are settled, run /create-feature kebab-case-name. This command formalizes the design conversation into a Feature Overview specification at docs/features/kebab-case-name/Kebab-Case-Name-Overview.md. The specification includes a description of the feature, its relationship to existing systems, design constraints, and, critically, a Feature Implementation Plan (FIP) at the end. The FIP is a checkboxlist that breaks the feature’s implementation into phased, numbered tasks, just like the Action Plan but scoped to this specific feature.
After the Feature Overview is created, request that the agent add a navigation pointer to your Action Plan linking to the new feature. This connects the feature into the WPD tree, making it visible to the Task-Master during normal workscope assignment. The Task-Master’s depth-first search will eventually reach your Action Plan entry, follow the link to the Feature Overview, and begin assigning workscopes from its FIP.
For complex features, consider creating additional specification files alongside the Overview in the same feature directory — schema specifications, component interaction documents, API contracts. These become context that the Context-Librarian surfaces when agents work on that feature.
There is a discipline worth adopting early: harden your specifications before implementation begins. The /deep-review command orchestrates a multi-agent review of a specification document, cross-checking it against related files and surfacing gaps, contradictions, and ambiguities. Running deep review on a Feature Overview before its first workscope is an investment that pays for itself quickly. Fixing a design problem at the specification level costs a fraction of what it costs to fix during implementation, when code, tests, and other specifications have already been built on the flawed foundation.12
The goal is zero modification to a specification after workscopes begin — and while that is an ideal rather than an absolute, taking every step to approach it prevents the painful mid-flight rework that comes from discovering design flaws several phases deep.
Managing Tickets
Tickets are for work items that need attention but exist outside the current flow of planned work: bugs discovered during implementation, inconsistencies between components, improvements that surface during review. They live in docs/tickets/open/ and follow a structured format that includes a problem description, analysis, proposed solution, and an implementation checkboxlist.
Create a ticket by running /open-ticket during any session. You can optionally provide a description of the ticket as an argument, but otherwise the command analyzes the conversation context and generates a ticket document with an appropriate kebab-case filename. Like any checkboxlist document, the ticket ends with an implementation plan organized into phases. When the final task in the ticket’s checkboxlist is completed, the Task-Master automatically moves the ticket file from docs/tickets/open/ to docs/tickets/closed/.
The key decision with tickets is where to place their reference in the WPD tree, which you can also request the User Agent to perform when you open the ticket. This determines when the Task-Master encounters them during its depth-first traversal. You have several options depending on urgency and scope.
For issues that demand immediate attention, place the ticket reference in a Phase 0 section — the emergency blocking mechanism described in the Work Plan Documents guide. Scope the placement narrowly: a bug in the caching feature should go in the caching feature’s Phase 0 (blocking only caching work), not in the Action Plan’s Phase 0 (which would block the entire project).
For issues that can wait until a natural point in the work sequence, insert the ticket reference at an appropriate location in the relevant checkboxlist. The Task-Master will encounter it when the depth-first search reaches that position, just like any other task.
Tickets can nest. If a ticket’s implementation reveals a deeper issue, create a child ticket and add a reference to it in the parent ticket’s Phase 0. The system unwinds naturally as each issue is resolved, as described in the Work Plan Documents guide.
Updating Features
Projects evolve, and completed features sometimes need modifications. When new requirements emerge, when edge cases surface in production, or when a related feature exposes a gap in an earlier design, you need a way to revisit completed work.
There are two approaches, and the choice between them usually depends on how recently the feature was completed.
For recent features, those still in the active area of the Action Plan, the simplest approach is to uncheck the original Action Plan entry. This reverts the navigation pointer from [x] back to [ ], making it visible to the Task-Master’s depth-first search again. Because the feature sits higher in the tree (in already-completed work), the Task-Master will encounter it and begin assigning workscopes from its FIP. You will typically need to append new phases to the existing FIP describing the modifications, since the original phases are already complete.
For features completed long ago, especially those whose Action Plan entries have been archived to docs/references/Action-Plan-Archive.md — create a new entry in the Action Plan referencing the same Feature Overview. Label it descriptively so the intent is clear, something like “Revisit authentication for OAuth2 support.” This creates a fresh reference point in the active portion of the plan, making the Task-Master aware that the feature needs additional attention without disrupting the archived record of the original implementation.
In either case, the Feature Overview itself remains the authoritative specification. Append new phases to its FIP describing the additional work. The existing phases serve as a historical record of what was already done, and the new phases define what comes next. This preserves the complete narrative of the feature’s evolution in a single document.
Working with the Workbench
The Documentation System guide defines the docs/workbench/ directory as your project’s working memory — a space between the ephemeral diagnostics folder and the permanent documentation locations. In daily practice, here is how you use it.
What belongs in the workbench: context documents for active work arcs, multi-session coordination artifacts, audit results that inform ongoing decisions, draft specifications being developed before promotion to permanent locations. A feature brief created during a /create-feature session lands here. An investigation report that multiple agents need to reference across workscopes goes here. A refactoring plan that spans several sessions lives here until the refactoring is complete.
What does not belong: temporary scripts and one-off analysis tools go in dev/diagnostics/. Permanent documentation goes in its designated permanent location only when explicitly directed. The workbench is for the middle ground.
The Context-Librarian agent assists with lifecycle management, archiving documents to docs/archive/ when their purpose is fulfilled. You retain full control — archiving documents yourself, pulling things back, or overriding suggestions when a document is still relevant.
One key discipline: edit documents in place rather than creating new versions. Git handles version history. A single well-named document is far more discoverable than a collection of timestamped revisions.