Special Keywords

Roles and Agents

WSD organizes work around a team metaphor. The humans and AI assistants involved in a project each have distinct roles, and the terminology reflects those distinctions precisely.

User is always the human developer — the person directing the project, making design decisions, reviewing agent work, and holding final authority over everything. WSD documentation never uses “User” to refer to an AI. When a rule says “only the User can authorize this,” it means a human must make that call.

End-User refers to the future consumer of the software that you are building, distinguishing between yourself (the User interacting with the AI agent) and the human interacting with the resulting product.

User Agent is the AI assistant that occupies a Claude Code session. Each session gets a fresh User Agent with no memory of previous sessions. It executes the assigned workscope, coordinates with Special Agents, and serves as the communication hub between the developer and the agent team. See the Agent Team guide for the full coordination model.

Special Agents are domain-specific AI assistants invoked as sub-agents by the User Agent. Each has a narrow area of expertise — the Task-Master assigns work, the Context-Librarian finds relevant documents, the Rule-Enforcer checks standards adherence, and so on. They start fresh with every invocation and communicate with the developer only through the User Agent. See the Agent Team guide for each agent’s role and responsibilities.

Session Cycling is the practice of starting a fresh AI session for each workscope rather than continuing in a long-running one. Models perform better with lower accumulated context,¹² and WSD is designed around this principle — all necessary context is loaded from disk rather than carried in conversational memory. See the Implementation Loop guide for the reasoning and practical rhythm.

Work Structure

WSD transforms abstract project goals into concrete, trackable, assignable work through a hierarchy of documents and task lists.

Workscope is a formally defined, immutable unit of work assigned to a User Agent for a single session. Once created, the workscope file never changes — preventing the scope creep that plagues unstructured AI interactions. See the Understanding Workscopes guide for the complete mechanics.

Work Journal is the real-time session log that a User Agent maintains throughout its workscope. It records initialization steps, context gathered from Special Agents, execution decisions, QA results, and user action items — a running narrative of everything the agent did and why. Each journal is named with its session’s workscope ID and stored permanently at dev/journal/archive/Journal-Workscope-YYYYMMDD-HHMMSS.md. A symlink at dev/journal/Current-Journal.md always points to the active session’s journal, allowing you to monitor the agent’s progress in real time.

Checkboxlist is a hierarchical, numbered task list with five checkbox states: [ ] (unaddressed), [%] (incomplete/unverified), [*] (assigned), [x] (completed), or [-] (skipped). Parent items reflect the state of their children, creating a scannable progress map. See the Understanding Workscopes guide for the full state system.

Phase 0 (Zero) is a reserved phase in a checkboxlist for blocking issues discovered during implementation — not for foundational work. Any unaddressed Phase 0 item blocks all regular-phase work until resolved. See the Work Plan Documents guide for the complete Phase 0 model including stack behavior.

Work Plan Document (WPD) is any document that combines a specification with a checkboxlist — “executable documentation” that the Task-Master can parse and the agent team can execute. The Action Plan, Feature Overviews, tickets, and workbench artifacts with checkboxlists are all WPDs. See the Work Plan Documents guide.

Action Plan is the root checkboxlist governing an entire project, located at docs/core/Action-Plan.md. All other checkboxlists connect to it through cross-document references, forming the WPD tree. See the Work Plan Documents guide.

Feature Overview is a WPD for a feature, containing both the feature’s design specification and a Feature Implementation Plan (checkboxlist). Each resides at docs/features/feature-name/Feature-Name-Overview.md. See the Organizing Your Project guide for the creation workflow.

Ticket is a WPD for a bug fix, investigation, or smaller alteration. Tickets reside in docs/tickets/open/ while active and move to docs/tickets/closed/ when complete. See the Organizing Your Project guide for ticket management.

Feature Implementation Plan (FIP) is the checkboxlist at the end of a Work Plan Document. Although the name originated from Feature Overviews, it is used colloquially for the checkboxlist in any WPD — tickets, workbench artifacts, or the Action Plan itself. When someone refers to “the FIP,” they mean the actionable task list in the document under discussion.

WPD Tree is the navigable hierarchy formed by cross-document references between all Work Plan Documents in a project. The Task-Master traverses it using depth-first search to find the next appropriate work. See the Work Plan Documents guide for the full model.

Workflow Concepts

