From 9b6487d114ed3ea9de625927403a910d94a22970 Mon Sep 17 00:00:00 2001 From: Todd Martin Date: Sun, 31 May 2026 15:08:21 -0400 Subject: [PATCH 01/11] Added new skill --- .../skills/running-ai-dlc-breakdown/SKILL.md | 188 ++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md diff --git a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md new file mode 100644 index 0000000..cbe5c9e --- /dev/null +++ b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md @@ -0,0 +1,188 @@ +--- +name: running-ai-dlc-breakdown +description: Drive a Bitwarden tech breakdown end-to-end through the three-phase AI-DLC model (design → construction → delivery) in the bitwarden/tech-breakdowns repo. Use when starting, drafting, or executing any tech breakdown — single engineer or pair driving with a Claude agent, per-artifact approval gates, Q→D→A clarifications, codegen-plan-to-Jira slicing, and `state.md` as the file-grain ↔ ticket-grain bridge. +allowed-tools: Skill, Read, Write, Edit, Bash, Glob, Grep, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_comments, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_issues, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_confluence_page, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_confluence +--- + +This skill drives a Bitwarden tech breakdown from a fresh Jira ticket through to all-shipped, using the three-phase AI-DLC model captured in the [bitwarden/tech-breakdowns](https://github.com/bitwarden/tech-breakdowns) repo. It is the operating playbook for the new mode of work: a single engineer or pair, with a Claude agent, driving the design → construction → delivery loop end-to-end against per-artifact approval gates. + +This skill assumes: + +- The breakdown lives as markdown files in the `tech-breakdowns` repo. +- Execution is single-team, single-engineer/pair. A breakdown is **never** a cross-team carve-up; if the design surfaces work another team must own, that team owns a separate breakdown. +- Implementation is driven by sequential codegen, file-by-file, with the agent executing and the engineer reviewing each diff. +- Jira tracks delivery via QA-testable slices, not via file-grained codegen steps. + +Cross-team coordination _during the design phase_ (interface review, signoff from peer teams) happens through the Cross-team engagement section of `design.md` and the companion `Skill(coordinating-cross-team-breakdown)`. What this skill changes is the execution model, not the coordination model. + +## Repo layout + +``` +breakdowns// + PM-12345-feature-name.md ← design (Phase 1) + PM-12345-feature-name/ ← sibling folder, created when construction starts + construction/ + functional-design.md ← per-layer implementation design + non-functional.md ← security, observability + infrastructure.md ← deployment, environments + codegen-plan.md ← file-level execution plan + delivery/ + tasks.md ← QA-testable Jira slices + state.md ← file progress ↔ ticket progress bridge + clarifications/ ← Q→D→A files (created on demand) + q-.md +templates/ + tech-breakdown.md + construction/ + delivery/ + clarifications/question.md +``` + +Templates are canonical. Copy from `templates/`, never edit in place. + +## Bootstrap + +Before drafting anything, orient on the work: + +1. **Read the Jira ticket** the breakdown is being written against. Pull description, comments, and any linked Confluence pages. +2. **Check for an originating BW Initiative.** If the work sits under one, **run `Skill(navigating-the-initiative-funnel)` first** to pull the shepherd, sibling teams, architecture plan, and PoC PRs. The initiative context feeds the Specification and Cross-team engagement sections of `design.md`. +3. **Identify the owning team** and confirm the breakdown will live in `breakdowns//`. +4. **Copy `templates/tech-breakdown.md`** into the team's folder, renamed to `-.md` (e.g., `PM-23289-sync-push-notifications.md`). +5. **Delete the template checklist** at the top of the copied file. + +## The three phases + +The skill runs each phase as a gated loop: draft → clarify (Q→D→A as needed) → request approval → either iterate or advance. Phase boundaries are explicit; gates are explicit. + +### Phase 1 — Design + +Single file: `breakdowns//-.md`. Covers Specification, Clarifications Log, Architecture (high-level), Cross-team engagement, Agent Context. + +Drafting order: + +1. **Specification.** Description, User Value, Functional Requirements, Alternatives, Success Criteria. Don't paste Product spec; link it and frame in the team's voice. +2. **Architecture.** Current State (what exists today in code, with paths), Proposed architecture (prefer Mermaid diagrams over images), Out of Scope, Known Limitations, Prototypes. +3. **Cross-team engagement.** Walk the three subsections — consuming other teams' APIs, changes required in other teams' code, sequencing & ordering. Populate the signoff table. **Hand off to `Skill(coordinating-cross-team-breakdown)`** when chasing signoffs. +4. **Agent Context.** Repos affected (with `CLAUDE.md` pointers), existing patterns to follow, external references, things an agent should not assume. This block is what makes the breakdown useful to future Claude conversations — populate it explicitly, not as an afterthought. +5. **Clarifications Log.** Run an AI clarify pass against the draft _before_ requesting cross-team review. AI-raised questions go in `clarifications/q-.md` files via the Q→D→A pattern; resolved answers fold back into Spec or Architecture and the log entry becomes a short stub. + +**Design Approval Gate.** Sign the gate at the bottom of `design.md` to advance from PROPOSED to ACCEPTED. Update `state.md` (in `delivery/`) with the transition once the gate is signed and the sibling folder is created. + +### Phase 2 — Construction + +Create the sibling folder. Copy `templates/construction/*.md` into it. Four artifacts, each through its own approval gate: + +1. **`functional-design.md` first.** Per-layer changes: data model, server logic, API surface, SDK, client services, UI, background jobs, testing strategy. Fill only the layers this change touches; remove the rest. Each subsection's checklist evaluated explicitly (mark N/A when skipped, don't leave blank). +2. **`non-functional.md` and `infrastructure.md` in parallel** once functional design is approved. NFR covers security, cryptography, observability, operations. Infrastructure covers deployment, environments, feature flagging. +3. **`codegen-plan.md` last.** Numbered, checkbox-tracked list of every file to create or modify, in execution order. Each file traces back to a construction doc (e.g., "Source: `functional-design.md` § Data model changes"). Sequencing constraints called out explicitly (interfaces before consumers, types before usages). + +Each artifact ends with a 2-option approval gate. After each approval, update `state.md` with the artifact name, approval date, and what changed since the last gate. + +### Phase 3 — Delivery + +Copy `templates/delivery/*.md`. Two artifacts: + +1. **`tasks.md`** — carve the codegen plan into **vertical, QA-testable slices**. Each slice = one Jira ticket. Typical grain: 3-7 tasks per breakdown. For each task: title (the user-observable behavior), scope (which codegen-plan steps), acceptance criteria in Given/When/Then, test scenarios, blocked-on, Jira ID. + - ✅ "Web client receives SyncPush and triggers vault refresh" — observable, testable + - ✅ "API endpoint accepts and validates SyncPush payload" — testable contract + - ❌ "All data model changes" — horizontal, not testable + - ❌ "All files in `apps/web/`" — file boundary, not a behavior +2. **QA engagement.** Walk the responsible QA Engineer through `tasks.md` _before_ creating Jira tickets. Adjust scenarios and slice boundaries based on their input. Capture name, date, and notes in the QA engagement subsection. +3. **Create Jira tickets** from the approved tasks. Each ticket carries its AC and test scenarios from `tasks.md`. Cross-link the breakdown. + +Then execute: engineer + agent work the codegen plan file-by-file. As each file lands, check it off in `codegen-plan.md`. When all files in a slice are done, transition the Jira ticket. Update `state.md` after each ticket transitions. + +## Clarifications: two mechanisms, one index + +Clarifications come from two sources and use two different mechanisms. Keep them separate. + +| Source | Mechanism | Lives in | Lifecycle in `design.md` Clarifications Log? | +| ----------------------------------------- | ----------------------------------------------- | --------------------------------- | -------------------------------------------- | +| **Human-raised** (PM, AppSec, peer team) | Free-form table entry | Clarifications Log in `design.md` | Yes — full lifecycle (Open → Resolved) | +| **AI-raised** (this skill, mid-iteration) | Q→D→A files: multi-choice with `[Answer]:` tags | `clarifications/q-.md` | Only as a resolved stub after fold-back | + +The Clarifications Log is the **unified index** a future reader uses to see what questions drove the design. Q→D→A files are the **working artifacts** the agent uses during iteration. Open AI-raised questions live in their q-file and are tracked in `delivery/state.md`'s Open clarifications section — **not** in the design log (they're noise until resolved). + +### The Question → Doc → Approval pattern (AI-raised only) + +When clarification is needed mid-iteration (any phase), do not chase the question conversationally. Use the Q→D→A pattern: + +1. **Create a question file** at `breakdowns///clarifications/q-.md` using `templates/clarifications/question.md`. Questions use multiple-choice format with options A/B/C/X (X = custom) and `[Answer]:` tags. +2. **Stop and announce.** Tell the user: "Created `clarifications/q-.md` with N questions. Fill in each `[Answer]:` tag and let me know when ready." Add the file to `delivery/state.md`'s Open clarifications section. +3. **Wait.** Do not proceed past the questions. Do not infer answers. +4. **On the trigger phrase** — when the user says some variant of _"We have answered your clarification questions. Please re-read the file and proceed"_ — re-read the question file from disk (the user has edited it), validate answers for ambiguity, then **fold significant decisions back into the relevant phase doc** (Spec, Architecture, functional-design, etc.). Three follow-on updates: + - The question file's Resolved decisions section gets the fold-back note (q-file becomes audit trail). + - The Clarifications Log in `design.md` gets a short stub row: status Resolved, source `q-.md`, resolver name, one-line answer with link to the updated section. + - `delivery/state.md`'s Open clarifications section drops the q-file. +5. **Resume.** Continue the phase work with the new context. + +Answer-format guidance for the user (encoded in the template): + +- Letter + label: `C — financial summary` +- Letter + label + reasoning: `C — financial summary; needed for the quarterly review` +- Combined letters: `B and C — rate limiting at both gateway and application level` +- Custom: `X — ...` freely when no option fits + +### Human-raised clarifications + +Questions from PM, AppSec, peer teams, or anyone else reviewing the design come in free-form and don't fit the multi-choice shape. **Log them directly in the Clarifications Log table** in `design.md` with status Open, the source (person), an owner, and a target resolution date. Update to Resolved with a one-line answer and link to the section when the question is answered. Do not create a q-file for human-raised questions — the Q→D→A mechanism is specifically the agent's working tool. + +## `state.md` — the bridge + +**This file is non-optional.** It is what an agent picking up cold reads first, and what a human (manager, peer team, QA) reads to see status without opening codegen-plan, tasks, and Jira separately. Keep it current. + +`state.md` tracks three axes: + +1. **Phase progress** — checkboxes per artifact (design → construction artifacts → delivery artifacts) showing what's approved and what's pending. +2. **Execution status** — codegen plan progress (`N of M files complete`), tasks complete (`N of M tickets closed`), active codegen step (which file the agent is touching now, and which task it's part of), tickets in QA, active engineer/pair. +3. **Last gate** — most recent approval gate, date, outcome (Approved and Continue / Request Changes), notes on anything that changed since approval. + +**Update `state.md` on every gate transition and every meaningful execution event:** + +- Approval gate signed → update Phase progress + Last gate +- Codegen step complete → bump the codegen progress counter +- Task complete → bump the tasks-complete counter and move the ticket to "In QA" +- QA passes → close the ticket and remove from "In QA" +- New clarification file created → add to Open clarifications +- Clarification resolved → remove from Open clarifications + +The skill should never advance phases without checking `state.md` is current. If state and reality diverge, fix state first. + +## Hard rules (AI-DLC inheritance) + +These come from the AI-DLC pattern and are not negotiable: + +1. **2-option approval format only.** Each approval gate is "Request Changes" or "Approve and Continue." Never present a 3-option menu. Never invent an emergent navigation pattern. +2. **Never proceed past a gate without explicit approval.** "Looks fine" is not approval. The user must signal Approve and Continue. +3. **Never proceed past open Q→D→A questions.** If a `clarifications/q-*.md` file has unanswered `[Answer]:` tags, the phase work stops. +4. **Update plan checkboxes immediately.** Don't batch. Don't defer. As soon as a file is generated, mark the corresponding `codegen-plan.md` checkbox. +5. **Never overwrite `state.md` or audit content.** Update in place via Edit; don't Write over the whole file. +6. **Always validate content before file creation.** Mermaid diagrams parse, links resolve, file paths exist where claimed. +7. **Always read the canonical templates** before drafting an artifact. Templates evolve; don't work from memory. +8. **Never carve work across teams.** A breakdown is single-team. Cross-team work means multiple breakdowns, one per owning team. + +## Cross-references + +- **`Skill(coordinating-cross-team-breakdown)`** — the design-phase cross-team signoff workflow. Drives the Cross-team engagement section of `design.md`. Treat blocking signoffs as gates on Design Approval. +- **`Skill(navigating-the-initiative-funnel)`** — load-bearing when the breakdown sits under a BW Initiative. Pulls the shepherd, sibling teams' epics, architecture plan, and PoC PRs that feed Specification, Architecture, and Cross-team engagement. +- **`Skill(architecting-solutions)` (in `bitwarden-tech-lead`)** — the architectural-judgment lens to apply when drafting Architecture and reviewing functional-design. +- **`Skill(bitwarden-security-context)` (in `bitwarden-security-engineer`)** — route through this when `non-functional.md`'s Security section flags cryptographic work or new security definitions. + +## Common mistakes + +- **Drafting without the Jira ticket and initiative context.** A breakdown drafted in a vacuum diverges from the work that triggered it. Always start from the ticket and (when applicable) the initiative. +- **Treating `state.md` as optional.** Stale state means anyone picking up cold reads codegen-plan, tasks, and Jira separately and reconstructs the picture. The whole point of `state.md` is that they don't have to. +- **Skipping the Q→D→A pattern for "small" questions.** Conversational clarifications get lost. Question files survive the next context reset; chat does not. +- **Slicing tasks horizontally instead of vertically.** "All data model changes" is not a QA-testable slice. Each task must deliver something QA can validate end-to-end. +- **Creating Jira tickets before QA reviews `tasks.md`.** QA's job gets harder when ticket scope/scenarios are baked in without their input. Walk them through first. +- **Carving work across teams within one breakdown.** Cross-team execution means separate breakdowns, linked via the Cross-team engagement section. Trying to track multi-team work in one breakdown's `tasks.md` collapses the model. +- **Editing a template instead of copying it.** Templates are canonical; teams copy them. Editing in place corrupts the next breakdown's starting point. +- **Approving a gate to "save time" without reading the artifact.** Downstream gates treat upstream approvals as authoritative. A rubber-stamped functional-design becomes the source the codegen-plan trusts. +- **Letting `codegen-plan.md` checkboxes lag execution.** Drift between checkboxes and actual files breaks the file-grain ↔ ticket-grain bridge `state.md` depends on. + +## Reference + +- [bitwarden/tech-breakdowns repo](https://github.com/bitwarden/tech-breakdowns) — canonical templates and team folders. +- [tech-breakdowns README](https://github.com/bitwarden/tech-breakdowns/blob/main/README.md) — three-phase model, layout, workflow. +- [AI-DLC working guide](https://github.com/awslabs/aidlc-workflows/blob/main/docs/WORKING-WITH-AIDLC.md) — upstream inspiration for the Q→D→A pattern, approval gates, and state-tracking discipline. +- [EDD — Evolutionary Database Design](https://contributing.bitwarden.com/contributing/database-migrations/edd) — referenced in `functional-design.md`'s data-model checklist. From a7cacaa25c1e0fbabe3e5b5903f36d5bd43d1e3e Mon Sep 17 00:00:00 2001 From: Todd Martin Date: Sun, 31 May 2026 15:23:03 -0400 Subject: [PATCH 02/11] Updates to remove deliery --- .../skills/running-ai-dlc-breakdown/SKILL.md | 53 +++++++++++-------- 1 file changed, 31 insertions(+), 22 deletions(-) diff --git a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md index cbe5c9e..85eb756 100644 --- a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md +++ b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md @@ -1,10 +1,10 @@ --- name: running-ai-dlc-breakdown -description: Drive a Bitwarden tech breakdown end-to-end through the three-phase AI-DLC model (design → construction → delivery) in the bitwarden/tech-breakdowns repo. Use when starting, drafting, or executing any tech breakdown — single engineer or pair driving with a Claude agent, per-artifact approval gates, Q→D→A clarifications, codegen-plan-to-Jira slicing, and `state.md` as the file-grain ↔ ticket-grain bridge. +description: Drive a Bitwarden tech breakdown end-to-end through the three-phase AI-DLC model (design → construction → execution) in the bitwarden/tech-breakdowns repo. Use when starting, drafting, or executing any tech breakdown — single engineer or pair driving with a Claude agent, per-artifact approval gates, Q→D→A clarifications, codegen-plan-to-Jira slicing with team refinement, and `state.md` as the breakdown-wide tracker. allowed-tools: Skill, Read, Write, Edit, Bash, Glob, Grep, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_comments, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_issues, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_confluence_page, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_confluence --- -This skill drives a Bitwarden tech breakdown from a fresh Jira ticket through to all-shipped, using the three-phase AI-DLC model captured in the [bitwarden/tech-breakdowns](https://github.com/bitwarden/tech-breakdowns) repo. It is the operating playbook for the new mode of work: a single engineer or pair, with a Claude agent, driving the design → construction → delivery loop end-to-end against per-artifact approval gates. +This skill drives a Bitwarden tech breakdown from a fresh Jira ticket through to all-shipped, using the three-phase AI-DLC model captured in the [bitwarden/tech-breakdowns](https://github.com/bitwarden/tech-breakdowns) repo. It is the operating playbook for the new mode of work: a single engineer or pair, with a Claude agent, driving the design → construction → execution loop end-to-end against per-artifact approval gates. This skill assumes: @@ -21,25 +21,26 @@ Cross-team coordination _during the design phase_ (interface review, signoff fro breakdowns// PM-12345-feature-name.md ← design (Phase 1) PM-12345-feature-name/ ← sibling folder, created when construction starts + state.md ← breakdown-wide tracker (all phases) construction/ functional-design.md ← per-layer implementation design non-functional.md ← security, observability infrastructure.md ← deployment, environments codegen-plan.md ← file-level execution plan - delivery/ - tasks.md ← QA-testable Jira slices - state.md ← file progress ↔ ticket progress bridge + tasks.md ← QA-testable Jira slices (final construction gate) clarifications/ ← Q→D→A files (created on demand) q-.md templates/ tech-breakdown.md + state.md construction/ - delivery/ clarifications/question.md ``` Templates are canonical. Copy from `templates/`, never edit in place. +Three phases, not three folders. Design is a single `.md`; construction is a folder of artifacts; execution is the loop of running the codegen plan, transitioning Jira tickets, and updating `state.md` — no folder of its own. + ## Bootstrap Before drafting anything, orient on the work: @@ -66,31 +67,39 @@ Drafting order: 4. **Agent Context.** Repos affected (with `CLAUDE.md` pointers), existing patterns to follow, external references, things an agent should not assume. This block is what makes the breakdown useful to future Claude conversations — populate it explicitly, not as an afterthought. 5. **Clarifications Log.** Run an AI clarify pass against the draft _before_ requesting cross-team review. AI-raised questions go in `clarifications/q-.md` files via the Q→D→A pattern; resolved answers fold back into Spec or Architecture and the log entry becomes a short stub. -**Design Approval Gate.** Sign the gate at the bottom of `design.md` to advance from PROPOSED to ACCEPTED. Update `state.md` (in `delivery/`) with the transition once the gate is signed and the sibling folder is created. +**Design Approval Gate.** Sign the gate at the bottom of the design doc to advance from PROPOSED to ACCEPTED. Create the sibling folder, copy `templates/construction/*.md` and `templates/state.md` into it, and initialize `state.md` with the transition. ### Phase 2 — Construction -Create the sibling folder. Copy `templates/construction/*.md` into it. Four artifacts, each through its own approval gate: +Five artifacts in the sibling folder, each through its own approval gate: 1. **`functional-design.md` first.** Per-layer changes: data model, server logic, API surface, SDK, client services, UI, background jobs, testing strategy. Fill only the layers this change touches; remove the rest. Each subsection's checklist evaluated explicitly (mark N/A when skipped, don't leave blank). 2. **`non-functional.md` and `infrastructure.md` in parallel** once functional design is approved. NFR covers security, cryptography, observability, operations. Infrastructure covers deployment, environments, feature flagging. -3. **`codegen-plan.md` last.** Numbered, checkbox-tracked list of every file to create or modify, in execution order. Each file traces back to a construction doc (e.g., "Source: `functional-design.md` § Data model changes"). Sequencing constraints called out explicitly (interfaces before consumers, types before usages). +3. **`codegen-plan.md`** — numbered, checkbox-tracked list of every file to create or modify, in execution order. Each file traces back to a construction doc (e.g., "Source: `functional-design.md` § Data model changes"). Sequencing constraints called out explicitly (interfaces before consumers, types before usages). +4. **`tasks.md` — the final construction gate.** Carve the codegen plan into **vertical, QA-testable slices**. Each slice = one Jira ticket. Typical grain: 3-7 tasks per breakdown. For each task: title (the user-observable behavior), scope (which codegen-plan steps), acceptance criteria in Given/When/Then, test scenarios, blocked-on, Jira ID (filled after refinement). + - ✅ "Web client receives SyncPush and triggers vault refresh" — observable, testable + - ✅ "API endpoint accepts and validates SyncPush payload" — testable contract + - ❌ "All data model changes" — horizontal, not testable + - ❌ "All files in `apps/web/`" — file boundary, not a behavior + +Before approving `tasks.md`, two engagements happen — these are gating, not optional: + +- **Team refinement session.** The driving engineer/pair walks the whole team (engineers, tech lead, QA, PM as appropriate) through the construction artifacts and the proposed task slicing. This is where the broader team gets read-in, catches what the pair missed, and aligns with QA. Capture session date, attendees, and changes in the Team refinement section of `tasks.md`. +- **QA review.** The responsible QA Engineer reviews tasks and test scenarios (typically as part of refinement). Capture separately so QA ownership is unambiguous. Each artifact ends with a 2-option approval gate. After each approval, update `state.md` with the artifact name, approval date, and what changed since the last gate. -### Phase 3 — Delivery +### Phase 3 — Execution -Copy `templates/delivery/*.md`. Two artifacts: +Not a folder. Once the Tasks gate is signed, execution begins: -1. **`tasks.md`** — carve the codegen plan into **vertical, QA-testable slices**. Each slice = one Jira ticket. Typical grain: 3-7 tasks per breakdown. For each task: title (the user-observable behavior), scope (which codegen-plan steps), acceptance criteria in Given/When/Then, test scenarios, blocked-on, Jira ID. - - ✅ "Web client receives SyncPush and triggers vault refresh" — observable, testable - - ✅ "API endpoint accepts and validates SyncPush payload" — testable contract - - ❌ "All data model changes" — horizontal, not testable - - ❌ "All files in `apps/web/`" — file boundary, not a behavior -2. **QA engagement.** Walk the responsible QA Engineer through `tasks.md` _before_ creating Jira tickets. Adjust scenarios and slice boundaries based on their input. Capture name, date, and notes in the QA engagement subsection. -3. **Create Jira tickets** from the approved tasks. Each ticket carries its AC and test scenarios from `tasks.md`. Cross-link the breakdown. +1. **Create Jira tickets** from each approved task (carry over AC + test scenarios). Cross-link the breakdown. +2. **Engineer + agent work `codegen-plan.md` file-by-file.** Check off each file as it lands. +3. **Transition the Jira ticket** when all files in its slice are complete. Move it to QA review. +4. **QA validates** against the AC and test scenarios. Ticket closes when QA passes. +5. **Update `state.md`** after every meaningful event — codegen step complete, ticket created, ticket transitioned, ticket closed, QA blocked, clarification surfaced. -Then execute: engineer + agent work the codegen plan file-by-file. As each file lands, check it off in `codegen-plan.md`. When all files in a slice are done, transition the Jira ticket. Update `state.md` after each ticket transitions. +Repeat until all tickets are through QA. The breakdown is complete when `state.md` shows all tasks closed. ## Clarifications: two mechanisms, one index @@ -101,19 +110,19 @@ Clarifications come from two sources and use two different mechanisms. Keep them | **Human-raised** (PM, AppSec, peer team) | Free-form table entry | Clarifications Log in `design.md` | Yes — full lifecycle (Open → Resolved) | | **AI-raised** (this skill, mid-iteration) | Q→D→A files: multi-choice with `[Answer]:` tags | `clarifications/q-.md` | Only as a resolved stub after fold-back | -The Clarifications Log is the **unified index** a future reader uses to see what questions drove the design. Q→D→A files are the **working artifacts** the agent uses during iteration. Open AI-raised questions live in their q-file and are tracked in `delivery/state.md`'s Open clarifications section — **not** in the design log (they're noise until resolved). +The Clarifications Log is the **unified index** a future reader uses to see what questions drove the design. Q→D→A files are the **working artifacts** the agent uses during iteration. Open AI-raised questions live in their q-file and are tracked in `state.md`'s Open clarifications section — **not** in the design log (they're noise until resolved). ### The Question → Doc → Approval pattern (AI-raised only) When clarification is needed mid-iteration (any phase), do not chase the question conversationally. Use the Q→D→A pattern: 1. **Create a question file** at `breakdowns///clarifications/q-.md` using `templates/clarifications/question.md`. Questions use multiple-choice format with options A/B/C/X (X = custom) and `[Answer]:` tags. -2. **Stop and announce.** Tell the user: "Created `clarifications/q-.md` with N questions. Fill in each `[Answer]:` tag and let me know when ready." Add the file to `delivery/state.md`'s Open clarifications section. +2. **Stop and announce.** Tell the user: "Created `clarifications/q-.md` with N questions. Fill in each `[Answer]:` tag and let me know when ready." Add the file to `state.md`'s Open clarifications section. 3. **Wait.** Do not proceed past the questions. Do not infer answers. 4. **On the trigger phrase** — when the user says some variant of _"We have answered your clarification questions. Please re-read the file and proceed"_ — re-read the question file from disk (the user has edited it), validate answers for ambiguity, then **fold significant decisions back into the relevant phase doc** (Spec, Architecture, functional-design, etc.). Three follow-on updates: - The question file's Resolved decisions section gets the fold-back note (q-file becomes audit trail). - The Clarifications Log in `design.md` gets a short stub row: status Resolved, source `q-.md`, resolver name, one-line answer with link to the updated section. - - `delivery/state.md`'s Open clarifications section drops the q-file. + - `state.md`'s Open clarifications section drops the q-file. 5. **Resume.** Continue the phase work with the new context. Answer-format guidance for the user (encoded in the template): From 6232a7b09cfe33edc54058d1cc50b8610723db6a Mon Sep 17 00:00:00 2001 From: Todd Martin Date: Sun, 31 May 2026 18:07:45 -0400 Subject: [PATCH 03/11] Updates to separate tasks vs. stories. --- .../skills/running-ai-dlc-breakdown/SKILL.md | 79 ++++++++++++++----- 1 file changed, 61 insertions(+), 18 deletions(-) diff --git a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md index 85eb756..b008093 100644 --- a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md +++ b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md @@ -45,11 +45,12 @@ Three phases, not three folders. Design is a single `.md`; construction is a fol Before drafting anything, orient on the work: -1. **Read the Jira ticket** the breakdown is being written against. Pull description, comments, and any linked Confluence pages. -2. **Check for an originating BW Initiative.** If the work sits under one, **run `Skill(navigating-the-initiative-funnel)` first** to pull the shepherd, sibling teams, architecture plan, and PoC PRs. The initiative context feeds the Specification and Cross-team engagement sections of `design.md`. -3. **Identify the owning team** and confirm the breakdown will live in `breakdowns//`. -4. **Copy `templates/tech-breakdown.md`** into the team's folder, renamed to `-.md` (e.g., `PM-23289-sync-push-notifications.md`). -5. **Delete the template checklist** at the top of the copied file. +1. **Read the Jira epic** the breakdown is being written against. Pull description, comments, and any linked Confluence pages. +2. **Read all child user stories** under the epic and their acceptance criteria. Stories are **inputs** to the design — they describe user-observable outcomes the breakdown must deliver. If no user stories exist for the epic, **stop and surface this as a blocker**: stories belong to Product and should exist before engineering decomposition begins. Either work with Product to author them, or scope the breakdown to a single existing story. +3. **Check for an originating BW Initiative.** If the work sits under one, **run `Skill(navigating-the-initiative-funnel)` first** to pull the shepherd, sibling teams, architecture plan, and PoC PRs. The initiative context feeds the Specification and Cross-team engagement sections of `design.md`. +4. **Identify the owning team** and confirm the breakdown will live in `breakdowns//`. +5. **Copy `templates/tech-breakdown.md`** into the team's folder, renamed to `-.md` (e.g., `PM-23289-sync-push-notifications.md`). +6. **Delete the template checklist** at the top of the copied file. ## The three phases @@ -61,8 +62,8 @@ Single file: `breakdowns//-.md`. Covers Specificatio Drafting order: -1. **Specification.** Description, User Value, Functional Requirements, Alternatives, Success Criteria. Don't paste Product spec; link it and frame in the team's voice. -2. **Architecture.** Current State (what exists today in code, with paths), Proposed architecture (prefer Mermaid diagrams over images), Out of Scope, Known Limitations, Prototypes. +1. **Specification.** Description, User Value, **User Stories** (list each one with Jira ID, "As a … I want …" line, and AC summary — these are inputs, not authored here), Functional Requirements (each mapped to the story IDs it implements), Alternatives, Success Criteria. Don't paste Product spec; link it and frame in the team's voice. +2. **Architecture.** Current State (what exists today in code, with paths), Proposed architecture (prefer Mermaid diagrams over images), Out of Scope, Known Limitations, Prototypes. The architecture must cover every user story listed in the Specification. 3. **Cross-team engagement.** Walk the three subsections — consuming other teams' APIs, changes required in other teams' code, sequencing & ordering. Populate the signoff table. **Hand off to `Skill(coordinating-cross-team-breakdown)`** when chasing signoffs. 4. **Agent Context.** Repos affected (with `CLAUDE.md` pointers), existing patterns to follow, external references, things an agent should not assume. This block is what makes the breakdown useful to future Claude conversations — populate it explicitly, not as an afterthought. 5. **Clarifications Log.** Run an AI clarify pass against the draft _before_ requesting cross-team review. AI-raised questions go in `clarifications/q-.md` files via the Q→D→A pattern; resolved answers fold back into Spec or Architecture and the log entry becomes a short stub. @@ -76,11 +77,25 @@ Five artifacts in the sibling folder, each through its own approval gate: 1. **`functional-design.md` first.** Per-layer changes: data model, server logic, API surface, SDK, client services, UI, background jobs, testing strategy. Fill only the layers this change touches; remove the rest. Each subsection's checklist evaluated explicitly (mark N/A when skipped, don't leave blank). 2. **`non-functional.md` and `infrastructure.md` in parallel** once functional design is approved. NFR covers security, cryptography, observability, operations. Infrastructure covers deployment, environments, feature flagging. 3. **`codegen-plan.md`** — numbered, checkbox-tracked list of every file to create or modify, in execution order. Each file traces back to a construction doc (e.g., "Source: `functional-design.md` § Data model changes"). Sequencing constraints called out explicitly (interfaces before consumers, types before usages). -4. **`tasks.md` — the final construction gate.** Carve the codegen plan into **vertical, QA-testable slices**. Each slice = one Jira ticket. Typical grain: 3-7 tasks per breakdown. For each task: title (the user-observable behavior), scope (which codegen-plan steps), acceptance criteria in Given/When/Then, test scenarios, blocked-on, Jira ID (filled after refinement). - - ✅ "Web client receives SyncPush and triggers vault refresh" — observable, testable - - ✅ "API endpoint accepts and validates SyncPush payload" — testable contract - - ❌ "All data model changes" — horizontal, not testable - - ❌ "All files in `apps/web/`" — file boundary, not a behavior +4. **`tasks.md` — the final construction gate.** Carve the codegen plan into **engineering tasks**, each a vertical slice of implementation work that delivers (part of) one or more user stories. Typical grain: 3-7 tasks per breakdown, ~1-3 days each. + + Engineering tasks are **not user stories**. The relationship is one-to-many: one story → multiple engineering tasks. Each task has: + - **Stories served** — Jira IDs from the design's User Stories section + - **Scope** — codegen-plan steps it implements + - **Definition of Done** — engineering-shaped (tests pass, code reviewed, build green), **not** user-AC. Story AC stays on the Jira story; engineering tasks don't duplicate it. + - **Test scenarios** — edge cases for QA to cross-check (story AC is the user-facing contract) + - **Blocked on** — prerequisites among the other tasks + - **Jira ID** — typically created as a sub-task of the parent story + + Include a **Coverage check** subsection mapping every user story from the design to at least one task. If a story is uncovered, the decomposition is incomplete. + + Slicing principle: vertical implementation slices, not horizontal layer batches. + - ✅ "Implement SyncPush dispatcher and validation" — vertical, coherent implementation unit + - ✅ "Implement web client SyncPush handler" — vertical for the client side + - ❌ "All data model changes" — horizontal layer + - ❌ "All files in `apps/web/`" — file boundary, not implementation logic + + Note the exception path: if user stories don't exist (the blocker from bootstrap wasn't resolved), engineering tasks may carry story-shaped AC and become Jira stories rather than sub-tasks. Use sparingly; the right fix is upstream. Before approving `tasks.md`, two engagements happen — these are gating, not optional: @@ -91,15 +106,39 @@ Each artifact ends with a 2-option approval gate. After each approval, update `s ### Phase 3 — Execution -Not a folder. Once the Tasks gate is signed, execution begins: +Not a folder. Once the Tasks gate is signed, execution begins. -1. **Create Jira tickets** from each approved task (carry over AC + test scenarios). Cross-link the breakdown. +**Task "done" and story "done" are different events.** Tasks close on engineering DoD (tests, review, build, behind flag if applicable). Stories close on QA validation against story AC. QA does **not** gate individual task merges; it validates at the story boundary. The flagging path (chosen in `construction/infrastructure.md`) determines how tasks merge safely without per-task QA. + +Execution loop: + +1. **Create Jira tickets** from each approved task — typically as sub-tasks of the parent stories. Cross-link the breakdown. 2. **Engineer + agent work `codegen-plan.md` file-by-file.** Check off each file as it lands. -3. **Transition the Jira ticket** when all files in its slice are complete. Move it to QA review. -4. **QA validates** against the AC and test scenarios. Ticket closes when QA passes. -5. **Update `state.md`** after every meaningful event — codegen step complete, ticket created, ticket transitioned, ticket closed, QA blocked, clarification surfaced. +3. **Task done — engineering DoD met:** tests pass, code reviewed, build green, behind flag if applicable. Merge. Close the Jira sub-task. Update `state.md`'s Tasks complete counter. +4. **Story enters QA** when all tasks serving it have merged (and the flag is enabled in staging, if flagged). Engineer/pair notifies QA; add the story to `state.md`'s Stories awaiting QA section. +5. **QA validates** against story AC (not task DoD). Story closes on pass. Update `state.md`'s Stories validated counter. +6. **Flag flip (flagged path only):** once the story is validated in staging, coordinate the production flag flip per the team's release process. Update `state.md`'s Stories awaiting prod flag flip section. + +The breakdown is complete when `state.md` shows all stories validated (and all flags flipped, if applicable). + +### QA testing process + +See the README's QA testing process section for the full model. Skill-level summary: + +**Two paths**, decided in `construction/infrastructure.md`: + +- **Feature-flagged (default).** Tasks merge to main behind the flag. Story-level QA happens when all tasks for a story land + flag is enabled in staging. Flag flips to prod after QA passes. +- **Non-flagged.** Three sub-cases: + - **Task = story:** one task delivers a whole user-observable behavior; QA validates story AC at task merge. + - **Sequenced harmless intermediates:** tasks merge in dependency order; the final wiring task is QA's validation point. + - **Feature branch:** discouraged; must justify in `infrastructure.md`. + +**QA's two touchpoints:** + +- **Upstream — during construction refinement.** QA reviews `tasks.md`, confirms story AC is clear, suggests edge cases. Gating for the Tasks Approval Gate. +- **Downstream — during execution.** QA validates each story when its tasks have merged (+ flag enabled in staging if flagged). Gating for the story closing in Jira. -Repeat until all tickets are through QA. The breakdown is complete when `state.md` shows all tasks closed. +QA does not validate individual engineering tasks. Engineering DoD covers implementation correctness; story AC covers the user-facing contract. ## Clarifications: two mechanisms, one index @@ -169,6 +208,8 @@ These come from the AI-DLC pattern and are not negotiable: 6. **Always validate content before file creation.** Mermaid diagrams parse, links resolve, file paths exist where claimed. 7. **Always read the canonical templates** before drafting an artifact. Templates evolve; don't work from memory. 8. **Never carve work across teams.** A breakdown is single-team. Cross-team work means multiple breakdowns, one per owning team. +9. **User stories are inputs, not outputs.** Read them during bootstrap from Jira; reference them in the design's Specification; ensure construction's `tasks.md` covers every story. Don't author stories in this breakdown — they belong to Product and live in Jira. If they're missing, that's a blocker. +10. **Engineering task Definition of Done is not user AC.** Story AC stays on the Jira story. Engineering tasks describe implementation work; their DoD is implementation-shaped (tests pass, code reviewed, build green). ## Cross-references @@ -184,6 +225,8 @@ These come from the AI-DLC pattern and are not negotiable: - **Skipping the Q→D→A pattern for "small" questions.** Conversational clarifications get lost. Question files survive the next context reset; chat does not. - **Slicing tasks horizontally instead of vertically.** "All data model changes" is not a QA-testable slice. Each task must deliver something QA can validate end-to-end. - **Creating Jira tickets before QA reviews `tasks.md`.** QA's job gets harder when ticket scope/scenarios are baked in without their input. Walk them through first. +- **Confusing engineering tasks with user stories.** Stories describe user-observable outcomes with Given/When/Then AC, authored by Product, living in Jira. Engineering tasks describe implementation work and reference stories. Duplicating story AC onto engineering tasks creates two sources of truth and confuses QA. +- **Starting design without user stories.** Stories are inputs to the breakdown. Bootstrap should pull them; missing stories is a blocker, not a section to fill in. Engineering doesn't author stories on Product's behalf. - **Carving work across teams within one breakdown.** Cross-team execution means separate breakdowns, linked via the Cross-team engagement section. Trying to track multi-team work in one breakdown's `tasks.md` collapses the model. - **Editing a template instead of copying it.** Templates are canonical; teams copy them. Editing in place corrupts the next breakdown's starting point. - **Approving a gate to "save time" without reading the artifact.** Downstream gates treat upstream approvals as authoritative. A rubber-stamped functional-design becomes the source the codegen-plan trusts. From 016e8f284964d94b9bf4b929ed515054e38eae54 Mon Sep 17 00:00:00 2001 From: Todd Martin Date: Mon, 1 Jun 2026 12:45:46 -0400 Subject: [PATCH 04/11] Enhancements. --- .../skills/running-ai-dlc-breakdown/SKILL.md | 65 ++++++++++--------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md index b008093..54b4fbe 100644 --- a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md +++ b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md @@ -19,27 +19,29 @@ Cross-team coordination _during the design phase_ (interface review, signoff fro ``` breakdowns// - PM-12345-feature-name.md ← design (Phase 1) - PM-12345-feature-name/ ← sibling folder, created when construction starts + PM-12345-feature-name.md ← design overview (cold-start entry, Phase 1) + PM-12345-feature-name/ ← sibling folder, created when design begins state.md ← breakdown-wide tracker (all phases) - construction/ + design/ functional-design.md ← per-layer implementation design - non-functional.md ← security, observability - infrastructure.md ← deployment, environments + non-functional-design.md ← security, observability + infrastructure-design.md ← deployment, environments, flagging + construction/ codegen-plan.md ← file-level execution plan tasks.md ← QA-testable Jira slices (final construction gate) clarifications/ ← Q→D→A files (created on demand) q-.md templates/ - tech-breakdown.md + tech-breakdown.md ← design overview template state.md - construction/ + design/ ← detailed design artifacts + construction/ ← codegen plan + tasks clarifications/question.md ``` Templates are canonical. Copy from `templates/`, never edit in place. -Three phases, not three folders. Design is a single `.md`; construction is a folder of artifacts; execution is the loop of running the codegen plan, transitioning Jira tickets, and updating `state.md` — no folder of its own. +Three phases. Design is the overview `.md` plus detailed sub-artifacts in `design/` (each with its own approval sub-gate, rolled up by the Design Approval Gate at the bottom of the overview). Construction is thin — just the codegen plan and task decomposition. Execution is the loop of running the codegen plan, transitioning Jira tickets, and updating `state.md` — no folder of its own. ## Bootstrap @@ -50,65 +52,66 @@ Before drafting anything, orient on the work: 3. **Check for an originating BW Initiative.** If the work sits under one, **run `Skill(navigating-the-initiative-funnel)` first** to pull the shepherd, sibling teams, architecture plan, and PoC PRs. The initiative context feeds the Specification and Cross-team engagement sections of `design.md`. 4. **Identify the owning team** and confirm the breakdown will live in `breakdowns//`. 5. **Copy `templates/tech-breakdown.md`** into the team's folder, renamed to `-.md` (e.g., `PM-23289-sync-push-notifications.md`). -6. **Delete the template checklist** at the top of the copied file. +6. **Create the sibling folder** with the same name and copy `templates/design/*.md`, `templates/construction/*.md`, and `templates/state.md` into it. +7. **Delete the template checklist** at the top of the overview file. ## The three phases -The skill runs each phase as a gated loop: draft → clarify (Q→D→A as needed) → request approval → either iterate or advance. Phase boundaries are explicit; gates are explicit. +The skill runs each phase as a gated loop: draft → clarify (Q→D→A as needed) → complete artifacts → request gate approval → either iterate or advance. **Two approval gates total per breakdown**: the Design Approval Gate (rolls up all design work) and the Tasks Approval Gate (rolls up all construction work). Individual artifacts have completion checklists, not per-artifact gates. ### Phase 1 — Design -Single file: `breakdowns//-.md`. Covers Specification, Clarifications Log, Architecture (high-level), Cross-team engagement, Agent Context. +Two parts: the overview (single file: `breakdowns//-.md`) and the detailed design artifacts (in the sibling `design/` folder). -Drafting order: +**Overview drafting order:** 1. **Specification.** Description, User Value, **User Stories** (list each one with Jira ID, "As a … I want …" line, and AC summary — these are inputs, not authored here), Functional Requirements (each mapped to the story IDs it implements), Alternatives, Success Criteria. Don't paste Product spec; link it and frame in the team's voice. -2. **Architecture.** Current State (what exists today in code, with paths), Proposed architecture (prefer Mermaid diagrams over images), Out of Scope, Known Limitations, Prototypes. The architecture must cover every user story listed in the Specification. +2. **Architecture (high-level).** Current State (what exists today in code, with paths), Proposed architecture (prefer Mermaid diagrams over images), Out of Scope, Known Limitations, Prototypes. The architecture must cover every user story listed in the Specification. Per-layer detail lives in `design/functional-design.md`, not here. 3. **Cross-team engagement.** Walk the three subsections — consuming other teams' APIs, changes required in other teams' code, sequencing & ordering. Populate the signoff table. **Hand off to `Skill(coordinating-cross-team-breakdown)`** when chasing signoffs. -4. **Agent Context.** Repos affected (with `CLAUDE.md` pointers), existing patterns to follow, external references, things an agent should not assume. This block is what makes the breakdown useful to future Claude conversations — populate it explicitly, not as an afterthought. +4. **Agent Context.** Durable reference content for future agent invocations: repos affected (with `CLAUDE.md` pointers), existing patterns to follow, external references, things an agent should not assume. Stable design-phase context only — current-position state (which phase, who's driving, last gate) lives in `state.md`, not here. Populate explicitly, not as an afterthought. 5. **Clarifications Log.** Run an AI clarify pass against the draft _before_ requesting cross-team review. AI-raised questions go in `clarifications/q-.md` files via the Q→D→A pattern; resolved answers fold back into Spec or Architecture and the log entry becomes a short stub. -**Design Approval Gate.** Sign the gate at the bottom of the design doc to advance from PROPOSED to ACCEPTED. Create the sibling folder, copy `templates/construction/*.md` and `templates/state.md` into it, and initialize `state.md` with the transition. +**Detailed design artifacts in `design/`.** Each has a completion checklist but no per-artifact gate; they roll up to the overview's Design Approval Gate. + +1. **`functional-design.md`** — per-layer changes: data model, server logic, API surface, SDK, client services, UI, background jobs, testing strategy. Fill only the layers this change touches; remove the rest. Each subsection's checklist evaluated explicitly (mark N/A when skipped, don't leave blank). +2. **`non-functional-design.md`** — security, cryptography, observability, operations. Drafted in parallel with step 3 once functional-design is complete. +3. **`infrastructure-design.md`** — deployment, environments, feature flagging strategy. Drafted in parallel with step 2 once functional-design is complete. + +**Design Approval Gate.** Sign the gate at the bottom of the overview when all three design artifacts have their completion checklists satisfied AND cross-team signoffs are complete. Status advances PROPOSED → ACCEPTED. Update `state.md` with the transition. ### Phase 2 — Construction -Five artifacts in the sibling folder, each through its own approval gate: +Two artifacts in the sibling `construction/` folder. Each has a completion checklist but no per-artifact gate; both roll up to the single **Tasks Approval Gate**. -1. **`functional-design.md` first.** Per-layer changes: data model, server logic, API surface, SDK, client services, UI, background jobs, testing strategy. Fill only the layers this change touches; remove the rest. Each subsection's checklist evaluated explicitly (mark N/A when skipped, don't leave blank). -2. **`non-functional.md` and `infrastructure.md` in parallel** once functional design is approved. NFR covers security, cryptography, observability, operations. Infrastructure covers deployment, environments, feature flagging. -3. **`codegen-plan.md`** — numbered, checkbox-tracked list of every file to create or modify, in execution order. Each file traces back to a construction doc (e.g., "Source: `functional-design.md` § Data model changes"). Sequencing constraints called out explicitly (interfaces before consumers, types before usages). -4. **`tasks.md` — the final construction gate.** Carve the codegen plan into **engineering tasks**, each a vertical slice of implementation work that delivers (part of) one or more user stories. Typical grain: 3-7 tasks per breakdown, ~1-3 days each. +1. **`codegen-plan.md`** — numbered, checkbox-tracked list of every file to create or modify, in execution order. Each file traces back to a design artifact (e.g., "Source: `../design/functional-design.md` § Data model changes"). Sequencing constraints called out explicitly (interfaces before consumers, types before usages). +2. **`tasks.md`** — the artifact that carries the Tasks Approval Gate at its bottom. Carve the codegen plan into **engineering tasks**, each a vertical slice of implementation work that delivers (part of) one or more user stories. Typical grain: 3-7 tasks per breakdown, ~1-3 days each. Engineering tasks are **not user stories**. The relationship is one-to-many: one story → multiple engineering tasks. Each task has: - - **Stories served** — Jira IDs from the design's User Stories section + - **Stories served** — Jira IDs from the overview's User Stories section - **Scope** — codegen-plan steps it implements - **Definition of Done** — engineering-shaped (tests pass, code reviewed, build green), **not** user-AC. Story AC stays on the Jira story; engineering tasks don't duplicate it. - **Test scenarios** — edge cases for QA to cross-check (story AC is the user-facing contract) - **Blocked on** — prerequisites among the other tasks - **Jira ID** — typically created as a sub-task of the parent story - Include a **Coverage check** subsection mapping every user story from the design to at least one task. If a story is uncovered, the decomposition is incomplete. + Include a **Coverage check** subsection mapping every user story from the overview to at least one task. If a story is uncovered, the decomposition is incomplete. Slicing principle: vertical implementation slices, not horizontal layer batches. - - ✅ "Implement SyncPush dispatcher and validation" — vertical, coherent implementation unit - - ✅ "Implement web client SyncPush handler" — vertical for the client side - - ❌ "All data model changes" — horizontal layer - - ❌ "All files in `apps/web/`" — file boundary, not implementation logic Note the exception path: if user stories don't exist (the blocker from bootstrap wasn't resolved), engineering tasks may carry story-shaped AC and become Jira stories rather than sub-tasks. Use sparingly; the right fix is upstream. -Before approving `tasks.md`, two engagements happen — these are gating, not optional: +Before signing the Tasks Approval Gate, two engagements happen — these are gating, not optional: - **Team refinement session.** The driving engineer/pair walks the whole team (engineers, tech lead, QA, PM as appropriate) through the construction artifacts and the proposed task slicing. This is where the broader team gets read-in, catches what the pair missed, and aligns with QA. Capture session date, attendees, and changes in the Team refinement section of `tasks.md`. - **QA review.** The responsible QA Engineer reviews tasks and test scenarios (typically as part of refinement). Capture separately so QA ownership is unambiguous. -Each artifact ends with a 2-option approval gate. After each approval, update `state.md` with the artifact name, approval date, and what changed since the last gate. +After the Tasks Approval Gate is signed, update `state.md` with the transition and proceed to execution. ### Phase 3 — Execution Not a folder. Once the Tasks gate is signed, execution begins. -**Task "done" and story "done" are different events.** Tasks close on engineering DoD (tests, review, build, behind flag if applicable). Stories close on QA validation against story AC. QA does **not** gate individual task merges; it validates at the story boundary. The flagging path (chosen in `construction/infrastructure.md`) determines how tasks merge safely without per-task QA. +**Task "done" and story "done" are different events.** Tasks close on engineering DoD (tests, review, build, behind flag if applicable). Stories close on QA validation against story AC. QA does **not** gate individual task merges; it validates at the story boundary. The flagging path (chosen in `design/infrastructure-design.md`) determines how tasks merge safely without per-task QA. Execution loop: @@ -125,7 +128,7 @@ The breakdown is complete when `state.md` shows all stories validated (and all f See the README's QA testing process section for the full model. Skill-level summary: -**Two paths**, decided in `construction/infrastructure.md`: +**Two paths**, decided in `design/infrastructure-design.md`: - **Feature-flagged (default).** Tasks merge to main behind the flag. Story-level QA happens when all tasks for a story land + flag is enabled in staging. Flag flips to prod after QA passes. - **Non-flagged.** Three sub-cases: @@ -216,7 +219,7 @@ These come from the AI-DLC pattern and are not negotiable: - **`Skill(coordinating-cross-team-breakdown)`** — the design-phase cross-team signoff workflow. Drives the Cross-team engagement section of `design.md`. Treat blocking signoffs as gates on Design Approval. - **`Skill(navigating-the-initiative-funnel)`** — load-bearing when the breakdown sits under a BW Initiative. Pulls the shepherd, sibling teams' epics, architecture plan, and PoC PRs that feed Specification, Architecture, and Cross-team engagement. - **`Skill(architecting-solutions)` (in `bitwarden-tech-lead`)** — the architectural-judgment lens to apply when drafting Architecture and reviewing functional-design. -- **`Skill(bitwarden-security-context)` (in `bitwarden-security-engineer`)** — route through this when `non-functional.md`'s Security section flags cryptographic work or new security definitions. +- **`Skill(bitwarden-security-context)` (in `bitwarden-security-engineer`)** — route through this when `design/non-functional-design.md`'s Security section flags cryptographic work or new security definitions. ## Common mistakes From 22f3d7384a8e54af0cea4a8bf05821fb3e5c1107 Mon Sep 17 00:00:00 2001 From: Todd Martin Date: Mon, 1 Jun 2026 12:53:43 -0400 Subject: [PATCH 05/11] Updates. --- .../skills/running-ai-dlc-breakdown/SKILL.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md index 54b4fbe..b99eaec 100644 --- a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md +++ b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md @@ -113,14 +113,16 @@ Not a folder. Once the Tasks gate is signed, execution begins. **Task "done" and story "done" are different events.** Tasks close on engineering DoD (tests, review, build, behind flag if applicable). Stories close on QA validation against story AC. QA does **not** gate individual task merges; it validates at the story boundary. The flagging path (chosen in `design/infrastructure-design.md`) determines how tasks merge safely without per-task QA. -Execution loop: - -1. **Create Jira tickets** from each approved task — typically as sub-tasks of the parent stories. Cross-link the breakdown. -2. **Engineer + agent work `codegen-plan.md` file-by-file.** Check off each file as it lands. -3. **Task done — engineering DoD met:** tests pass, code reviewed, build green, behind flag if applicable. Merge. Close the Jira sub-task. Update `state.md`'s Tasks complete counter. -4. **Story enters QA** when all tasks serving it have merged (and the flag is enabled in staging, if flagged). Engineer/pair notifies QA; add the story to `state.md`'s Stories awaiting QA section. -5. **QA validates** against story AC (not task DoD). Story closes on pass. Update `state.md`'s Stories validated counter. -6. **Flag flip (flagged path only):** once the story is validated in staging, coordinate the production flag flip per the team's release process. Update `state.md`'s Stories awaiting prod flag flip section. +Execution loop (each step shows the owner): + +1. **Create Jira tickets** — **engineer** (or agent via Atlassian MCP, with engineer review) creates a Jira sub-task per engineering task, typically linked to the parent stories. Cross-link the breakdown. +2. **Execute the codegen plan** — **engineer + agent** work `codegen-plan.md` file-by-file. Agent generates each file; engineer reviews the diff and commits. Check off each file as it lands. +3. **Close tasks as they merge** — **engineer** transitions the Jira sub-task to Done when engineering DoD is met (tests, review, build, behind flag if applicable). +4. **Notify QA when a story is ready** — when all tasks serving a story have merged (and the flag is enabled in staging if flagged), **engineer/pair** notifies the QA Engineer. +5. **QA validates** — **QA Engineer** validates the story against its AC (not task DoD). Story closes on pass. +6. **Flag flip (flagged path only)** — once the story is validated in staging, **engineer** coordinates the production flag flip per the team's release process. + +**Who updates `state.md`:** the engineer owns it. During an AI-DLC session, the agent updates `state.md` as a side-effect of its work (codegen step complete, gate signed, clarification surfaced) — the agent can only update what it observes in-session. For asynchronous events (a PR merging hours later, QA validating a story a day later, a flag flip), the engineer updates `state.md` directly or asks the agent in the next session to record what's changed. Stale state means anyone picking up cold reconstructs the picture from scratch. The breakdown is complete when `state.md` shows all stories validated (and all flags flipped, if applicable). From e889510342931a4191880a52be1650126fd6bae3 Mon Sep 17 00:00:00 2001 From: Todd Martin Date: Mon, 1 Jun 2026 14:14:07 -0400 Subject: [PATCH 06/11] Changes. --- .../skills/running-ai-dlc-breakdown/SKILL.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md index b99eaec..167a856 100644 --- a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md +++ b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md @@ -92,17 +92,17 @@ Two artifacts in the sibling `construction/` folder. Each has a completion check - **Definition of Done** — engineering-shaped (tests pass, code reviewed, build green), **not** user-AC. Story AC stays on the Jira story; engineering tasks don't duplicate it. - **Test scenarios** — edge cases for QA to cross-check (story AC is the user-facing contract) - **Blocked on** — prerequisites among the other tasks - - **Jira ID** — typically created as a sub-task of the parent story + - **Jira ID** — created as a Jira **Task** under the parent epic, linked to the story or stories it serves via "implements" or similar (not as a sub-task; engineering tasks need their own QA-capable status lifecycle) Include a **Coverage check** subsection mapping every user story from the overview to at least one task. If a story is uncovered, the decomposition is incomplete. Slicing principle: vertical implementation slices, not horizontal layer batches. - Note the exception path: if user stories don't exist (the blocker from bootstrap wasn't resolved), engineering tasks may carry story-shaped AC and become Jira stories rather than sub-tasks. Use sparingly; the right fix is upstream. + Note the exception path: if user stories don't exist (the blocker from bootstrap wasn't resolved), engineering tasks may carry story-shaped AC and be created as Jira Stories instead of Tasks-linked-to-stories. Use sparingly; the right fix is upstream. Before signing the Tasks Approval Gate, two engagements happen — these are gating, not optional: -- **Team refinement session.** The driving engineer/pair walks the whole team (engineers, tech lead, QA, PM as appropriate) through the construction artifacts and the proposed task slicing. This is where the broader team gets read-in, catches what the pair missed, and aligns with QA. Capture session date, attendees, and changes in the Team refinement section of `tasks.md`. +- **Team refinement session.** The driving engineer/pair walks the whole team (engineers, tech lead, QA, PM as appropriate) through the construction artifacts and the proposed task slicing. Two things happen: (1) the broader team gets read-in, catches what the pair missed, and aligns with QA on test scenarios; (2) each task's ticket-ready content gets fleshed out — the implementation pointers, one-paragraph context, sharpened scenarios, affected file list. The task entries in `tasks.md` carry structural fields out of construction; refinement is where the team adds the rest so each task is ready to become a Jira Task. Capture session date, attendees, and changes in the Team refinement section of `tasks.md`. - **QA review.** The responsible QA Engineer reviews tasks and test scenarios (typically as part of refinement). Capture separately so QA ownership is unambiguous. After the Tasks Approval Gate is signed, update `state.md` with the transition and proceed to execution. @@ -115,9 +115,9 @@ Not a folder. Once the Tasks gate is signed, execution begins. Execution loop (each step shows the owner): -1. **Create Jira tickets** — **engineer** (or agent via Atlassian MCP, with engineer review) creates a Jira sub-task per engineering task, typically linked to the parent stories. Cross-link the breakdown. +1. **Create Jira Tasks** — **engineer** (or agent via Atlassian MCP, with engineer review) creates a Jira **Task** per engineering task (siblings of the parent stories under the same epic), linking each Task to the story or stories it serves via "implements" or similar. Cross-link the breakdown. 2. **Execute the codegen plan** — **engineer + agent** work `codegen-plan.md` file-by-file. Agent generates each file; engineer reviews the diff and commits. Check off each file as it lands. -3. **Close tasks as they merge** — **engineer** transitions the Jira sub-task to Done when engineering DoD is met (tests, review, build, behind flag if applicable). +3. **Close tasks as they merge** — **engineer** transitions the Jira Task to Done when engineering DoD is met (tests, review, build, behind flag if applicable). 4. **Notify QA when a story is ready** — when all tasks serving a story have merged (and the flag is enabled in staging if flagged), **engineer/pair** notifies the QA Engineer. 5. **QA validates** — **QA Engineer** validates the story against its AC (not task DoD). Story closes on pass. 6. **Flag flip (flagged path only)** — once the story is validated in staging, **engineer** coordinates the production flag flip per the team's release process. From 2f4bc03eb56ee4eee128fc907533c0e6c6261ed7 Mon Sep 17 00:00:00 2001 From: Todd Martin Date: Mon, 1 Jun 2026 14:44:04 -0400 Subject: [PATCH 07/11] Skill changes. --- .../skills/running-ai-dlc-breakdown/SKILL.md | 44 ++++++++----------- 1 file changed, 18 insertions(+), 26 deletions(-) diff --git a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md index 167a856..bddd69d 100644 --- a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md +++ b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md @@ -19,29 +19,24 @@ Cross-team coordination _during the design phase_ (interface review, signoff fro ``` breakdowns// - PM-12345-feature-name.md ← design overview (cold-start entry, Phase 1) + PM-12345-feature-name.md ← the full design (cold-start entry, Phase 1) PM-12345-feature-name/ ← sibling folder, created when design begins state.md ← breakdown-wide tracker (all phases) - design/ - functional-design.md ← per-layer implementation design - non-functional-design.md ← security, observability - infrastructure-design.md ← deployment, environments, flagging construction/ codegen-plan.md ← file-level execution plan tasks.md ← QA-testable Jira slices (final construction gate) clarifications/ ← Q→D→A files (created on demand) q-.md templates/ - tech-breakdown.md ← design overview template + tech-breakdown.md ← single-file design template state.md - design/ ← detailed design artifacts construction/ ← codegen plan + tasks clarifications/question.md ``` Templates are canonical. Copy from `templates/`, never edit in place. -Three phases. Design is the overview `.md` plus detailed sub-artifacts in `design/` (each with its own approval sub-gate, rolled up by the Design Approval Gate at the bottom of the overview). Construction is thin — just the codegen plan and task decomposition. Execution is the loop of running the codegen plan, transitioning Jira tickets, and updating `state.md` — no folder of its own. +Three phases. Design is a single self-contained `.md` containing spec, architecture, functional design (per layer), non-functional design, infrastructure design, cross-team coordination, and agent context — gated by one Design Approval Gate at its bottom. Construction is thin — just the codegen plan and task decomposition, gated by one Tasks Approval Gate. Execution is the loop of running the codegen plan, transitioning Jira tickets, and updating `state.md` — no folder of its own. ## Bootstrap @@ -52,7 +47,7 @@ Before drafting anything, orient on the work: 3. **Check for an originating BW Initiative.** If the work sits under one, **run `Skill(navigating-the-initiative-funnel)` first** to pull the shepherd, sibling teams, architecture plan, and PoC PRs. The initiative context feeds the Specification and Cross-team engagement sections of `design.md`. 4. **Identify the owning team** and confirm the breakdown will live in `breakdowns//`. 5. **Copy `templates/tech-breakdown.md`** into the team's folder, renamed to `-.md` (e.g., `PM-23289-sync-push-notifications.md`). -6. **Create the sibling folder** with the same name and copy `templates/design/*.md`, `templates/construction/*.md`, and `templates/state.md` into it. +6. **Create the sibling folder** with the same name and copy `templates/construction/*.md` and `templates/state.md` into it. 7. **Delete the template checklist** at the top of the overview file. ## The three phases @@ -61,29 +56,26 @@ The skill runs each phase as a gated loop: draft → clarify (Q→D→A as neede ### Phase 1 — Design -Two parts: the overview (single file: `breakdowns//-.md`) and the detailed design artifacts (in the sibling `design/` folder). +Single file: `breakdowns//-.md`. Self-contained — spec, architecture, all design detail, cross-team coordination, and agent context in one cold-start-readable document. -**Overview drafting order:** +**Drafting order (top to bottom in the file):** 1. **Specification.** Description, User Value, **User Stories** (list each one with Jira ID, "As a … I want …" line, and AC summary — these are inputs, not authored here), Functional Requirements (each mapped to the story IDs it implements), Alternatives, Success Criteria. Don't paste Product spec; link it and frame in the team's voice. -2. **Architecture (high-level).** Current State (what exists today in code, with paths), Proposed architecture (prefer Mermaid diagrams over images), Out of Scope, Known Limitations, Prototypes. The architecture must cover every user story listed in the Specification. Per-layer detail lives in `design/functional-design.md`, not here. -3. **Cross-team engagement.** Walk the three subsections — consuming other teams' APIs, changes required in other teams' code, sequencing & ordering. Populate the signoff table. **Hand off to `Skill(coordinating-cross-team-breakdown)`** when chasing signoffs. -4. **Agent Context.** Durable reference content for future agent invocations: repos affected (with `CLAUDE.md` pointers), existing patterns to follow, external references, things an agent should not assume. Stable design-phase context only — current-position state (which phase, who's driving, last gate) lives in `state.md`, not here. Populate explicitly, not as an afterthought. -5. **Clarifications Log.** Run an AI clarify pass against the draft _before_ requesting cross-team review. AI-raised questions go in `clarifications/q-.md` files via the Q→D→A pattern; resolved answers fold back into Spec or Architecture and the log entry becomes a short stub. +2. **Clarifications Log.** Run an AI clarify pass against the draft _before_ requesting cross-team review. AI-raised questions go in `clarifications/q-.md` files via the Q→D→A pattern; resolved answers fold back into the relevant section and the log entry becomes a short stub. +3. **Architecture (high-level).** Current State (what exists today in code, with paths), Proposed architecture (prefer Mermaid diagrams over images), Out of Scope, Known Limitations, Prototypes. The architecture must cover every user story listed in the Specification. +4. **Functional Design.** Per-layer changes: data model, server logic, API surface, SDK, client services, UI, background jobs, testing strategy. Fill only the layers this change touches; remove the rest. Each subsection's checklist evaluated explicitly (mark N/A when skipped, don't leave blank). +5. **Non-Functional Design.** Security, cryptography, observability, operations. Can be iterated in parallel with Infrastructure Design. +6. **Infrastructure Design.** Deployment, environments, feature flagging strategy and QA path. Can be iterated in parallel with Non-Functional Design. +7. **Cross-team engagement.** Walk the three subsections — consuming other teams' APIs, changes required in other teams' code, sequencing & ordering. Populate the signoff table. **Hand off to `Skill(coordinating-cross-team-breakdown)`** when chasing signoffs. +8. **Agent Context.** Durable reference content for future agent invocations: repos affected (with `CLAUDE.md` pointers), existing patterns to follow, external references, things an agent should not assume. Stable design-phase context only — current-position state (which phase, who's driving, last gate) lives in `state.md`, not here. Populate explicitly, not as an afterthought. -**Detailed design artifacts in `design/`.** Each has a completion checklist but no per-artifact gate; they roll up to the overview's Design Approval Gate. - -1. **`functional-design.md`** — per-layer changes: data model, server logic, API surface, SDK, client services, UI, background jobs, testing strategy. Fill only the layers this change touches; remove the rest. Each subsection's checklist evaluated explicitly (mark N/A when skipped, don't leave blank). -2. **`non-functional-design.md`** — security, cryptography, observability, operations. Drafted in parallel with step 3 once functional-design is complete. -3. **`infrastructure-design.md`** — deployment, environments, feature flagging strategy. Drafted in parallel with step 2 once functional-design is complete. - -**Design Approval Gate.** Sign the gate at the bottom of the overview when all three design artifacts have their completion checklists satisfied AND cross-team signoffs are complete. Status advances PROPOSED → ACCEPTED. Update `state.md` with the transition. +**Design Approval Gate.** Sign the gate at the bottom of the design when every section above is complete AND cross-team signoffs are captured. Status advances PROPOSED → ACCEPTED. Update `state.md` with the transition. ### Phase 2 — Construction Two artifacts in the sibling `construction/` folder. Each has a completion checklist but no per-artifact gate; both roll up to the single **Tasks Approval Gate**. -1. **`codegen-plan.md`** — numbered, checkbox-tracked list of every file to create or modify, in execution order. Each file traces back to a design artifact (e.g., "Source: `../design/functional-design.md` § Data model changes"). Sequencing constraints called out explicitly (interfaces before consumers, types before usages). +1. **`codegen-plan.md`** — numbered, checkbox-tracked list of every file to create or modify, in execution order. Each file traces back to a section in the design (e.g., "Source: `../.md` § Functional Design § Data model changes"). Sequencing constraints called out explicitly (interfaces before consumers, types before usages). 2. **`tasks.md`** — the artifact that carries the Tasks Approval Gate at its bottom. Carve the codegen plan into **engineering tasks**, each a vertical slice of implementation work that delivers (part of) one or more user stories. Typical grain: 3-7 tasks per breakdown, ~1-3 days each. Engineering tasks are **not user stories**. The relationship is one-to-many: one story → multiple engineering tasks. Each task has: @@ -111,7 +103,7 @@ After the Tasks Approval Gate is signed, update `state.md` with the transition a Not a folder. Once the Tasks gate is signed, execution begins. -**Task "done" and story "done" are different events.** Tasks close on engineering DoD (tests, review, build, behind flag if applicable). Stories close on QA validation against story AC. QA does **not** gate individual task merges; it validates at the story boundary. The flagging path (chosen in `design/infrastructure-design.md`) determines how tasks merge safely without per-task QA. +**Task "done" and story "done" are different events.** Tasks close on engineering DoD (tests, review, build, behind flag if applicable). Stories close on QA validation against story AC. QA does **not** gate individual task merges; it validates at the story boundary. The flagging path (chosen in the design's Infrastructure Design section) determines how tasks merge safely without per-task QA. Execution loop (each step shows the owner): @@ -130,7 +122,7 @@ The breakdown is complete when `state.md` shows all stories validated (and all f See the README's QA testing process section for the full model. Skill-level summary: -**Two paths**, decided in `design/infrastructure-design.md`: +**Two paths**, decided in the design's Infrastructure Design section: - **Feature-flagged (default).** Tasks merge to main behind the flag. Story-level QA happens when all tasks for a story land + flag is enabled in staging. Flag flips to prod after QA passes. - **Non-flagged.** Three sub-cases: @@ -221,7 +213,7 @@ These come from the AI-DLC pattern and are not negotiable: - **`Skill(coordinating-cross-team-breakdown)`** — the design-phase cross-team signoff workflow. Drives the Cross-team engagement section of `design.md`. Treat blocking signoffs as gates on Design Approval. - **`Skill(navigating-the-initiative-funnel)`** — load-bearing when the breakdown sits under a BW Initiative. Pulls the shepherd, sibling teams' epics, architecture plan, and PoC PRs that feed Specification, Architecture, and Cross-team engagement. - **`Skill(architecting-solutions)` (in `bitwarden-tech-lead`)** — the architectural-judgment lens to apply when drafting Architecture and reviewing functional-design. -- **`Skill(bitwarden-security-context)` (in `bitwarden-security-engineer`)** — route through this when `design/non-functional-design.md`'s Security section flags cryptographic work or new security definitions. +- **`Skill(bitwarden-security-context)` (in `bitwarden-security-engineer`)** — route through this when the design's Non-Functional Design § Security section flags cryptographic work or new security definitions. ## Common mistakes From e73c7cd96e08c288826286b9813faff47b460ddf Mon Sep 17 00:00:00 2001 From: Todd Martin Date: Mon, 1 Jun 2026 15:59:08 -0400 Subject: [PATCH 08/11] More refactoring. --- .../skills/running-ai-dlc-breakdown/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md index bddd69d..bc00075 100644 --- a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md +++ b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md @@ -11,7 +11,7 @@ This skill assumes: - The breakdown lives as markdown files in the `tech-breakdowns` repo. - Execution is single-team, single-engineer/pair. A breakdown is **never** a cross-team carve-up; if the design surfaces work another team must own, that team owns a separate breakdown. - Implementation is driven by sequential codegen, file-by-file, with the agent executing and the engineer reviewing each diff. -- Jira tracks delivery via QA-testable slices, not via file-grained codegen steps. +- Jira tracks delivery via engineering tasks (PR-review-sized implementation units), not via file-grained codegen steps. QA validates at the story boundary, not the task boundary. Cross-team coordination _during the design phase_ (interface review, signoff from peer teams) happens through the Cross-team engagement section of `design.md` and the companion `Skill(coordinating-cross-team-breakdown)`. What this skill changes is the execution model, not the coordination model. @@ -24,7 +24,7 @@ breakdowns// state.md ← breakdown-wide tracker (all phases) construction/ codegen-plan.md ← file-level execution plan - tasks.md ← QA-testable Jira slices (final construction gate) + tasks.md ← engineering tasks for Jira tracking (final construction gate) clarifications/ ← Q→D→A files (created on demand) q-.md templates/ @@ -220,7 +220,7 @@ These come from the AI-DLC pattern and are not negotiable: - **Drafting without the Jira ticket and initiative context.** A breakdown drafted in a vacuum diverges from the work that triggered it. Always start from the ticket and (when applicable) the initiative. - **Treating `state.md` as optional.** Stale state means anyone picking up cold reads codegen-plan, tasks, and Jira separately and reconstructs the picture. The whole point of `state.md` is that they don't have to. - **Skipping the Q→D→A pattern for "small" questions.** Conversational clarifications get lost. Question files survive the next context reset; chat does not. -- **Slicing tasks horizontally instead of vertically.** "All data model changes" is not a QA-testable slice. Each task must deliver something QA can validate end-to-end. +- **Slicing tasks horizontally instead of by logical implementation unit.** "All data model changes" produces a PR that mixes unrelated changes and isn't reviewable as one coherent unit. Each task should be sized for one code review pass and one merge event. - **Creating Jira tickets before QA reviews `tasks.md`.** QA's job gets harder when ticket scope/scenarios are baked in without their input. Walk them through first. - **Confusing engineering tasks with user stories.** Stories describe user-observable outcomes with Given/When/Then AC, authored by Product, living in Jira. Engineering tasks describe implementation work and reference stories. Duplicating story AC onto engineering tasks creates two sources of truth and confuses QA. - **Starting design without user stories.** Stories are inputs to the breakdown. Bootstrap should pull them; missing stories is a blocker, not a section to fill in. Engineering doesn't author stories on Product's behalf. From e1b19b2104c82f0b8bb8f9f01a047f8d96a9afa7 Mon Sep 17 00:00:00 2001 From: Todd Martin Date: Mon, 1 Jun 2026 22:15:12 -0400 Subject: [PATCH 09/11] Updates to state. --- .../skills/running-ai-dlc-breakdown/SKILL.md | 33 ++++++++++--------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md index bc00075..995695b 100644 --- a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md +++ b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md @@ -1,6 +1,6 @@ --- name: running-ai-dlc-breakdown -description: Drive a Bitwarden tech breakdown end-to-end through the three-phase AI-DLC model (design → construction → execution) in the bitwarden/tech-breakdowns repo. Use when starting, drafting, or executing any tech breakdown — single engineer or pair driving with a Claude agent, per-artifact approval gates, Q→D→A clarifications, codegen-plan-to-Jira slicing with team refinement, and `state.md` as the breakdown-wide tracker. +description: Drive a Bitwarden tech breakdown end-to-end through the three-phase AI-DLC model (design → construction → execution) in the bitwarden/tech-breakdowns repo. Use when starting, drafting, or executing any tech breakdown — single engineer or pair driving with a Claude agent, two approval gates (Design and Tasks), Q→D→A clarifications, codegen-plan-to-Jira slicing with team refinement, and `state.md` for breakdown-level state that Jira can't capture (phase progress, codegen position, open clarifications). allowed-tools: Skill, Read, Write, Edit, Bash, Glob, Grep, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_comments, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_issues, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_confluence_page, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_confluence --- @@ -21,7 +21,7 @@ Cross-team coordination _during the design phase_ (interface review, signoff fro breakdowns// PM-12345-feature-name.md ← the full design (cold-start entry, Phase 1) PM-12345-feature-name/ ← sibling folder, created when design begins - state.md ← breakdown-wide tracker (all phases) + state.md ← breakdown-level state (phase progress, codegen position, open clarifications); Jira is the source of truth for ticket-level state construction/ codegen-plan.md ← file-level execution plan tasks.md ← engineering tasks for Jira tracking (final construction gate) @@ -116,7 +116,7 @@ Execution loop (each step shows the owner): **Who updates `state.md`:** the engineer owns it. During an AI-DLC session, the agent updates `state.md` as a side-effect of its work (codegen step complete, gate signed, clarification surfaced) — the agent can only update what it observes in-session. For asynchronous events (a PR merging hours later, QA validating a story a day later, a flag flip), the engineer updates `state.md` directly or asks the agent in the next session to record what's changed. Stale state means anyone picking up cold reconstructs the picture from scratch. -The breakdown is complete when `state.md` shows all stories validated (and all flags flipped, if applicable). +The breakdown is complete when the Jira board shows all stories closed (and all flags flipped, if applicable). `state.md`'s Phase progress section reflects this via the Execution checkboxes. ### QA testing process @@ -172,26 +172,28 @@ Answer-format guidance for the user (encoded in the template): Questions from PM, AppSec, peer teams, or anyone else reviewing the design come in free-form and don't fit the multi-choice shape. **Log them directly in the Clarifications Log table** in `design.md` with status Open, the source (person), an owner, and a target resolution date. Update to Resolved with a one-line answer and link to the section when the question is answered. Do not create a q-file for human-raised questions — the Q→D→A mechanism is specifically the agent's working tool. -## `state.md` — the bridge +## `state.md` — breakdown-level state -**This file is non-optional.** It is what an agent picking up cold reads first, and what a human (manager, peer team, QA) reads to see status without opening codegen-plan, tasks, and Jira separately. Keep it current. +**`state.md` captures what Jira can't show.** Jira is the source of truth for ticket-level state (task counts, story status, assignees, who's in QA right now); `state.md` captures breakdown-level state (which approval gates have been signed, file-by-file codegen position, open Q→D→A clarifications). An agent picking up cold reads the design + `state.md` + the Jira board. Don't duplicate ticket counts in `state.md`. -`state.md` tracks three axes: +`state.md` tracks four things: -1. **Phase progress** — checkboxes per artifact (design → construction artifacts → delivery artifacts) showing what's approved and what's pending. -2. **Execution status** — codegen plan progress (`N of M files complete`), tasks complete (`N of M tickets closed`), active codegen step (which file the agent is touching now, and which task it's part of), tickets in QA, active engineer/pair. -3. **Last gate** — most recent approval gate, date, outcome (Approved and Continue / Request Changes), notes on anything that changed since approval. +1. **Jira pointers** — epic ID and board/filter link, so anyone navigating from `state.md` can drill into ticket detail. +2. **Phase progress** — checkboxes for breakdown-level milestones that Jira doesn't represent: design sections complete, cross-team signoffs done, Design Approval Gate signed, Tasks Approval Gate signed. +3. **Codegen execution** — flagging path, codegen plan progress (`N of M files complete`), active codegen step (which file the agent is touching now, which Jira Task it's part of). Sub-task granularity that Jira doesn't carry. +4. **Open clarifications** — pending `clarifications/q-*.md` files. Q-files are repo artifacts, not Jira items. +5. **Last gate** — most recent approval gate, date, outcome (Approved / Request Changes), notes on anything that changed since approval. -**Update `state.md` on every gate transition and every meaningful execution event:** +**Update `state.md` on:** - Approval gate signed → update Phase progress + Last gate -- Codegen step complete → bump the codegen progress counter -- Task complete → bump the tasks-complete counter and move the ticket to "In QA" -- QA passes → close the ticket and remove from "In QA" +- Codegen step complete → bump the codegen progress counter; update Active codegen step - New clarification file created → add to Open clarifications - Clarification resolved → remove from Open clarifications -The skill should never advance phases without checking `state.md` is current. If state and reality diverge, fix state first. +**Don't update `state.md` for ticket events** — those live in Jira. PR merges, Jira Task transitions to Done, QA passing a story, flag flips: these are visible on the Jira board, which `state.md` links to. + +The skill should never advance phases without checking `state.md` is current for the things it owns. If state and reality diverge on the items above, fix state first. ## Hard rules (AI-DLC inheritance) @@ -218,7 +220,8 @@ These come from the AI-DLC pattern and are not negotiable: ## Common mistakes - **Drafting without the Jira ticket and initiative context.** A breakdown drafted in a vacuum diverges from the work that triggered it. Always start from the ticket and (when applicable) the initiative. -- **Treating `state.md` as optional.** Stale state means anyone picking up cold reads codegen-plan, tasks, and Jira separately and reconstructs the picture. The whole point of `state.md` is that they don't have to. +- **Treating `state.md` as optional.** Stale state means anyone picking up cold has to reconstruct phase progress and codegen position by reading the design, scanning the codegen plan, and clicking through clarifications. `state.md` exists so they don't have to. +- **Duplicating Jira state in `state.md`.** Task counts, story statuses, QA queue, assignees — these all live in Jira. Adding them to `state.md` creates drift between two trackers. `state.md` carries only what Jira can't (phase gates, codegen position, open Q→D→A clarifications). - **Skipping the Q→D→A pattern for "small" questions.** Conversational clarifications get lost. Question files survive the next context reset; chat does not. - **Slicing tasks horizontally instead of by logical implementation unit.** "All data model changes" produces a PR that mixes unrelated changes and isn't reviewable as one coherent unit. Each task should be sized for one code review pass and one merge event. - **Creating Jira tickets before QA reviews `tasks.md`.** QA's job gets harder when ticket scope/scenarios are baked in without their input. Walk them through first. From 4489a121298951a4a6b2d692836cbb313595d6e6 Mon Sep 17 00:00:00 2001 From: Todd Martin Date: Tue, 2 Jun 2026 10:01:11 -0400 Subject: [PATCH 10/11] Added handoff language --- .../skills/running-ai-dlc-breakdown/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md index 995695b..a3456d2 100644 --- a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md +++ b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md @@ -9,7 +9,7 @@ This skill drives a Bitwarden tech breakdown from a fresh Jira ticket through to This skill assumes: - The breakdown lives as markdown files in the `tech-breakdowns` repo. -- Execution is single-team, single-engineer/pair. A breakdown is **never** a cross-team carve-up; if the design surfaces work another team must own, that team owns a separate breakdown. +- Execution is single-team. By default, one engineer or pair drives the breakdown end-to-end; teams may opt to hand off between design and execution at the Tasks Approval Gate (see the README's [Handoff option](https://github.com/bitwarden/tech-breakdowns#handoff-option) section for when and how). A breakdown is **never** a cross-team carve-up; if the design surfaces work another team must own, that team owns a separate breakdown. - Implementation is driven by sequential codegen, file-by-file, with the agent executing and the engineer reviewing each diff. - Jira tracks delivery via engineering tasks (PR-review-sized implementation units), not via file-grained codegen steps. QA validates at the story boundary, not the task boundary. @@ -114,7 +114,7 @@ Execution loop (each step shows the owner): 5. **QA validates** — **QA Engineer** validates the story against its AC (not task DoD). Story closes on pass. 6. **Flag flip (flagged path only)** — once the story is validated in staging, **engineer** coordinates the production flag flip per the team's release process. -**Who updates `state.md`:** the engineer owns it. During an AI-DLC session, the agent updates `state.md` as a side-effect of its work (codegen step complete, gate signed, clarification surfaced) — the agent can only update what it observes in-session. For asynchronous events (a PR merging hours later, QA validating a story a day later, a flag flip), the engineer updates `state.md` directly or asks the agent in the next session to record what's changed. Stale state means anyone picking up cold reconstructs the picture from scratch. +**Who updates `state.md`:** the engineer owns it for the things `state.md` tracks (phase progress, codegen position, open clarifications, last gate). During an AI-DLC session, the agent updates `state.md` as a side-effect of its work (codegen step complete, gate signed, clarification surfaced). For asynchronous breakdown-level events (a gate signed outside the session, a clarification answered later), the engineer updates `state.md` directly or asks the agent in the next session. **Ticket-level events (PR merges, Jira Task transitions, QA validations, flag flips) update Jira, not `state.md`** — Jira is the source of truth for those. The breakdown is complete when the Jira board shows all stories closed (and all flags flipped, if applicable). `state.md`'s Phase progress section reflects this via the Execution checkboxes. From 47805cdd8db22aa5ab9b1bb47c1733910bc4fe18 Mon Sep 17 00:00:00 2001 From: Todd Martin Date: Thu, 4 Jun 2026 15:08:20 -0400 Subject: [PATCH 11/11] Skill adjustments. --- .../skills/running-ai-dlc-breakdown/SKILL.md | 45 +++++++++---------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md index a3456d2..54d0bb0 100644 --- a/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md +++ b/plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md @@ -1,6 +1,6 @@ --- name: running-ai-dlc-breakdown -description: Drive a Bitwarden tech breakdown end-to-end through the three-phase AI-DLC model (design → construction → execution) in the bitwarden/tech-breakdowns repo. Use when starting, drafting, or executing any tech breakdown — single engineer or pair driving with a Claude agent, two approval gates (Design and Tasks), Q→D→A clarifications, codegen-plan-to-Jira slicing with team refinement, and `state.md` for breakdown-level state that Jira can't capture (phase progress, codegen position, open clarifications). +description: Drive a Bitwarden tech breakdown end-to-end through the three-phase AI-DLC model (design → construction → execution) in the bitwarden/tech-breakdowns repo. Use when starting, drafting, or executing any tech breakdown — single engineer or pair driving with a Claude agent, two approval gates (Design and Tasks), Q→D→A clarifications, engineering tasks that carry their affected files inline (no separate codegen plan), team refinement, and `state.md` for breakdown-level state that Jira can't capture (phase progress, active task and file, open clarifications). allowed-tools: Skill, Read, Write, Edit, Bash, Glob, Grep, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_comments, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_issues, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_confluence_page, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_confluence --- @@ -23,20 +23,19 @@ breakdowns// PM-12345-feature-name/ ← sibling folder, created when design begins state.md ← breakdown-level state (phase progress, codegen position, open clarifications); Jira is the source of truth for ticket-level state construction/ - codegen-plan.md ← file-level execution plan - tasks.md ← engineering tasks for Jira tracking (final construction gate) + tasks.md ← engineering tasks (each carries its affected files); the construction artifact and final construction gate clarifications/ ← Q→D→A files (created on demand) q-.md templates/ tech-breakdown.md ← single-file design template state.md - construction/ ← codegen plan + tasks + construction/ ← the single tasks artifact clarifications/question.md ``` Templates are canonical. Copy from `templates/`, never edit in place. -Three phases. Design is a single self-contained `.md` containing spec, architecture, functional design (per layer), non-functional design, infrastructure design, cross-team coordination, and agent context — gated by one Design Approval Gate at its bottom. Construction is thin — just the codegen plan and task decomposition, gated by one Tasks Approval Gate. Execution is the loop of running the codegen plan, transitioning Jira tickets, and updating `state.md` — no folder of its own. +Three phases. Design is a single self-contained `.md` containing spec, architecture, functional design (per layer), non-functional design, infrastructure design, cross-team coordination, and agent context — gated by one Design Approval Gate at its bottom. Construction is thin — just `tasks.md`, where each engineering task carries its affected files inline (no separate codegen plan), gated by one Tasks Approval Gate. Execution is the loop of working each task, transitioning Jira Tasks, and updating `state.md` — no folder of its own. ## Bootstrap @@ -75,22 +74,22 @@ Single file: `breakdowns//-.md`. Self-contained — Two artifacts in the sibling `construction/` folder. Each has a completion checklist but no per-artifact gate; both roll up to the single **Tasks Approval Gate**. -1. **`codegen-plan.md`** — numbered, checkbox-tracked list of every file to create or modify, in execution order. Each file traces back to a section in the design (e.g., "Source: `../.md` § Functional Design § Data model changes"). Sequencing constraints called out explicitly (interfaces before consumers, types before usages). -2. **`tasks.md`** — the artifact that carries the Tasks Approval Gate at its bottom. Carve the codegen plan into **engineering tasks**, each a vertical slice of implementation work that delivers (part of) one or more user stories. Typical grain: 3-7 tasks per breakdown, ~1-3 days each. +**`tasks.md`** is the single construction artifact, carrying the Tasks Approval Gate at its bottom. Decompose the design into **engineering tasks**, each a coherent implementation slice that delivers (part of) one or more user stories. Typical grain: 3-7 tasks per breakdown, ~1-3 days each. - Engineering tasks are **not user stories**. The relationship is one-to-many: one story → multiple engineering tasks. Each task has: - - **Stories served** — Jira IDs from the overview's User Stories section - - **Scope** — codegen-plan steps it implements - - **Definition of Done** — engineering-shaped (tests pass, code reviewed, build green), **not** user-AC. Story AC stays on the Jira story; engineering tasks don't duplicate it. - - **Test scenarios** — edge cases for QA to cross-check (story AC is the user-facing contract) - - **Blocked on** — prerequisites among the other tasks - - **Jira ID** — created as a Jira **Task** under the parent epic, linked to the story or stories it serves via "implements" or similar (not as a sub-task; engineering tasks need their own QA-capable status lifecycle) +Engineering tasks are **not user stories**. The relationship is one-to-many: one story → multiple engineering tasks. Each task has: - Include a **Coverage check** subsection mapping every user story from the overview to at least one task. If a story is uncovered, the decomposition is incomplete. +- **Stories served** — Jira IDs from the design's User Stories section +- **Files affected** — explicit file list with `(N)` for new / `(M)` for modified. This is the agent's execution scope for the task; no separate codegen plan. +- **Definition of Done** — engineering-shaped (tests pass, code reviewed, build green), **not** user-AC. Story AC stays on the Jira story; engineering tasks don't duplicate it. +- **Test scenarios** — edge cases for QA to cross-check (story AC is the user-facing contract) +- **Blocked on** — prerequisites among the other tasks +- **Jira ID** — created as a Jira **Task** under the parent epic, linked to the story or stories it serves via "implements" or similar (not as a sub-task; engineering tasks need their own QA-capable status lifecycle) - Slicing principle: vertical implementation slices, not horizontal layer batches. + Include a **Coverage check** subsection mapping every user story from the overview to at least one task. If a story is uncovered, the decomposition is incomplete. - Note the exception path: if user stories don't exist (the blocker from bootstrap wasn't resolved), engineering tasks may carry story-shaped AC and be created as Jira Stories instead of Tasks-linked-to-stories. Use sparingly; the right fix is upstream. + Slicing principle: vertical implementation slices, not horizontal layer batches. + + Note the exception path: if user stories don't exist (the blocker from bootstrap wasn't resolved), engineering tasks may carry story-shaped AC and be created as Jira Stories instead of Tasks-linked-to-stories. Use sparingly; the right fix is upstream. Before signing the Tasks Approval Gate, two engagements happen — these are gating, not optional: @@ -108,7 +107,7 @@ Not a folder. Once the Tasks gate is signed, execution begins. Execution loop (each step shows the owner): 1. **Create Jira Tasks** — **engineer** (or agent via Atlassian MCP, with engineer review) creates a Jira **Task** per engineering task (siblings of the parent stories under the same epic), linking each Task to the story or stories it serves via "implements" or similar. Cross-link the breakdown. -2. **Execute the codegen plan** — **engineer + agent** work `codegen-plan.md` file-by-file. Agent generates each file; engineer reviews the diff and commits. Check off each file as it lands. +2. **Execute task by task** — **engineer + agent** work each engineering task in `tasks.md`. For the current task, the agent generates / modifies each file listed in the task's Files affected; engineer reviews the diff and commits. Move to the next file, then the next task. 3. **Close tasks as they merge** — **engineer** transitions the Jira Task to Done when engineering DoD is met (tests, review, build, behind flag if applicable). 4. **Notify QA when a story is ready** — when all tasks serving a story have merged (and the flag is enabled in staging if flagged), **engineer/pair** notifies the QA Engineer. 5. **QA validates** — **QA Engineer** validates the story against its AC (not task DoD). Story closes on pass. @@ -180,7 +179,7 @@ Questions from PM, AppSec, peer teams, or anyone else reviewing the design come 1. **Jira pointers** — epic ID and board/filter link, so anyone navigating from `state.md` can drill into ticket detail. 2. **Phase progress** — checkboxes for breakdown-level milestones that Jira doesn't represent: design sections complete, cross-team signoffs done, Design Approval Gate signed, Tasks Approval Gate signed. -3. **Codegen execution** — flagging path, codegen plan progress (`N of M files complete`), active codegen step (which file the agent is touching now, which Jira Task it's part of). Sub-task granularity that Jira doesn't carry. +3. **Task execution** — flagging path, active task (which Jira Task is in progress now, which story it serves), active file within the task (which file the agent is touching now, file N of M for this task). Sub-task granularity that Jira doesn't carry. 4. **Open clarifications** — pending `clarifications/q-*.md` files. Q-files are repo artifacts, not Jira items. 5. **Last gate** — most recent approval gate, date, outcome (Approved / Request Changes), notes on anything that changed since approval. @@ -202,7 +201,7 @@ These come from the AI-DLC pattern and are not negotiable: 1. **2-option approval format only.** Each approval gate is "Request Changes" or "Approve and Continue." Never present a 3-option menu. Never invent an emergent navigation pattern. 2. **Never proceed past a gate without explicit approval.** "Looks fine" is not approval. The user must signal Approve and Continue. 3. **Never proceed past open Q→D→A questions.** If a `clarifications/q-*.md` file has unanswered `[Answer]:` tags, the phase work stops. -4. **Update plan checkboxes immediately.** Don't batch. Don't defer. As soon as a file is generated, mark the corresponding `codegen-plan.md` checkbox. +4. **Update progress immediately.** Don't batch. Don't defer. As soon as a file is generated, update `state.md`'s Active file within task line; when a task's files are all merged, update Phase progress. 5. **Never overwrite `state.md` or audit content.** Update in place via Edit; don't Write over the whole file. 6. **Always validate content before file creation.** Mermaid diagrams parse, links resolve, file paths exist where claimed. 7. **Always read the canonical templates** before drafting an artifact. Templates evolve; don't work from memory. @@ -220,7 +219,7 @@ These come from the AI-DLC pattern and are not negotiable: ## Common mistakes - **Drafting without the Jira ticket and initiative context.** A breakdown drafted in a vacuum diverges from the work that triggered it. Always start from the ticket and (when applicable) the initiative. -- **Treating `state.md` as optional.** Stale state means anyone picking up cold has to reconstruct phase progress and codegen position by reading the design, scanning the codegen plan, and clicking through clarifications. `state.md` exists so they don't have to. +- **Treating `state.md` as optional.** Stale state means anyone picking up cold has to reconstruct phase progress and active-task position by reading the design, scanning tasks.md, and clicking through clarifications. `state.md` exists so they don't have to. - **Duplicating Jira state in `state.md`.** Task counts, story statuses, QA queue, assignees — these all live in Jira. Adding them to `state.md` creates drift between two trackers. `state.md` carries only what Jira can't (phase gates, codegen position, open Q→D→A clarifications). - **Skipping the Q→D→A pattern for "small" questions.** Conversational clarifications get lost. Question files survive the next context reset; chat does not. - **Slicing tasks horizontally instead of by logical implementation unit.** "All data model changes" produces a PR that mixes unrelated changes and isn't reviewable as one coherent unit. Each task should be sized for one code review pass and one merge event. @@ -229,8 +228,8 @@ These come from the AI-DLC pattern and are not negotiable: - **Starting design without user stories.** Stories are inputs to the breakdown. Bootstrap should pull them; missing stories is a blocker, not a section to fill in. Engineering doesn't author stories on Product's behalf. - **Carving work across teams within one breakdown.** Cross-team execution means separate breakdowns, linked via the Cross-team engagement section. Trying to track multi-team work in one breakdown's `tasks.md` collapses the model. - **Editing a template instead of copying it.** Templates are canonical; teams copy them. Editing in place corrupts the next breakdown's starting point. -- **Approving a gate to "save time" without reading the artifact.** Downstream gates treat upstream approvals as authoritative. A rubber-stamped functional-design becomes the source the codegen-plan trusts. -- **Letting `codegen-plan.md` checkboxes lag execution.** Drift between checkboxes and actual files breaks the file-grain ↔ ticket-grain bridge `state.md` depends on. +- **Approving a gate to "save time" without reading the artifact.** Downstream gates treat upstream approvals as authoritative. A rubber-stamped Functional Design section becomes the source the tasks trust. +- **Letting `state.md` progress lag execution.** Drift between `state.md`'s active-task line and reality breaks the cold-start dashboard property. ## Reference