From bffc51eb2f57a0340d7418b4e8fd517183692c44 Mon Sep 17 00:00:00 2001 From: Matt Bishop Date: Mon, 6 Jul 2026 10:17:57 -0400 Subject: [PATCH 1/3] feat: add LaunchDarkly feature-flag guidance to engineer and tech-lead plugins Ground both agents in Bitwarden's feature-flag practice and wire in the optional LaunchDarkly plugin. bitwarden-software-engineer (1.1.0): - Feature-flag conventions per contributing docs: server-side .NET uses Bitwarden.Server.Sdk.Features (IFeatureService, FeatureFlagKeys, [RequireFeature]); clients consume flag state from the /config endpoint. - Discipline rules: one flag per independently-releasable feature; release-vs-operational (kill switches may be permanent). - Optional launchdarkly plugin for the flag lifecycle (discovery, create, targeting, cleanup); flag-create can automate the currently-manual LaunchDarkly-side creation, gated on confirming with the flag owner. bitwarden-tech-lead (2.4.0): - architecting-solutions: "Feature-flag new work by default" principle (placement, one-flag-per-feature, default off, gradual rollout, release-vs-operational) plus a matching Red Flag. - Optional launchdarkly plugin for the release-strategy side (guarded rollout, experiment/metric setup), carved out as an explicit exception to the "all cross-plugin skills required" contract. Adds rollout/rollouts to the cspell dictionary. --- .claude-plugin/marketplace.json | 4 ++-- .cspell.json | 2 ++ README.md | 4 ++-- .../.claude-plugin/plugin.json | 2 +- .../bitwarden-software-engineer/CHANGELOG.md | 7 +++++++ plugins/bitwarden-software-engineer/README.md | 13 ++++++++----- .../agents/AGENT.md | 8 ++++++++ .../.claude-plugin/plugin.json | 2 +- plugins/bitwarden-tech-lead/CHANGELOG.md | 7 +++++++ plugins/bitwarden-tech-lead/README.md | 19 ++++++++++--------- plugins/bitwarden-tech-lead/agents/AGENT.md | 3 ++- .../skills/architecting-solutions/SKILL.md | 2 ++ 12 files changed, 52 insertions(+), 21 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f3a88ac8..dfb0e07a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -42,7 +42,7 @@ { "name": "bitwarden-software-engineer", "source": "./plugins/bitwarden-software-engineer", - "version": "1.0.0", + "version": "1.1.0", "description": "Software engineer agent for a Bitwarden product team. Implements stories, tasks, and bugs in the team's domain with code quality, performance, and security in mind. Participates in refinement, reviews PRs, collaborates with QA, and follows Git conventions." }, { @@ -66,7 +66,7 @@ { "name": "bitwarden-tech-lead", "source": "./plugins/bitwarden-tech-lead", - "version": "2.3.2", + "version": "2.4.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." }, { diff --git a/.cspell.json b/.cspell.json index c42db5a0..0684a15f 100644 --- a/.cspell.json +++ b/.cspell.json @@ -97,6 +97,8 @@ "remotelink", "Rescope", "resolutiondate", + "rollout", + "rollouts", "rustdoc", "sarif", "SDLC", diff --git a/README.md b/README.md index aa59d8d1..861f967d 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ A curated collection of plugins for AI-assisted development at Bitwarden. Enable | Plugin | Version | Description | | ------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [bitwarden-tech-lead](plugins/bitwarden-tech-lead/) | 2.3.2 | Tech lead for technical planning, architecture coherence, and surfacing patterns to Technical Strategy Ideas | +| [bitwarden-tech-lead](plugins/bitwarden-tech-lead/) | 2.4.0 | Tech lead for technical planning, architecture coherence, and surfacing patterns to Technical Strategy Ideas | | [bitwarden-shepherd](plugins/bitwarden-shepherd/) | 1.0.0 | Champion of a technical strategy — shepherds a TSI through evaluation into the funnel, then through to adoption | | [bitwarden-atlassian-tools](plugins/bitwarden-atlassian-tools/) | 2.2.7 | Read-only Atlassian access via MCP server with deep Jira issue research skill | | [bitwarden-code-review](plugins/bitwarden-code-review/) | 1.13.1 | Autonomous code review agent following Bitwarden engineering standards with GitHub integration | @@ -17,7 +17,7 @@ A curated collection of plugins for AI-assisted development at Bitwarden. Enable | [bitwarden-init](plugins/bitwarden-init/) | 1.2.0 | Initialize and enhance CLAUDE.md files with Bitwarden's standardized template format | | [bitwarden-product-analyst](plugins/bitwarden-product-analyst/) | 0.1.5 | Product analyst agent for creating comprehensive Bitwarden requirements documents from multiple sources | | [bitwarden-security-engineer](plugins/bitwarden-security-engineer/) | 1.2.0 | Application security engineering: vulnerability triage, threat modeling, and secure code analysis | -| [bitwarden-software-engineer](plugins/bitwarden-software-engineer/) | 1.0.0 | Software engineer agent for a Bitwarden product team. Implements stories, tasks, and bugs with code quality, performance, security, and team comms in mind. | +| [bitwarden-software-engineer](plugins/bitwarden-software-engineer/) | 1.1.0 | Software engineer agent for a Bitwarden product team. Implements stories, tasks, and bugs with code quality, performance, security, and team comms in mind. | | [claude-config-validator](plugins/claude-config-validator/) | 1.1.1 | Validates Claude Code configuration files for security, structure, and quality | | [claude-retrospective](plugins/claude-retrospective/) | 1.1.1 | Analyze Claude Code sessions to identify successful patterns and improvement opportunities | diff --git a/plugins/bitwarden-software-engineer/.claude-plugin/plugin.json b/plugins/bitwarden-software-engineer/.claude-plugin/plugin.json index 8fd96b95..a54d7bbf 100644 --- a/plugins/bitwarden-software-engineer/.claude-plugin/plugin.json +++ b/plugins/bitwarden-software-engineer/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "bitwarden-software-engineer", - "version": "1.0.0", + "version": "1.1.0", "description": "Software engineer agent for a Bitwarden product team. Implements stories, tasks, and bugs in the team's domain with code quality, performance, and security in mind. Participates in refinement, reviews PRs, collaborates with QA, and follows Git conventions.", "author": { "name": "Bitwarden", diff --git a/plugins/bitwarden-software-engineer/CHANGELOG.md b/plugins/bitwarden-software-engineer/CHANGELOG.md index 5fc709d8..e02c7de7 100644 --- a/plugins/bitwarden-software-engineer/CHANGELOG.md +++ b/plugins/bitwarden-software-engineer/CHANGELOG.md @@ -5,6 +5,13 @@ All notable changes to the `bitwarden-software-engineer` plugin will be document 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). +## [1.1.0] - 2026-07-06 + +### Added + +- Feature-flag guidance in `AGENT.md` and README, per the [Bitwarden feature flags guidance](https://contributing.bitwarden.com/contributing/feature-flags): server-side .NET evaluates through `Bitwarden.Server.Sdk.Features` (`IFeatureService`, `FeatureFlagKeys`, `[RequireFeature]`), not a hand-rolled abstraction or the raw LaunchDarkly SDK; clients read flag state from the server's `/config` endpoint. Includes two discipline rules: one flag per independently-releasable feature, and release-vs-operational (kill switches may be permanent, not cleanup candidates). +- Cross-Plugin Integration guidance for the optional `launchdarkly` plugin (requires the plugin and its hosted MCP server): `launchdarkly-flag-discovery` / `launchdarkly-flag-command` to find flags, `launchdarkly-flag-create` to gate code, `launchdarkly-flag-targeting` to toggle locally, `launchdarkly-flag-cleanup` to remove launched flags. Production rollout decisions defer to the tech lead. + ## [1.0.0] - 2026-05-19 ### Changed diff --git a/plugins/bitwarden-software-engineer/README.md b/plugins/bitwarden-software-engineer/README.md index 274643a9..cdd9031b 100644 --- a/plugins/bitwarden-software-engineer/README.md +++ b/plugins/bitwarden-software-engineer/README.md @@ -12,11 +12,14 @@ Software engineer agent for a Bitwarden product team. Generic AI coding assistan ## Cross-Plugin Integration -| Plugin | How It's Used | -| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| `bitwarden-delivery-tools` | `committing-changes`, `creating-pull-request`, `perform-preflight`, `labeling-changes` for the day-to-day PR loop | -| `bitwarden-atlassian-tools` | `researching-jira-issues` when picking up a story | -| `bitwarden-security-engineer` | `reviewing-security-architecture`, `analyzing-code-security`, `reviewing-dependencies`, `detecting-secrets` when relevant to the change | +| Plugin | How It's Used | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `bitwarden-delivery-tools` | `committing-changes`, `creating-pull-request`, `perform-preflight`, `labeling-changes` for the day-to-day PR loop | +| `bitwarden-atlassian-tools` | `researching-jira-issues` when picking up a story | +| `bitwarden-security-engineer` | `reviewing-security-architecture`, `analyzing-code-security`, `reviewing-dependencies`, `detecting-secrets` when relevant to the change | +| `launchdarkly` (optional) | `launchdarkly-flag-discovery` / `launchdarkly-flag-command`, `launchdarkly-flag-create`, `launchdarkly-flag-targeting`, `launchdarkly-flag-cleanup` for the feature-flag lifecycle — requires the LaunchDarkly plugin and its hosted MCP server ([install](https://mcp.launchdarkly.com/mcp/launchdarkly/install)) | + +**Feature flags** follow the [Bitwarden feature flags guidance](https://contributing.bitwarden.com/contributing/feature-flags) (flags in general always used for new work, one flag per independent feature, default off, kebab-case; release flags are temporary while operational kill-switches may be permanent). Server-side .NET evaluates them through our core [`Bitwarden.Server.Sdk.Features`](https://github.com/bitwarden/dotnet-extensions/tree/main/extensions/Bitwarden.Server.Sdk.Features/src) package (`IFeatureService`, `FeatureFlagKeys`, `[RequireFeature]`), which wraps LaunchDarkly — the agent uses it rather than hand-rolling a flag abstraction or calling the LaunchDarkly SDK directly. Clients (web/browser/desktop/mobile) are simple consumers that read flag state from the server's `/config` endpoint via `ConfigService` / `IConfigService`, never from LaunchDarkly directly. Per-repo skills (`implementing-dapper-queries`, `implementing-ef-core`, `writing-database-queries`, and similar) live in the relevant Bitwarden repos and are picked up by Claude Code's progressive disclosure. diff --git a/plugins/bitwarden-software-engineer/agents/AGENT.md b/plugins/bitwarden-software-engineer/agents/AGENT.md index b48be505..f6985b22 100644 --- a/plugins/bitwarden-software-engineer/agents/AGENT.md +++ b/plugins/bitwarden-software-engineer/agents/AGENT.md @@ -71,3 +71,11 @@ These skills are available across plugins and agent-neutral by design — invoke - `Skill(analyzing-code-security)` when handling user input that reaches SQL, HTML, the file system, or URLs. - `Skill(reviewing-dependencies)` when adding or updating dependencies. - `Skill(detecting-secrets)` when working with secrets or configuration. +- **Feature flags.** Per the [feature flags guidance](https://contributing.bitwarden.com/contributing/feature-flags), flags should in general **always** be used for new work — give each independently-releasable feature its own flag (don't couple separable features onto one), default the flag off, and name it kebab-case (`new-feature`, not `enable-new-feature`). A **release** flag is temporary and needs a retirement plan; **operational** flags (kill switches, infrastructure toggles) may be permanent — don't treat those as cleanup candidates. + - **Server-side (.NET): evaluate flags through the `Bitwarden.Server.Sdk.Features` package — do not hand-roll a flag abstraction or call the LaunchDarkly SDK directly.** It wraps LaunchDarkly, is part of our core server SDK, and already ships in our larger solutions. Inject `IFeatureService` (and `ICurrentContext`), reference the key from the `FeatureFlagKeys` constants, and read with `IsEnabled` / `GetIntVariation` / `GetStringVariation`; or gate an endpoint/controller declaratively with `[RequireFeature("flag-key")]` / `.RequireFeature("flag-key")`. Source: https://github.com/bitwarden/dotnet-extensions/tree/main/extensions/Bitwarden.Server.Sdk.Features/src + - **Clients (web/browser/desktop/mobile) are simple consumers** — they read flag state from the server's `/config` endpoint, never from LaunchDarkly directly. Web: add the key to the `FeatureFlags` enum and read via `ConfigService` (`getFeatureFlagBool` / `getFeatureFlagString` / `getFeatureFlagNumber`). Mobile: add the constant and read via `IConfigService` (`GetFeatureFlagBoolAsync` / `GetFeatureFlagStringAsync` / `GetFeatureFlagNumberAsync`). + - The `launchdarkly` plugin (optional) adds skills for the flag lifecycle. They require the plugin installed **and** its hosted MCP server configured (install: https://mcp.launchdarkly.com/mcp/launchdarkly/install) — degrade gracefully if either is absent: + - `Skill(launchdarkly-flag-discovery)` or `Skill(launchdarkly-flag-command)` to find an existing flag before touching code. + - `Skill(launchdarkly-flag-create)` when a story asks you to gate a new or risky code path behind a flag. It explores the repo's existing flag patterns first — in .NET server code, that pattern is `Bitwarden.Server.Sdk.Features`, so steer the generated evaluation code onto `IFeatureService` / `[RequireFeature]` rather than a raw SDK call. Today the LaunchDarkly flag itself is created by hand by a tech lead or manager (EM approval on merge to mainline); this skill can automate that creation via MCP, but confirm with the flag's owner before creating one rather than assuming it. + - `Skill(launchdarkly-flag-targeting)` to toggle a flag on or off while verifying locally. Production percentage rollouts are a release decision — surface those to the tech lead rather than deciding them here. + - `Skill(launchdarkly-flag-cleanup)` to remove a launched or stale flag and hardcode the winning variation once a rollout is complete. diff --git a/plugins/bitwarden-tech-lead/.claude-plugin/plugin.json b/plugins/bitwarden-tech-lead/.claude-plugin/plugin.json index 5590b2a3..420f92dd 100644 --- a/plugins/bitwarden-tech-lead/.claude-plugin/plugin.json +++ b/plugins/bitwarden-tech-lead/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "bitwarden-tech-lead", - "version": "2.3.2", + "version": "2.4.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.", "author": { "name": "Bitwarden", diff --git a/plugins/bitwarden-tech-lead/CHANGELOG.md b/plugins/bitwarden-tech-lead/CHANGELOG.md index 5e4302a9..775843de 100644 --- a/plugins/bitwarden-tech-lead/CHANGELOG.md +++ b/plugins/bitwarden-tech-lead/CHANGELOG.md @@ -5,6 +5,13 @@ All notable changes to the `bitwarden-tech-lead` plugin will be documented in th 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.4.0] - 2026-07-06 + +### Added + +- `architecting-solutions`: "Feature-flag new work by default" principle (per the Bitwarden feature flags guidance) — flag new work, decide server-side vs client-side placement up front, one flag per independently-releasable feature, default off, gradual rollout over a binary flip, and release-vs-operational flags (kill switches may be permanent). Added a matching Red Flag for feature work landing without a warranted flag. +- Cross-Plugin Integration guidance for the optional `launchdarkly` plugin — the tech-lead's release-strategy side: `launchdarkly-guarded-rollout` and `launchdarkly-experiment-setup` / `launchdarkly-metric-choose` / `launchdarkly-metric-create`, with an MCP install link. Carved out as an explicit optional exception to the "all cross-plugin skills required" contract, so the agent degrades gracefully when it is absent. + ## [2.3.2] - 2026-06-15 ### Changed diff --git a/plugins/bitwarden-tech-lead/README.md b/plugins/bitwarden-tech-lead/README.md index 465a826f..198c07cc 100644 --- a/plugins/bitwarden-tech-lead/README.md +++ b/plugins/bitwarden-tech-lead/README.md @@ -21,15 +21,16 @@ The tech lead represents a team inside Bitwarden's architecture process — arch ## Cross-Plugin Integration -| Plugin | How It's Used | -| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `bitwarden-delivery-tools` | Delivery lifecycle skills — `navigating-the-initiative-funnel` for funnel phase mechanics, `running-work-transitions` for ownership transitions either side | -| `bitwarden-security-engineer` | Security context (P01-P06), architecture pattern review, threat modeling | -| `bitwarden-product-analyst` | Consumes requirements documents as upstream input | -| `bitwarden-software-engineer` | Implementation conventions for server, client, and database decisions | -| `bitwarden-atlassian-tools` | Jira issue research and Confluence page access for the funnel, operating model, and TSI documents this plugin's skills reference | - -All cross-plugin skills are required because we rely upon each of them for a rich, complete workflow. +| Plugin | How It's Used | +| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `bitwarden-delivery-tools` | Delivery lifecycle skills — `navigating-the-initiative-funnel` for funnel phase mechanics, `running-work-transitions` for ownership transitions either side | +| `bitwarden-security-engineer` | Security context (P01-P06), architecture pattern review, threat modeling | +| `bitwarden-product-analyst` | Consumes requirements documents as upstream input | +| `bitwarden-software-engineer` | Implementation conventions for server, client, and database decisions | +| `bitwarden-atlassian-tools` | Jira issue research and Confluence page access for the funnel, operating model, and TSI documents this plugin's skills reference | +| `launchdarkly` (optional) | Release-strategy side of feature flags — `launchdarkly-guarded-rollout`, `launchdarkly-experiment-setup`, `launchdarkly-metric-choose`, `launchdarkly-metric-create`; requires the LaunchDarkly plugin and its hosted MCP server ([install](https://mcp.launchdarkly.com/mcp/launchdarkly/install)) | + +All cross-plugin skills except `launchdarkly` are required because we rely upon each of them for a rich, complete workflow. LaunchDarkly is optional — the agent degrades gracefully when it is not installed. ## Related Plugins diff --git a/plugins/bitwarden-tech-lead/agents/AGENT.md b/plugins/bitwarden-tech-lead/agents/AGENT.md index 5286803e..919de54f 100644 --- a/plugins/bitwarden-tech-lead/agents/AGENT.md +++ b/plugins/bitwarden-tech-lead/agents/AGENT.md @@ -72,7 +72,7 @@ For other work — participating in the Software Initiative Funnel, running a wo ## Cross-Plugin Integration -All cross-plugin skills are required. If unavailable, **STOP** and alert the human that they must be installed. +Every cross-plugin skill below is required **except LaunchDarkly, which is optional**. If a required one is unavailable, **STOP** and alert the human that they must be installed. These skills are available across plugins and are agent-neutral by design — a calling workflow (or the user) decides when to invoke them: @@ -80,3 +80,4 @@ These skills are available across plugins and are agent-neutral by design — a - **Security** (`bitwarden-security-engineer`): `Skill(bitwarden-security-context)` for P01-P06 principles, `Skill(reviewing-security-architecture)` for architecture pattern validation, `Skill(threat-modeling)` for formal threat models. - **Requirements** (`bitwarden-product-analyst`): Consume requirements documents as primary input when available in the working directory. - **Jira/Confluence** (`bitwarden-atlassian-tools`): `Skill(researching-jira-issues)` for Jira tickets, `get_confluence_page` MCP tool for Confluence pages — including the funnel, Work Transition Playbook, operating model, and Technical Strategy Ideas pages referenced by this plugin's skills and the delivery-lifecycle skills. +- **Feature flags & rollout** (`launchdarkly`, optional — when installed and its hosted MCP server is configured; install: https://mcp.launchdarkly.com/mcp/launchdarkly/install): the release-strategy side of feature management, which is a tech-lead call rather than an implementation detail. `Skill(launchdarkly-guarded-rollout)` for progressive, metric-gated rollouts with automatic rollback; `Skill(launchdarkly-experiment-setup)`, `Skill(launchdarkly-metric-choose)`, and `Skill(launchdarkly-metric-create)` when framing an experiment or the metrics a rollout is gated on. Degrade gracefully if the plugin is absent — do not STOP over it. Wrapping code in a flag and cleaning up launched flags stay with the engineer (`bitwarden-software-engineer`). diff --git a/plugins/bitwarden-tech-lead/skills/architecting-solutions/SKILL.md b/plugins/bitwarden-tech-lead/skills/architecting-solutions/SKILL.md index ea83cd38..75506e5a 100644 --- a/plugins/bitwarden-tech-lead/skills/architecting-solutions/SKILL.md +++ b/plugins/bitwarden-tech-lead/skills/architecting-solutions/SKILL.md @@ -33,6 +33,7 @@ Bitwarden is a password manager — security isn't a feature, it's the product. ## Bitwarden-Specific Principles +- **Feature-flag new work by default.** Per the [feature flags guidance](https://contributing.bitwarden.com/contributing/feature-flags), flags should in general **always** be used for new work — progressive rollouts, high-risk changes, cross-platform coordination, and merging incomplete work to mainline. Skip them only for simple/dependency updates, permanent architectural or database-logic changes, or anything that would become long-term debt. When architecting: decide up front **where the flag lives** (server-side, client-side, or both) since that shapes the design; give each independently-releasable feature **its own flag** — never couple separable features onto one, or a ready feature waits on an unready one; default the flag **off** and code defensively; and plan a **gradual rollout** (incremental percentages with monitoring at each step) rather than a binary on/off flip. Treat a **release** flag as temporary with a retirement plan — an un-retired one is tech debt you own — while **operational** flags (kill switches, infrastructure toggles) may be permanent and are categorized separately. Server-side projects evaluate flags through `Bitwarden.Server.Sdk.Features` (`IFeatureService`); clients are simple consumers that read flag state from the server's `/config` endpoint, never from LaunchDarkly directly. - **Multi-client reality:** Changes ripple across web, browser, desktop, CLI, and self-hosted deployments. Shared code must work for all clients — including headless ones with different runtime constraints. - **Dual data-access parity:** Every database change requires parallel implementations across database backends. Never ship one without the other. - **Open-source stewardship:** Code is public. Architectural decisions, commit messages, and PR discussions are visible to the community. Write them with that audience in mind. @@ -81,5 +82,6 @@ Two failure modes to avoid: - Silent behavior changes in shared libraries (`libs/common`, `src/Core`) - Missing test coverage for new code paths - Security shortcuts in the name of velocity +- New feature work landing without a feature flag when a flag is warranted (flags should in general always be used for new work) - 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 From 7b53b1fc755501bc2c65f4167b209a6fb1a69de1 Mon Sep 17 00:00:00 2001 From: Matt Bishop Date: Mon, 6 Jul 2026 13:08:48 -0400 Subject: [PATCH 2/3] docs: address plugin-validator readability notes on architecting-solutions - Break the dense feature-flag principle into a nested sub-list for scannability. - Trim the "always used for new work" clause repeated in the Red Flag. No behavior change; refines guidance added earlier in this PR. --- .../skills/architecting-solutions/SKILL.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/plugins/bitwarden-tech-lead/skills/architecting-solutions/SKILL.md b/plugins/bitwarden-tech-lead/skills/architecting-solutions/SKILL.md index 75506e5a..f5f0926a 100644 --- a/plugins/bitwarden-tech-lead/skills/architecting-solutions/SKILL.md +++ b/plugins/bitwarden-tech-lead/skills/architecting-solutions/SKILL.md @@ -33,7 +33,13 @@ Bitwarden is a password manager — security isn't a feature, it's the product. ## Bitwarden-Specific Principles -- **Feature-flag new work by default.** Per the [feature flags guidance](https://contributing.bitwarden.com/contributing/feature-flags), flags should in general **always** be used for new work — progressive rollouts, high-risk changes, cross-platform coordination, and merging incomplete work to mainline. Skip them only for simple/dependency updates, permanent architectural or database-logic changes, or anything that would become long-term debt. When architecting: decide up front **where the flag lives** (server-side, client-side, or both) since that shapes the design; give each independently-releasable feature **its own flag** — never couple separable features onto one, or a ready feature waits on an unready one; default the flag **off** and code defensively; and plan a **gradual rollout** (incremental percentages with monitoring at each step) rather than a binary on/off flip. Treat a **release** flag as temporary with a retirement plan — an un-retired one is tech debt you own — while **operational** flags (kill switches, infrastructure toggles) may be permanent and are categorized separately. Server-side projects evaluate flags through `Bitwarden.Server.Sdk.Features` (`IFeatureService`); clients are simple consumers that read flag state from the server's `/config` endpoint, never from LaunchDarkly directly. +- **Feature-flag new work by default.** Per the [feature flags guidance](https://contributing.bitwarden.com/contributing/feature-flags), flags should in general **always** be used for new work (progressive rollouts, high-risk changes, cross-platform coordination, merging incomplete work to mainline). Skip them only for simple or dependency updates, permanent architectural or database-logic changes, or anything that would become long-term debt. When architecting: + - Decide up front **where the flag lives** (server-side, client-side, or both), since that shapes the design. + - Give each independently releasable feature **its own flag**. Coupling separable features onto one flag makes a ready feature wait on an unready one. + - Default the flag **off** and code defensively. + - Plan a **gradual rollout** (incremental percentages with monitoring at each step) rather than a binary on/off flip. + - Treat a **release** flag as temporary with a retirement plan; an un-retired one is tech debt you own. **Operational** flags (kill switches, infrastructure toggles) may be permanent and are categorized separately. + - Server-side projects evaluate flags through `Bitwarden.Server.Sdk.Features` (`IFeatureService`); clients are simple consumers that read flag state from the server's `/config` endpoint, never from LaunchDarkly directly. - **Multi-client reality:** Changes ripple across web, browser, desktop, CLI, and self-hosted deployments. Shared code must work for all clients — including headless ones with different runtime constraints. - **Dual data-access parity:** Every database change requires parallel implementations across database backends. Never ship one without the other. - **Open-source stewardship:** Code is public. Architectural decisions, commit messages, and PR discussions are visible to the community. Write them with that audience in mind. @@ -82,6 +88,6 @@ Two failure modes to avoid: - Silent behavior changes in shared libraries (`libs/common`, `src/Core`) - Missing test coverage for new code paths - Security shortcuts in the name of velocity -- New feature work landing without a feature flag when a flag is warranted (flags should in general always be used for new work) +- New feature work landing without a feature flag when one is warranted - 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 From 130cf6d982079c6d6910f9b1325383eb01ce89fc Mon Sep 17 00:00:00 2001 From: Matt Bishop Date: Mon, 6 Jul 2026 14:17:14 -0400 Subject: [PATCH 3/3] docs: trim feature-flag prose from software-engineer README The SDK/evaluation detail (Bitwarden.Server.Sdk.Features, IFeatureService, /config) is behavioral guidance that belongs in AGENT.md, where it already lives. Other cross-plugin integrations carry only a table row, not a prose paragraph; this drops the duplicated block. The launchdarkly row in the cross-plugin table still covers the integration at README altitude. --- plugins/bitwarden-software-engineer/CHANGELOG.md | 2 +- plugins/bitwarden-software-engineer/README.md | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/plugins/bitwarden-software-engineer/CHANGELOG.md b/plugins/bitwarden-software-engineer/CHANGELOG.md index e02c7de7..599d93b2 100644 --- a/plugins/bitwarden-software-engineer/CHANGELOG.md +++ b/plugins/bitwarden-software-engineer/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Feature-flag guidance in `AGENT.md` and README, per the [Bitwarden feature flags guidance](https://contributing.bitwarden.com/contributing/feature-flags): server-side .NET evaluates through `Bitwarden.Server.Sdk.Features` (`IFeatureService`, `FeatureFlagKeys`, `[RequireFeature]`), not a hand-rolled abstraction or the raw LaunchDarkly SDK; clients read flag state from the server's `/config` endpoint. Includes two discipline rules: one flag per independently-releasable feature, and release-vs-operational (kill switches may be permanent, not cleanup candidates). +- Feature-flag guidance in `AGENT.md`, per the [Bitwarden feature flags guidance](https://contributing.bitwarden.com/contributing/feature-flags): server-side .NET evaluates through `Bitwarden.Server.Sdk.Features` (`IFeatureService`, `FeatureFlagKeys`, `[RequireFeature]`), not a hand-rolled abstraction or the raw LaunchDarkly SDK; clients read flag state from the server's `/config` endpoint. Includes two discipline rules: one flag per independently-releasable feature, and release-vs-operational (kill switches may be permanent, not cleanup candidates). - Cross-Plugin Integration guidance for the optional `launchdarkly` plugin (requires the plugin and its hosted MCP server): `launchdarkly-flag-discovery` / `launchdarkly-flag-command` to find flags, `launchdarkly-flag-create` to gate code, `launchdarkly-flag-targeting` to toggle locally, `launchdarkly-flag-cleanup` to remove launched flags. Production rollout decisions defer to the tech lead. ## [1.0.0] - 2026-05-19 diff --git a/plugins/bitwarden-software-engineer/README.md b/plugins/bitwarden-software-engineer/README.md index cdd9031b..db8a3477 100644 --- a/plugins/bitwarden-software-engineer/README.md +++ b/plugins/bitwarden-software-engineer/README.md @@ -19,8 +19,6 @@ Software engineer agent for a Bitwarden product team. Generic AI coding assistan | `bitwarden-security-engineer` | `reviewing-security-architecture`, `analyzing-code-security`, `reviewing-dependencies`, `detecting-secrets` when relevant to the change | | `launchdarkly` (optional) | `launchdarkly-flag-discovery` / `launchdarkly-flag-command`, `launchdarkly-flag-create`, `launchdarkly-flag-targeting`, `launchdarkly-flag-cleanup` for the feature-flag lifecycle — requires the LaunchDarkly plugin and its hosted MCP server ([install](https://mcp.launchdarkly.com/mcp/launchdarkly/install)) | -**Feature flags** follow the [Bitwarden feature flags guidance](https://contributing.bitwarden.com/contributing/feature-flags) (flags in general always used for new work, one flag per independent feature, default off, kebab-case; release flags are temporary while operational kill-switches may be permanent). Server-side .NET evaluates them through our core [`Bitwarden.Server.Sdk.Features`](https://github.com/bitwarden/dotnet-extensions/tree/main/extensions/Bitwarden.Server.Sdk.Features/src) package (`IFeatureService`, `FeatureFlagKeys`, `[RequireFeature]`), which wraps LaunchDarkly — the agent uses it rather than hand-rolling a flag abstraction or calling the LaunchDarkly SDK directly. Clients (web/browser/desktop/mobile) are simple consumers that read flag state from the server's `/config` endpoint via `ConfigService` / `IConfigService`, never from LaunchDarkly directly. - Per-repo skills (`implementing-dapper-queries`, `implementing-ef-core`, `writing-database-queries`, and similar) live in the relevant Bitwarden repos and are picked up by Claude Code's progressive disclosure. ## Related Plugins