@arthai/agents 1.0.0

package/skills/solution-architect/SKILL.md

@@ -0,0 +1,566 @@
+---
+name: solution-architect
+description: "Design AI solutions for consulting engagements. Usage: /solution-architect <client-name> [--initiative <name>]"
+user-invocable: true
+arguments: "<client-name> [--initiative <name>]"
+---
+
+# Solution Architect Skill
+
+Designs comprehensive AI solutions for consulting engagements, including technology selection, architecture diagrams, implementation plans, and cost models.
+
+## Trigger
+
+When the user invokes `/solution-architect <client-name>` with an optional `--initiative <name>` to target a specific initiative.
+
+## Prerequisites
+
+- Client profile at `clients/<client-name>/profile.json`
+- Discovery outputs at `clients/<client-name>/discovery/`
+- Assessment outputs at `clients/<client-name>/assessment/`
+- Selected initiatives (from opportunity-map or user specification)
+
+## Steps
+
+### 1. Load Context
+
+Read and synthesize inputs from prior skill outputs:
+
+**From Discovery:**
+- `discovery/market-research.md` — industry benchmarks, adoption rates
+- `discovery/competitive-landscape.md` — competitor capabilities
+- `discovery/industry-trends.md` — technology trajectory
+
+**From Assessment:**
+- `assessment/current-state.md` — existing tech stack, data landscape
+- `assessment/ai-readiness.md` — maturity scores, gaps
+- `assessment/stakeholder-map.md` — decision makers, champions
+
+**From Opportunity Map:**
+- `assessment/opportunity-matrix.md` — scored initiatives
+- Selected initiative(s) to architect
+
+If `--initiative` is specified, filter to that single initiative. Otherwise, architect solutions for the top 3 initiatives by score.
+
+For each selected initiative, extract:
+- Business objective and success metrics
+- Data requirements and availability
+- Integration points with existing systems
+- Stakeholder requirements and constraints
+- Timeline and budget constraints
+
+### 2. Technology Selection Matrix
+
+For each component of the solution, evaluate options across key dimensions:
+
+```markdown
+## Technology Selection Matrix
+
+### [Initiative Name]
+
+| Component | Option A | Option B | Option C | Recommendation |
+|-----------|----------|----------|----------|----------------|
+| **LLM Provider** | | | | |
+| Capability | | | | |
+| Cost/month | | | | |
+| Hosting | Cloud/On-prem/Hybrid | | | |
+| Data Privacy | Level 1-4 | | | |
+| Integration Effort | Low/Med/High | | | |
+| Vendor Lock-in Risk | Low/Med/High | | | |
+| **Vector Database** | | | | |
+| Capability | | | | |
+| Cost/month | | | | |
+| Hosting | | | | |
+| Data Privacy | | | | |
+| Integration Effort | | | | |
+| Vendor Lock-in Risk | | | | |
+| **Orchestration** | | | | |
+| **Data Pipeline** | | | | |
+| **Monitoring** | | | | |
+| **Frontend/UX** | | | | |
+```
+
+**Data Privacy Levels:**
+- Level 1: Public data only, cloud OK
+- Level 2: Internal data, SOC 2 required
+- Level 3: PII/sensitive data, encryption at rest/transit required
+- Level 4: Regulated data (HIPAA/GDPR/CCPA), on-prem or private cloud required
+
+**Scoring criteria (1-5 for each):**
+- Functional fit for use case
+- Total cost of ownership
+- Team skill match
+- Scalability headroom
+- Ecosystem/community support
+
+### 3. Build vs Buy Decisions
+
+For each major component, provide a structured recommendation:
+
+```markdown
+## Build vs Buy Analysis
+
+### [Component Name]
+
+| Factor | Build Custom | SaaS Solution | Open Source |
+|--------|-------------|---------------|------------|
+| **Upfront Cost** | | | |
+| **Monthly Cost** | | | |
+| **Time to Deploy** | | | |
+| **Customizability** | High | Low-Med | High |
+| **Maintenance Burden** | High | Low | Med-High |
+| **Data Control** | Full | Limited | Full |
+| **Vendor Risk** | None | Med-High | Low |
+| **Skill Required** | High | Low | Med |
+
+**Pros:**
+- Build: [specific advantages for this client]
+- Buy: [specific advantages for this client]
+- Open Source: [specific advantages for this client]
+
+**Cons:**
+- Build: [specific disadvantages]
+- Buy: [specific disadvantages]
+- Open Source: [specific disadvantages]
+
+**Recommendation:** [Build/Buy/Open Source] because [1-2 sentence justification tied to client constraints]
+```
+
+### 4. Architecture Design
+
+Create architecture diagrams using Mermaid syntax. Select the most appropriate template from the reference architectures below and customize for the client's needs.
+
+#### System Architecture (Mermaid Flowchart)
+
+```mermaid
+flowchart TB
+    subgraph Users["User Layer"]
+        WebApp[Web Application]
+        API[API Clients]
+        Mobile[Mobile App]
+    end
+
+    subgraph Gateway["API Gateway"]
+        Auth[Authentication]
+        RateLimit[Rate Limiting]
+        Router[Request Router]
+    end
+
+    subgraph Core["AI Core"]
+        Orchestrator[AI Orchestrator]
+        LLM[LLM Service]
+        Embeddings[Embedding Service]
+        VectorDB[(Vector Store)]
+        Cache[(Response Cache)]
+    end
+
+    subgraph Data["Data Layer"]
+        ETL[ETL Pipeline]
+        DataWarehouse[(Data Warehouse)]
+        FeatureStore[(Feature Store)]
+    end
+
+    subgraph Ops["Operations"]
+        Monitor[Monitoring]
+        Logging[Centralized Logging]
+        Alerts[Alert Manager]
+    end
+
+    Users --> Gateway --> Core
+    Core --> Data
+    Ops --> Core
+    Ops --> Gateway
+```
+
+#### Data Pipeline (Mermaid Sequence Diagram)
+
+```mermaid
+sequenceDiagram
+    participant Source as Data Sources
+    participant Ingest as Ingestion Layer
+    participant Process as Processing
+    participant Store as Storage
+    participant Serve as Serving Layer
+    participant Monitor as Monitoring
+
+    Source->>Ingest: Raw data (batch/stream)
+    Ingest->>Process: Validated data
+    Process->>Process: Transform, enrich, embed
+    Process->>Store: Processed artifacts
+    Store->>Serve: Query/retrieve
+    Serve->>Monitor: Metrics, latency, quality
+    Monitor-->>Process: Feedback loop
+```
+
+#### Integration Points Diagram
+
+Document every integration with external systems:
+
+```markdown
+| Integration Point | System | Protocol | Direction | Auth | Data Volume | SLA |
+|-------------------|--------|----------|-----------|------|-------------|-----|
+| CRM sync | Salesforce | REST API | Bidirectional | OAuth 2.0 | ~10K records/day | 99.9% |
+| Document ingest | SharePoint | Graph API | Inbound | App token | ~500 docs/week | 99.5% |
+| Notification | Slack | Webhook | Outbound | Bot token | ~100 msgs/day | Best effort |
+```
+
+#### Security and Privacy Design
+
+```markdown
+## Security Architecture
+
+### Authentication & Authorization
+- [Auth method: SSO/OAuth/API keys]
+- [RBAC model: roles and permissions]
+- [Token management: rotation, expiry]
+
+### Data Protection
+- Encryption at rest: [method]
+- Encryption in transit: [method]
+- PII handling: [anonymization/pseudonymization approach]
+- Data retention: [policy]
+- Right to deletion: [mechanism]
+
+### Compliance
+- [Relevant regulations: GDPR, HIPAA, SOC 2, etc.]
+- [Audit trail requirements]
+- [Data residency requirements]
+
+### AI-Specific Security
+- Prompt injection mitigation
+- Output filtering and guardrails
+- Model access controls
+- Training data governance
+```
+
+### 5. Implementation Plan
+
+#### Sequenced Build Plan (Mermaid Gantt)
+
+```mermaid
+gantt
+    title [Initiative Name] Implementation Plan
+    dateFormat YYYY-MM-DD
+    axisFormat %b %Y
+
+    section Foundation
+    Infrastructure setup       :a1, 2026-04-01, 2w
+    Data pipeline MVP          :a2, after a1, 3w
+    Authentication/security    :a3, after a1, 2w
+
+    section Core Build
+    AI model integration       :b1, after a2, 4w
+    Core feature development   :b2, after a3, 6w
+    Integration development    :b3, after b1, 3w
+
+    section Testing & Launch
+    Integration testing        :c1, after b2, 2w
+    UAT with stakeholders      :c2, after c1, 2w
+    Pilot launch               :c3, after c2, 1w
+    Monitor and iterate        :c4, after c3, 4w
+```
+
+#### Resource Requirements
+
+```markdown
+| Role | Headcount | Duration | Skills Required | Internal/External |
+|------|-----------|----------|-----------------|-------------------|
+| ML Engineer | 1-2 | 6 months | Python, LLM fine-tuning, RAG | Internal preferred |
+| Data Engineer | 1 | 4 months | ETL, data pipeline, vector DB | Either |
+| Full-Stack Dev | 1-2 | 6 months | React/Next.js, API design | Internal |
+| DevOps/MLOps | 0.5 | Ongoing | K8s, CI/CD, monitoring | Internal |
+| Project Manager | 0.5 | 6 months | AI project delivery | Internal |
+| AI/ML Architect | 0.25 | Ongoing | Solution design, reviews | Consulting |
+```
+
+#### Risk Register
+
+```markdown
+| # | Risk | Probability | Impact | Mitigation | Owner | Status |
+|---|------|-------------|--------|------------|-------|--------|
+| 1 | Data quality insufficient for AI | Medium | High | Data audit sprint in Week 2, quality gates | Data Lead | Open |
+| 2 | LLM accuracy below threshold | Medium | High | Evaluation framework, fallback to rules | ML Lead | Open |
+| 3 | Integration delays with legacy systems | High | Medium | API adapter pattern, mock interfaces | Tech Lead | Open |
+| 4 | User adoption resistance | Medium | High | Change management plan, early champions | PM | Open |
+| 5 | Cost overrun on cloud AI services | Low | Medium | Usage caps, cost monitoring alerts, caching | DevOps | Open |
+```
+
+#### Testing Strategy
+
+```markdown
+## Testing Strategy
+
+### Unit Testing
+- Minimum 80% code coverage
+- AI component testing with fixed seed inputs
+- Mock external API calls
+
+### Integration Testing
+- End-to-end pipeline validation
+- Cross-system data flow verification
+- Error handling and retry logic
+
+### AI-Specific Testing
+- Accuracy/quality benchmarks against golden dataset
+- Hallucination detection test suite
+- Prompt robustness testing (adversarial inputs)
+- Latency and throughput benchmarks
+- Cost-per-query tracking
+
+### UAT Criteria
+- [ ] Core workflows complete without errors
+- [ ] Response quality meets stakeholder expectations
+- [ ] Performance within SLA (< [X]s response time)
+- [ ] Edge cases handled gracefully
+- [ ] Feedback mechanism functional
+```
+
+### 6. Cost Model
+
+#### Total Cost of Ownership (3-Year)
+
+```markdown
+## Cost Model: [Initiative Name]
+
+### Year 1 — Build + Initial Operations
+| Category | Monthly | Annual | Notes |
+|----------|---------|--------|-------|
+| Cloud Infrastructure | | | |
+| AI/LLM API Costs | | | |
+| Vector DB Hosting | | | |
+| SaaS Licenses | | | |
+| Personnel (build) | | | |
+| Consulting/External | | | |
+| Training & Enablement | | | |
+| **Year 1 Total** | | **$XXX,XXX** | |
+
+### Year 2 — Scale + Optimize
+| Category | Monthly | Annual | Notes |
+|----------|---------|--------|-------|
+| Cloud Infrastructure | | | +20% scaling |
+| AI/LLM API Costs | | | Volume optimization |
+| Personnel (maintain) | | | Reduced from build |
+| SaaS Licenses | | | |
+| **Year 2 Total** | | **$XXX,XXX** | |
+
+### Year 3 — Steady State
+| Category | Monthly | Annual | Notes |
+|----------|---------|--------|-------|
+| Cloud Infrastructure | | | Optimized |
+| AI/LLM API Costs | | | Mature usage |
+| Personnel (maintain) | | | |
+| SaaS Licenses | | | |
+| **Year 3 Total** | | **$XXX,XXX** | |
+
+### 3-Year TCO: $XXX,XXX
+```
+
+#### Break-Even Analysis
+
+```markdown
+### Break-Even Analysis
+
+| Metric | Value |
+|--------|-------|
+| Total Investment (Year 1) | $XXX,XXX |
+| Monthly Benefit (once live) | $XX,XXX |
+| Break-Even Point | Month [X] |
+| 3-Year Net Benefit | $XXX,XXX |
+| 3-Year ROI | XXX% |
+
+**Assumptions:**
+1. [Key assumption 1]
+2. [Key assumption 2]
+3. [Key assumption 3]
+```
+
+#### Cost Scaling Projection
+
+```markdown
+### Cost Scaling Projection
+
+| Scale Factor | Users | Queries/Day | Monthly Cost | Cost/Query |
+|-------------|-------|-------------|--------------|------------|
+| Pilot | 50 | 500 | $X,XXX | $X.XX |
+| Department | 500 | 5,000 | $XX,XXX | $X.XX |
+| Enterprise | 5,000 | 50,000 | $XX,XXX | $X.XX |
+| Full Scale | 20,000 | 200,000 | $XXX,XXX | $X.XX |
+```
+
+### 7. Generate Output Files
+
+Create output files in `clients/<client-name>/architecture/`:
+
+- **`architecture/solution-design.md`** — System architecture, integration points, security design, Mermaid diagrams
+- **`architecture/technology-selection.md`** — Selection matrix, build vs buy, vendor comparisons
+- **`architecture/implementation-plan.md`** — Gantt chart, resource plan, risk register, testing strategy
+- **`architecture/cost-model.md`** — TCO, break-even, scaling projections
+
+## Reference Architecture Templates
+
+Use the appropriate template as a starting point and customize for the client's specific needs.
+
+### Template 1: RAG Pipeline
+
+```mermaid
+flowchart LR
+    subgraph Ingest["Document Ingestion"]
+        Docs[Documents] --> Chunker[Text Chunker]
+        Chunker --> Embedder[Embedding Model]
+    end
+
+    subgraph Store["Vector Storage"]
+        Embedder --> VectorDB[(Vector Database)]
+        VectorDB --> Index[HNSW Index]
+    end
+
+    subgraph Retrieve["Retrieval"]
+        Query[User Query] --> QueryEmbed[Query Embedding]
+        QueryEmbed --> Search[Similarity Search]
+        Search --> VectorDB
+        Search --> Reranker[Re-ranker]
+    end
+
+    subgraph Generate["Generation"]
+        Reranker --> PromptBuilder[Prompt Builder]
+        PromptBuilder --> LLM[LLM]
+        LLM --> Response[Response]
+        Response --> Guardrails[Output Guardrails]
+    end
+
+    Guardrails --> User[User]
+```
+
+**When to use:** Knowledge bases, document Q&A, internal search, support chatbots.
+
+### Template 2: ML Prediction Service
+
+```mermaid
+flowchart LR
+    subgraph Data["Data Pipeline"]
+        Sources[Data Sources] --> ETL[ETL/ELT]
+        ETL --> FeatureStore[(Feature Store)]
+    end
+
+    subgraph Train["Model Training"]
+        FeatureStore --> Training[Training Pipeline]
+        Training --> Registry[Model Registry]
+        Registry --> Validation[Model Validation]
+    end
+
+    subgraph Serve["Model Serving"]
+        Validation --> Deploy[Model Deployment]
+        Deploy --> API[Prediction API]
+        API --> Cache[(Prediction Cache)]
+    end
+
+    subgraph Monitor["Monitoring"]
+        API --> Metrics[Performance Metrics]
+        Metrics --> Drift[Drift Detection]
+        Drift --> Retrain[Retrain Trigger]
+        Retrain --> Training
+    end
+```
+
+**When to use:** Forecasting, churn prediction, pricing optimization, anomaly detection.
+
+### Template 3: Document Processing
+
+```mermaid
+flowchart LR
+    subgraph Intake["Document Intake"]
+        Upload[Upload / Email / API] --> Classify[Document Classifier]
+        Classify --> Queue[(Processing Queue)]
+    end
+
+    subgraph Extract["Extraction"]
+        Queue --> OCR[OCR Engine]
+        OCR --> NER[Named Entity Recognition]
+        NER --> Extract2[Field Extraction]
+        Extract2 --> Structured[Structured Data]
+    end
+
+    subgraph Validate["Validation"]
+        Structured --> Rules[Business Rules]
+        Rules --> Confidence[Confidence Scoring]
+        Confidence -->|High| Auto[Auto-Approve]
+        Confidence -->|Low| Review[Human Review Queue]
+    end
+
+    subgraph Output["Output"]
+        Auto --> DB[(Database)]
+        Review --> DB
+        DB --> Downstream[Downstream Systems]
+    end
+```
+
+**When to use:** Invoice processing, contract analysis, form digitization, claims processing.
+
+### Template 4: Chatbot / Agent
+
+```mermaid
+flowchart TB
+    User[User Input] --> Router[Intent Router]
+
+    Router -->|FAQ| Knowledge[Knowledge Base RAG]
+    Router -->|Action| Tools[Tool Executor]
+    Router -->|Complex| Agent[Multi-step Agent]
+
+    Knowledge --> LLM[LLM]
+    Tools --> LLM
+    Agent --> Planner[Task Planner]
+    Planner --> Tools
+    Planner --> Knowledge
+
+    LLM --> Safety[Safety Filter]
+    Safety --> Response[Response]
+    Response --> Feedback[User Feedback]
+    Feedback --> Memory[(Conversation Memory)]
+    Memory --> Router
+```
+
+**When to use:** Customer support, internal helpdesk, sales assistant, onboarding guide.
+
+### Template 5: Analytics Dashboard
+
+```mermaid
+flowchart LR
+    subgraph Sources["Data Sources"]
+        CRM[CRM]
+        ERP[ERP]
+        Web[Web Analytics]
+        Custom[Custom Data]
+    end
+
+    subgraph Pipeline["Data Pipeline"]
+        Sources --> ETL[ETL/CDC]
+        ETL --> Warehouse[(Data Warehouse)]
+    end
+
+    subgraph ML["ML Layer"]
+        Warehouse --> Features[Feature Engineering]
+        Features --> Models[ML Models]
+        Models --> Predictions[(Predictions Store)]
+    end
+
+    subgraph Viz["Visualization"]
+        Warehouse --> Dashboards[Dashboard Engine]
+        Predictions --> Dashboards
+        Dashboards --> NLQ[Natural Language Query]
+        Dashboards --> Alerts[Automated Alerts]
+    end
+```
+
+**When to use:** Executive dashboards, operational analytics, predictive reporting, KPI monitoring.
+
+## Quality Checklist
+
+Before finalizing output:
+- [ ] All Mermaid diagrams render correctly (no syntax errors)
+- [ ] Technology selections are justified with specific criteria
+- [ ] Cost estimates are realistic and sourced where possible
+- [ ] Implementation timeline is achievable given resource constraints
+- [ ] Risk mitigations are actionable, not generic
+- [ ] Security design addresses client's compliance requirements
+- [ ] Build vs Buy decisions account for client's team capabilities
+- [ ] Architecture handles expected scale (current + 3 year growth)