solutions-architecture-agent

AI Solutions Architecture Agent

A production-grade Claude Code plugin that covers the complete pre-sales SA lifecycle — requirements through proposal — in a single conversation. Built by a principal SA for principal SAs. Not a chatbot wrapper: a structured, reviewable, expert system.

Turn a project idea into a complete, Well-Architected solution design — requirements, architecture, security review, cost estimate, project plan, and client-ready proposal — in a single Claude Code session.

Version: 1.1.0 | Owner: Modular Earth LLC | Validated: 9-skill end-to-end against a HIPAA-compliant healthcare IBMi migration (500+ users). See example outputs | Changelog

---

Why This Exists

Traditional SA work is slow, inconsistent, and hard to review. A single engagement produces requirements documents, architecture diagrams, security reviews, cost estimates, and proposals — each assembled manually, each varying by the individual SA. The output is hard to diff, hard to audit, and hard to reproduce.

This agent makes SA work reproducible, auditable, and peer-reviewable. Every output is a structured KB artifact with a JSON schema, a version number, and a declared dependency chain — not a free-form conversation. Each skill runs in isolation, produces a single file it owns, and never writes to a file it doesn't own. Human review is mandatory at every checkpoint.

---

Quick Start

# Clone
git clone https://github.com/Modular-Earth-LLC/solutions-architecture-agent.git
cd solutions-architecture-agent

# Install Python test dependencies
uv sync

# Load plugin (development — reads live from this directory)
claude --plugin-dir .

# Run your first skill
# Type: /requirements
# Or: "I need to design a system for [your project]"

Claude loads CLAUDE.md and .claude/rules/ automatically. Skills appear as solutions-architecture-agent:<skill-name>.

---

Skills

Skill	Command	What It Produces
Requirements Discovery	/requirements	Progressive discovery workshop output — AI suitability score, classified pain points, 7-category requirements list, BANT qualification
Solution Architecture	/architecture	Tech stack selection with cited benchmarks, component design, 3 Mermaid diagrams, AWS/Azure/GCP Well-Architected scores per pillar
Data Modeling	/data-model	ER schema, vector DB collection design (embedding model, chunking strategy, reranking), graph schema, governance policy
Security & Privacy Review	/security-review	STRIDE threat model (6 parallel sub-agents), defense-in-depth architecture, compliance posture per framework, AI threat mapping
Integration Planning	/integration-plan	API contract definitions, migration strategy (strangler fig/parallel run), data flow mappings, legacy bridging patterns
Estimation	/estimate	3-point LOE estimates, team composition, infrastructure cost model, confidence scoring (HIGH/MEDIUM/LOW)
Technical Project Plan	/project-plan	Phased roadmap, 2-week sprint plans, risk register, dependency graph, Fist-of-Five decision gates
Proposal Assembly	/proposal	SOW (12 sections), discovery proposal, internal pitch deck, or custom-format document — assembled from KB
Deliverable Review	/review	LLM-as-judge 3-iteration review, 5-dimension scoring (0-10 per dimension), Well-Architected pillar scores for architecture reviews

---

Design Philosophy

This agent was designed around three non-obvious architectural decisions. See DESIGN_RATIONALE.md for the full reasoning.

Single agent with skills, not multi-agent orchestration. Research shows multi-agent pipelines degrade sequential reasoning by 39-70% (arXiv:2512.08296). One agent with structured skills eliminates inter-agent handoff failures and maintains full conversation context across the engagement.

Blackboard pattern for skill communication. Skills communicate exclusively through JSON files in knowledge_base/. No direct skill-to-skill calls. This supports independent skill testing, replay/resume capability, and human auditability of every intermediate state.