X Ipe Workflow Task Execution

Task Execution Guideline

Purpose

Orchestrate a multi-skill workflow for development tasks by:

1. Plan - Match requests to task-based skills and create tasks on board
2. Verify - Check prerequisites via Global DoR gate
3. Execute - Load and run task-based skills for core work
4. Close - Update boards via category-based skill loading
5. Validate - Confirm completion via Global DoD checks
6. 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-dao-end-user-representative 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"  # default: manual
    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>
  <!-- Task fields (resolved during Step 1 Planning) -->
  <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" />

  <!-- Execution mode (resolved at start of Step 1) -->
  <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>

  <!-- Execution fields (populated after Step 3) -->
  <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" />

  <!-- Git strategy (resolved during Step 2 DoR) -->
  <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>

  <!-- Closing fields (populated after Step 4) -->
  <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.

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

Task States

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

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 &lt;routing&gt; phase at the end.
      The task-based skill's routing phase passes the full task_completion_output to
      x-ipe-dao-end-user-representative for context-rich routing decisions.

      This step acts as a fallback/coordinator:

      IF task-based skill already executed its &lt;routing&gt; 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-dao-end-user-representative 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-dao-end-user-representative (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-dao-end-user-representative 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-dao-end-user-representative
      - 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: {}  # Per task-based skill

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:

1. Scan .github/skills/x-ipe-task-based-*/SKILL.md
2. Each skill's Output Result YAML declares: category, next_task_based_skill, process_preference.interaction_mode
3. Each skill's description in frontmatter contains trigger keywords for request matching

Request matching:

1. Read the description field from each x-ipe-task-based-*/SKILL.md frontmatter
2. Match user request against trigger keywords (e.g., "fix bug" matches x-ipe-task-based-bug-fix)
3. 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

Templates & Examples

• templates/task-record.yaml - Task data template
• references/examples.md - Full workflow examples, request matching patterns, and git strategy rules

Converted and distributed by TomeVault — claim your Tome and manage your conversions.