Architecture Decision Records (ADRs)

ADRs are lightweight documents that capture important technical decisions. Gyrus provides a full ADR management system integrated with MCP.

What is an ADR?

An Architecture Decision Record captures:

• What decision was made
• Why it was made
• What alternatives were considered
• What the consequences are

ADRs help with spec-driven development, where you define what you're building before writing code.

ADR Structure

Each ADR has YAML frontmatter with metadata:

---
title: Feature Name
description: Brief description of what this ADR covers
date_created: 2026-01-15
date_updated: 2026-01-15
status: todo
type: enhancement
tags: [api, authentication]
working_folder: /path/to/project
---

Status Values

Status	Description
todo	Not yet started
in-progress	Currently being worked on
in-review	Ready for review
blocked	Blocked by dependencies
completed	Finished
deprecated	No longer relevant

Type Values

Type	Use Case
enhancement	New features or improvements
debug	Bug fixes and debugging
research	Exploration and investigation

ADR Content Template

The default ADR template includes these sections:

## Goal

What are you trying to achieve?

## Context

Background information and constraints.

## Issues

Problems or challenges to address.

## Proposed Solution

Your recommended approach.

## Execution Plan

Step-by-step implementation plan.

## Consequences

Trade-offs and implications of this decision.

Using ADRs via MCP

AI agents can interact with ADRs through these MCP tools:

List ADRs

adr_list
  workspace?: string    # Target workspace (optional)
  status?: string       # Filter by status
  type?: string         # Filter by type
  tags?: string[]       # Filter by tags

Read an ADR

adr_read
  name: string          # ADR filename (without .md) or partial match
  workspace?: string    # Target workspace (optional)

Search ADRs

adr_search
  query?: string        # Search in titles, descriptions, content
  status?: string       # Filter by status
  type?: string         # Filter by type
  tags?: string[]       # Filter by tags
  workspace?: string    # Target workspace (optional)

Create an ADR

adr_create
  title: string         # Human-readable title
  type: string          # enhancement, debug, or research
  workingFolder: string # Project path
  description?: string  # Brief description
  status?: string       # Initial status (defaults to 'todo')
  tags?: string[]       # Tags for categorization
  content?: string      # Custom content (optional)
  workspace?: string    # Target workspace (optional)

Update an ADR

adr_update
  name: string          # ADR to update (partial match supported)
  status?: string       # New status
  title?: string        # New title
  description?: string  # New description
  content?: string      # New content
  tags?: string[]       # New tags
  type?: string         # New type
  workspace?: string    # Target workspace (optional)

Example Workflow

Here's how an AI agent might use ADRs for spec-driven development:

1. Create an ADR for a new feature

User: I want to add OAuth authentication to the API.

Agent: I'll create an ADR to plan this feature.
[calls adr_create with title="OAuth Authentication", type="enhancement"]

2. Update the ADR with research

Agent: I've researched OAuth providers. Let me update the ADR.
[calls adr_update with content including provider comparison]

3. Track progress

Agent: Starting implementation. Updating status.
[calls adr_update with status="in-progress"]

4. Complete the work

Agent: OAuth is implemented and tested.
[calls adr_update with status="completed"]

File Naming

ADRs are automatically named with a date prefix:

YYYY-MM-DD-title-slug.md

For example:

• 2026-01-15-oauth-authentication.md
• 2026-01-20-database-migration.md

Best Practices

1. One decision per ADR — Keep ADRs focused on a single decision
2. Update status regularly — Reflect current state accurately
3. Link to related ADRs — Use tags to group related decisions
4. Include context — Future readers need to understand the "why"
5. Document alternatives — Record what you didn't choose and why

ADR Location

ADRs are stored in the adrs/ folder within your workspace:

<workspace>/
└── adrs/
    ├── template.md
    ├── 2026-01-15-oauth-authentication.md
    └── 2026-01-20-database-migration.md

Next Steps

• Skills — Reusable AI instructions
• Knowledge Notes — Capture information
• MCP Integration — Connect to AI agents