diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 2fd1a8c9..a9cc775b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -78,7 +78,7 @@ { "name": "bitwarden-delivery-tools", "source": "./plugins/bitwarden-delivery-tools", - "version": "2.0.0", + "version": "2.1.0", "description": "Delivery lifecycle skills for Bitwarden initiatives — initiative funnel navigation, work transitions, tech breakdowns and task decomposition, commits, pull requests, preflight checks, and change labeling." }, { diff --git a/README.md b/README.md index 58808c38..9a83cf28 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ A curated collection of plugins for AI-assisted development at Bitwarden. Enable | [bitwarden-shepherd](plugins/bitwarden-shepherd/) | 1.0.0 | Champion of a technical strategy — shepherds a TSI through evaluation into the funnel, then through to adoption | | [bitwarden-atlassian-tools](plugins/bitwarden-atlassian-tools/) | 2.2.7 | Read-only Atlassian access via MCP server with deep Jira issue research skill | | [bitwarden-code-review](plugins/bitwarden-code-review/) | 1.13.0 | Autonomous code review agent following Bitwarden engineering standards with GitHub integration | -| [bitwarden-delivery-tools](plugins/bitwarden-delivery-tools/) | 2.0.0 | Delivery lifecycle skills: initiative funnel navigation, work transitions, tech breakdowns and task decomposition, commits, PRs, preflight, labeling | +| [bitwarden-delivery-tools](plugins/bitwarden-delivery-tools/) | 2.1.0 | Delivery lifecycle skills: initiative funnel navigation, work transitions, tech breakdowns and task decomposition, commits, PRs, preflight, labeling | | [bitwarden-designer](plugins/bitwarden-designer/) | 0.1.0 | Product designer persona: Code of Conduct and 30/60/90 critique, critique facilitation; dispatches into bitwarden-design-tools | | [bitwarden-design-tools](plugins/bitwarden-design-tools/) | 0.1.0 | Design toolkit: content style guide, Figma Dev Mode MCP, Bitwarden brand application, handoff prep, Design System governance, Product and Design Jira | | [bitwarden-devops-engineer](plugins/bitwarden-devops-engineer/) | 0.1.3 | DevOps engineering assistant: workflow compliance linting, action security auditing, and org-wide CI/CD remediation | diff --git a/plugins/bitwarden-delivery-tools/.claude-plugin/plugin.json b/plugins/bitwarden-delivery-tools/.claude-plugin/plugin.json index 06aa914e..d0f3f64e 100644 --- a/plugins/bitwarden-delivery-tools/.claude-plugin/plugin.json +++ b/plugins/bitwarden-delivery-tools/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "bitwarden-delivery-tools", - "version": "2.0.0", + "version": "2.1.0", "description": "Delivery lifecycle skills for Bitwarden initiatives — initiative funnel navigation, work transitions, tech breakdowns and task decomposition, commits, pull requests, preflight checks, and change labeling.", "author": { "name": "Bitwarden", diff --git a/plugins/bitwarden-delivery-tools/CHANGELOG.md b/plugins/bitwarden-delivery-tools/CHANGELOG.md index d081fc2a..40cb3273 100644 --- a/plugins/bitwarden-delivery-tools/CHANGELOG.md +++ b/plugins/bitwarden-delivery-tools/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to the `bitwarden-delivery-tools` plugin will be documented The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.1.0] - 2026-06-19 + +### Added + +- **`completing-breakdown` skill** — marks a breakdown `Complete` and moves the breakdown folder into the team's `complete/` subfolder. + ## [2.0.0] - 2026-06-19 ### Added diff --git a/plugins/bitwarden-delivery-tools/README.md b/plugins/bitwarden-delivery-tools/README.md index 052906bd..58e37a1b 100644 --- a/plugins/bitwarden-delivery-tools/README.md +++ b/plugins/bitwarden-delivery-tools/README.md @@ -31,6 +31,7 @@ Any agent (tech-lead, software-engineer, shepherds, others) can compose these sk | `developing-breakdown-spec` | "understand the work", "resolve open questions", "write the breakdown spec", "Spec Alternatives" | Resolve open design questions one at a time with concrete options, then capture what's being built into the Specification section. | | `developing-breakdown-plan` | "develop the plan", "draft the implementation plan", "map per-layer impact", "scan for in-flight work", "identify cross-team impacts" | Develop the Plan section after the Spec is filled: technical architecture, per-layer impact, in-flight collision scan, cross-team impact mapping, and self-review. Supports resumption. | | `decomposing-into-tasks` | "decompose into tasks", "draft the tasks section", "break this into stories", "split into Jira tickets", "fill in the tasks table" | Decompose a Plan into a `tasks.md` document with one entry per future Jira work item. | +| `completing-breakdown` | "complete this breakdown", "archive the breakdown", "move breakdown to complete", "finish the breakdown" | Marks a breakdown `Complete` and `git mv` the breakdown folder into the team's `complete/` archive so the active directory only holds in-flight work. | ### Mechanics diff --git a/plugins/bitwarden-delivery-tools/skills/completing-breakdown/SKILL.md b/plugins/bitwarden-delivery-tools/skills/completing-breakdown/SKILL.md new file mode 100644 index 00000000..81d21f5f --- /dev/null +++ b/plugins/bitwarden-delivery-tools/skills/completing-breakdown/SKILL.md @@ -0,0 +1,75 @@ +--- +name: completing-breakdown +description: Complete a Bitwarden Tech Breakdown. Use when a team has completed delivering the work captured in a Tech Breakdown. Triggered by phrasings such as "complete this breakdown", "mark the breakdown as done", "archive the breakdown", "move breakdown to complete", "finish the breakdown", "wrap up the breakdown". +argument-hint: "[]" +arguments: breakdown +allowed-tools: Read, Edit, Glob, Bash(git mv:*), Bash(git status:*), Bash(mkdir:*), AskUserQuestion +--- + +# Completing a Tech Breakdown + +## Overview + +Help the user retire a Tech Breakdown once the work it describes has shipped. + + +Orientation within a breakdown is required. If `$breakdown` was provided at invocation, treat it as the breakdown identifier (path, Jira key, or slug) and resolve it via `Glob` under `tech-breakdowns/` to a real `breakdown.md`, then confirm the resolved path with `AskUserQuestion` before proceeding. Otherwise, ask the user which breakdown to complete — they can give a path, a Jira key, or a slug — and resolve the same way. If the user already named it earlier in the conversation, confirm the resolved path with `AskUserQuestion` before proceeding. + +Once the breakdown is found, do NOT update the Status or move the folder until both hold: + +- The resolved folder is not already inside a `complete/` directory. If it is, surface that and stop — the breakdown is already archived. +- The working tree is clean (`git status` in the `tech-breakdowns` checkout shows no uncommitted changes that would be entangled with the move). If it is not clean, surface the dirty files and ask the user whether to proceed or stash first. + + + +## Key Principles + +- **Status flip then move.** Update `breakdown.md` first so the commit that moves the folder also carries the terminal-state edit. Reversing the order leaves a window where the file is at its new path with stale status. +- **Preserve history.** Use `git mv` rather than `mv`. The breakdown folder's history is the design record; moving outside git rewrites it as a delete + add and breaks blame. +- **Don't touch sibling artifacts.** `tasks.md` and other files in the folder move with the folder unchanged. +- **Inform the use after move is complete.** The folder move is reversible but disruptive — links to the old path break. Surface the source path, destination path, and the affected files after doing the move so the user can revert if they did not intend to do so. + +## Phases + +### Phase 1: Resolve the breakdown + +Use the orientation rules from the HARD-GATE to locate `/-/breakdown.md` in the `tech-breakdowns` working copy. Record the resolved values: + +- `BREAKDOWN_PATH` — absolute path to `breakdown.md`. +- `BREAKDOWN_FOLDER` — the parent folder. +- `TEAM_DIR` — the team directory (`BREAKDOWN_FOLDER`'s parent). +- `DEST_FOLDER` — `/complete/-/`. + +**Validate before using in shell commands.** Slug must match `^[a-z][a-z0-9-]*$`. Jira key must match `^[A-Z][A-Z0-9]+-[0-9]+$`. Reject any resolved path that contains `..` or characters outside `[A-Za-z0-9._/-]`, and confirm `BREAKDOWN_FOLDER` and `DEST_FOLDER` resolve inside the `tech-breakdowns` working copy. If any check fails, stop and surface the mismatch — never interpolate a non-validated value into `mkdir`, `git mv`, or any other shell command. + +Read `breakdown.md` and surface the current Status block to the user before proceeding. + +### Phase 2: Update the Status block + +Edit `breakdown.md` in place. Update the Status block: + +- `Status:` — `Complete` +- `Last substantive update:` — today's date + the literal note `breakdown completed` + +Leave `Active owner / contact:` unchanged; the historical record should keep pointing at the engineer who ran the breakdown. + +Do not edit the Spec, Plan, Tasks, or any other section. The breakdown's content is now the as-shipped record. + +### Phase 3: Move the folder + +1. Ensure the `complete/` directory exists under `TEAM_DIR`. `git mv` does not create missing parent directories — if `/complete/` does not exist yet, run `mkdir -p '/complete/'` first (single-quote the interpolated path). The first breakdown a team completes will hit this case. +2. Run `git mv '' ''` from inside the `tech-breakdowns` working copy — single-quote both operands so a path containing whitespace or shell metacharacters cannot word-split. This moves `breakdown.md`, `tasks.md`, and any sibling artifacts in one operation while preserving history. +3. Surface the result to the user: + - Old path: `/-/` + - New path: `/complete/-/` + - Files moved: list from `git status`. + +Leave the commit to the user — they may want to bundle the status flip + move with a referencing message (`PM-XXXXX: complete breakdown`) and push at their own cadence. + +## Output + +When all phases are complete, tell the user: + +1. The new path of `breakdown.md` under the `complete/` subfolder. +2. That the Status block now reads `Complete`. +3. That the move is staged in git and waiting for them to commit.