senior-engineering-partner

Last updated: 2026-08-08 06:35 PM CDT

A custom Claude Code skill: a strict code reviewer, pair programmer, debugger, and mentor for Python, Bash, Google Apps Script, JavaScript, and Swift/Apple platforms. It encodes a security-first, phase-aware engineering discipline — and an enforced spec → plan → TDD → verify workflow — as reusable instructions that activate via /senior-engineering-partner (or auto-activate when a task matches its description) in any Claude Code session.

This README documents the skill's architecture — how it is organized and maintained. The skill's actual instructions live in SKILL.md; the deep, per-topic standards live in references/.

• Author: Brian Greenberg · Web: https://briangreenberg.net
• Version: see the metadata table at the bottom of SKILL.md, the CHANGELOG.md, and the Releases page
• Invoke: /senior-engineering-partner in Claude Code, optionally prefixed with a mode trigger word (see Modes).

Contents

• What it is
• What it governs
• Architecture
• Modes & triggers
• The rigor ladder
• Reference catalog
• Shipped helpers & evals
• Install
• Using it with other AI tools (Codex, Gemini CLI, …)
• Customize for your environment (my-environment.md)
• Maintaining / contributing
• Citing this repository
• License
• Disclaimer

What it is

A single skill that does the heavy lifting of senior engineering work — design, write, test, review, debug, and document code — calibrated to an intermediate Python/Bash developer. Three ideas run through everything:

• Phase-aware rigor, with a security floor that never moves. Match effort to the project's phase (prototype → MVP → production), but never relax the secrets/injection/validation/isolation/authentication fundamentals. Cheap ≠ insecure.
• Deterministic-first, anti-hallucination discipline. Verify before asserting (claims about the environment come from a tool run this turn), never invent flags/paths/APIs, and mechanize anything checkable (counting, parsing, regex, transforms) in a script rather than reasoning it out token-by-token.
• An enforced workflow, not just standards. The skill doesn't only say what good looks like — it drives the loop that produces it: spec-first (agree what you're building before building it) → plan in verifiable steps → tier-aware iron-law TDD → verify-before-done self-review. Depth scales with the rigor tier; the loop does not.

_{↑ Back to contents}

What it governs

The disciplines are stack-agnostic, but they bind to concrete tooling. At a glance, what the skill carries standards for:

• Languages: Python · Bash · Google Apps Script · JavaScript / TypeScript · Swift (macOS/iOS/watchOS/iPadOS)
• Source control & CI/CD: GitHub · GitHub Actions · branch protection / rulesets · supply-chain gates (SBOM · SLSA · signing)
• Cloud & infra: GCP / Cloud Run · Docker · Kubernetes · Terraform (IaC)
• Data: Postgres / Supabase (RLS) · BigQuery · SQLite · caching
• App layer: FastAPI / Python web APIs · front-end & browser security · responsive, accessible (WCAG 2.2 AA) UI · LLM-app engineering (workflow/agent-loop patterns · stopping criteria · RAG · evals)
• Security & standards: the security floor (secrets · injection · input validation · isolation · least privilege) · NIST CSF 2.0 + SSDF · OWASP Top 10 / API Top 10 / LLM Top 10 · STRIDE · SOC 2 · Well-Architected · PCI-DSS scope · crypto-agility / post-quantum readiness (FIPS 203–205, HNDL)
• Reliability & ops: resilience engineering · disaster recovery & business continuity · scalability / system design · observability + incident response (DORA · SLOs)
• Platform-specific: macOS app bundles / TCC · local & agentic AI tooling · diagrams-as-code (Mermaid)

Each binds to a deep, read-on-demand reference (see the catalog below); your concrete hosts, projects, and stack live only in the private, un-committed references/my-environment.md.

_{↑ Back to contents}

Architecture

The skill is a stack-agnostic universal core (SKILL.md, always loaded) plus a swappable environment profile and a library of deep per-topic references read on demand (progressive disclosure — Claude reads a reference only when its trigger paragraph in SKILL.md says the work is relevant). Forking the skill for a different environment is a matter of replacing one file (references/my-environment.md).

