Remove tech breakdown skills from delivery-tools plugin

[trmartin4]

📔 Objective

Remove the four Tech Breakdown drafting skills from bitwarden-delivery-tools and update every remaining reference across the repo.

They are moved to tech-breakdowns in https://github.com/bitwarden/tech-breakdowns/pull/23.

Removed

• plugins/bitwarden-delivery-tools/skills/starting-breakdown/
• plugins/bitwarden-delivery-tools/skills/developing-breakdown-spec/
• plugins/bitwarden-delivery-tools/skills/developing-breakdown-plan/
• plugins/bitwarden-delivery-tools/skills/decomposing-into-tasks/

[github-actions]

Plugin Validation Report — PR #161

Verdict: PASS — no blocking issues. Both changed plugins validate cleanly on structure, manifests, versioning, frontmatter, and security. Three non-blocking quality findings are documented below; all are documentation-actionability gaps that the skill removal exposed, not defects it introduced.

Scope: bitwarden-delivery-tools (2.2.0 → 3.0.0) and bitwarden-tech-lead (3.0.0 → 3.0.1). The PR removes four Tech Breakdown skills (starting-breakdown, developing-breakdown-spec, developing-breakdown-plan, decomposing-into-tasks) and repoints cross-references at the external bitwarden/tech-breakdowns repository. 652 deletions, 40 insertions.

---

Errors (must fix)

None.

---

Warnings (should fix)

Minor 1 — Agent is told to clone a repo but has no tool that can clone

plugins/bitwarden-tech-lead/agents/AGENT.md:79

"Clone it when the team is drafting a breakdown coming out of the funnel's Scoping & Commitment phase."

The agent's tool grant is tools: Read, Write, Glob, Grep, Skill (line 42) — no Bash, no WebFetch. The agent cannot execute this instruction. Before this PR the same guidance was reachable, because it was expressed as Skill(starting-breakdown) and Skill is granted. Replacing skill invocations with an external-repo pointer removed the only path to the action.

Remediation — prefer rewording over widening permissions. The tool list is correctly least-privilege for a planning agent; adding Bash to satisfy one doc sentence is the wrong trade in this repo. Reframe the bullet so the human performs the fetch:

