-
Notifications
You must be signed in to change notification settings - Fork 14
Move architecting-solutions from bitwarden-tech-lead to bitwarden-delivery-tools #160
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from 5 commits
e56d611
50aeb4a
f47de83
cfdf072
7e6278c
c7a4034
a3d9fbe
1a9ee58
e95a8da
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,14 +1,16 @@ | ||
| --- | ||
| name: architecting-solutions | ||
| description: Framework for architecting solutions inside a team's domain while staying coherent with Bitwarden's holistic architecture. Covers security mindset, blast radius assessment, architectural judgment, Bitwarden-specific constraints, working with the architecture group, and working with initiative shepherds. Use when planning a solution, reviewing architecture within a team's scope, assessing blast radius, evaluating trade-offs, or deciding whether a choice needs architecture-group input. | ||
| description: Framework for architecting solutions at the team level while staying coherent with Bitwarden's holistic architecture. Covers security mindset, blast radius assessment, architectural judgment, Bitwarden-specific constraints, and working with the architecture group. Use when planning a solution, reviewing architecture within a team's scope, assessing blast radius, evaluating trade-offs, or deciding whether a choice needs architecture-group input. | ||
| allowed-tools: Skill, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_comments, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_remote_links, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_issues, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_confluence_page, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_confluence_page_comments, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_confluence, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_confluence_cql | ||
| --- | ||
|
|
||
| This skill applies architectural judgment during team-level delivery work: scoping tickets, drafting breakdowns, evaluating trade-offs, and choosing between approaches. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ❓ How did adding this statement change Claude's behavior?
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You're right. It doesn't meaningfully change it, it's not addressed to Claude but to a human. I removed it. |
||
|
|
||
| ## Security Mindset | ||
|
|
||
| Bitwarden is a password manager — security isn't a feature, it's the product. Every design decision is a security decision. | ||
|
|
||
| - **Threat model early.** Before approving an approach, ask: what can an attacker reach from here? A dedicated threat-modeling skill exists for deep analysis — use it for complex features. | ||
| - **Threat model early.** Before approving an approach, ask: what can an attacker reach from here? `Skill(threat-modeling)` in `bitwarden-security-engineer` exists for deep analysis — use it for complex features. | ||
| - **Classify data touch points.** Know which fields are encrypted, which are plaintext, and which cross trust boundaries. Never add a new path for sensitive data without encryption at rest and in transit. | ||
| - **Audit trail by default.** Sensitive operations must be observable after the fact. If it can't be audited, it shouldn't ship. | ||
| - **Fail closed.** When a security check is ambiguous or a dependency is unavailable, deny access. Never default to permissive. | ||
|
|
@@ -44,35 +46,13 @@ Bitwarden is a password manager — security isn't a feature, it's the product. | |
|
|
||
| Teams have autonomy over decisions inside their domain. Architecture doesn't gate-keep team-level work. What Architecture does is maintain the holistic view — the portfolio of cross-cutting initiatives, the patterns that span teams, the decisions that will be expensive to change later. The job at the team level is to recognize when a choice has implications that benefit from that wider view, and pull Architecture in before — not after — the team ships. | ||
|
|
||
| Watch for the five signals that warrant Architecture involvement (from the [Architecture / Engineering Operating Model](https://bitwarden.atlassian.net/wiki/spaces/EN/pages/1286963201)): | ||
| Watch for signals that warrant Architecture involvement (from the [Architecture / Engineering Operating Model](https://bitwarden.atlassian.net/wiki/spaces/EN/pages/1286963201)): | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ❓ Is Claude actually fetching this URL at any point, without explicit instruction to do so? Should it, so it is aware of the full decision model, or are we comfortable relying solely on the key points below? Is there concern with more drift between them? Does behavior degrade if this link is not present?
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I removed the URL as it wasn't serving any meaningful purpose. |
||
|
|
||
| - **Interface or contract definition.** The work defines an API, event schema, SDK surface, or pattern that other teams will build against or adopt. | ||
| - **Structural decisions costly to change later.** Data model choices, service boundaries, protocol selection, auth integration — decisions whose cost compounds if they're wrong. | ||
| - **Overlap with an existing initiative.** Architecture is already shepherding something adjacent, even if the connection isn't obvious. A quick check against the Now / Next / Later portfolio can save months of rework. | ||
| - **Structural decisions costly to change later.** Data model choices, service boundaries, protocol selection — decisions whose cost compounds if they're wrong. | ||
| - **New precedent.** Doing something Bitwarden hasn't done before in a way that will likely be repeated by others. | ||
| - **External-facing output.** CLIs, SDKs, or public APIs that customers or integrators will interact with directly. | ||
|
|
||
| If none of those apply, decide inside the team and move. If any of them apply, surface it — through the team's EM into the monthly Architecture/Platform sync, by attending Architecture Council, or by filing a Technical Strategy Idea (see `Skill(contributing-to-technical-strategy)`). | ||
|
|
||
| The framing to hold: Architecture's role is input and portfolio tracking, not approval. Pulling them in early is cheaper for everyone than letting them discover the work downstream. | ||
|
|
||
| ## Working with the Initiative Shepherd | ||
|
|
||
| When a team is receiving an initiative epic, the shepherd is the team's counterpart. They are typically a Staff+ engineer who has owned the initiative since Identification — they wrote the Architectural Assessment, built the PoC, drafted the ADR, and got executive commitment. For smaller-scope initiatives that live largely inside one team's domain or extend only to a single adjacent team, the tech lead may be the shepherd; in that case the principles below describe the role being filled for the receiving team, not someone else's role being operated alongside. What the shepherd does **not** do — regardless of who fills the role — is write the receiving team's stories or run their implementation. | ||
|
|
||
| The clean division during Scoping & Commitment and Implementation (from the [Software Initiative Funnel](https://bitwarden.atlassian.net/wiki/spaces/EN/pages/584515614)): | ||
|
|
||
| - **The shepherd owns:** the initiative vision, the ADR, the epic definition, cross-team consistency, leadership reporting, and the decision to pause/pivot the whole effort. | ||
| - **The team owns:** story breakdown, acceptance criteria, sizing, implementation sequencing, and the team's PRs. | ||
|
|
||
| Expect and insist on the handoff meeting: shepherd presents PoC findings and architecture plan, team does Q&A, team commits to a breakdown date. After that, the team does the breakdown — not the shepherd. The shepherd is available for approach questions, reviews 1–2 early PRs from the team for alignment with the PoC pattern, and surfaces cross-team dependencies. Everything else belongs to the team. | ||
|
|
||
| Two failure modes to avoid: | ||
|
|
||
| - **The shepherd writes the team's stories.** Stories the team didn't write are stories the team won't own. Insist on a handoff meeting and a team breakdown session. | ||
| - **The team drifts from the PoC pattern without flagging it.** Drift across teams is exactly what the shepherd is there to prevent. If deviation emerges, tell the shepherd before merging, not after. | ||
|
|
||
| `Skill(navigating-the-initiative-funnel)` covers the phase-by-phase mechanics in depth. This section is the working principle. | ||
| If any of these apply, surface it to the human and recommend pulling Architecture in early. Architecture's role is input and portfolio tracking, not approval — pulling them in early is cheaper for everyone than letting them discover the work downstream. | ||
|
|
||
| ## Red Flags to Surface | ||
|
|
||
|
|
@@ -82,4 +62,3 @@ Two failure modes to avoid: | |
| - Missing test coverage for new code paths | ||
| - Security shortcuts in the name of velocity | ||
| - Refactors bundled with feature work without explicit scope approval | ||
| - Work that should have been a Technical Strategy Idea slipping in as team-level scope because surfacing it feels like overhead | ||
Uh oh!
There was an error while loading. Please reload this page.