flowchart TD
    U["/senior-engineering-partner"] --> C
    C["SKILL.md — universal core<br/>modes · epistemic discipline · engineering workflow · rigor ladder<br/>security floor · coding standards · toolchain triggers"]
    C -->|"progressive disclosure: read a reference only when relevant"| R[(references/)]
    C -.->|"shipped helpers"| K["scripts/ (audit · render-diagrams · validate-citation · leakage-guard · actions-lint · run-evals · eval-guard · curate-baseline · skill-lint · self-review · fixture tests)<br/>evals/ (regression scenarios + recorded baselines)"]
    R --> P["Environment profile<br/>my-environment.md (swap to re-home the skill)"]
    R --> W["Engineering process (5)<br/>engineering-workflow · debugging · audit-report-format · standards-authoring · skill-self-improvement"]
    R --> S["Security, privacy and compliance (7)"]
    R --> T["Testing and QA (3)"]
    R --> I["Cloud, infra, ops and logging (10) + data (2)"]
    R --> A["App toolchains, CI and collaboration (12)"]
    R --> X["UI, a11y, diagrams, AI tooling, macOS (5)"]

SKILL.md carries the rules that must always be in context (the modes, the security floor, the rigor ladder, the coding/documentation/logging/SCM standards, and a short trigger paragraph per toolchain). Each trigger paragraph states the non-negotiables and points at the reference to read before doing related work — so the expensive detail is loaded only when it earns its place in the context window.

_{↑ Back to contents}

Modes & triggers

Behavior changes on a leading trigger word; with no trigger, it defaults to pair programming.

flowchart TD
    P[User prompt] --> Q{Leading trigger word?}
    Q -->|"REVIEW:"| R["Strict senior code reviewer<br/>critique rigorously, then deliver the refactor"]
    Q -->|"EXPLAIN:"| E["Patient mentor<br/>teach the why, not just a copy-paste answer"]
    Q -->|"MVP: / PROTOTYPE:"| M["Lean-but-safe builder<br/>Tier 0/1, defer heavy gates, never the floor"]
    Q -->|"DEBUG:"| G["Systematic debugger<br/>reproduce, isolate, fix root cause, prove with a red-first test"]
    Q -->|"AUDIT:"| A["Report-first codebase auditor<br/>severity-ranked findings report; fixes only after review"]
    Q -->|none| D["Collaborative pair programmer (default)<br/>clean, tested, documented, production-ready code"]

_{↑ Back to contents}

The rigor ladder

Effort scales with project phase; the security/CIA floor holds at every tier. Only verification depth, redundancy, and operational maturity scale.

flowchart LR
    T0["Tier 0 — Prototype<br/>throwaway, never real tenant data"]
    T1["Tier 1 — MVP / early product<br/>critical-path tests, basic CI, secrets manager, authn, backups"]
    T2["Tier 2 — Production / commercial / multi-tenant<br/>full strict posture, every merge-blocking gate"]
    Floor["Security / CIA floor — CONSTANT at every tier<br/>no hardcoded secrets · validate inputs · no injection · isolated env · authn · vetted deps"]
    T0 -->|"real users / small scale"| T1
    T1 -->|"customers · money · multi-tenant · PII · 2nd contributor · public exposure"| T2
    Floor -.underpins.-> T0
    Floor -.underpins.-> T1
    Floor -.underpins.-> T2

Crossing any promotion trigger (real customer/tenant data, money changing hands, multi-tenant isolation, regulated/PII data, a second contributor, public internet exposure) re-rates the project up a tier — it is not optional polish.

_{↑ Back to contents}

Reference catalog

Deep standards, read on demand. Each carries verify-against-live-docs caveats on version-specific commands.

_{↑ Back to contents}

Shipped helpers & evals

Beyond the always-loaded core and the read-on-demand references, the skill ships two support directories:

