feat: add bitwarden-shepherd plugin for Software Initiative Funnel#116
Open
withinfocus wants to merge 7 commits into
Open
feat: add bitwarden-shepherd plugin for Software Initiative Funnel#116withinfocus wants to merge 7 commits into
withinfocus wants to merge 7 commits into
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 Reviewed the new Code Review DetailsNo findings. |
![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 changed plugins ( Scope of validation
Critical issuesNone. Major issuesNone. Minor issues
|
| Skill | Words | Frontmatter | Body quality |
|---|---|---|---|
championing-a-strategy-idea |
2,539 | valid | strong: arc walkthrough, gates, retro, common mistakes |
coordinating-implementation-across-teams |
2,477 | valid | cadence-driven; anti-pattern about code review is clear |
curating-the-strategy-ideas-backlog |
2,007 | valid | defers Stakeholder Map to sibling skill — good progressive disclosure |
running-a-proof-of-concept |
2,070 | valid | unambiguous ADR-location guidance |
running-an-architectural-assessment |
1,538 | valid | Part A/B time split mirrors budget |
scoping-and-handing-off-to-teams |
1,990 | valid | leads with anti-pattern — strong pedagogy |
shepherding-an-initiative |
2,032 | valid | umbrella playbook dispatching to phase-deep skills |
- All
namefields match directory names. - All cross-references to sibling skills (
bitwarden-tech-lead,bitwarden-delivery-tools) resolve to existing skills. - Writing style is consistently imperative/infinitive throughout.
- Trigger surface is strong: descriptions name specific artifacts, phases, decision-makers, and explicit boundary calls against adjacent skills.
3. Security Validation — claude-config-validator (reviewing-claude-config)
PASS — no security issues found.
| Check | Result |
|---|---|
Committed settings.local.json |
N/A — not in change set |
| Hardcoded credentials / API keys / tokens / passwords | None found |
.env or credentials.json |
None present |
| Permission scoping in settings | N/A — no settings files in change set |
| Dangerous command auto-approvals | N/A — no settings files in change set |
| Agent tool scope | Both agents scope to Read, Write, Glob, Grep, Skill (no Bash, WebFetch, Edit, no wildcards) |
Skill allowed-tools scope |
All 7 shepherd skills restricted to Skill + read-only Atlassian MCP tools (no write/delete) |
| MCP HTTPS/WSS enforcement | N/A — no MCP server configs in change set |
| Prompt-injection vectors | None found; external references all point to Bitwarden-controlled domains |
| Cross-plugin failure modes | "STOP and alert the human" patterns used for missing dependencies — correct fail-safe |
Conclusion
The PR is in a release-ready state. Both plugins pass structural, frontmatter, changelog, version-consistency, and security validation. The 7 new shepherd skills are well-written, lean, and within target word counts. All minor issues are stylistic polish items that can be addressed in a future pass without blocking this 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
Contributor
theMickster
left a comment
theMickster
left a comment
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.
|
|
||
| You are not the tech lead for any of the implementing teams. The `bitwarden-tech-lead` plugin covers the team-side counterpart of this role. When something is purely inside one team's codebase boundary, defer to that team's tech lead. When a team-scope tech lead asks you to make a team-internal call, push it back to them — your authority is at the initiative scale and the strategy scale, not below. | ||
|
|
||
| ## Scope: When To Use This Agent |
Contributor
There was a problem hiding this comment.
💭 I appreciate the depth of detail the describes when to use the agent, but I'm unsure if this is the best location for these details. We have a strong description opening followed by several examples. I am unsure how a subagent invoked as the bitwarden-shepherd utilizes this information.
Maybe another way to say that is, what does a bitwarden-shepherd subagent do differently knowing when it's supposed to be used (which is essentially the section title)?
My initial sense is that the best home for this is outside the agent itself 🤔
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.