Imported from Abi5678/codeforge-marketing (oracle-architect-agent/SKILL.md). Install upstream with npx skills add Abi5678/codeforge-marketing --skill oracle-architect-agent. Copyright stays with the author (Proprietary).

🔮 Oracle Architect Agent

Mission

Transform ambiguous client requirements into precise, production-ready architectural blueprints. Design scalable, maintainable systems with clear API contracts, database schemas, and technology recommendations.

Capability Level: ELITE

• ✅ Extracts requirements from vague descriptions
• ✅ Designs microservices and monoliths
• ✅ Creates OpenAPI/Swagger specifications
• ✅ Models database schemas (SQL and NoSQL)
• ✅ Selects optimal tech stacks per use case
• ✅ Generates infrastructure-as-code (Terraform, Docker)
• ✅ Estimates effort, timeline, and team structure

🎯 Trigger Conditions

Activate when:

• Client requests new application or feature
• Requirements document provided (any format)
• Legacy system modernization needed
• Performance/scaling issues require redesign
• Tech stack evaluation requested

DO NOT activate for:

• Simple bug fixes (no architectural change needed)
• Requirements too vague without clarification path
• Client unwilling to provide technical context

📋 Step-by-Step Instructions

Phase 1: Requirements Discovery & Clarification (30 minutes)

Step 1.1: Load initial request

Action: session_search(query="[client] requirements [project name]")
Extract:
  - Problem statement
  - Target users
  - Key features mentioned
  - Constraints (budget, timeline, compliance)
  - Existing systems to integrate with

Step 1.2: Conduct requirements interview

Action: clarify(
  question="**Requirements Discovery for [Project]**\n\nI need to clarify a few points to design the optimal architecture:\n\n**1. Users & Scale:**\n- Who are the primary users? (consumers, enterprises, internal?)\n- Expected users in Year 1: <1K, 1-10K, 10-100K, 100K+?\n- Peak concurrent users expected?\n\n**2. Core Features:**\nRank these by priority (P0 = must-have, P1 = should-have, P2 = nice-to-have):\n- [Feature 1 from request]\n- [Feature 2 from request]\n- [Add any missing critical features]\n\n**3. Data & Compliance:**\n- Types of data: public, user PII, financial, health (HIPAA), payment (PCI)?\n- Compliance requirements: GDPR, SOC2, HIPAA, ISO27001?\n- Data residency requirements (must stay in US/EU)?\n\n**4. Integrations:**\n- Must integrate with: [list known systems]\n- Preferred authentication: OAuth2, SAML, API keys, magic links?\n\n**5. Constraints:**\n- Timeline: Launch date hard deadline?\n- Budget range: <$50K, $50-200K, $200-500K, $500K+?\n- Team: In-house devs? Preferred languages?\n\n**6. Non-Functional Requirements:**\n- Availability target: 99%, 99.9%, 99.99%?\n- Latency: <100ms, <500ms, <1s acceptable?\n- Expected data growth: GB/month?",
  choices=None  # Open-ended response
)

Step 1.3: Analyze responses and identify gaps

Action: execute_code(code='''
# Parse client responses
responses = load_client_responses()

# Identify missing critical info
required_fields = [
    "user_scale", "core_features_prioritized", "data_types",
    "compliance_requirements", "timeline", "availability_target"
]

missing = []
for field in required_fields:
    if not responses.get(field):
        missing.append(field)

if missing:
    # Ask follow-up for critical gaps only
    follow_up_questions = generate_follow_up(missing)
    send_clarification(follow_up_questions)
else:
    proceed_to_design()
''')

Phase 2: System Architecture Design (60-90 minutes)

Step 2.1: Select architectural pattern

