Reframe tech-lead/software-engineer as engineering-shaping/engineering-building

[trmartin4]

Objective

Two role-named agents (bitwarden-tech-lead and bitwarden-software-engineer) carved the engineer's day along a seniority axis ("tech lead role" vs. "engineer role"). In practice, the same engineer slides between shaping (discovery, scoping, architectural reasoning, cross-team coordination, tech-breakdown drafting) and building (implementing stories, reviewing PRs, preparing commits, shipping) within a single day. The role-based split forced users to pick a hat that didn't match what they were actually doing.

This PR reframes the two plugins along activity mode instead of role:

• bitwarden-tech-lead → bitwarden-engineering-shaping (the work of forming workable shape from vague intent)
• bitwarden-software-engineer → bitwarden-engineering-building (the work of constructing the result)

Both are for any engineer; the split is by what you're doing, not what title you hold. The skills (architecting-solutions, contributing-to-technical-strategy, the delivery-tools workflow skills, etc.) stay agent-neutral and remain invocable from either agent.

Cross-plugin reference updates

• bitwarden-code-review/skills/performing-multi-agent-code-review/SKILL.md — references bitwarden-tech-lead:bitwarden-tech-lead subagent (architecture review subagent). Update to bitwarden-engineering-shaping:bitwarden-engineering-shaping. PATCH-bump bitwarden-code-review.
• bitwarden-designer/README.md and bitwarden-designer/agents/AGENT.md — multiple references to bitwarden-tech-lead as the engineering counterpart. Update to bitwarden-engineering-shaping. PATCH-bump bitwarden-designer.
• bitwarden-delivery-tools/skills/writing-tech-breakdowns/SKILL.md — references Skill(architecting-solutions) "in the bitwarden-tech-lead plugin" (twice). Update both to "in the bitwarden-engineering-shaping plugin." Already at 2.0.0 unreleased on parent branch; either fold into 2.0.0 or PATCH-bump to 2.0.1.
• bitwarden-delivery-tools/skills/choosing-collaboration-model/SKILL.md — single reference to bitwarden-tech-lead in the Related skills block. Update. Same versioning question as above.
• bitwarden-software-engineer/README.md (now bitwarden-engineering-building/README.md) — internal reference to bitwarden-tech-lead as "the next rung on the career ladder." Rewrite this line to reflect the activity-mode framing (no longer a career-ladder relationship; both agents are for any engineer).

Versioning

• bitwarden-engineering-shaping: 3.0.0 (was bitwarden-tech-lead@2.3.1) — MAJOR because the rename is a breaking change for any caller invoking Agent(bitwarden-tech-lead) by name.
• bitwarden-engineering-building: 2.0.0 (was bitwarden-software-engineer@1.0.0) — MAJOR for the same reason.
• Cross-plugin reference updates will be PATCH bumps on the affected plugins (bitwarden-code-review, bitwarden-designer, bitwarden-delivery-tools).

[github-actions]

Plugin Validation Summary

PR: #138 — plugin renames bitwarden-software-engineer → bitwarden-engineering-building (v2.0.0) and bitwarden-tech-lead → bitwarden-engineering-shaping (v3.0.0), with agent body rewrites to activity-mode framing.

Overall: PASS with documentation-drift warnings. No critical or major errors, no security issues. The structural rename is correct and consistent across plugin.json, agent frontmatter, marketplace.json, root README, CHANGELOGs, and directory layout. The two plugin-level README files still carry pre-rename content and should be updated before the PR exits draft.

---

Critical (0)

None.

Major (0)

None.

Minor / Warnings — must fix before exiting draft

These are documentation-drift issues the PR description and CHANGELOG entries explicitly anticipate ("body rewrite … lands in subsequent commits on this PR"). They block users from installing or invoking the renamed plugins with the commands shown in the docs.

plugins/bitwarden-engineering-building/README.md still describes the old plugin throughout:

• Line 1 — title # Bitwarden Software Engineer Plugin should become # Bitwarden Engineering Building Plugin.
• Line 5 — Overview paragraph frames the plugin as the "Software Engineer" role rather than building-mode activity.
• Line 11 — Agent table row uses old name bitwarden-software-engineer; should be bitwarden-engineering-building.
• Line 25 — "Related Plugins" references bitwarden-tech-lead (should be bitwarden-engineering-shaping) and calls it "the next rung on the career ladder," which directly contradicts the activity-mode framing the rename introduces ("same engineer, different mode — not different seniority").
• Line 30 — Install command /plugin install bitwarden-software-engineer@bitwarden-marketplace is broken; the plugin is now bitwarden-engineering-building.
• Lines 36, 40 — Usage examples invoke bitwarden-software-engineer agent; that agent name no longer exists.

plugins/bitwarden-engineering-shaping/README.md still describes the old plugin throughout:

• Line 1 — title # Bitwarden Tech Lead Plugin should become # Bitwarden Engineering Shaping Plugin.
• Lines 5, 7 — Overview and second paragraph frame the plugin as the "tech lead" role rather than shaping-mode activity.
• Line 13 — Agent table row uses old name bitwarden-tech-lead.
• Line 29 — Cross-plugin row references bitwarden-software-engineer; should be bitwarden-engineering-building.
• Line 36 — Related-plugins description says "tech-lead role"; should reflect shaping-mode framing.
• Line 41 — Install command /plugin install bitwarden-tech-lead@bitwarden-marketplace is broken.
• Lines 44–51 — "Upgrading from bitwarden-architect" section is now two renames stale (architect → tech-lead → engineering-shaping). Replace with an "Upgrading from bitwarden-tech-lead" section.

