feat(software-engineer): realign agent to canonical Software Engineer role (1.0.0)

[withinfocus]

🎟️ Tracking

No Jira/issue tracker — follows the recent realignment of bitwarden-tech-lead (2.3.0) and applies the same pattern to bitwarden-software-engineer, sourced from Bitwarden's Software Engineer role definition on the Engineering Career Ladder.

📔 Objective

Realign the bitwarden-software-engineer agent with the canonical Software Engineer role and bring the plugin's file layout in line with sibling plugins.

• Rewrite the agent description around the three role dimensions — Engineering Excellence, Delivery & Impact, Leadership & Communication — and add four <example> blocks (story implementation, PR review, surfacing mid-implementation ambiguity, preparing the commit/PR deliverable) so the orchestrator can route on concrete triggering scenarios.
• Tighten the AGENT.md body to match the size and density of bitwarden-tech-lead's AGENT.md (the reference): collapse the role-dimensions recap, condense Verification, and fold Security-Aware Development into Cross-Plugin Integration.
• Rename agents/bitwarden-software-engineer.md → agents/AGENT.md to match the convention used by bitwarden-tech-lead and bitwarden-shepherd; switch plugin.json's agents field to the string form.
• Refresh plugin/marketplace descriptions and the README catalog row; add software-engineer to plugin keywords.
• Bump plugin 0.4.2 → 1.0.0 via ./scripts/bump-plugin-version.sh.

Validators run locally:

• ./scripts/validate-plugin-structure.sh bitwarden-software-engineer — clean
• ./scripts/validate-marketplace.sh bitwarden-software-engineer — clean
• npm run lint (prettier + cspell) — clean after npm run format
• plugin-dev:plugin-validator agent — PASS

[github-actions]

Validation Summary — PR #124 (bitwarden-software-engineer)

Result: PASS — no critical or major issues. Plugin can ship as-is.

What was validated

Check	Tool	Outcome
Plugin structure & manifest	plugin-dev:plugin-validator agent	PASS
Agent frontmatter & system prompt	plugin-dev:plugin-validator agent	PASS
Security / config review	claude-config-validator:reviewing-claude-config	PASS
Marketplace ↔ plugin.json ↔ CHANGELOG consistency	Manual cross-check	PASS
Hardcoded credentials / secrets	grep + skill review	PASS

Skill review and command/hook/MCP checks are not applicable — this PR adds no skills, commands, hooks, or MCP servers.

Critical issues

None.

Major issues

None.

Minor warnings (non-blocking)

1. plugins/bitwarden-software-engineer/README.md — Thin README (16 lines). Has Overview and Usage but no Installation section. Also still references "skills" in the lead paragraph even though skills were migrated out in 0.4.0. Recommendation: reword the lead sentence to describe the agent and add an Installation block. Not blocking — this is a pre-existing condition, not introduced by PR feat(software-engineer): realign agent to canonical Software Engineer role (1.0.0) #124.
2. plugins/bitwarden-software-engineer/agents/AGENT.md:42 — tools: Read, Write, Edit, Bash, Glob, Grep, Skill uses the comma-separated string form rather than a YAML array. Claude Code accepts both forms and this matches the prior file (unchanged by this PR, per CHANGELOG 0.4.1). Optional cleanup only.
3. plugins/bitwarden-software-engineer/agents/AGENT.md:71-77 — Cross-plugin skill references (committing-changes, creating-pull-request, perform-preflight, labeling-changes, researching-jira-issues, security-engineer skills) are not asserted to exist in this PR's diff. If a sibling plugin renames or removes one, the Skill() call fails silently. Worth a periodic spot-check; not a PR feat(software-engineer): realign agent to canonical Software Engineer role (1.0.0) #124 issue.

Notes on false positives in the deeper scan