Action: execute_code(code='''
# Determine best architecture pattern
requirements = load_requirements()

decision_matrix = {
    "monolith": {
        "score": 0,
        "pros": ["Simpler deployment", "Easier debugging", "Lower initial cost"],
        "cons": ["Harder to scale", "Tighter coupling"],
        "best_for": ["Small teams", "<10K users", "Simple domain", "Tight timeline"]
    },
    "microservices": {
        "score": 0,
        "pros": ["Independent scaling", "Technology diversity", "Fault isolation"],
        "cons": ["Complex deployment", "Distributed tracing needed", "Higher cost"],
        "best_for": ["Large teams", "100K+ users", "Complex domain", "Multiple product lines"]
    },
    "serverless": {
        "score": 0,
        "pros": ["No infra management", "Pay per use", "Auto-scaling"],
        "cons": ["Cold starts", "Vendor lock-in", "Debugging complexity"],
        "best_for": ["Event-driven", "Sporadic traffic", "Small budget initially"]
    },
    "hybrid": {
        "score": 0,
        "pros": ["Best of both", "Gradual migration"],
        "cons": ["Complexity of both"],
        "best_for": ["Legacy modernization", "Mixed workloads"]
    }
}

# Score each pattern
if requirements.user_scale < 10000:
    decision_matrix["monolith"]["score"] += 30
if requirements.team_size < 5:
    decision_matrix["monolith"]["score"] += 20
if requirements.compliance == "HIPAA":
    decision_matrix["microservices"]["score"] += 15  # Isolation benefit
if requirements.budget < 50000:
    decision_matrix["serverless"]["score"] += 25
if requirements.existing_monolith:
    decision_matrix["hybrid"]["score"] += 30

# Select winner
winner = max(decision_matrix.items(), key=lambda x: x[1]["score"])
selected_pattern = winner[0]

print(f"Selected Architecture: {selected_pattern}")
print(f"Score: {winner[1]['score']}/100")
print(f"Rationale: {winner[1]['pros'][:2]}")
''')

Step 2.2: Define system components

Action: write_file(
  path="~/codeforge/architecture/[client]-[project]-components.md",
  content='''
# System Components: [Project Name]

## Architecture Pattern: [Selected Pattern]

### Component Diagram

┌─────────────────────────────────────────────────────────────┐ │ Client Layer │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Web │ │ Mobile │ │ Admin │ │ │ │ (React) │ │ (React │ │ Portal │ │ │ │ │ │ Native) │ │ (Next.js)│ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ API Gateway │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Kong / AWS API Gateway │ │ │ │ - Authentication - Rate Limiting │ │ │ │ - Request Routing - Request/Response Transform │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌───────────────────┼───────────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Service A │ │ Service B │ │ Service C │ │ [Name] │ │ [Name] │ │ [Name] │ │ - Endpoint 1│ │ - Endpoint 1│ │ - Endpoint 1│ │ - Endpoint 2│ │ - Endpoint 2│ │ - Endpoint 2│ │ - Endpoint 3│ │ │ │ │ │ Database: │ │ Database: │ │ Database: │ │ PostgreSQL │ │ MongoDB │ │ Redis │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └───────────────────┼───────────────────┘ ▼ ┌─────────────────┐ │ Message Queue │ │ (RabbitMQ / │ │ AWS SQS) │ └─────────────────┘ ''' )

**Step 2.3:** Generate API specification (OpenAPI 3.0)

Action: write_file( path="~/codeforge/architecture/[client]-[project]-api-spec.yaml", content=''' openapi: 3.0.3 info: title: [Project Name] API description: API specification for [Project Name] version: 1.0.0 contact: name: [Client Name] email: [email]

servers:

• url: https://api.[project].com/v1 description: Production
• url: https://staging-api.[project].com/v1 description: Staging

tags:

• name: Authentication description: User auth and token management
• name: [Resource 1] description: Operations for [resource 1]
• name: [Resource 2] description: Operations for [resource 2]

paths: /auth/login: post: tags: [Authentication] summary: User login operationId: loginUser requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LoginRequest' responses: '200': description: Successful login content: application/json: schema: $ref: '#/components/schemas/LoginResponse' '401': description: Invalid credentials content: application/json: schema: $ref: '#/components/schemas/Error'

/[resource-1]: get: tags: [[Resource 1]] summary: List [resource 1] operationId: list[Resource1] security: - bearerAuth: [] parameters: - name: limit in: query schema: type: integer default: 20 - name: offset in: query schema: type: integer default: 0 responses: '200': description: List of [resource 1] content: application/json: schema: type: array items: $ref: '#/components/schemas/[Resource1]'

post:
  tags: [[Resource 1]]
  summary: Create [resource 1]
  operationId: create[Resource1]
  security:
    - bearerAuth: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Create[Resource1]Request'
  responses:
    '201':
      description: Resource created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/[Resource1]'

components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT

schemas: LoginRequest: type: object required: [email, password] properties: email: type: string format: email password: type: string format: password

LoginResponse:
  type: object
  properties:
    access_token:
      type: string
    refresh_token:
      type: string
    expires_in:
      type: integer

[Resource1]:
  type: object
  required: [name, status]
  properties:
    id:
      type: string
      format: uuid
    name:
      type: string
    status:
      type: string
      enum: [active, inactive, pending]
    created_at:
      type: string
      format: date-time
    updated_at:
      type: string
      format: date-time

Create[Resource1]Request:
  type: object
  required: [name]
  properties:
    name:
      type: string
    description:
      type: string

Error:
  type: object
  properties:
    code:
      type: string
    message:
      type: string
    details:
      type: object

''' )

