-
Notifications
You must be signed in to change notification settings - Fork 96
feat(catalog): add Staff Engineer Mode #146
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
Open
sirmarkz
wants to merge
2
commits into
hashgraph-online:main
Choose a base branch
from
sirmarkz:add-staff-engineer-mode
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
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
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
42 changes: 42 additions & 0 deletions
42
plugins/sirmarkz/staff-engineer-mode/.codex-plugin/plugin.json
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| { | ||
| "name": "staff-engineer-mode", | ||
| "version": "1.5.1", | ||
| "description": "Staff-engineering decision guidance for AI coding agents. Routes design, development, testing, release, operations, reliability, security, API, data, and platform work to specialist guidance.", | ||
| "author": { | ||
| "name": "sirmarkz", | ||
| "url": "https://github.com/sirmarkz/staff-engineer-mode" | ||
| }, | ||
| "homepage": "https://github.com/sirmarkz/staff-engineer-mode", | ||
| "repository": "https://github.com/sirmarkz/staff-engineer-mode", | ||
| "license": "MIT", | ||
| "keywords": [ | ||
| "staff-engineer", | ||
| "engineering-lifecycle", | ||
| "devops", | ||
| "sre", | ||
| "reliability", | ||
| "security", | ||
| "architecture", | ||
| "skills" | ||
| ], | ||
| "skills": "./skills/", | ||
| "interface": { | ||
| "displayName": "Staff Engineer Mode", | ||
| "shortDescription": "Staff Engineer Mode engineering lifecycle and operations guidance", | ||
| "longDescription": "Technology-agnostic guidance for applying large-scale engineering practices to architecture, reliability, resilience, delivery, operations, security, privacy, data, platform, client, and cost-aware reliability work. The router automatically selects the smallest useful routed specialist set from natural-language engineering requests.", | ||
| "developerName": "sirmarkz", | ||
| "category": "Coding", | ||
| "composerIcon": "./assets/icon.svg", | ||
| "capabilities": [ | ||
| "Interactive", | ||
| "Read", | ||
| "Write" | ||
| ], | ||
| "defaultPrompt": [ | ||
| "Design the production readiness checks for this service.", | ||
| "Make this architecture reliable and operable.", | ||
| "Decide the right engineering constraints for this change." | ||
| ], | ||
| "brandColor": "#1F6FEB" | ||
| } | ||
| } |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| .git/ | ||
| .github/ | ||
| .claude/ | ||
| .codex/ | ||
| .cursor-plugin/ | ||
| .opencode/ | ||
| __pycache__/ | ||
| .pytest_cache/ | ||
| node_modules/ | ||
| assets/readme/ |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| MIT License | ||
|
|
||
| Copyright (c) 2026 sirmarkz | ||
|
|
||
| Permission is hereby granted, free of charge, to any person obtaining a copy | ||
| of this software and associated documentation files (the "Software"), to deal | ||
| in the Software without restriction, including without limitation the rights | ||
| to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | ||
| copies of the Software, and to permit persons to whom the Software is | ||
| furnished to do so, subject to the following conditions: | ||
|
|
||
| The above copyright notice and this permission notice shall be included in all | ||
| copies or substantial portions of the Software. | ||
|
|
||
| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
| IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
| FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
| AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
| LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
| OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | ||
| SOFTWARE. | ||
|
|
||
| Project Notice | ||
|
|
||
| Staff Engineer Mode is an independent project. It cites public engineering | ||
| writing and standards for context. Named organizations are sources, not | ||
| sponsors, maintainers, or project owners. | ||
|
|
||
| The MIT License above covers this repository's original code, skill text, | ||
| documentation, scripts, manifests, and templates. | ||
|
|
||
| Third-party articles, papers, documentation, trademarks, logos, product names, | ||
| and organization names remain under their owners' terms. | ||
|
|
||
| For contributors: | ||
|
|
||
| - Cite stable source IDs from `skills/_shared/references/source-index.md`. | ||
| - Write original summaries and operational guidance. | ||
| - Keep quotes short and necessary. | ||
| - Do not copy third-party articles, diagrams, logos, or other materials into | ||
| this repository. |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,208 @@ | ||
| # Staff Engineer Mode | ||
|
|
||
| [](./RELEASE-NOTES.md) | ||
|
|
||
| **Your AI coding agent ships fast. This makes it ship with judgment.** | ||
|
|
||
| Staff-level engineering reasoning for design, development, testing, release, and operations decisions. | ||
|
|
||
| ## Why Now | ||
|
|
||
| AI coding agents now write material amounts of production code. The bottleneck is no longer how fast the agent writes — it is whether the agent reasoned about what happens when the code runs at 3am. Agents will happily design an endpoint without a compatibility plan, implement a migration with no rollback, add tests that miss the failure mode, or ship a config change with no canary. This pack closes that gap. | ||
|
|
||
| ## How It Works | ||
|
|
||
| Ask a normal engineering question. Hand the agent a task, design, diff, incident, rollout, or maintenance problem. The router reads the work, picks one specialist (occasionally one secondary), reads that specialist file, and returns concrete decisions, risks, checks, owners, supporting details, and next steps. You never name a specialist. | ||
|
|
||
| Supported tools should list only the native `staff-engineer-mode` router. Specialist files live under `specialists/` and load only after routing. | ||
|
|
||
| The router refuses to load every plausible specialist. One primary specialist at a time, by default. | ||
|
|
||
| See [SAMPLE-PROMPTS.md](SAMPLE-PROMPTS.md) for prompts across every specialist. | ||
|
|
||
| ## What It Looks Like | ||
|
|
||
| These are real Claude Code captures from public codebases. The prompt is plain | ||
| developer wording; Staff Engineer Mode routes to one specialist, loads that | ||
| specialist file, and returns a structured engineering answer. | ||
|
|
||
| <details> | ||
| <summary>API compatibility review</summary> | ||
|
|
||
| <img src="assets/staff-engineer-mode-api-design-and-compatibility.png" alt="Claude Code capture showing an API compatibility review for an account API response change" width="100%"> | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Backup and recovery review</summary> | ||
|
|
||
| <img src="assets/staff-engineer-mode-backup-and-recovery.png" alt="Claude Code capture showing a backup and recovery review for a database restore plan" width="100%"> | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Code readability for agents review</summary> | ||
|
|
||
| <img src="assets/staff-engineer-mode-code-readability-for-agents.png" alt="Claude Code capture showing a code readability for agents review for repo areas an AI coding agent may misunderstand" width="100%"> | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Dependency and code hygiene plan</summary> | ||
|
|
||
| <img src="assets/staff-engineer-mode-dependency-and-code-hygiene.png" alt="Claude Code capture showing a dependency and code hygiene plan for stale dependencies and dead helper code" width="100%"> | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Dependency resilience review</summary> | ||
|
|
||
| <img src="assets/staff-engineer-mode-dependency-resilience.png" alt="Claude Code capture showing a dependency resilience review for remote media fetch timeouts, retries, and fallback behavior" width="100%"> | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>High availability design</summary> | ||
|
|
||
| <img src="assets/staff-engineer-mode-high-availability-design.png" alt="Claude Code capture showing a high availability design review for a multi-region control plane" width="100%"> | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Observability and alerting review</summary> | ||
|
|
||
| <img src="assets/staff-engineer-mode-observability-and-alerting.png" alt="Claude Code capture showing an observability and alerting review for API server request errors and latency" width="100%"> | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Performance and capacity review</summary> | ||
|
|
||
| <img src="assets/staff-engineer-mode-performance-and-capacity.png" alt="Claude Code capture showing a performance and capacity review for an account lookup endpoint" width="100%"> | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Production readiness before launch</summary> | ||
|
|
||
| <img src="assets/staff-engineer-mode-production-readiness-review.png" alt="Claude Code capture showing a production readiness review for a media processing queue split" width="100%"> | ||
|
|
||
| </details> | ||
|
|
||
| ## Installation | ||
|
|
||
| ### Claude Code | ||
|
|
||
| Register the marketplace: | ||
|
|
||
| ```text | ||
| /plugin marketplace add https://github.com/sirmarkz/staff-engineer-mode.git | ||
| ``` | ||
|
|
||
| Install the plugin: | ||
|
|
||
| ```text | ||
| /plugin install staff-engineer-mode@staff-engineer-mode | ||
| ``` | ||
|
|
||
| ### Codex | ||
|
|
||
| Works with Codex CLI and Codex App. Tell Codex: | ||
|
|
||
| ```text | ||
| Fetch and follow instructions from https://raw.githubusercontent.com/sirmarkz/staff-engineer-mode/main/.codex/INSTALL.md | ||
| ``` | ||
|
|
||
| ### Cursor | ||
|
|
||
| ```text | ||
| /add-plugin staff-engineer-mode | ||
| ``` | ||
|
|
||
| ### OpenCode | ||
|
|
||
| Works with OpenCode. Tell OpenCode: | ||
|
|
||
| ```text | ||
| Fetch and follow instructions from https://raw.githubusercontent.com/sirmarkz/staff-engineer-mode/main/.opencode/INSTALL.md | ||
| ``` | ||
|
|
||
| ### GitHub Copilot CLI | ||
|
|
||
| Register the marketplace: | ||
|
|
||
| ```bash | ||
| copilot plugin marketplace add https://github.com/sirmarkz/staff-engineer-mode.git | ||
| ``` | ||
|
|
||
| Install the plugin: | ||
|
|
||
| ```bash | ||
| copilot plugin install staff-engineer-mode@staff-engineer-mode | ||
| ``` | ||
|
|
||
| ### Gemini CLI | ||
|
|
||
| ```bash | ||
| gemini extensions install https://github.com/sirmarkz/staff-engineer-mode | ||
| ``` | ||
|
|
||
| ## Verify | ||
|
|
||
| Start a fresh session inside any open repo and ask one of: | ||
|
|
||
| - "Before implementing partner webhooks, design the event contract, delivery retries, replay path, and dead-letter handling." | ||
| - "During development of the checkout inventory call, decide timeout, retry, fallback, and duplicate-work safeguards." | ||
| - "Review my last commit and tell me what you would catch in PR review." | ||
|
|
||
| The agent should load the router, choose one specialist, and respond with concrete decisions, risks, checks, owners, supporting details, and next steps — not vibes. | ||
|
|
||
| ## What's Inside | ||
|
|
||
| One native router skill: `staff-engineer-mode`. It routes to 54 specialist | ||
| files under `specialists/`; those files are not installed or listed as separate | ||
| native skills. | ||
|
|
||
| Examples by surface (the full catalog with prompts for every specialist file is in [SAMPLE-PROMPTS.md](SAMPLE-PROMPTS.md)): | ||
|
|
||
| | Surface | Example specialist files | | ||
| | --- | --- | | ||
| | Architecture and interfaces | [`architecture-decisions`](specialists/architecture-decisions.md), [`api-design-and-compatibility`](specialists/api-design-and-compatibility.md), [`data-contracts`](specialists/data-contracts.md), [`state-machine-correctness`](specialists/state-machine-correctness.md) | | ||
| | Reliability and resilience | [`slo-and-error-budgets`](specialists/slo-and-error-budgets.md), [`high-availability-design`](specialists/high-availability-design.md), [`dependency-resilience`](specialists/dependency-resilience.md), [`backup-and-recovery`](specialists/backup-and-recovery.md), [`resilience-experiments`](specialists/resilience-experiments.md), [`performance-and-capacity`](specialists/performance-and-capacity.md) | | ||
| | Delivery and change safety | [`progressive-delivery`](specialists/progressive-delivery.md), [`feature-flag-lifecycle`](specialists/feature-flag-lifecycle.md), [`release-build-reproducibility`](specialists/release-build-reproducibility.md), [`testing-and-quality-gates`](specialists/testing-and-quality-gates.md), [`test-data-engineering`](specialists/test-data-engineering.md), [`dev-environment-parity`](specialists/dev-environment-parity.md), [`migration-and-deprecation`](specialists/migration-and-deprecation.md), [`code-readability-for-agents`](specialists/code-readability-for-agents.md), [`dependency-and-code-hygiene`](specialists/dependency-and-code-hygiene.md), [`configuration-and-automation-safety`](specialists/configuration-and-automation-safety.md), [`fleet-upgrades`](specialists/fleet-upgrades.md) | | ||
| | Operations and observability | [`observability-and-alerting`](specialists/observability-and-alerting.md) | | ||
| | Security and privacy | [`secure-sdlc-and-threat-modeling`](specialists/secure-sdlc-and-threat-modeling.md), [`identity-and-secrets`](specialists/identity-and-secrets.md), [`cryptography-and-key-lifecycle`](specialists/cryptography-and-key-lifecycle.md), [`software-supply-chain-security`](specialists/software-supply-chain-security.md), [`vulnerability-management`](specialists/vulnerability-management.md), [`tenant-isolation`](specialists/tenant-isolation.md), [`privacy-and-data-lifecycle`](specialists/privacy-and-data-lifecycle.md) | | ||
| | Data and workflow systems | [`distributed-data-and-consistency`](specialists/distributed-data-and-consistency.md), [`database-operations`](specialists/database-operations.md), [`event-workflows`](specialists/event-workflows.md), [`data-pipeline-reliability`](specialists/data-pipeline-reliability.md), [`caching-and-derived-data`](specialists/caching-and-derived-data.md) | | ||
| | Platform and edge | [`infrastructure-and-policy-as-code`](specialists/infrastructure-and-policy-as-code.md), [`internal-service-networking`](specialists/internal-service-networking.md), [`edge-traffic-and-ddos-defense`](specialists/edge-traffic-and-ddos-defense.md), [`cost-aware-reliability`](specialists/cost-aware-reliability.md) | | ||
| | Client, ML/AI, and experimentation | [`web-release-gates`](specialists/web-release-gates.md), [`mobile-release-engineering`](specialists/mobile-release-engineering.md), [`accessibility-gates`](specialists/accessibility-gates.md), [`llm-application-security`](specialists/llm-application-security.md), [`llm-evaluation`](specialists/llm-evaluation.md), [`llm-serving-cost-and-latency`](specialists/llm-serving-cost-and-latency.md), [`ml-reliability-and-evaluation`](specialists/ml-reliability-and-evaluation.md), [`experimentation-and-metric-guardrails`](specialists/experimentation-and-metric-guardrails.md) | | ||
| | Engineering workflow, readiness, and controls | [`agent-pr-review`](specialists/agent-pr-review.md), [`ai-coding-governance`](specialists/ai-coding-governance.md), [`documentation-lifecycle`](specialists/documentation-lifecycle.md), [`engineering-control-evidence`](specialists/engineering-control-evidence.md), [`production-readiness-review`](specialists/production-readiness-review.md), [`incident-response-and-postmortems`](specialists/incident-response-and-postmortems.md), [`oncall-health`](specialists/oncall-health.md), [`platform-golden-paths`](specialists/platform-golden-paths.md) | | ||
|
|
||
| Every specialist file appears in [SAMPLE-PROMPTS.md](SAMPLE-PROMPTS.md) with four representative prompts. | ||
|
|
||
| ## Compared To Alternatives | ||
|
|
||
| Staff Engineer Mode can be used alongside workflow skills like Superpowers. | ||
| Workflow skills shape how the agent plans and executes; Staff Engineer Mode | ||
| shapes the engineering checks and decisions it applies to the work. | ||
|
|
||
| ## Contributing | ||
|
|
||
| Patches welcome — especially additional practices from authoritative sources: first-party engineering publications, official documentation, standards bodies, peer-reviewed papers, or widely cited practitioner references. | ||
|
|
||
| New specialist files must be technology-agnostic, cite stable source IDs, and avoid vendor endorsement. Read [STYLE.md](STYLE.md) before opening a PR. The voice is enforced. | ||
|
|
||
| ## Maintainers | ||
|
|
||
| See [MAINTAINERS.md](MAINTAINERS.md). | ||
|
|
||
| ## Sources And Influences | ||
|
|
||
| This pack focuses on the intersection of the strongest publicly documented engineering practices from leading software engineering organizations. It synthesizes large-operator engineering writing (Google, Amazon, Meta, Microsoft, Apple, Netflix) and standards work cited by their teams (NIST, CISA, OWASP, OpenSSF, IETF, W3C). Specific source IDs are in `skills/_shared/references/source-index.md`. This is an independent project; nothing here is endorsed by or affiliated with those organizations. | ||
|
|
||
| ## License | ||
|
|
||
| MIT — see [LICENSE](LICENSE). The project notice is included there. | ||
|
|
||
| --- | ||
|
|
||
| *Fewer vibes. More engineering.* |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
SUGGESTION: README entries are not in alphabetical order — "Staff Engineer Mode" should appear before "Spec-Driven Development"
The check-alphabetical.py script would catch this failure.
Correct order in the "Development & Workflow" subsection:
The issue is that ‘staff engineer mode’ < ‘spec-driven development’ in case-insensitive alphabetical order (character 4: ‘f’ < ‘p’). Currently the new entry is inserted after Spec-Driven (line 158), which breaks the list’s expected sort order.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Checked against the repository checker and a case-insensitive sort. The current README order is correct:
Spec-Driven Developmentsorts beforeStaff Engineer Modebecausespec...comes beforestaff...(p<t).Verification:
python3 scripts/check-alphabetical.py README.mdpasses withDevelopment & Workflowat 51 items.printf "%s\\n" "Spec-Driven Development" "Staff Engineer Mode" | sort -foutputsSpec-Driven Developmentfirst.No README move.