# Architecting Typescript

> ALWAYS invoke this skill when writing ADRs for TypeScript.

- Skill: `outcomeengineering/architecting-typescript` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add outcomeengineering/architecting-typescript`
- Raw SKILL.md: https://api.skillmd.com/api/skills/outcomeengineering/architecting-typescript/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: outcomeengineering (https://skillmd.com/u/outcomeengineering)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/outcomeengineering/architecting-typescript

---


<essential_principles>
**Read `/standardizing-typescript-architecture` before writing any ADR.** It defines the canonical ADR sections, how testability appears in Compliance rules, and what does NOT belong in an ADR.

- ADRs follow the authoritative template: Purpose, Context, Decision, Rationale, Trade-offs, Invariants, Compliance
- Testability constraints go in the Compliance section as MUST/NEVER rules -- not in a separate Testing Strategy section
- No `any` without explicit justification in ADR
- Design for dependency injection (NO MOCKING)
- You produce ADRs (Architecture Decision Records), not implementation code

</essential_principles>

<context_loading>
**For spec-tree work items: Load complete context before creating ADRs.**

If you're creating ADRs for a spec-tree work item (enabler/outcome), ensure complete hierarchical context is loaded:

1. **Invoke `spec-tree:contextualizing`** with the node path
2. **Verify all ancestor ADRs/PDRs are loaded** - Must understand and honor all decision records in hierarchy
3. **Read the node spec** - Requirements, Test Strategy, and Outcomes sections

**The `spec-tree:contextualizing` skill provides:**

- Complete ADR/PDR hierarchy (product and ancestor decisions at all levels)
- Node spec with requirements, test strategy, and outcomes
- Typed assertions from the target node

**ADR creation requirements:**

- Must not contradict ancestor ADRs/PDRs (product → ancestor hierarchy)
- Must reference relevant ancestor decisions
- Must include testability constraints in Compliance (MUST/NEVER rules for DI, no mocking)
- Must document trade-offs and consequences

**If NOT working on spec-tree work item**: Proceed directly with ADR creation using provided requirements.
</context_loading>

<input_context>
Before creating ADRs, you must understand:

**1. Node Specification**

- Functional requirements in `## Requirements` section
- Test strategy in `## Test Strategy` section
- Typed assertions from the node spec
- Architectural constraints from ancestor ADRs

**2. Project Context**

Read these files to understand project structure and workflow:

- `spx/CLAUDE.md` - Project navigation, work item status, BSP dependencies

For testing methodology, invoke the `/testing-typescript` skill

**3. Existing Decisions**

Read existing ADRs/PDRs to ensure consistency:

- `spx/{NN}-{slug}.adr.md` - Product-level ADRs (interleaved at root)
- `spx/{NN}-{slug}.pdr.md` - Product-level PDRs (interleaved at root)
- ADRs/PDRs interleaved within enabler/outcome nodes

</input_context>

<adr_scope>
You produce ADRs. The scope depends on what you're deciding:

| Decision Scope | ADR Location                                     | Example                              |
| -------------- | ------------------------------------------------ | ------------------------------------ |
| Product-wide   | `spx/{NN}-{slug}.adr.md`                         | "Use Zod for all data validation"    |
| Node-specific  | `spx/{NN}-{slug}.enabler/{NN}-{slug}.adr.md`     | "CLI command structure"              |
| Nested node    | `spx/.../{NN}-{slug}.outcome/{NN}-{slug}.adr.md` | "Use execa for subprocess execution" |

**ADR Numbering:**

- BSP range: [10, 99]
- Lower BSP = dependency (higher-BSP ADRs may rely on it)
- Insert using midpoint calculation: `new = floor((left + right) / 2)`
- Append using: `new = floor((last + 99) / 2)`
- First ADR in scope: use 21

See `/authoring` skill for complete ordering rules.

**Within-scope dependency order**: adr-21 must be decided before adr-37 (lower BSP = dependency).

**Cross-scope dependencies**: Must be documented explicitly in ADR "Context" section using markdown links.

