ADR Assistant Skill

I autonomously help with Architecture Decision Records when you're making architectural or technical decisions.

When I Activate

I trigger when you're:

• Discussing technology choices
• Evaluating alternatives
• Making architectural decisions
• Documenting technical choices
• Updating existing ADRs

What I Provide

1. ADR Analysis

• Review existing ADRs in /Users/home/hyperscape-5/adr/
• Identify related decisions
• Check for conflicts or dependencies
• Suggest improvements

2. ADR Creation

• Generate next ADR number (currently 0012+)
• Follow established template structure
• Research alternatives using Deepwiki
• Document consequences and tradeoffs
• Include implementation timeline

3. ADR Template Structure

# NNNN. Title

Date: YYYY-MM-DD

## Status
Proposed | Accepted | Deprecated | Superseded

## Context
- Current situation
- Pain points
- Requirements
- Drivers

## Decision
What we decided and why

## Alternatives Considered
- Alt 1: Pros/Cons/Reason for rejection
- Alt 2: ...

## Consequences
- Positive
- Negative
- Neutral
- Risks with mitigations

## Implementation
- Action items
- Timeline
- Success metrics

## References
- Links to docs, commits, related ADRs

## Notes
- Additional insights

4. Best Practices

• Use Deepwiki to research similar ADRs
• Consider 3-5 alternatives minimum
• Document concrete consequences
• Include measurable success metrics
• Link to related ADRs
• Update ADR README index

Current ADR Index (as of 2025-11-07)

• 0001: Use Bun as Primary Package Manager
• 0002: Adopt Turbo for Monorepo Build Orchestration
• 0003: Migrate from Docker to RAILPACK for Railway Deployment
• 0004: Use PostgreSQL for Primary Database
• 0005: Adopt ElizaOS for AI Agent Framework
• 0006: Enforce TypeScript Strict Typing Standards
• 0007: Real Gameplay Testing with Playwright
• 0008: Adopt Privy HD Wallets for User Wallet Management
• 0009: Semi-Automated Asset Approval Workflow
• 0010: Meshy.ai API Integration for 3D Asset Generation
• 0011: VRM Avatar System Architecture

Next number: 0012

Example Usage

User: "Should we use GraphQL or REST for our new API?"

Me: I notice you're evaluating API architecture. Let me help create ADR-0012.

I'll:

1. Research GraphQL vs REST using Deepwiki
2. Analyze your current tech stack (Elysia, TypeScript)
3. Consider Hyperscape-specific requirements
4. Document alternatives with detailed pros/cons
5. Propose decision with implementation plan
6. Create ADR file at adr/0012-api-architecture-choice.md
7. Update ADR README index

Integration with Project

• Follows ADR template from existing records
• Updates README.md index automatically
• Links to related ADRs
• Aligns with project standards (CLAUDE.md)
• Uses Deepwiki for research