Skip to content
Back to search

senior-engineering-partner

A stack-agnostic Claude Code skill: strict code reviewer, pair programmer, debugger, and mentor (Python/Bash/Apps Script/JS). Security-first, phase-aware engineering discipline with a spec→plan→TDD→verify workflow.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bjgreenberg--senior-engineering-partner/badge.svg)](/listings/bjgreenberg--senior-engineering-partner)

HTML

<a href="/listings/bjgreenberg--senior-engineering-partner"><img src="/api/listings/bjgreenberg--senior-engineering-partner/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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`](.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](https://github.com/bjgreenberg/senior-engineering-partner/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](#customize-for-your-environment-my-environmentmd)) 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*.

<sub>[↑ Back to contents](#contents)</sub>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 29 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "bjgreenberg",
  3. "owner": {
  4. "name": "Brian Greenberg"
  5. },
  6. "description": "Claude Code plugins by Brian Greenberg",
  7. "plugins": [
  8. {
  9. "name": "senior-engineering-partner",
  10. "source": "./",
  11. "description": "A strict code reviewer, pair programmer, debugger, and mentor for Python, Bash, Google Apps Script, and JavaScript — a security-first, phase-aware engineering discipline with an enforced spec → plan → TDD → verify workflow.",
  12. "category": "engineering",
  13. "keywords": [
  14. "code-review",
  15. "security",
  16. "tdd",
  17. "debugging",
  18. "python",
  19. "bash"
  20. ],
  21. "author": {
  22. "name": "Brian Greenberg"
  23. },
  24. "homepage": "https://github.com/bjgreenberg/senior-engineering-partner",
  25. "repository": "https://github.com/bjgreenberg/senior-engineering-partner",
  26. "license": "Apache-2.0"
  27. }
  28. ]
  29. }