</adr_scope>

<adr_creation_protocol>
Execute these phases IN ORDER.

**Phase 0: Read Context**

1. Read the node spec completely (requirements, assertions)
2. Read project context:
   - `spx/CLAUDE.md` - Project structure, navigation, work item management
3. Read `/standardizing-typescript-architecture` for canonical ADR conventions
4. Invoke `/testing-typescript` to understand testing methodology
5. Read existing ADRs for consistency:
   - `spx/{NN}-{slug}.adr.md` - Product-level ADRs
   - ADRs interleaved within enabler/outcome nodes
6. Read `/authoring` skill for ADR template

**Phase 1: Identify Decisions Needed**

For each TRD section, ask:

- What architectural choices does this imply?
- What patterns or approaches should be mandated?
- What constraints should be imposed?
- What trade-offs are being made?

List decisions needed before writing any ADRs.

**Phase 2: Analyze TypeScript-Specific Implications**

For each decision, consider:

- **Type system**: How will types be designed? What generics needed?
- **Architecture**: Which pattern applies (DDD, hexagonal, etc.)?
- **Security**: What boundaries need protection?
- **Testability**: How will this be tested?

**Phase 3: Write ADRs**

Use the authoritative template (from `/understanding`). Each ADR includes:

1. **Purpose**: What concern this decision governs
2. **Context**: Business impact and technical constraints
3. **Decision**: The specific choice in one sentence
4. **Rationale**: Why this is right given constraints, alternatives rejected
5. **Trade-offs accepted**: What is given up, why acceptable
6. **Invariants** (optional): Algebraic properties for all governed code
7. **Compliance**: Recognized by, MUST rules, NEVER rules -- including testability constraints

**Phase 4: Verify Consistency**

- No ADR should contradict another
- Node ADRs must align with ancestor ADRs
- Nested ADRs must not contradict parent-level ADRs

</adr_creation_protocol>

<what_you_do_not_do>

1. **Do NOT write implementation code**. You write ADRs that constrain implementation.
2. **Do NOT review code**. That's a separate concern.
3. **Do NOT fix bugs**. That's an implementation concern.
4. **Do NOT create work items**. That's a project management concern.

</what_you_do_not_do>

<accessing_skill_files>
When this skill is invoked, Claude Code provides the base directory in the loading message:

```
Base directory for this skill: {skill_dir}
```

Use this path to access skill files:

- References: `{skill_dir}/references/`

**IMPORTANT**: Do NOT search the project directory for skill files.
</accessing_skill_files>

<reference_index>
Detailed patterns and principles:

| File                                  | Purpose                                   |
| ------------------------------------- | ----------------------------------------- |
| `references/adr-patterns.md`          | Common ADR patterns for TypeScript        |
| `references/typescript-principles.md` | Type safety, clean architecture, security |

</reference_index>

<output_format>
When you complete ADR creation, provide:

```markdown
## Architectural Decisions Created

### ADRs Written

| ADR                                                         | Scope          | Decision Summary                 |
| ----------------------------------------------------------- | -------------- | -------------------------------- |
| [Type Safety](spx/21-type-safety.adr.md)                    | Product        | Use strict TS, Zod at boundaries |
| [CLI Structure](spx/32-cli.enabler/21-cli-structure.adr.md) | 32-cli enabler | Commander.js with subcommands    |

### Key Constraints

1. {constraint from [Type Safety](spx/21-type-safety.adr.md)}
2. {constraint from [CLI Structure](spx/32-cli.enabler/21-cli-structure.adr.md)}
```

</output_format>

<success_criteria>
ADR is complete when:

- [ ] Compliance section includes testability constraints (DI, no mocking) per `/standardizing-typescript-architecture`
- [ ] All architectural choices documented
- [ ] Compliance criteria defined with MUST/NEVER rules for verification
- [ ] No contradictions with existing ADRs
- [ ] Type safety considerations addressed
- [ ] Security boundaries identified

*Remember: Your decisions shape everything downstream. A well-designed architecture enables clean implementation.*
</success_criteria>