feat: add tech-breakdown-template skills to delivery-tools#118
Merged
Conversation
Bring Bitwarden's Tech Breakdown Template (Confluence page 2920349776) into Claude Code as two new agent-neutral skills in `bitwarden-delivery-tools`: - `writing-tech-breakdowns` — drafts Parts 1, 2, 4, 5, 6 of the standard template plus the IN PLANNING → PROPOSED → ACCEPTED → COMPLETE status lifecycle. - `coordinating-cross-team-breakdown` — Part 3 signoff table, cross-team checklist, and completion-communication checklist that closes a breakdown. Both skills cross-reference `navigating-the-initiative-funnel` as a load-bearing first step when the breakdown sits under a BW Initiative, so the breakdown process pulls the shepherd, affected-teams list, and architecture-plan context directly from the funnel. The funnel skill is updated reciprocally to point at the two new skills at Phase 4 and in its Related block. Both the bitwarden-tech-lead and bitwarden-software-engineer agents are updated to dispatch to the new skills — the tech-lead via its Orientation and Cross-Plugin Integration sections, the software-engineer via a new "Planning and Coordination" section parallel to its existing "Security-Aware Development" section. Version bumps: bitwarden-delivery-tools 1.1.0 → 1.2.0, bitwarden-tech-lead 2.1.0 → 2.2.0, bitwarden-software-engineer 0.4.1 → 0.5.0.
Plugin Validation Summary — PR #118All three validation passes (plugin structure, skill quality, security/credentials) completed cleanly. No critical or major issues. Two minor headroom notes recorded. Plugins validated
Both plugin descriptions are identical between 1. Plugin structure (plugin-validator)
2. Skill review (skill-reviewer)
Minor notes (warnings, not errors):
3. Security / config review
Files scanned
Overall✅ PASS — both plugins, all three changed skills, and the agent redefinition validate cleanly. No remediation required. Two minor notes recorded for future-edit awareness only. |
🤖 Bitwarden Claude Code ReviewOverall Assessment: APPROVE This PR introduces two new Code Review DetailsNo new code-level findings beyond the open reviewer threads already on this PR. PR Metadata Assessment
|
Apply three cheap fixes flagged by the plugin validator on PR #118, plus add a worked example of the Part 3 signoff table for users: - Promote `REJECTED` from a `###` heading nested under completion-communication to its own `##` heading in `coordinating-cross-team-breakdown` — it's a sibling terminal state to `COMPLETE`, not a sub-step of completion comms. - Disambiguate the security-engineer skill references in `writing-tech-breakdowns` Part 2 to match the `(in the <plugin-name> plugin)` parenthetical convention used elsewhere for cross-plugin references. - Expand the status-lifecycle summary phrasing in the delivery-tools CHANGELOG and README to include `IN PROGRESS` and `REJECTED` (previously listed only the four happy-path states; SKILL.md documents all six). - Add `examples/signoff-table.md` to `coordinating-cross-team-breakdown` showing an in-flight and a fully-signed-off Part 3 table for an illustrative feature. The signoff table is the skill's primary artifact and the canonical Confluence page has no worked example. No version bump — these are documentation/clarity fixes within an unreleased PR.
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
Two follow-ups from the second validator run on PR #118: - Add `IN PROGRESS` to the `writing-tech-breakdowns` frontmatter description so it matches the body (which defines all six states) and the sibling docs (delivery-tools CHANGELOG and README, which were aligned in the previous commit). The frontmatter description is what Claude reads for skill matching; dropping a state weakens dispatch on prompts like "move the breakdown to IN PROGRESS." - Add `tech-breakdown` and `planning` keywords to the `bitwarden-software-engineer` plugin manifest so the new 0.5.0 Planning and Coordination dispatch behavior is discoverable from marketplace search.
Resolve conflicts from main bumps that landed alongside this branch: - `bitwarden-software-engineer` 0.4.1 → 0.4.2 on main (#122 added `dotnet format` to server verification). This branch bumps to 0.5.0 (new Planning and Coordination section + keywords); 0.5.0 supersedes 0.4.2 and the 0.4.2 entry is preserved as a historical CHANGELOG block under the 0.5.0 entry. - `bitwarden-tech-lead` 2.1.0 → 2.1.1 on main (#116 added `<example>` blocks to the agent description and a "Related plugins" pointer to the new bitwarden-shepherd plugin). This branch bumps to 2.2.0 (new Tech Breakdown dispatch rules); 2.2.0 supersedes 2.1.1 and the 2.1.1 entry is preserved as a historical CHANGELOG block. Main's agent-description `<example>` blocks auto-merged with this branch's Orientation and Cross-Plugin Integration additions. - `bitwarden-code-review` 1.10.1 → 1.11.0 on main (#96 multi-agent code review). No conflict with this branch; pulled in via merge. - New `bitwarden-shepherd` 1.0.0 plugin on main (#116). Added its catalog row to the root README and kept main's marketplace entry. - `marketplace.json` metadata.version 1.0.1 → 1.1.0 on main; kept. - `.cspell.json` auto-merged (this branch's `signoffs` entry sits alongside main's new entries — `Rescope`, `rustdoc`, `SDLC`, `tarpit`, `touchpoint`). All version-bump validation passes against the new main: delivery-tools 1.1.0 → 1.2.0, software-engineer 0.4.2 → 0.5.0, tech-lead 2.1.1 → 2.2.0. Lint, plugin-structure, and marketplace validators all clean.
SaintPatrck
reviewed
May 19, 2026
Comment on lines
+11
to
+19
| ## When to Reach for This Skill | ||
|
|
||
| Three triggers: | ||
|
|
||
| 1. **The breakdown has reached `PROPOSED`** in `Skill(writing-tech-breakdowns)`. Parts 1, 2, 4, 5 are drafted; the team has reviewed internally. Now affected teams need to be identified, the signoff table needs to be built, and signoffs need to be chased. | ||
| 2. **A signoff has stalled** or an affected team has surfaced an interface concern. Coordination work continues until the breakdown moves to `ACCEPTED`. | ||
| 3. **Implementation has shipped** and the breakdown is ready to move to `COMPLETE`. The completion-communication checklist is the closing ritual. | ||
|
|
||
| Don't reach for this skill while the breakdown is still `IN PROGRESS` — cross-team review on a half-drafted doc wastes the affected teams' time and yields signoffs nobody trusts. |
Contributor
There was a problem hiding this comment.
|
|
||
| When the `bitwarden-delivery-tools` plugin is installed, additional planning and coordination skills are available: | ||
|
|
||
| - **Before starting non-trivial implementation work** → activate `Skill(writing-tech-breakdowns)` to draft or update the team's Tech Breakdown for the change (Parts 1, 2, 4, 5, 6 of the Bitwarden template — problem framing, scope checklist, specification artifacts, open questions, AI context) so design decisions are captured before code lands. |
Contributor
There was a problem hiding this comment.
💭 This feels out of place. I think it should be part of the funnel workflow, or left up to the user. Not baked into this agent as default behavior. What I don't want, as a user, is for Claude to think the work I just assigned it needs extra technical breakdown when I don't want or need it to do that. If I, as a user, want this agent to produce a tech-breakdown I would instruct it to do so as part of my workflow.
| - Team-level problem → stay in-team and apply `Skill(architecting-solutions)`. | ||
| - Initiative epic (from a shepherd, or one you're shepherding) → invoke `Skill(navigating-the-initiative-funnel)` (lives in `bitwarden-delivery-tools`). | ||
| - Transition in either direction (your team taking on work, or handing off framework, tooling, or patterns it built) → invoke `Skill(running-work-transitions)` (lives in `bitwarden-delivery-tools`). | ||
| - Drafting or updating the Tech Breakdown for the team's epic (problem framing, scope checklist, specification artifacts, status lifecycle) → invoke `Skill(writing-tech-breakdowns)` (lives in `bitwarden-delivery-tools`); chain into `Skill(coordinating-cross-team-breakdown)` once the doc reaches PROPOSED and needs cross-team signoffs. |
Contributor
There was a problem hiding this comment.
💭 Along the lines of my other comment in the engineer agent, "chain into coordinating-cross-team-breakdown" feels like forcing initiative funnel workflow as the default agent behavior instead of behavior only when participating in the funnel workflow.
The purpose of this agent is blurring to me. Is it to analyze requirements and produce a tech breakdown, or to follow the initiative funnel steps? Statements like "For most initiatives you are not the shepherd" are counter-intuitive. If the agent isn't commonly part of this workflow why is it mentioned here? I would expect the workflow to express how the agent behaves when working within it, not the other way around.
Another way to think about it, is like traditional dependency injection. Functions (skills and agents) should be provided the things (instruction) they need to operate within a specific context, not reach upwards or derive that context themselves.
| @@ -0,0 +1,205 @@ | |||
| --- | |||
| name: writing-tech-breakdowns | |||
| description: Drafting the engineering content of a Bitwarden Tech Breakdown — Parts 1, 2, 4, 5, 6 of the standard template (problem overview, breakdown scope checklist, specification artifacts, open questions, AI context) plus the IN PLANNING → IN PROGRESS → PROPOSED → ACCEPTED → COMPLETE status lifecycle. Use when starting a new tech breakdown, filling in the scope checklist (DB/API/UI/SDK/services/hosting/feature flags/security/testing/tech debt/dev environment), drafting specification child pages, capturing open questions, or moving the doc between status states. Pair with `coordinating-cross-team-breakdown` for Part 3 signoffs and completion communication. | |||
Contributor
There was a problem hiding this comment.
♻️ Can we trim description down to focus on the general purpose and leverage when_to_use for trigger examples? Something like...
description: Draft engineering work breakdowns following the Bitwarden Tech Breakdown template.
when_to_use: Breaking down functional requirements into technical implementation plans. Trigger on terms like, "break down ticket x", "analyze requirements in document y".In my experience, since this is part of a larger workflow, you'll get better trigger reliability if this is referenced explicitly as a "next step" in said workflow(s). Verbose description and when_to_use get dropped when tool context limits are nearing, which can negatively impact implicit trigger rates. Keeping them both lean ensures we get the best of both worlds.
| @@ -0,0 +1,205 @@ | |||
| --- | |||
| name: writing-tech-breakdowns | |||
| description: Drafting the engineering content of a Bitwarden Tech Breakdown — Parts 1, 2, 4, 5, 6 of the standard template (problem overview, breakdown scope checklist, specification artifacts, open questions, AI context) plus the IN PLANNING → IN PROGRESS → PROPOSED → ACCEPTED → COMPLETE status lifecycle. Use when starting a new tech breakdown, filling in the scope checklist (DB/API/UI/SDK/services/hosting/feature flags/security/testing/tech debt/dev environment), drafting specification child pages, capturing open questions, or moving the doc between status states. Pair with `coordinating-cross-team-breakdown` for Part 3 signoffs and completion communication. | |||
Contributor
There was a problem hiding this comment.
⛏️ "Pair with..." reads like instruction that should be in the skill's body and/or in the coordinating-cross-team-breakdown skill's when_to_use field, not this skill's description.
Address SaintPatrck's review on PR #118: the consuming agents shouldn't pre-commit to invoking the new Tech Breakdown skills as default behavior. Skills are workflow-invoked tools, not self-injecting defaults. Changes: - `coordinating-cross-team-breakdown/SKILL.md` — remove "When to Reach for This Skill" section. By the time the skill is read, it's already been invoked; meta-text about when (not) to invoke it doesn't serve the user. Aligns with `navigating-the-initiative-funnel` and `running-work-transitions`, neither of which has a when-to-invoke section. - `writing-tech-breakdowns/SKILL.md:3` — trim description from ~620 chars to ~330. Drop Parts/checklist enumerations and the trailing "Pair with..." pointer (instruction belongs in the body, not in the trigger surface). Per Patrick: verbose descriptions get dropped when context tightens, hurting trigger reliability. - `coordinating-cross-team-breakdown/SKILL.md:3` — symmetric trim from ~720 chars to ~280. - `navigating-the-initiative-funnel/SKILL.md:50` — add `IN PROGRESS` to the lifecycle string in the Phase 4 paragraph so it matches the body and sibling docs (bot-suggested fix). - `bitwarden-software-engineer.md` — remove the entire "Planning and Coordination" section. Skills are discoverable via their descriptions; explicit listing turns optional capability into "by default, do this." Implementation work should not pre-commit to drafting a Tech Breakdown — that's a user-driven workflow decision. - `bitwarden-tech-lead/AGENT.md` — remove the Orientation bullet that said "Drafting or updating the Tech Breakdown for the team's epic ... chain into `Skill(coordinating-cross-team-breakdown)`...". Same default-behavior critique. The Cross-Plugin Integration listing remains because it documents what's available, not what to dispatch. Version impact: - `bitwarden-software-engineer` reverted 0.5.0 → 0.4.2. With Planning and Coordination removed, the keywords additions are also reverted — no behavior change in this PR for that plugin. - `bitwarden-tech-lead` 2.2.0 changelog entry rewritten to reflect that the change is documentation of available skills in the Cross-Plugin Integration section, not default-behavior dispatch. - `bitwarden-delivery-tools` 1.2.0 unchanged — the changelog already framed the new skills as plugin additions, not as wiring into consuming agents.
Realign the bitwarden-tech-lead agent with the canonical Team Tech Lead role from Confluence page 214041059, addressing SaintPatrck's critique that the agent had become defined by its participation in the Software Initiative Funnel rather than by what a tech lead actually is. The canonical role has three relationships: - **To the team:** primary technical resource; knows the codebase or knows where to find answers; undertakes forward-thinking investigative work to remove current and future roadblocks; serves as conduit for cross-team decisions affecting how the team builds; has authority (backed by the EM) to enforce technical recommendations via PR reviews. - **To peer tech leads:** maintains an open channel for architecture, design, and implementation discussions that challenge standard practices; advocates for groundbreaking changes the team's work introduces. - **To the EM:** primary point of contact for initial scoping of backlog work and design sessions; sounding board for technical questions; partners on Tech Debt prioritization and sprint planning. Changes: - Frontmatter description rewritten around the three-relationship framing. Use cases enumerate the canonical responsibilities (in-team planning, EM partnership, cross-team conduit, upstream- pattern recognition) rather than funnel-specific workflows. - Two of four `<example>` blocks replaced: the "receiving a shepherded epic" and "small-scope initiative I could shepherd" examples were removed, replaced with an EM-partnership scoping example and a cross-team-conduit example. Those funnel-specific capabilities are still present via the relevant skills but no longer define the agent. - Body intro rewritten to lead with the three relationships. A new paragraph makes the architectural principle explicit: "those workflows orchestrate your participation; you do not orchestrate them." When a workflow needs the tech lead, the workflow brings context and tells the agent what's expected. - "For most initiatives you are not the shepherd" decision tree removed. That was the source of Patrick's "purpose is blurring" concern — the agent should know what a tech lead is before knowing when a tech lead is not a shepherd. - Orientation block reduced to the two genuinely tech-lead-owned skills (architecting-solutions, contributing-to-technical-strategy). Workflow-classification bullets (funnel epic, transition) removed — those workflows bring their own dispatch context. - Cross-Plugin Integration framing tightened. Skills are now listed as "available across plugins, agent-neutral by design — a calling workflow (or the user) decides when to invoke them" rather than "load-bearing for any work that crosses teams." - plugin.json and marketplace.json descriptions rewritten to match. Version: 2.2.0 → 2.3.0 (minor — agent identity shift, no removed capabilities). Note for follow-up: Patrick's broader architectural direction is that workflows should be defined as orchestration skills that explicitly direct agent participation (a "plan-implement-review" example was referenced). The agent redefinition in this commit is a prerequisite to that pattern — agents need stable, role-grounded identities before workflow skills can compose them. The orchestration- skill work itself is out of scope here.
Trim verbose bullets and drop the literal Confluence page-ID reference; the canonical role description lives in the agent file itself.
SaintPatrck
reviewed
May 19, 2026
Contributor
SaintPatrck
left a comment
SaintPatrck
left a comment
There was a problem hiding this comment.
Thanks for clearing some of that up. Left one question about the additional version bump.
| "version": "2.1.1", | ||
| "description": "Tech lead agent for a Bitwarden product team. Architects solutions holistically with the architecture group, dispatches to delivery-lifecycle skills (initiative funnel, work transitions) when work crosses teams, and surfaces team patterns to the Technical Strategy Ideas backlog." | ||
| "version": "2.3.0", | ||
| "description": "Tech lead agent for a Bitwarden product team. The team's primary technical resource — architects solutions in the team's domain, partners with the EM on scoping and backlog, partners with peer tech leads on cross-team architecture, and serves as the team's conduit for cross-team technical decisions." |
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), | ||
| and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). | ||
|
|
||
| ## [2.3.0] - 2026-05-19 |
Contributor
There was a problem hiding this comment.
❓ Is the additional version bump intentional?
Contributor
Author
There was a problem hiding this comment.
Yes, although perhaps moot. I wanted to show that the agent redefinition came in a subsequent minor change. It's one PR so 🤷 but if someone's reading it in a moment it could help.
Contributor
There was a problem hiding this comment.
Makes sense, and sounds good.
SaintPatrck
approved these changes
May 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🎟️ Tracking
Engineering management published a standardized Tech Breakdown Template (Confluence page
2920349776, currently version 16) as the canonical artifact for capturing a feature's technical design before implementation. This PR brings that template into Claude Code so the tech-lead and software-engineer agents reach for a consistent workflow instead of re-deriving the template from memory.📔 Objective
Add two new agent-neutral skills to
bitwarden-delivery-toolsand wire both thebitwarden-tech-leadandbitwarden-software-engineeragents to use them:writing-tech-breakdowns— drafts the engineering content of the breakdown (Parts 1, 2, 4, 5, 6 — problem overview, scope checklist for DB/API/UI/SDK/services/hosting/feature flags/security/testing/tech debt/dev environment, specification artifacts, open questions, AI context) plus theIN PLANNING → PROPOSED → ACCEPTED → COMPLETEstatus lifecycle.coordinating-cross-team-breakdown— Part 3 signoff table, the cross-team checklist (mobile changes, components outside the team's domain, dependencies on other teams' services, APIs built for other teams), and the completion-communication checklist (post to#team-eng-tech-breakdowns, contact QA, contact refinement facilitator, verify all signoffs).Both skills follow the established lifecycle-skill pattern in this plugin: SKILL.md describes the workflow, and the canonical template is fetched on demand via
get_confluence_pageagainst page2920349776rather than being forked into the repo. This matchesnavigating-the-initiative-funnelandrunning-work-transitionsand avoids drift from a Confluence page that's already on version 16.Funnel integration (bidirectional)
Both new skills explicitly invoke
Skill(navigating-the-initiative-funnel)as a load-bearing first step when the breakdown sits under a BW Initiative — so the breakdown process pulls the shepherd, the affected-teams list, sibling teams' epics, and the architecture plan from the funnel rather than reconstructing them. The funnel skill is updated reciprocally to point at the two new skills at Phase 4 (Scoping & Commitment) and in its Related block.Agent updates
bitwarden-tech-lead/AGENT.md— new Orientation bullet dispatches toSkill(writing-tech-breakdowns)andSkill(coordinating-cross-team-breakdown)for Tech Breakdown work; the delivery-lifecycle line in Cross-Plugin Integration is extended to list both new skills alongside the existing funnel and work-transitions skills.bitwarden-software-engineer.md— new "Planning and Coordination" section, parallel in shape to the existing "Security-Aware Development" section, directing the agent to draft a Tech Breakdown before non-trivial implementation work and to run the cross-team coordination skill when the breakdown affects other teams. Marked optional ("if the plugin is unavailable, proceed with your standard workflow") to match the existing cross-plugin convention.Version bumps
bitwarden-delivery-tools1.1.0 → 1.2.0 (MINOR — two new skills, funnel skill updated, plugin description and keywords extended)bitwarden-tech-lead2.1.0 → 2.2.0 (MINOR — agent dispatch additions)bitwarden-software-engineer0.4.1 → 0.5.0 (MINOR — new "Planning and Coordination" section)All three CHANGELOG.md files updated; marketplace.json and root README catalog updated by the bump script; delivery-tools README's skills table gained a new "Technical design" section with both new skills and two new usage examples.
Notes for reviewers
writing-tech-breakdownsexplicitly names both engineer-led and tech-lead-led patterns.Skill(architecting-solutions)(which lives inbitwarden-tech-lead) are qualified with the plugin name to avoid dead references when the software-engineer agent reaches for these skills.writing-tech-breakdowns; the coordination skill points back at it rather than re-encoding the state machine.npm run lintclean,validate-plugin-structure.shclean for all three plugins,validate-marketplace.shclean. Theplugin-dev:plugin-validatorandplugin-dev:skill-revieweragents were run; reviewer suggestions on cross-plugin qualifiers and agent-neutral tone were applied.signoffswas added to.cspell.json(the singularsignoffwas already accepted by dictionary fallthrough; the plural was flagged).