feat: add bitwarden-shepherd plugin for Software Initiative Funnel#116
Merged
Conversation
Introduces a Staff+ initiative-shepherd agent as the symmetric counterpart to bitwarden-tech-lead. Where tech-lead represents one team inside an initiative, shepherd owns the initiative across teams — running the architectural assessment, building the PoC, drafting the ADR, handing epics off to teams, coordinating cross-team consistency during implementation, and curating the upstream Technical Strategy Ideas backlog from the Architecture-group side. Ships with the bitwarden-shepherd agent and six skills: - shepherding-an-initiative (umbrella playbook for all five funnel phases) - running-an-architectural-assessment (Phase 2 deep dive) - running-a-proof-of-concept (Phase 3 deep dive) - scoping-and-handing-off-to-teams (Phase 4, composes running-work-transitions) - coordinating-implementation-across-teams (Phase 5, composes running-work-transitions) - curating-the-strategy-ideas-backlog (Architecture-curator side of TSI) Funnel-mechanics and work-transition content is not duplicated — those agent-neutral skills live in bitwarden-delivery-tools and are composed by the shepherd skills (mirroring how bitwarden-tech-lead composes them). Also bumps bitwarden-tech-lead 2.1.0 → 2.1.1 with a Related Plugins pointer to bitwarden-shepherd so the two siblings are mutually discoverable, and registers the new plugin in the root README catalog and marketplace.json.
…y championing The v1.0.0 framing led with funnel mechanics — "owns a single cross-cutting initiative end-to-end" — and treated the upstream TSI work as a secondary curator responsibility. The Confluence docs frame the role differently: the TSI page describes a Shepherding Model where every active idea has a Primary Owner who "drives the idea through the pipeline" and "shepherds the transition to the funnel." The shepherd is genuinely a two-act role. Rebias the persona to lead with championing a thesis about what Bitwarden should change; the funnel mechanics are how the thesis becomes reality. Adds: - championing-a-strategy-idea skill — Primary-Owner playbook for the pre-funnel arc: pairing with a peer reviewer, completing the Stakeholder & Engagement Map (with friction named honestly), refining the Problem Statement through Research, presenting at Architecture Council, earning intake at quarterly prioritization, transitioning to the BW Initiative. Also the canonical home for the Adoption Retrospective at Implementation handoff (influence-effectiveness retro — Primary Owner + Peer Reviewer, distinct from the funnel's execution retro covered in coordinating-implementation-across-teams). Reframes: - AGENT.md description and system prompt now lead with "champion of Bitwarden's technical strategy" and the two-act arc; the ownership-division block and failure modes are preserved. A third failure mode — "technically sound proposals that stall at adoption" — is added because it's the championing-act equivalent. - AGENT.md scope list and orientation now lead with strategy-championing entries and add a "locate yourself in the two acts" first orientation step. - Skills frontmatter and orientation dispatch reorder the seven skills to follow the persona's natural arc: champion -> umbrella -> four phase deep dives -> curator/peer-reviewer. - shepherding-an-initiative opening clarifies that the umbrella picks up after Architecture has approved an idea for funnel intake; pre-funnel work lives in championing-a-strategy-idea. - curating-the-strategy-ideas-backlog is retitled in framing to the Peer-Reviewer-and-portfolio-curator side of the same Shepherding Model. Its description, two-roles section, Adoption Retrospective section, and common-mistakes entry now point to championing-a-strategy-idea for the Primary-Owner playbook. - README, plugin.json, marketplace.json, and root README catalog descriptions all reframed to lead with the strategy-champion framing. The v1.0.0 changelog entry is rewritten in place rather than bumping version, since this branch is unmerged pre-release iteration.
🤖 Bitwarden Claude Code ReviewOverall Assessment: APPROVE Documentation-only PR adding the new Code Review DetailsNo findings. All previously-raised review issues have been addressed:
Latest commit (
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
…erns Two corrections grounded in [Documentation Patterns][docs-patterns]: 1. ADRs live in the centralized `bitwarden/contributing-docs` repository under `docs/architecture/adr/` (rendered at contributing.bitwarden.com/architecture/adr/) — not in per-repo ADR directories. The earlier "appropriate codebase's ADR directory" phrasing in running-a-proof-of-concept and shepherding-an-initiative was wrong; corrected both. 2. The PoC is the moment to establish documentation patterns for the new framework — both close-to-code (framework README, folder notes, JSDoc/XML/rustdoc, CLAUDE.md updates) and centralized (ADR, migration guides, contributing-guide changes in contributing-docs). Without this, the PoC PR is far less legible at Phase 4 handoff and during Phase 5 adoption. Changes: - running-a-proof-of-concept: corrected ADR location with a concrete reference to ADR 0020 as an example; added a new "Establishing Documentation Patterns" section covering close-to-code vs. centralized homes, what the PoC ships in each, and tech-stack-specific guidance. - shepherding-an-initiative: corrected Phase 3 ADR location; added a close-to-code documentation bullet pointing to the deep skill. - coordinating-implementation-across-teams: reframed "Managing Documentation" to anchor on the two homes — close-to-code (README, folder notes, inline docs, CLAUDE.md updates alongside team code) and centralized (ADR finalization, migration guide, contributing-guide, runbooks in contributing-docs). - Added Documentation Patterns to the Reference section of both PoC and coordinating skills. - .cspell.json: added rustdoc. - CHANGELOG: extended the still-unreleased 1.0.0 entry to note the grounded documentation framing. [docs-patterns]: https://bitwarden.atlassian.net/wiki/spaces/EN/pages/1774977070/Documentation+Patterns
Plugin Validation Report — PR #116Validated two plugins ( Overall result: PASS with minor observations. No critical or blocking issues found. No secrets, credentials, or unsafe permissions detected. 1. Plugin Structure Validation
|
| Skill | Words | Desc len |
|---|---|---|
| championing-a-strategy-idea | 2,416 | 150 |
| coordinating-implementation-across-teams | 2,396 | 175 |
| curating-the-strategy-ideas-backlog | 1,907 | 150 |
| running-a-proof-of-concept | 2,056 | 121 |
| running-an-architectural-assessment | 1,513 | 90 |
| scoping-and-handing-off-to-teams | 1,952 | 144 |
| shepherding-an-initiative | 1,964 | 149 |
Minor observations (should fix, non-blocking)
-
when_to_usefrontmatter field is unique to this plugin and not part of the documented SKILL.md schema. All 7 shepherd skills place real triggering phrases (e.g.,"I'm Primary Owner on ARCH-…","Architecture Council prep") inwhen_to_userather thandescription. Because the runtime selects skills based onname+description, these phrase-level triggers are not reaching the dispatcher.- Remediation: fold the most valuable trigger phrases into
description(keep total length short — the recent commit0a0bf67shrank these intentionally to protect the listing budget). Suggested shape:<one-line role>. Use when <condition>. Triggers: "<phrase>". Not for <X>.After folding, either keepwhen_to_useas project-local documentation or remove it. - Note:
allowed-toolsin SKILL.md is a marketplace-wide convention (used in 19 SKILL.md files across the repo) — leave as-is for consistency.
- Remediation: fold the most valuable trigger phrases into
-
Trigger collision between
coordinating-implementation-across-teamsandchampioning-a-strategy-idea. Both reference "retrospective" triggers (Adoption Retrospective vs. funnel/Implementation retrospective). Risk of misrouting.- Remediation: rename the execution-side trigger in
coordinating-implementation-across-teams/SKILL.mdto"end-of-Implementation retrospective"or"funnel retrospective".
- Remediation: rename the execution-side trigger in
-
Generic
"handoff meeting"trigger inscoping-and-handing-off-to-teams/SKILL.mdmay collide withrunning-work-transitionsinbitwarden-delivery-tools.- Remediation: tighten to
"Phase 4 handoff"or"initiative handoff to teams".
- Remediation: tighten to
-
No progressive-disclosure structure (no
references/,examples/,scripts/subdirs). At current sizes (1.5K–2.4K words) this is fine; would become Major if any skill grows past ~3,000 words. -
running-an-architectural-assessment/SKILL.mdhas the leanest description (90 chars). Acceptable, but could grow modestly if trigger phrases are folded in.
Strengths
- Cross-plugin integration (delivery-tools, tech-lead, security-engineer, atlassian-tools) is explicit and well-documented.
- Each skill ends with a "Common Mistakes" section grounded in real failure modes.
shepherding-an-initiativeumbrella skill has a high-value time/effort capacity-planning table.scoping-and-handing-off-to-teamsleads with "The Anti-Pattern to Reject First" — directly addresses the highest-risk failure mode.
3. Security Validation
Scanned all 15 changed files for credential patterns (api_key, secret, password, token, bearer with 16+ char values) — no matches.
- No committed secrets, API keys, tokens, or hardcoded credentials.
- No
settings.json/settings.local.jsonchanges in this PR — no permission scoping or auto-approval concerns. - No hooks, no scripts, no MCP server declarations — no command execution surface to review.
- All external URLs point to legitimate Bitwarden Atlassian,
contributing.bitwarden.com, orgithub.com/bitwardenhosts. - YAML frontmatter is valid across all 9 changed
.mdfiles with frontmatter (1 AGENT.md + 7 SKILL.md in shepherd, 1 AGENT.md in tech-lead). - No prompt-injection-style instructions in agent/skill content — all guidance is appropriately scoped to plugin orchestration.
Summary
| Check | Result |
|---|---|
bitwarden-shepherd structure |
PASS |
bitwarden-tech-lead structure |
PASS |
| Marketplace.json consistency | PASS (both plugins) |
| CHANGELOG format & version bump | PASS (both plugins) |
| Agent frontmatter | PASS (both agents) |
| Skill frontmatter | PASS (all 7 shepherd skills) |
| Cross-skill references | PASS |
| Security scan (secrets/credentials) | CLEAN |
| Permission/hook safety | N/A (no settings or hooks changed) |
Errors (must fix): 0
Warnings (should fix): 3 — all in shepherd skills, all about trigger phrasing/dispatch precision (items 1–3 above)
Both plugins are ready to merge. The skill-trigger refinements are recommended polish but do not block the PR.
…findings Two changes from validator findings in PR #116 (see comment 4441026950): 1. Both agent descriptions now include four `<example>` blocks following Anthropic's documented standard for agent description fields. This gives the orchestrator concrete triggering scenarios rather than prose alone, which is the load-bearing signal for routing accuracy. Adopting it in both opus-level boundary agents (shepherd and tech-lead) keeps the team-vs-shepherd routing symmetry honest. 2. The scoping-and-handing-off-to-teams skill had a ~135-line `## What You Produce` H2 with 8 numbered H3 deliverables nested inside. Replaced with a short intro listing the 8 artifacts plus each promoted to its own H2 — cleaner TOC, easier progressive scanning, no content change. Tech-lead's example-block addition is folded into the existing 2.1.1 changelog entry rather than bumping a new version, since the change is a description refinement on top of the not-yet-released 2.1.1. cspell: added `touchpoint` (singular form; `touchpoints` was already in the dictionary). Validator findings deferred to follow-up work (with rationale): adding `license` field is a marketplace-wide convention question, not a shepherd-specific one; trimming long skill descriptions would erode the trigger discrimination that distinguishes championing- vs. curating-strategy-ideas-backlog; restructuring the explicit `"agents"` manifest field is not actually inconsistent with this marketplace (conventions are split three ways); adding `examples/` template skeletons is a separate body of work that should be framed as quick-reference scaffolds rather than Confluence duplicates.
Polish from the second-round plugin-validator findings on PR #116: - Agent color: purple → magenta (purple is outside the documented standard color set; magenta is the closest documented equivalent and stays visually distinct from tech-lead's cyan). - Tightened the two longest skill descriptions (championing-a-strategy-idea and curating-the-strategy-ideas-backlog) without losing trigger discrimination. - Deduplicated the Stakeholder & Engagement Map section: the canonical field-by-field detail now lives only in championing-a-strategy-idea (Primary-Owner side); the curator skill keeps a pointer plus its own Peer-Reviewer-specific guidance on what to push back on. - scoping-and-handing-off-to-teams: corrected "four" → "five" success factors in the Exit Criteria list. Also rewrote the v1.0.0 changelog to describe what the release is rather than the iteration history of getting there. Implementation minutiae (description char counts, color choices, off-by-one fixes) belong in PR commits, not in the public changelog.
theMickster
requested changes
May 14, 2026
theMickster
left a comment
theMickster
left a comment
Contributor
There was a problem hiding this comment.
I like the plugin's detailed breakdown by phase and am intrigued to see how the skills will support folks as they work through the funnel. My mind is seeing the plugin as the coach to help a Staff+ stay focused over many sessions that span weeks/months.
I am a little concerned about the amount of text in each skill. Feels like a lot to maintain and we may need to trim the fat (I tell Claude that a lot when it's helping me write skills, lol) over time keeping only the most succinct + direct instructions to prevent Claude from wandering.
Areas of minor improvement
I think we need to split up is the description frontmatter into description and when_to_use properties Building Claude Skills - Frontmatter. @SaintPatrck mentioned it in #121 and I have added that as well to newer skills. And when we do, I think we need to keep them succinct to avoid the following :
I would also like to see Claude + /skill-creator surgically trim those initial opening paragraphs that come right after the frontmatter. The body of each skill is very strong and carries the theme of each well, so to me they feel redundant. I have tended to prefer a cut to the chase motto when designing Claude skills.
The agent comment of mine is a topic for discussion, not necessarily a required change yet.
Reviewer feedback on #116: - Split each skill's single `description` field into `description` + `when_to_use` per the PR #121 / creating-pull-request pattern. Combined chars per skill: 935-1140 (cap 1536). - Trim the redundant 11-22 line preamble between the frontmatter and the first `## Heading` in every skill; the phase/time-budget/ composition content now lives in the frontmatter. The coordinating-implementation-across-teams skill preserves its funnel-doc "Think of the shepherd as..." mental-model quote since that's behavioral framing the rest of the skill relies on. - Remove the `## Scope: When To Use This Agent` section from AGENT.md. Dispatch criteria belong in the frontmatter `description` (which the dispatcher reads), not in the system prompt. The defer-to-bitwarden-tech-lead boundary folds into the existing paragraph that already mentions bitwarden-tech-lead. Net: -29 lines across 8 files. skill-reviewer agent run against all seven thinned skills reports clean pass.
theMickster
reviewed
May 18, 2026
theMickster
left a comment
theMickster
left a comment
Contributor
There was a problem hiding this comment.
👋🏼 Hi Matt,
Will you please take another spin through the description and the when_to_use frontmatter properties in the skills? It appears that we have grown those properties by taking what was in the initial overview of the skill and putting that into the frontmatter. I am concerned that if someone installs the plugin but doesn't use the skills often that they will quickly see their skill_listing_budget eaten away by just these few skills.
Thanks you!
Per Mick's review on #116, the previous refactor (ec46add) moved phase / time-budget / deliverable / composition prose out of the body and into description + when_to_use. That content doesn't aid dispatch — it's orienting context for a reader who already invoked the skill — so it shouldn't live in the listing budget that every session pays on load. Trim description and when_to_use to dispatch-relevant content only: - description: 1-line "what role/phase, what deliverable" - when_to_use: "Use when…" + 2-3 trigger phrases + 1 anti-trigger Restore the orienting prose (phase, time budget, deliverables, composition references) to the body opening above the first ## heading, where it loads on invocation rather than on session start. Combined description+when_to_use per skill: championing-a-strategy-idea 1100 → 399 shepherding-an-initiative 1055 → 421 running-an-architectural-assessment 935 → 375 running-a-proof-of-concept 1058 → 470 scoping-and-handing-off-to-teams 1140 → 477 coordinating-implementation-across-teams 1121 → 472 curating-the-strategy-ideas-backlog 1117 → 460 Cumulative listing budget: 7,526 → 3,074 chars (-59%).
theMickster
approved these changes
May 18, 2026
withinfocus
added a commit
that referenced
this pull request
May 19, 2026
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.
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
No Jira/GitHub issue — this is a self-initiated follow-up to #95 (
Tech lead agent skill development), which scopedbitwarden-tech-leadaround the team-side of an initiative and explicitly noted that funnel-mechanics skills live inbitwarden-delivery-toolsso "multiple agents (tech-lead, software-engineer, shepherds) can compose them." This PR ships that shepherd plugin.📔 Objective
Introduce
bitwarden-shepherdas the upstream counterpart tobitwarden-tech-lead. Where tech-lead represents a team inside an initiative, shepherd is the Staff+ engineer who champions a Technical Strategy Idea through Architecture's evaluation, into the Software Initiative Funnel, and across all five funnel phases to durable adoption.Persona framing. The agent leads with the strategy-champion role — holding a thesis about something Bitwarden should change — and frames the funnel mechanics as how that thesis becomes reality. The role spans two connected acts the Confluence docs already name:
Ships:
bitwarden-shepherdagent (opus, purple) with explicit shepherd-vs-team ownership boundaries and three named failure modes: writing the team's stories, drift across teams, and technically-sound proposals that stall at adoption.championing-a-strategy-idea— Primary-Owner playbook for the pre-funnel arc; canonical home for the Adoption Retrospective at Implementation handoff.shepherding-an-initiative— umbrella playbook for the five funnel phases.running-an-architectural-assessment(Phase 2).running-a-proof-of-concept(Phase 3) — includes the close-to-code vs. centralized documentation pattern guidance.scoping-and-handing-off-to-teams(Phase 4, composesrunning-work-transitions).coordinating-implementation-across-teams(Phase 5, composesrunning-work-transitions).curating-the-strategy-ideas-backlog— Peer-Reviewer and portfolio-curator side of the TSI Shepherding Model.Composition over duplication. Funnel-mechanics and work-transition content lives in
bitwarden-delivery-tools(added in #109). The shepherd skills compose those agent-neutral skills rather than restating them — same patternbitwarden-tech-leaduses.Documentation placement is grounded in canonical docs. ADRs live in the centralized
bitwarden/contributing-docsrepository underdocs/architecture/adr/(rendered atcontributing.bitwarden.com/architecture/adr/) — not per-repo. Close-to-code documentation (frameworkREADME.md, folder notes, JSDoc/XML/rustdoc, CLAUDE.md updates) ships alongside the code. The PoC and Implementation skills carry the deep guidance for both homes.Boundary with tech-lead. When work fits inside one team's domain or one adjacent team, the agent defers to
bitwarden-tech-lead, whose description already covers filling the shepherd role for smaller-scope initiatives.bitwarden-tech-leadis bumped 2.1.0 → 2.1.1 with a "Related plugins" pointer back to shepherd for mutual discoverability.Source grounding. Each skill anchors against the canonical Confluence docs and recommends fetching them via the atlassian MCP tool when full templates or entry/exit criteria are needed:
✅ Notes for reviewers
Pre-release iteration: the CHANGELOG
1.0.0entry was extended in place rather than adding subsequent versions, because the plugin hasn't been released yet.Validators run locally:
npm run lint(prettier + cspell),./scripts/validate-plugin-structure.sh bitwarden-shepherd,./scripts/validate-marketplace.sh,./scripts/validate-version-bump.sh origin/main bitwarden-shepherd bitwarden-tech-lead.Test plan
plugin-validatoragent run againstbitwarden-shepherd(frontmatter, manifest correctness, no hardcoded credentials)skill-revieweragent run against each new SKILL.md (description quality, trigger phrase specificity, length 1k–3k words target)claude-config-validator:reviewing-claude-configskill run across the new fileschampioning-a-strategy-idea, not the funnel umbrella.curating-the-strategy-ideas-backlog.shepherding-an-initiative(umbrella), which routes by phase.running-a-proof-of-conceptand reference to the centralizedcontributing-docsADR placement plus the close-to-code frameworkREADME.mdpattern.bitwarden-tech-lead.