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. Version bumps are correct and complete — delivery-tools 2.4.0 → 3.0.0 (major, matching the BREAKING removal) and tech-lead 3.0.0 → 3.0.1 (patch, doc-only), each reflected in plugin.json, .claude-plugin/marketplace.json, the README catalog, and a Keep a Changelog entry. A repo-wide search confirms no dangling Skill(...) references to the four removed skills remain outside historical changelog entries, and no sibling plugin depended on them.

Code Review Details

No findings at or above the reporting threshold.

The actionability gap raised in the previous review round (plugins/bitwarden-tech-lead/agents/AGENT.md) has been addressed: the Tech Breakdowns bullet now phrases the step around reading from a local checkout, and the "all cross-plugin skills are required / STOP" rule explicitly exempts the repository pointer. The allowed-tools addition in navigating-the-initiative-funnel/SKILL.md (Read, Bash(git clone:*), Bash(gh api repos/bitwarden/*)) matches the pattern already used by bitwarden-testing-tools/skills/assessing-test-coverage, so it is consistent with repo convention.

[github-actions]

Claude Configuration Validation

PR: #161 — remove breakdown skills from bitwarden-delivery-tools
Changed plugins: bitwarden-delivery-tools (2.4.0 → 3.0.0), bitwarden-tech-lead (3.0.0 → 3.0.1)

Verdict: ✅ Approve with comments. No critical issues. The skill removal is complete and internally consistent — versions, changelogs, and every cross-reference were updated correctly. Two findings concern the newly added allowed-tools grants in navigating-the-initiative-funnel, which are broader than what the skill body actually does.

Check	Result
1. Plugin validation (plugin-validator)	PASS with findings
2. Skill review (skill-reviewer)	PASS with findings
3. Config & security review (reviewing-claude-config)	PASS — no secrets

---

Critical (0)

None.

---

Major — errors that should be fixed before merge (2)

E1 — Bash(gh api repos/bitwarden/*) is unused and pre-approves write/delete calls

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

allowed-tools in a SKILL.md is pre-authorization, not restriction — listed tools run without an approval prompt for the turn that invokes the skill. Two problems:

1. Nothing in the skill body invokes gh api. Verified: the only acquisition instruction is line 50 ("clone it (or read the template from an existing local checkout)"). The string gh api appears nowhere outside the frontmatter. This is dead permission surface.
2. The pattern is not read-only. Bash rules match by command prefix and a bare * spans arguments including spaces, so this rule auto-approves gh api repos/bitwarden/server --method DELETE, gh api repos/bitwarden/clients/issues -X POST ..., and collaborator-add calls against any Bitwarden repo.

This is a real-world risk here because the same skill grants eight Jira/Confluence MCP read tools and routinely pulls attacker-influenceable text (Confluence bodies, Jira comments) into context.

Fix: drop the entry entirely (nothing uses it). If a read path is intended, follow existing repo precedent and constrain the method:

Bash(gh api --method GET repos/bitwarden/tech-breakdowns/*)

Precedent: plugins/bitwarden-security-engineer/skills/auditing-hackerone-vulns/SKILL.md:4 and plugins/bitwarden-devops-engineer/skills/workflow-fix/SKILL.md:17 both use Bash(gh api --method GET *).

E2 — The external-repo handoff on line 50 is not executable as written

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

"Breakdowns live in the bitwarden/tech-breakdowns repository — clone it (or read the template from an existing local checkout), follow the per-team folder conventions, and fill in the template's Specification, Plan, and Tasks sections."

The prose replacing the four Skill() calls loses their actionability. Four gaps, any one of which stalls the agent:

• No template path or filename — the agent is told to read "the template" with no idea where it lives in that repo.
• "read from an existing local checkout" is impossible with this tool set — Read needs a known absolute path, and neither Glob nor Grep is granted, so the agent has no way to find a checkout.
• No failure path — gh api repos/bitwarden/tech-breakdowns returns 404 from this environment, so the repo is private or the token lacks access; an unauthenticated git clone will fail and the skill says nothing about what to do next. AskUserQuestion is not granted either, so it cannot cleanly ask the human.
• "per-team folder conventions" — no pointer to where those are documented.

Note the sibling agent already gets this right — plugins/bitwarden-tech-lead/agents/AGENT.md:79 says "if no checkout is present, ask the human to clone it". The SKILL.md should carry the same fallback.

Fix: name the template file, give the exact command, and add the ask-the-human fallback. Also consider phrasing the sections as "the sections the template defines" rather than hardcoding "Specification, Plan, and Tasks" — that structure is now owned by an external repo and will drift.

---

Minor — warnings (5)

W1 — Bash(git clone:*) is broader than the single use it serves

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

Syntax is valid, but the rule auto-approves cloning any repo with any flags to any destination, while the body names exactly one repo. Combined with the MCP read tools that ingest untrusted Confluence/Jira text, a prompt-injection payload could reach the known git clone -c protocol.ext.allow=always 'ext::sh -c …' RCE vector under a rule that reads as harmless.

Scoped to the body's actual need:

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

Kept at minor because plugins/bitwarden-atlassian-tools/skills/assessing-jira-issue-relevance/SKILL.md:4 uses the same broad pattern — this is consistent with existing precedent rather than a regression.

W2 — Changelog omits the permission-surface change

plugins/bitwarden-delivery-tools/CHANGELOG.md:8-18

The 3.0.0 entry documents the skill removals, the Phase-4 prose rewrite, and the README/plugin.json edits — but not the new Read, Bash(git clone:*), and Bash(gh api repos/bitwarden/*) grants. A tool pre-authorization expansion is the most review-worthy line in the diff and should be called out under ### Changed. Land this alongside the E1/W1 fixes.

W3 — bitwarden-tech-lead/README.md lags the AGENT.md edit

plugins/bitwarden-tech-lead/README.md:31

AGENT.md was softened this PR ("a missing local checkout is not a STOP condition — ask the human to clone it") and gained a Tech Breakdowns bullet. The README still reads "All cross-plugin skills are required because we rely upon each of them for a rich, complete workflow" and its Cross-Plugin Integration table (lines 23–29) has no bitwarden/tech-breakdowns row. The table's bitwarden-delivery-tools row is otherwise accurate — it never named the removed skills.

W4 — Description is 532 chars and omits "Scoping & Commitment"

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

Slightly over the ~500-char guideline, yet missing the literal phase name users actually say — which the plugin README lists as a trigger for this very skill. Tighten one clause and fold the phase name in.

W5 — Bash grants are unreachable from the agent that composes this skill

plugins/bitwarden-tech-lead/agents/AGENT.md:42 declares tools: Read, Write, Glob, Grep, Skill — no Bash. When this skill runs inside the tech-lead agent the git clone path is unavailable, which is why AGENT.md:69 correctly says to ask the human. Not a break (the skill is agent-neutral by design), but it reinforces that the grants in E1/W1 deserve a second look. Nit on AGENT.md:69: "The Tech Breakdowns bullet points at a separate repository" reads awkwardly — "The Tech Breakdowns bullet below points to a separate repository" is clearer.

---

Verified Clean

Security scan (no findings)

• No committed settings.local.json anywhere in the repo.
• No hardcoded credentials, API keys, tokens, or passwords in either changed plugin or in marketplace.json. The only regex hits were TARGET_SKILL_TOKEN = "committing-changes" / "creating-pull-request" in the eval harnesses — skill-name constants, not secrets.
• No settings.json / settings.local.json changed in this PR, so no permission-scoping or dangerous auto-approval surface beyond the SKILL.md allowed-tools discussed above.
• No dangerous command patterns (rm -rf, chmod 777, curl | sh, force-push) in any changed file.
• No MCP servers or hooks in either plugin; nothing to check for HTTPS/WSS enforcement or ${CLAUDE_PLUGIN_ROOT} misuse in script paths.

Removal completeness

• All four skill directories deleted in full, including references/process-flow.dot and examples/task-breakdown.md. No orphaned or empty directories remain.
• Repo-wide grep for starting-breakdown, developing-breakdown-spec, developing-breakdown-plan, decomposing-into-tasks returns hits only inside CHANGELOG files — the correct historical record. No live dangling Skill() reference anywhere, including in bitwarden-shepherd and bitwarden-tech-lead, which reference this plugin.
• Both surviving Skill() targets on SKILL.md:106 resolve: skills/running-work-transitions/ and skills/architecting-solutions/.
• ${CLAUDE_PLUGIN_ROOT}/references/change-type-labels.md still resolves and is still used by three skills — not orphaned by the removal.

Manifests and versioning

• All three JSON manifests parse. Names are kebab-case and match their directories; description, author, homepage, repository, keywords all present; no unknown fields.
• Version consistency verified across all four required locations. bitwarden-delivery-tools 3.0.0 in .claude-plugin/marketplace.json:82, plugins/bitwarden-delivery-tools/.claude-plugin/plugin.json:3, README.md:14. bitwarden-tech-lead 3.0.1 in .claude-plugin/marketplace.json:69, plugins/bitwarden-tech-lead/.claude-plugin/plugin.json:3, README.md:10.
• agents/AGENT.md carries no version: field, consistent with the designer/shepherd/software-engineer agents in this repo — nothing to bump there.
• Semver correct: MAJOR for the breaking skill removal, PATCH for the doc-only cross-reference update. Marketplace and plugin.json descriptions updated in lockstep; tech-breakdown / task-decomposition keywords removed.
• Changelog entries present in Keep a Changelog format for both plugins, with the removal correctly marked BREAKING.

Frontmatter

• AGENT.md: name: bitwarden-tech-lead (19 chars, lowercase + hyphens), 4 <example> blocks each with <commentary>, model: opus, color: cyan, tools: Read, Write, Glob, Grep, Skill (least-privilege — no Bash, no Edit), skills: [contributing-to-technical-strategy] resolves. System prompt ~1,100 words.
• All 9 remaining SKILL.md files have valid name + description, and every name matches its directory.
• navigating-the-initiative-funnel frontmatter parses cleanly — the colon in Bash(git clone:*) is a safe YAML plain scalar (not followed by a space), so the unquoted list is fine.

Skill content quality

• navigating-the-initiative-funnel body is 1,541 words — comfortably inside the 1,000–3,000 target. Consistent imperative/infinitive voice, concrete inline examples, no bloat. No references/or examples/ directory, appropriate at this length.
• The replacement prose preserves the why ("the team produces a Tech Breakdown from it") rather than just deleting the mechanics.
• Nit for future tracking (out of scope for this PR): this is one of two skills in the plugin with no evals/ directory; four siblings have them.

---

Checks Not Run

• pnpm run lint (prettier + cspell) — pnpm is not installed in this environment and npx prettier is blocked by the repo's devEngines packageManager pin. CI's lint.yml workflow covers this.
• validate-plugin-structure.sh / validate-marketplace.sh — these live in bitwarden/gh-actions and no checkout is available here. Their checks (manifest correctness, marketplace consistency, version bump across all four files) were performed manually above and pass; the Validate AI workflow will confirm.

---

Recommended Actions Before Merge

1. Delete Bash(gh api repos/bitwarden/*) from SKILL.md:4 — nothing uses it (E1).
2. Make SKILL.md:50 executable: name the template file, give the exact command, add the ask-the-human fallback (E2).
3. Scope Bash(git clone:*) to bitwarden/tech-breakdowns (W1).
4. Add a ### Changed changelog line covering the allowed-tools expansion (W2).
5. Update plugins/bitwarden-tech-lead/README.md to match the softened AGENT.md wording (W3).