setup-architect · git:20260504.f0e538c · 2026-05-04 · sha256 43874bf0070896b5
setup-architect git:20260504.f0e538cA
Immutable. This exact content is served forever at /api/v1/blob/43874bf0070896b5.
---
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 skill needs to know where to source templates from. Two paths:
- **Plugin path (canonical, 1.4.0+):** the framework templates live inside the installed plugin (typically under `~/.claude/plugins/marketplaces/codenamev-ai-software-architect/plugins/ai-software-architect/.architecture/templates/`). Use this when it's available.
- **Legacy clone path:** `.architecture/.architecture/` exists in the target project (a manual `git clone` of the framework). Used when the plugin isn't installed.
**Discovery order:** check plugin install location first (via `find ~/.claude/plugins -type d -name ai-software-architect 2>/dev/null` or env-var hints), then fall back to `.architecture/.architecture/`. If neither exists, stop and guide the user to install the plugin.
### 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)):
- Copy framework templates from the source location identified in step 1 into the target project's `.architecture/`
- Create directory structure (decisions/adrs, reviews, recalibration, etc.)
- Initialize `.architecture/config.yml` from `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.
**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 Architecture Team
Add technology-specific members to `.architecture/members.yml`:
- **JavaScript/TypeScript**: JavaScript Expert, framework specialists (React/Vue/Angular)
- **Python**: Python Expert, framework specialists (Django/Flask/FastAPI)
- **Ruby**: Ruby Expert, Rails Architect
- **Java**: Java Expert, Spring Boot Specialist
- **Go**: Go Expert, Microservices Architect
- **Rust**: Rust Expert, Systems Programmer
Use template from [assets/member-template.yml](assets/member-template.yml).
**Keep core members**: Systems Architect, Domain Expert, Security, Performance, Maintainability, AI Engineer, Pragmatic Enforcer.
**Customization details**: [references/customization-guide.md § Customize Team Members](references/customization-guide.md#customize-architecture-team-members)
### 5. Customize Architectural Principles
Add framework-specific principles to `.architecture/principles.md`:
- **React**: Component composition, hooks, unidirectional data flow
- **Rails**: Convention over configuration, DRY, RESTful design
- **Django**: Explicit over implicit, reusable apps, use built-ins
**Principle examples**: [references/customization-guide.md § Customize Principles](references/customization-guide.md#customize-architectural-principles)
### 6. Update CLAUDE.md Integration
If `CLAUDE.md` exists in project root, append framework usage section:
- Available commands
- Where to find documentation
- How to invoke skills
**Template**: [references/customization-guide.md § Update CLAUDE.md](references/customization-guide.md#update-claudemd-integration)
### 7. Cleanup
Remove framework development files:
- Framework documentation (README.md, USAGE*.md, INSTALL.md)
- Template `.git/` directory (with **critical safety checks**)
**⚠️ IMPORTANT**: Follow all safeguards in [references/installation-procedures.md § Cleanup](references/installation-procedures.md#cleanup-procedures).
### 8. Create Initial System Analysis
Generate comprehensive initial analysis document:
- Each member analyzes system from their perspective
- System overview (stack, structure, patterns)
- Strengths identified
- Concerns raised (with impact levels)
- Recommendations prioritized (Critical/Important/Nice-to-Have)
- Collaborative synthesis of findings
Save to `.architecture/reviews/initial-system-analysis.md`.
**Template**: [assets/initial-analysis-template.md](assets/initial-analysis-template.md)
### 9. Report to User
Provide setup summary:
```
AI Software Architect Framework Setup Complete
Customizations:
- Added [N] technology specialists: [list]
- Customized principles for: [frameworks]
- Configuration: Pragmatic mode [enabled/disabled]
Initial Analysis Highlights:
- Overall assessment: [assessment]
- Top strength: [strength]
- Top concern: [concern]
- Critical recommendation: [recommendation]
Location: .architecture/reviews/initial-system-analysis.md
Next Steps:
- Review initial analysis findings
- "List architecture members" to see customized team
- "Create ADR for [first decision]" to start documenting
- "What's our architecture status?" to verify setup
```
## Error Handling
**Framework source not found**:
```
I can't find the framework templates. Two installation options:
Recommended (plugin):
/plugin marketplace add codenamev/ai-software-architect
/plugin install ai-software-architect@ai-software-architect
Legacy (clone):
git clone https://github.com/codenamev/ai-software-architect .architecture/.architecture
After installing, run "Setup ai-software-architect" again.
```
**Already set up**:
```
Framework appears to be already set up.
To verify: "What's our architecture status?"
To reconfigure: Manually edit .architecture/members.yml and .architecture/principles.md
```
**Unclear project structure**:
```
Could not clearly identify project type. Please describe:
- Primary programming language(s)
- Framework(s) used
- Project purpose
I'll customize the framework accordingly.
```
## Related Skills
**After Setup**:
- `list-members` - View customized team
- `architecture-status` - Verify setup completion
- `create-adr` - Document first decision
**Initial Work**:
- Review `initial-system-analysis.md` findings
- `specialist-review` - Deep-dive on specific concerns
- `create-adr` - Document existing key decisions
**Workflow Example**:
Setup → Review initial analysis → Create ADRs → Status check → Regular reviews
## Notes
- Customize based on **actual** project, not every possible option
- Be specific about **why** each customization was made
- Initial analysis should be thorough but focused on actionable findings
- Safety checks during cleanup are **non-negotiable**
## Documentation
- **Installation details**: [references/installation-procedures.md](references/installation-procedures.md)
- **Customization guide**: [references/customization-guide.md](references/customization-guide.md)
- **Initial analysis template**: [assets/initial-analysis-template.md](assets/initial-analysis-template.md)
- **Member template**: [assets/member-template.yml](assets/member-template.yml)
- **Common patterns**: [../_patterns.md](../_patterns.md)