• scripts/ — the utility scripts the disciplines reference, shipped so they're executed, not regenerated: audit.sh (manifest-level dependency-audit gate), render-diagrams.sh (the docs-render Mermaid render-check), validate-citation.sh (the citation-validate CFF schema check), leakage-guard.sh (the two-tier environment-identifier gate), actions-lint.sh (the workflow gate: checksum-verified actionlint + pinned zizmor — green-optional by explicit decision, on the testing.md §3d introduction ladder; promotion to required is a recorded maintainer call), run-evals.py (the eval-suite runner — below), eval-guard.py (the substantive-SKILL.md-change-needs-an-eval gate), curate-baseline.py (slims a sweep into a committable baseline), skill-lint.py (name/description/word-budget/ reference-integrity), and self-review.md (the verify-before-done checklist). Pin render-diagrams.sh's MMDC_IMAGE to a digest before relying on it.
• evals/ — a regression suite. Each scenarios/*.json encodes a real miss from the changelog as a checkable expectation, in Anthropic's evaluation shape. evals/README.md documents the baseline-then-iterate (Claude-A authors / Claude-B tests) loop, and scripts/run-evals.py executes the suite: it runs each query headlessly through the claude CLI (with the skill injected, or bare for a baseline) — or through any other agent CLI via --runner generic — LLM-judges the response against expected_behavior/anti_behavior, and writes per-scenario verdicts + a summary (see How to run and Cross-CLI runs in evals/README.md). Add or extend a scenario whenever a new changelog entry is written from a real miss — a lesson without a guarding eval can silently regress.

_{↑ Back to contents}

Install

Two ways into Claude Code — pick one (a side-by-side plugin install and skill clone would load the skill twice):

As a plugin (quickest)

The repo doubles as its own single-plugin marketplace (.claude-plugin/marketplace.json), so two commands inside Claude Code install it:

/plugin marketplace add bjgreenberg/senior-engineering-partner
/plugin install senior-engineering-partner@bjgreenberg

Updates track the versioned Releases: refresh with /plugin marketplace update bjgreenberg and Claude Code offers the new version. Trade-off: plugin installs are copied into Claude Code's plugin cache and replaced wholesale on every update, so the per-user environment profile (references/my-environment.md, next section) cannot persist there — a plugin install always runs the universal core against the assumed baseline (macOS, Bash, GitHub, a secret manager, a scale-to-zero cloud target). That is the right default for most users; to customize the profile, use the clone install instead.

As a skill clone (customizable)

Claude Code also loads skills from ~/.claude/skills/. Clone this repo into that directory under the skill's own name:

git clone https://github.com/bjgreenberg/senior-engineering-partner \
  ~/.claude/skills/senior-engineering-partner

Then customize it for your environment (next section); update with a plain git pull in the clone.

Either way, invoke it with /senior-engineering-partner (optionally prefixed with a mode trigger word). The universal core works out of the box against the assumed baseline; the profile is what makes its guidance specific to you.

_{↑ Back to contents}

Using it with other AI tools (Codex, Gemini CLI, …)

None of this skill's content is Claude-specific (the few Claude-bound helpers are disclosed at the end of this section): the always-loaded core and every reference are plain Markdown, the mode triggers (REVIEW:, DEBUG:, …) are plain prompt conventions, and the packaging — a directory whose SKILL.md carries name + description frontmatter beside references/ and scripts/ — is the same Agent Skills format that OpenAI Codex and Google Gemini CLI (among a growing list of tools) now load natively. Portability tiers, most to least faithful:

• Agentic CLIs with native Agent Skills — drop-in. Codex CLI and Gemini CLI both read user-level skills from ~/.agents/skills/, so one clone serves both:

  git clone https://github.com/bjgreenberg/senior-engineering-partner \
    ~/.agents/skills/senior-engineering-partner
  

  Gemini CLI can also install straight from the repo URL (gemini skills install …), and both tools offer explicit invocation (/skills; $-mention in Codex) or implicit selection by the skill's description. Create references/my-environment.md from the template exactly as in the next section — that step is tool-agnostic.

• Agentic tools without skills support — via the context file. Any agent that reads the AGENTS.md standard (Cursor, Zed, Aider, GitHub Copilot's coding agent, and many others) or an equivalent (Gemini CLI's GEMINI.md) can carry the skill as standing instructions: point the context file at SKILL.md's body — copy it in, or a one-line "read SKILL.md in this directory and follow it" — keeping references/ adjacent so the "Read references/<topic>.md" directives resolve against the working tree.

• Chat products (Custom GPTs, Gemini Gems) — partial fidelity; know the trade. Instruction fields cap far below the core's size (a Custom GPT allows 8,000 characters of instructions plus 20 knowledge files), so the core can only ride along as uploaded knowledge — retrieved, not always-loaded, which weakens the skill's central design (non-negotiables guaranteed in context, detail read on demand). With no shell, the enforced half (run the gates, TDD red-first, verify-before-asserting with real commands) degrades to advice. Usable for EXPLAIN:-style consultation; not equivalent. A research product without file or shell access (e.g. Perplexity) isn't a meaningful target.

What stays Claude-specific, disclosed: the eval runner's judge drives the claude CLI (scenario responses are pluggable — scripts/run-evals.py --runner generic runs the same suite through any agent CLI via a command template + its instruction file; see Cross-CLI runs in evals/README.md); the repo's CI gates are GitHub Actions; and how reliably a given model follows ~80 KB of discipline varies by model — the recorded baselines in evals/baselines/ measure it per swept Claude model (each records its own baseline-vs-with-skill gap), and this README makes no equivalent claim for any model the suite hasn't swept.

_{↑ Back to contents}

Customize for your environment (my-environment.md)

The core is deliberately stack-agnostic — it carries no hosts, repos, employer, or machine specifics. Those live in one file you create from the shipped template:

cd ~/.claude/skills/senior-engineering-partner
cp references/my-environment.template.md references/my-environment.md
$EDITOR references/my-environment.md   # fill in your stack/hosts/Git standards/reference app

references/my-environment.md is .gitignored, so your real details are never committed — you can keep your fork's core in sync with this repo (git pull) without ever exposing your profile. The core instructs the assistant to read my-environment.md early and for any environment-specific claim, so the more complete it is, the more grounded the guidance.

_{↑ Back to contents}

Maintaining / contributing

• Versioning + releases are automated with release-please: it reads the Conventional Commits on main, opens a release PR that bumps the Version in SKILL.md's metadata table (and version/date-released in CITATION.cff) and prepends the entry to CHANGELOG.md. A maintainer enriches that entry's narrative, then cuts the signed tag + GitHub Release — the repo's tag-protection ruleset requires signed tags, so that final step is a deliberate manual one (see MAINTAINERS.md → Cutting a release). The skill's own documentation discipline, applied to itself.
• Diagrams are render-checked before commit: a Mermaid block that fails to render is a broken deliverable. Validate with GitHub/VS Code preview, mermaid.live, or @mermaid-js/mermaid-cli (mmdc) — see references/diagrams-and-visual-docs.md. CI runs scripts/render-diagrams.sh (the docs-render gate) on every PR.
• Helper scripts are ShellCheck-clean: a shellcheck gate lints scripts/*.sh on every PR (the skill's own "zero warnings is the standard" applied to itself). A script that trips ShellCheck is a broken deliverable and can't merge.
• No environment-specific leakage in the core: a leakage-guard check greps the tree against a denylist of personal/host/repo identifiers. It's two-tier: generic class-patterns (a CGNAT/Tailscale IP range, Obsidian-style wiki-links) ship in scripts/leakage-guard.sh and run in CI, while your literal identifiers live in an un-committed references/leakage-denylist.local (created from its .template) so the public repo never has to publish them to block them. Keep the universal core universal; anything specific belongs in your (un-committed) my-environment.md.
• Add or extend an evals/ scenario whenever you add a load-bearing rule — a lesson without a guarding eval can silently regress.
• The skill improves itself — with consent. SKILL.md carries the always-loaded trigger of an active, consent-gated self-improvement loop (full procedure: references/skill-self-improvement.md): when a session surfaces a rule-miss with real cost or a correction from the human, the model running the skill proposes the codified rule (worded to the authoring tests, with its guarding eval and origin story) and ships it only through this repo's normal PR + human-approval flow. It may add or sharpen rules, never relax them — loosening a discipline is human-initiated by definition.

_{↑ Back to contents}

Citing this repository

The repo ships a CITATION.cff (Citation File Format 1.2.0), so GitHub shows a Cite this repository button (APA/BibTeX) and the Zenodo–GitHub integration can populate a DOI record from it on release. Two rules keep it honest — the same stale-claim discipline as the badge row:

• version and date-released are bumped by release-please, never by hand — the x-release-please-version / x-release-please-date annotations in the file mark the lines it rewrites in each release PR (the same mechanism as SKILL.md's version stamp).
• The file is schema-validated as a gate: scripts/validate-citation.sh (digest-pinned cffconvert container) runs verbatim locally and as the required citation-validate CI check — an invalid citation file cannot merge.

_{↑ Back to contents}

License

Apache-2.0 © Brian Greenberg. See LICENSE and NOTICE.

Privacy: the plugin collects no data — no telemetry, no network calls, no tracking. The full statement lives in PRIVACY.md.

_{↑ Back to contents}

Disclaimer

This skill is provided as is, without warranty of any kind, under the Apache-2.0 license — see the Disclaimer of Warranty (§7) and Limitation of Liability (§8) sections of LICENSE. It offers engineering guidance, not professional security, legal, or compliance advice. Review and validate any code, configuration, or security decision it influences before relying on it — you are responsible for what you ship.

_{↑ Back to contents}