home / skills / dexploarer / hyper-forge / adr-assistant

adr-assistant skill

safe

/.claude/plugins/core-dev/skills/adr-assistant

This skill helps you create, analyze, and maintain Architecture Decision Records to streamline tech choices and ensure traceable decisions.

npx playbooks add skill dexploarer/hyper-forge --skill adr-assistant

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.9 KB

---
name: ADR Assistant
description: Helps create, analyze, and maintain Architecture Decision Records
trigger: Creating architectural decisions, evaluating alternatives, documenting technical choices
---

# 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 `${WORKSPACE_DIR}/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
```markdown
# 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

Overview

This skill helps create, analyze, and maintain Architecture Decision Records (ADRs) to support clear, traceable architectural choices. It automates ADR numbering, enforces a consistent template, and surfaces conflicts, dependencies, and improvements across existing records. The assistant also researches alternatives and produces implementation plans with measurable success metrics.

How this skill works

The assistant scans the project's ADR index and adr/ directory to identify existing decisions and relationships. It generates new ADRs using a standard template, researches alternatives via knowledge sources, and outputs pros/cons, consequences, and an implementation timeline. It can also review and suggest edits for current ADRs, flag conflicts, and update the ADR index.

When to use it

When choosing between major technology options (e.g., GraphQL vs REST).
When documenting a finalized architectural decision for traceability.
When updating or reviewing existing ADRs for conflicts or gaps.
When preparing an implementation plan with timelines and metrics.
When researching and comparing 3–5 viable alternatives for a decision.

Best practices

Consider at least three alternatives and document clear reasons for rejection.
Include measurable success metrics and a realistic timeline in the Implementation section.
Link related ADRs and surface dependencies or conflicts explicitly.
Document concrete consequences (positive, negative, neutral) and risk mitigations.
Keep each ADR focused on one decision and update the ADR index after changes.

Example use cases

Generate ADR-0012 to compare GraphQL and REST including tradeoffs and implementation steps.
Review existing ADRs to detect contradictory choices or untracked dependencies.
Create an ADR that records adoption of a new package manager or build tool.
Draft an ADR for database selection with performance and operational consequences.
Update an ADR to mark a decision as Superseded and link to the replacement.

FAQ

Can the assistant suggest implementation timelines and success metrics?

Yes. It proposes action items, an estimated timeline, and measurable success metrics tailored to the decision.

How many alternatives should I include?

Aim for 3–5 alternatives to ensure a well-rounded comparison; the assistant will research and summarize each.