Breakdown initialization and spec definition skills

[trmartin4]

📔 Objective

The first in a series of changes to decompose and enhance the existing writing-tech-breakdowns skill, for use with our new tech-breakdowns repo.

The plan for skill decomposition is roughly defined below, and these are the first 2 skills in that plan:

• Creating a new breakdown (this PR)
• Defining the Specification (the WHAT and WHY) (this PR)
• Defining the Plan (the HOW) Breakdown plan skill #143
• Defining the Tasks Breakdown tasks skill #144
• Completing the breakdown (archiving to avoid ambiguous future references)

Depends upon https://github.com/bitwarden/tech-breakdowns/pull/10 for naming of breakdown.md template.

For current ideation on all the remaining skills, you can reference #134, which will not be merged in its current state

[github-actions]

Plugin Validation Report — bitwarden-delivery-tools v1.4.0

Overall verdict: PASS. No critical or major issues. A handful of minor observations are listed below for awareness.

---

What was validated

• Plugin structure via the plugin-dev:plugin-validator agent.
• Skill quality via the plugin-dev:skill-reviewer agent (for starting-breakdown, developing-breakdown-spec, writing-tech-breakdowns).
• Security review via direct scan of all changed files (the claude-config-validator:skill-reviewer agent does not exist; the corresponding skill claude-config-validator:reviewing-claude-config exists only as a Skill, not an Agent). The changed plugin files were grep-scanned for credentials, API keys, tokens, dangerous shell patterns, and overly broad permissions.

Files reviewed

• plugins/bitwarden-delivery-tools/.claude-plugin/plugin.json
• plugins/bitwarden-delivery-tools/CHANGELOG.md
• plugins/bitwarden-delivery-tools/README.md
• plugins/bitwarden-delivery-tools/skills/developing-breakdown-spec/SKILL.md
• plugins/bitwarden-delivery-tools/skills/developing-breakdown-spec/references/process-flow.dot
• plugins/bitwarden-delivery-tools/skills/starting-breakdown/SKILL.md
• plugins/bitwarden-delivery-tools/skills/writing-tech-breakdowns/SKILL.md
• Cross-checked against .claude-plugin/marketplace.json

---

Critical issues

None.

Major issues

None.

Minor issues / observations

Plugin structure

1. plugins/bitwarden-delivery-tools/skills/developing-breakdown-spec/SKILL.md:4 — allowed-tools lists TaskCreate, which is a deferred Claude Code tool whose schema must be loaded via ToolSearch before invocation. The skill body at line 32 already documents this gracefully (load it via ToolSearch with select:TaskCreate). Acceptable; the redundancy between the frontmatter declaration and the in-body workaround is intentional and self-documenting.
2. plugins/bitwarden-delivery-tools/README.md:32 — the writing-tech-breakdowns row is correctly marked obsolete and matches the SKILL.md banner. No action needed; flagged only because the deprecated skill is intentionally still surfaced in the table.

Skill review

3. plugins/bitwarden-delivery-tools/skills/starting-breakdown/SKILL.md — 682 words, below the 1,000-word soft floor for skills. Defensible given the narrow scope (setup-only); no remediation required.
4. plugins/bitwarden-delivery-tools/skills/developing-breakdown-spec/SKILL.md — no examples/ directory. Optional improvement: a sample filled-in Spec excerpt would aid first-time users; not blocking.
5. plugins/bitwarden-delivery-tools/skills/writing-tech-breakdowns/SKILL.md:3 — description is ~625 chars (slightly over the 500-char soft guideline). Length is carrying the deprecation banner verbatim, which is intentional and acceptable.
6. plugins/bitwarden-delivery-tools/skills/writing-tech-breakdowns/SKILL.md — references Skill(coordinating-cross-team-breakdown) (lines 9, 50, 52, 184, 188, 191, 207) and Skill(navigating-the-initiative-funnel) (lines 24, 28, 74, 195, 207). Both sibling skills exist in the same plugin (skills/coordinating-cross-team-breakdown/, skills/navigating-the-initiative-funnel/), so the references are valid.
7. plugins/bitwarden-delivery-tools/skills/writing-tech-breakdowns/SKILL.md:4 — optional hardening: a deprecated skill could narrow allowed-tools (e.g., drop the Confluence/Jira MCP set) to reinforce the deprecation signal. Currently the tool list is broad enough that the skill remains fully operable; this very slightly undercuts the deprecation banner. Non-blocking.

Security

8. No hardcoded credentials, API keys, tokens, passwords, or private-key material were found in any changed file.
9. The newly-granted Bash permissions in starting-breakdown/SKILL.md:4 — Bash(git clone:*), Bash(git pull:*), Bash(git status:*), Bash(cp:*), Bash(mkdir:*) — are narrowly scoped to the operations the skill actually performs (template cloning and folder/file creation under bitwarden/tech-breakdowns). The colon-glob patterns are appropriate; none are overly broad (e.g., no unconstrained Bash(*), no Bash(rm:*)).
10. No .local.json or settings files were modified, so there are no permission-scoping or auto-approval risks introduced by this PR.

