The Documentation System

Why Documentation Architecture Matters

The previous guide introduced Work Plan Documents (the Action Plans, Feature Overviews, and Tickets) that organize your project’s work into a navigable hierarchy. But they live alongside specifications, standards, working notes, reports, development artifacts, and temporary analysis files. Where each of these documents lives, how it is named, and how long it persists all determine whether the agents working on your project can find the information they need.

This matters because AI assistants do not have the ambient familiarity that human developers build over months of working in a codebase. A human developer remembers that “the caching design notes are in that file Sarah created last week.” An AI assistant starts fresh every session with no memory of previous work. When the Context-Librarian is asked to find documentation relevant to a caching workscope, it does not search the entire filesystem at random. It navigates a structured hierarchy where location implies purpose: core specifications live in docs/core/, feature documentation lives in docs/features/, active tickets live in docs/tickets/open/. The librarian knows where to look because the documentation system defines where things go.

The result is that document placement is an engineering decision that directly affects the quality of AI-assisted work. A document placed predictably in the right location gets surfaced when it matters. A document in an ad hoc directory with a vague name may never be found. The discipline of placing documents predictably is a form of context engineering that happens long before any agent is invoked.

The Two Hierarchies

WSD organizes project information into two top-level directories, each serving a different audience and purpose.

docs/ contains project documentation — specifications, plans, tickets, standards, working memory, and archived material. This is the intellectual infrastructure of your project: what you are building, why you are building it that way, what rules govern the work, and what is currently in progress. Agents spend most of their time reading from this hierarchy.

dev/ contains development artifacts — work journals, workscope records, diagnostic scripts, and the prompt workspace. These are the operational byproducts of the development process itself. While docs/ describes the project, dev/ records how the project is being built.

The distinction matters because it separates concerns that have different lifecycles, audiences, and management needs. A Feature Overview in docs/features/ is a permanent specification that any agent might need. A work journal in dev/journal/ is a session record that is rarely read after its session ends. Mixing these together would muddy both: agents searching for specifications would wade through session logs, and session logs would be scattered among permanent documents. The two-hierarchy design keeps each category clean and navigable.

The docs/ Hierarchy

docs/
├── core/            # Foundational project specifications
├── features/        # Feature-specific documentation (one directory per feature)
├── tickets/         # Issue tracking
│   ├── open/        # Active tickets
│   └── closed/      # Completed tickets
├── read-only/       # Rules, standards, and system documentation
│   └── standards/   # Coding and process standards
├── references/      # Reference material and templates
├── workbench/       # Active working memory for current focus
├── archive/         # Retired documents no longer relevant
├── reports/         # Tool-generated project documentation
└── public/          # End-User-facing documentation for publication

Each directory has a defined purpose, audience, and lifecycle:

docs/core/ holds the foundational documents that define the project: the PRD, the Action Plan, the Design Decisions. These are always relevant and always current. Every agent working on the project may need to reference them. Changes to core documents are deliberate and represent shifts in the project’s direction or design philosophy.

docs/features/[name]/ contains feature-specific documentation. Each feature gets its own directory with a Feature Overview specification and optionally supporting documents (schema definitions, component interaction documents, API contracts). When an agent works on a feature, the Context-Librarian surfaces the relevant feature directory. When an agent works on something unrelated, these directories are ignored. The per-feature directory structure is what makes this selective surfacing possible.

docs/tickets/ separates active work from completed work. Open tickets in docs/tickets/open/ are candidates for workscope assignment. Closed tickets in docs/tickets/closed/ are historical records. The Task-Master moves tickets between these directories when their checkboxlists are complete. This physical separation makes it trivial for agents to distinguish current issues from resolved ones.

docs/read-only/ contains the rules, standards, and system documentation that govern how agents work. Agent Rules, coding standards, the system overview documents — these are protected from agent edits and serve as the behavioral foundation for every session. The Project-Bootstrapper draws from this directory when educating agents about project expectations. The standards/ subdirectory holds language-specific coding conventions and process standards.

docs/references/ holds reference material and templates: the Action Plan Archive (completed phases moved out of the active Action Plan), document templates, and other material that informs work without being actively executed. These are permanent but less frequently accessed than core documents.

docs/workbench/ is your project’s active working memory. This directory is important enough to warrant its own section below.

docs/archive/ is where retired documents go when they are no longer relevant to active work. The Context-Librarian manages archival, moving documents here when their purpose is fulfilled. Archived documents are preserved for historical reference but are rarely surfaced as context.

