GitHub - jsingh6/arch-decision: Open-source ADR orchestrator — explores your codebase, proposes approaches, writes Architecture Decision Records automatically · GitHub

/" data-turbo-transient="true" />

Skip to content

Search or jump to...

Search code, repositories, users, issues, pull requests...

-->

Search

Clear

Search syntax tips

Provide feedback

--><br>We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted

Cancel

Submit feedback

Saved searches

Use saved searches to filter your results more quickly

-->

Name

Query

To see all available qualifiers, see our documentation.

Cancel

Create saved search

Sign in

/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up

Appearance settings

Resetting focus

You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

{{ message }}

jsingh6

arch-decision

Public

Notifications<br>You must be signed in to change notification settings

Fork

Star

main

BranchesTags

Go to file

CodeOpen more actions menu

Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit

History<br>16 Commits<br>16 Commits

.claude-plugin

.claude-plugin

.github/workflows

.github/workflows

agents

agents

community

community

example-output

example-output

scripts

scripts

skills

skills

DASHBOARD.md

DASHBOARD.md

README.md

README.md

View all files

Repository files navigation

📐 arch-decision

Stop losing architectural decisions to Slack threads and forgotten docs.

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

The Problem

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.

What It Does

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<br>Phase 1 Understands the problem from the issue or description<br>Phase 2 Launches 3 parallel agents — prior art, impact map, constraints<br>Phase 3 Asks clarifying questions before designing anything<br>Phase 4 Generates 3 approaches simultaneously (Minimal / Clean / Pragmatic)<br>Phase 5 Synthesizes a trade-off table and recommends the best path<br>Phase 6 Waits for your approval — nothing is written without sign-off<br>Phase 7 Writes a formal ADR to docs/decisions/ with full context<br>Phase 8 Links the ADR back to the original issue

Works on any language. Any framework. Any team.

Why It's Different

GitHub Copilot / Cursor<br>arch-decision

Operates on<br>Files and lines<br>The full decision lifecycle

Knows why you're building<br>No<br>Yes — starts from the problem

Produces documentation<br>No<br>Yes — formal ADR, committed to git

Human approval gate<br>No<br>Yes — cannot proceed without sign-off

Resumable across sessions<br>No<br>Yes — checkpoints after every phase

Independently validated<br>Yes — community PRs confirm recommendations

Real Example

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.

Read the full ADR

How It Works

arch-decision is a Claude Code plugin built on a multi-agent architecture:

Orchestrator (skills/arch-decision/SKILL.md) — coordinates all 8 phases, maintains a context bus, enforces the human approval gate

Explorer agents (agents/arch-explorer/) — 3 run in parallel during Phase 2, each focused on a different angle: prior art, impact map, and constraints

Synthesizer agent (agents/arch-synthesizer/) — produces the trade-off table and recommendation from all three approaches

The 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.

Get Started

Requires Claude Code. Install it first if you haven't already.

Then install the...