--- name: execute-tasks description: >- Execute and complete a specific list of tasks one by one. Use this skill whenever the user asks to work on, implement, execute, or do a specific set or batch of task IDs (e.g. "Do tasks OT-001, OT-002", "Work on these tasks one at a time"). Validates task statuses, executes implementation sequentially, updates documentation, transitions tasks to testing, records follow-up tasks, includes tasks.md changes in git commits, logs verification instructions in docs/task-verification.md, and checks project-description timestamps. --- # Execute Tasks Workflow Skill This skill defines the standardized procedure for executing a specific set of tasks sequentially with strict status validation, documentation updates, follow-up tracking, inclusion of `tasks.md` changes, per-task commits, and comprehensive verification instructions. --- ## 1. Task Status Validation & Confirmation Before starting execution on any given task ID, inspect its status using `./scripts/get-task `: - **Valid Statuses to Work On**: - `ready` / `pending` (Ready for implementation) - `in_progress` (Work currently active) - **Invalid / Ambiguous Statuses**: - `planning`: Scoping incomplete; requirements still unknown. - `triage`: Requirements known, but prioritization or technical approach unconfirmed. - `research`: Technical investigation required before planning. - `testing`: Feature is already implemented and currently awaiting human verification. - `done` / `fixed`: Task is already completed and verified. - `cancelled`: Task was discarded or rejected. - `blocked`: Task is waiting on external dependencies or decisions. > [!WARNING] > **Status Check Rule**: If any requested task is in an invalid status (such as `planning`, `triage`, `research`, `testing`, `done`, `cancelled`, or `blocked`), you **must stop, report the task ID and its current status to the user, explain why it is not ready for implementation, and ask for explicit confirmation** before proceeding with that task. --- ## 2. Step-by-Step Task Execution Loop Process each validated task **strictly one at a time** in the requested order: ```mermaid graph TD A[Inspect & Validate Task Status] --> B[Mark Task In Progress] B --> C[Implement Code & Fixes] C --> D[Run Build & Verification Tests] D --> E[Update Relevant Documentation] E --> F[Check Off Requirements & Transition to Testing] F --> G[Add Verification Steps to docs/task-verification.md] G --> H[Check 20-Commit Rule on docs/project-description.md] H --> I[Stage tasks.md & Create Git Commit per Task] I --> J{More Tasks in Batch?} J -- Yes --> A J -- No --> K[Output Verification Summary to User] ``` ### Step A: Mark In Progress Transition the task to active work: ```bash ./scripts/update-task --status in_progress ``` ### Step B: Implement Requirements 1. Read the task requirements using `./scripts/get-task `. 2. Inspect the relevant source files and implement the requested changes adhering to project architecture and best practices. 3. If partial implementation is required or edge cases emerge, record notes directly in the task description. ### Step C: Verify & Test Run build verification and automated tests to ensure no regressions: ```bash npm test -w @oldbear/client npm test -w @oldbear/shared ``` ### Step D: Update Documentation Check if the changes affect: - [README.md](file:///Users/tom/Projects/OldBearBattles/README.md) - `docs/` specifications or architecture guides Update the corresponding documentation files accordingly. ### Step E: Transition Task to Testing (Not Done) Check off completed checklist items and transition status to `testing`: ```bash ./scripts/update-task --status testing --check-all ``` If specific items need implementation notes: ```bash ./scripts/update-task --status testing --append-description "### Implementation Notes:\n- Completed core logic." ``` > [!IMPORTANT] > **Testing vs Done**: The agent sets the status to `testing`. The user will manually test the feature and create their own commit transitioning the status to `done` once verified. ### Step F: Record Newly Discovered Tasks If during the work any new bugs, edge cases, refactor opportunities, or follow-ups are discovered, log them immediately in `planning` status: ```bash ./scripts/add-task "Follow-up: " --project= --type= --status=planning -d "Discovered during work on :\n- [ ] Detail" ``` ### Step G: Update `docs/task-verification.md` Add clear, step-by-step verification instructions for the completed task into [docs/task-verification.md](file:///Users/tom/Projects/OldBearBattles/docs/task-verification.md) under the appropriate section: - Include task ID, title, where to find it in the UI, exact steps to execute, and pass/fail criteria. - *(Note: Once a human tester verifies a feature and marks it `done`, the verification steps are migrated from `docs/task-verification.md` into `docs/human-tests.md` as permanent regression tests).* ### Step H: Check 20-Commit Rule on Project Description Check the number of commits since `docs/project-description.md` was last modified: ```bash LAST_COMMIT=$(git log -n 1 --pretty=format:"%H" -- docs/project-description.md) git rev-list --count ${LAST_COMMIT}..HEAD ``` If the count is $\ge 20$ (or if major features/technologies were added): 1. Update `docs/project-description.md` with current UTC timestamp (`- Last Verified UTC: YYYY-MM-DDTHH:MM:SSZ`) and any major feature changes. 2. Update `docs/project-description.json` with `"lastVerifiedUtc": "YYYY-MM-DDTHH:MM:SSZ"`. 3. Include these files in the commit (resetting the 20-commit counter). ### Step I: Include tasks.md & Create Git Commit When creating the commit for the task: 1. **Always include `docs/tasks.md` and `docs/task-verification.md`**: Check `git status`. Ensure all changes to `docs/tasks.md` (including user edits or pre-staged edits) and `docs/task-verification.md` are staged: ```bash git add docs/tasks.md docs/task-verification.md git commit -m "(): " ``` *(At least one commit must be made per completed task before moving to the next task).* ### Step J: Verification Instructions in Response Always provide clear verification instructions so the user can easily test the work: 1. **Single Task / Small Batch**: Include clear, actionable step-by-step verification instructions directly in your response to the user. 2. **Batch / Many Tasks**: If executing a batch of multiple tasks, create a dedicated verification report in `docs/` (e.g. `docs/verification-report.md`) detailing the changes, commits, and verification steps for each task, and link to it in your final response.