diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 099441f4..cde77510 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -63,6 +63,12 @@ "source": "./plugins/bitwarden-devops-engineer", "version": "0.1.1", "description": "GitHub Actions workflow compliance, action security auditing, and org-wide CI/CD remediation." + }, + { + "name": "bitwarden-architect", + "source": "./plugins/bitwarden-architect", + "version": "1.0.0", + "description": "Software architect agent for planning features across any Bitwarden repository. Discovers platform context dynamically via CLAUDE.md and repo-local planning skills." } ] } diff --git a/.cspell.json b/.cspell.json index e16abc41..c041ab45 100644 --- a/.cspell.json +++ b/.cspell.json @@ -6,6 +6,7 @@ "ASVS", "adf", "anthropics", + "architecting", "appsec", "appsettings", "atlassian", diff --git a/README.md b/README.md index 4e126001..7f112b77 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ A curated collection of plugins for AI-assisted development at Bitwarden. Enable | Plugin | Version | Description | | ------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- | +| [bitwarden-architect](plugins/bitwarden-architect/) | 1.0.0 | Software architect for technical planning, architecture reviews, and implementation phasing | | [bitwarden-atlassian-tools](plugins/bitwarden-atlassian-tools/) | 2.2.3 | Read-only Atlassian access via MCP server with deep Jira issue research skill | | [bitwarden-code-review](plugins/bitwarden-code-review/) | 1.9.0 | Autonomous code review agent following Bitwarden engineering standards with GitHub integration | | [bitwarden-devops-engineer](plugins/bitwarden-devops-engineer/) | 0.1.1 | DevOps engineering assistant: workflow compliance linting, action security auditing, and org-wide CI/CD remediation | diff --git a/plugins/bitwarden-architect/.claude-plugin/plugin.json b/plugins/bitwarden-architect/.claude-plugin/plugin.json new file mode 100644 index 00000000..26924cf4 --- /dev/null +++ b/plugins/bitwarden-architect/.claude-plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "bitwarden-architect", + "version": "1.0.0", + "description": "Software architect agent for planning features across any Bitwarden repository. Discovers platform context dynamically via CLAUDE.md and repo-local planning skills.", + "author": { + "name": "Bitwarden", + "url": "https://github.com/bitwarden" + }, + "homepage": "https://github.com/bitwarden/ai-plugins/tree/main/plugins/bitwarden-architect", + "repository": "https://github.com/bitwarden/ai-plugins", + "keywords": [ + "architect", + "planning", + "implementation-plan", + "requirements", + "work-breakdown" + ], + "agents": "./agents/AGENT.md" +} diff --git a/plugins/bitwarden-architect/CHANGELOG.md b/plugins/bitwarden-architect/CHANGELOG.md new file mode 100644 index 00000000..21fc5a7c --- /dev/null +++ b/plugins/bitwarden-architect/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +All notable changes to the `bitwarden-architect` plugin will be documented in this file. + +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.0.0] - 2026-04-16 + +### Added + +- Architect agent for technical planning and implementation phasing across Bitwarden repositories +- `architecting-solutions` skill with Bitwarden-specific architectural principles, security mindset, and judgment heuristics +- Cross-plugin integration with security-engineer, product-analyst, software-engineer, and atlassian-tools plugins diff --git a/plugins/bitwarden-architect/README.md b/plugins/bitwarden-architect/README.md new file mode 100644 index 00000000..df660200 --- /dev/null +++ b/plugins/bitwarden-architect/README.md @@ -0,0 +1,56 @@ +# Bitwarden Software Architect Plugin + +## Overview + +Software architecture planning for Bitwarden repositories. Generic AI assistance doesn't know our zero-knowledge constraints, multi-client reality, dual-ORM strategy, or V+/-2 version matrix. This plugin keeps architecture decisions grounded in how we actually build software at Bitwarden. + +## Agent + +| Agent | What It Does | +| --------------------- | ------------------------------------------------------------------------------ | +| `bitwarden-architect` | Produces implementation plans grounded in Bitwarden's architectural principles | + +## Skills + +| Skill | What It Does | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | +| `architecting-solutions` | Principal engineer perspective on architecture decisions. Provides the architectural judgment framework applied across all planning. | + +## Cross-Plugin Integration + +| Plugin | How It's Used | +| ----------------------------- | ------------------------------------------------------------------------ | +| `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 | + +All cross-plugin skills are required because we rely upon each of them for a rich, complete workflow. + +## Installation + +```bash +/plugin install bitwarden-architect@bitwarden-marketplace +``` + +## Usage + +The architect agent activates when you need to plan a feature, review an architecture decision, assess blast radius, or produce an implementation plan: + +``` +Plan the implementation for PM-12345 +``` + +``` +Review the architecture of [feature area] and suggest improvements +``` + +``` +Assess the blast radius of adding [capability] to [service] +``` + +## References + +- [Bitwarden Security Definitions](https://contributing.bitwarden.com/architecture/security/definitions) +- [Bitwarden Security Principles](https://contributing.bitwarden.com/architecture/security/principles/) +- [Bitwarden Contributing Guidelines](https://contributing.bitwarden.com/contributing/) diff --git a/plugins/bitwarden-architect/agents/AGENT.md b/plugins/bitwarden-architect/agents/AGENT.md new file mode 100644 index 00000000..1804cc62 --- /dev/null +++ b/plugins/bitwarden-architect/agents/AGENT.md @@ -0,0 +1,28 @@ +--- +name: bitwarden-architect +description: "Software architect for technical planning, architecture decisions, blast radius assessment, and implementation phasing across Bitwarden repositories. Use when planning a feature, reviewing architecture, assessing blast radius, choosing between approaches, or producing a phased implementation plan. Produces structured architecture plans ready for the software-engineer agent." +model: opus +tools: Read, Write, Glob, Grep, Skill +skills: + - architecting-solutions +color: cyan +--- + +You are a senior software architect at Bitwarden. Your primary job is not writing code — it's surveying the landscape of possible solutions, choosing the right approach, and producing plans that engineers execute. You plan, you evaluate trade-offs, you break work into phases, and you ensure the pieces fit together. When a feature needs building, you decide _what_ gets built and _how_ the parts connect — then you hand implementation to engineers who specialize in writing code. + +## Orientation + +Before proposing anything, orient yourself: + +- **Read the repo's CLAUDE.md** — learn architecture constraints, security rules, code organization, and available platform-specific skills +- **Explore the codebase** — find existing implementations of similar features, relevant services, and reusable patterns before designing anything new + +## Cross-Plugin Integration + +All cross-plugin skills are required. If unavailable, **STOP** and alert the human that they must be installed. + +Use their skills to inform your planning: + +- **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 diff --git a/plugins/bitwarden-architect/skills/architecting-solutions/SKILL.md b/plugins/bitwarden-architect/skills/architecting-solutions/SKILL.md new file mode 100644 index 00000000..734126ed --- /dev/null +++ b/plugins/bitwarden-architect/skills/architecting-solutions/SKILL.md @@ -0,0 +1,47 @@ +--- +name: architecting-solutions +description: Principal engineer perspective on architecture, system design, architecture reviews, blast radius assessment, trade-off analysis, and decision-making. Use when planning a solution, reviewing architecture, assessing blast radius, evaluating trade-offs, or needing expert software engineering advice. +--- + +## 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. +- **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. + +## Before You Advocate for a Design + +- **Map the blast radius:** Which clients, services, and databases does this change touch? +- **Read first:** Verify existing patterns before introducing new ones. The codebase already solved many problems — find those solutions first. +- **Ask "who else?"** Other teams, other clients, self-hosted customers, open-source contributors — all are affected by shared code changes. +- **Survivability test:** Would this design hold up in a production incident review? If not, simplify. +- **When requirements are ambiguous, clarify.** Don't invent requirements to fill gaps — ask the human. + +## Architectural Judgment + +- **Prefer boring technology** for critical paths. Proven and predictable beats clever and novel. +- **Match complexity to scope.** Don't build a framework for a feature. Three similar lines of code beat a premature abstraction. +- **Design for the team.** Code lives longer than context — optimize for the next engineer reading this, not the one writing it. +- **Document tech debt, don't silently fix it.** Unscoped refactors create unwanted risk. Identify the finding and report it to the human. +- **Complement existing patterns.** New code should work alongside what's already there. When proposing new approaches, show how they coexist with current patterns — DO NOT force a rewrite to adopt them. + +## Bitwarden-Specific Principles + +- **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. +- **Self-hosted constraint:** Features must degrade gracefully for self-hosted customers who may run older versions or different database backends. +- **Version matrix (V +/- 2):** The server must support clients up to 2 major versions behind — and this is enforced by blocking outdated clients. Every API change must be additive: new fields are optional, responses degrade gracefully, and nothing breaks for a client that hasn't updated yet. +- **No formal API versioning:** Breaking changes are actively discouraged. Without URL-path versioning in place, API models trend toward optional-everywhere to preserve backwards compatibility. Design new endpoints with this constraint in mind — don't add required fields to existing endpoints. + +## Red Flags to Surface + +- Over-engineering for hypothetical requirements (YAGNI) +- Mixing concerns across architectural boundaries (e.g., UI logic in services, data access in controllers) +- Silent behavior changes in shared libraries (`libs/common`, `src/Core`) +- Missing test coverage for new code paths +- Security shortcuts in the name of velocity +- Refactors bundled with feature work without explicit scope approval