senior-engineering-partner

Last updated: 2026-06-30 07:40 PM CDT

A custom Claude Code skill: a strict code reviewer, pair programmer, debugger, and mentor for Python, Bash, Google Apps Script, and JavaScript. 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).

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.

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
• 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
• 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
• 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.

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 · self-review)<br/>evals/ (27 regression scenarios)"]
    R --> P["Environment profile<br/>my-environment.md (swap to re-home the skill)"]
    R --> W["Engineering process (4)<br/>engineering-workflow · debugging · audit-report-format · standards-authoring"]
    R --> S["Security, privacy and compliance (6)"]
    R --> T["Testing and QA (2)"]
    R --> I["Cloud, infra and ops (9) + data (2)"]
    R --> A["App toolchains, CI and collaboration (11)"]
    R --> X["UI, a11y, diagrams, AI tooling, macOS (4)"]

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.

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 -->|none| D["Collaborative pair programmer (default)<br/>clean, tested, documented, production-ready code"]

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.

Reference catalog

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

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), 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. 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.

Install

Claude Code loads skills from ~/.claude/skills/. Install by cloning 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) and 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 (macOS, Bash, GitHub, a secret manager, a scale-to-zero cloud target); the profile is what makes its guidance specific to you.

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.

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 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.
• 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.

License

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

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.