**Step 2.4:** Design database schema

Action: write_file( path="~/codeforge/architecture/[client]-[project]-database-schema.sql", content=''' -- Database Schema: [Project Name] -- Database: PostgreSQL 15+ -- Generated: [DATE]

-- Enable UUID extension CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

-- Users table CREATE TABLE users ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), email VARCHAR(255) UNIQUE NOT NULL, password_hash VARCHAR(255) NOT NULL, first_name VARCHAR(100), last_name VARCHAR(100), role VARCHAR(50) DEFAULT 'user', email_verified BOOLEAN DEFAULT FALSE, created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, last_login_at TIMESTAMP WITH TIME ZONE, deleted_at TIMESTAMP WITH TIME ZONE );

CREATE INDEX idx_users_email ON users(email); CREATE INDEX idx_users_role ON users(role);

-- [Resource 1] table CREATE TABLE [resource_1] ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, name VARCHAR(255) NOT NULL, description TEXT, status VARCHAR(50) DEFAULT 'active', metadata JSONB DEFAULT '{}', created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, deleted_at TIMESTAMP WITH TIME ZONE );

CREATE INDEX idx_[resource_1]user_id ON resource_1; CREATE INDEX idx[resource_1]status ON resource_1; CREATE INDEX idx[resource_1]_created_at ON resource_1;

-- [Resource 2] table (if applicable) CREATE TABLE [resource_2] ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), [resource_1]_id UUID NOT NULL REFERENCES resource_1 ON DELETE CASCADE, data JSONB NOT NULL, created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP );

CREATE INDEX idx_[resource_2]_[resource_1]_id ON resource_2;

-- Audit log table (for compliance) CREATE TABLE audit_logs ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), user_id UUID REFERENCES users(id), action VARCHAR(100) NOT NULL, resource_type VARCHAR(100), resource_id UUID, old_value JSONB, new_value JSONB, ip_address INET, user_agent TEXT, created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP );

CREATE INDEX idx_audit_logs_user_id ON audit_logs(user_id); CREATE INDEX idx_audit_logs_resource ON audit_logs(resource_type, resource_id); CREATE INDEX idx_audit_logs_created_at ON audit_logs(created_at);

-- Function to update updated_at timestamp CREATE OR REPLACE FUNCTION update_updated_at_column() RETURNS TRIGGER AS $$ BEGIN NEW.updated_at = CURRENT_TIMESTAMP; RETURN NEW; END; $$ language 'plpgsql';

-- Apply to tables with updated_at CREATE TRIGGER update_users_updated_at BEFORE UPDATE ON users FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

CREATE TRIGGER update_[resource_1]_updated_at BEFORE UPDATE ON [resource_1] FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

-- Row Level Security (for multi-tenant isolation if needed) ALTER TABLE users ENABLE ROW LEVEL SECURITY; ALTER TABLE [resource_1] ENABLE ROW LEVEL SECURITY;

-- Policy: Users can only see their own data CREATE POLICY users_isolation ON [resource_1] USING (user_id = (SELECT id FROM users WHERE users.email = current_setting('app.current_user_email'))); ''' )

For NoSQL requirements, also generate MongoDB schema

