From dbd9c9bbe87e4ee3d628e5e7cf22cee264778cc2 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] chore(workflow): keep temporary artifacts out of commits (#36) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 40bf5936-fdf2-408a-afe7-dd07b66ed7da --- .../plugins/devsquad/agents/devsquad.agent.md | 4 ++-- .../devsquad/agents/devsquad.decompose.agent.md | 17 +++++++++-------- .../devsquad/agents/devsquad.kickoff.agent.md | 8 +++++--- .../plugins/devsquad/skills/git-commit/SKILL.md | 6 ++---- CHANGELOG.md | 1 + docs/src/content/docs/agents/lifecycle.mdx | 10 +++++----- .../docs/concepts/reasoning-and-handoff.mdx | 2 +- .../docs/core-components/context-management.mdx | 16 ++++++++-------- docs/src/content/docs/work-items.mdx | 4 +++- 9 files changed, 36 insertions(+), 32 deletions(-) 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.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/CHANGELOG.md b/CHANGELOG.md index f41c9f2..275acf3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,6 +29,7 @@ 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 7235a68..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** 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/work-items.mdx b/docs/src/content/docs/work-items.mdx index 5b02242..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 @@ -72,6 +72,8 @@ Every creation includes the full required label or tag set and a readback check. | 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