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]

Plugin Validation Summary — PR #130

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

Three validation passes were run: plugin structure (plugin-validator), skill quality (skill-reviewer), and security/config review (reviewing-claude-config).

---

Overall Assessment: REQUEST CHANGES

The new skill file itself is structurally clean, well-written, and free of security issues. However, the PR is missing the mandatory version bump and changelog entry required by .claude/CLAUDE.md for any substantive plugin change. This is a CI/policy violation that must be resolved before merge.

---

Critical Issues (must fix)

1. Plugin version not bumped

• File: plugins/bitwarden-delivery-tools/.claude-plugin/plugin.json
• Current: "version": "1.3.0"
• Required: "version": "1.4.0" (MINOR bump — new backward-compatible skill)
• Fix: From the repo root, run:

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

  This updates plugin.json and marketplace.json atomically.

2. Marketplace version stale

• File: .claude-plugin/marketplace.json
• Issue: The bitwarden-delivery-tools entry still shows "version": "1.3.0", will diverge from plugin.json after the bump.
• Fix: Handled by the bump script above.

3. Missing CHANGELOG entry

• File: plugins/bitwarden-delivery-tools/CHANGELOG.md
• Issue: Latest entry is [1.3.0] - 2026-05-20; no entry for the new running-ai-dlc-breakdown skill.
• Fix: Add a new section at the top following Keep a Changelog format:

  ## [1.4.0] - 2026-06-04
  
  ### Added
  
  - `running-ai-dlc-breakdown` skill — drives Bitwarden tech breakdowns end-to-end through the three-phase AI-DLC model (design → construction → execution), with two approval gates, Q→D→A clarifications, and `state.md` for breakdown-level state.

---

Major Issues (should fix)

4. SKILL.md over the recommended word-count target

• File: plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md
• Issue: Core SKILL.md is ~3,900 words (239 lines); the skill-development guidance targets 1,000–3,000 words. File is still under the hard 500-line limit, so this is a warning, not an error.
• Fix: Apply progressive disclosure — move these reference-shaped sections to a references/ subdirectory:
  • references/repo-layout.md (lines 18–36)
  • references/clarifications.md (lines 139–172, Q→D→A pattern + human-raised flow + answer formats)
  • references/state-md-schema.md (lines 174–195)
  • references/qa-testing.md (lines 120–137)
  • references/common-mistakes.md (lines 219–232)
• Target core SKILL.md at ~1,500–2,200 words after the split.

5. No examples/ directory

• File: plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/
• Issue: The skill is highly prescriptive about artifact shape (design.md, tasks.md, state.md, q-files) but provides no concrete examples. Engineers cold-starting will have to reconstruct shape from prose.
• Fix: Add at minimum:
  • examples/q-file.md — sample Q→D→A file with multi-choice options
  • examples/state-md.md — snapshot of a mid-execution state.md
  • examples/tasks-md-entry.md — one fully-filled engineering task with all required fields

6. Description: trigger phrases vs. feature inventory

• File: plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md:3
• Issue: Description is ~770 characters; trailing enumeration reads as feature inventory rather than user-phrasing triggers. Does not disambiguate from sibling skills (coordinating-cross-team-breakdown, navigating-the-initiative-funnel).
• Fix: Lead with explicit trigger phrasings ("start a tech breakdown", "draft design.md", "decompose into engineering tasks", "sign the Design Approval Gate") and add a one-line disambiguation from the sibling skills.

---

Minor Issues (nice to have)

7. "Four things" / five-item count mismatch

• File: plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md:178
• Issue: Text says state.md tracks four things, but the numbered list below contains five items (1 Jira pointers, 2 Phase progress, 3 Task execution, 4 Open clarifications, 5 Last gate).
• Fix: Change "four things" to "five things" — or merge two items if four was intended.

8. Phase 2 narration style drift

• File: plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md:77-99
• Issue: Phase 2 uses long paragraphs while Phase 1 and Phase 3 use imperative numbered steps. Inconsistent voice.
• Fix: Restructure Phase 2 into numbered steps with team-refinement and QA-review as explicit sub-steps.

9. Hard rules list is long

• File: plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md:197-211
• Issue: Ten hard rules — rules 6 ("validate content before file creation") and 7 ("always read canonical templates") could move to a references/operating-rules.md.
• Fix: Consider extracting non-load-bearing rules to a reference file.

10. Inconsistent Skill(...) backticking

• File: plugins/bitwarden-delivery-tools/skills/running-ai-dlc-breakdown/SKILL.md (multiple locations)
• Issue: Some Skill(...) invocations are wrapped in backticks, others in bold-backticks, others bare. Pick one convention.

---

Security / Configuration Review (PASS)

The reviewing-claude-config security pass found no issues:

• No committed secrets, API keys, tokens, or passwords — only HTTPS URLs to public GitHub and Bitwarden docs.
• No hardcoded credentials in instructions or examples.
• No settings.local.json introduced or modified.
• allowed-tools scoping is appropriate — read-heavy Atlassian MCP tools (get_issue, get_issue_comments, search_issues, get_confluence_page, search_confluence) plus standard filesystem/skill tools (Skill, Read, Write, Edit, Bash, Glob, Grep). No destructive MCP tools (no Jira issue creation/transition from this skill's allowed-tools list; the skill describes those operations as performed via the engineer or a separate explicit invocation). Bash is broad but justifiable for template copying.
• MCP tool references use the correct fully-qualified mcp__plugin_<plugin>_<server>__<tool> pattern and resolve to the existing bitwarden-atlassian-tools MCP server.
• No prompt-injection risks — the skill instructs future agents but does not echo external/untrusted content into prompts.
• YAML frontmatter is valid (required name, description present; optional allowed-tools well-formed).
• File size: 239 lines, well under the 500-line hard limit.

---

What Was Validated

Check	Tool	Result
Plugin manifest structure	plugin-validator	FAIL — missing version bump + changelog
Marketplace consistency	plugin-validator	FAIL — marketplace.json version stale
Skill YAML frontmatter	skill-reviewer + plugin-validator	PASS
Skill content quality	skill-reviewer	Warnings — word count, no examples, description shape
Progressive disclosure	skill-reviewer	Warning — single file, no references/ or examples/
File references	skill-reviewer	PASS — no broken local references
Secrets / credentials	reviewing-claude-config	PASS
Tool permission scoping	reviewing-claude-config	PASS
Prompt-injection surface	reviewing-claude-config	PASS
File size limits	reviewing-claude-config	PASS (239 / 500 lines)

---

Recommended Action

1. Run the version bump: echo "y" | ./scripts/bump-plugin-version.sh bitwarden-delivery-tools 1.4.0
2. Add a CHANGELOG [1.4.0] entry describing the new skill.
3. Re-run local validators: ./scripts/validate-plugin-structure.sh bitwarden-delivery-tools and ./scripts/validate-marketplace.sh bitwarden-delivery-tools.
4. (Recommended, not blocking) — apply progressive disclosure by extracting reference-shaped sections to references/ and adding an examples/ directory; tighten the description.

[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.