Minor / Warnings — optional polish

plugins/bitwarden-engineering-shaping/skills/contributing-to-technical-strategy/SKILL.md — persistent "tech lead" wording survives the rename:

• Line 7 — "The tech lead is the role that spans the vertical…"
• Line 38 — "tech leads absolutely can and should contribute ideas…"
• Line 71 — "A tech lead usually won't create the BW Initiative…"
• Line 81 — "This is where tech-lead-specific work lives."

These read as describing the org role rather than the agent persona (consistent with the file's similar treatment of "shepherd"), so they are not strictly errors. If the rename intends fully role-neutral skill bodies, replace with mode-language ("the engineer shaping the work" / "the team's shaping role"). Otherwise, accept as-is.

plugins/bitwarden-engineering-shaping/skills/contributing-to-technical-strategy/SKILL.md line 3 — description is ~620 chars, above the ~500-char soft target. Reads cleanly; tightening is optional.

Both SKILL.md files line 4 — allowed-tools frontmatter key is not formally honored on skills (it's an agent/command convention). Currently harmless but easy to mistake for an enforced restriction. Optional: remove, or treat as documentation of expected tool availability.

Both CHANGELOG.md entries (bitwarden-engineering-building line 12; bitwarden-engineering-shaping line 12) — text says "the agent body rewrite … lands in subsequent commits on this PR before the draft moves out of draft." That body rewrite has already partially landed in the committed AGENT.md files (activity-mode framing is in both frontmatter description and system-prompt body). Either reconcile the CHANGELOG wording, or treat the lingering README drift as the remaining work the wording anticipated.

---

What was validated

Plugin structure (plugin-validator):

• Both .claude-plugin/plugin.json files: valid JSON, name matches directory, semver versions (2.0.0 / 3.0.0), required fields present.
• Both agents/AGENT.md files: valid YAML frontmatter, name matches plugin name and is 31–32 chars lowercase + hyphens, four <example> blocks each, valid model: opus, valid colors (blue, cyan), substantive system prompt (40+ lines body).
• Both CHANGELOG.md files: Keep a Changelog format, top entry matches plugin.json version, BREAKING change properly categorized.
• Shaping plugin's two skills: valid frontmatter (name, description, allowed-tools), name matches directory, substantive bodies.
• Both deleted directories (plugins/bitwarden-software-engineer/, plugins/bitwarden-tech-lead/) confirmed absent.
• Root .claude-plugin/marketplace.json contains both new plugin entries with matching versions; neither old name appears.

Skill review (skill-reviewer):

• architecting-solutions/SKILL.md: 1,289 words (inside 1,000–3,000 target), seven well-organized H2 sections, imperative writing style, Bitwarden-specific anchors (V±2, dual data-access, self-hosted, libs/common, src/Core). No references/ or examples/ subdirectories needed at current size. PASS.
• contributing-to-technical-strategy/SKILL.md: 1,817 words (inside target), three-act structure (top/middle/bottom of funnel) plus Common Mistakes and Reference. PASS, with the "tech lead" wording note above.
• Cross-skill Skill(name) references are intentional cross-plugin dispatch calls, not required to exist as local files.

Security (reviewing-claude-config + manual scan):

• No committed secrets, API keys, tokens, or passwords in any changed file.
• All URLs go to bitwarden-owned infrastructure (github.com/bitwarden, bitwarden.atlassian.net, contributing.bitwarden.com) or standards references (keepachangelog.com, semver.org); grep for non-bitwarden URLs returned only the four github.com/bitwarden entries in the two plugin.json files.
• Matches for secret-related keywords were limited to skill names (detecting-secrets), documentation about security mindset, and a sample user prompt about "org-scoped tokens" — no actual credentials.
• Agent tool access is appropriately scoped:
  • bitwarden-engineering-building: Read, Write, Edit, Bash, Glob, Grep, Skill — Bash + Edit are powerful but appropriate for a code-implementation agent.
  • bitwarden-engineering-shaping: Read, Write, Glob, Grep, Skill — deliberately omits Bash and Edit, correctly scoping a planning/architecture agent away from code modification.
• Skill allowed-tools enumerate read-only Atlassian MCP tools (get_issue, search_issues, get_confluence_page, etc.) — appropriately read-only and scoped.
• No settings.json or settings.local.json changes in this PR.
• YAML frontmatter parses cleanly on all four agent/skill files.

[theMickster]

I am struggling to see why the name change is a now priority compared to building the Claude tooling leveraged by these agents. Pure cost-benefit for me. I don't really mind what the agents are called, but more so that they have the skills, rules, etc. to aiding engineering. I think that's where we need to be investing our efforts.

I could also be missing a bigger picture missing in the Claude generated description. How does the change help us achieve the bigger VFO for AI + Engineering excellence? What planned Claude tooling enhancements will directly benefit from this change that I don't see?