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 from bitwarden-delivery-tools and repoints every remaining reference at the bitwarden/tech-breakdowns repository. A repo-wide search confirms no dangling Skill(...) references to the removed skills remain, and the removed skill directories (including their examples/ and references/ files) are fully deleted. Version bumps are complete and correctly scoped — bitwarden-delivery-tools 2.4.0 → 3.0.0 (major, for the breaking skill removal) and bitwarden-tech-lead 3.0.0 → 3.0.1 — and are consistent across marketplace.json, each plugin.json, and the README catalog, with changelog entries for both.

Code Review Details

No findings at or above the reporting threshold.

The new Bash(git clone https://github.com/bitwarden/tech-breakdowns*) entries in the navigating-the-initiative-funnel frontmatter are narrower than existing allowed-tools patterns elsewhere in the repo (e.g. Bash(git clone:*) in assessing-jira-issue-relevance and assessing-test-coverage), and the skill documents a non-Bash fallback for agents whose tool ceiling excludes Bash. The actionability gap raised in the earlier review round on plugins/bitwarden-tech-lead/agents/AGENT.md is resolved — the agent is now told to read from a local checkout and ask the human to clone when absent, which is executable under its Read, Write, Glob, Grep, Skill allowlist, and the STOP condition is explicitly scoped to plugin skills only.

[github-actions]

Claude Configuration Validation — PR #161

Scope: removal of four Tech Breakdown skills from bitwarden-delivery-tools (→ 3.0.0, BREAKING) and the follow-on documentation/agent updates in bitwarden-tech-lead (→ 3.0.1).

Result: No critical issues. The removal itself is clean and complete. Three findings worth addressing before merge, all in the replacement Phase‑4 guidance that points at the external bitwarden/tech-breakdowns repo.

Check	Result
Plugin manifests (JSON validity, name, semver)	Pass
Version consistency across 4 required locations	Pass
Auto-discovery / directory structure	Pass
Agent frontmatter (bitwarden-tech-lead)	Pass
Skill frontmatter + word count	Pass (1,613 words, in the 1,000–3,000 band)
Dangling references to removed skills	None outside CHANGELOG history
Committed secrets / hardcoded credentials	None
settings.local.json / .env committed	None
Dangerous command auto-approvals	None (see minor #4 on wildcard boundary)
Hooks / MCP server configs	None present in either plugin

---

Errors (must fix)

None. Nothing in this PR blocks functionality or exposes a vulnerability.

---

Warnings (should fix)

Major 1 — Skill instructs a file-copy it has no tool to perform

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

"Copy the two template files into the team's folder per the repository README's conventions, and fill in the sections the template defines."

The allowed-tools list on line 4 grants only Read, Skill, two Bash(git clone …) rules, and read-only Atlassian MCP tools. There is no Write, no Edit, no Glob, and no Bash(cp …). Under a restricted tool set the agent can read the templates and then stall.

Remediation — pick one:

• Add the tools the instruction needs: Read, Write, Edit, Glob, Skill, … (Glob also helps locate an existing local checkout, which line 50 tells the agent to look for).
• Or reword line 56 so the copy-and-fill step is explicitly handed to the human.

Major 2 — The documented clone command is the one guaranteed to fail

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

The body shows only the HTTPS form:

git clone https://github.com/bitwarden/tech-breakdowns.git

and line 56 concedes it will 404 because the repo is private. Meanwhile allowed-tools (line 4) permits an SSH clone — Bash(git clone git@github.com:bitwarden/tech-breakdowns*) — that a credentialed Bitwarden engineer's environment would actually satisfy, but the body never mentions it, so the model has no reason to try it. Net effect: the documented happy path always fails, then falls back to "ask the human."

Remediation — document the authenticated variant alongside the HTTPS one, or drop the SSH rule as dead permission surface. Note that plugins/bitwarden-testing-tools/skills/assessing-test-coverage/SKILL.md reads this same private repo via gh, which inherits gh auth and sidesteps the problem; Bash(gh repo clone bitwarden/tech-breakdowns:*) would be more consistent across plugins.

Major 3 — Clone path is unreachable from this plugin's primary consumer

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

tools: Read, Write, Glob, Grep, Skill

A subagent's tools list is a hard ceiling — a skill's own allowed-tools cannot grant tools the parent agent lacks. Bash is absent, so the clone instruction added in this PR can never run when navigating-the-initiative-funnel is dispatched from the tech-lead agent. The same ceiling already blocks the mcp__* Atlassian tools that this skill and running-work-transitions depend on, and the get_confluence_page call at AGENT.md:82.

This degrades gracefully — both SKILL.md:56 and AGENT.md:15 provide an "ask the human to clone it" fallback — and it is a pre-existing repo-wide pattern (bitwarden-shepherd and bitwarden-designer declare the identical tools: line with the same MCP references), so it is arguably out of scope here. Flagging it because this PR is what makes the gap load-bearing for the new Tech Breakdown path.

Remediation — either widen the agent's tools to cover what its required skills declare, or accept the human-in-the-loop fallback as the intended behavior and say so explicitly. If the repo-wide pattern is deliberate, a follow-up issue is the right home.

---

Minor

4. Wildcard has no path boundary — SKILL.md:4
Bash(git clone https://github.com/bitwarden/tech-breakdowns*) appends * directly to the repo name with no separator, so it also auto-approves any bitwarden-org repo whose name starts with tech-breakdowns. Suggested boundary-safe form:

Bash(git clone https://github.com/bitwarden/tech-breakdowns.git:*), Bash(git clone git@github.com:bitwarden/tech-breakdowns.git:*)

The blast radius is small (bitwarden-org repos only) and the repo already contains a strictly broader Bash(git clone:*) in two other skills, so this PR narrows rather than widens the org-wide surface. Both bare-* and :* styles appear in this repo today; :* is the documented prefix form and the more common convention here.

5. Changelog omits the frontmatter change — plugins/bitwarden-delivery-tools/CHANGELOG.md:16
The 3.0.0 entry covers the prose rewrite but not that the funnel skill's description was rewritten and its allowed-tools expanded with Read plus two Bash(git clone …) rules. The prior version had no Bash entries at all, so this is a new auto-approval surface — worth recording explicitly.

6. Changelog omits README changes — plugins/bitwarden-tech-lead/CHANGELOG.md:12
The 3.0.1 entry documents only AGENT.md, but README.md:23-32 was substantively rewritten in the same PR (new bitwarden/tech-breakdowns row; the "All cross-plugin skills are required…" paragraph reworded). Not formatting-only, so per the repo's CLAUDE.md policy it needs a changelog line.

7. Fenced code block has no language tag — SKILL.md:52
Add ```bash to match other fences in the plugin.

8. Clone command specifies no target directory — SKILL.md:53
Run as written, it clones tech-breakdowns/ into whatever repo the engineer is currently sitting in. Suggest a concrete target so an unrelated repo isn't nested inside the working tree.

9. Description dropped two trigger keywords — SKILL.md:3
"sizing and estimation" became "sizing" (loses estimation), and the description never mentions "Tech Breakdown" even though Phase‑4 routing to that template is now one of the skill's headline jobs. A user asking "how do we do the tech breakdown for this initiative epic?" matches more weakly than before. Consider restoring estimation and adding Tech Breakdown to the trigger list.

10. No evals/ directory for this skill — pre-existing, but four sibling skills in the same plugin have them (force-multiplier, architecting-solutions, committing-changes, creating-pull-request), and this PR changed the description — the exact thing evals guard.

11. AGENT.md has no version: frontmatter field — nothing was missed in this bump (there is no field to bump), but the repo CLAUDE.md bump procedure lists agents/*/AGENT.md as a target and two other plugins (bitwarden-code-review, bitwarden-product-analyst) do carry it. Adding it would make the bump script's coverage uniform.

---

Verified clean

• Deletions are complete. All four skill directories are fully removed — 9 D entries covering every SKILL.md, references/process-flow.dot, and examples/task-breakdown.md. No orphaned files or empty directories.
• No dangling references. Repo-wide search for starting-breakdown, developing-breakdown-spec, developing-breakdown-plan, decomposing-into-tasks returns hits only in the two CHANGELOG.md files (historical entries, correct). Both plugin READMEs, plugin.json keywords, the marketplace description, the root README catalog, and AGENT.md were all updated.
• Version bumps correct and consistent. delivery-tools 2.4.0 → 3.0.0 (MAJOR, correct for a breaking removal, with a ### Removed BREAKING entry); tech-lead 3.0.0 → 3.0.1. Both match across marketplace.json, plugin.json, and the root README.md catalog table. Descriptions match between each plugin.json and its marketplace entry.
• Agent frontmatter valid. name: bitwarden-tech-lead (19 chars, lowercase-hyphens), 4 well-formed <example> blocks each with <commentary>, model: opus valid, color: cyan valid, substantial system prompt. The skills: list resolves (contributing-to-technical-strategy exists).
• Skill frontmatter valid. yaml.safe_load parses cleanly; name matches the directory; description is 478 chars, third-person, no second person.
• All Skill() cross-references resolve to skills that exist in the repo.
• Semantic improvement worth calling out: the AGENT.md rewrite correctly distinguishes "required plugin skill (STOP if missing)" from "external repo (ask the human to clone)" — a real behavioral distinction, not just a find-and-replace.

---

Notes on this review

• Correction to an automated finding: the plugin-validator reported that Bash(gh api repos/bitwarden/*) was removed from the funnel skill's allowed-tools. That is wrong — the pre-PR version of SKILL.md:4 contained no Bash entries at all. The change is purely additive.
• pnpm run lint (prettier + cspell) could not be run — pnpm is not installed in this environment and the repo's devEngines blocks the npm fallback. CI's lint.yml covers it.
• Steps run: plugin-validator agent (both changed plugins), skill-reviewer agent (navigating-the-initiative-funnel), and the reviewing-claude-config security/structure scan. No command, hook, MCP, settings, or repo-level CLAUDE.md/.claude/ files changed in this PR, so those portions of the checklist had nothing to review.