// Record an architecture decision as an ADR in docs/adr/. Use when choosing between frameworks, libraries, databases, or architectural patterns; stating a decision with reasoning ("we decided X instead of Y because..."); or querying past decisions ("why did we choose X?").
| name | adr |
| description | Record an architecture decision as an ADR in docs/adr/. Use when choosing between frameworks, libraries, databases, or architectural patterns; stating a decision with reasoning ("we decided X instead of Y because..."); or querying past decisions ("why did we choose X?"). |
| allowed-tools | Read, Write, Edit, Glob, Grep, AskUserQuestion |
You are recording or retrieving an Architecture Decision Record (ADR) for this
project. ADRs live in docs/adr/ at the repo root.
Record these decisions:
Skip: trivial choices (variable naming, formatting, minor refactors).
Every ADR file must include all of these sections:
# ADR-NNNN: [Decision Title]
**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [who was involved]
## Context
[2–5 sentences describing the situation, constraints, and forces at play]
## Decision
[1–3 sentences stating the change clearly and unambiguously]
## Alternatives Considered
### Alternative 1: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific rejection reason]
## Consequences
### Positive
- [benefit 1]
### Negative
- [trade-off 1]
### Risks
- [risk and mitigation]
Glob docs/adr/[0-9]*.md to find the highest existing number.0003).docs/adr/NNNN-kebab-title.md (kebab-case title, all lowercase).| ADR | Title | Status | Date | table in docs/adr/README.md.docs/adr/README.md exists. If not, offer to start the ADR directory.superseded by ADR-NNNN and create the new ADR with a back-reference in its Context.Scaffold a new sub-worker inside packages_worker (npm, deps.dev, osv, scorecard, etc.) following the single-service multi-entry-point structure. Use when: "add a new packages worker", "scaffold a sub-worker in packages_worker", "new worker for packages-db", "add npm worker", "add OSV worker", "add deps.dev worker".
Get packages_worker running locally — first time or resuming after a break. Spins up packages-db if not running, applies any pending migrations, and starts the worker. All steps are safe to re-run. Use when: "set up packages worker", "start packages worker", "resume packages worker", "get packages-db running", "packages-db stopped", "restart the worker".
Generate a commit message and commit staged changes using git commit -s -S.
Recover from missing DCO sign-off on commits. Handles the single-commit amend, older-commit recovery via interactive rebase or cherry-pick, and explains the Probot DCO check that blocks PRs without sign-off. Use when a PR fails the DCO check, when a commit needs a Signed-off-by trailer added retroactively, or when sign-off was forgotten during rebase / cherry-pick / amend.
Pre-PR validation — working tree status, format, lint, TypeScript check, and protected file check. Workspace-aware: detects which of backend/, frontend/, services/apps/*, services/libs/* were changed and runs only the relevant scripts. Use before submitting any PR, to check if code is ready, or to validate a branch before review.
Review a pull request against CDP architecture standards — fetches PR diff, verifies previous comments are addressed, validates PR metadata (title, branch, JIRA key, size), runs a code-standards enforcer against every file in `.claude/rules/` and `.claude/hooks/guard-protected-files.sh`, and drafts inline review comments with suggested fixes. NEVER auto-posts comments or submits reviews — always presents a draft in the terminal for user approval before any comment lands on the PR. Use when reviewing PRs, checking PR quality, validating code changes, or when the user says "review", "check this PR", or "audit code".