docs/reports/ contains documentation generated by automated tools — code maps, project structure reports, and other machine-generated summaries. These are refreshed by running wsd docs and are not manually edited. They provide pre-computed context that agents can consume efficiently.

docs/public/ holds user-facing documentation intended for publication — website content, user guides, and other material that will be visible to end-users of the project.

The dev/ Hierarchy

dev/
├── journal/
│   └── archive/     # Work journals from every session
├── workscopes/
│   └── archive/     # Immutable workscope assignment files
├── diagnostics/     # Temporary scripts and one-off analysis (agent scratch pad)
└── prompts/         # Prompt workspace and archive (agent-restricted)

dev/journal/archive/ stores the work journals from every session, each named with the session’s workscope ID. These are the real-time records of what each agent did, what decisions were made, and what issues arose. They serve as an audit trail and are occasionally useful for debugging why a previous session produced unexpected results. The dev/journal/Current-Journal.md symlink allows for live monitoring of the latest work journal as it is written.

dev/workscopes/archive/ holds the immutable workscope files created by the Task-Master. Each file records the exact tasks assigned, the navigation path through the WPD tree, and the context documents identified. All agents (including Special Agents) will synchronize on these files while performing a workscope. These files never change after creation and accumulate as a permanent record of every work assignment.

dev/diagnostics/ is the scratch pad for agents: temporary scripts, one-off debugging tools, anything that serves the current session and can be deleted without loss. This provides a place for agents to create whatever they need for their current task, expecting that no future agent will need it.

dev/prompts/ contains the prompt workspace and its archives. As the Design Mode and Compilation Mode guide covers, this directory is intentionally restricted from agent access — it is a space reserved for the human developer’s thinking, where past conversations and personal notes live without risk of confusing future agents. The current prompt workspace is symlinked to dev/prompts/Current-Prompts.md, and new workspaces (archiving the old) can be created via wsd prompt.

Document Lifecycle

Every document in WSD exists somewhere on a spectrum from temporary to permanent. Learning to place documents at the right point on this spectrum is one of the more useful habits you develop with WSD.

Permanent Documents

Documents in docs/core/, docs/features/, docs/read-only/, and docs/references/ are permanent fixtures. Your PRD, your Action Plan, your Feature Overviews, your rules and standards — these persist for the life of the project and are always available as context for agents. They change through deliberate edits, not through lifecycle transitions. A Feature Overview might be updated as new phases are added, but it does not move or get archived; it stays in its feature directory as the authoritative specification for that feature.

Permanent documents in docs/read-only/ are hardened against agent manipulation and must earn their status through explicit human decision. An agent does not place documents directly into docs/read-only/ but instead must petition for document promotion (e.g., from the workbench). This gatekeeping is intentional.

Active Documents: The Workbench

The docs/workbench/ directory is your project’s working memory, a space for documents that need to persist across sessions but are not permanent fixtures of the project. It is the only location designed for documents with a medium lifespan: context for active work arcs, multi-session coordination artifacts, audit results, and draft specifications before promotion to a permanent location. The Organizing Your Project guide covers the practical details of working with the workbench.

The Context-Librarian assists with workbench lifecycle management, archiving documents to docs/archive/ when their purpose is fulfilled during the /wsd:close process. In practice this is a collaborative effort — you may occasionally archive documents yourself or override the agent’s suggestions. The key discipline is to evolve documents in place rather than creating versioned copies; git handles version history, and a single well-named document is far more discoverable than a collection of timestamped revisions.

Temporary Artifacts: Diagnostics

The dev/diagnostics/ directory holds the most ephemeral artifacts: temporary scripts, one-off debugging tools, and quick analysis files. Anything that serves the current session and can be deleted without consequence. It is scratch space.

The distinction between dev/diagnostics/ and docs/workbench/ comes down to a single question: will a future session need this?

• “I need a quick script to check how many tests reference the old API.” → dev/diagnostics/. The script serves its purpose and is done.
• “I have documented the patterns found in the test suite that will inform the next three workscopes of refactoring.” → docs/workbench/. Future sessions need this context.

Agents are trained to make this distinction when creating files during workscopes. A document that turns out to be unnecessary can always be archived, but useful context placed in diagnostics is invisible to future sessions. You can choose whether to clean out dev/diagnostics/ regularly, add it to .gitignore, or keep its contents tracked.