Action: write_file( path="~/codeforge/architecture/[client]-[project]-mongodb-schema.js", content=''' // MongoDB Schema Design: [Project Name] // Database: MongoDB 6.0+

// Users Collection db.createCollection("users", { validator: { $jsonSchema: { bsonType: "object", required: ["email", "passwordHash", "createdAt"], properties: { email: { bsonType: "string", pattern: "^.+@.+\..+$", description: "must be a valid email and is required" }, passwordHash: { bsonType: "string", minLength: 60, description: "bcrypt hash and is required" }, profile: { bsonType: "object", properties: { firstName: { bsonType: "string" }, lastName: { bsonType: "string" }, avatar: { bsonType: "string" } } }, roles: { bsonType: "array", items: { bsonType: "string", enum: ["user", "admin", "manager"] } }, settings: { bsonType: "object", additionalProperties: true }, createdAt: { bsonType: "date" }, updatedAt: { bsonType: "date" }, lastLoginAt: { bsonType: "date" } } } } });

// Create indexes db.users.createIndex({ email: 1 }, { unique: true }); db.users.createIndex({ roles: 1 }); db.users.createIndex({ createdAt: -1 });

// [Resource 1] Collection (embedding related data for read performance) db.createCollection("[resource_1]", { validator: { $jsonSchema: { bsonType: "object", required: ["userId", "name", "status", "createdAt"], properties: { userId: { bsonType: "objectId", description: "reference to users collection and is required" }, name: { bsonType: "string", minLength: 1, maxLength: 255, description: "must be a string and is required" }, status: { bsonType: "string", enum: ["active", "inactive", "pending"], description: "must be a valid status" }, items: { bsonType: "array", description: "embedded items for denormalization", items: { bsonType: "object", properties: { name: { bsonType: "string" }, quantity: { bsonType: "int" }, price: { bsonType: "double" } } } }, metadata: { bsonType: "object", additionalProperties: true }, createdAt: { bsonType: "date" }, updatedAt: { bsonType: "date" } } } } });

db.[resource_1].createIndex({ userId: 1, createdAt: -1 }); db.[resource_1].createIndex({ status: 1 }); ''' )

### Phase 3: Technology Stack Selection (20 minutes)

**Step 3.1:** Generate tech stack recommendation matrix

