![doctrine](./assets/banner-v6.png)

<p align="center">
  <a href="https://aethrox.github.io/doctrine/"><img alt="Documentation: Doctrine Wiki" src="https://img.shields.io/badge/docs-Doctrine%20Wiki-7C3AED.svg"></a>
  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
  <a href="https://github.com/sponsors/aethrox"><img alt="GitHub Sponsors" src="https://img.shields.io/badge/sponsor-GitHub%20Sponsors-EA4AAA?logo=githubsponsors&logoColor=white"></a>
</p>

Software engineering discipline grounded in named primary standards (OWASP, ITIL, IETF RFCs, ISO, BABOK, SBAR, and more) instead of invented convention. 34 skills covering the software development lifecycle: TDD, code review, incident response, domain modeling, deployment, dependency management, and more.

New to Doctrine? Start with the bilingual [Doctrine Wiki](https://aethrox.github.io/doctrine/).

Three ways to use it, depending on your tool:

## Option 1: Claude Code plugin

Native install for Claude Code: the right skill is auto-invoked from its description, no manual copying.

```bash
/plugin marketplace add aethrox/doctrine
/plugin install doctrine
```

Toggle it off later from `enabledPlugins` in `~/.claude/settings.json`, same as any other plugin.

## Option 2: MCP server (Claude Desktop, Cursor, Windsurf, Cline, and anything else that speaks MCP)

Requires Node.js >= 18.

Every skill is exposed as an MCP **prompt**: the same content, reachable from any MCP-capable client, not just Claude Code. Add it as a local MCP server:

```json
{
  "mcpServers": {
    "doctrine": {
      "command": "npx",
      "args": ["-y", "github:aethrox/doctrine"]
    }
  }
}
```

(Exact config location and format differ per client; Claude Desktop's `claude_desktop_config.json`, Cursor's `.cursor/mcp.json`, etc., but the `command`/`args` above are the same everywhere.)

Run it directly to confirm it works:

```bash
npx github:aethrox/doctrine
```

## Option 3: manual copy (no plugin system, no MCP client)

```bash
git clone https://github.com/aethrox/doctrine.git
mkdir -p ~/.claude/skills
for s in doctrine/skills/*/; do
  name=$(basename "$s")
  cp -r "$s" ~/.claude/skills/"$name"/
done
```

Re-run after pulling updates to resync.

## How it works

Every skill follows the same shape: a one-sentence defining constraint (the fact that makes it behave differently from the obvious default), a numbered set of phases with concrete, checkable rules, and a closing checklist. The skills combine named external standards and established practices with clearly labeled Doctrine policy defaults.

See [WORKFLOW.md](./WORKFLOW.md) for how the 34 skills relate to each other: the lifecycle they map to, which ones cross-reference which, and a worked example.

## Skills

| Skill | Standard(s) it encodes | Covers |
|---|---|---|
| [release-versioning](./skills/release-versioning/SKILL.md) | [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), [Semantic Versioning](https://semver.org/spec/v2.0.0.html), [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), trunk-based development | Commit classification, version bump, changelog entry, branching model |
| [secure-coding](./skills/secure-coding/SKILL.md) | [OWASP Top 10](https://owasp.org/www-project-top-ten/), SCA and secret-scanning practice | Injection classes, access control, secrets, dependency and supply-chain risk, safe error handling |
| [observability](./skills/observability/SKILL.md) | Google SRE golden signals, SLI/SLO/error budget, the RED method | Structured logging, the four golden signals, SLO definition, alert and runbook discipline |
| [safe-deployment](./skills/safe-deployment/SKILL.md) | Progressive delivery, canary/blue-green/rolling, expand-contract migrations | Decoupling deploy from release, rollout strategy choice, rollback triggers defined up front |
| [api-design-standards](./skills/api-design-standards/SKILL.md) | Microsoft/Google REST guidelines, consumer-driven contract testing | Resource/URL conventions, versioning strategy, backward-compatible vs breaking changes, contract testing |
| [dependency-upgrade-management](./skills/dependency-upgrade-management/SKILL.md) | SBOM (CycloneDX/SPDX), [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html)/[9745](https://www.rfc-editor.org/rfc/rfc9745.html) deprecation headers, Dependabot/Renovate cadence practice | Dependency inventory, security vs routine vs major-upgrade lanes, deprecation windows, safe major-version migration |
| [incident-response](./skills/incident-response/SKILL.md) | Google SRE incident management guide, blameless postmortem culture | Severity/declaration, IC/comms/ops roles, mitigate-before-root-cause, blameless postmortem structure |
| [test-strategy](./skills/test-strategy/SKILL.md) | Test data management practice, flaky-test quarantine practice | Synthetic vs anonymized production test data, flaky-test quarantine policy, integration/e2e boundary decisions |
| [code-style-lint](./skills/code-style-lint/SKILL.md) | Established per-language formatters (gofmt, rustfmt, black, prettier), pre-commit/CI enforcement practice | Adopting the ecosystem standard, opinionated over configurable, pre-commit + CI enforcement layers, linting vs formatting |
| [tdd](./skills/tdd/SKILL.md) | Kent Beck's red-green-refactor, the testing pyramid, Fowler's test-double taxonomy, FIRST properties | The TDD cycle, what makes a test worth keeping, choosing the right test double, shaping a suite |
| [code-review](./skills/code-review/SKILL.md) | Google's Engineering Practices code review guide, Fowler's code-smell catalog | Improve-over-perfect approval bar, naming smells instead of vague complaints, small-PR discipline, review etiquette |
| [diagnosing-bugs](./skills/diagnosing-bugs/SKILL.md) | David Agans' *Debugging: The 9 Indispensable Rules* | Reproduce reliably, bisect the search space, change one variable at a time, audit trail, verify the fix against the original failure |
| [domain-modeling](./skills/domain-modeling/SKILL.md) | Eric Evans' Domain-Driven Design, Michael Nygard's ADR format | Ubiquitous language, bounded contexts and translation at boundaries, one-page ADRs, keeping the model current |
| [codebase-design](./skills/codebase-design/SKILL.md) | John Ousterhout's *A Philosophy of Software Design* | Depth as the design metric, information hiding vs. leakage, concrete shallow-module red flags, designing it twice |
| [resolving-merge-conflicts](./skills/resolving-merge-conflicts/SKILL.md) | Git's three-way merge model | Resolving hunks by tracing both sides' intent, avoiding whole-file --ours/--theirs, verifying before finishing, merge vs. rebase |
| [spec-to-tickets](./skills/spec-to-tickets/SKILL.md) | INVEST criteria, tracer-bullet development, Definition of Ready/Done | Synthesizing a spec, slicing tracer-bullet tickets with blocking edges, INVEST checks, Ready/Done gates, handoff to tdd/code-review |
| [prototype](./skills/prototype/SKILL.md) | Kent Beck/Ward Cunningham's spike solution (Extreme Programming) | Naming the one question a spike answers, timeboxing it, building disposable code, recording the verdict and discarding the code |
| [research](./skills/research/SKILL.md) | Primary-source citation practice, the CRAAP source-evaluation test | Scoping a checkable question, tracing claims to primary sources, weighing source credibility, citing findings in a saved file |
| [triage](./skills/triage/SKILL.md) | ITIL incident priority matrix (Impact x Urgency) | Classifying bug vs. enhancement, scoring impact and urgency independently, verifying before prioritizing, routing to needs-info/ready-to-spec/scheduled/wontfix |
| [improve-codebase-architecture](./skills/improve-codebase-architecture/SKILL.md) | Fowler's Technical Debt Quadrant, layered on `codebase-design`'s Ousterhout grounding | Scoping a scan, finding shallow-module red flags, classifying findings by how debt was incurred, prioritizing by leave-cost, recording declined findings as ADRs |
| [wayfinder](./skills/wayfinder/SKILL.md) | The RFC process (IETF/Rust-style engineering decision records) | Naming the destination, charting open decisions breadth-first, resolving one at a time with recorded reasoning, tracking decided/open/unspecified/out-of-scope, handoff to spec-to-tickets |
| [grilling](./skills/grilling/SKILL.md) | BABOK elicitation techniques (structured interviews, confirm elicitation results) | Mapping the known/needed gap before asking, frontier-round questioning, resolving facts by lookup not by asking, confirming answers before treating them as settled |
| [handoff](./skills/handoff/SKILL.md) | SBAR (Situation-Background-Assessment-Recommendation) handoff communication standard | Structuring a handoff into Situation/Background/Assessment/Recommendation, naming what's already ruled out, confirming receipt via read-back |
| [teach](./skills/teach/SKILL.md) | Bloom's Taxonomy, the worked-example effect and fading (cognitive load theory) | Placing the target and learner's cognitive level, opening with a fully worked example, fading scaffolding in stages, matching method to level, checking retention over fluency |
| [to-questionnaire](./skills/to-questionnaire/SKILL.md) | Survey-design practice: leading/loaded question avoidance, closed vs. open question choice, balanced Likert-scale construction | Scoping the send (recipient, gap), choosing closed vs. open per question, avoiding leading/loaded/compound questions, balancing rating scales, assembling the document |
| [wait-what](./skills/wait-what/SKILL.md) | [ISO 24495-1:2023](https://www.iso.org/standard/78907.html) Plain Language standard (Relevant/Findable/Understandable/Actionable) | Recognizing a missed-explanation signal, re-pitching instead of repeating, applying all four RFUA principles, keeping vocabulary consistent, confirming it landed |
| [writing-for-agents](./skills/writing-for-agents/SKILL.md) | The Diátaxis documentation framework, adapted to agent-consumed documents | Classifying content as how-to/reference/explanation/tutorial, writing the how-to as the spine, structuring reference for lookup, relocating explanation to human-read artifacts, skipping tutorial voice |
| [wizard](./skills/wizard/SKILL.md) | Standard operating procedure (SOP) / runbook documentation practice | Scoping to human-authority-only steps, one verifiable action per step, persisting captured values immediately, confirming before advancing, resumability after interruption |
| [repo-secure](./skills/repo-secure/SKILL.md) | GitHub's maintainer security best-practices guidance | Inventorying current settings, judging which layers apply to this repo, confirming every setting before enabling it, with branch protection receiving the most scrutiny, recording deliberate skips |
| [architecture-diagram](./skills/architecture-diagram/SKILL.md) | [The C4 model](https://c4model.com/) (Simon Brown) | Picking the right zoom level for the audience, consistent box and arrow notation, choosing to show, save, or commit a diagram as code based on what is authorized, updating on structural change |
| [explain-plainly](./skills/explain-plainly/SKILL.md) | [ISO 24495-1:2023](https://www.iso.org/standard/78907.html) Plain Language standard, applied as a default posture | No unexplained jargon by default, framing from the reader's stake, maintaining a running glossary, verifying the explanation is actionable |
| [repo-ship](./skills/repo-ship/SKILL.md) | [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), applied at authoring time, plus repo-creation-as-first-class-step practice | Splitting commits by intent, naming a new repo for what it is, deciding visibility deliberately, filling description and topics at creation |
| [project-groundwork](./skills/project-groundwork/SKILL.md) | [ISO/IEC/IEEE 29148:2018](https://www.iso.org/standard/72089.html) requirements quality characteristics | Scanning a draft for ambiguity, inconsistency, incompleteness, and unverifiable claims, batching only the blocking gaps, writing decisions into the document and the repository's existing decision record together |
| [capacity-estimation](./skills/capacity-estimation/SKILL.md) | [Little's Law](https://pubsonline.informs.org/doi/10.1287/opre.9.3.383) (Little, 1961), [ISO/IEC 25010:2023](https://www.iso.org/standard/78176.html) performance efficiency, Gunther's Universal Scalability Law, [IEC 80000-13](https://www.iec.ch/prefixes-binary-multiples) binary prefixes | Restating "fast" and "scalable" as numbers with percentiles, labeling every input measured/derived/assumed, sizing concurrency as arrival rate times service time, headroom against the utilization curve, ending in a recorded decision |

## MCP server internals

`mcp-server.js` is a plain Node.js (ESM, no build step) script: at startup it reads every `skills/<name>/SKILL.md`, parses the `name`/`description` out of the frontmatter, and registers each one as an MCP prompt whose content is the full skill text. Run `npm test` to smoke-test it. The test validates every skill's frontmatter as real YAML, spawns the server and performs a real MCP handshake, asserts an exact `prompts/list` name match against the discovered skill set, and diffs each `prompts/get` response against its corresponding `SKILL.md` file byte-for-byte.

## Limitations

None of the 34 skills have been battle-tested against a real release, incident, or security review yet; they're authored from standards but not yet validated in use. The MCP server has a smoke test (`npm test`) but hasn't been exercised against a real third-party MCP client (Cursor, Windsurf, etc.) yet, only a scripted handshake. This repo has no SECURITY.md or vulnerability reporting channel yet.

## Donate

<p align="center">
  <a href="https://buymeacoffee.com/aethrox"><img alt="BuyMeACoffee" src="https://img.shields.io/badge/buy_me_a_coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black"></a>
  <a href="https://etherscan.io/address/0x090f4d8d313bb12c13c63c8b6a7acba19af94490"><img alt="Ethereum" src="https://img.shields.io/badge/ETH-donate-3C3C3D?logo=ethereum&logoColor=white"></a>
  <a href="https://solscan.io/account/9PduqxAVxPp78heUG7KKAVpSbPAYa3HjwN3r3JnzcE2X"><img alt="Solana" src="https://img.shields.io/badge/SOL-donate-9945FF?logo=solana&logoColor=white"></a>
  <a href="https://mempool.space/address/bc1q4vzs920q3x7d76eq2fu3agq4gxywu5z05aqf86"><img alt="Bitcoin" src="https://img.shields.io/badge/BTC-donate-F7931A?logo=bitcoin&logoColor=white"></a>
</p>

| Chain | Address |
|---|---|
| Ethereum | `0x090f4d8d313bb12c13c63c8b6a7acba19af94490` |
| Solana | `9PduqxAVxPp78heUG7KKAVpSbPAYa3HjwN3r3JnzcE2X` |
| Bitcoin | `bc1q4vzs920q3x7d76eq2fu3agq4gxywu5z05aqf86` |

## Contributing

Adding a new skill or fixing an existing one? See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

MIT, see [LICENSE](LICENSE).