ai-software-architect

AI Software Architect

A markdown-based framework for implementing rigorous software architecture practices in any project, with specialized AI assistant integration.

Overview

This framework provides a structured approach to:

1. Architecture Documentation - Templates and processes for documenting architectural decisions
2. Architecture Reviews - A multi-perspective review process with specialized reviewers
3. Architecture Recalibration - Process for translating reviews into concrete implementation plans
4. Progress Tracking - Tools for monitoring the implementation of architectural changes
5. AI Integration - Seamless collaboration with AI coding assistants

For detailed usage instructions, see USAGE.md. For troubleshooting and advanced usage, see TROUBLESHOOTING.md.

Installation

Choose the installation method for your AI assistant:

Claude Code Installation

Claude Code supports three installation methods:

Option 1: Claude Code Plugin (Recommended) 🆕

Install via the Claude Code plugin system with automatic updates:

# In Claude Code, run these commands:
/plugin marketplace add codenamev/ai-software-architect
/plugin install ai-software-architect@ai-software-architect

That's it! The framework is now available in all your projects — including the seven skills, MCP server, and generated subagents as a single unit.

See USAGE-WITH-CLAUDE-PLUGIN.md for detailed installation guide, troubleshooting, and comparison with other methods.

Benefits: Simplest installation, automatic updates, works across all projects, no manual file management, ships skills + MCP + hooks as a unit

When to use: You use Claude Code and want the most streamlined experience with automatic updates.

---

Option 2: MCP Server

npm install -g ai-software-architect

Then register it with Claude Code (claude mcp add ai-software-architect -- mcp), or add it to ~/.claude.json (user scope) or your project's .mcp.json:

{
  "mcpServers": {
    "ai-software-architect": {
      "command": "mcp",
      "args": []
    }
  }
}

The npm package carries the server, not the framework tree: setup_architecture installs from the Claude Code plugin if present, otherwise from a clone named by CLAUDE_PLUGIN_ROOT in the server's env (see mcp/README.md). The other five tools read the project's own .architecture/ and need no framework tree.

Benefits: Programmatic automation, external tool integration, advanced project analysis

When to use: You need programmatic access or integration with other MCP-compatible tools.

---

Option 3: Traditional Setup

Setup architecture using: https://github.com/codenamev/ai-software-architect

See USAGE-WITH-CLAUDE.md for detailed instructions.

Benefits: No installation required, works immediately, maximum flexibility

When to use: Quick experiments, no installation permissions, or maximum customization needs.

Cursor Installation

If you're using Cursor, you have two options:

Option 1: MCP Server (Recommended)

npm install -g ai-software-architect

