TypeScript ADR conventions enforced across architect and auditor skills. Loaded by other skills, not invoked directly.
From typescriptnpx claudepluginhub outcomeeng/claude --plugin typescriptThis skill is limited to using the following tools:
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Reorganizes X and LinkedIn networks: review-first pruning of low-value follows, priority-based add/follow recommendations, and drafts warm outreach in user's voice.
<reference_note>
This is a reference skill. The architect and auditor load these conventions automatically. Invoke /architecting-typescript to write ADRs or /auditing-typescript-architecture to review them.
</reference_note>
<adr_sections>
The ADR template (from /understanding) defines exactly these sections:
This is the complete list. An ADR has no other sections. There is no "Testing Strategy" section, no "Status" field, no "Level Assignments" table. Testability constraints live in Compliance as MUST/NEVER rules.
When an ADR is required: Every module that makes architectural decisions — module layout, library choice, DI patterns — requires an ADR. The absence of an ADR is itself a violation, not a reason to skip the audit.
</adr_sections>
<testability_in_compliance>
ADRs do not assign testing levels. They establish constraints that make levels achievable. The /testing skill assigns levels when it reads spec assertions alongside ADR constraints. This separation follows the truth hierarchy: ADR governs, spec declares, test verifies.
The mechanism: Compliance rules that mandate DI, prohibit mocking, and require observable interfaces.
Correct pattern -- testability as MUST/NEVER:
## Compliance
### Recognized by
Observable DI parameters in all functions that invoke external tools.
### MUST
- All external tool invocations accept a dependency-injected runner parameter -- enables isolated testing without mocking ([review])
- Configuration accepts typed inputs, not environment reads -- enables Level 1 verification of config logic ([review])
### NEVER
- `vi.mock()` or `jest.mock()` for any dependency -- violates reality principle ([review])
- Direct `child_process.exec/spawn` without DI wrapper -- prevents isolated testing ([review])
What this replaces -- the following does NOT belong in an ADR:
## Testing Strategy <-- NOT a valid ADR section
### Level Assignments <-- downstream concern for /testing
| Component | Level | Justification |
| ---------------- | ----- | ------------------------------- |
| Command building | 1 | Pure function, no external deps |
| Hugo invocation | 2 | Needs real Hugo binary |
### Escalation Rationale <-- downstream concern for /testing
- Level 1->2: Hugo binary required for acceptance
Why: Level assignments depend on the spec's assertions, the project's infrastructure, and the /testing skill's Five Factors analysis. The ADR cannot know these at authoring time. The ADR's job is to establish constraints (DI, no mocking) that make the right levels possible.
</testability_in_compliance>
<atemporal_voice>
ADRs state architectural truth. They NEVER narrate code history, current state, or migration plans. This is a REJECTION-level violation in ANY section -- Context, Decision, Rationale, Compliance, all of it. No section gets a pass.
An ADR that references existing code ("The current X has...", "The file X does not exist") is temporal -- it becomes stale the moment that code changes. Code that violates an ADR is discovered through code review and test coverage analysis against the ADR's invariants.
Temporal patterns to reject:
module.ts has..." -- narrates code statedeprecated/old.ts does not exist" -- narrates filesystem stateThe rewrite pattern:
TEMPORAL: "The current BuildRunner class in build.ts shells out to Hugo directly without dependency injection."
ATEMPORAL: "Build orchestration uses dependency injection to isolate tool invocation from build logic."
TEMPORAL: "The file legacy/builder.ts does not exist and should be removed."
ATEMPORAL: "Build implementations conform to the BuildDependencies interface."
TEMPORAL: "We discovered that direct execa calls make testing impossible."
ATEMPORAL: "Direct process invocation prevents Level 1 testing. Dependency injection enables isolated unit verification."
</atemporal_voice>
<di_patterns>
When an ADR mandates dependency injection, these are the TypeScript patterns to reference in Compliance rules.
Interface-based DI:
// ADR Compliance: "MUST accept runner as parameter"
interface BuildDependencies {
run: (cmd: string[], opts?: ExecOptions) => Promise<ExecResult>;
resolveVersion: (tool: string) => Promise<string>;
}
// Level 1: inject controlled implementation
// Level 2+: inject real implementation
function buildSite(
config: BuildConfig,
deps: BuildDependencies,
): Promise<BuildResult> {
// ...
}
ADR Compliance rule to code mapping:
| ADR Compliance rule | Code implements |
|---|---|
| "MUST accept runner as parameter" | function f(deps: RunnerDeps) |
| "MUST validate config at load time" | Zod schema with .parse() at boundary |
| "NEVER use vi.mock()" | No mock imports in test files |
| "NEVER shell out without DI wrapper" | No bare exec() / spawn() calls |
Mocking prohibition in ADR language:
The auditor checks for these violations in ADR text:
vi.mock() or jest.mock() mentioned as an approach -- reject/testing exception case -- rejectCorrect ADR language: "Use dependency injection to isolate X from Y" or "Accept X as a parameter implementing the Y interface."
</di_patterns>
<level_context>
The architect needs to understand testing levels to write effective Compliance rules. The auditor needs them to verify that Compliance rules enable the right levels. These definitions come from /testing.
| Level | Name | TypeScript Infrastructure | When to Use |
|---|---|---|---|
| 1 | Unit | Node.js built-ins + Git + temp fixtures | Pure logic, FS operations, git operations |
| 2 | Integration | Project-specific binaries/tools | Hugo, Caddy, Claude Code, Docker, TS compiler |
| 3 | E2E | External deps (GitHub, network, Chrome) | Full workflows with external services |
Key rules:
How levels relate to ADRs: The ADR does not assign levels. It establishes Compliance rules that determine what levels are achievable. "MUST accept runner as parameter" makes Level 1 possible for the logic around the tool. "NEVER call external API directly" means Level 3 for the real call, Level 1 for the business logic.
</level_context>
<anti_patterns>
| Anti-pattern | Why it is wrong | Where it belongs |
|---|---|---|
## Testing Strategy section | Not in the authoritative ADR template | /testing skill output |
| Level assignment tables | Downstream concern; depends on spec assertions | /testing Stage 2 |
| Escalation rationale | Downstream concern; depends on project infra | /testing Stage 2 |
## Status field | Not in the authoritative ADR template | Git history / commit metadata |
| File names to delete | Temporal; becomes stale immediately | Code review against ADR invariants |
| Migration plans | Temporal; narrates a transition | Code review / work items |
| Implementation code | ADRs constrain implementation, not provide it | /coding-typescript |
Test references ([test]) | ADRs are verified by architecture review | Spec assertions only |
</anti_patterns>