---

Validation coverage

Check	Result
plugin.json schema, semver, required fields	PASS
marketplace.json ↔ plugin.json version + description consistency (both at 1.4.0)	PASS
CHANGELOG.md Keep-a-Changelog format and matching [1.4.0] - 2026-06-09 entry	PASS
README.md surfaces both new skills with triggers and purposes	PASS
New starting-breakdown skill frontmatter and content	PASS
New developing-breakdown-spec skill frontmatter and content	PASS
developing-breakdown-spec/references/process-flow.dot exists and matches the documented flow	PASS
writing-tech-breakdowns deprecation banner well-signaled in description and body	PASS
Cross-skill Skill(...) references resolve to existing siblings	PASS
No secrets, no overly broad permissions, no dangerous auto-approvals	PASS

Recommendation: ready to merge. The two optional follow-ups (examples/ in developing-breakdown-spec, tightening allowed-tools on the deprecated writing-tech-breakdowns) can be deferred to a later PR.

[github-actions]

🤖 Bitwarden Claude Code Review

Overall Assessment: APPROVE

This PR introduces the first two skills (starting-breakdown, developing-breakdown-spec) in the planned decomposition of writing-tech-breakdowns, marks the predecessor obsolete via README and an in-file deprecation banner, and ships a process-flow.dot reference for the spec-development flow. Plugin version is correctly bumped to 1.4.0 across marketplace.json, the plugin manifest, both READMEs, and the CHANGELOG. The latest five commits have addressed all substantive feedback from prior review rounds — the duplicate skill directory is gone, the Spec-Kit reference is no longer in the new skill's description, Glob is now declared in allowed-tools, the self-referential Skill(developing-breakdown-spec) in the Output step has been replaced with a generic "developing the Plan" prompt, and the template path was updated to templates/breakdown.md.

Code Review Details

No new findings. All previously raised issues across the 11 review threads have either been resolved in commits on this branch or were dismissed with justification (the TaskCreate tool reference was confirmed valid per Claude Code v2.1.83+).

[theMickster]

I support these changes and have added only a couple idea comments as feedback opportunities to ensure Claude does exactly as instructed.

[trmartin4]

@theMickster for your review, I did add in a nudge at the end of the skills saying "offer to continue inline by invoking Skill(X)" to continue the breakdown process. It was something the skill-creator pushed, and the justification was that it offered the opportunity to tie the skills together without forcing it to be so. Let me know if you see an issue with that approach.

[trmartin4]

@bitwarden/tech-leads I've added you as optional reviewers on this, as the intent is for these skills and subsequent ones in the follow-up PRs to leverage the new template you're reviewing in https://github.com/bitwarden/tech-breakdowns/pull/10.

I've spent a lot of time iterating on these skills (way more than I expected when starting out), trying to hone them down to what the highest-leverage work for Claude to assist you or other engineers doing breakdowns; where Claude can help, and how to make sure the skills are clear and known to provide that help consistently.

I've taken as input:

• OpenSpec skills: Fission-AI/OpenSpec@main/openspec
• Feedback from https://github.com/bitwarden/tech-breakdowns/pull/8, where Andreas has compared the existing skill to the skills he's using.
• Looking at Andreas's custom skills as an example.
• Feedback from lots of runs of the skill-creator skill.
• Our existing writing-tech-breakdowns skill.

I'd love any input on these and also on the (still Draft) #143 and #144, which build on top of this. These PRs are in Draft because I'll need to rebase on main, but the content is largely done and stable. I believe that the skills will all work together with one another, but can also be used independently if desired.

If preferred, we can merge these and you can provide feedback on skill effectiveness after the fact, but I want to make sure that these are actually helpful for you and your teams doing breakdowns.

[theMickster]

Approving on behalf of the team-ai-sme and not tech-leads as denoted by GitHub.

[withinfocus]

I'm not really sure a tech lead is gonna review this independently as it's entirely about AI skills.

Regarding the "deprecated" skills though, is that necessary? Just get rid of the ones you're no longer supporting. This is entirely contained here and we're not building anything repo-specific using them so you can just delete the skills, no?

[trmartin4]

Regarding the "deprecated" skills though, is that necessary? Just get rid of the ones you're no longer supporting. This is entirely contained here and we're not building anything repo-specific using them so you can just delete the skills, no?

@withinfocus my fear was that we'd be left with no full solution as this is broken up into several PRs; in the interim we'd have no full breakdown solution in the plugins. Is that OK?

Would you be OK with me removing them as part of the tasks PR, since that's the last one in the chain and at that point we'll have the full process in the new skills? #144

[withinfocus]

I don't personally think it's some critical gap and as long as you get them purged once your wave of work completes, that's fine. I just don't want it seen as more traditional deprecation with some long tail.

[trmartin4]

@bitwarden/tech-leads I merged this PR, as Matt pointed out, your input will likely be more valuable as users of the skill versus evaluators of the skill as written. I'm preferencing merging them so that they can be used and iterated upon in action. Please don't take this as ignoring feedback.