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:
- Templates and processes for documenting architectural decisions
AI-powered architecture documentation framework with ADRs, reviews, and pragmatic mode. Now available as Claude Code Plugin for easiest installation.
Architecture Documentation
Architecture Reviews - A multi-perspective review process with specialized reviewers
Architecture Recalibration - Process for translating reviews into concrete implementation plans
Progress Tracking - Tools for monitoring the implementation of architectural changes
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:
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: 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):
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:
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.
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
This updates the plugin wrapper and everything it bundles (skills, MCP server, generated subagents, ADR-validation hook) as one unit. The standalone ~/.claude/skills/ copy was retired in 1.4.0 (ADR-012); if you still have one, remove it and install the plugin.
If using MCP Server:
# Update to latest version
npm update -g ai-software-architect
# Or reinstall
npm install -g ai-software-architect
If using Traditional Setup: follow UPGRADE.md. Do not run git fetch / git reset --hard inside .architecture/ — setup removes that directory's .git, so those commands resolve to your own project repository and reset --hard discards your uncommitted work.
Note: Updates preserve your project's custom architecture artifacts (ADRs, reviews, member customizations) while updating framework files (templates, base configuration, scripts).
What Gets Updated
✅ Updated Files:
.architecture/templates/ - Templates for ADRs, reviews, AGENTS.md
.architecture/principles.md - Core architectural principles (if not customized)
Framework scripts and helper files
MCP server (if using MCP installation)
Plugin skills, subagents, and hook (if using the plugin installation)
✅ Preserved Files:
.architecture/decisions/adrs/ - Your architectural decision records
.architecture/reviews/ - Your architecture review documents
.architecture/recalibration/ - Your recalibration plans
.architecture/members.yml - Your customized team members
.architecture/config.yml - Your configuration settings
All your project-specific customizations
See UPGRADE.md for detailed upgrade instructions and troubleshooting.
Directory Structure
.architecture/
├── decisions/
│ ├── adrs/ # Architectural Decision Records
│ └── principles.md # Architectural principles document
├── reviews/ # Architecture review documents
├── recalibration/ # Recalibration plans and tracking
├── comparisons/ # Version-to-version comparisons
├── docs/ # General architecture documentation
├── agent_docs/ # Detailed AI assistant guidance (progressive disclosure)
├── templates/ # Templates for various documents
└── members.yml # Architecture review team members
Usage with AI Assistants
This framework is designed to work seamlessly with AI assistants. Each assistant has specialized instructions in the .coding-assistants directory.
Create ADR: "Document architectural decision for [topic]", "Write ADR about [topic]"
Reviews: "Conduct architecture review", "Review architecture for [scope]"
Specialist: "Get [specialist]'s opinion on [topic]", "Have [role] review [component]"
Adding new specialists: edit .architecture/members.yml directly and run node tools/cli.js generate-subagents to refresh the corresponding agents/<id>.md subagent. Auto-creation during specialist-review was removed in 1.5.0 (see ADR-013) — the trade-off keeps the generated subagents and members.yml in sync at all times.
"What are the architectural implications of this change?"
"Review this database schema for performance"
"Does this code follow our architectural principles?"
Other AI Assistants
Support for additional AI assistants can be added by creating appropriate configuration files in the .coding-assistants directory following the established patterns.
Key Features
Architectural Wisdom
The framework incorporates wisdom from influential software architects including Martin Fowler, Sandi Metz, Robert C. Martin, Eric Evans, Sarah Mei, Obie Fernandez, and others. These principles are embedded in the architectural documentation.
Externalizing Senior Thinking: The framework systematically captures "senior engineering thinking"—the invisible architectural reasoning about blast radius, reversibility, timing, and social cost that typically stays undocumented. By forcing explicit documentation of these considerations, we're creating the corpus of senior architectural thinking that the industry lacks.
Using with Implementation Guidance: When using both Pragmatic Mode and Implementation Guidance together, pragmatic mode respects your configured security practices and methodological choices while challenging unnecessary complexity in other areas. The pragmatic enforcer ensures implementations remain simple while still following your team's documented standards for security, testing, and code quality.
Implementation Guidance
Configuration-driven implementation that applies your team's methodology and best practices automatically:
上次檢查時間:2026-11-10。 AI-powered architecture documentation framework with ADRs, reviews, and pragmatic mode. Now available as Claude Code Plugin for easiest installation.