diff --git a/.github/plugins/devsquad/agents/devsquad.agent.md b/.github/plugins/devsquad/agents/devsquad.agent.md index b587607..c2d7c3a 100644 --- a/.github/plugins/devsquad/agents/devsquad.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.agent.md @@ -48,8 +48,8 @@ Check existing artifacts to suggest the appropriate phase: | No structure on the board | `devsquad.kickoff` | | No specs in `docs/features/` | `devsquad.specify` | | Specs without `plan.md` | `devsquad.plan` | -| Plan without `tasks.md` | `devsquad.decompose` | -| Tasks ready | `devsquad.implement` | +| Plan without board tasks or a local-only `tasks.md` | `devsquad.decompose` | +| Board tasks or local-only tasks ready | `devsquad.implement` | --- diff --git a/.github/plugins/devsquad/agents/devsquad.decompose.agent.md b/.github/plugins/devsquad/agents/devsquad.decompose.agent.md index 70fae32..f95b8f0 100644 --- a/.github/plugins/devsquad/agents/devsquad.decompose.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.decompose.agent.md @@ -14,7 +14,7 @@ Detect the user's language from their messages or existing non-framework project The agent's tool list (`tools:` frontmatter) is the runtime authority. The constraints below are behaviors the agent must honor even when its tools permit otherwise. -- **Disk writes are scoped to `tasks.md`** at the feature or migration path. No source-code edits. +- **Disk writes are scoped to local-only task lists** at the feature or migration path and optional ignored drafts under `.memory/`. In board mode, do not create a versioned `tasks.md`. No source-code edits. - **Board writes create user stories, tasks, approved technical-debt items, parent/child links, labels, issue types, and Copilot assignments.** Does not close, delete, or modify unrelated work items. - **Terminal commands are read-only board introspection.** No mutating commands outside the board MCP/API. @@ -117,9 +117,10 @@ When the input is an approved refactor plan or technical-debt proposal rather th - **Validate consistency**: Tasks must reflect ADR decisions - Validate task completeness (each user story/migration scenario has all necessary tasks) -7. **Save local draft**: Save `docs/features//tasks.md` or `docs/migrations//tasks.md` as a record of what was planned. - - **Before saving and creating work items**, present the Reasoning Log in the format from the `reasoning` skill. Wait for confirmation before creating work items. +7. **Prepare the task record**: Present the Reasoning Log using the `reasoning` skill and obtain confirmation before creating work items. + - **Local-only mode**: Save `docs/features//tasks.md` or `docs/migrations//tasks.md` as the durable task list. Skip board creation and validate the local list instead. + - **GitHub or Azure DevOps mode**: Keep the draft in the session, or under `.memory/decompose//` only after confirming that directory is ignored by Git. Do not create or stage a feature or migration `tasks.md` for board mode. The verified work items become the durable task record. + - If resuming from an existing `tasks.md`, transfer its full task descriptions, acceptance criteria, dependencies, and relevant completion state. Verify every item and relationship on the board before treating the handoff as complete. Do not delete or overwrite an existing authored or tracked task list without an explicitly approved migration scope. On a partial failure, preserve the draft and report the created IDs so a retry repairs or reuses them instead of creating duplicates. 8. **Create Work Items**: Invoke the `work-item-creation` skill according to the chosen platform. Validate every outgoing title against its Title rules before creating GitHub or Azure DevOps items. Use the descriptive title without local task or story numbering, retaining the required feature prefix and board hierarchy and dependency links. @@ -172,7 +173,7 @@ When the input is an approved refactor plan or technical-debt proposal rather th - Cross-cutting: A (project level) - Feature-scoped: B (within the feature) - Local draft: docs/features//tasks.md + Task record: [verified board item URLs, or tasks.md path in local-only mode] Summary: - Total tasks: T @@ -183,7 +184,7 @@ When the input is an approved refactor plan or technical-debt proposal rather th Next step: `/devsquad.implement` to start implementation ``` - When handing off, include the Handoff Envelope per the `reasoning` skill, including: tasks.md, spec.md, plan.md, referenced ADRs, and decomposition assumptions. + When handing off, include the Handoff Envelope per the `reasoning` skill, including: verified task and parent work item URLs, spec.md, plan.md, referenced ADRs, and decomposition assumptions. In local-only mode, pass the tasks.md path instead of board URLs. Do not pass a deleted or temporary draft as the authoritative task record. 11. **Delegation to Copilot Coding Agent** (GitHub): @@ -205,11 +206,11 @@ When the input is an approved refactor plan or technical-debt proposal rather th ``` github/add_issue_comment(owner, repo, issue_number, body: - "📋 Decomposition completed by SDD Framework\n\n + "Decomposition completed by SDD Framework\n\n - Tasks created: N\n - Copilot-candidate: C\n - Pending ADRs: A\n\n - Details: docs/features//tasks.md") + Task records: [verified work item URLs]") ``` ## Identify Missing ADRs diff --git a/.github/plugins/devsquad/agents/devsquad.implement.agent.md b/.github/plugins/devsquad/agents/devsquad.implement.agent.md index 0453c48..5507802 100644 --- a/.github/plugins/devsquad/agents/devsquad.implement.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.implement.agent.md @@ -20,7 +20,7 @@ Detect the user's language from their messages or existing non-framework project The agent's tool list (`tools:` frontmatter) is the runtime authority. The constraints below are behaviors the agent must honor even when its tools permit otherwise. -- **Disk writes are scoped to the assigned task** in `tasks.md`. Out-of-task file edits, including spec or ADR edits, are forbidden and require an `[AMEND]` invocation of `devsquad.refine`. +- **Disk writes are scoped to the assigned board task or local-only `tasks.md` entry**. Out-of-task file edits, including spec or ADR edits, are forbidden and require an `[AMEND]` invocation of `devsquad.refine`. - **Git writes target the feature branch only.** Never `main`, `master`, `develop`, or any branch named in `.memory/git-config.md`. Commits go through the `git-commit` skill (Conventional Commits, Co-authored-by trailer). - **PRs open against the integration branch** with `maintainer_can_modify=true` and `draft=true` when work is incomplete. - **Never merges PRs.** Merge is always human. @@ -161,7 +161,7 @@ This agent is an **orchestrator**. The detailed steps are delegated to specializ 4. Impact Classification → sub-agent: devsquad.implement.validate 5. Understanding Checkpoint → inline (below) 6. Branch Management → skill: git-branch -7. Implementation Execution → sub-agent: devsquad.implement.execute + skill: git-commit (per task) +7. Implementation Execution → sub-agent: devsquad.implement.execute (coordinator commits after verification and Completion Checkpoint unless deferred) 8. Self-Verification → sub-agent: devsquad.implement.verify 9. Automated Review → sub-agent: devsquad.review (with parallel workers) 10. Finalization and PR → sub-agent: devsquad.implement.finalize + skill: pull-request @@ -170,11 +170,11 @@ 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. +**Phase 1 is a precondition in board mode**, not an optional step. Before editing, run `work-item-workflow`, including its resume check, and confirm the selected work item is owned by the current user and in the appropriate active state for new implementation. If existing evidence shows verified work awaiting review or merge, resume that stage without reactivating or reimplementing it. If a linked board item is present but its readiness checks were skipped or the board is unreachable, stop before code edits. In local-only mode, select the durable `tasks.md` entry instead of requiring a board assignee or state, and still run the Completion Checkpoint after verification. **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). Fast-track does not skip pipeline-protection verification when a pipeline is detected. +For **low-impact** tasks, skip steps 3, 5, 8, 9 and apply fast-track (see Impact Classification). Fast-track does not skip required verification, the Completion Checkpoint, temporary-artifact staging checks, or pipeline-protection verification when a pipeline is detected. ## Additional Context @@ -232,7 +232,7 @@ Spec drift occurs when implementation reveals that the spec or an ADR no longer When a `spec-drift` flag appears from either worker: -1. **Pause the task.** Do not proceed against a stale spec. If execute is mid-work, preserve partial progress via save-point before pausing. +1. **Pause the task.** Do not proceed against a stale spec. If execute is mid-work, preserve its partial diff and last verified state without committing unverified work or automatically stashing or reverting changes. 2. **Present the structured drift payload** to the developer: affected artifact and section, original statement, observed reality, impacted IDs, recommended scope, confidence. 3. **Suggest amendment; never silently apply.** Ask the developer to confirm, reject, or defer: - **Confirm**: hand off to `devsquad.refine` with `[AMEND]` prefix and the drift payload as amendment scope. Refine updates only the affected spec/ADR section and returns control. Re-decomposition is explicitly triggered next: invoke `devsquad.decompose` for the feature or slice so tasks reflect the amended artifacts. Resume implementation against the amended spec. @@ -315,13 +315,13 @@ Generic responses ("ok", "go", "do it") should trigger a request for more specif - **Test discipline**: Apply test-first or design-first-then-test per vertical slice as appropriate (consult the `test-discipline` skill) - **ADR compliance**: Follow documented architectural decisions - **Traceability**: Add comment referencing spec/task in generated code - - **Commit per task**: After completing each task (or group of parallel [P] tasks from the same phase), commit using the `git-commit` skill before proceeding to the next task. Each commit should represent a logical, functional unit of work. **Do not accumulate all changes for a single commit at the end.** + - **Logical commit scope per task**: The execution worker returns each task or same-phase [P] group as a pending commit scope. After required verification and the persisted/read-back Completion Checkpoint, the coordinator commits through `git-commit` before the next task unless the developer deferred commits. Preserve separate logical scopes when commits are deferred. 5. Progress tracking: - Report progress after each completed task - Interrupt execution if any non-parallel task fails - - **If using tasks.md**: Mark tasks as [X] in the file when completed - - **If using issue**: Add comment on the issue with progress (if requested) + - **Completion checkpoint is mandatory**: After required verification passes, invoke the Completion Checkpoint in `work-item-workflow` before moving to another task, reporting completion, or staging its logical commit. In local-only mode, persist the verified task's `[x]` checkbox first. In board mode, persist and read back implementation evidence even when commits or PR creation were deferred. Do not close work items before merge. + - **Resume safely**: Check durable completion evidence and linked PRs before assuming an active task still needs implementation. Resume review or finalization when its implementation is already verified. - **Pipeline protection**: When a pipeline is created, changed, or detected, run the read-only Pipeline Protection Check in `engineering-practices` and include the result in completion evidence. This also applies to low-impact pipeline/configuration tasks. - Provide clear error messages for debugging @@ -330,8 +330,8 @@ Generic responses ("ok", "go", "do it") should trigger a request for more specif For each task (or [P] group): 1. Implement the task 2. Verify that tests pass (no regression) - 3. Commit via git-commit skill (referencing issue/work item) - 4. Mark task as completed in tasks.md ([X]) + 3. Persist and read back the Completion Checkpoint (local checkbox or board evidence) + 4. Commit via git-commit skill unless the developer deferred commits, excluding temporary caches and board-mode task drafts 5. Proceed to next task ``` @@ -459,7 +459,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. +- In board mode, synchronization is mandatory. Phase 1 checks existing evidence before activating work that still needs implementation. The Completion Checkpoint records verified implementation before another task starts, and finalization records the PR using states supported by the actual Azure DevOps work item type. If the board is unreachable, report a blocking error instead of skipping synchronization. Local-only mode persists its task checkbox without requiring a board. - 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) @@ -471,7 +471,7 @@ github/add_issue_comment(owner, repo, issue_number, body: "🚀 Implementation started by SDD Framework\n\nBranch: ``") ``` -When creating a PR, the comment is already implicit via `Closes #N` in the PR body. +After required verification passes, persist the Completion Checkpoint even if no PR is requested yet. On PR creation, the finalize worker adds or updates the issue comment with the PR URL and retains `Closes #N` in the PR body. ## CI Diagnostics (GitHub Actions) @@ -534,11 +534,11 @@ Streamlined mode is activated when: **Low Impact** (automatic until test, then asks): ``` -Work Item Workflow → Branch → Implementation (commit per task) → Test -→ [QUESTION: push and PR?] +Work Item Workflow -> Branch -> Implement -> Verify -> Completion Checkpoint +-> Commit unless deferred -> Ask about push and PR ``` -No intermediate checkpoints. Skips: spec validation, understanding checkpoint, self-verification, automated review. Incremental commits per task remain mandatory. +No intermediate approval prompts. Skip spec validation, the understanding checkpoint, the separate verification worker, and automated review. Run required verification and persist/read back the Completion Checkpoint for every task before the coordinator commits or advances. Honor commit deferral and the pipeline-protection check when applicable. After tests pass: ``` @@ -552,13 +552,13 @@ Implementation completed. Tests passing. **Medium Impact** (plan checkpoint, then automatic until test): ``` -Work Item Workflow → Context → Classification → Implementation Plan -→ [CHECKPOINT: dev approves plan] -→ Branch → Implementation (commit per task) → Test → Automated Review -→ [QUESTION: push and PR?] +Work Item Workflow -> Context -> Classification -> Implementation Plan +-> Developer approves plan +-> Branch -> Implement -> Verify -> Completion Checkpoint -> Commit unless deferred +-> Automated Review -> Ask about push and PR ``` -After plan approval, executes implementation with incremental commits per task, tests, and review without stops. The automated review runs as sub-agent and auto-corrects Major findings (maximum 2 attempts). At the end, asks the dev whether to push and open PR. +After plan approval, execute each task with verification and a persisted/read-back Completion Checkpoint before the coordinator commits or advances. Honor commit deferral. Automated review runs as a sub-agent and auto-corrects Major findings (maximum 2 attempts). At the end, ask whether to push and open a PR. **High Impact** (not eligible): diff --git a/.github/plugins/devsquad/agents/devsquad.implement.execute.agent.md b/.github/plugins/devsquad/agents/devsquad.implement.execute.agent.md index 6db32da..10ab054 100644 --- a/.github/plugins/devsquad/agents/devsquad.implement.execute.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.implement.execute.agent.md @@ -1,13 +1,13 @@ --- name: devsquad.implement.execute -description: Implementation worker that executes coding tasks following TDD, phase ordering, and commit-per-task discipline. Invoked as a sub-agent by devsquad.implement. Do not use directly. +description: Implementation worker that executes coding tasks following TDD and phase ordering, and returns verified changes and logical commit scopes to the coordinator. Invoked as a sub-agent by devsquad.implement. Do not use directly. user-invocable: false tools: ['read/readFile', 'vscode/askQuestions', 'read/problems', 'search/changes', 'search/listDirectory', 'search/textSearch', 'search/fileSearch', 'search/codebase', 'search/usages', 'edit/editFiles', 'edit/createFile', 'edit/createDirectory', 'edit/rename', 'execute/runInTerminal', 'execute/getTerminalOutput', 'azure/get_azure_bestpractices', 'azure/bicepschema', 'azure/azureterraformbestpractices', 'microsoft-learn/microsoft_docs_search', 'microsoft-learn/microsoft_docs_fetch', 'microsoft-learn/microsoft_code_sample_search'] --- ## Role -Code execution worker for the implement coordinator. Execute a specific task or group of parallel [P] tasks, following TDD discipline and commit-per-task rules. +Code execution worker for the implement coordinator. Execute a specific task or group of parallel [P] tasks and return verification evidence and pending commit scopes. The coordinator owns task-status persistence and commits after the Completion Checkpoint. This worker does not commit. ## Input @@ -49,7 +49,7 @@ The test must fail BEFORE the fix and pass AFTER. If the test passes before the - **ADR compliance**: Follow documented architectural decisions - **Traceability**: Add comment referencing spec/task in generated code - **Consult harness learnings**: Before coding, read `.memory/harness-learnings.md` (if it exists) and check for entries whose Scope overlaps with the task's files. Apply high-confidence Guidance proactively to avoid known pitfalls. -- **Context budget**: If the conversation is growing large (many tool calls, long outputs), compress completed work into a brief summary and drop raw intermediate output. Commit progress and request a fresh context window from the coordinator rather than degrading in a bloated context. +- **Context budget**: If the conversation is growing large, return verified progress, remaining work, and pending commit scopes to the coordinator and request a fresh context window. Do not commit merely to free context, bypass the Completion Checkpoint, or override a developer instruction to defer commits. ### 3a. Pipeline Protection @@ -90,6 +90,7 @@ After each edit cycle: ### 7. Progress Tracking +- Return verification evidence for each implemented task to the coordinator. The coordinator must persist and read back the `work-item-workflow` Completion Checkpoint before advancing or reporting completion. Do not treat an unrecorded worker result as durable board state. - Report progress after each completed task - Interrupt execution if any non-parallel task fails - Provide clear error messages for debugging @@ -103,7 +104,7 @@ Do NOT escalate for internal refactor opportunities, naming, or non-observable p On drift detection: 1. Stop the current task. Do not work around a stale spec. -2. Commit or stash any partial work to a save-point as appropriate. +2. Preserve the partial diff and report the last verified state and unfinished scope to the coordinator. Do not commit unverified work or automatically stash or revert changes. 3. Return `spec-drift` in the output with the structured payload below. The coordinator handles the amendment loop; this worker does not edit specs directly. Low-impact fast-track tasks are not exempt: if execution uncovers drift, escalate regardless of the original classification. @@ -118,6 +119,7 @@ Worker: execute Tasks completed: [list of task IDs] Files modified: [list] Tests written: [list of test files/names] +Completion evidence: [verified scope, exact commands and outcomes, remaining work, and branch/commit when available] Pipeline protection: [not applicable | verified required checks | confirmed gap with recommendation | unable to verify with reason] Changes made: @@ -170,9 +172,9 @@ Do not return the output structure until the checkpoint resolves. If no triggers ## Rules -- Each task or [P] group should be a logical commit unit -- Do not accumulate all changes for a single commit at the end -- **Save-point protocol**: Commit after each passing task or [P] group. If tests fail after the next change, revert to the last committed state before investigating — do not debug on top of broken state +- Return each task or [P] group as a logical pending commit unit. Do not commit from this worker. +- The coordinator persists and reads back completion evidence before committing, and honors developer instructions to defer commits. +- **Save-point protocol**: Return the last verified state and failing task to the coordinator when verification fails. Preserve the diff for diagnosis instead of committing or automatically reverting it. Do not discard user changes or bypass synchronization to create a save-point. - If tests fail after implementation, use the `debugging-recovery` skill: reproduce, localize, fix root cause, guard with test (max 2 attempts then escalate) - When self-correction triggers fire (see Learning Capture Checkpoint), do not skip the user prompt; return output only after the checkpoint resolves - Do not modify code outside the scope of the current task. If you notice issues in adjacent code, report them in the "Not touched" section diff --git a/.github/plugins/devsquad/agents/devsquad.implement.finalize.agent.md b/.github/plugins/devsquad/agents/devsquad.implement.finalize.agent.md index 42c0f64..59baf36 100644 --- a/.github/plugins/devsquad/agents/devsquad.implement.finalize.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.implement.finalize.agent.md @@ -2,7 +2,7 @@ name: devsquad.implement.finalize description: Implementation worker that handles PR creation, board updates, and next task suggestion. Invoked as a sub-agent by devsquad.implement. Do not use directly. user-invocable: false -tools: ['read/readFile', 'vscode/askQuestions', 'search/changes', 'search/listDirectory', 'execute/runInTerminal', 'execute/getTerminalOutput', 'github/create_pull_request', 'github/list_pull_requests', 'github/pull_request_read', 'github/update_pull_request', 'github/add_issue_comment', 'github/get_job_logs', 'ado/wit_get_work_item', 'ado/wit_update_work_item', 'ado/repo_pull_request', 'ado/repo_pull_request_write'] +tools: ['read/readFile', 'vscode/askQuestions', 'search/changes', 'search/listDirectory', 'execute/runInTerminal', 'execute/getTerminalOutput', 'github/create_pull_request', 'github/list_pull_requests', 'github/pull_request_read', 'github/update_pull_request', 'github/add_issue_comment', 'github/issue_read', 'github/issue_write', 'github/get_job_logs', 'ado/wit_get_work_item', 'ado/wit_update_work_item', 'ado/repo_pull_request', 'ado/repo_pull_request_write'] --- ## Role @@ -19,9 +19,11 @@ The coordinator passes: ## Finalization Steps -### 1. PR Creation +### 1. Verify Completion Record and Create PR -Execute the PR workflow following the `pull-request` skill. +Confirm that the coordinator persisted the `work-item-workflow` Completion Checkpoint for every verified task, including when the developer deferred PR creation. If evidence is missing, run that checkpoint and read it back before continuing. If PR creation is deferred, return the persisted implementation status without opening a PR. + +When authorized, execute the PR workflow following the `pull-request` skill. ### 2. Status Comments and State Transition (GitHub) @@ -29,8 +31,8 @@ When working with a GitHub issue: 1. On PR creation, the PR body MUST contain `Closes #N` (the `pull-request` skill handles this) so the issue closes automatically on merge. This is mandatory, not optional, and remains required even when the body also carries non-closing references such as `Refs #N`. 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. After PR creation, add or update the verified-implementation status comment with the PR URL and implementation summary, then read it back. If the write or readback fails, report the synchronization error instead of claiming finalization succeeded. +4. Keep the issue open and retain `status:in-progress` until merge. `Closes #N` closes the issue on merge but does not itself remove labels. ### 3. CI Diagnostics (GitHub Actions) @@ -44,22 +46,12 @@ Present the error summary to the coordinator and suggest a fix. ### 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` | - -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: +Use the detected process and actual work item type's allowed states rather than assuming `Resolved` exists for every Task. -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. +1. Read the task's current state and verified-implementation evidence. Confirm it is active or already in a supported nonterminal ready-for-review state. A missing start-of-work transition is a blocking precondition failure. +2. On PR creation, use a supported nonterminal ready-for-review state, such as `Resolved` only when that state is available for this item type. If no such state exists, keep the active state and persist "Implementation verified, pending merge" with the PR URL and verification evidence. Do not set terminal `Done` or `Closed` before the required merge or acceptance event. +3. Preserve unrelated work item fields and tags. Read back both the state and the PR/evidence comment. Retry a missing update once, then report a blocking synchronization error. +4. Keep parent story progress distinct from final completion. Do not close a parent or its tasks automatically. Merge-time transitions and approved cascade closure remain the developer's or configured pipeline's responsibility. ### 5. Next Task Suggestion @@ -108,6 +100,6 @@ The `Board Updated` line must include the previous and new state explicitly (e.g - This agent does NOT close issues/work items automatically. On GitHub, the PR body uses `Closes #N` to close the issue on merge. Azure DevOps transition to `Closed` is the developer's action after merge. - Before delegating PR creation to the `pull-request` skill, verify the planned body contains `Closes #N` for every GitHub issue this PR fully resolves. `Closes #N` is mandatory and not optional. A non-closing reference such as `Refs #N` does not auto-close and does not substitute for it: when the body mixes `Refs #N` (or other non-closing references) with closing keywords, a `Closes #N` line must still be present for each fully-resolved issue. Spike PRs that complete the spike's deliverable still require `Closes #`. Regenerate the body if the keyword is missing. -- State transitions to `Resolved` (Azure DevOps) and the `status:in-progress` label hygiene (GitHub) are mandatory at this step. Do not silently skip them. +- Persist and verify the PR link, implementation evidence, and any supported nonterminal state transition. If Azure DevOps has no suitable nonterminal state, retaining the active state with verified evidence is valid and must be reported explicitly. - If CI fails, provide error summary for the coordinator to decide next steps. - When human PR feedback contradicts prior agent output (see Learning Capture Checkpoint), do not skip the user prompt; return output only after the checkpoint resolves. diff --git a/.github/plugins/devsquad/agents/devsquad.kickoff.agent.md b/.github/plugins/devsquad/agents/devsquad.kickoff.agent.md index 1285809..85153b0 100644 --- a/.github/plugins/devsquad/agents/devsquad.kickoff.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.kickoff.agent.md @@ -338,9 +338,11 @@ Epic: [Product Name] **Important**: Do not skip step 3. Features must appear as sub-issues of the epic, not as independent issues. Follow `work-item-creation` label/tag readback verification for each created item before creating its dependents or reporting success. On failure, report the existing IDs and missing values rather than continuing with unlabeled items. -### 9. Save Cache +### 9. Save Temporary Cache -`docs/envisioning/structure.md`: +Keep the board as the durable record. If a cache is useful, write `.memory/structure.md` only after confirming `.memory/` is ignored by Git. Otherwise keep the summary in the session and report the missing ignore rule. Never create or stage `docs/envisioning/structure.md` as an agent cache, and do not delete an existing user-authored file as cleanup. + +`.memory/structure.md` (optional, ignored): ```markdown # Structure (Cache) @@ -369,4 +371,4 @@ Epic: [Product Name] ## Handoff Envelope -When handing off to another agent (`devsquad.specify`, `devsquad.plan`), include Handoff Envelope per skill `reasoning`, including: docs/envisioning/structure.md, README.md, feature dependency assumptions, and pending prioritization. +When handing off to another agent (`devsquad.specify`, `devsquad.plan`), include Handoff Envelope per skill `reasoning`, including: verified board item URLs, README.md, feature dependency assumptions, and pending prioritization. Include `.memory/structure.md` only when that optional cache exists. Never make the next phase depend on a temporary cache. diff --git a/.github/plugins/devsquad/skills/git-commit/SKILL.md b/.github/plugins/devsquad/skills/git-commit/SKILL.md index eb4debc..9fa419d 100644 --- a/.github/plugins/devsquad/skills/git-commit/SKILL.md +++ b/.github/plugins/devsquad/skills/git-commit/SKILL.md @@ -91,11 +91,9 @@ git add docs/features/login/ # commit 3: docs(login) **Principle: one commit = one coherent logical change.** -If all changes are part of the same logical unit, stage everything: +Even for a single logical unit, stage explicit reviewed paths rather than using `git add -A`. Before staging, exclude agent-generated `structure.md` caches, ignored `.memory/` drafts, and board-mode `tasks.md` files. Local-only task lists remain durable artifacts and their verified checkbox updates belong in the task commit. -```bash -git add -A -``` +If an agent-generated cache is already staged, remove only that cache from the index without deleting its working copy. Do not unstage user changes or remove existing authored files automatically. If a legacy tracked task list needs migration to the board, require an approved scope and verified board transfer before staging its removal. ### 3. Pre-Commit Checks diff --git a/.github/plugins/devsquad/skills/work-item-workflow/SKILL.md b/.github/plugins/devsquad/skills/work-item-workflow/SKILL.md index 4c4da71..45dba41 100644 --- a/.github/plugins/devsquad/skills/work-item-workflow/SKILL.md +++ b/.github/plugins/devsquad/skills/work-item-workflow/SKILL.md @@ -1,6 +1,6 @@ --- name: work-item-workflow -description: "Work item workflow for implementation. Use when starting work on a GitHub issue or Azure DevOps work item to verify assignee, dependencies, priority, and capacity. Do not use for creating new work items (use work-item-creation), for suggesting the next task (use next-task), or when the work source is only tasks.md without an issue/work item." +description: "Work item workflow for implementation. Use when starting or completing work on a GitHub issue or Azure DevOps work item to verify readiness and persist completion evidence. Also use the Completion Checkpoint for verified local-only task lists. Do not use for creating new work items (use work-item-creation), for suggesting the next task (use next-task)." --- # Work Item Workflow @@ -10,7 +10,7 @@ description: "Work item workflow for implementation. Use when starting work on a Classify the work source before any other action. Resolve in this priority order: 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. +2. **tasks.md only** if no issue or work item ID is reachable from the current context. Skip board readiness checks, but run the Completion Checkpoint after verification. 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. @@ -22,6 +22,10 @@ When in doubt between the two, choose board mode and read the work item. Reading - Azure DevOps: `az account show --query user.name -o tsv` or ask the user 3. **Read work item via MCP**: Extract title, description, assignee, acceptance criteria, state, and tags/labels +### Resume Check Before State Changes + +Inspect the selected item's existing implementation evidence, linked PRs, and code/test evidence before changing its workflow state. If verified work is awaiting review or merge, retain its current state and resume review or finalization rather than reactivating the task or implementing it again. Do not reopen a terminal item without an explicit new scope. If the evidence is incomplete or no longer matches the current code, verify the remaining work before deciding what to implement. Apply the readiness state transition below only to work that genuinely needs implementation. + ## Required Checks Execute in order. If any check blocks, **STOP** and inform the user. @@ -96,6 +100,17 @@ State transitions are mandatory, not advisory. If the board MCP is unreachable, [C] Continue and pick up another task ``` +## Completion Checkpoint + +Run this checkpoint after the task's required verification succeeds and before moving to another task or reporting completion. It applies to low-impact work, autonomous execution, and sessions where the developer deferred committing or opening a PR. Verification failure is not completion. + +1. Read the current task or local checklist. On a resumed session, inspect existing implementation-status comments, linked PRs, and available code/test evidence before editing. If the task is already implemented and awaiting review or merge, continue from that stage instead of implementing it again. An active label alone does not prove work is missing or complete. +2. For a local-only `tasks.md`, mark only the verified task's checkbox `[x]` and read it back before staging the logical task commit. Preserve unchecked work and unrelated text. If committing is deferred, still persist the checkbox update. +3. For GitHub, add or update a durable issue comment stating "Implementation verified, pending PR" or "Implementation verified, pending merge" as applicable. Include the implemented scope, verification commands and outcomes, branch or commit when available, PR URL when present, and any remaining work. Keep the issue open with `status:in-progress` until merge and retain `Closes #N` in the eventual PR body. Do not mark unrelated or unmet acceptance criteria as satisfied. +4. For Azure DevOps, inspect the detected process and the actual work item type's allowed states. Use a supported nonterminal implementation-complete state when one exists, or retain the active state and add the same verified-implementation evidence in a comment. Do not assume every Task supports `Resolved`, and do not set terminal `Done` or `Closed` before the required merge or acceptance event. +5. Read back the updated checklist, issue comment, or work item state and comment to confirm it persisted. If the update is missing, retry once. If writing or verifying still fails, report the blocking synchronization error and do not advance to another task or claim completion. +6. For a parent story, record child progress with links and distinguish verified implementation from merged completion. Do not mark a parent complete or close it merely because its children have code written. Use Cascade Closure only after the required child completion events and user approval. + ## tasks.md (when no issue/work item is mentioned) 1. Identify the current feature by checking the `docs/features/` directory. If the user specified a feature, use it. diff --git a/CHANGELOG.md b/CHANGELOG.md index 2c73aef..275acf3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,6 +29,8 @@ See `CONTRIBUTING.md` for full conventions. - Work item creation now computes the complete required label/tag set, creates missing GitHub labels before issue creation, verifies stored metadata, and reports recoverable partial batches instead of silently continuing. Kickoff and specification agents have the minimum tools needed to apply and repair this metadata. - Pipeline creation, changes, or detection now trigger read-only verification of integration-branch protection, including effective GitHub rulesets or blocking Azure DevOps build validation. Missing protection produces a recommendation, while permission errors remain explicitly unverified. Repository settings are not changed without approval. +- Board-mode decomposition no longer creates versioned task lists. Temporary structure caches and drafts stay in the session or an ignored `.memory/` directory, and handoffs use verified work item URLs. Local-only task lists remain durable. Existing authored files are not removed automatically. +- Implementation now persists and reads back completion evidence before advancing, including when committing or PR creation is deferred. Resumed sessions inspect this evidence and linked PRs before coding again. GitHub closure remains merge-driven, and Azure DevOps uses states supported by the actual work item type without prematurely closing tasks or parent stories. - Work item creation and decomposition now explicitly exclude invented sequential task and story identifiers from generated GitHub and Azure DevOps titles. The task quality rubric checks this convention while preserving feature prefixes, domain numbers, native board IDs, hierarchy, and dependency links. Existing work items are not renamed automatically. - The `test-discipline` skill now explicitly covers tautological assertions, independent behavioral oracles, and behavior-preserving refactoring. Implementation and review workers and the code quality rubric reinforce these checks. Reuse existing behavioral tests and add tests only for concrete coverage gaps, without requiring mutation-testing tooling or banning legitimate test helpers and computed expectations. diff --git a/docs/src/content/docs/agents/lifecycle.mdx b/docs/src/content/docs/agents/lifecycle.mdx index 4f01d3f..34f69d6 100644 --- a/docs/src/content/docs/agents/lifecycle.mdx +++ b/docs/src/content/docs/agents/lifecycle.mdx @@ -25,7 +25,7 @@ flowchart LR kickoff -->|"board structure"| specify specify -->|"spec.md"| plan plan -->|"plan.md + ADRs"| decompose - decompose -->|"tasks.md + work items"| implement + decompose -->|"board tasks or local task list"| implement ``` --- @@ -76,12 +76,12 @@ Structure project hierarchy (epics, features, dependencies) and sync with the bo | | | |---|---| -| **Produces** | Board structure + `docs/envisioning/structure.md` (cache) | +| **Produces** | Board structure with an optional ignored `.memory/structure.md` cache | | **Handoff** | to specify or plan | | **Skills** | documentation-style, reasoning, work-item-creation, board-config, complexity-analysis | Adaptive modes based on state detection: @@ -139,11 +139,11 @@ Decompose specs into user stories, tasks, and work items. | | | |---|---| -| **Produces** | `tasks.md` + work items on board | +| **Produces** | Verified board work items, or `tasks.md` in local-only mode | | **Handoff** | to implement | | **Skills** | documentation-style, reasoning, work-item-creation, complexity-analysis, work-item-workflow, board-config | -11-step flow: Configuration, Detect environment, Sync board, Load design docs, Identify missing ADRs, Generate tasks, Save draft, Present for confirmation, Create work items, Validate, Report. +The flow detects the board mode, loads design context, generates and confirms tasks, creates work items with verified labels and relationships, and passes their URLs to implementation. Board-mode drafts remain in the session or ignored `.memory/`, while local-only mode keeps a durable `tasks.md`. Failed or partial synchronization preserves the draft and created IDs for recovery. Task organization by user story: **Models, Services, Endpoints, Integration** @@ -172,6 +172,7 @@ Key characteristics: - **Git workflow**: Branch creation following detected strategy, conventional commits - **PR automation**: Automated reviews, technical debt tracking, Copilot review option - **One task at a time**: Soft limit of 3 in-progress with warning signal +- **Durable completion**: Records and reads back verified implementation before advancing, even when committing or opening a PR is deferred. Existing status evidence prevents implementing completed work again. --- diff --git a/docs/src/content/docs/concepts/reasoning-and-handoff.mdx b/docs/src/content/docs/concepts/reasoning-and-handoff.mdx index af0d06f..d9bf40a 100644 --- a/docs/src/content/docs/concepts/reasoning-and-handoff.mdx +++ b/docs/src/content/docs/concepts/reasoning-and-handoff.mdx @@ -30,7 +30,7 @@ When work moves between phases (e.g., specify to plan), context is transferred v - Paths to files the next phase should read: `spec.md`, `plan.md`, ADRs, `tasks.md`. + Paths to design files (`spec.md`, `plan.md`, ADRs), plus verified board task URLs or `tasks.md` in local-only mode. Temporary caches are not required handoff artifacts. Decisions and assumptions from the current phase that carry forward and need validation. diff --git a/docs/src/content/docs/core-components/context-management.mdx b/docs/src/content/docs/core-components/context-management.mdx index 5826cfe..1621930 100644 --- a/docs/src/content/docs/core-components/context-management.mdx +++ b/docs/src/content/docs/core-components/context-management.mdx @@ -12,17 +12,17 @@ Agents use a multi-layered approach to manage context across phases and sessions ## Disk Artifacts (Source of Truth) -All persistent state lives in versioned files on disk. Board is the source of truth for **task status and ownership**. Disk artifacts are the source of truth for **design decisions, specifications, and architecture**. +Design artifacts live in versioned files on disk. The board is the source of truth for **board-backed task descriptions, relationships, status, and ownership**. Local-only projects keep their task lists on disk. Temporary drafts and caches stay in the session or ignored `.memory/`. Disk artifacts are the source of truth for **design decisions, specifications, and architecture**. | Artifact | Path | Phase | |----------|------|-------| | Strategic vision | `docs/envisioning/README.md` | Envision | | Feature specification | `docs/features/*/spec.md` | Specify | | Technical plan | `docs/features/*/plan.md` | Plan | -| Task decomposition | `docs/features/*/tasks.md` | Decompose | +| Local-only feature tasks | `docs/features/*/tasks.md` | Decompose | | Architecture decisions | `docs/architecture/decisions/*.md` | Plan | | Migration specification | `docs/migrations/*/spec.md` | Specify | -| Migration tasks | `docs/migrations/*/tasks.md` | Decompose | +| Local-only migration tasks | `docs/migrations/*/tasks.md` | Decompose | | Sprint records | `docs/sprints/sprint-N.md` | Sprint | ## Copilot Memory @@ -44,7 +44,7 @@ Structured context passing between phases ([ADR 0003](../../decisions/#adr-0003- - Paths to files the next phase should read (spec.md, plan.md, ADRs, tasks.md). + Paths to design artifacts (`spec.md`, `plan.md`, ADRs), plus verified board work item URLs or a local-only `tasks.md`. Decisions and assumptions from the current phase that carry forward. @@ -76,8 +76,8 @@ flowchart LR P2["ADRs"] end subgraph decompose["Decompose"] - D1["tasks.md"] - D2["Work Items"] + D1["Confirmed task scope"] + D2["Board items or local tasks.md"] end subgraph implement["Implement"] I1["Source Code"] @@ -92,7 +92,7 @@ flowchart LR P1 -->|"handoff envelope"| D1 P2 -->|"read from disk"| D1 D1 -->|"handoff envelope"| I1 - D2 -->|"board state"| I1 + D2 -->|"task state and evidence"| I1 I1 --> I2 I2 -->|"clean context"| R1 ``` @@ -104,7 +104,7 @@ Each arrow represents a phase boundary where context is explicitly passed via a 1. **specify to plan**: Spec locked, plan starts fresh reading spec from disk 2. **plan to decompose**: ADRs locked, decompose reads decisions from files -3. **decompose to implement**: Tasks locked, implement picks one task at a time +3. **decompose to implement**: Verified board URLs or a local-only task list passed to implementation, which checks existing completion evidence before coding 4. **implement to review**: Code committed, review reads independently with clean context diff --git a/docs/src/content/docs/skills/work-items.mdx b/docs/src/content/docs/skills/work-items.mdx index 858e6b1..b398d26 100644 --- a/docs/src/content/docs/skills/work-items.mdx +++ b/docs/src/content/docs/skills/work-items.mdx @@ -8,7 +8,7 @@ banner: import { Aside, Badge } from '@astrojs/starlight/components'; -These four skills support backlog setup, estimation, work item creation, and workflow checks before implementation starts. +These four skills support backlog setup, estimation, work item creation, readiness checks, and durable implementation status. ## board-config @@ -75,12 +75,14 @@ Checks implementation readiness for an existing work item. The skill confirms as | Dependencies | Verifies predecessor work is complete | | Priority | Confirms ordering against competing work | | Capacity | Checks whether the team can absorb the work now | +| Completion | Persists and reads back verification evidence or local task checkboxes before another task starts | +| Resume | Checks existing evidence and linked PRs to avoid implementing verified work again | -**Activation triggers:** Start of implementation, dependency review, work item readiness check. +**Activation triggers:** Start of implementation, dependency review, work item readiness checks, verified task completion, and resuming implementation. Completion evidence is required even when a commit or PR is deferred. --- diff --git a/docs/src/content/docs/work-items.mdx b/docs/src/content/docs/work-items.mdx index 71747f9..d60e86f 100644 --- a/docs/src/content/docs/work-items.mdx +++ b/docs/src/content/docs/work-items.mdx @@ -8,7 +8,7 @@ banner: import { Tabs, TabItem, Aside, Card, CardGrid, LinkCard } from '@astrojs/starlight/components'; -The board is the source of truth for **task status, assignment, and workflow state**. Design decisions and specifications remain authoritative as disk artifacts (specs, ADRs, `plan.md`). Local files (`tasks.md`, `structure.md`) are caches. Agents integrate with GitHub Issues and Azure DevOps for bidirectional work item management. +The board is the source of truth for **task status, assignment, and workflow state**. Design decisions and specifications remain authoritative as disk artifacts (specs, ADRs, `plan.md`). Board-mode drafts and optional `.memory/structure.md` caches are temporary and never committed. In local-only mode, `tasks.md` is the durable task list. Agents integrate with GitHub Issues and Azure DevOps for bidirectional work item management. ## Platform Detection @@ -64,6 +64,18 @@ Additional by type: Every creation includes the full required label or tag set and a readback check. GitHub label definitions are created before the issue when missing. Azure DevOps tags are stored on the work item. A permission failure or missing value stops the batch with the existing item URLs, allowing repair without duplicates. +## Task Records and Completion + +| Mode | Durable task record | After verification | +|------|---------------------|--------------------| +| GitHub | Issues, descriptions, relationships, and comments | Persist verified implementation evidence, then add the PR URL when available. Keep the issue open until merge. | +| Azure DevOps | Work items, relationships, state, and comments | Persist evidence and use a supported nonterminal state if available. Do not assume every Task has a `Resolved` state. | +| Local only | Feature or migration `tasks.md` | Mark only verified tasks `[x]` and read the update back before committing or moving on. | + +Board-backed decomposition does not create a versioned `tasks.md`. Drafts remain in the session or an ignored `.memory/` directory until all items, required labels/tags, and links have been verified. Existing authored task lists require an approved migration before removal. + +Completion evidence is required even when the developer defers a commit or PR. It distinguishes implementation awaiting review from work that still needs coding and from final merged completion. Resumed sessions inspect that evidence and linked PRs before editing again. + ## Workflow