Then configure in Cursor settings (settings.json), pointing CLAUDE_PLUGIN_ROOT at a clone so setup_architecture has a framework tree to install from (Cursor has no Claude Code plugin to fall back on; the other five tools read the project's own .architecture/ once it exists and need no framework tree):

{
  "mcp.servers": {
    "ai-software-architect": {
      "command": "mcp",
      "args": [],
      "env": { "CLAUDE_PLUGIN_ROOT": "/path/to/ai-software-architect" }
    }
  }
}

Option 2: Traditional Setup

Setup architecture using @https://github.com/codenamev/ai-software-architect

See USAGE-WITH-CURSOR.md for detailed traditional setup instructions.

GitHub Copilot / Codex Installation

MCP Support: GitHub Copilot and Codex currently have limited MCP support. Use the traditional setup method:

Setup architecture using: https://github.com/codenamev/ai-software-architect

See USAGE-WITH-CODEX.md for detailed setup instructions. The framework will be configured with context files that GitHub Copilot and Codex can automatically understand.

Installation Method Comparison

Choose the right installation method for your workflow:

Feature	Plugin 🆕	MCP Server	Traditional	Best For
Installation	Two commands	npm install -g	Clone repo	Plugin: SimplestMCP: ProgrammaticTraditional: Quick
Setup Complexity	⭐ Simplest	⭐⭐ Medium	⭐ Simple	Plugin easiest
AI Assistants	Claude Code	Claude, Cursor	All assistants	Plugin: Claude onlyMCP: Claude, CursorTraditional: Universal
Invocation	Automatic (MCP + Skills)	Programmatic tools	Natural language	Plugin: SeamlessMCP: PreciseTraditional: Flexible
Dependencies	Node.js ≥22 (auto)	Node.js ≥22	None	Traditional: No depsPlugin & MCP: Node auto-managed
Auto-Updates	✅ /plugin update	✅ npm update	❌ Git pull	Plugin & MCP: Auto-update
Offline Use	⚠️ Needs npm	⚠️ Needs npm	✅ Full	Traditional: Offline ready
Tier-1 Deterministic Tools	✅ All 6	✅ All 6	✅ All 6	All methods identical
Tier-2 Reviews / Enforcement	✅ Skills	❌ MCP-only install	✅ Yes	Plugin & Traditional run reviews
Advanced Features	⚠️ 33%	⚠️ 33%	✅ 100%	Traditional most complete
Input Validation	✅ Yes	⚠️ Basic	❌ No	Plugin best
Pragmatic Mode	✅ Yes	⚠️ Config only	✅ Yes	MCP configures; reviews are Tier 2
Dynamic Members	✅ Yes	❌ No	✅ Yes	Plugin & Traditional auto-create
Recalibration	❌ No	❌ No	✅ Yes	Traditional only
Project Analysis	✅ Advanced	✅ Advanced	⚠️ Basic	Plugin & MCP: Advanced
Error Handling	✅ Explicit	✅ Explicit	⚠️ Implicit	Plugin, MCP clearest
Documentation	✅ Detailed	✅ Detailed	✅ Detailed	All well-documented
Customization	⚠️ Fork npm pkg	⚠️ Fork npm pkg	✅ Easy	Traditional most flexible
Multi-Project	✅ Automatic	✅ Automatic	⚠️ Per-project	Plugin, MCP global
Version Control	❌ External	❌ External	✅ In repo	Traditional best for VCS

Recommendation by Use Case

Choose Plugin if (Recommended for most Claude Code users):

• ✅ You use Claude Code exclusively
• ✅ You want the absolute simplest installation (2 commands)
• ✅ You want automatic updates (/plugin update)
• ✅ You're okay with internet dependency for updates
• ✅ You want zero manual file management

Choose MCP Server if:

• You use Claude Code or Cursor
• You want programmatic automation
• You need advanced project analysis
• You're building integrations
• You prefer npm-based package management

Choose Traditional if:

• You use multiple AI assistants (Copilot, Codex, etc.)
• You want maximum flexibility and customization
• You need recalibration (only the Traditional path implements it)
• You want the framework files in your repository
• You need offline capability with full features

Feature Availability Matrix

Feature	Plugin 🆕	MCP Server	Traditional
Setup Architecture (Tier 1)	✅	✅	✅
Create ADR (Tier 1)	✅	✅	✅
List Members (Tier 1)	✅	✅	✅
Get Status (Tier 1)	✅	✅	✅
Configure Pragmatic Mode (Tier 1)	✅	✅	✅
Implementation Guidance (Tier 1)	✅	✅	✅
Architecture Review (Tier 2)	✅ Skills	❌ MCP tool	✅
Specialist Review (Tier 2)	✅ Skills	❌ MCP tool	✅
Pragmatic Enforcement (Tier 2)	✅ Subagent	❌ MCP tool	✅
Dynamic Member Creation	✅	❌	✅
Recalibration Process	❌	❌	✅
Initial System Analysis	✅	✅	✅
Input Validation	✅	⚠️	❌
Tool Restrictions	✅	N/A	N/A
Auto-Update	✅	✅	❌

Legend: ✅ Fully supported, ⚠️ Partially supported, ❌ Not supported, N/A Not applicable

Note: The Plugin bundles the same npm package as the MCP Server option, plus the seven skills, generated subagents, and ADR-validation hook as a single install unit.

Two-tier capability model (see ADR-015): Tier-1 operations are deterministic file/config tasks available on every channel, including the MCP server. Tier-2 capabilities — orchestrated architecture reviews, specialist reviews, and pragmatic enforcement — require LLM reasoning and are delivered only through the plugin/Skills (architecture-review, specialist-review, and the pragmatic-enforcer subagent), not as MCP tools. The Plugin gets Tier 2 via its bundled Skills; an MCP-only install does not.

See Feature Parity Analysis for detailed comparison.

Quick Installation Decision Tree

Do you use Claude Code?
├─ Yes → ✅ Choose Plugin (simplest, ships skills + MCP + hooks together)
│
└─ No → Do you use Cursor?
         ├─ Yes → ✅ Choose MCP Server (Cursor compatible)
         └─ No  → Choose Traditional (universal — Copilot, Codex, etc.)

Still unsure? Start with Plugin if you use Claude Code. It's the easiest to set up and you can always switch later. All methods provide identical core functionality.

Getting Started

After installation, start using the framework with these standardized commands:

Standard Commands

Setup:

Setup ai-software-architect

Create ADR:

Create ADR for [decision topic]

Example: "Create ADR for PostgreSQL database choice"

Architecture Review:

Start architecture review for [version/feature]

Examples: "Start architecture review for version 2.0.0" or "Start architecture review for authentication feature"

Specialist Review:

Ask [Specialist Name] to review [target]

Example: "Ask Security Specialist to review API authentication"

List Members:

List architecture members

Check Status:

What's our architecture status?

Enable Pragmatic Mode (Optional):

Enable pragmatic mode

Example: "Enable pragmatic mode with balanced intensity"

Implement with Methodology:

Implement [feature] as the architects

Examples: "Implement authentication as the architects" or "Implement user registration as the architects"

Recalibration (Traditional method):

Start architecture recalibration for [target]

See USAGE.md for detailed workflow instructions and platform-specific variations.

Upgrading

Already have AI Software Architect installed? Update to get the latest features and improvements.

Quick Update (Recommended)

For any AI assistant, simply ask:

Update the software architect framework from https://github.com/codenamev/ai-software-architect

Your AI assistant will fetch the latest framework files from the main branch while preserving your project's architecture artifacts (ADRs, reviews, recalibration plans).

Manual Update Methods

If using the Claude Code Plugin:

# In Claude Code:
/plugin update ai-software-architect@ai-software-architect