From 646313248e2c7915588df638a94e1d0fc4485006 Mon Sep 17 00:00:00 2001 From: Fernando de Oliveira <5161098+fedeoliv@users.noreply.github.com> Date: Thu, 7 May 2026 13:32:02 -0400 Subject: [PATCH] fix(implement): make work item state transitions mandatory and explicit The implement coordinator and the finalize worker treated board updates as advisory, so issues and Azure DevOps work items routinely stayed in New through the full implement and PR cycle, even though every required tool was wired up. Changes: - work-item-workflow source detection now resolves to board mode whenever a work item ID is reachable from the user request, recent conversation, or the tasks.md being implemented, including phrasings like 'implement the Terraform task' or 'continue the work'. tasks.md mode only applies when no ID is reachable. - work-item-workflow Phase 2 makes state transitions mandatory, with a re-read confirmation and a single retry before surfacing failure. If the board MCP is unreachable, the agent surfaces a blocking error rather than skipping silently. - devsquad.implement orchestration documents Phase 1 as a precondition. No code-editing tool runs until the task and parent user story are Active with the current user as assignee. - devsquad.implement.finalize replaces 'update as appropriate' with an explicit state machine (Active on start, Resolved on PR open, Closed on merge), per-platform procedure, and a structured 'Board Updated: # -> ' output so the coordinator can detect skipped transitions. CHANGELOG entry to be landed alongside the existing Unreleased WIP. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../agents/devsquad.implement.agent.md | 3 ++ .../devsquad.implement.finalize.agent.md | 38 ++++++++++++++----- .../skills/work-item-workflow/SKILL.md | 18 +++++---- 3 files changed, 43 insertions(+), 16 deletions(-) diff --git a/.github/plugins/devsquad/agents/devsquad.implement.agent.md b/.github/plugins/devsquad/agents/devsquad.implement.agent.md index 544dc69..e0b368c 100644 --- a/.github/plugins/devsquad/agents/devsquad.implement.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.implement.agent.md @@ -137,6 +137,8 @@ This agent is an **orchestrator**. The detailed steps are delegated to specializ **Worker delegation**: Steps 3-4 are delegated to `devsquad.implement.validate`, which returns impact classification and spec mapping. Steps 7-8 can use `devsquad.implement.execute` and `devsquad.implement.verify` respectively. Step 9 delegates to `devsquad.review` which internally fans out to 5 parallel compliance checkers. Step 10 delegates to `devsquad.implement.finalize`. +**Phase 1 is a precondition**, not an optional step. Before any code-editing tool is invoked (Step 7), confirm that `work-item-workflow` ran and the linked work item is in the active state with the current user as assignee. If a work item ID is reachable from the user's request, recent conversation, or the tasks.md being implemented but Phase 1 was not executed, stop and run it. If the board MCP is unreachable, surface a blocking error rather than silently proceeding with code edits. + **When to use workers vs inline**: Use workers when the step benefits from context isolation (verification, review). Keep steps inline when they require interactive developer dialogue (understanding checkpoint, code question guidance, churn detection). For **low-impact** tasks, skip steps 3, 5, 8, 9 and apply fast-track (see Impact Classification). @@ -423,6 +425,7 @@ If the pattern repeats (3+ modifications to the same code), suggest pausing impl - For Azure DevOps work items, the agent requires Azure DevOps MCP configured. - This agent does NOT close issues/work items automatically. The PR uses `Closes #N` to close on merge (GitHub) or the developer manually updates the state (Azure DevOps). - Automatic developer assignment when starting work prevents conflicts when multiple devs look at the same board. +- Board state transitions are mandatory, not advisory. Phase 1 sets the task and parent user story to active before any code is written; the finalize worker transitions the task to `Resolved` (Azure DevOps) when the PR opens. If the board MCP is unreachable, surface a blocking error rather than silently skipping. - Security review is executed following the `security-review` skill workflow. The verdict is used by this agent to decide the next step. ## Status Comments (GitHub) diff --git a/.github/plugins/devsquad/agents/devsquad.implement.finalize.agent.md b/.github/plugins/devsquad/agents/devsquad.implement.finalize.agent.md index 4a9138b..4b85533 100644 --- a/.github/plugins/devsquad/agents/devsquad.implement.finalize.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.implement.finalize.agent.md @@ -23,10 +23,14 @@ The coordinator passes: Execute the PR workflow following the `pull-request` skill. -### 2. Status Comments (GitHub) +### 2. Status Comments and State Transition (GitHub) -When working with a GitHub issue, add status comments: -- On PR creation, the comment is implicit via `Closes #N` in the PR body +When working with a GitHub issue: + +1. On PR creation, ensure the PR body contains `Closes #N` (the `pull-request` skill handles this) so the issue closes automatically on merge. +2. Verify the issue still has the `status:in-progress` label set by `work-item-workflow`. If it is missing, add it. +3. After PR creation, add a status comment on the issue with the PR URL and a one-line implementation summary. +4. Do not remove `status:in-progress` until merge. The label closes via `Closes #N` together with the issue. ### 3. CI Diagnostics (GitHub Actions) @@ -38,11 +42,24 @@ github/get_job_logs(owner, repo, run_id: , failed_only: true, re Present the error summary to the coordinator and suggest a fix. -### 4. Board Update (Azure DevOps) +### 4. State Transition (Azure DevOps) + +State transitions are mandatory, not advisory. The expected flow is: + +| Trigger | Task state | Parent User Story state | +|---|---|---| +| `work-item-workflow` Phase 1 (start of implement) | `Active` | `Active` if not already | +| PR opened (this step) | `Resolved` | unchanged | +| PR merged (developer or pipeline) | `Closed` | `Closed` if all child tasks are `Closed` | -When working with Azure DevOps work items: -- Update the work item state as appropriate -- Add relevant comments with implementation summary +This worker is responsible for the `Resolved` transition. Closing on merge is the developer's action (or a downstream pipeline), per `Rules` below. + +Procedure for this worker: + +1. Use `ado/wit_get_work_item` to confirm the task is in `Active`. If it is still in `New` or another pre-active state, the assignee/state preconditions from `work-item-workflow` Phase 1 were not satisfied. Surface this to the coordinator as a blocking error and do not proceed silently. +2. Use `ado/wit_update_work_item` to transition the task to `Resolved`. Include the PR URL in the update comment. +3. Re-read the work item to confirm the new state. If the read shows the old state, retry once and then surface the failure. +4. Add a comment on the work item with the implementation summary and the PR URL. ### 5. Next Task Suggestion @@ -57,12 +74,15 @@ Worker: finalize PR: [URL or "not created"] CI Status: [PASS | FAIL - summary] -Board Updated: [Yes/No - details] +Board Updated: [ -> | Skipped: | N/A (tasks.md only)] Next Task Suggestion: [task ID and title, or "none"] ``` +The `Board Updated` line must include the previous and new state explicitly (e.g., `#1690 Active -> Resolved`). If the transition was skipped, state the reason ("MCP unreachable", "task already in Resolved", "no work item linked"). The coordinator uses this line to detect skipped transitions. + ## Rules -- This agent does NOT close issues/work items automatically. The PR uses `Closes #N` to close on merge. +- This agent does NOT close issues/work items automatically. The PR uses `Closes #N` to close on merge (GitHub). Azure DevOps transition to `Closed` is the developer's action after merge. +- State transitions to `Resolved` (Azure DevOps) and the `status:in-progress` label hygiene (GitHub) are mandatory at this step. Do not silently skip them. - If CI fails, provide error summary for the coordinator to decide next steps. - If human PR review feedback identifies a preventable issue (something the agent should have caught), capture it via the `harness-learnings` skill so future implementations avoid the same mistake. diff --git a/.github/plugins/devsquad/skills/work-item-workflow/SKILL.md b/.github/plugins/devsquad/skills/work-item-workflow/SKILL.md index 396179d..1d80e13 100644 --- a/.github/plugins/devsquad/skills/work-item-workflow/SKILL.md +++ b/.github/plugins/devsquad/skills/work-item-workflow/SKILL.md @@ -7,11 +7,12 @@ description: "Work item workflow for implementation. Use when starting work on a ## Work Source Detection -Analyze the user's input to determine the source: +Classify the work source before any other action. Resolve in this priority order: -- **GitHub Issue**: user mentions an issue (e.g., "implement issue #42", "#15") -- **Azure DevOps Work Item**: user mentions a work item (e.g., "work item 1234", "task 5678") -- **tasks.md**: no issue/work item mentioned, skip this skill +1. **GitHub Issue or Azure DevOps Work Item** if a numeric ID is referenced anywhere in the user's message, the recent conversation, or the tasks.md being implemented (e.g., "implement issue #42", "#15", "work item 1234", "task 5678", or a tasks.md row that links to `#1690`). Any such reference activates board mode for the entire implementation, even if the user phrases the request as "implement the Terraform task" or "continue the work". +2. **tasks.md only** if no issue or work item ID is reachable from the current context. Skip this skill. + +When in doubt between the two, choose board mode and read the work item. Reading is read-only and cheap; silently skipping board updates is the failure this skill exists to prevent. ### Reading the Work Item @@ -35,12 +36,15 @@ Execute in order. If any check blocks, **STOP** and inform the user. ### 2. State update -- Move the task to active state: +State transitions are mandatory, not advisory. If the board MCP is unreachable, surface a blocking error rather than skipping the transition. + +- Move the task to the active state: - **GitHub**: Add label `status:in-progress` - - **Azure DevOps**: Change State per process template (invoke `board-config` skill for details) + - **Azure DevOps**: Change State per process template (invoke `board-config` skill for details; typical: `New` to `Active`) - Check the parent User Story: - - If the parent US is not in progress, update it as well + - If the parent is not yet in the active state, update it as well - Inform: "User Story #[ID] moved to In Progress." +- Confirm the transition succeeded by re-reading the work item and verifying the new state. If the read shows the old state, retry once and then surface the failure to the user before any code is written. ### 3. Dependency check