Architecture Decision Record orchestrator for Claude Code. Given a feature request, issue, or problem statement, it explores the codebase, compares several architectural approaches, and writes the decision record. A companion skill structures vague problems into an intake document first.
Claude Code
$ npx -y skills add jsingh6/arch-decision --agent claude-code
Codex
$ npx skills add jsingh6/arch-decision -a codex
Cursor
$ npx skills add jsingh6/arch-decision -a cursor
Gemini CLI
$ npx skills add jsingh6/arch-decision -a gemini-cli
GitHub Copilot
$ npx skills add jsingh6/arch-decision -a github-copilot
OpenCode
$ npx skills add jsingh6/arch-decision -a opencode
Windsurf
$ npx skills add jsingh6/arch-decision -a windsurf
arch-decision is an open-source AI orchestrator that runs inside any codebase, explores it deeply, and produces a formal Architecture Decision Record — in minutes, not hours.
View Example ADR · Impact Dashboard · Install
Every team faces the same gap: a decision gets made, the code gets written, but nobody wrote down why. Six months later a new engineer changes it — and the same debate happens all over again.
Architecture Decision Records (ADRs) solve this. But writing them is friction. It takes a senior engineer 2–4 hours to research the codebase, draft approaches, build a trade-off table, and write it up clearly. So it almost never happens.
arch-decision removes that friction entirely.
Give it a GitHub issue, a Jira ticket, or a plain description. It handles the rest:
/arch-decision https://github.com/owner/repo/issues/42
Phase 0 Detects repo language, framework, existing ADRs
Phase 1 Understands the problem from the issue or description
Phase 2 Launches 3 parallel agents — prior art, impact map, constraints
Phase 3 Asks clarifying questions before designing anything
Phase 4 Generates 3 approaches simultaneously (Minimal / Clean / Pragmatic)
Phase 5 Synthesizes a trade-off table and recommends the best path
Phase 6 Waits for your approval — nothing is written without sign-off
Phase 7 Writes a formal ADR to docs/decisions/ with full context
Phase 8 Links the ADR back to the original issue
Works on any language. Any framework. Any team.
| GitHub Copilot / Cursor | arch-decision | |
|---|---|---|
| Operates on | Files and lines | The full decision lifecycle |
| Knows why you're building | No | Yes — starts from the problem |
| Produces documentation | No | Yes — formal ADR, committed to git |
| Human approval gate | No | Yes — cannot proceed without sign-off |
| Resumable across sessions | No | Yes — checkpoints after every phase |
| Independently validated | — | Yes — community PRs confirm recommendations |
Ran against refinedev/refine on issue #7338 — a feature request for reverse filter mapping in useTable with syncWithLocation.
The tool explored the codebase cold, found prior art in crudFiltersToColumnFilters, identified the framework-agnostic constraint in packages/core, and recommended an onParse callback scoped to the antd wrapper.
A community contributor independently opened PR #7385 with the same callback name, same scope, same placement — without seeing this output.
The tool reached the same conclusion a human engineer did, from a cold start, in under 5 minutes.
arch-decision is a Claude Code plugin built on a multi-agent architecture:
skills/arch-decision/SKILL.md) — coordinates all 8 phases, maintains a context bus, enforces the human approval gateagents/arch-explorer/) — 3 run in parallel during Phase 2, each focused on a different angle: prior art, impact map, and constraintsagents/arch-synthesizer/) — produces the trade-off table and recommendation from all three approachesThe human approval gate in Phase 6 means the agent cannot write the ADR without your explicit sign-off. It is designed to accelerate human judgment, not replace it.
Requires Claude Code. Install it first if you haven't already.
Then install the plugin:
claude plugin install arch-decision
Open Claude Code inside any repo and run:
/arch-decision <GitHub issue URL, Jira description, or plain text>
That's it. Examples of what you can pass:
# GitHub issue
/arch-decision https://github.com/owner/repo/issues/42
# Paste your Jira ticket summary or description directly
/arch-decision We need reverse filter mapping in useTable so URL params sync back to filter state on page load
# Or just describe the problem in plain English
/arch-decision add rate limiting to the public API
The tool asks you clarifying questions, shows you 3 approaches with a trade-off table, and waits for your approval before writing anything. The ADR is saved to docs/decisions/ in your repo.
If the problem is still vague and you want to frame it first, use
/arch-intake your problem herebefore running/arch-decision.
Metrics are tracked automatically on every ADR merge.
View the full Impact Dashboard
arch-decision/
├── skills/
│ ├── arch-decision/SKILL.md — 8-phase orchestrator
│ └── arch-intake/SKILL.md — problem framing pre-skill
├── agents/
│ ├── arch-explorer/agent.md — parallel codebase exploration
│ └── arch-synthesizer/agent.md — trade-off synthesis
├── example-output/ — real ADR examples
├── scripts/generate_dashboard.py — auto-generates DASHBOARD.md
└── .github/workflows/ — updates dashboard on every ADR merge
MIT
Stars on GitHub
Fetches up-to-date documentation and code examples for libraries, frameworks, SDKs, CLI tools and cloud services, so an AI agent can answer API questions and generate code against current references.
@upstashGives Claude Code skills and agents for writing React documentation on react.dev, covering MDX components, voice and style rules, blog post structure, and interactive Sandpack code examples.
@reactjsAn agent skill that turns complex terminal output into styled HTML pages you actually want to read. Ask your agent to explain a system architecture, review a diff, or compare requirements against a plan.
@nicobailonA WYSIWYG markdown editor so you can edit markdown files like a Google Doc or Notion page, with a desktop app and web UI for navigation, search, and wiki-style linking. It also ships skills for working in codebase wiki, personal CRM, and knowledge base projects.
@inkeepArchitecture Decision Record orchestrator for Claude Code. Given a feature request, issue, or problem statement, it explores the codebase, compares several architectural approaches, and writes the decision record. A companion skill structures vague problems into an intake document first. Install it with the command on its page. It includes arch-decision, arch-intake. Its skills do not fire on their own yet. Free and open source.
Is this plugin yours?
Claim it with GitHubSubmit a pluginPromote it