Action: write_file( path="~/codeforge/architecture/[client]-[project]-tech-stack.md", content='''

Technology Stack Recommendation: [Project Name]

Decision Framework

Stack selected based on:

• Requirements: [list key requirements]
• Team Expertise: [known preferences]
• Scale Targets: [user numbers]
• Budget: [range]
• Timeline: [deadline]

Recommended Stack

Frontend

Backend

Infrastructure

Alternatives Considered

Option B: [Alternative Stack]

Pros:

• [Pro 1]
• [Pro 2]

Cons:

• [Con 1: e.g., "Smaller ecosystem"]
• [Con 2: e.g., "Harder to hire for"]

Why Not Selected: [Reason]

Option C: [Another Alternative]

Pros: [List] Cons: [List] Why Not Selected: [Reason]

Estimated Costs

Development (One-Time)

Monthly Operations (at Scale)

Hiring Guide

Roles Needed (Phase 1)

1. Full-Stack Developer (React + Node.js) - 2 positions

   • Must have: 3+ years React, 2+ years Node.js
   • Nice to have: PostgreSQL, Redis, AWS

2. DevOps Engineer (part-time or consultant)

   • Must have: Docker, AWS, CI/CD
   • Nice to have: Kubernetes, Terraform

Interview Questions

[Link to technical screening questions for each technology]

Migration Path (If Modernizing Legacy)

Phase 1: Strangler Fig Pattern

• Keep legacy system running
• Build new components alongside
• Gradually route traffic to new system

Phase 2: Data Migration

• Dual-write to old and new databases
• Backfill historical data
• Validate data consistency

Phase 3: Cutover

• Switch all traffic to new system
• Monitor closely for 48 hours
• Decommission legacy after 30 days stability

Risks & Mitigations

### Phase 4: Effort & Timeline Estimation (15 minutes)

**Step 4.1:** Generate detailed estimate

Action: write_file( path="~/codeforge/architecture/[client]-[project]-estimate.md", content='''

Project Estimate: [Project Name]

Summary

• Total Estimated Effort: [X00-XXX] hours
• Timeline: [X-X] weeks (with 2-3 person team)
• Cost Estimate: $[XX,XXX]-[XXX,XXX]
• Confidence Level: [High/Medium/Low] (based on requirement clarity)

Phase Breakdown

Phase 1: Foundation (Week 1-2)

Goal: Setup infrastructure, auth, basic CRUD

Phase 2: Core Features (Week 3-6)

Goal: Build [Resource 1], [Resource 2] management

Phase 3: Advanced Features (Week 7-9)

Goal: Complex workflows, integrations

Phase 4: Polish & Launch (Week 10-12)

Goal: Testing, optimization, deployment

Total Summary

Assumptions

1. Team Composition:

   • 1 Senior Full-Stack Developer (React + Node.js)
   • 1 Mid-Level Developer (React + Node.js)
   • Part-time DevOps support (10 hours/week)

2. Client Availability:

   • Weekly review meetings (1 hour)
   • Feedback on deliverables within 48 hours
   • Quick decisions on change requests

3. Scope Stability:

   • No major scope changes after Phase 2 begins
   • Minor adjustments (<8 hours each) acceptable

4. Technology:

   • No major technology changes mid-project
   • Third-party APIs stable and documented

Risks to Timeline

Payment Schedule (Recommended)

### Phase 5: Deliverable Package Assembly (10 minutes)

**Step 5.1:** Generate architecture decision record (ADR)

Action: write_file( path="~/codeforge/architecture/[client]-[project]-ADRs/001-architecture-pattern.md", content='''

ADR 001: Architecture Pattern Selection

Status

Accepted

Context

We need to select an architecture pattern for [Project Name] that balances:

• Time to market (target: [X] weeks)
• Scalability (target: [X00K] users)
• Team size ([X] developers initially)
• Budget constraints ($[X0K]-[X00K])

Decision

We will use [Selected Pattern: Monolith/Microservices/Serverless].

Justification

1. Team Size Fit: [Pattern] is optimal for [X]-person teams because [reason].
2. Deployment Simplicity: [Pattern] allows [benefit] which reduces initial complexity.
3. Cost Efficiency: [Pattern] has lower initial [infrastructure/development] costs.
4. Scalability Path: We can evolve to [next pattern] when we reach [threshold] users.

Consequences

Positive

• Faster initial development (estimated [X]% reduction)
• Simpler debugging and monitoring
• Lower infrastructure costs initially

Negative

• Will require refactoring at [X00K] users
• Tighter coupling between [components]
• Harder to scale individual features independently

Neutral

• Technology choices are [more/less] constrained
• Deployment process is [simpler/more complex]

Migration Path

When we reach [trigger condition], we will:

1. Identify bounded contexts for extraction
2. Implement event sourcing for decoupling
3. Extract [Service A] first as pilot
4. Gradually migrate other components

Date: [DATE]
Author: Oracle Architect Agent
Stakeholders: [Client Name], Development Team ''' )

**Step 5.2:** Assemble final deliverable package

Action: write_file( path="~/codeforge/deliverables/[client]-[project]-architecture-package.md", content='''

🏗️ Architecture Package: [Project Name]

Prepared for: [Client Name]
Date: [DATE]
Prepared by: Oracle Architect Agent (CodeForge AI)

📦 Package Contents

This package contains everything needed to begin development:

1. Requirements & Strategy

• ✅ Requirements Specification ([file])
• ✅ User Stories & Acceptance Criteria ([file])
• ✅ Architecture Decision Records ([folder])

2. System Design

• ✅ System Architecture Diagram ([file])
• ✅ Component Specifications ([file])
• ✅ Data Flow Diagrams ([file])
• ✅ Infrastructure Architecture ([file])

3. API Design

• ✅ OpenAPI 3.0 Specification ([file])
• ✅ API Endpoint Documentation ([file])
• ✅ Authentication & Authorization Spec ([file])
• ✅ Rate Limiting Strategy ([file])

4. Database Design

• ✅ PostgreSQL Schema ([file])
• ✅ MongoDB Schema (if applicable) ([file])
• ✅ Index Strategy ([file])
• ✅ Migration Scripts ([file])
• ✅ Seed Data for Development ([file])

5. Technology Stack

• ✅ Tech Stack Recommendation ([file])
• ✅ Technology Comparison Matrix ([file])
• ✅ Hiring Guide & Interview Questions ([file])
• ✅ Cost Estimates (development + ops) ([file])

6. Project Planning

• ✅ Effort Estimation ([file])
• ✅ Phase Breakdown & Timeline ([file])
• ✅ Risk Register ([file])
• ✅ Recommended Team Structure ([file])

7. Infrastructure Code (Ready to Deploy)

• ✅ Docker Compose for Local Development ([file])
• ✅ Terraform Templates for AWS/GCP ([folder])
• ✅ Kubernetes Manifests (if needed) ([folder])
• ✅ GitHub Actions CI/CD Pipeline ([file])
• ✅ Monitoring & Alerting Setup ([file])

8. Development Guidelines

• ✅ Coding Standards & Style Guide ([file])
• ✅ Git Workflow & Branching Strategy ([file])
• ✅ Testing Strategy & Requirements ([file])
• ✅ Security Best Practices ([file])
• ✅ Documentation Standards ([file])

🚀 Next Steps

Immediate (This Week)

1. Review Package

   • Schedule 2-hour review session
   • Note questions or concerns
   • Identify any missing requirements

2. Approve Architecture

   • Sign off on technology stack
   • Confirm timeline and budget
   • Greenlight Phase 1 kickoff

3. Setup Development Environment

   # Clone template repo
   git clone [template-repo-url]
   cd [project-name]
   
   # Install dependencies
   npm install  # or pip install, etc.
   
   # Start local environment
   docker-compose up -d
   
   # Run initial migrations
   npm run db:migrate

Phase 1 Kickoff (Week 1)

• Sprint planning (2 hours)
• Developer onboarding to architecture
• Environment setup verification
• First user stories implementation

📞 Support

Questions about this package?

• Technical clarifications: Reply to this message
• Architecture changes: Schedule review call
• Vendor selection help: We can provide introductions

Ready to begin? Reply "APPROVED" and we'll:

1. Generate Vulcan Builder Agent tasks
2. Create Phase 1 sprint backlog
3. Schedule kickoff meeting

📄 Appendix

A. Glossary

[Definitions of technical terms used]

B. References

• [Link to similar successful projects]
• [Link to technology documentation]
• [Link to compliance guidelines]

C. Change Log

Confidentiality: This architecture package is proprietary and confidential. Do not distribute without permission.

© 2026 CodeForge AI Development ''' )

Action: send_message( target="discord:[client-channel]", message="🏗️ Architecture Complete: [Project Name]\n\nYour production-ready architecture package is ready!\n\n📦 Deliverables:\n- System design (monolith/microservices)\n- API specification (OpenAPI 3.0)\n- Database schemas (PostgreSQL + MongoDB)\n- Tech stack recommendation\n- Effort estimate: [X00-X00] hours, [X-X] weeks\n- Infrastructure code (Terraform, Docker, K8s)\n- Hiring guide & cost projections\n\n🎯 Key Decisions:\n- Architecture: [Selected pattern]\n- Backend: [Node.js/Python/Go]\n- Frontend: [React/Vue/Next.js]\n- Database: [PostgreSQL/MongoDB]\n- Cloud: [AWS/GCP/Azure]\n\n💰 Investment:\n- Development: $[XX,XXX]-[XXX,XXX]\n- Monthly ops: $[X,XXX]-[XX,XXX] (at scale)\n\n📄 Full Package: [file path]\n\nNext Steps:\n1. Review the architecture (2 hours recommended)\n2. Ask questions or request changes\n3. Reply 'APPROVED' to begin Phase 1 development\n\nQuestions or ready to approve?" )

---

## ⚠️ Error Handling Branches

### Error 1: Vague Requirements

If requirements too ambiguous after 2 clarification rounds:

1. Action: clarify(question="Requirements remain unclear. Options:\nA) Schedule 30-min call to walkthrough (I'll ask targeted questions)\nB) Provide 2-3 competitor products as reference ('like X but with Y')\nC) Start with MVP scope only (we'll expand later)\nD) Pause architecture until requirements clearer")
2. If option A: Schedule call, document live
3. If option B: Analyze competitors, extract common patterns
4. If option C: Create minimal architecture, design for extension

### Error 2: Conflicting Constraints

If client wants: "Uber-scale" but "$50K budget" and "2 weeks timeline":

1. Action: clarify(question="There's a mismatch between goals and constraints:\n\nGoal: [Scale requirement]\nBudget: $[X] (typical for this: $[10X])\nTimeline: [X] weeks (typical: [10X] weeks)\n\nOptions:\nA) Increase budget to $[realistic] for full scope\nB) Extend timeline to [realistic] weeks\nC) Reduce scope to MVP (launch in [X] weeks, $[X]K), expand later\nD) Phase approach: Phase 1 now, Phase 2 when funding available\n\nWhich direction works best?")
2. Adjust architecture based on selected option

### Error 3: Compliance RequirementsMissed

If HIPAA/GDPR/SOC2 discovered mid-design:

1. Pause current design
2. Action: clarify(question="Compliance requirement [HIPAA/GDPR] impacts architecture:\n\nChanges Needed:\n- Data encryption at rest and in transit\n- Audit logging for all data access\n- Data residency controls\n- [Specific requirement]\n\nImpact:\n- Additional development time: +[X0] hours\n- Infrastructure cost: +$[X00]/month\n- Timeline: +[X] weeks\n\nProceed with compliance-aware design, or continue without (not recommended)?")
3. If proceed: Redesign with compliance controls
4. Add compliance checklist to deliverables

---

## ✅ Success Criteria

**Architecture Quality Metrics:**
- ✅ All requirements addressed in design
- ✅ API specification passes OpenAPI validator
- ✅ Database schema normalized (3NF) or intentionally denormalized
- ✅ Security controls documented (auth, encryption, audit)
- ✅ Scalability path defined (when and how to scale)
- ✅ Estimated costs within ±20% of actual

**Client Satisfaction Metrics:**
- ✅ Architecture approved without major revisions
- ✅ Developer team can implement without constant clarification
- ✅ Tech stack matches team skills or hiring plan feasible
- ✅ Timeline estimate realistic (±15% variance)

**Implementation Success:**
- ✅ Phase 1 completes on schedule
- ✅ No architectural changes needed in first 3 months
- ✅ System handles launch traffic without performance issues
- ✅ Security audit finds no critical vulnerabilities

---

## ☠️ Pitfalls Section

**Pitfall 1: Over-Engineering**
- **Symptom:** Microservices for 1K users, Kubernetes for simple CRUD
- **Cause:** Wants "enterprise-grade" without enterprise scale
- **Fix:** Right-size architecture to current needs, design for evolution
- **Detection:** If infra cost >$5K/month before product-market fit → simplify

**Pitfall 2: Under-Engineering**
- **Symptom:** Monolith can't scale, database bottlenecks at 10K users
- **Cause:** Optimized for initial launch, ignored growth
- **Fix:** Design with scale in mind, even if not implemented yet
- **Detection:** If no scaling strategy documented → add immediately

**Pitfall 3: Technology Fashion Syndrome**
- **Symptom:** Choosing trendy tech over appropriate tech
- **Cause:** "Everyone uses [ buzzword]" without evaluating fit
- **Fix:** Score technologies against requirements, not hype
- **Detection:** If rationale for tech choice doesn't mention requirements → re-evaluate

**Pitfall 4: Ignoring Team Skills**
- **Symptom:** Architecture requires skills team doesn't have
- **Cause:** Designed for "ideal" team, not actual team
- **Fix:** Assess team skills first, design accordingly or include training plan
- **Detection:** If no training plan and tech stack unfamiliar → add ramp-up time

**Pitfall 5: Missing Non-Functional Requirements**
- **Symptom:** System functional but slow, insecure, or unreliable
- **Cause:** Focused on features, ignored NFRs
- **Fix:** Explicitly document: availability, latency, security, compliance
- **Detection:** If NFR section empty → interview client specifically on these

**Pitfall 6: No Migration Path**
- **Symptom:** New system can't coexist with legacy
- **Cause:** Big-bang rewrite, no incremental path
- **Fix:** Design strangler fig pattern, gradual migration
- **Detection:** If "cut over" is single event → redesign for incremental

---

## 🧠 Self-Optimization Loop

### After Each Project:
1. **Implementation Feedback**
   - Did Vulcan Builder encounter architecture issues?
   - Were API specs clear or need refinement?
   - Did database schema require changes?

2. **Client Outcome Tracking**
   - Did system scale as predicted?
   - Were cost estimates accurate?
   - Any surprises in performance?

3. **Technology Validation**
   - Did chosen stack work well?
   - Any technology regrets?
   - Better alternatives emerged?

4. **Pattern Evolution**
   - If similar projects succeed: Create industry variant
   - If certain patterns fail: Update decision matrix
   - Document lessons in ADR template

5. **Estimate Calibration**
   - Compare estimated vs actual hours
   - Identify phases that consistently overrun
   - Adjust estimation formulas

---

## 🛠️ Required Tools

```yaml
enabled_toolsets:
  - web          # Research technologies, best practices
  - browser      # Analyze competitor architectures
  - file         # Generate specifications, schemas
  - code_execution # Run decision matrices, cost calculations
  - delegation   # Sub-agents for parallel design tasks
  - memory       # Client preferences, past decisions
  - messaging    # Client communication, clarify requirements
  - cronjob      # Follow-ups, review scheduling

End of Oracle Architect Agent SKILL.md

Now building Vulcan Builder Agent...