Agent skill

adr-plan

Analyze a task and produce an Architecture Decision Record with implementation steps.

View SKILL.md on GitHub Repository
Stars 114
Forks 19

Install this agent skill to your Project

npx add-skill https://github.com/NikiforovAll/claude-code-rules/tree/main/plugins/handbook-team-stack/skills/adr-plan

SKILL.md

ADR Plan: Task Analysis → Architecture Decision Record

Analyze a task, explore the codebase, and produce an ADR with concrete implementation steps.

Phase 1: Analyze

  1. Read the task description, active plan, or task list
  2. Explore affected areas of the codebase — do it concurrently for independent modules
  3. Map blast radius — search for consumers of functions/types/routes being changed
  4. Identify alternatives worth considering (at least 2)

Do this silently.

Phase 2: Detect ADR Setup

Check if the project has an ADR directory:

ls docs/adr/ || ls adr/ || ls doc/adr/
  • Found → use existing directory, detect next number from existing files
  • Not found → run npx adr init en, then proceed

Phase 3: Produce ADR Content

Write the ADR using npx adr new "<title>", then edit the generated file with the following structure:

markdown
# ADR-NNNN: [Title]

## Status
Proposed

## Context
[What problem are we solving? What constraints exist?]

## Decision
[What we chose and why]

## Alternatives Considered
| Option | Pros | Cons |
|--------|------|------|
| ... | ... | ... |

## Implementation Steps

### Step 1: [Description]
- **Files:** [files to create/modify]
- **Depends on:** [previous step or "none"]
- **Done when:** [concrete acceptance criteria]

### Step 2: [Description]
...

## Consequences
- [Positive and negative outcomes, tradeoffs accepted]

Guidelines

  • Steps are ordered by dependency — each step lists what it depends on
  • Steps are parallelizable when independent — note which steps can run concurrently
  • Each step has concrete "done when" criteria — no vague outcomes
  • Alternatives table is honest — include the option you chose and why others lost
  • Keep it short. 1-2 pages max. No padding.

Phase 4: Present to User

Show the ADR content and the file path. The user may:

  • Approve → ADR stays as-is
  • Adjust → edit and re-present
  • Cancel → delete the file

Important

  • The ADR is a planning artifact, not documentation for posterity
  • Steps should map naturally to work units (a team member could own one or more steps)
  • If the task is too simple for an ADR (single file, obvious fix), say so and skip
  • Do not write implementation code — this is planning only

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

NikiforovAll/claude-code-rules

update-component-reference

This skill should be used when the user wants to add components (commands, agents, skills, hooks, or MCP servers) to the Component Reference section of the website.

114 19
Explore
NikiforovAll/claude-code-rules

version-bump

This skill automates version bumping during the release process for the Claude Code Handbook monorepo. It should be used when the user requests to bump versions, prepare a release, or increment version numbers across the repository.

114 19
Explore
NikiforovAll/claude-code-rules

spec-driven

Guide spec-driven development workflow (Requirements → Design → Tasks → Implementation) with approval gates between phases. Use when user wants structured feature planning or says "use spec-driven" or "follow the spec process".

114 19
Explore
NikiforovAll/claude-code-rules

nano-banana-prompting

This skill should be used when crafting prompts for Nano Banana Pro (Gemini image generation). Use when users want help writing image generation prompts, need guidance on prompt structure, or want to optimize their prompts for better results.

114 19
Explore
NikiforovAll/claude-code-rules

nano-banana

This skill should be used for Python scripting and Gemini image generation. Use when users ask to generate images, create AI art, edit images with AI, or run Python scripts with uv. Trigger phrases include "generate an image", "create a picture", "draw", "make an image of", "nano banana", or any image generation request.

114 19
Explore
NikiforovAll/claude-code-rules

structured-plan-mode

This skill should be used when planning and tracking complex feature implementations that require systematic task decomposition. Use this skill to break down large features into manageable, well-documented tasks with clear dependencies, action items, and success criteria. The skill provides a structured template and methodology for iterative planning and tracking throughout implementation.

114 19
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results