Run Work

Invoked as /agiflow:run-work. In hosts without slash-prompts, this skill is triggered by matching intent and drives AgiFlow via its MCP tools.

Usage:

• /agiflow:run-work <work-unit-slug-or-id> - Execute specific work unit
• /agiflow:run-work - List and select from available work units

Examples:

• /agiflow:run-work DXX-WU-1 (using slug)
• /agiflow:run-work 01K8FABMNEJG1XTA9JGHSNFV40 (using ID)
• /agiflow:run-work (interactive selection)

Guardrails

• Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
• Keep changes tightly scoped to the requested outcome within the work unit scope.
• A work unit represents a cohesive feature/epic that can be completed in one Claude Code session.

If a work unit slug/id is provided, load it with get_work_unit; otherwise list available work units with list_work_units for selection.

AgiFlow Project Management Guidelines

Follow the shared AgiFlow project-management guidelines in references/agiflow-agents.md — agent assignment, the task status workflow and transitions, work-unit best practices, and the tags strategy apply to this workflow.

Task Status Workflow (per task) Each task moves individually through: Todo → In Progress → Testing → Review The work unit stays in_progress until all tasks reach Review or Done. If any task hits Blocked, consider setting the work unit to blocked too.

IMPORTANT: Planning Status Guard This skill ONLY executes tasks in "Todo" or later status. Tasks in "Planning" have NOT been groomed and are NOT ready for execution. Use backlog-grooming to promote Planning tasks to Todo first.

Steps Track these steps as TODOs and complete them one by one.

1. Work Unit Selection & Loading

If work unit slug/id NOT provided:

1. Use list_work_units MCP tool to show available work units:
   • Filter by status: "in_progress" for active work, or work units with tasks in "Todo"
   • Do NOT pick up work units where all tasks are still in "Planning" status
   • Display: slug, title, type, priority, task count, status
2. Ask user to select which work unit to work on.
3. Once user selects, proceed with the selected work unit slug/id.

If work unit slug/id IS provided: 4. Use get_work_unit MCP tool with the provided slug/id to retrieve:

• Work unit: title, description, goals, type, priority, status, dates, devInfo
• Tasks: All tasks associated with this work unit (already included in response)
• Note: get_work_unit returns tasks automatically - no separate list_tasks call needed

5. Review the work unit and all its tasks to understand:
   • Complete feature scope and deliverables
   • Task dependencies and execution order
   • Acceptance criteria across all tasks

5b. PLANNING STATUS GUARD (MANDATORY):

• Check all tasks in the work unit
• If ANY task has status "Planning": REFUSE to execute
• Report: "Cannot execute: N task(s) are still in Planning status. Use backlog-grooming to promote them to Todo first."
• List the Planning tasks by title
• STOP execution — do not proceed

2. Start Work Unit Execution

6. If work unit status is "planning":
   • First verify ALL tasks are in "Todo" or later status (not "Planning")
   • If verified, use update_work_unit MCP tool to set status to "in_progress"
   • If any tasks are in "Planning", REFUSE and suggest backlog-grooming
7. Create a TODO list of all tasks in execution order (use TodoWrite tool).
8. Document execution plan in work unit via update_work_unit devInfo:

   devInfo: {
     executionPlan: "Backend API → Frontend UI → Tests → Documentation",
     sessionId: "<current-session-id>",
     startedAt: "<timestamp>"
   }
   

3. Execute Tasks Sequentially

9. For each task in the work unit (in dependency order from the tasks array):

   • Review task details: title, description, acceptance criteria, assignee
   • Use update_task MCP tool to set status to "In Progress"
   • BEFORE editing any code: Use architect MCP get_file_design_pattern (MANDATORY)
   • Implement the task following acceptance criteria
   • AFTER editing code: Use architect MCP review_code_change (MANDATORY)
   • Update task devInfo with implementation notes:

     devInfo: {
       filesChanged: ["path/to/file.ts:42"],
       testResults: { passed: true, coverage: "85%" },
       notes: "Implementation notes here"
     }
     

   • Mark acceptance criteria as checked via update_task

   Testing phase for each task:

   • Use update_task to move status to "Testing"

   • Run unit tests, integration tests, type check and lint for affected code

   • If tests PASS: proceed to move task to "Review"

   • If tests FAIL:

     • Increment retryCount in devInfo
     • If retryCount >= maxRetries (default: 2): move task to "Blocked", set work unit to "blocked", stop
     • If retryCount < maxRetries: move task back to "Todo", document failure, continue to next task or stop session

   • Use update_task to set status to "Review" when tests pass

   • Update your TODO list (mark task as completed)

