agentsclimarketplace

Adr

Skill Dev10x-Guru/Dev10x-Claude/skills/adr

Create Architecture Decision Records (ADRs) following project conventions. Extends the base scope skill with ADR-specific format, numbering, diagram generation, and decision documentation. TRIGGER when: documenting significant architectural decisions, design trade-offs, or technology choices that affect the codebase. DO NOT TRIGGER when: making code changes without architecture impact, or writing commit messages (use Dev10x:git-commit).From its SKILL.md

Install
npx -y skills add Dev10x-Guru/Dev10x-Claude --skill adr

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

6.3 KB, as published. Nobody here has run it

ADR Create - Architecture Decision Record Skill

Orchestration

This skill follows references/task-orchestration.md patterns. Create a task at invocation, mark completed when done:

REQUIRED: Create a task at invocation. Execute at startup:

  1. TaskCreate(subject="Create Architecture Decision Record", activeForm="Creating ADR")

Mark completed when done: TaskUpdate(taskId, status="completed")

Overview

This skill creates Architecture Decision Records (ADRs) following the project's established format. It extends the base Dev10x:scope skill with ADR-specific workflows.

Use when:

  • Documenting significant architectural decisions
  • Proposing new integration patterns
  • Recording technology choices
  • Documenting system boundaries and responsibilities

Do NOT use when:

  • Simple bug fixes (no architectural impact)
  • Minor refactoring within existing patterns
  • Configuration changes

Prerequisites

Before invoking this skill, gather:

  1. Problem context - What situation needs a decision?
  2. External references (optional) - Documentation, API docs
  3. Linear ticket (optional) - Associated ticket for linking

Workflow

Phase 1: Discovery (Uses base scope skill)

Follow the base Dev10x:scope skill for context gathering:

  1. Understand the problem space

    • What are we trying to solve?
    • What constraints exist?
  2. Research external resources (if any)

    • Fetch and analyze documentation
    • Extract key concepts and patterns
  3. Explore existing codebase

    • Find related patterns
    • Identify reusable components
    • Note naming conventions
  4. Identify components

    • What exists vs. what's needed
    • Dependencies between components

Phase 2: ADR-Specific Design

2.1 Determine ADR Number

ls docs/adr/*.md | grep -E '^docs/adr/[0-9]{4}-' | sort | tail -1

If last is 0009, next is 0010.

2.2 Create ADR Structure

Use the template in references/adr-template.md for the full structure. Key sections:

  • Context — situation, current state, problems
  • Decision — architecture, key flows, new components
  • Alternatives Considered — pros/cons/verdict for each
  • Consequences — what becomes easier, harder, risks
  • Implementation Plan — phased steps with file paths
  • References — external docs, internal links

Default status: Accepted. Use Proposed only when explicitly requesting review before acceptance.

2.3 Create Diagrams Directory

mkdir -p docs/adr/diagrams/{ADR_NUMBER}/

Phase 3: Diagram Creation

Use PlantUML patterns from references/plantuml-patterns.md.

3.1 Component Architecture Diagram

Shows system boundaries and component relationships.

3.2 Sequence Diagrams

Shows flow of operations for key interactions.

3.3 Generate PNG Files

cd docs/adr/diagrams/{ADR_NUMBER}/
for f in *.puml; do
  java -jar ~/.local/bin/plantuml.jar "$f"
done

Phase 4: Apply Design Principles

YAGNI (You Aren't Gonna Need It):

  • Don't design features that aren't needed yet
  • Remove unused return values
  • Prefer void methods over complex returns

Follow Existing Patterns:

  • Find similar implementations in codebase
  • Use same layering (Entry Point → Service → Client)
  • Follow naming conventions

Clean Architecture:

  • Keep external dependencies at edges
  • Business logic independent of frameworks
  • Clear component responsibilities

Phase 5: User Review Loop

Critical: Present findings to user and incorporate corrections.

Common corrections include:

  • Business context not visible in code
  • Organizational preferences
  • Future plans affecting design
  • YAGNI simplifications

Iterate until user approves the architecture.

Phase 6: Finalize and Commit

6.1 Create Branch

Use Dev10x:ticket-branch skill if a ticket exists, or Dev10x:git-worktree for isolated workspace.

6.2 Commit ADR

Use the Dev10x:git-commit skill to commit:

  • Stage docs/adr/ directory
  • Gitmoji: 📝
  • Title: outcome-focused (e.g., "Document payment routing architecture")

6.3 Create PR

Use Dev10x:gh-pr-create skill for PR creation.

ADR Quality Checklist

Before finalizing, verify:

Content

  • Context clearly explains the problem
  • Decision is explicit and actionable
  • Alternatives genuinely considered
  • Consequences are honest (both easier and harder)
  • Risks have mitigations

Architecture

  • Follows existing codebase patterns
  • YAGNI applied
  • Clean Architecture respected
  • Component responsibilities clear

Diagrams

  • Component architecture shows system boundaries
  • Sequence diagrams show key flows
  • PNGs generated and referenced in ADR

Implementation

  • Steps ordered logically
  • File paths specified
  • Pattern references included
  • Phases make sense

Review

  • User feedback incorporated
  • Business context accurate
  • Ready for implementation

Integration with Other Skills

Dev10x:adr
├── Extends: Dev10x:scope (base scoping workflow)
├── May use: Dev10x:work-on (if ticket exists)
├── Uses: Dev10x:gh-pr-create (for PR creation)
└── Uses: Dev10x:git-commit (for commit formatting)

References

ADR Format

Project ADR Location

  • ADRs: docs/adr/NNNN-title.md
  • Diagrams: docs/adr/diagrams/NNNN/

PlantUML

  • Generate: java -jar ~/.local/bin/plantuml.jar diagram.puml
  • Themes: !theme plain for clean diagrams

Keep looking

Skills are one crate of 610,677. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.