Design Mode and Compilation Mode

Two Modes, One Interface

The prevailing assumption in AI-assisted development is that the prompt box is a homogeneous interface. You type a request, the AI responds, you type another. The interaction is always the same kind of activity, a conversation where you tell the AI what you want and it tries to deliver. Tools like “plan mode”¹² hint that something more nuanced is going on, but the dominant mental model remains: one box, one activity, one way of working.

This model is incomplete, and it explains a great deal about why unstructured AI workflows feel chaotic. The prompt box hosts two fundamentally different activities sharing an interface that looks identical in both cases. Recognizing this, learning to see which mode you are in even though the terminal never changes, is one of the more useful shifts you can make in AI-assisted development.

The first mode is what happens when you run /wsd:init --custom and start talking through a design problem. You are sketching a feature, debating trade-offs, resolving conflicts between specifications, writing the documents that will define your project’s next phase of growth. This is Design Mode: specification-layer work where the engineer’s real thinking happens.

The second mode is what happens when you run the four-command ceremony: /wsd:init → /wsd:prepare → /wsd:execute → /wsd:close. The Task-Master selects work from your checkboxlists. The preparation agents load context. The User Agent executes the assigned tasks. The QA gauntlet validates the results. You supervise, handle user action items, and start a fresh session. This is Compilation Mode: the semi-automated process of converting your specifications into working software.

The cognitive difference between these modes is stark. Design Mode is intense and hands-on. You are composing careful prompts, challenging the AI’s assumptions, thinking deeply about edge cases and architectural implications. The quality of the output depends directly on the quality of your engagement. Compilation Mode is lean-back and routine. The system handles task selection, context loading, execution, and quality assurance. Your role shifts from director to supervisor: confirming workscope assignments, monitoring the work journal, reviewing results, and intervening only when the agents escalate something to you.

Both modes use the same terminal, the same AI, the same project. But they demand different things from you, and understanding which mode you are in helps you allocate your attention where it matters most. The hard thinking belongs in Design Mode. The disciplined execution belongs in Compilation Mode. WSD’s architecture exists to make Compilation Mode as lean as possible, so that you can spend your cognitive energy where it counts.

Design Mode

Design Mode begins with /wsd:init --custom. This entry point initializes a WSD session but skips the Task-Master’s automatic work selection, returning control to you for an interactive collaboration. You bring the problem; the AI brings its ability to synthesize, challenge, and formalize.

This is where features are born. You describe what you want to build, and the conversation becomes a design session, working through requirements, identifying conflicts with existing specifications, debating approaches, and gradually converging on a design that accounts for the edge cases you would have discovered three phases into implementation. When the design is solid, you run /create-feature to generate the Feature Overview specification, or you draft a ticket, or you refine an existing Work Plan Document.

Design Mode is also where you create your project’s foundational documents — the PRD, the Action Plan, the design decisions that will govern how agents build your project. Each of these is produced in a dedicated session, cycling to a fresh context between documents for clarity and focus.

What distinguishes Design Mode from casual prompting is intentionality. A good prompt is a carefully composed engineering artifact, written in a scratch file, edited for precision, reviewed before submission. The quality of what you send determines the quality of what you receive.

This is where the engineer’s expertise adds the most value. An AI assistant can write code, run tests, and check formatting. But it cannot decide what the product should be, how features should interact, or which trade-offs serve the project’s long-term interests. Those decisions happen in Design Mode, and they are the decisions that matter most.

Compilation Mode

Compilation Mode is the four-command ceremony at its most routine:

/wsd:init → /wsd:prepare → /wsd:execute → /wsd:close

The engineer’s role shifts from director to supervisor. You confirm that the Task-Master selected the right tasks. You glance at the work journal to monitor progress. You review results after the QA gauntlet completes. You handle the occasional judgment call that gets escalated. And then you start fresh and do it again.

What makes Compilation Mode powerful is what it automates. Task selection, context loading, execution, and quality assurance all happen within the ceremony. The Implementation Loop guide covers the operational details, including git practices, post-workscope activities, and recovery from failed sessions.

This is the mode where your specifications compile into software. The hard work of deciding what to build and how to build it happened in Design Mode. Compilation Mode is the execution engine that turns those decisions into reality, one workscope at a time. The loop runs as many times as needed, advancing through your checkboxlists until the work is done.