10. Between tasks:

    • Commit changes with meaningful commit messages
    • Run tests to ensure no regressions
    • Update work unit progress in devInfo

4. Work Unit Progress Tracking

11. The work unit tasks array automatically updates as tasks are completed.

    • Use get_work_unit to check current state and task statuses
    • Track: How many tasks in Review or Done vs. total?
    • Monitor: Are we on track for target date?
    • Work unit stays in_progress until all tasks reach Review or Done

12. Update work unit devInfo as you progress via update_work_unit:

    devInfo: {
      executionPlan: "...",
      sessionId: "<session-id>",
      startedAt: "<timestamp>",
      progress: {
        completedTasks: 3,
        totalTasks: 8,
        lastTaskCompleted: "Implement cart API",
        currentTask: "Add cart UI component"
      },
      testResults: {
        unitTests: "passing",
        integrationTests: "passing",
        coverage: "85%"
      },
      blockers: [] // or list any blockers encountered
    }
    

5. Work Unit Completion

13. When ALL tasks in work unit are in "Review" or "Done":

    • Verify all tasks have status "Review" or "Done"
    • Verify all acceptance criteria across all tasks are met
    • Run full test suite for the feature
    • Review all files changed (use git diff)

14. Draft a PR description for the work unit (DO NOT create the PR yet - just draft the text):

    • Title format: [WORK-UNIT-SLUG] Work unit title (e.g., [DXX-WU-1] Shopping cart feature)
    • Body should include:
      • Work unit reference and summary
      • List of tasks completed
      • Summary of all changes across tasks
      • Files modified (use file.ts:42 format)
      • Test results

15. Use update_work_unit to set status to "completed" and save draft PR text and commit message:

    {
      status: "completed",
      completedAt: new Date(),
      devInfo: {
        ...existing,
        draftCommitMessage: "feat(cart): implement shopping cart feature\n\n- Add cart API endpoints\n- Add cart UI components\n- Add integration tests\n\nCloses: DXX-WU-1",
        draftPr: {
          title: "[DXX-WU-1] Shopping cart feature",
          body: "## Summary\n\nImplemented shopping cart feature.\n\n## Tasks Completed\n\n- [DXX-1] Add cart API\n- [DXX-2] Add cart UI\n- [DXX-3] Add cart tests\n\n## Changes\n\n- Added cart endpoints\n- Added cart components\n- Added integration tests\n\n## Files Modified\n\n- src/api/cart.ts:42\n- src/components/Cart.tsx:15\n- tests/cart.test.ts:1\n\n## Test Results\n\nAll tests passing. Coverage: 85%"
        },
        finalNotes: "All tasks completed. Files changed: [...]. Tests passing.",
        completedBy: "<member-id>",
        totalDuration: "3.5 hours"
      }
    }
    

    Note on draftCommitMessage: Write a conventional commit message that will be used for the final git commit. Format: type(scope): description with optional body listing changes.

16. Create final summary comment documenting:

    • Work unit scope and goals achieved
    • All files created/modified (use file.ts:42 format)
    • Test coverage and results
    • Any follow-up work needed
    • Performance or architectural notes

6. Handle Blockers or Scope Changes

17. If blocked on a task:

    • Use update_task to set task status to "Blocked"
    • Use update_work_unit to set status to "blocked"
    • Document blocker in work unit devInfo
    • Use create_task_comment on blocked task with details explaining what human intervention is needed
    • Consider creating follow-up tasks for blockers

18. If scope changes during execution:

    • Use create_task to add new tasks to work unit
    • Update work unit description/goals if needed
    • Communicate scope change in work unit comments

Common Mistakes to Avoid

• ❌ Starting without reviewing all tasks in work unit (lack of context)
• ❌ Working on tasks in wrong order (missing dependencies)
• ❌ Skipping vibe-lint MCP validation (MANDATORY for every file)
• ❌ Not tracking work unit-level progress in devInfo
• ❌ Completing tasks in isolation without considering work unit goals
• ❌ Not running integration tests between tasks
• ❌ Moving task to "Review" without first going through "Testing"
• ❌ Marking work unit complete when tasks are still in "In Progress" or "Testing"
• ❌ Not documenting scope changes or blockers
• ❌ Forgetting to commit between tasks (losing incremental progress)
• ❌ Not updating work unit status when blocked
• ❌ Setting work unit to "completed" before all tasks reach "Review" or "Done"
• ❌ Executing tasks that are still in "Planning" status (must be promoted to "Todo" via backlog-grooming first)

Source: hashgraph-online/awesome-codex-plugins → plugins/AgiFlow/ai-plugin/skills/run-work/SKILL.md