From 27b174b0e24fe38f95f2b035fe7edbbe8d863e44 Mon Sep 17 00:00:00 2001 From: Fernando de Oliveira <5161098+fedeoliv@users.noreply.github.com> Date: Fri, 16 Oct 2026 17:39:20 -0400 Subject: [PATCH 1/2] chore(board): verify required labels and tags (#38) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 40bf5936-fdf2-408a-afe7-dd07b66ed7da --- .../devsquad/agents/devsquad.decompose.agent.md | 15 ++++++++++++--- .../devsquad/agents/devsquad.kickoff.agent.md | 4 ++-- .../devsquad/agents/devsquad.plan.agent.md | 4 ++-- .../devsquad/agents/devsquad.specify.agent.md | 2 +- .../devsquad/skills/work-item-creation/SKILL.md | 11 ++++++++++- .../work-item-creation/references/azdo-format.md | 6 ++++-- .../references/github-format.md | 2 ++ CHANGELOG.md | 1 + docs/src/content/docs/skills/work-items.mdx | 2 +- docs/src/content/docs/work-items.mdx | 3 +++ 10 files changed, 38 insertions(+), 12 deletions(-) diff --git a/.github/plugins/devsquad/agents/devsquad.decompose.agent.md b/.github/plugins/devsquad/agents/devsquad.decompose.agent.md index d134e72..70fae32 100644 --- a/.github/plugins/devsquad/agents/devsquad.decompose.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.decompose.agent.md @@ -15,10 +15,10 @@ 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. -- **Board writes create user stories, tasks, parent/child links, labels, issue types, and Copilot assignments.** Does not close, delete, or modify unrelated work items. +- **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. -**Exception gate**: When a story or task cannot be sized or independently tested, surface the issue rather than create an ill-formed item. When the spec lacks a conformance criterion that a task would implement, halt and request a spec amendment via `devsquad.refine`. +**Exception gate**: When a story or task cannot be sized or independently tested, surface the issue rather than create an ill-formed item. For spec-derived tasks, when the spec lacks a conformance criterion the task would implement, halt and request a spec amendment via `devsquad.refine`. Approved standalone proposals follow the intake below and must include their own observable acceptance criteria. ### Agent-specific invariant @@ -54,6 +54,15 @@ Without `[CONDUCTOR]` → normal interactive flow. Consider the input above before proceeding (if not empty). +## Standalone Proposal Intake + +When the input is an approved refactor plan or technical-debt proposal rather than a feature or migration decomposition, use this narrow creation path instead of the Main Flow's spec discovery: + +1. Read the approved proposal and linked plan. Confirm the requested item type, observable scope, acceptance criteria, and any existing parent or dependencies. For a refactor task, require the feature and phase metadata specified by `work-item-creation`. Do not invent missing metadata or require a nonexistent feature spec solely to file a standalone proposal. +2. Identify the board via `board-config`, check duplicates, and confirm any unresolved scope or hierarchy details before creation. This intake does not authorize implementing code or expanding the approved proposal. +3. Create only the approved task or technical-debt item using `work-item-creation`, including its full required labels/tags and readback verification. Link any confirmed parent and dependencies, then verify those relationships. +4. Return the verified item URL and creation evidence to the caller. Stop and report partial creation or permission errors with existing IDs. Do not create a versioned `tasks.md` or report success before metadata and links are verified. + ## Main Flow 1. **Configuration**: Identify the current spec by checking both `docs/features/` and `docs/migrations/` directories. If the user specified a feature or migration, use it. Otherwise, list available specs from both directories and ask the user to choose. @@ -138,7 +147,7 @@ Consider the input above before proceeding (if not empty). | Cutover and rollback tasks exist? | Flag missing cutover/rollback tasks | | Every missing ADR has an associated task? | List decisions without task | - **If there are CRITICAL problems**: List and ask before creating issues. + **If there are CRITICAL problems**: Stop the batch and report the missing or inconsistent records. Preserve the draft and the IDs already created. Do not report successful synchronization or delegate implementation until the affected records, required labels/tags, and relationships have been read back and verified. 10. **Report completion**: diff --git a/.github/plugins/devsquad/agents/devsquad.kickoff.agent.md b/.github/plugins/devsquad/agents/devsquad.kickoff.agent.md index 73201b9..1285809 100644 --- a/.github/plugins/devsquad/agents/devsquad.kickoff.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.kickoff.agent.md @@ -1,7 +1,7 @@ --- name: devsquad.kickoff description: Structure project hierarchy (epics, features, dependencies) and sync with board. -tools: ['read/readFile', 'vscode/askQuestions', 'search/listDirectory', 'search/textSearch', 'search/fileSearch', 'search/codebase', 'edit/editFiles', 'edit/createFile', 'edit/createDirectory', 'execute/runInTerminal', 'execute/getTerminalOutput', 'github/issue_read', 'github/issue_write', 'github/list_issues', 'github/search_issues', 'github/sub_issue_write', 'ado/wit_create_work_item', 'ado/wit_get_work_item', 'ado/wit_add_child_work_items', 'ado/wit_work_items_link', 'ado/search_workitem'] +tools: ['read/readFile', 'vscode/askQuestions', 'search/listDirectory', 'search/textSearch', 'search/fileSearch', 'search/codebase', 'edit/editFiles', 'edit/createFile', 'edit/createDirectory', 'execute/runInTerminal', 'execute/getTerminalOutput', 'github/issue_read', 'github/issue_write', 'github/list_label', 'github/label_write', 'github/list_issues', 'github/search_issues', 'github/sub_issue_write', 'ado/wit_create_work_item', 'ado/wit_get_work_item', 'ado/wit_update_work_item', 'ado/wit_add_child_work_items', 'ado/wit_work_items_link', 'ado/search_workitem'] handoffs: - label: Specify Feature agent: devsquad.specify @@ -336,7 +336,7 @@ Epic: [Product Name] 3. **Link features as sub-issues of epics** using the platform's available tool for parent-child relationships 4. **Create dependency links** between features (if any) -**Important**: Do not skip step 3. Features must appear as sub-issues of the epic, not as independent issues. +**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 diff --git a/.github/plugins/devsquad/agents/devsquad.plan.agent.md b/.github/plugins/devsquad/agents/devsquad.plan.agent.md index 71b6f6c..8ab5a3a 100644 --- a/.github/plugins/devsquad/agents/devsquad.plan.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.plan.agent.md @@ -139,7 +139,7 @@ Triggered when the user mentions "refactor", "restructure", "reorganize", or sel 8. **Save**: `docs/features//refactor-plan.md` -9. **Optionally create a work item**: offer to file the refactor plan as a GitHub issue or Azure DevOps work item using the `work-item-creation` skill. +9. **Optionally hand off work item creation**: With developer confirmation, pass the refactor plan to `devsquad.decompose` for GitHub or Azure DevOps creation using `work-item-creation`, including required label/tag readback verification. This agent does not write to the board. ## Proactive Behavior @@ -289,7 +289,7 @@ Use the `adr-workflow` skill for the complete ADR creation flow: duplicate check Before proceeding to the zoom in, present a summary: ADRs created/updated, existing ADRs that will be followed, confirmed decisions. Ask `[Y/N]` to proceed. -If technical debt is identified during the analysis, ask whether the user wants to create work items on the board (`work-item-creation` skill, Tech Debt section). +If technical debt is identified, ask whether to hand the proposed items to `devsquad.decompose` for board creation using `work-item-creation`, including required labels/tags and readback verification. Do not create items directly from this read-only planning agent. **WAIT** for confirmation before proceeding. diff --git a/.github/plugins/devsquad/agents/devsquad.specify.agent.md b/.github/plugins/devsquad/agents/devsquad.specify.agent.md index f2e6c67..ec31e32 100644 --- a/.github/plugins/devsquad/agents/devsquad.specify.agent.md +++ b/.github/plugins/devsquad/agents/devsquad.specify.agent.md @@ -1,7 +1,7 @@ --- name: devsquad.specify description: Create or update a feature specification from a natural language description, including requirements clarification. -tools: ['read/readFile', 'vscode/askQuestions', 'search/listDirectory', 'search/textSearch', 'search/fileSearch', 'search/codebase', 'edit/editFiles', 'edit/createFile', 'edit/createDirectory', 'github/issue_read', 'github/issue_write', 'github/list_issues', 'ado/wit_create_work_item', 'ado/wit_get_work_item', 'ado/search_workitem'] +tools: ['read/readFile', 'vscode/askQuestions', 'search/listDirectory', 'search/textSearch', 'search/fileSearch', 'search/codebase', 'edit/editFiles', 'edit/createFile', 'edit/createDirectory', 'github/issue_read', 'github/issue_write', 'github/list_label', 'github/label_write', 'github/list_issues', 'ado/wit_create_work_item', 'ado/wit_get_work_item', 'ado/wit_update_work_item', 'ado/search_workitem'] handoffs: - label: Create Technical Plan agent: devsquad.plan diff --git a/.github/plugins/devsquad/skills/work-item-creation/SKILL.md b/.github/plugins/devsquad/skills/work-item-creation/SKILL.md index 59f0de7..97ea462 100644 --- a/.github/plugins/devsquad/skills/work-item-creation/SKILL.md +++ b/.github/plugins/devsquad/skills/work-item-creation/SKILL.md @@ -9,13 +9,22 @@ Before creating ANY work item, verify: 1. **Platform**: Read `.memory/board-config.md` to identify GitHub or Azure DevOps 2. **Duplicates**: Check if a similar work item already exists on the board -3. **Required tags/labels**: all present (see section below) +3. **Required tags/labels**: compute the complete set for this item type and verify they can be applied before creation (see Label and Tag Verification below) 4. **Title in correct format**: follow the Title section and check the outgoing title contains no invented sequential task or story identifier 5. **Body filled in**: per the platform format (see GitHub and Azure DevOps sections) 6. **Hierarchy**: parent linked correctly 7. **Durable descriptions**: body describes *behavior* using domain language, not implementation details (see Durability Rules below) 8. **Content style**: title and body follow the Content Style section below +## Label and Tag Verification + +1. Before each creation, compute the required set from the common labels, item type, feature, priority, and phase below. Include applicable conditional labels. Apply any confirmed repository naming convention consistently without dropping a required meaning. +2. For GitHub, list all repository labels, following pagination when needed, and create any missing required definitions before creating the issue. Use `github/list_label` and `github/label_write`, or an available authenticated GitHub CLI/API. Cache definitions within the session, but update the cache after creating a label. If listing or creating labels is denied or unavailable, report the exact missing labels and stop creation. Do not create an unlabeled item as a fallback. +3. Include the full label set in the GitHub issue creation request. For Azure DevOps, include the full required tag set in `System.Tags` on creation. Tags are values on the work item, not GitHub-style repository label definitions. Surface permission or tag-validation failures instead of silently omitting tags. +4. Read the created item back and verify that every required label or tag is stored. A successful creation response alone does not prove they were applied. Preserve additional existing labels and tags when repairing an item. +5. If readback shows omissions, add only the missing labels or merge missing tags into the stored tag set, then re-read once. If verification still fails or cannot be performed, report the existing item's ID or URL and missing values, stop the batch, and resume by repairing that item rather than creating a duplicate. +6. Only count an item as successfully created or create dependent items after verification passes. Report any partial batch and its verified items explicitly. Do not describe the batch as complete or clean up its draft while label/tag verification is incomplete. + ## Content Style Work items live on the board, get rendered in GitHub/ADO UIs, and are read by humans and agents long after creation. Apply these rules to **every** title, description, comment, and acceptance criterion. diff --git a/.github/plugins/devsquad/skills/work-item-creation/references/azdo-format.md b/.github/plugins/devsquad/skills/work-item-creation/references/azdo-format.md index d230712..07e4fab 100644 --- a/.github/plugins/devsquad/skills/work-item-creation/references/azdo-format.md +++ b/.github/plugins/devsquad/skills/work-item-creation/references/azdo-format.md @@ -1,5 +1,7 @@ # Azure DevOps Format +Apply the parent `work-item-creation` skill's Label and Tag Verification procedure for every item. Creation is incomplete until required labels or tags have been read back and verified. + ## Work Item Types per Process Template | Process Template | User Story Type | Task Type | @@ -12,13 +14,13 @@ ## Epics - **Type**: Epic -- **Tags**: `copilot-generated`, `ai-model:` +- **Tags**: `epic`, `copilot-generated`, `ai-model:` ## Features - **Type**: Feature - **Priority**: 1/2/3 -- **Tags**: `copilot-generated`, `ai-model:` +- **Tags**: `feature`, `copilot-generated`, `ai-model:`, `priority:` - **Parent**: use `ado/wit_add_child_work_items` ## User Stories (or equivalent) diff --git a/.github/plugins/devsquad/skills/work-item-creation/references/github-format.md b/.github/plugins/devsquad/skills/work-item-creation/references/github-format.md index 98397da..d005792 100644 --- a/.github/plugins/devsquad/skills/work-item-creation/references/github-format.md +++ b/.github/plugins/devsquad/skills/work-item-creation/references/github-format.md @@ -1,5 +1,7 @@ # GitHub Issues Format +Apply the parent `work-item-creation` skill's Label and Tag Verification procedure for every item. Creation is incomplete until required labels or tags have been read back and verified. + ## User Stories - **Required labels**: `copilot-generated`, `ai-model:`, `type:user-story`, `feature:`, `priority:` diff --git a/CHANGELOG.md b/CHANGELOG.md index 01427e1..bc1f4cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,7 @@ See `CONTRIBUTING.md` for full conventions. ### Changed +- 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. - 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/skills/work-items.mdx b/docs/src/content/docs/skills/work-items.mdx index 879eabf..858e6b1 100644 --- a/docs/src/content/docs/skills/work-items.mdx +++ b/docs/src/content/docs/skills/work-items.mdx @@ -55,7 +55,7 @@ Applies structure and rules when creating work items. The skill standardizes tit | Area | Detail | |------|--------| | Type rules | Uses the right structure for epics, features, stories, and tasks | -| Tagging | Applies required metadata such as Copilot and model tags | +| Tagging | Computes the complete required set, creates missing GitHub labels, and reads back stored labels or Azure DevOps tags before reporting success | | Linking | Creates parent-child and related links in the correct order | | Content checks | Verifies title format and required fields before creation | diff --git a/docs/src/content/docs/work-items.mdx b/docs/src/content/docs/work-items.mdx index c5746f3..bea3b7e 100644 --- a/docs/src/content/docs/work-items.mdx +++ b/docs/src/content/docs/work-items.mdx @@ -62,6 +62,9 @@ Additional by type: | Epic | `epic` | | Feature | `feature`, `priority:{p1,p2,p3}` | +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. + + ## Workflow