| name | code-design |
| description | D-phase skill for the codesmith implementation workflow. Invokes render-design-doc-skeleton.py to overwrite the design.md placeholder with a tag-aware skeleton grounded in R-phase findings. Runs the always-interactive brain-surgery alignment conversation per Lock 6: agent presents each design section, human stress-tests via Question tool per substantive decision, iterate until aligned. Tracks the foundational-reversal strike counter per Lock 31. May identify multiple architecturally-distinct plans (NOT sub-tickets). Hands off to code-structure when D-phase is locked. |
Execute workflow by following instructions and producing output
Always read COMPLETE files - NEVER use offset/limit when reading any workflow related files
Instructions are MANDATORY - either as file path, steps or embedded list in YAML, XML or markdown
Execute ALL steps in instructions IN EXACT ORDER
Save to template output file after EVERY "template-output" tag
NEVER skip a step - YOU are responsible for every step's execution without fail or excuse
Steps execute in exact numerical order (1, 2, 3...) unless an explicit goto directs otherwise
Optional steps: Ask user unless YOLO mode active
Template-output tags: Save content, discuss with the user the section completed, and NEVER proceed until the user indicates to proceed (unless YOLO mode has been activated)
For each step in instructions:
<substep n="1a" title="Track Progress">
<action if="first iteration">Create todo list from all instruction step titles (TodoWrite)</action>
<action>Mark current step as in_progress (TodoWrite)</action>
</substep>
<substep n="1b" title="Handle Step Attributes">
<check>If optional="true" and NOT YOLO -> Use Question tool to ask user whether to include (Yes/Skip)</check>
<check>If if="condition" -> Evaluate condition</check>
<check>If for-each="item" -> Repeat step for each item</check>
<check>If repeat="n" -> Repeat step n times</check>
</substep>
<substep n="1c" title="Execute Step Content">
<action>Process step instructions (markdown or XML tags)</action>
<action>Replace {{variables}} with values (ask user if unknown)</action>
<execute-tags>
<tag>action -> Perform the action</tag>
<tag>action type="script" -> Execute as shell command, capture output</tag>
<tag>check if="condition" -> Conditional block wrapping actions (requires closing </check>)</tag>
<tag>ask -> Prompt user using Question tool and WAIT for response. When options exist, present them as selectable choices. For open-ended questions, provide helpful suggested options with custom input enabled</tag>
<tag>invoke-skill name="skill-name" -> Execute another skill via OpenCode skill system</tag>
<tag>invoke-agent name="subagent" prompt="task" -> Delegate to subagent via Task tool</tag>
<tag>goto step="x" -> Jump to specified step (used for explicit loop-back in Q-R style flows)</tag>
</execute-tags>
</substep>
<substep n="1d" title="Handle template-output Tags">
<if tag="template-output">
<mandate>Generate content for this section</mandate>
<mandate>Save to file (Write first time, Edit subsequent)</mandate>
<action>Display generated content</action>
<action>Use Question tool to present checkpoint options. WAIT for response.
<options>
<option label="Continue" description="Approve this section and move to the next step" />
<option label="Advanced Elicitation" description="Explore this section deeper before proceeding" />
<option label="YOLO" description="Auto-complete the rest of this workflow without stopping" />
</options>
<if response="Advanced Elicitation">
<action>Invoke advanced-elicitation skill</action>
</if>
<if response="Continue">
<action>Continue to next step</action>
</if>
<if response="YOLO">
<action>Enter YOLO mode for the rest of the workflow</action>
</if>
</action>
</if>
</substep>
<substep n="1e" title="Step Completion">
<action>Mark current step as completed (TodoWrite)</action>
<check>If no special tags and NOT YOLO:</check>
<action>Use Question tool to ask:
<options>
<option label="Continue" description="Proceed to the next step" />
<option label="Edit" description="Revise this step before moving on" />
</options>
</action>
</substep>
</step>
<step n="2" title="Completion">
<check>Confirm all instruction steps have been executed</check>
<output>Workflow complete.</output>
</step>
Full user interaction and confirmation of EVERY step at EVERY template output - NO EXCEPTIONS except YOLO mode
Skip all confirmations and elicitation, minimize prompts and try to produce all of the workflow automatically by simulating the remaining discussions with a simulated expert user
step n="X" goal="..." - Define step with number and goal
substep n="Xa" title="..." - Sub-step within a step
phase n="X" - Phase within a substep
optional="true" - Step can be skipped
if="condition" - Conditional execution
for-each="collection" - Iterate over items
repeat="n" - Repeat n times
action - Required action to perform
action type="script" - Execute shell command
action if="condition" - Single conditional action (inline, no closing tag needed)
check if="condition">...</check> - Conditional block wrapping multiple items (closing tag required)
ask - Get user input via Question tool (ALWAYS wait for response before continuing). Present defined options as selectable choices. For open-ended questions, offer helpful suggestions with custom input enabled
goto - Jump to another step (explicit loop-back)
invoke-skill - Call another skill
invoke-agent - Delegate to subagent via Task tool
invoke-protocol - Execute a reusable protocol (e.g., discover_inputs)
template-output - Save content checkpoint
critical - Cannot be skipped
example - Show example output
note - Informational content
output - Display to user without saving
halt-conditions - Define conditions that MUST stop execution
condition - Single halt condition
validation - Pre-condition rules to check
- This is the complete workflow execution engine
- You MUST follow instructions exactly as written
- This workflow uses INTENT-DRIVEN PLANNING - adapt organically to product type and context
- YOU ARE FACILITATING A CONVERSATION with a user to produce a final document step by step
- The whole process is meant to be collaborative - helping the user flesh out their ideas
- Do not rush or optimize and skip any section
Run D-phase: produce the design.md sibling artifact through an
always-interactive brain-surgery conversation. Highest-leverage
stage of the workflow per Lock 6.
<inputs>
Session state from code-grill (Q-R readiness met):
- bundle_dir, ticket_path, ticket_alias, ticket_slug, primary_tag
- design_path (placeholder from scaffold, status: draft)
- research_path (populated by code-grill)
</inputs>
<outputs>
design.md (kind: design, status: active → locked once D-phase
complete) with three populated sections:
- Current state (grounded in research)
- Desired end state (behavioral + structural)
- Design decisions (vertical slices, risk areas, multi-plan
identification)
Strike counter persisted across iterations for Lock 31
foundational-reversal abort.
</outputs>
<step n="1" title="Render Design Skeleton">
<action>Load and execute: references/steps/step-01-render-skeleton.xml</action>
</step>
<step n="2" title="Present Current State">
<action>Load and execute: references/steps/step-02-current-state.xml</action>
</step>
<step n="3" title="Present Desired End State">
<action>Load and execute: references/steps/step-03-desired-end-state.xml</action>
</step>
<step n="4" title="Present Design Decisions">
<action>Load and execute: references/steps/step-04-design-decisions.xml</action>
</step>
<step n="5" title="Identify Plans">
<action>Load and execute: references/steps/step-05-identify-plans.xml</action>
</step>
<step n="6" title="Lock and Handoff">
<action>Load and execute: references/steps/step-06-lock-and-handoff.xml</action>
</step>
D-phase produces the locked design.md. The skill hands off to
code-structure (S-phase) which converts design decisions into
the structural skeleton (files + signatures + test structure +
vertical slices).