- **Tech Breakdowns** ([`bitwarden/tech-breakdowns`](https://github.com/bitwarden/tech-breakdowns)):
  the canonical repository for the Tech Breakdown template and per-team folder conventions.
  Ask the human to clone or open it when the team is drafting a breakdown coming out of the
  funnel's Scoping & Commitment phase.

If the agent genuinely should fetch it itself, scope the grant narrowly instead — Bash(gh repo clone:*) or WebFetch(domain:github.com) — mirroring how architecting-solutions scopes WebFetch(domain:contributing.bitwarden.com). Do not add bare Bash.

Minor 2 — Phase-4 pointer in the funnel skill is unreachable under its own allowed-tools

plugins/bitwarden-delivery-tools/skills/navigating-the-initiative-funnel/SKILL.md:50

Same root cause. Line 50 asserts the Tech Breakdown "is the canonical artifact for this phase," then points at a GitHub repository — but allowed-tools (line 4) grants only Skill plus nine read-only Atlassian MCP tools. No Bash, Read, or WebFetch. The paragraph previously carried four actionable Skill(...) invocations covering setup → spec → plan → task decomposition; it now names the artifact without any path to producing one.

Sibling docs are more actionable for the same repo and are worth matching: plugins/bitwarden-testing-tools/skills/assessing-test-coverage/SKILL.md:19 says "read it from bitwarden/tech-breakdowns via gh."

Remediation: either state plainly that the team drafts the breakdown in that repo outside this skill's scope (no tool change needed — lowest-risk option), or make it actionable and add a correspondingly narrow tool grant to line 4.

Minor 3 — Narrative gap between the story list and the Tech Breakdown artifact

plugins/bitwarden-delivery-tools/skills/navigating-the-initiative-funnel/SKILL.md:39-50

Lines 39–48 tell the team to run a breakdown session and create stories, with six story-quality bullets ending at "share it back with the shepherd." Line 50 then asserts the Tech Breakdown is the canonical artifact and back-references "when 'share it back' happens above." The deleted decomposing-into-tasks skill was the bridge between these two threads ("one entry per future Jira work item"); with it gone, a reader cannot tell whether the shepherd reviews Jira stories, a markdown breakdown doc, or both — or in what order they are produced.

Remediation: add one linking sentence after the story-quality bullets, e.g. "These stories become the task list inside the Tech Breakdown; each entry corresponds to one future Jira work item." Optionally move the Tech Breakdown paragraph above line 39 so the artifact is established first, which also removes the awkward backward "above" reference.

---

Informational (no action required)

• allowed-tools over-grant (pre-existing). SKILL.md:4 grants nine Atlassian MCP tools; only get_confluence_page is referenced in the body (lines 7, 105). Not introduced by this PR and consistent with the sibling running-work-transitions skill. Least-privilege would trim it.
• No evals/ directory for navigating-the-initiative-funnel, while three sibling skills in this plugin carry eval fixtures. Not enforced by the repo's validation scripts.
• epic-breakdown keyword retained in plugins/bitwarden-tech-lead/.claude-plugin/plugin.json:15 — verified still accurate. Epic-to-story breakdown remains in scope; only Tech Breakdown document drafting moved out.

---

What was validated

1. Plugin structure (plugin-validator agent) — PASS, 0 findings

Check	Result
plugin.json valid JSON, kebab-case name, valid semver, well-formed author/homepage/repository/keywords	Pass (both)
bitwarden-tech-lead "agents": "./agents/AGENT.md" path resolves	Pass
bitwarden-delivery-tools skills/ auto-discovery (no explicit field needed)	Pass
Agent frontmatter: name 19 chars lowercase-hyphen, 4 well-formed <example> blocks with <commentary>, model: opus, color: cyan, system prompt lines 48–83	Pass
Declared skills: contributing-to-technical-strategy exists	Pass
All 9 SKILL.md files: --- opener, name matching directory, non-empty description	Pass
Hooks / commands / MCP configs	None shipped — nothing to validate
README.md + CHANGELOG.md present, Keep a Changelog format, descending version order	Pass (both)
Orphaned files / empty directories after removal	None — find -type d -empty clean; each removed skill dir deleted whole including references/ and examples/ children
No node_modules, .DS_Store, build artifacts	Pass

Version consistency — verified across all four locations per plugin (plugin.json, root .claude-plugin/marketplace.json, plugin CHANGELOG.md, root README.md catalog). 3.0.0 and 3.0.1 match everywhere. AGENT.md carries no version: field, consistent with repo convention, so nothing to sync there.

Semver appropriateness — bitwarden-delivery-tools 3.0.0 (MAJOR) is correct for a breaking skill removal, and the changelog marks it **BREAKING:** under ### Removed. bitwarden-tech-lead 3.0.1 (PATCH) is correct for a documentation-only cross-reference fix, and its entry cross-links the cause ("Follows the skill removal in bitwarden-delivery-tools 3.0.0"), making the two-plugin coordination traceable.

Dangling references — repo-wide grep for all four removed skill names returns hits only in CHANGELOG history (bitwarden-delivery-tools/CHANGELOG.md lines 12, 37, 41, 46, 52, 58, 59, 63; bitwarden-tech-lead/CHANGELOG.md lines 12, 30), which is expected and correct. Zero hits in live skills, agents, or READMEs. plugins/bitwarden-tech-lead/README.md:25 already lists only the three surviving delivery-tools skills.

Cross-plugin references resolve — every Skill(...) target in AGENT.md:78-82 and both READMEs exists on disk: architecting-solutions, navigating-the-initiative-funnel, running-work-transitions (delivery-tools); bitwarden-security-context, reviewing-security-architecture, threat-modeling (security-engineer); researching-jira-issues (atlassian-tools).

2. Skill review (skill-reviewer agent) — PASS with recommendations

Only one SKILL.md survived and was modified: navigating-the-initiative-funnel. The other four were deleted.

• Frontmatter — name and description present; allowed-tools syntactically valid and matching the sibling running-work-transitions.
• Description quality — strong. ~490 chars, third-person, four concrete trigger scenarios, domain-specific vocabulary ("Architectural Assessment", "PoC", "shepherd"). No change needed.
• Word count — 1,601 words, comfortably inside the 1,000–3,000 target.
• Progressive disclosure — appropriately applied by not being applied: uniformly high-value prose with no extractable block; the Reference section (lines 103–106) correctly defers the canonical template, go/no-go criteria, and timeline table to Confluence via get_confluence_page rather than inlining them.
• Reference resolution — all pass. Both surviving Skill(...) targets resolve with matching name: fields; all 9 Atlassian MCP tool names verified against real registrations in plugins/bitwarden-atlassian-tools/mcp/.../src/tools/; the Confluence page ID is identical at lines 7 and 105; no references//examples//scripts/ are named and none exist, so there are no dangling paths.

Findings 2 and 3 above came from this review.

3. Security validation (reviewing-claude-config skill) — PASS

• No committed secrets. Scanned both plugin trees for API keys, tokens, passwords, credentials, bearer tokens, private keys, and provider-specific prefixes (ghp_, xox[bp]-, AKIA, sk-). Every hit is legitimate prose or a test fixture: security guidance in force-multiplier/references/safety-and-self-checks.md:63-75, architectural eval fixtures in architecting-solutions/evals/behavior-eval.json, and the word "tokens" in an example PR branch name. The literal AKIA[0-9A-Z]{16} in the force-multiplier reference is a detection regex, not a key.
• No settings.local.json or .env committed anywhere in the repo.
• No settings files modified by this PR, so no permission-scoping or auto-approval surface changed.
• Agent tool access is appropriately least-privilege — AGENT.md:42 grants Read, Write, Glob, Grep, Skill: no Bash, no Edit, no network. This is the correct posture for a planning agent and should be preserved (see Minor 1, which recommends rewording rather than widening it).
• All added lines in this PR are prose, versions, and links — no executable code, no configuration with a security surface.

---

Checks not run

• pnpm run lint / npx prettier --check and the repo's scripts/validate-plugin-structure.sh and scripts/validate-marketplace.sh could not be executed — the sandbox blocked these invocations. Every check those scripts perform was verified manually above.
• Prettier's markdown-table alignment was the one mechanical gap, so it was verified by hand for the one table this PR structurally rewrote: the Technical design table at plugins/bitwarden-delivery-tools/README.md:30-32 has separator widths of exactly 24 / 97 / 161 characters, matching its header and content rows. The root README.md catalog table kept its separator row unchanged and the replacement row preserved its column padding, so widths are stable there too. CI's lint.yml remains authoritative.

---

Positive observations

• The removal is unusually clean: 652 deletions with zero residue — no orphaned directories, no stray references/process-flow.dot or examples/task-breakdown.md files, no live dangling references.
• The bitwarden-delivery-tools 3.0.0 changelog entry enumerates every downstream file it touched (navigating-the-initiative-funnel, README.md, plugin.json), and the diff matches that description exactly.
• Description, keywords, and catalog text were updated in lockstep across plugin.json, marketplace.json, both READMEs, and both changelogs — no half-renamed surfaces.
• plugins/bitwarden-delivery-tools/references/change-type-labels.md was correctly not removed; it is a plugin-root reference consumed via ${CLAUDE_PLUGIN_ROOT} by three surviving skills.

[github-actions]

🤖 Bitwarden Claude Code Review

Overall Assessment: APPROVE

This PR removes the four Tech Breakdown drafting skills (starting-breakdown, developing-breakdown-spec, developing-breakdown-plan, decomposing-into-tasks) from bitwarden-delivery-tools and repoints every remaining reference at the bitwarden/tech-breakdowns repository. I verified there are no dangling Skill(...) references, keyword entries, or file references to the removed directories anywhere in the repo. Version bumps and changelog entries are present and consistent across marketplace.json, both plugin.json manifests, and the root README catalog — bitwarden-delivery-tools 2.2.0 → 3.0.0 (major, correctly reflecting the breaking skill removal) and bitwarden-tech-lead 3.0.0 → 3.0.1 (patch, documentation-only AGENT.md edit). No security, correctness, or breaking-change concerns beyond the intentional and documented removal.

Code Review Details

No findings.

Verification performed:

• Repo-wide grep for the four removed skill names across *.md, *.json, *.sh, *.yml, *.dot — no stale references outside changelog history.
• plugins/bitwarden-delivery-tools/references/ and remaining skills contain no references to the deleted references/process-flow.dot or examples/task-breakdown.md files.
• Version consistency across .claude-plugin/marketplace.json, plugins/*/.claude-plugin/plugin.json, and the root README.md table.
• bitwarden-tech-lead/agents/AGENT.md frontmatter, tool access, and model selection unchanged; only prose edits in the workflow-orchestration paragraph and Cross-Plugin Integration list.
• No secrets, settings files, permission changes, or dependency manifest changes in the diff.