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 four 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 anthropics/ai-software-architect
/plugin install ai-software-architect@ai-software-architect

That's it! The framework is now available in all your projects.

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

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

---

Option 2: Claude Skills

Install as reusable skills that work across all your projects:

# Clone and install skills
git clone https://github.com/codenamev/ai-software-architect /tmp/ai-architect-$$
cp -r /tmp/ai-architect-$$/.claude/skills ~/.claude/
# Temporary directory will be cleaned up automatically, or you can remove it:
# rm -rf /tmp/ai-architect-$$

Then in any project:

Setup ai-software-architect

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

Benefits: No dependencies, automatic skill invocation, portable, works offline

When to use: You want manual control over updates or need offline availability.

---

Option 3: MCP Server

npm install -g ai-software-architect

Then configure in ~/.claude/config.json:

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

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

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

---

Option 4: 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):

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

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: