/setup-architect

name: setup-architect
description: Sets up and installs the AI Software Architect framework in a NEW project for the FIRST time. Use when the user requests "Setup .architecture", "Setup ai-software-architect", "Initialize architecture framework", "Install software architect", or similar setup/installation phrases. Do NOT use for checking status (use architecture-status), creating documents (use create-adr or reviews), or when framework is already set up.
allowed-tools: Read,Write,Edit,Glob,Grep,Bash(git:*,npm:*,node:*,mkdir:*,cp:*,ls:*,test:*)
disable-model-invocation: true

Setup AI Software Architect Framework

Sets up and customizes the AI Software Architect framework for a project.

Overview

This skill performs a complete framework installation: 1. Locates the framework source (plugin install dir or legacy clone) 2. Analyzes the target project (languages, frameworks, structure, patterns) 3. Scaffolds `.architecture/` in the target project from framework templates 4. Customizes team members and principles for the detected tech stack 5. Performs an initial system analysis 6. Reports customizations and findings, with explicit next steps

**Detailed procedures**: [references/installation-procedures.md](references/installation-procedures.md) **Customization guide**: [references/customization-guide.md](references/customization-guide.md)

What happens when you run `Setup ai-software-architect`

The skill creates a `.architecture/` directory in your **target project** (not in this plugin's repo) and populates it with templates customized for your tech stack. After it finishes you'll have:

• `.architecture/decisions/adrs/` — empty, ready for `create-adr`
• `.architecture/reviews/initial-system-analysis.md` — your team's first pass at the codebase
• `.architecture/members.yml` — team customized for your detected stack
• `.architecture/principles.md` — principles tailored to your frameworks
• `.architecture/config.yml` — operational config (pragmatic mode, etc.)
• `.architecture/templates/` — ADR + review templates ready to use

The skill writes **only into your target project's `.architecture/`**. It does not modify code outside that directory.

High-Level Workflow

1. Locate framework source

The framework templates can live in two places: inside the installed Claude Code plugin (canonical, 1.4.0+) or under a legacy `.architecture/.architecture/` clone in the target project. Discovery is deterministic — run the framework's own CLI:

# Locate the plugin install on disk first; tools/cli.js lives inside it.
TOOLS_CLI=""
if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/tools/cli.js" ]; then
  TOOLS_CLI="$CLAUDE_PLUGIN_ROOT/tools/cli.js"
else
  TOOLS_CLI=$(find ~/.claude/plugins -type f -name cli.js -path '*ai-software-architect/tools/*' 2>/dev/null | head -1)
fi

if [ -z "$TOOLS_CLI" ] && [ -f ".architecture/.architecture/tools/cli.js" ]; then
  # Legacy clone path: the cli ships in the cloned repo.
  TOOLS_CLI=".architecture/.architecture/tools/cli.js"
fi

if [ -z "$TOOLS_CLI" ]; then
  echo "Framework not found. Install the plugin or clone manually — see error message below."
  exit 1
fi

# Resolve the framework source via the canonical discovery logic.
FRAMEWORK_ROOT=$(node "$TOOLS_CLI" find-source)

Discovery order (the order and sentinel live in `tools/lib/setup-source-discovery.js`, tested via `tools/test/setup-source-discovery.test.js`; the `~/.claude/plugins` walk itself is `findPluginCandidates` in `tools/cli.js`, mirrored by the MCP server's `listPluginCandidates` and exercised by `mcp/test/setup-source.test.js`):

1. `${CLAUDE_PLUGIN_ROOT}` env var (if set and contains `.architecture/templates/adr-template.md`). 2. Recursive search of `~/.claude/plugins/` for any `ai-software-architect/` directory, or an immediate subdirectory of one (Claude Code installs under `cache/<marketplace>/<plugin>/<version>/`), containing the sentinel; versions marked `.orphaned_at` by a plugin update are skipped. 3. `.architecture/.architecture/` in the target project (legacy clone path).

If `find-source` exits non-zero, surface its error message verbatim — it tells the user exactly which install option to take.

2. Analyze Project

Identify project characteristics:

• **Languages**: JavaScript/TypeScript, Python, Ruby, Java, Go, Rust
• **Frameworks**: React, Vue, Django, Rails, Spring, etc.
• **Infrastructure**: Testing setup, CI/CD, package managers
• **Structure**: Directory layout, architectural patterns

Use `Glob` and `Grep` to detect technologies, `Read` to examine configs.

3. Install Framework

Execute installation steps (see [references/installation-procedures.md](references/installation-procedures.md)):

# $FRAMEWORK_ROOT is from step 1.
cp -r "$FRAMEWORK_ROOT/.architecture/templates" .architecture/templates
cp "$FRAMEWORK_ROOT/.architecture/principles.md" .architecture/principles.md
cp "$FRAMEWORK_ROOT/.architecture/members.yml" .architecture/members.yml
cp "$FRAMEWORK_ROOT/.architecture/config.yml" .architecture/config.yml

mkdir -p .architecture/decisions/adrs
mkdir -p .architecture/reviews
mkdir -p .architecture/recalibration
mkdir -p .architecture/comparisons
mkdir -p .architecture/agent_docs

• Create directory structure (decisions/adrs, reviews, recalibration, etc.)
• Initialize `.architecture/config.yml` from the source location's `.architecture/config.yml` (not `templates/config.yml`)
• Set up agent documentation (ADR-006 progressive disclosure)
• **Legacy clone path only:** remove `.architecture/.architecture/` and (with safeguards) the cloned `.git/` directory. **Plugin path:** no clone removal needed — the plugin's install dir stays where it is under `~/.claude/plugins/`.

**Critical (legacy clone path only):** Follow safety procedures when removing `.git/` directory. See [references/installation-procedures.md § Cleanup Procedures](references/installation-procedures.md#cleanup-procedures).

4. Customize Archit