README.md · README · 466 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # senior-engineering-partner
  2. Last updated: 2026-11-05 02:59 PM CST
  3. [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  4. [![Latest release](https://img.shields.io/github/v/release/bjgreenberg/senior-engineering-partner?sort=semver&label=release)](https://github.com/bjgreenberg/senior-engineering-partner/releases)
  5. [![docs-render](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/docs-render.yml/badge.svg?branch=main)](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/docs-render.yml)
  6. [![leakage-guard](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/leakage-guard.yml/badge.svg?branch=main)](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/leakage-guard.yml)
  7. [![shellcheck](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/shellcheck.yml/badge.svg?branch=main)](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/shellcheck.yml)
  8. [![skill-lint](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/skill-lint.yml/badge.svg?branch=main)](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/skill-lint.yml)
  9. [![actions-lint](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/actions-lint.yml/badge.svg?branch=main)](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/actions-lint.yml)
  10. [![script-tests](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/script-tests.yml/badge.svg?branch=main)](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/script-tests.yml)
  11. [![citation-validate](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/citation-validate.yml/badge.svg?branch=main)](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/citation-validate.yml)
  12. [![plugin-validate](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/plugin-validate.yml/badge.svg?branch=main)](https://github.com/bjgreenberg/senior-engineering-partner/actions/workflows/plugin-validate.yml)
  13. [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/bjgreenberg/senior-engineering-partner/badge)](https://scorecard.dev/viewer/?uri=github.com/bjgreenberg/senior-engineering-partner)
  14. [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13458/badge)](https://www.bestpractices.dev/projects/13458)
  15. [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://www.conventionalcommits.org/en/v1.0.0/)
  16. A custom Claude Code skill: a strict **code reviewer, pair programmer, debugger, and mentor** for
  17. Python, Bash, Google Apps Script, JavaScript, and Swift/Apple platforms. It encodes a security-first,
  18. phase-aware engineering discipline — and an enforced **spec → plan → TDD → verify** workflow —
  19. as reusable instructions that activate via
  20. `/senior-engineering-partner` (or auto-activate when a task matches its description) in
  21. any Claude Code session.
  22. > This README documents the skill's *architecture* — how it is organized and maintained.
  23. > The skill's actual instructions live in [`SKILL.md`](SKILL.md); the deep, per-topic
  24. > standards live in [`references/`](references/).
  25. - **Author:** Brian Greenberg · **Web:** https://briangreenberg.net
  26. - **Version:** see the metadata table at the bottom of [`SKILL.md`](SKILL.md), the
  27. [`CHANGELOG.md`](CHANGELOG.md), and the
  28. [Releases](https://github.com/bjgreenberg/senior-engineering-partner/releases) page
  29. - **Invoke:** `/senior-engineering-partner` in Claude Code, optionally prefixed with a
  30. mode trigger word (see [Modes](#modes--triggers)).
  31. ## Contents
  32. - [What it is](#what-it-is)
  33. - [What it governs](#what-it-governs)
  34. - [Architecture](#architecture)
  35. - [Modes & triggers](#modes--triggers)
  36. - [The rigor ladder](#the-rigor-ladder)
  37. - [Reference catalog](#reference-catalog)
  38. - [Shipped helpers & evals](#shipped-helpers--evals)
  39. - [Install](#install)
  40. - [Using it with other AI tools (Codex, Gemini CLI, …)](#using-it-with-other-ai-tools-codex-gemini-cli-)
  41. - [Customize for your environment (my-environment.md)](#customize-for-your-environment-my-environmentmd)
  42. - [Maintaining / contributing](#maintaining--contributing)
  43. - [Citing this repository](#citing-this-repository)
  44. - [License](#license)
  45. - [Disclaimer](#disclaimer)
  46. ---
  47. ## What it is
  48. A single skill that does the heavy lifting of senior engineering work — design, write,
  49. test, review, debug, and document code — calibrated to the experience level you set in your
  50. environment profile. Three ideas run through everything:
  51. - **Phase-aware rigor, with a security floor that never moves.** Match effort to the
  52. project's phase (prototype → MVP → production), but never relax the
  53. secrets/injection/validation/isolation/authentication fundamentals. *Cheap ≠ insecure.*
  54. - **Deterministic-first, anti-hallucination discipline.** Verify before asserting (claims
  55. about the environment come from a tool run *this turn*), never invent flags/paths/APIs,
  56. and mechanize anything checkable (counting, parsing, regex, transforms) in a script
  57. rather than reasoning it out token-by-token.
  58. - **An enforced workflow, not just standards.** The skill doesn't only say what good looks
  59. like — it drives the loop that produces it: **spec-first** (agree what you're building
  60. before building it) → **plan** in verifiable steps → **tier-aware iron-law TDD** →
  61. **verify-before-done self-review**. Depth scales with the rigor tier; the loop does not.
  62. <sub>[↑ Back to contents](#contents)</sub>
  63. ---
  64. ## What it governs
  65. The disciplines are stack-agnostic, but they bind to concrete tooling. At a glance, what the skill
  66. carries standards for:
  67. - **Languages:** Python · Bash · Google Apps Script · JavaScript / TypeScript · Swift (macOS/iOS/watchOS/iPadOS)
  68. - **Source control & CI/CD:** GitHub · GitHub Actions · branch protection / rulesets · supply-chain gates (SBOM · SLSA · signing)
  69. - **Cloud & infra:** GCP / Cloud Run · Docker · Kubernetes · Terraform (IaC)
  70. - **Data:** Postgres / Supabase (RLS) · BigQuery · SQLite · caching
  71. - **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)
  72. - **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)
  73. - **Reliability & ops:** resilience engineering · disaster recovery & business continuity · scalability / system design · observability + incident response (DORA · SLOs)
  74. - **Platform-specific:** macOS app bundles / TCC · local & agentic AI tooling · diagrams-as-code (Mermaid)
  75. Each binds to a deep, **read-on-demand** reference (see the [catalog](#reference-catalog) below); your
  76. concrete hosts, projects, and stack live only in the private, un-committed `references/my-environment.md`.
  77. <sub>[↑ Back to contents](#contents)</sub>
  78. ---
  79. ## Architecture
  80. The skill is a **stack-agnostic universal core** (`SKILL.md`, always loaded) plus a
  81. **swappable environment profile** and a library of deep per-topic references read **on
  82. demand** (progressive disclosure — Claude reads a reference only when its trigger
  83. paragraph in `SKILL.md` says the work is relevant). Forking the skill for a different
  84. environment is a matter of replacing one file (`references/my-environment.md`).
  85. ```mermaid
  86. flowchart TD
  87. U["/senior-engineering-partner"] --> C
  88. C["SKILL.md — universal core<br/>modes · epistemic discipline · engineering workflow · rigor ladder<br/>security floor · coding standards · toolchain triggers"]
  89. C -->|"progressive disclosure: read a reference only when relevant"| R[(references/)]
  90. 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)"]
  91. R --> P["Environment profile<br/>my-environment.md (swap to re-home the skill)"]
  92. R --> W["Engineering process (5)<br/>engineering-workflow · debugging · audit-report-format · standards-authoring · skill-self-improvement"]
  93. R --> S["Security, privacy and compliance (7)"]
  94. R --> T["Testing and QA (3)"]
  95. R --> I["Cloud, infra, ops and logging (10) + data (2)"]
  96. R --> A["App toolchains, CI and collaboration (12)"]
  97. R --> X["UI, a11y, diagrams, AI tooling, macOS (5)"]
  98. ```
  99. `SKILL.md` carries the rules that must always be in context (the modes, the security
  100. floor, the rigor ladder, the coding/documentation/logging/SCM standards, and a short
  101. trigger paragraph per toolchain). Each trigger paragraph states the non-negotiables and
  102. points at the reference to **read before** doing related work — so the expensive detail
  103. is loaded only when it earns its place in the context window.
  104. <sub>[↑ Back to contents](#contents)</sub>
  105. ---
  106. ## Modes & triggers
  107. Behavior changes on a leading trigger word; with no trigger, it defaults to pair
  108. programming.
  109. ```mermaid
  110. flowchart TD
  111. P[User prompt] --> Q{Leading trigger word?}
  112. Q -->|"REVIEW:"| R["Strict senior code reviewer<br/>critique rigorously, then deliver the refactor"]
  113. Q -->|"EXPLAIN:"| E["Patient mentor<br/>teach the why, not just a copy-paste answer"]
  114. Q -->|"MVP: / PROTOTYPE:"| M["Lean-but-safe builder<br/>Tier 0/1, defer heavy gates, never the floor"]
  115. Q -->|"DEBUG:"| G["Systematic debugger<br/>reproduce, isolate, fix root cause, prove with a red-first test"]
  116. Q -->|"AUDIT:"| A["Report-first codebase auditor<br/>severity-ranked findings report; fixes only after review"]
  117. Q -->|none| D["Collaborative pair programmer (default)<br/>clean, tested, documented, production-ready code"]
  118. ```
  119. | Trigger | Mode | What it does |
  120. |---|---|---|
  121. | *(none)* | **Pair programmer** | Do the work — production-ready code with tests + docs, concise explanation. |
  122. | `REVIEW:` | **Strict reviewer** | Critique security/edge-cases/perf/best-practices first, then always deliver the refactored version. |
  123. | `EXPLAIN:` | **Mentor** | Educate step-by-step, calibrate to the user's level, prioritize understanding. |
  124. | `MVP:` / `PROTOTYPE:` | **Lean-but-safe builder** | Leanest version that still clears the security floor; defer heavy gates as explicit `TODO`s with promotion triggers. |
  125. | `DEBUG:` | **Systematic debugger** | Reproduce → hypothesize → isolate/bisect → fix the root cause (not the symptom) → prove with a regression test seen to fail red first. |
  126. | `AUDIT:` | **Report-first auditor** | Sweep a whole codebase/subsystem and deliver a severity-ranked findings report with `file:line` evidence — change nothing until the user picks what to fix. |
  127. <sub>[↑ Back to contents](#contents)</sub>
  128. ---
  129. ## The rigor ladder
  130. Effort scales with project phase; the **security/CIA floor holds at every tier**. Only
  131. verification depth, redundancy, and operational maturity scale.
  132. ```mermaid
  133. flowchart LR
  134. T0["Tier 0 — Prototype<br/>throwaway, never real tenant data"]
  135. T1["Tier 1 — MVP / early product<br/>critical-path tests, basic CI, secrets manager, authn, backups"]
  136. T2["Tier 2 — Production / commercial / multi-tenant<br/>full strict posture, every merge-blocking gate"]
  137. Floor["Security / CIA floor — CONSTANT at every tier<br/>no hardcoded secrets · validate inputs · no injection · isolated env · authn · vetted deps"]
  138. T0 -->|"real users / small scale"| T1
  139. T1 -->|"customers · money · multi-tenant · PII · 2nd contributor · public exposure"| T2
  140. Floor -.underpins.-> T0
  141. Floor -.underpins.-> T1
  142. Floor -.underpins.-> T2
  143. ```
  144. Crossing any promotion trigger (real customer/tenant data, money changing hands,
  145. multi-tenant isolation, regulated/PII data, a second contributor, public internet
  146. exposure) re-rates the project up a tier — it is not optional polish.
  147. <sub>[↑ Back to contents](#contents)</sub>
  148. ---
  149. ## Reference catalog
  150. Deep standards, read on demand. Each carries verify-against-live-docs caveats on
  151. version-specific commands.
  152. | Group | Reference | Covers |
  153. |---|---|---|
  154. | **Environment profile** | `my-environment.md` | The concrete stack/hosts/repos/house-Git-standards — the one file to swap when forking the skill |
  155. | **Engineering process** | `engineering-workflow.md` | The spec → plan → tier-aware iron-law TDD → verify-before-done self-review loop |
  156. | | `debugging.md` | Systematic root-cause method (the `DEBUG:` mode): read the logs first, then reproduce → hypothesize → isolate → fix cause → red-first regression test |
  157. | | `audit-report-format.md` | The `AUDIT:` mode deliverable: a severity-ranked findings report (finding schema, severity taxonomy, mechanize-the-checkable, lead-with-verified-strengths) |
  158. | | `standards-authoring.md` | Distill sprawling project conventions into a checkable standards set (extract → filter → human-approve → classify floor-vs-overridable); prose-first, format-agnostic |
  159. | | `skill-self-improvement.md` | The consent-gated loop's full procedure: classify (pattern / one-off / irreversible-cost), the three-part proposal package (rule + guarding eval + origin story), ship-through-PR, never-relax, the non-maintainer path |
  160. | **Security, privacy & compliance** | `threat-modeling-and-api-design.md` | In-PR STRIDE threat models + attack-surface-shrinking API design |
  161. | | `secure-data-processing.md` | Hostile-file parsing, prompt-injection fencing (two-zone worked example), RAG/vector-store isolation, multi-tenant data handling |
  162. | | `frontend-web-security.md` | Token storage, CSP, output sanitization, security headers |
  163. | | `secrets-and-key-rotation.md` | Rotation lifecycle, zero-downtime overlap, KMS key-version re-wrap |
  164. | | `action-identity-and-audit.md` | Every action identified, signed, recorded: threat model, enforce-not-record, the agent's own code-host identity, a session-id trailer (never a host name on a public artifact), hash-chained off-host action log, provenance, drills, fleet conformance gate |
  165. | | `data-protection.md` | GDPR/UK-GDPR/CCPA as code: DSAR, erasure cascade, retention, DPIA |
  166. | | `compliance.md` | NIST CSF 2.0 + **SSDF (800-218)** / OWASP / SOC 2 / **Well-Architected** as enforceable review checklists, incl. crypto-agility + **post-quantum readiness** (FIPS 203–205, harvest-now-decrypt-later triage) |
  167. | | `agentic-ai-security.md` | Products that ARE agents: least agency, human-in-the-loop on the resolved call, memory as a poisoning surface, OWASP Agentic Top 10 + CSA MAESTRO mapping |
  168. | **Testing & QA** | `testing.md` | The enforced merge-gate taxonomy, tenant-isolation tests, the monitor→comment→block gate-introduction ladder, coverage/mutation/load tiers, frontend testing (behavior-not-implementation, network-boundary mocks, E2E/a11y gates) |
  169. | | `testing-single-file.md` | The `conftest.py` argv-patch pattern for single-file scripts |
  170. | | `maintainability-metrics.md` | Complexity (cognitive, not cyclomatic) + structural duplication as committed-threshold gates; legacy ratchet; tool bindings incl. the qlty BUSL license note |
  171. | **Cloud, infra & ops** | `gcp.md` | Cloud Run, GCS, BigQuery, Secret Manager, IAM (no SA keys → Workload Identity) |
  172. | | `iac-terraform.md` | Terraform on GCP, locked remote state, OIDC deployer, plan-as-gate |
  173. | | `containers-and-orchestration.md` | Docker/Kubernetes: digest pins, non-root, scanning, securityContext |
  174. | | `observability-and-incident-response.md` | Structured logs + correlation id, RED/USE metrics, SLO burn-rate alerting + severity-routed channels, client-side/RUM monitoring, incident lifecycle |
  175. | | `disaster-recovery.md` | 3-2-1-1-0 immutable backups (Bucket Lock, not just versioning), out-of-domain copies, verified PITR, scheduled restore drills, local/sync-≠-backup |
  176. | | `business-continuity.md` | BIA → justified RTO/RPO, provider-outage plans, comms/decision plan, the solo-operator/bus-factor path |
  177. | | `resilience-engineering.md` | Degrade-don't-die in code: timeouts, circuit breaker, bulkhead, load-shed, designed degraded modes, kill-switch |
  178. | | `scalability-and-system-design.md` | The "-ilities": statelessness for horizontal scale, queue+worker, DLQ, transactional outbox, the pool/N+1/hot-partition ceilings, capacity & perf targets |
  179. | | `logging-and-monitoring.md` | Reading the logs as a Definition-of-Done gate (subsystem-scoped *and* not-subsystem-scoped, never-report-clean-without-the-command, empty ≠ clean), structured logging in Python (JSON + `contextvars` correlation id, per-stack loggers), log location/rotation, the launchd open-fd gotcha, unattended-job monitor design |
  180. | **Data** | `databases.md` | Postgres/Supabase RLS (+ pgTAP), BigQuery, SQLite, migrations |
  181. | | `caching.md` | Cache-key-must-encode-the-tenant, invalidation, what-not-to-cache |
  182. | **App toolchains, CI & collaboration** | `python-web-apis.md` | FastAPI/Uvicorn/psycopg: lifespan, Pydantic, auth-as-`Depends`, RLS pipeline |
  183. | | `github-actions.md` | Least-priv `permissions`, SHA-pinned actions, multi-gate pipelines (audit on PRs and a daily schedule — with the 60-idle-day caveat that makes the central sweep the standing check — typecheck/lint over the whole tree, no file paths), the Swift/Apple job shape (macOS runners, pinned resolution, ASC-API-key signing), SBOM + build-provenance attestation, gated deploy + canary + release automation |
  184. | | `github-teams.md` | Team-grade repo hygiene (required gates, CODEOWNERS, review every agent PR) |
  185. | | `package-managers.md` | Brewfile/npm/mas — reproducible pinned manifests, supply-chain vetting; the daily re-scan of every repo (idle and still-deploying archived ones included) and every administered host, the sources by role (OSV/GHSA, CISA KEV first, EPSS, the vendor channel, NVD last), fix SLAs (KEV/critical same day, high 24 h, rest 7 days) and the bounded security-fix merge lane (fixed version, past the cooldown, green CI + contract test, veto-only reviewer checking provenance) |
  186. | | `dev-environments.md` | VS Code/Xcode/Antigravity hygiene, extension vetting, signing |
  187. | | `dev-environment-isolation.md` | Never dev against prod, per-project venv/container, sandbox untrusted code |
  188. | | `foss-adoption.md` | Vet FOSS before adopting (license/Scorecard/CVEs) + pin/lock/contract-test; bot update PRs never merge on green alone — the bounded security-fix lane vs the human-reviewed, cooldown-gated freshness lane |
  189. | | `multi-agent-coordination.md` | The concurrency override when >1 writer shares a repo |
  190. | | `python-typing-and-packaging.md` | The TypedDict worked example, the whole-tree gate config (mypy/ruff/bandit/pytest scoped to the tree by config, tests and scripts included, never a hand-kept file list) verified by file count against `git ls-files`, and the single-file→package target layout |
  191. | | `google-apps-script.md` | `clasp` + git over the editor, minimal `oauthScopes`, `PropertiesService` secrets/limits, `LockService`, trigger quotas + the 6-min wall, Advanced Services vs `UrlFetchApp`, `console`→Cloud Logging, pure-logic isolation for testing |
  192. | | `javascript-and-typescript.md` | TS strict mode (the `mypy --strict` analog) + the flags `strict` misses, runtime-validated typed boundaries (the Pydantic analog), Node `SIGTERM`/no-floating-promises patterns |
  193. | | `bash-scripting.md` | Strict mode's documented gaps (`-e` suspension, masked substitutions), traps/atomic output/locks, `curl -f`, stock-bash-3.2 portability, BATS + command stubs |
  194. | | `swift-apple-development.md` | XcodeGen `project.yml` as source of truth, SwiftPM pure-logic packages, headless provisioning, never-store-ticks state design, the `CKSyncEngine` hard rules, Swift 6 concurrency field notes, `log stream`/`.ips` diagnosis — plus the enforcement lane: SwiftLint/`swift format`/compiler gates, committed `Package.resolved` + `osv-scanner` audit, the Apple security-floor bindings (Keychain, sandbox/entitlements, ATS, privacy manifests, entry-surface validation), Swift Testing/XCTest + `xccov` coverage gate, CI wiring |
  195. | **UI, docs & AI tooling** | `ui-design-and-accessibility.md` | Responsive + light/dark + WCAG 2.2 AA + Claude Design handoff |
  196. | | `diagrams-and-visual-docs.md` | Diagrams-as-code, Mermaid-first; render-check before commit |
  197. | | `local-and-agentic-ai-tools.md` | Agentic assistants + self-hosted LLMs (Ollama/Open WebUI) |
  198. | | `llm-apps.md` | Building software that contains model calls: the five workflow patterns, evaluator-optimizer preconditions, the agent loop (verify every iteration), stopping criteria + cost budgets, RAG as architecture (retriever evals, index as derived cache), evals as the outer loop |
  199. | | `macos-app-bundles.md` | LaunchAgent `.app` bundles, TCC/FDA, the compiled-launcher requirement |
  200. <sub>[↑ Back to contents](#contents)</sub>
  201. ---
  202. ## Shipped helpers & evals
  203. Beyond the always-loaded core and the read-on-demand references, the skill ships two
  204. support directories:
  205. - **`scripts/`** — the utility scripts the disciplines reference, shipped so they're
  206. *executed*, not regenerated: `audit.sh` (manifest-level dependency-audit gate),
  207. `render-diagrams.sh` (the `docs-render` Mermaid render-check), `validate-citation.sh`
  208. (the `citation-validate` CFF schema check), `leakage-guard.sh` (the two-tier
  209. environment-identifier gate), `actions-lint.sh` (the workflow gate: checksum-verified
  210. `actionlint` + pinned `zizmor` — **green-optional by explicit decision**, on the
  211. `testing.md` §3d introduction ladder; promotion to required is a recorded maintainer
  212. call), `run-evals.py` (the eval-suite runner — below), `eval-guard.py` (the
  213. substantive-SKILL.md-change-needs-an-eval gate), `curate-baseline.py` (slims a sweep
  214. into a committable baseline), `skill-lint.py` (name/description/word-budget/
  215. reference-integrity), and `self-review.md` (the verify-before-done checklist).
  216. Pin `render-diagrams.sh`'s `MMDC_IMAGE` to a digest before relying on it.
  217. - **`evals/`** — a regression suite. Each `scenarios/*.json` encodes a real miss from the
  218. changelog as a checkable expectation, in Anthropic's evaluation shape. `evals/README.md`
  219. documents the baseline-then-iterate (Claude-A authors / Claude-B tests) loop, and
  220. **`scripts/run-evals.py` executes the suite**: it runs each `query` headlessly through the
  221. `claude` CLI (with the skill injected, or bare for a baseline) — or through any other agent
  222. CLI via `--runner generic` — LLM-judges the response
  223. against `expected_behavior`/`anti_behavior`, and writes per-scenario verdicts + a summary
  224. (see *How to run* and *Cross-CLI runs* in `evals/README.md`). **Add or
  225. extend a scenario whenever a new changelog entry is written from a real miss** — a lesson
  226. without a guarding eval can silently regress.
  227. <sub>[↑ Back to contents](#contents)</sub>
  228. ---
  229. ## Install
  230. Two ways into Claude Code — pick **one** (a side-by-side plugin install and skill clone
  231. would load the skill twice):
  232. ### As a plugin (quickest)
  233. The repo doubles as its own single-plugin marketplace
  234. ([`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json)), so two commands
  235. inside Claude Code install it:
  236. ```
  237. /plugin marketplace add bjgreenberg/senior-engineering-partner
  238. /plugin install senior-engineering-partner@bjgreenberg
  239. ```
  240. Updates track the versioned
  241. [Releases](https://github.com/bjgreenberg/senior-engineering-partner/releases): refresh
  242. with `/plugin marketplace update bjgreenberg` and Claude Code offers the new version.
  243. **Trade-off:** plugin installs are copied into Claude Code's plugin cache and replaced
  244. wholesale on every update, so the per-user environment profile
  245. (`references/my-environment.md`, [next section](#customize-for-your-environment-my-environmentmd))
  246. cannot persist there — a plugin install always runs the universal core against the assumed
  247. baseline (macOS, Bash, GitHub, a secret manager, a scale-to-zero cloud target). That is the
  248. right default for most users; to customize the profile, use the clone install instead.
  249. ### As a skill clone (customizable)
  250. Claude Code also loads skills from `~/.claude/skills/`. Clone this repo into that
  251. directory under the skill's own name:
  252. ```bash
  253. git clone https://github.com/bjgreenberg/senior-engineering-partner \
  254. ~/.claude/skills/senior-engineering-partner
  255. ```
  256. Then **customize it for your environment** (next section); update with a plain `git pull`
  257. in the clone.
  258. Either way, invoke it with `/senior-engineering-partner` (optionally prefixed with a mode
  259. trigger word). The universal core works out of the box against the assumed baseline; the
  260. profile is what makes its guidance specific to *you*.
  261. <sub>[↑ Back to contents](#contents)</sub>
  262. ## Using it with other AI tools (Codex, Gemini CLI, …)
  263. None of this skill's *content* is Claude-specific (the few Claude-bound helpers are
  264. disclosed at the end of this section): the always-loaded core and every reference are
  265. plain Markdown, the mode triggers (`REVIEW:`, `DEBUG:`, …) are plain prompt conventions, and
  266. the packaging — a directory whose `SKILL.md` carries `name` + `description` frontmatter
  267. beside `references/` and `scripts/` — is the same **Agent Skills format** that OpenAI Codex
  268. and Google Gemini CLI (among a growing list of tools) now load natively. Portability tiers,
  269. most to least faithful:
  270. - **Agentic CLIs with native Agent Skills — drop-in.** Codex CLI and Gemini CLI both read
  271. user-level skills from `~/.agents/skills/`, so one clone serves both:
  272. ```bash
  273. git clone https://github.com/bjgreenberg/senior-engineering-partner \
  274. ~/.agents/skills/senior-engineering-partner
  275. ```
  276. Gemini CLI can also install straight from the repo URL (`gemini skills install …`), and
  277. both tools offer explicit invocation (`/skills`; `$`-mention in Codex) or implicit
  278. selection by the skill's `description`. Create `references/my-environment.md` from the
  279. template exactly as in the next section — that step is tool-agnostic.
  280. - **Agentic tools without skills support — via the context file.** Any agent that reads
  281. the [`AGENTS.md` standard](https://agents.md/) (Cursor, Zed, Aider, GitHub Copilot's coding agent, and
  282. many others) or an equivalent (Gemini CLI's `GEMINI.md`) can carry the skill as standing
  283. instructions: point the context file at `SKILL.md`'s body — copy it in, or a one-line
  284. "read `SKILL.md` in this directory and follow it" — keeping `references/` adjacent so the
  285. "Read `references/<topic>.md`" directives resolve against the working tree.
  286. - **Chat products (Custom GPTs, Gemini Gems) — partial fidelity; know the trade.**
  287. Instruction fields cap far below the core's size (a Custom GPT allows 8,000 characters of
  288. instructions plus 20 knowledge files), so the core can only ride along as uploaded
  289. knowledge — *retrieved*, not always-loaded, which weakens the skill's central design
  290. (non-negotiables guaranteed in context, detail read on demand). With no shell, the
  291. enforced half (run the gates, TDD red-first, verify-before-asserting with real commands)
  292. degrades to advice. Usable for `EXPLAIN:`-style consultation; not equivalent. A research
  293. product without file or shell access (e.g. Perplexity) isn't a meaningful target.
  294. What stays Claude-specific, disclosed: the eval runner's **judge** drives the `claude` CLI
  295. (scenario responses are pluggable — `scripts/run-evals.py --runner generic` runs the same
  296. suite through any agent CLI via a command template + its instruction file; see *Cross-CLI
  297. runs* in `evals/README.md`); the repo's CI gates are GitHub Actions; and how reliably a
  298. given model *follows* ~80 KB of discipline varies **by model** — the recorded baselines in
  299. [`evals/baselines/`](evals/baselines/) measure it per swept Claude model (each records its
  300. own baseline-vs-with-skill gap), and this README makes no equivalent claim for any model
  301. the suite hasn't swept.
  302. <sub>[↑ Back to contents](#contents)</sub>
  303. ## Customize for your environment (`my-environment.md`)
  304. The core is deliberately **stack-agnostic** — it carries no hosts, repos, employer, or
  305. machine specifics. Those live in one file you create from the shipped template:
  306. ```bash
  307. cd ~/.claude/skills/senior-engineering-partner
  308. cp references/my-environment.template.md references/my-environment.md
  309. $EDITOR references/my-environment.md # fill in your stack/hosts/Git standards/reference app
  310. ```
  311. `references/my-environment.md` is `.gitignore`d, so your real details are never committed —
  312. you can keep your fork's core in sync with this repo (`git pull`) without ever exposing your
  313. profile. The core instructs the assistant to **read `my-environment.md` early and for any
  314. environment-specific claim**, so the more complete it is, the more grounded the guidance.
  315. <sub>[↑ Back to contents](#contents)</sub>
  316. ## Maintaining / contributing
  317. - **Versioning + releases are automated** with
  318. [release-please](https://github.com/googleapis/release-please): it reads the Conventional
  319. Commits on `main`, opens a release PR that bumps the `Version` in `SKILL.md`'s metadata table
  320. (and `version`/`date-released` in [`CITATION.cff`](CITATION.cff))
  321. and prepends the entry to [`CHANGELOG.md`](CHANGELOG.md). A maintainer enriches that entry's
  322. narrative, then cuts the **signed** tag + GitHub Release — the repo's `tag-protection` ruleset
  323. requires signed tags, so that final step is a deliberate manual one (see
  324. [`MAINTAINERS.md`](MAINTAINERS.md) → *Cutting a release*). The skill's own documentation
  325. discipline, applied to itself.
  326. - **Diagrams are render-checked before commit:** a Mermaid block that fails to render is a
  327. broken deliverable. Validate with GitHub/VS Code preview, mermaid.live, or
  328. `@mermaid-js/mermaid-cli` (`mmdc`) — see
  329. [`references/diagrams-and-visual-docs.md`](references/diagrams-and-visual-docs.md). CI
  330. runs `scripts/render-diagrams.sh` (the `docs-render` gate) on every PR.
  331. - **Helper scripts are ShellCheck-clean:** a `shellcheck` gate lints `scripts/*.sh` on every PR
  332. (the skill's own "zero warnings is the standard" applied to itself). A script that trips
  333. ShellCheck is a broken deliverable and can't merge.
  334. - **No environment-specific leakage in the core:** a `leakage-guard` check greps the tree against
  335. a denylist of personal/host/repo identifiers. It's **two-tier**: generic class-patterns (a
  336. CGNAT/Tailscale IP range, Obsidian-style wiki-links) ship in `scripts/leakage-guard.sh` and run in CI,
  337. while your *literal* identifiers live in an un-committed `references/leakage-denylist.local`
  338. (created from its `.template`) so the public repo never has to publish them to block them. Keep
  339. the universal core universal; anything specific belongs in your (un-committed) `my-environment.md`.
  340. - **Add or extend an `evals/` scenario** whenever you add a load-bearing rule — a lesson
  341. without a guarding eval can silently regress.
  342. - **Every decision about the skill opens with its expert panel.** The maintainer keeps the
  343. panel privately; [`docs/expert-panel.md`](docs/expert-panel.md) explains the rule, how a
  344. forker keeps their own, and the public evidence a decision cites.
  345. - **The skill improves itself — with consent.** `SKILL.md` carries the always-loaded trigger
  346. of an active, consent-gated self-improvement loop (full procedure:
  347. [`references/skill-self-improvement.md`](references/skill-self-improvement.md)): when a
  348. session surfaces a rule-miss with real cost or a correction from the human, the model
  349. running the skill *proposes* the codified rule (worded to the authoring tests, with its
  350. guarding eval and origin story) and ships it only through this repo's normal PR +
  351. human-approval flow. It may add or sharpen rules, never relax them — loosening a
  352. discipline is human-initiated by definition.
  353. <sub>[↑ Back to contents](#contents)</sub>
  354. ## Citing this repository
  355. The repo ships a [`CITATION.cff`](CITATION.cff)
  356. ([Citation File Format](https://citation-file-format.github.io/) 1.2.0), so GitHub shows a
  357. **Cite this repository** button (APA/BibTeX) and the
  358. [Zenodo–GitHub integration](https://help.zenodo.org/docs/github/describe-software/citation-file/)
  359. can populate a DOI record from it on release. Two rules keep it honest — the same
  360. stale-claim discipline as the badge row:
  361. - **`version` and `date-released` are bumped by release-please, never by hand** — the
  362. `x-release-please-version` / `x-release-please-date` annotations in the file mark the
  363. lines it rewrites in each release PR (the same mechanism as `SKILL.md`'s version stamp).
  364. - **The file is schema-validated as a gate**: `scripts/validate-citation.sh` (digest-pinned
  365. `cffconvert` container) runs verbatim locally and as the **required** `citation-validate`
  366. CI check — an invalid citation file cannot merge.
  367. <sub>[↑ Back to contents](#contents)</sub>
  368. ## License
  369. Apache-2.0 © Brian Greenberg. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
  370. Privacy: the plugin collects no data — no telemetry, no network calls, no tracking. The
  371. full statement lives in [`PRIVACY.md`](PRIVACY.md).
  372. <sub>[↑ Back to contents](#contents)</sub>
  373. ## Disclaimer
  374. This skill is provided **as is**, without warranty of any kind, under the Apache-2.0 license —
  375. see the *Disclaimer of Warranty* (§7) and *Limitation of Liability* (§8) sections of
  376. [`LICENSE`](LICENSE). It offers **engineering guidance, not professional security, legal, or
  377. compliance advice**. Review and validate any code, configuration, or security decision it
  378. influences before relying on it — you are responsible for what you ship.
  379. <sub>[↑ Back to contents](#contents)</sub>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.