Getting Started

Your First Project

Create your project's core documents and run your first workscope cycle with WSD.

Creating Your PRD

Every WSD project begins with two foundational documents. The first is a Product Requirements Document (PRD) at docs/core/PRD.md. This document introduces your project to every AI agent that will work on it: what you are building, why it matters, who it serves, and what constraints shape the design.

Start a new Claude Code session and run /wsd:init --custom. This initializes a WSD User Agent that understands the system, generates a session identifier and work journal, and then returns control to you for a custom assignment. Tell the agent that you want to create the project’s PRD. Describe your project: its goals, its high-level architecture, the problems it solves, the technologies you plan to use. Work interactively: ask questions, explore edge cases, refine the scope. The agent will draft the PRD and write it to docs/core/PRD.md.

The PRD does not need to be perfect on the first pass, just an honest snapshot of your current thinking. As the project evolves, you will update it. What matters now is that every future agent session starts with a real understanding of what this project is.

After the PRD is complete, either clear or exit Claude Code. Session cycling between major documents is a core WSD discipline (the Implementation Loop guide covers the reasoning in detail). The PRD is persisted to disk, so a fresh session picks up everything it needs.

Creating Your Action Plan

Relaunch Claude Code and run /wsd:init --custom again. This time, the goal is to create the project’s Action Plan at docs/core/Action-Plan.md.

The Action Plan is a phased, hierarchical task list that drives the entire workscope assignment system. It breaks your project into numbered phases, and each phase into numbered tasks. When a workscope cycle runs, the Task-Master agent reads this plan to determine what work should be done next. Without an Action Plan, the Task-Master has nothing to work from. This document is the bridge between setup and execution.

Work interactively with the agent to design the plan. Discuss how to approach the project, what to tackle first, and where the natural breakpoints fall. A practical guideline for the first phase: aim to create a minimal version of your project in its intended shape. If you are building a web application, Phase 1 might produce a blank page with routing configured. If you are building a CLI tool, it might produce a command that prints “hello world.”

The goal is to get the project’s skeleton in place (code structure, test suite, tooling) so that everything else has a foundation to build on. You should include coverage for documentation and automated testing as well. If there are other planning documents that you will need (database schema, technical spec, game design), you can add their research and construction as phases or work items in the plan. If there is a specific framework or tools (pydoc, eslint, ruff, jest) you intend to use, you should discuss including work items to install and integrate these as well.

This is also the moment to address a question that may already be forming: why all this planning? The answer is practical, not philosophical. What you are doing by creating these documents is setting an engineering foundation that makes the growth of the project smoother and more robust. AI assistants work dramatically better when they have clear assignments, curated context, and defined completion criteria.¹² The ceremony of creating a PRD and Action Plan pays for itself within the first few workscope cycles, when you see agents executing precisely scoped tasks instead of wandering through vague objectives.

After the Action Plan is complete, commit your work. You now have the two documents that every WSD project needs to begin.

Running Your First Workscopes

Notice the shift that is about to happen. The PRD and Action Plan sessions were intense, interactive collaborations — you drove the conversation, made design decisions, and shaped the output directly. What comes next feels very different. The system selects the work, loads the context, executes the tasks, and runs quality checks. Your role shifts from director to supervisor. This shift is deliberate, and the Design Mode and Compilation Mode guide explores it in depth once you have more experience to anchor it.

With the Action Plan in place, the standard workscope cycle begins. This is the four-command sequence you will use repeatedly throughout the life of your project (the Implementation Loop guide covers the full rhythm):

/wsd:init — The Task-Master examines your Action Plan and creates a formal workscope defining the next piece of work.
/wsd:prepare — Specialized agents gather relevant documentation, source code, and project rules for the assignment.
/wsd:execute — The agent performs its assigned tasks, maintaining a work journal you can monitor in real time.
/wsd:close — You review the results and accept the completed work. The system updates task lists and archives session documents.

After closing, start a fresh Claude Code session and repeat. Each cycle picks up where the last one left off.

The early workscopes build out your project’s foundation: establishing the directory structure, bringing in core libraries, setting up the test suite. If your project is still in the “codeless” phase at this point, the QA agents will not have much to check — there are no tests to run and no code to lint. That is expected. The workflow is the same regardless; the quality checks simply become more meaningful as the project takes shape.

If the Task-Master selects work that does not match what you want to focus on, you can guide it with a directive: /wsd:init Just do 1.3 or /wsd:init Skip to Phase 2. The Task-Master follows your direction while still creating the formal workscope documentation.

Integrating WSD Tools (Re-Setup)

Once your project has code and a test suite in place — even a minimal one — re-run /wsd:setup in a new Claude Code session. The setup command detects the changes since its initial configuration and updates accordingly. A project that started as “codeless” will now be recognized as a Python project, a TypeScript project, or whatever languages your code uses.

This is the point where WSD’s quality tooling activates. After re-setup:

Run wsd test to verify your test suite executes correctly through the task runner
Run wsd health to verify the comprehensive health check works — this covers build integrity, type checking, security scanning, dependency auditing, linting, and code formatting

If either command reveals configuration issues, address them now. Ensure that your check directories are pointing to the right locations — [tool.wsd] check_dirs in pyproject.toml for Python projects, or wsd.checkDirs in package.json for Node.js projects. These tell WSD’s quality tools which directories contain your product code and tests.

Commit once the tooling is fully configured. From this point forward, the QA gauntlet has real work to do.

Your First Full Cycle with QA

Run another workscope cycle, but this time, pay attention to what happens during /wsd:execute after the agent completes its assigned tasks. This is where the QA gauntlet activates.

Several Special Agents independently review the completed work: checking specification compliance, standards adherence, test coverage, and code health. Each can reject the work, and the User Agent must fix the problem before proceeding. The Agent Team guide covers each agent’s role, the veto power model, and the proof-of-work requirement that ensures agents actually perform their reviews.

When a Special Agent finds a problem, the User Agent fixes it and resubmits. If an issue cannot be resolved, the User Agent escalates it to you with a clear explanation. The work journal captures everything throughout this process — you can monitor it in real time.

After the QA gauntlet passes and you review the results, run /wsd:close to accept the work. The cycle is complete.

Understanding What Just Happened

You have now experienced the complete WSD workflow. Before moving on, here are the key concepts you just encountered. Each has a dedicated guide that goes deeper now that you have firsthand experience to anchor it.

Workscopes are formally documented, immutable work assignments that prevent scope creep. The Understanding Workscopes guide covers the mechanics.

The Agent Team prepared context, executed your assignment, and validated the results through the QA gauntlet. The Agent Team guide covers each agent’s role and the enforcement model.

Checkboxlists are the hierarchical task lists (like your Action Plan) that drive workscope assignment. The Understanding Workscopes guide explains how the Task-Master navigates these lists across documents.

The Work Journal is the session log you monitored during execution, providing real-time visibility and a persistent audit trail across sessions.

Two modes of interaction emerged from the work you just did. The PRD and Action Plan sessions were hands-on design collaborations. The workscope cycles were semi-automated execution. These are fundamentally different cognitive activities, and recognizing which mode you are in changes how you allocate your attention. The Design Mode and Compilation Mode guide develops this distinction.

Together, these concepts create something ad hoc AI interactions cannot provide: continuity and genuine quality assurance. The tenth workscope cycle is more effective than the first because the system accumulates project knowledge over time.

If the ceremony felt heavy for the simplicity of the work — and it may have, especially on a fresh project with minimal code — that is a fair observation. The structure is designed for the long arc of a project’s life, not for the first fifteen minutes. The overhead stays roughly constant. The benefit scales with the project.³