• The validator agent flagged "agents": "./agents/AGENT.md" in plugin.json:12 as non-standard. This is the established repository convention — bitwarden-shepherd and bitwarden-tech-lead use the identical pattern (verified). Not an issue.
• The validator agent flagged the flat agents/AGENT.md layout (vs nested agents/<name>/AGENT.md) as a mismatch with scripts/validate-plugin-structure.sh:424. This is a repo-level layout inconsistency between siblings (bitwarden-code-review is nested; bitwarden-shepherd, bitwarden-tech-lead, and this plugin are flat). Out of scope for PR feat(software-engineer): realign agent to canonical Software Engineer role (1.0.0) #124 — should be reconciled separately at the repo level.

Positive findings

• Version bump applied consistently across all three required surfaces: plugin.json:3 (1.0.0), .claude-plugin/marketplace.json:45 (1.0.0), CHANGELOG.md:8 ([1.0.0] - 2026-05-19).
• 1.0.0 jump from 0.4.2 is justified by the realignment to the canonical Software Engineer role and the AGENT.md rename. Classifying it as ### Changed (not breaking) is correct because the install/invocation contract is unchanged.
• CHANGELOG entry (CHANGELOG.md:8-14) follows Keep a Changelog format and clearly documents (a) the realignment to the Engineering Career Ladder dimensions, (b) the file rename, and (c) the description and keyword updates.
• Agent description includes 4 <example> blocks (AGENT.md:6-40) covering implementation, PR review, ambiguity escalation, and deliverable preparation — strong orchestrator-routing signal.
• System prompt is substantial (~2.2k chars, well above the 20-char floor) and explicitly disclaims tech-lead / architect / EM responsibilities, which helps keep the agent in lane.
• Plugin/marketplace descriptions match exactly (plugin.json:4 ↔ marketplace.json:46).
• No hardcoded credentials, API keys, or tokens anywhere in the changed files. The only matches for security-related terms are legitimate references to the detecting-secrets skill name in AGENT.md:77 and CHANGELOG.md:60.
• keywords updated to include software-engineer, matching the new description framing.

Files validated

• plugins/bitwarden-software-engineer/.claude-plugin/plugin.json
• plugins/bitwarden-software-engineer/CHANGELOG.md
• plugins/bitwarden-software-engineer/agents/AGENT.md
• plugins/bitwarden-software-engineer/agents/bitwarden-software-engineer.md (deletion — renamed to AGENT.md)
• .claude-plugin/marketplace.json (cross-check)

[github-actions]

Bitwarden Claude Code Review

Overall Assessment: APPROVE

Reviewed the realignment of the bitwarden-software-engineer agent to Bitwarden's canonical Software Engineer role on the Engineering Career Ladder. All six changed files are configuration, documentation, or marketplace metadata — no runtime code paths are affected. The agents/bitwarden-software-engineer.md → agents/AGENT.md rename and the plugin.json agents field switch from array to string both align with the string-form convention used by bitwarden-tech-lead, bitwarden-shepherd, bitwarden-product-analyst, and bitwarden-code-review. The 0.4.2 → 1.0.0 version bump is applied consistently across plugin.json, marketplace.json, the README catalog row, and the CHANGELOG entry, and the four new <example> blocks in the AGENT.md frontmatter are well-formed for orchestrator routing.

Code Review Details

No findings.

Verified:

• Version 1.0.0 consistent across plugins/bitwarden-software-engineer/.claude-plugin/plugin.json:3, .claude-plugin/marketplace.json:45, README.md:18, and plugins/bitwarden-software-engineer/CHANGELOG.md:8.
• plugin.json:12 agents: "./agents/AGENT.md" matches the dominant sibling-plugin convention.
• All nine cross-plugin Skill() references in agents/AGENT.md:71-77 resolve to real skill directories (committing-changes, creating-pull-request, perform-preflight, labeling-changes, researching-jira-issues, reviewing-security-architecture, analyzing-code-security, reviewing-dependencies, detecting-secrets).
• CHANGELOG entry follows Keep a Changelog format under ### Changed — appropriate since the install/invocation contract (bitwarden-software-engineer agent name) is unchanged.
• No stale references to the old bitwarden-software-engineer.md filename outside the CHANGELOG entry that documents the rename.
• AGENT.md frontmatter includes Skill in tools: (carried over from the 0.4.1 fix) and all four <example> blocks have proper Context, user, assistant, and <commentary> sections.