Add new skill for breakdown

[trmartin4]

📔 Objective

Adds a new skill for breakdown that understands the context of the phased breakdown and construction approach in https://github.com/bitwarden/tech-breakdowns/pull/3.

[github-actions]

Validation Summary — PR #130

Plugin: bitwarden-delivery-tools
Changed file: plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md (new)

Overall: CHANGES REQUESTED

The new skill is substantively well-written and structurally sound, but the PR is missing the mandatory version bump and CHANGELOG entry required by the repo's CLAUDE.md for any substantive plugin change. Progressive disclosure is also absent.

---

Critical (must fix — blocks merge)

1. Missing plugin version bump

• Where: plugins/bitwarden-delivery-tools/.claude-plugin/plugin.json and .claude-plugin/marketplace.json (entry for bitwarden-delivery-tools)

• Issue: Both still pin version 1.3.0 (released 2026-05-20). Adding a new skill is a backward-compatible feature and must be a MINOR bump.

• Fix: From repo root, run

  echo "y" | ./scripts/bump-plugin-version.sh bitwarden-delivery-tools 1.4.0

  This updates plugin.json and the marketplace.json entry in lockstep.

2. Missing CHANGELOG entry

• Where: plugins/bitwarden-delivery-tools/CHANGELOG.md

• Issue: Newest entry is [1.3.0] - 2026-05-20; there is no [1.4.0] block describing the new skill. CLAUDE.md ("When Modifying Existing Plugins") makes this mandatory.

• Fix: Prepend a new entry under Keep a Changelog format, e.g.

  ## [1.4.0] - 2026-06-02
  
  ### Added
  
  - `running-ai-dlc-breakdown` skill — drives a Bitwarden tech breakdown end-to-end through the three-phase AI-DLC model (design → construction → execution) in the `bitwarden/tech-breakdowns` repo, with Design and Tasks approval gates, Q→D→A clarifications, codegen-plan-to-Jira slicing, and `state.md` for breakdown-level state.
  

---

Major (should fix)

3. No progressive disclosure — single 3,668-word file

• Where: plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md

• Issue: Skill ships as one file at ~3,668 words (target 1,000–3,000). No references/, examples/, or scripts/ subdirectories — every invocation loads the full QA model, clarification mechanism, and state.md rules even when the agent only needs the phase-1 drafting order. Sibling skills (coordinating-cross-team-breakdown, creating-pull-request) already follow the progressive-disclosure pattern.

• Fix: Extract these blocks into references/ and replace each with a 5–10 line inline summary that links out:

  • Lines 121–138 "QA testing process" → references/qa-testing-process.md (the skill itself acknowledges this duplicates the README).
  • Lines 140–173 "Clarifications: two mechanisms, one index" + Q→D→A → references/clarifications-qda.md.
  • Lines 175–196 "state.md — breakdown-level state" → references/state-md-update-rules.md.

  Target inline body: ~2,000–2,400 words.

4. No examples directory

• Where: plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/
• Issue: A heavily procedural skill with no concrete worked artifacts. Q→D→A files, mid-execution state.md, and tasks.md engineering-task entries are referenced repeatedly in prose but the reader has nothing to anchor on.
• Fix: Add at minimum:
  • examples/q-question-file.md — a worked Q→D→A artifact
  • examples/state-mid-execution.md — sample state.md partway through codegen
  • examples/tasks-excerpt.md — one engineering task with all fields (Stories served, Scope, DoD, Test scenarios, Blocked on, Jira ID)

---

Minor (nice to fix)

5. README not updated to advertise the new skill

• Where: plugins/bitwarden-delivery-tools/README.md
• Issue: The "Technical design" section lists only writing-tech-breakdowns and coordinating-cross-team-breakdown. running-ai-dlc-breakdown is absent from user-facing discovery. Auto-discovery still works, but humans browsing the README won't find it.
• Fix: Add a row under "Technical design" (or a new "Execution / AI-DLC" subsection) with the trigger phrases ("AI-DLC breakdown", "design approval gate", "tasks approval gate", "codegen plan") and a one-line summary.