Document Promotion

Not all permanent documents start in the workbench. Many are created directly in their permanent locations through established workflows. When you run /create-feature, the Feature-Writer agent creates the Feature Overview directly in docs/features/. When you collaborate on a PRD during setup, it lands directly in docs/core/. The /open-ticket command creates tickets directly in docs/tickets/open/. These workflows place documents where they belong from the start.

Document promotion is the process of moving a document from the workbench to a permanent location, and it is a requirement for one particular directory: docs/read-only/. Because agents cannot write to docs/read-only/ (it is protected by file hooks), any new standard, rule, or system document that should live there must arrive through promotion. The agent drafts the document in the workbench, identifies it as a promotion candidate in its User Action Items, and the developer reviews it and moves it to its permanent home. When an agent needs to update an existing docs/read-only/ file, the same principle applies: it knows to first copy the file to the workbench, make its edits there, and then petition the developer to replace the original with the updated version after review.

Promotion is also available as a general practice beyond docs/read-only/. Some developers prefer a review-first workflow where agents draft documents in the workbench regardless of their eventual destination, giving the developer a chance to review before the document becomes a permanent fixture. A reference guide might be drafted in the workbench and promoted to docs/references/ after review. A project-wide design principle discovered during implementation might be formalized through /add-dd into the Design Decisions document. This is a matter of preference — the system supports both direct placement (through established commands) and staged promotion (through the workbench).

Naming and Placement Conventions

How you name and place documents has a direct impact on how effectively agents can find them. The documentation system works because location implies purpose — but this contract only holds when the conventions are followed consistently.

Filenames should be descriptive enough that the purpose is clear from the name alone. Use kebab-case, aim for 5-7 words, and choose terms that communicate the document’s content to an agent that has never seen it before. caching-layer-design-review.md tells an agent exactly what it will find. notes.md does not. phase-5-cli-cleanup-analysis.md communicates both the topic and the context.

Placement should follow the directory purposes described above for documents that participate in WSD’s workflows. The directories listed in this guide are the ones WSD’s agents know to navigate — the Context-Librarian searches them, the Task-Master traverses them, the Documentation-Steward monitors them. Documents placed in these locations are automatically discoverable.

You are encouraged to extend the directory structure with project-specific directories that serve your needs. A research project might add docs/experiments/. A book-writing project might add docs/character-profiles/. WSD provides the minimal skeleton it requires; your project’s documentation needs will likely go beyond that skeleton. The key understanding is that WSD’s agents will specially search the directories they know about — documents in your custom directories are available to agents but may benefit from extra direction in prompting, inclusion of the files via cross-referencing, or added to the WPD tree via linking. Agents themselves, however, should not invent new directories on their own. When an agent needs to place a document, it should use the established WSD directories (especially the workbench) rather than creating novel locations that future agents will not know to check.

Cross-referencing follows a natural pattern. Workbench documents frequently reference core documents. A draft feature spec in the workbench will reference the PRD’s requirements or the Design Decisions that govern the approach. Core documents generally do not reference workbench documents, because workbench content is temporary and a permanent document should not depend on something that may be archived. The exception is the Action Plan, which as the root of the WPD tree references everything through its checkboxlist, including tickets and features that may temporarily have workbench-based context documents.

How This Enables the Agent Team

The documentation system is the infrastructure that makes WSD’s agent team effective. The next guide introduces the specialized agents that prepare, validate, and enforce quality in your workflow. Many of those agents depend directly on the predictable structure described here.

The Context-Librarian navigates docs/core/, docs/features/, docs/tickets/, and docs/workbench/ with confidence because it knows what each location contains and what kind of documents to expect there. A caching workscope naturally points to docs/features/caching/ — the directory structure itself encodes the relevance relationship. The librarian navigates a hierarchy where location implies purpose.

The Project-Bootstrapper draws from docs/read-only/ to educate agents about rules and standards. The Documentation-Steward monitors docs/core/ and docs/features/ to ensure implementations match their specifications. The Task-Master traverses the WPD tree from the Action Plan through feature specs and tickets, a navigation that only works because those documents are placed in known, consistent locations.

This relationship between documentation structure and agent effectiveness is the foundation of context engineering — the principle that the quality of AI output depends directly on the quality of the information provided to it. Organizing your information so that it can be found is the essential first step. Everything else (the preparation agents, the context curation, the targeted file lists) builds on the assumption that documents are where the system expects them to be.