The Prompt Workspace

Behind Design Mode is a practice that transforms how you interact with your AI assistant: composing prompts in a dedicated workspace file rather than typing directly into the terminal.

The workspace is dev/prompts/Current-Prompts.md, a scratch file where you draft, edit, and refine your prompts before sending them. The wsd prompt command manages the lifecycle: it archives the current workspace with a timestamp and creates a fresh one. Over time, these archives accumulate into a chronological record of every instruction, every design discussion, and every decision you made during the project’s development.

This practice matters for several reasons. Writing in a file gives you editing freedom: you can restructure a complex prompt, add context you forgot, or rephrase an ambiguous instruction before the AI ever sees it. If a session fails or you want to retry with a different approach, your prompt is still there. And the act of composing a prompt in a separate space, rather than firing off a quick message, changes the quality of what you produce.³ And prompts written with care and revision may yield better results than prompts that are streamed and submitted.⁴

The workspace also serves as a place for personal notes. Brainstorming, observations, frustrations, ideas that are not ready to become prompts — all of these can live alongside your active work. They are captured in the archive and can be surfaced later through prompt processing.

A companion file, Developer-Notes.md, lives in the same directory as a persistent private scratchpad for thoughts you want to preserve but not act on immediately. The entire dev/prompts/ directory is intentionally restricted from agent access. Agents could stumble across archived conversations from previous sessions and become confused by outdated context. The prompt workspace is a space reserved for the human developer, where thinking happens without AI observation.

Over time, these prompt archives become a valuable resource in their own right. The /process-prompts command can extract insights from your accumulated prompts into persistent, customizable reports. See Prompt Processing for details.

Maintaining Your Workflow

The two-modes pattern and the prompt workspace are not features you configure once and forget. They benefit from ongoing attention — small maintenance habits that keep the workflow healthy and the archives useful.

Cycle your prompt workspaces at natural breakpoints. Run wsd prompt to archive the current workspace and start fresh — daily, after completing a cohesive collection of tasks, or whenever the current file has grown long enough that scrolling becomes tedious. There is no rigid rule. Roll over when it makes sense. The archives are there for later reference and processing.

Process your prompts periodically. Running /process-prompts after a significant stretch of work surfaces insights while they are still fresh enough to act on. The reports accumulate over time, building a richer picture of your project’s evolution with each processing pass.

Use the interview skill for brainstorming. The /interview skill provides a structured way to externalize ideas by speaking rather than typing, with the AI handling the synthesis into written form. This is particularly useful when you have unstructured thoughts that need formalization. The difference between speaking and typing is real: humans think differently in each mode,⁵⁶ and the interview format leverages this to capture richer, more nuanced input.

The rhythm that emerges is one of alternation. Design Mode sessions produce the specifications and plans. Compilation Mode sessions execute them. Prompt maintenance keeps the workspace clean and the archive useful. Over time, the boundary between the modes becomes intuitive. You know which mode you are entering before you type the first command, and you know what each mode demands of you. That awareness is the insight this guide set out to name.

Footnotes

1. Anthropic, “Common Workflows — Claude Code,” Anthropic Documentation. [Online]. Available: https://code.claude.com/docs/en/common-workflows ↩

2. Anysphere, “Plan Mode — Cursor Agent,” Cursor Documentation. [Online]. Available: https://cursor.com/docs/agent/plan-mode ↩

3. L. Flower and J. R. Hayes, “A Cognitive Process Theory of Writing,” College Composition and Communication, vol. 32, no. 4, pp. 365-387, Dec. 1981. Writing as a recursive cognitive process involving planning, translating, and reviewing — stages that composing in a file enables but typing into a chat box collapses. ↩

4. D. Kahneman, Thinking, Fast and Slow. New York, NY: Farrar, Straus and Giroux, 2011. Composing in a separate file engages deliberate System 2 thinking; typing directly into a chat box invites automatic System 1 thinking. ↩

5. W. Chafe, “Integration and Involvement in Speaking, Writing, and Oral Literature,” in Spoken and Written Language: Exploring Orality and Literacy, D. Tannen, Ed. Norwood, NJ: Ablex, 1982, pp. 35-53. ↩

6. W. J. Ong, Orality and Literacy: The Technologizing of the Word, 30th Anniversary ed. New York, NY: Routledge, 2012. ↩