| name | x-ipe-workflow-task-execution |
| description | Orchestrates development task lifecycle through 6-step workflow. Coordinates skills for planning, execution, closing, and routing. Use when "implement feature", "fix bug", "create PR", "design architecture", "set up project". Triggers on requests like "implement feature", "fix bug", "refactor code", "set up project". |
Task Execution Guideline
Purpose
Orchestrate a multi-skill workflow for development tasks by:
- Plan - Match requests to task-based skills and create tasks on board
- Verify - Check prerequisites via Global DoR gate
- Execute - Load and run task-based skills for core work
- Close - Update boards via category-based skill loading
- Validate - Confirm completion via Global DoD checks
- Route - Chain to next task if auto-proceed enabled
Important Notes
BLOCKING: Tasks MUST be created via x-ipe-tool-task-board-manager BEFORE any work begins. Step 2 will reject tasks not found on the board.
CRITICAL: This skill does NOT implement task logic itself — it coordinates task-based skills and category skills.
MANDATORY: NEVER use manage_todo_list (VS Code internal) as substitute for the JSON task board (project tracking).
Note: If Agent does not have skill capability, go to .github/skills/ folder to learn skills. SKILL.md is the entry point for each skill.
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. When manual or stop_for_question, always wait for human feedback before proceeding to the next task.
Input Parameters
input:
task:
task_id: "TASK-XXX"
task_based_skill: "{task_based_skill}"
task_description: "{description, max 50 words}"
category: "{derived from task-based skill} | Standalone"
role_assigned: "{agent_nickname}"
status: "pending | in_progress | blocked | deferred | completed | cancelled"
last_updated: "{MM-DD-YYYY HH:MM:SS}"
execution_mode: "free-mode | workflow-mode"
workflow:
name: "N/A"
execution:
next_task_based_skill: "{task_based_skill} | null"
process_preference:
interaction_mode: "interact-with-human | dao-represent-human-to-interact | dao-represent-human-to-interact-for-questions-in-skill"
task_output_links: ["{links}"] | null
dynamic_attributes: {}
git:
strategy: "main-branch-only | dev-session-based"
main_branch: "{auto-detected}"
closing:
category_level_change_summary: "{summary, max 100 words} | null"
Input Initialization
<input_init>
<field name="task.task_id" source="x-ipe-tool-task-board-manager (auto-generated on create)" />
<field name="task.task_based_skill" source="Auto-discovery: match request against .github/skills/x-ipe-task-based-*/SKILL.md descriptions" />
<field name="task.task_description" source="Summarize from human request (max 50 words)" />
<field name="task.category" source="Read from matched skill's Output Result `category` field" />
<field name="task.role_assigned" source="Current agent nickname" />
<field name="task.status" source="Set to 'pending' on creation" />
<field name="task.last_updated" source="Current timestamp on each status change" />
<field name="execution_mode">
<steps>
1. IF instruction starts with `--workflow-mode@{name}` → "workflow-mode"
2. IF instruction starts with `--workflow-mode` (no @) → "workflow-mode"
3. ELSE → "free-mode"
</steps>
</field>
<field name="workflow.name">
<steps>
1. IF instruction has `--workflow-mode@{name}` → extract {name}
2. ELSE → "N/A"
</steps>
</field>
<field name="execution.next_task_based_skill" source="From task-based skill output" />
<field name="execution.process_preference.interaction_mode" source="Resolved from: (a) workflow-{name}.json global.process_preference in workflow-mode, (b) CLI flag --proceed@auto or --proceed@stop-for-question in free-mode, (c) Semantic understanding from user message, (d) default: manual" />
<field name="execution.task_output_links" source="From task-based skill output" />
<field name="git.strategy">
<steps>
1. Read .x-ipe.yaml from project root
2. IF file exists AND git.strategy specified → use value
3. ELSE → "main-branch-only"
</steps>
</field>
<field name="git.main_branch">
<steps>
1. IF .x-ipe.yaml specifies git.main-branch → use value
2. ELSE → auto-detect from `git remote show origin` or fallback to main/master
</steps>
</field>
<field name="closing.category_level_change_summary" source="From category skill output (or null if skipped)" />
</input_init>
Git Strategy
BLOCKING: At the start of every workflow execution, read .x-ipe.yaml from project root to determine git.strategy and git.main-branch. If .x-ipe.yaml does not exist or git.strategy is not specified, default to main-branch-only. If git.main-branch is not specified, auto-detect the main branch from git (see Step 2 procedure). Pass these values to all task-based skills that interact with git.
| Strategy | Branch Model | PR Required? | Description |
|---|
main-branch-only | Work directly on main branch | No | All commits go to main. No feature branches created. |
dev-session-based | dev/{git_user_name} branch per developer | Yes, on feature close | Each developer works on their own persistent branch. PR to main when a feature is closed. |
See references/examples.md for detailed strategy rules and git identity validation.
Category Derivation
BLOCKING: Category is read from the skill's own Output Result section (category field). Do NOT hardcode category mappings.
Auto-discovery rule: Load .github/skills/x-ipe-task-based-{name}/SKILL.md → read category from Output Result YAML block.
Category to Closing Skill Mapping
| Category | Closing Skill | Required? |
|---|
| feature-stage | x-ipe-tool-task-board-manager | Yes |
| ideation-stage | (none) | N/A |
| requirement-stage | (none) | N/A |
| code-refactoring-stage | x-ipe+feature+quality-board-management | No (optional) |
| Standalone | (none) | N/A |
Task States
| State | Terminal? | Description |
|---|
pending | No | Created, waiting to start |
in_progress | No | Currently being worked on |
blocked | No | Waiting for dependency |
deferred | No | Human paused |
completed | Yes | Successfully done |
cancelled | Yes | Stopped |
Valid State Transitions
pending → in_progress
in_progress → completed | blocked | deferred | cancelled
blocked → in_progress
deferred → in_progress
Definition of Ready
<definition_of_ready>
<checkpoint required="true">
<name>Task Exists on Board</name>
<verification>Task {task_id} found via x-ipe-tool-task-board-manager query</verification>
<on_failure>STOP, return to Step 1 to create task on board</on_failure>
</checkpoint>
<checkpoint required="true">
<name>Valid Starting Status</name>
<verification>Task status is pending or blocked</verification>
<on_failure>STOP, log "Task {task_id} has invalid status: {status}"</on_failure>
</checkpoint>
<checkpoint required="true">
<name>Git Repository Initialized</name>
<verification>Project root is a git repository (invoke x-ipe-tool-git-version-control skill if needed)</verification>
</checkpoint>
<checkpoint required="true">
<name>Git Strategy Resolved</name>
<verification>Read .x-ipe.yaml git.strategy; agent is on correct branch per strategy rules</verification>
</checkpoint>
<checkpoint required="true">
<name>Git Identity Valid</name>
<verification>For dev-session-based strategy: git config user.name is NOT a placeholder ("Your Name", empty). If invalid, STOP and ask user.</verification>
<on_failure>STOP, ask user to provide actual git user.name</on_failure>
</checkpoint>
</definition_of_ready>
Execution Flow Summary
| Step | Name | Action | Mandatory Output | Next Step |
|---|
| 1 | Planning | Match request, create task(s) on board | Tasks visible via task board query | → Step 2 |
| 2 | Global DoR | Verify prerequisites | All checks pass | → Step 3 (pass) or STOP (fail) |
| 3 | Execute | Load task-based skill, do work | Skill output collected | → Step 4 |
| 4 | Closing | Load category skills, update boards | Boards updated | → Step 5 |
| 5 | Global DoD | Validate, output summary | Summary displayed | → Step 6 (pass) or STOP (manual) |
| 6 | 继续执行（Continue Execute） | Resolve process_preference mode, route next | Next action decided | → Step 1 (auto) or WAIT for human (manual/stop_for_question) |
BLOCKING: Step 1 → Step 2: task must be created via x-ipe-tool-task-board-manager.
BLOCKING: Step 3 → Step 4: x-ipe-tool-task-board-manager skill must be loaded.
BLOCKING: Step 4 → Step 5: task board must be updated via x-ipe-tool-task-board-manager.
Execution Procedure
<procedure name="x-ipe-workflow-task-execution">
<execute_dor_checks_before_starting/>
<schedule_dod_checks_with_sub_agent_before_starting/>
<step_1>
<name>Task Planning</name>
<trigger>Receive work request from human or system</trigger>
<actions>
1. Resolve execution_mode and workflow.name from instruction prefix (see Input Initialization)
2. Match request to task-based skill using auto-discovery (scan `.github/skills/x-ipe-task-based-*/SKILL.md` descriptions)
See references/examples.md for request matching patterns.
3. Derive category from skill's Output Result `category` field
4. Check task:
- IF task not exists → Create with status: pending
- ELSE IF exists AND assigned to you → Continue
- ELSE → STOP
5. MANDATORY: Load x-ipe-tool-task-board-manager skill to create/update tasks on board
→ This step CANNOT be skipped
→ Tasks MUST appear on board BEFORE proceeding to Step 2
6. IF task-based skill defines next_task_based_skill → Create ALL chained tasks upfront
7. VERIFICATION: Confirm all tasks are visible on task board before proceeding
</actions>
<output>Task Data Model with core fields populated AND tasks created on board</output>
<gate>All tasks visible via task board query</gate>
</step_1>
<step_2>
<name>Check Global DoR</name>
<actions>
GATE CHECK: This step validates that Step 1 was completed correctly.
1. Query task board via x-ipe-tool-task-board-manager (task_query.py)
2. Search for {task_id} in Active Tasks section
3. IF task NOT found:
→ STOP execution
→ Log: "Task {task_id} not found on board. Returning to Step 1."
→ Return to Step 1 and create task on board
4. IF task found but status is not pending/blocked:
→ STOP execution
→ Log: "Task {task_id} has invalid status for starting: {status}"
5. Verify git repository:
IF not a git repository:
CALL x-ipe-tool-git-version-control skill: operation=init
CALL x-ipe-tool-git-version-control skill: operation=create_gitignore
6. Resolve git.strategy and git.main_branch (see Input Initialization)
7. Apply git strategy:
IF git.strategy == "main-branch-only":
→ Ensure on main branch: git checkout {main_branch}
→ Do NOT create any other branches
ELSE IF git.strategy == "dev-session-based":
→ BLOCKING: Validate git identity first:
Run: git config user.name AND git config user.email
KNOWN_PLACEHOLDERS = ["Your Name", "your name", "you@example.com", ""]
IF user.name IN KNOWN_PLACEHOLDERS OR user.email IN KNOWN_PLACEHOLDERS OR user.name is empty:
→ STOP: Ask user "Your git user.name is '{user.name}' which appears to be a placeholder. Please provide your actual name for the dev branch."
→ Do NOT proceed until user provides valid identity
→ After user provides name: run git config user.name "{provided_name}" (and git config user.email if needed)
→ Resolve dev branch name from git identity:
Run: git config user.name (or git config user.email if empty)
Sanitize: lowercase, spaces→hyphens, remove special chars
Branch name: dev/{sanitized_git_user_name}
→ Check if branch dev/{git_user_name} exists
→ IF not exists: git checkout -b dev/{git_user_name} (from main)
→ IF exists: git checkout dev/{git_user_name}
→ Pull latest: git pull origin dev/{git_user_name} (ignore if remote doesn't exist yet)
</actions>
<on_failure>STOP and report missing prerequisites</on_failure>
<on_success>Transition task status: pending → in_progress</on_success>
<gate>All DoR checkpoints pass</gate>
</step_2>
<step_3>
<name>Task Work Execution</name>
<actions>
1. Load task-based skill: x-ipe-task-based-{task_based_skill}
2. Pass Task Data Model to skill, including execution_mode and workflow.name
3. Check task-based skill DoR (defined in skill)
4. Execute core work (defined in skill)
5. Check task-based skill DoD (defined in skill)
6. Collect skill output into Task Data Model
</actions>
<skill_output_contract>
Each task-based skill MUST return:
status: {new_status}
next_task_based_skill: {task_based_skill} | null
process_preference:
interaction_mode: "{from input process_preference.interaction_mode}"
task_output_links: [{links}] | null
{dynamic_attributes}: per skill definition
</skill_output_contract>
<output>Task Data Model updated with execution results</output>
<gate>Skill output collected</gate>
</step_3>
<step_4>
<name>Category Closing</name>
<actions>
1. MANDATORY: Load skill x-ipe-tool-task-board-manager
→ Update task status on board
→ Pass Task Data Model
2. IF category != "Standalone":
TRY:
→ Load skill @{category}+{category-skill-name}
→ Pass Task Data Model
→ Collect category_level_change_summary
CATCH SkillNotFound:
→ Log: "No category-level skill found for {category}, skipping"
→ Continue without error (category_level_change_summary = null)
</actions>
<category_skill_mapping>
Refer to "Category to Closing Skill Mapping" in the Category Derivation section above.
</category_skill_mapping>
<note>If category skill not found, execution continues without error. Category-level change summary will be null if skipped.</note>
<output>category_level_change_summary added to Task Data Model (or null)</output>
<gate>task board updated via x-ipe-tool-task-board-manager</gate>
</step_4>
<step_5>
<name>Check Global DoD</name>
<actions>
1. Validate:
- Task status updated on task board
- Category-level changes committed (if applicable)
- All task-based skill DoD met
- Changes committed to git (if files were created/modified)
2. Git Commit Check:
IF task_output_links is NOT empty AND files were created/modified:
CALL x-ipe-tool-git-version-control skill: operation=add, files=null (stage all)
CALL x-ipe-tool-git-version-control skill: operation=commit, task_data={task_id, task_description, feature_id}
OPTIONAL: IF auto_push = true:
CALL x-ipe-tool-git-version-control skill: operation=push
3. Workflow Status Verification:
IF execution_mode == "workflow-mode" AND completed skill's task_completion_output contains workflow_action field:
a. Extract workflow_name and workflow_action from output
b. READ instance/workflows/wf-{nnn}-{workflow_name}.json
c. CHECK that actions.{workflow_action}.status is NOT "pending"
d. IF status is "pending" → FLAG task as incomplete: "Workflow action '{workflow_action}' status not updated. Run `python3 .github/skills/x-ipe-tool-x-ipe-app-interactor/scripts/workflow_update_action.py` before completing."
e. CHECK that actions.{workflow_action}.deliverables is a keyed dict (not a list). Keys must match extract tags from workflow-template.json for this action.
f. IF workflow JSON file not found → WARN and skip (non-blocking)
ELSE IF execution_mode == "free-mode":
→ Skip workflow status verification
4. Auto-Proceed Freshness Check:
Re-read the current process_preference.interaction_mode value from its source:
- workflow-mode: from workflow-{name}.json global.process_preference
- free-mode: from CLI flag or user message
IF the value has changed since Step 2 → update process_preference.interaction_mode for Step 6 routing.
5. Human Review Check (mode-aware):
IF process_preference.interaction_mode == "dao-represent-human-to-interact":
→ Skip human review, proceed directly
ELIF process_preference.interaction_mode == "dao-represent-human-to-interact-for-questions-in-skill" OR "manual":
→ Output summary and STOP for human review
</actions>
<output_template>
> Task ID: {task_id}
> Task-Based Skill: {task_based_skill}
> Description: {task_description}
> Category: {category}
> Assignee: {role_assigned}
> Status: {status}
> Execution Mode: {execution_mode}
> Workflow: {workflow.name}
> Category Changes: {category_level_change_summary}
> Process Preference: {process_preference.interaction_mode}
> Task Output Links: {task_output_links}
> --- Dynamic Attributes ---
> {attr_1}: {value}
</output_template>
<gate>All DoD checkpoints pass</gate>
</step_5>
<step_6>
<name>继续执行（Continue Execute）</name>
<actions>
NOTE: Each task-based skill now includes its own <routing> phase at the end.
The task-based skill's routing phase passes the full task_completion_output to
x-ipe-assistant-user-representative-Engineer for context-rich routing decisions.
This step acts as a fallback/coordinator:
IF task-based skill already executed its <routing> phase:
→ Routing decision was already made with full skill output context
→ Follow the routing decision (next task or stop)
→ If routing to next task → Start from Step 1 (Planning)
ELSE IF routing was not handled by the task-based skill:
IF next_task_based_skill EXISTS:
IF process_preference.interaction_mode == "dao-represent-human-to-interact":
→ Invoke x-ipe-assistant-user-representative-Engineer with:
type: "routing"
completed_skill_output: {full task_completion_output YAML}
next_task_based_skill: "{from output}"
context: "Skill completed. Study the full output to decide best next action."
→ IF multiple next_actions_suggested (workflow-mode):
invoke x-ipe-assistant-user-representative-Engineer (type: routing) to choose
→ Start execution from Step 1 (Planning — to create/verify task on board)
ELIF process_preference.interaction_mode == "dao-represent-human-to-interact-for-questions-in-skill":
→ Invoke x-ipe-assistant-user-representative-Engineer with same context
→ Present DAO's recommendation to human and wait for confirmation
ELSE (interact-with-human):
→ Present next task suggestion to human using the skill-specific hint template
(each skill defines its own contextual hint in its routing phase)
→ For feature-stage skills: always name the specific feature ID and the next pipeline step
→ After feature-closing: suggest the next unstarted feature from backlog, or celebrate completion if all done
→ Wait for human instruction
ELSE:
→ STOP (no next task defined)
</actions>
<constraints>
- BLOCKING (manual/stop_for_question): Human MUST confirm or redirect before routing to next task
- BLOCKING (auto): Proceed automatically; resolve routing ambiguity via x-ipe-assistant-user-representative-Engineer
- DAO receives full task_completion_output for context-aware routing decisions
</constraints>
<gate>Continue Execute decision made</gate>
</step_6>
</procedure>
Output Result
output:
task_id: "{task_id}"
task_based_skill: "{task_based_skill}"
task_description: "{task_description}"
category: "{category}"
role_assigned: "{role_assigned}"
status: "completed | blocked | deferred"
execution_mode: "{execution_mode}"
workflow:
name: "{workflow.name}"
category_level_change_summary: "{summary} | null"
process_preference:
interaction_mode: "interact-with-human | dao-represent-human-to-interact | dao-represent-human-to-interact-for-questions-in-skill"
task_output_links: ["{links}"] | null
next_task_based_skill: "{task_based_skill} | null"
dynamic_attributes: {}
Definition of Done
<definition_of_done>
<checkpoint required="true">
<name>Task Board Updated</name>
<verification>Task status updated via x-ipe-tool-task-board-manager</verification>
</checkpoint>
<checkpoint required="true">
<name>Category Changes Committed</name>
<verification>Category-level changes committed if applicable</verification>
</checkpoint>
<checkpoint required="true">
<name>Task-Based Skill DoD Met</name>
<verification>All task-based skill Definition of Done criteria satisfied</verification>
</checkpoint>
<checkpoint required="true">
<name>Git Changes Committed</name>
<verification>All created/modified files committed to git</verification>
</checkpoint>
</definition_of_done>
Task-Based Skills Auto-Discovery
BLOCKING: Do NOT maintain a hardcoded registry. Skills are auto-discovered.
Discovery rule:
- Scan
.github/skills/x-ipe-task-based-*/SKILL.md
- Each skill's Output Result YAML declares:
category, next_task_based_skill, process_preference.interaction_mode
- Each skill's
description in frontmatter contains trigger keywords for request matching
Request matching:
- Read the
description field from each x-ipe-task-based-*/SKILL.md frontmatter
- Match user request against trigger keywords (e.g., "fix bug" matches
x-ipe-task-based-bug-fix)
- See references/examples.md for common request-to-skill patterns
Note: When process_preference.interaction_mode is dao-represent-human-to-interact or dao-represent-human-to-interact-for-questions-in-skill, human review at skill completion is handled by the mode-aware gate in Step 5. In dao-represent-human-to-interact mode, review is skipped entirely. In dao-represent-human-to-interact-for-questions-in-skill mode, review still stops for human approval.
Error Handling
| Error | Cause | Recovery |
|---|
TASK_NOT_ON_BOARD | Task not found via x-ipe-tool-task-board-manager query | Return to Step 1, create task on board |
INVALID_STATUS | Task status not valid for starting | STOP, log invalid status |
SKILL_NOT_FOUND | Task-based or category skill missing | Fail for task-based skills; skip for optional category skills |
GIT_NOT_INITIALIZED | No git repository | Invoke x-ipe-tool-git-version-control skill to init |
DOR_FAILED | Prerequisites not met | STOP, report missing prerequisites |
Templates & Examples
templates/task-record.yaml - Task data template- references/examples.md - Full workflow examples, request matching patterns, and git strategy rules
