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`](../../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: ```typescript 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: ```typescript 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`: ```typescript 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: ```typescript { 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)