Escalation is the act of the User Agent halting work and returning to the developer to resolve a blocking issue — a Special Agent veto it cannot satisfy, a design ambiguity requiring a human decision, or a tool failure needing investigation. The agent presents the issue in full detail, since the developer does not have direct visibility into tool outputs or agent conversations.

Veto Power is the authority held by the Documentation-Steward and the Rule-Enforcer to reject a workscope submission outright. The User Agent must either fix the problem or escalate to the developer — it cannot override a veto. See the Agent Team guide for the enforcement model.

Proof of Work is the requirement for QA agents to include actual tool output in their reports — not just verdicts, but real test runner summaries and health check tables proving they executed their checks. See the Agent Team guide for the full accountability system.

Situational Awareness is the practice by which a User Agent establishes an understanding of how its individual tasks fit into the broader objectives of the phase and Work Plan Document it is working within. Rather than treating assigned tasks in isolation, a situationally aware agent understands the full arc of the work: what came before, what comes after, and what is intentionally deferred to later phases. This drives agents to orient themselves as members of a relay team sharing collective responsibility rather than individual contributors defending a personal scope.

QA Gauntlet is the quality assurance phase where multiple Special Agents independently review completed work — checking specification compliance, standards adherence, test coverage, and code health. Any agent can reject the submission. See the Agent Team guide for the full gauntlet.

In-Flight Failure (IFF) is a test failure caused by earlier phases of the current ticket that is scheduled for resolution in a later phase. IFFs are expected during multi-phase work and are not bugs. Health check violations are never IFFs. See the Advanced Techniques guide for the classification system.

Working Spaces and Artifacts

Workbench is the docs/workbench/ directory — the project’s working memory for documents that persist across sessions but are not permanent fixtures. The Context-Librarian manages this space. See the Documentation System guide for its role in the documentation hierarchy, and Organizing Your Project for practical usage.

Artifact is a file-based output created by an agent, typically written to the workbench. While most agent responses are given directly in conversation, an artifact is a document on disk that can be read by future agents or reviewed by the developer. The term signals a working product of the agent process, not permanent project documentation.

Document Promotion is the process of moving a document from the workbench to a permanent location. Agents draft in the workbench; the developer reviews and moves the document to its final home. This is required for docs/read-only/ (protected from agent writes) and available as a general practice for any document. See the Documentation System guide.

File Hoisting is a method of adding a file’s contents directly into an agent’s context by reference rather than asking the agent to read it. In Claude Code, this is accomplished using the @ + filename syntax in a prompt, which prepends the file’s contents to the message before the agent sees it. Hoisting guarantees that the agent receives the content, unlike a read instruction which the agent might fail to follow or deprioritize under context pressure.

Design Principles

Several principles recur throughout WSD documentation and guide how agents are expected to reason about their work.

Source of Truth is a principle that drives the convergence of definitions and declarations across a project. When a particular document or code module is declared the Source of Truth for a schema, configuration, or behavior, it holds authority in any conflict or inconsistency. This principle also motivates DRY (Don’t Repeat Yourself)³ practices: rather than defining something in multiple places where the definitions can drift apart, establish a single authoritative source and reference it from everywhere else.

Evergreen is a quality sought in specifications and code, meaning they avoid over-detailing to the point of sacrificing future-proofing. An evergreen specification describes what something does and why, without encoding assumptions about current implementation details that are likely to change.

Chesterton’s Fence is a principle cautioning against removing something whose purpose you do not understand.⁴ Before an agent dismantles a seemingly useless piece of design, code, or configuration, it should determine why it was constructed in the first place.

The thing may serve a purpose that is not immediately obvious.

Meta-Process References are internal references within planning documents — Workscope IDs, internal filenames, phase numbers, task references — that are essential for development coordination but must never appear in the final product. The shipped code should read as if the ephemeral planning artifacts that produced it never existed.

Karpathy Script (kscript) is a hybrid software artifact combining natural language instructions (interpreted by an AI) with traditional code (executed by a machine) to create a repeatable operation. See the Karpathy Scripts guide for the complete practice.

Footnotes

1. 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. ↩

2. 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 ↩

3. A. Hunt and D. Thomas, The Pragmatic Programmer, 20th Anniversary ed. Boston, MA: Addison-Wesley, 2019. “Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.” ↩

4. G. K. Chesterton, “The Drift from Domesticity,” in The Thing: Why I Am a Catholic. New York, NY: Dodd, Mead, 1929. ↩