Architecting Typescript

• 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

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.

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

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.

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

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.

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.

## 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)}

• 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.