| name | x-ipe-task-based-idea-mockup |
| description | Create visual mockups and prototypes for refined ideas. Use after ideation when idea needs visual representation. Invokes x-ipe-tool-frontend-design skill or other mockup tools based on x-ipe-docs/config/tools.json config. Triggers on requests like "create mockup", "visualize idea", "prototype UI", "design mockup". |
Task-Based Skill: Idea Mockup
Purpose
Create visual mockups and prototypes for refined ideas by:
- Reading the idea summary from ideation task
- Loading mockup tools from
x-ipe-docs/config/tools.json config
- Creating visual representations (UI mockups, wireframes, prototypes)
- Saving artifacts to the idea folder
- Preparing for Requirement Gathering
Important Notes
BLOCKING: Learn x-ipe-workflow-task-execution and x-ipe-tool-task-board-manager skills before executing this skill. Learn x-ipe-tool-frontend-design skill if enabled in config.
Note: If Agent does not have skill capability, go to .github/skills/ folder to learn skills. SKILL.md is the entry point.
CRITICAL: Focus ONLY on UI/UX presentation -- ignore all tech stack mentions. See references/mockup-guidelines.md for focus guidelines, tool mapping table, mockup type priorities, naming conventions, and summary update template.
Workflow Mode: When execution_mode == "workflow-mode", the completion step MUST run the workflow update script via bash: python3 .github/skills/x-ipe-tool-x-ipe-app-interactor/scripts/workflow_update_action.py with workflow_name from workflow.name input, action from workflow.action input, status: "done", and a deliverables keyed dict using ONLY the extract tags defined in workflow-template.json for this action (format: {"tag-name": "path/to/file"}). Do NOT pass a flat list of file paths. Verify the script exits with code 0 before marking the task complete.
IMPORTANT: When process_preference.interaction_mode == "dao-represent-human-to-interact", NEVER stop to ask the human. Instead, call x-ipe-assistant-user-representative-Engineer to get the answer. The DAO skill acts as the human representative and will provide the guidance needed to continue.
Input Parameters
input:
task_id: "{TASK-XXX}"
task_based_skill: "x-ipe-task-based-idea-mockup"
execution_mode: "free-mode | workflow-mode"
workflow:
name: "N/A"
action: "design_mockup"
extra_context_reference:
refined-idea: "path | N/A | auto-detect"
uiux-reference: "path | N/A | auto-detect"
category: "ideation-stage"
next_task_based_skill:
- skill: "x-ipe-task-based-requirement-gathering"
condition: "Proceed to requirements after mockup"
process_preference:
interaction_mode: "{from input process_preference.interaction_mode}"
ideation_toolbox_meta: "{project_root}/x-ipe-docs/config/tools.json"
current_idea_folder: "N/A"
extra_instructions: "N/A"
Input Initialization
<input_init>
<field name="task_id" source="x-ipe-tool-task-board-manager (auto-generated)" />
<field name="execution_mode" source="x-ipe-workflow-task-execution (from --workflow-mode@{name})" />
<field name="workflow.name" source="x-ipe-workflow-task-execution (from --workflow-mode@{name})" />
<field name="process_preference.interaction_mode" source="from caller (x-ipe-workflow-task-execution) or default 'interact-with-human'" />
<field name="current_idea_folder" source="previous Ideation task output OR task board OR human input">
<steps>
1. IF previous task was "Ideation" → use previous task output's current_idea_folder field
2. ELIF task board has current_idea_folder in task data → use it
3. ELIF human provides path → use it
4. IF null → list folders under x-ipe-docs/ideas/ and ask human to select
</steps>
</field>
<field name="extra_instructions" source="human-provided > config > N/A">
<steps>
1. IF human provides extra_instructions → use human value
2. ELIF tools.json stages.ideation.mockup._extra_instruction exists → use config value
3. ELSE → set to "N/A"
</steps>
</field>
<field name="ideation_toolbox_meta" source="default: x-ipe-docs/config/tools.json">
<steps>
1. Default path: {project_root}/x-ipe-docs/config/tools.json
2. IF file exists → use it
3. ELSE → inform user, offer manual mode
</steps>
</field>
<field name="extra_context_reference" source="workflow context OR auto-detect">
<steps>
1. IF workflow-mode → use workflow.extra_context_reference values
2. FOR EACH ref in [refined-idea, uiux-reference]:
IF ref is a file path → use it
ELIF "auto-detect" → use existing discovery logic
ELIF "N/A" → skip
3. ELSE (free-mode) → use existing behavior
</steps>
</field>
</input_init>
MANDATORY: See references/mockup-guidelines.md for Extra Instructions loading logic, Current Idea Folder validation, and tool configuration details.
Definition of Ready
<definition_of_ready>
<checkpoint required="true">
<name>Current Idea Folder Set</name>
<verification>current_idea_folder is not N/A and folder exists on disk</verification>
</checkpoint>
<checkpoint required="true">
<name>Idea Summary Exists</name>
<verification>File {current_idea_folder}/idea-summary-vN.md exists</verification>
</checkpoint>
<checkpoint required="true">
<name>Tools Config Accessible</name>
<verification>x-ipe-docs/config/tools.json is readable or manual mode accepted</verification>
</checkpoint>
<checkpoint required="true">
<name>Mockup Tool Available</name>
<verification>At least one mockup tool enabled in config OR human accepts manual mode</verification>
</checkpoint>
</definition_of_ready>
Execution Flow
| Phase | Step | Name | Action | Gate |
|---|
| 1. 博学之 (Study Broadly) | 1.1 | Validate Folder | Verify Current Idea Folder exists | Folder validated |
| 1.2 | Load Config | Read x-ipe-docs/config/tools.json mockup section | Config loaded |
| 1.3 | Read Idea Summary | Load latest idea-summary-vN.md from folder | Summary loaded |
| 1.4 | Research Design References | If needs lack detail, search online for design inspiration | References gathered |
| 2. 审问之 (Inquire Thoroughly) | 2.1 | Identify Mockup Needs | Extract UI/visual elements from idea | Needs identified |
| 3. 慎思之 (Think Carefully) | 3.1 | Load Brand Theme and Plan | Load theme, plan layout approach | Theme loaded |
| 4. 明辨之 (Discern Clearly) | — | SKIP | Single implementation approach; tool selection done in Phase 1 config | — |
| 5. 笃行之 (Practice Earnestly) | 5.1 | Create Mockups | Invoke enabled mockup tools with creative, distinctive designs | Mockups created |
| 5.2 | Save Artifacts | Store mockups in {current_idea_folder}/mockups/ | Artifacts saved |
| 5.3 | Update Summary | Add mockup links to idea summary | Summary updated |
| 5.4 | Complete | Verify DoD, update workflow status | DoD verified |
| 继续执行 | 6.1 | Decide Next Action | DAO-assisted next task decision | Next action decided |
| 继续执行 | 6.2 | Execute Next Action | Load skill, generate plan, execute | Execution started |
BLOCKING: Step 1.1 halts if current_idea_folder is N/A -- ask human for folder path.
BLOCKING: Step 5.1 halts if no tools available AND human declines manual mode.
Execution Procedure
<procedure name="idea-mockup">
<execute_dor_checks_before_starting/>
<schedule_dod_checks_with_sub_agent_before_starting/>
<phase_0 name="Board — Register Task">
<step_0_1>
<name>Create Task on Board</name>
<action>
Call `x-ipe-tool-task-board-manager` → `task_create.py`:
- task_type: "Idea Mockup"
- description: summarize work from input context
- status: "in_progress"
- role: from input context
- assignee: from input context
Store returned task_id for later update.
</action>
<output>Task created on board with status in_progress</output>
</step_0_1>
</phase_0>
<phase_1 name="博学之 — Study Broadly">
<step_1_1>
<name>Validate Current Idea Folder</name>
<action>
1. IF current_idea_folder == N/A:
- List available folders under x-ipe-docs/ideas/
- Ask "Which idea folder should I create mockups for?" with available options
- Set current_idea_folder = selected folder
Response source (based on interaction_mode):
IF process_preference.interaction_mode == "dao-represent-human-to-interact":
→ Resolve via x-ipe-assistant-user-representative-Engineer
ELSE (interact-with-human/dao-represent-human-to-interact-for-questions-in-skill):
→ Ask human for selection
2. Validate folder exists on disk
3. Verify idea-summary-vN.md exists in folder
4. Log: "Working with idea folder: {current_idea_folder}"
</action>
<constraints>
- BLOCKING: If folder does not exist, stop with error
- BLOCKING: If no idea-summary-vN.md found, stop: "Run Ideation task first"
</constraints>
<output>validated current_idea_folder path</output>
</step_1_1>
<step_1_2>
<name>Load Mockup Tool Configuration</name>
<action>
1. Check if x-ipe-docs/config/tools.json exists
2. IF exists: Parse JSON, extract stages.ideation.mockup section
3. IF not exists: Ask "Proceed with manual mockup description? (Y/N)"
4. Load Extra Instructions (human input > config._extra_instruction > N/A)
5. Log active configuration
</action>
<output>list of enabled mockup tools, extra_instructions value</output>
</step_1_2>
<step_1_3>
<name>Read Idea Summary</name>
<action>
0. Resolve extra_context_reference inputs:
- FOR EACH ref in [refined-idea, uiux-reference]:
IF workflow mode AND extra_context_reference.{ref} is a file path:
READ the file at that path
ELIF extra_context_reference.{ref} is "auto-detect":
Use existing discovery logic below
ELIF extra_context_reference.{ref} is "N/A":
Skip this context input
ELSE (free-mode / absent):
Use existing behavior
1. Navigate to {current_idea_folder}/
2. Find latest idea-summary-vN.md (highest version number)
3. Parse summary content
4. Extract: overview, key features, UI/UX mentions, user flow descriptions
</action>
<output>parsed idea summary with UI-relevant sections</output>
</step_1_3>
<step_1_4>
<name>Research Design References</name>
<action>
1. Evaluate whether mockup needs provide enough detail to design a high-quality UI/UX
2. IF needs are vague, generic, or lack visual specificity (e.g., "a dashboard", "a form" without layout/interaction details):
a. Use the mockup needs as search queries to find real-world design references online
b. Search for: "{mockup type} UI design", "{domain} dashboard examples", "{feature} UX patterns"
c. Analyze found references for: layout patterns, component arrangements, interaction models, visual hierarchy
d. Enrich the mockup needs with specific design details gleaned from references
e. Document which references inspired which design decisions
3. IF needs are already detailed and specific enough: skip to next step
</action>
<success_criteria>
- Mockup needs now include concrete layout, component, and interaction details
- Design references documented (if searched)
</success_criteria>
<output>enriched mockup needs with design reference insights (if applicable)</output>
</step_1_4>
</phase_1>
<phase_2 name="审问之 — Inquire Thoroughly">
<step_2_1>
<name>Identify Mockup Needs</name>
<action>
1. Analyze summary for screens/pages needed
2. Identify interactive elements and workflows
3. Determine primary user-facing components
4. Prioritize mockups by importance
</action>
<success_criteria>
- At least one mockup need identified
- Needs prioritized (high/medium/low)
</success_criteria>
<output>prioritized list of mockups to create</output>
</step_2_1>
</phase_2>
<phase_3 name="慎思之 — Think Carefully">
<step_3_1>
<name>Load Brand Theme and Plan Layout</name>
<action>
1. Check x-ipe-docs/config/tools.json for `selected-theme` section
2. IF `selected-theme` exists AND `theme-folder-path` is set:
a. Read the design system file at {theme-folder-path}/design-system.md
b. Extract: color palette, typography, spacing, component styles, semantic tokens
c. These theme tokens MUST be applied when creating mockups in Phase 5
d. Log: "Brand theme loaded: {theme-name}"
3. IF `selected-theme` is not set or theme folder does not exist:
a. Log: "No brand theme configured -- using tool defaults"
b. Proceed without theme constraints
4. Plan layout approach based on mockup needs and theme constraints
</action>
<output>brand theme tokens (colors, typography, spacing) or null, layout_plan</output>
</step_3_1>
</phase_3>
<phase_4 name="明辨之 — Discern Clearly">
<skip reason="Single implementation approach; mockup tool selection already determined in Phase 1 config loading. No alternative approaches to evaluate." />
</phase_4>
<phase_5 name="笃行之 — Practice Earnestly">
<step_5_1>
<name>Create Mockups</name>
<action>
1. For each enabled tool, invoke with idea context (UI/UX content only)
2. Generate mockup artifacts per identified needs (enriched with design references from step 1.4)
3. IF brand theme loaded in step 3.1: apply theme colors, typography, and spacing to all mockups
4. IF no tools enabled and manual mode accepted: create markdown description
</action>
<constraints>
- CRITICAL: Focus on UI/UX only -- ignore all tech stack mentions from idea files
- CRITICAL: Be creative and distinctive -- avoid generic, cookie-cutter layouts. Push for unique visual compositions, unexpected but intuitive interactions, and bold design choices that make the mockup memorable. Surprise the reviewer with thoughtful design details they did not ask for but will love.
- BLOCKING: Halts if no tools available AND human declines manual mode
</constraints>
<output>generated mockup files/links</output>
</step_5_1>
<step_5_2>
<name>Save Artifacts</name>
<action>
1. Create {current_idea_folder}/mockups/ directory if needed
2. Save all mockup files with naming: {mockup-type}-v{version}.{ext}
3. Record list of saved artifact paths
</action>
<output>list of saved artifact paths relative to current_idea_folder</output>
</step_5_2>
<step_5_3>
<name>Update Idea Summary</name>
<action>
1. Open the existing {current_idea_folder}/idea-summary-vN.md (latest version)
2. Add or update "Mockups and Prototypes" section with artifact links
3. Do NOT create a new versioned file -- edit in-place
</action>
<constraints>
- CRITICAL: Update the existing idea-summary file in-place -- do NOT create a new version
</constraints>
<output>updated idea summary path</output>
</step_5_3>
<step_5_4>
<name>Complete</name>
<action>
1. IF execution_mode == "workflow-mode":
a. Run the workflow update script via bash (`python3 .github/skills/x-ipe-tool-x-ipe-app-interactor/scripts/workflow_update_action.py`) with:
- workflow_name: {from context}
- action: {workflow.action}
- status: "done"
- deliverables: {"mockup-html": "{path to mockup HTML file}", "mockups-folder": "{path to mockups/ folder}"}
b. Log: "Workflow action status updated to done"
2. Verify all DoD checkpoints pass
3. Present mockups summary to human
</action>
<output>workflow_action_updated</output>
</step_5_4>
<step_5_5>
<name>Update Task on Board</name>
<action>
Call `x-ipe-tool-task-board-manager` → `task_update.py`:
- task_id: from Phase 0
- status: "done"
- output_links: list of deliverables produced in this skill execution
</action>
<output>Task marked done on board</output>
</step_5_5>
</phase_5>
<phase_6 name="继续执行(Continue Execute)">
<step_6_1>
<name>Decide Next Action</name>
<action>Collect task_completion_output. IF interaction_mode == "dao-represent-human-to-interact": invoke x-ipe-assistant-user-representative-Engineer with type: "routing", completed_skill_output, next_task_based_skill. ELSE: present next task suggestion to human.</action>
<constraints>
- BLOCKING (manual): Human MUST confirm or redirect
- BLOCKING (auto): Auto-select next task via DAO after DoD verification
</constraints>
<output>Next action decided</output>
</step_6_1>
<step_6_2>
<name>Execute Next Action</name>
<action>Load target skill's SKILL.md, generate execution plan, start from first phase.</action>
<constraints>MUST load skill before executing — follows target skill's procedure.</constraints>
<output>Next task execution started</output>
</step_6_2>
</phase_6>
</procedure>
Output Result
task_completion_output:
category: "ideation-stage"
status: completed | blocked
next_task_based_skill:
- skill: "x-ipe-task-based-requirement-gathering"
condition: "Proceed to requirements after mockup"
process_preference:
interaction_mode: "{from input process_preference.interaction_mode}"
execution_mode: "{from input}"
workflow:
name: "{from input}"
workflow_action: "{workflow.action}"
workflow_action_updated: true | false
task_output_links:
- "{current_idea_folder}/mockups/{mockup-type}-v1.html"
- "{current_idea_folder}/idea-summary-vN.md"
current_idea_folder: "{current_idea_folder}"
mockup_tools_used:
- "x-ipe-tool-frontend-design"
mockup_list:
- mockup_name: "Dashboard mockup"
mockup_link: "{current_idea_folder}/mockups/dashboard-v1.html"
- mockup_name: "User form mockup"
mockup_link: "{current_idea_folder}/mockups/user-form-v1.html"
idea_summary_version: "vN"
MANDATORY: The mockup_list is passed through the chain: Idea Mockup -> Requirement Gathering -> Feature Breakdown -> Feature Refinement -> Technical Design.
Definition of Done
CRITICAL: Use a sub-agent to validate DoD checkpoints independently.
<definition_of_done>
<checkpoint required="true">
<name>Folder Validated</name>
<verification>current_idea_folder exists and contains idea-summary-vN.md</verification>
</checkpoint>
<checkpoint required="true">
<name>Config Loaded</name>
<verification>x-ipe-docs/config/tools.json loaded and mockup section parsed (or manual mode accepted)</verification>
</checkpoint>
<checkpoint required="true">
<name>Summary Analyzed</name>
<verification>Idea summary read and UI-relevant elements extracted</verification>
</checkpoint>
<checkpoint required="true">
<name>Needs Identified</name>
<verification>Mockup needs identified and prioritized</verification>
</checkpoint>
<checkpoint required="true">
<name>Design References Researched</name>
<verification>If needs lacked detail, online design references were searched and insights incorporated; otherwise explicitly skipped with justification</verification>
</checkpoint>
<checkpoint required="true">
<name>Brand Theme Applied</name>
<verification>If selected-theme configured in tools.json, theme tokens read and applied to mockups; otherwise no theme configured</verification>
</checkpoint>
<checkpoint required="true">
<name>Mockups Created</name>
<verification>Mockups created using enabled tools or manual description</verification>
</checkpoint>
<checkpoint required="true">
<name>Artifacts Saved</name>
<verification>All mockups saved to {current_idea_folder}/mockups/</verification>
</checkpoint>
<checkpoint required="true">
<name>Summary Updated</name>
<verification>Existing idea-summary-vN.md updated in-place with mockup links</verification>
</checkpoint>
<checkpoint required="if-applicable">
<name>Workflow Action Status Updated</name>
<verification>If execution_mode == "workflow-mode", ran `workflow_update_action.py` script with status "done" and deliverables keyed dict</verification>
</checkpoint>
</definition_of_done>
MANDATORY: After completing this skill, return to x-ipe-workflow-task-execution to continue the task execution flow.
Patterns & Anti-Patterns
| Pattern | When | Then |
|---|
| Dashboard-Heavy | Data visualization focus | Prioritize dashboard mockup, chart placeholders, responsive layout |
| Form-Heavy | Data input or registration | Form mockups with validation, error/success, multi-step flows |
| No UI Description | Summary lacks UI details | Ask clarifying questions, suggest patterns, create minimal mockup |
| Multiple Roles | Different user types | Separate mockups per role, document role-specific features |
| Anti-Pattern | Why Bad | Do Instead |
|---|
| Mockup before reading idea | May miss requirements | Always analyze idea first |
| Ignoring tools.json config | Inconsistent tool usage | Always check config |
| Using disabled tools | Violates config rules | Only use enabled tools |
| Too many mockups at once | Overwhelms review | Start with 1-3 key mockups |
Examples
See references/examples.md for detailed execution examples including:
- Mockup with frontend-design tool enabled
- Mockup without tools (manual mode)
- Missing idea folder (blocked scenario)
- No idea summary (blocked scenario)