6. Description form and trigger coverage

• Where: SKILL.md line 3
• Issue: Opens with imperative Drive a Bitwarden tech breakdown…; the skill-development convention used elsewhere in this repo prefers third-person ("This skill should be used when…"). Trigger phrases ("starting, drafting, or executing") miss common phrasings a user would actually type — write a tech breakdown, AI-DLC, design.md, codegen-plan.md, tasks.md, state.md, resume breakdown, approval gate.
• Fix: Rewrite in third-person form and broaden the trigger phrase set to include the artifact filenames and AI-DLC term that surface in user prompts.

7. Internal numbering mismatch

• Where: SKILL.md line 179
• Issue: "state.md tracks four things" precedes a five-item numbered list (lines 180–185).
• Fix: Change to "tracks five things", or collapse one item.

8. Inconsistent Jira-key examples

• Where: SKILL.md lines 20–35 (PM-12345) vs. line 49 (PM-23289-sync-push-notifications.md)
• Issue: Two different example Jira keys make the layout diagram and the bootstrap step look like they're describing different breakdowns.
• Fix: Pick one example key or use <JIRA-KEY> placeholder uniformly.

9. Orphan paragraphs between sections

• Where: SKILL.md lines 37–39 ("Templates are canonical…" and "Three phases. Design is…")
• Issue: Two single-sentence paragraphs sit between the repo layout and Bootstrap section with no subhead.
• Fix: Promote "Three phases" to a small subhead, or fold both into adjacent sections.

10. Keywords don't reflect the new skill

• Where: plugin.json keywords array
• Issue: No keyword covers AI-DLC / breakdown execution / codegen-plan workflows.
• Fix: Add e.g. ai-dlc and breakdown-execution.

---

What passed

• plugin.json manifest — valid JSON; all required and recommended fields present; kebab-case name; semver-formatted version.
• Directory structure — standard layout (.claude-plugin/, skills/, references/, README.md, CHANGELOG.md). Auto-discovery will pick up the new skill.
• All 9 skills' frontmatter — every SKILL.md in the plugin carries valid name and description. New skill also adds allowed-tools.
• allowed-tools correctness — comma-separated list with Skill, Read, Write, Edit, Bash, Glob, Grep plus five fully qualified MCP tools using the correct mcp__plugin_<plugin>_<server>__<tool> convention. All five Atlassian MCP tools resolved to real tools in bitwarden-atlassian-tools.
• Cross-references all valid — Skill(coordinating-cross-team-breakdown), Skill(navigating-the-initiative-funnel), Skill(architecting-solutions) in bitwarden-tech-lead, and Skill(bitwarden-security-context) in bitwarden-security-engineer all exist on disk.
• Security — no committed secrets, API keys, tokens, passwords, or credentials in the changed file. No .env/.local.json files added. All external URLs are HTTPS. allowed-tools is appropriately scoped for a workflow skill (Bash is justified by file/folder operations the skill performs).
• Writing style — imperative/infinitive throughout the procedural sections; strong "Hard rules" and "Common mistakes" sections with rationale.
• No hooks or MCP server configs added in this PR; nothing to validate there.

[withinfocus]

There are a number of validation improvements called out as comments, but generally-speaking and beyond those fixes I would suggest this land differently -- right now it's one isolated skill with no wireup. This should be a replacement for the skill in https://github.com/bitwarden/ai-plugins/blob/main/plugins/bitwarden-delivery-tools/skills/writing-tech-breakdowns/SKILL.md and to a lesser extent https://github.com/bitwarden/ai-plugins/blob/main/plugins/bitwarden-delivery-tools/skills/coordinating-cross-team-breakdown/SKILL.md. In addition, a search of "breakdown" across this repo to confirm touchpoints will be important.