---
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:

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 on task-board.md 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 task-board.md (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.

---

## Input Parameters

```yaml
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"
    require_human_review: true | false
    auto_proceed: true | false
    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"
```

### 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. |

**Rules by strategy:**

**`main-branch-only`:**
- Do NOT create any branches
- All commits go directly to the main branch
- No PRs needed — code lands on main immediately
- `git push` pushes to main

**`dev-session-based`:**
- BLOCKING: Validate git identity before resolving branch name:
  → Run: `git config user.name` and `git config user.email`
  → Reject placeholder values: `"Your Name"`, `"you@example.com"`, empty, or any value matching common defaults
  → IF placeholder detected: STOP and ask user to provide their actual git name/email
  → Do NOT proceed with branch creation until valid identity confirmed
- Resolve dev branch name from git identity (NOT agent nickname):
  → Run: `git config user.name` (or `git config user.email` if user.name is empty)
  → Sanitize: lowercase, replace spaces with hyphens, remove special chars
  → Branch name: `dev/{sanitized_git_user_name}`
- On first task execution, check if `dev/{git_user_name}` branch exists
  - If not → create it from main: `git checkout -b dev/{git_user_name}`
  - If exists → switch to it: `git checkout dev/{git_user_name}`
- All work happens on this branch
- On feature close → push branch, create PR targeting main
- Branch persists across features (not deleted after PR)

### 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+feature+feature-board-management | 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

```xml
<definition_of_ready>
  <checkpoint required="true">
    <name>Task Exists on Board</name>
    <verification>Task {task_id} found in Active Tasks section of x-ipe-docs/planning/task-board.md</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 on task-board.md | → 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 (review) |
| 6 | Routing | Check auto_proceed, next task or STOP | Next action decided | → Step 2 (next) or END |

BLOCKING: Step 1 → Step 2: task must be created on task-board.md.
BLOCKING: Step 3 → Step 4: x-ipe+all+task-board-management skill must be loaded.
BLOCKING: Step 4 → Step 5: task-board.md must be updated.

---

## Execution Procedure

```xml
<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. Detect execution mode from instruction prefix:
         - IF instruction starts with `--workflow-mode` → set execution_mode = "workflow-mode", strip prefix from instruction
         - ELSE → set execution_mode = "free-mode"
      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+all+task-board-management 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 on task-board.md</gate>
  </step_1>

  <step_2>
    <name>Check Global DoR</name>
    <actions>
      GATE CHECK: This step validates that Step 1 was completed correctly.

      1. Read task board at x-ipe-docs/planning/task-board.md
      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. Read git strategy from .x-ipe.yaml:
         → Read .x-ipe.yaml from project root (if file exists)
         → Set git.strategy = git.strategy (default: "main-branch-only" if not specified or file missing)
         → Set git.main_branch:
           IF .x-ipe.yaml specifies git.main-branch → use that value
           ELSE → auto-detect: run `git remote show origin` to find HEAD branch,
                  or fallback to `git symbolic-ref refs/remotes/origin/HEAD` → parse branch name,
                  or fallback to checking if `main` or `master` branch exists locally

      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
      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
        require_human_review: true | false
        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+all+task-board-management
         → 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.md updated</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/workflow-{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. Call update_workflow_action MCP tool before completing."
           e. IF workflow JSON file not found → WARN and skip (non-blocking)
         ELSE IF execution_mode == "free-mode":
           → Skip workflow status verification

      4. Human Review Check:
         IF require_human_review = true AND auto_proceed = false AND global_auto_proceed = false:
           → Output summary and STOP for human review
         ELSE:
           → Skip human review (auto-proceed overrides)
    </actions>
    <output_template>
      > Task ID: {task_id}
      > Task-Based Skill: {task_based_skill}
      > Description: {task_description}
      > Category: {category}
      > Assignee: {role_assigned}
      > Status: {status}
      > Category Changes: {category_level_change_summary}
      > Require Human Review: {require_human_review}
      > Task Output Links: {task_output_links}
      > Auto Proceed: {auto_proceed}
      > --- Dynamic Attributes ---
      > {attr_1}: {value}
    </output_template>
    <gate>All DoD checkpoints pass</gate>
  </step_5>

  <step_6>
    <name>Task Routing</name>
    <actions>
      1. Read Global Auto-Proceed setting from task-board.md (Global Settings section)
         → Default to false if not found
      2. Set effective_auto_proceed = auto_proceed OR global_auto_proceed

      IF effective_auto_proceed = true AND next_task_based_skill EXISTS:
        → Find next task on board (already created in Step 1)
        → Start execution from Step 2
      ELSE:
        → STOP (wait for human)
    </actions>
    <gate>Routing decision made</gate>
  </step_6>
</procedure>
```

---

## Output Result

```yaml
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"
  category_level_change_summary: "{summary} | null"
  require_human_review: true | false
  task_output_links: ["{links}"] | null
  auto_proceed: true | false
  next_task_based_skill: "{task_based_skill} | null"
  dynamic_attributes: {}  # Per task-based skill
```

---

## Definition of Done

```xml
<definition_of_done>
  <checkpoint required="true">
    <name>Task Board Updated</name>
    <verification>Task status updated on task-board.md</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`, `require_human_review`
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](references/examples.md) for common request-to-skill patterns

> **Note:** When Auto-Proceed is enabled (global or task-level), `require_human_review` is skipped regardless of the skill's default.

---

## Error Handling

| Error | Cause | Recovery |
|-------|-------|----------|
| `TASK_NOT_ON_BOARD` | Task not found on task-board.md | 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

- `templates/task-record.yaml` - Task data template
- `templates/task-board.md` - Task tracking board

---

## Examples

See [references/examples.md](references/examples.md) for full workflow examples and request matching patterns.
