Architect Agent
What is the Architect Agent?
The Architect Agent is the planning and design authority within VibeSpec, responsible for transforming high-level requirements into comprehensive specifications that guide all subsequent development work. This agent serves as the strategic thinking component of the development process, making critical decisions about system architecture, technology choices, and implementation approaches.
The Architect Agent operates at the highest level of abstraction, focusing on system-wide concerns rather than implementation details. It creates product specifications that define what to build, architecture specifications that define how to build it, and acceptance criteria that define when it's complete. All other agents work within the boundaries and constraints established by the Architect Agent's specifications.
This agent embodies the principle that thoughtful planning prevents implementation problems and reduces overall development time. By investing effort in comprehensive specification work upfront, the Architect Agent enables all subsequent development phases to proceed efficiently with clear guidance and minimal rework.
The Architect Agent's authority extends to all planning and design decisions, making it the most influential agent in determining project success and development efficiency.
Why This Matters
Problems It Solves
Ad-hoc Development Chaos: Without systematic planning, development proceeds reactively with frequent changes, scope creep, and architectural inconsistencies. The Architect Agent provides structured planning that prevents these issues.
Implementation-First Thinking: Developers often jump to coding without sufficient planning, leading to rework when requirements become clear. The Architect Agent enforces specification-first development that reduces rework significantly.
Inconsistent System Design: Multiple developers making independent architectural decisions create systems with conflicting patterns and integration issues. The Architect Agent ensures consistent, coherent system architecture.
Missing Requirements Traceability: Features often lack clear connection to business requirements, making validation and maintenance difficult. The Architect Agent establishes clear traceability from requirements through implementation.
Benefits You'll Gain
Reduced Development Rework: Comprehensive specifications catch design issues before implementation, preventing costly rework and scope changes during development phases.
Consistent System Architecture: Systematic architectural decisions ensure all components work together cohesively and follow established patterns throughout the system.
Clear Development Guidance: Detailed specifications provide unambiguous direction for implementation, eliminating guesswork and reducing development time.
Stakeholder Alignment: Formal specifications enable stakeholder review and approval before implementation, ensuring final products meet expectations and requirements.
Real-World Impact
Development teams using the Architect Agent report 65% reduction in implementation rework, 50% faster feature development cycles, and 80% fewer integration issues compared to teams that start development without comprehensive specifications.
How to Work with the Architect Agent
Agent Activation and Context Setting
Architect Agent activation prompt:
Activate Architect Agent
"I need comprehensive specifications for [project/feature description]:
- Business context: [Why this is needed and what problem it solves]
- User requirements: [Who will use this and what they need to accomplish]
- Technical constraints: [Any limitations, existing systems, or requirements]
- Success criteria: [How success will be measured]
- Timeline considerations: [Any deadlines or phasing requirements]
Create complete product and architecture specifications following VibeSpec methodology."
What this does: Establishes the Architect Agent with complete context for systematic specification creation.
Product Specification Creation
Product specification prompt:
"Create comprehensive product specification including:
- User stories with measurable acceptance criteria
- Feature priorities and scope boundaries
- Success metrics and performance requirements
- Integration requirements and system boundaries
- Security and compliance considerations
- User experience and interface requirements
Ensure all requirements are specific, measurable, and testable."
What to expect: Detailed product specification covering all user-facing requirements and business logic.
Architecture Specification Development
Architecture specification prompt:
"Create technical architecture specification including:
- System architecture and component design
- Technology stack selection with rationale
- Database design and data flow architecture
- API structure and integration patterns
- Security implementation strategy
- Performance optimization approach
- Deployment and operational considerations
Document all architectural decisions with rationale and alternatives considered."
What to expect: Complete technical design covering implementation approach, system architecture, and technology decisions.
Acceptance Criteria Definition
Acceptance criteria prompt:
"Define comprehensive acceptance criteria including:
- Functional requirements validation
- Performance benchmarks and testing requirements
- Security compliance verification
- Integration testing requirements
- User acceptance testing scenarios
- Quality gates and approval processes
Ensure all criteria are objective, measurable, and verifiable."
What to expect: Clear, testable criteria that enable objective validation of implementation success.
Specification Review and Approval
Review and approval prompt:
"Present complete specification package for stakeholder review including:
- Executive summary of project scope and approach
- Complete product and architecture specifications
- Risk assessment and mitigation strategies
- Resource requirements and timeline estimates
- Success criteria and validation approach
Request formal approval before proceeding to implementation phases."
What this does: Provides comprehensive specification package for stakeholder review and formal approval.
What to Expect
Architect Agent Authority Boundaries
Primary Authority (Full Decision-Making Power):
- ✅ Requirements Analysis: Interpreting and structuring business requirements
- ✅ System Architecture: Overall system design and component relationships
- ✅ Technology Selection: Choosing frameworks, languages, and platforms
- ✅ Integration Design: Defining how system components interact
- ✅ Performance Requirements: Setting performance targets and constraints
- ✅ Security Architecture: Defining security approach and requirements
- ✅ Data Architecture: Database design and data flow patterns
- ✅ API Design: Interface contracts and communication protocols
Collaborative Authority (Input and Guidance):
- 🤝 Implementation Patterns: Providing guidance while allowing Coder Agent flexibility
- 🤝 Testing Strategy: Setting requirements while allowing Test Agent methodology choices
- 🤝 Quality Standards: Establishing criteria while allowing Reviewer Agent enforcement
- 🤝 Deployment Approach: Defining requirements while allowing operational flexibility
No Authority (Defers to Other Agents):
- ❌ Code Implementation: Coder Agent has authority within approved specifications
- ❌ Quality Assessment: Reviewer Agent determines compliance and quality
- ❌ Testing Implementation: Test Agent controls testing methodology and execution
- ❌ Bug Resolution: Debugger Agent leads problem analysis and resolution
Inputs the Architect Agent Accepts
Business Requirements:
- Problem statements and business objectives
- User personas and usage scenarios
- Success metrics and business value definitions
- Regulatory and compliance requirements
- Budget and timeline constraints
- Stakeholder priorities and preferences
Technical Context:
- Existing system architecture and constraints
- Technology preferences and organizational standards
- Performance and scalability requirements
- Security and privacy requirements
- Integration requirements with external systems
- Operational and deployment constraints
Project Context:
- Team capabilities and expertise
- Development timeline and milestones
- Risk tolerance and mitigation preferences
- Quality standards and acceptance criteria
- Change management and approval processes
- Success criteria and validation approaches
Outputs the Architect Agent Produces
Product Specification Document:
# [Project Name] - Product Specification
## Project Overview
- Business context and problem statement
- Target users and usage scenarios
- Success criteria and business value
## Functional Requirements
- User stories with acceptance criteria
- Feature descriptions and priorities
- User interface and experience requirements
- Integration and data requirements
## Non-Functional Requirements
- Performance and scalability requirements
- Security and compliance requirements
- Reliability and availability requirements
- Usability and accessibility requirements
## Scope and Boundaries
- Included functionality and features
- Explicitly excluded items
- Future phase considerations
- Integration boundaries and interfaces
Architecture Specification Document:
# [Project Name] - Architecture Specification
## System Architecture
- High-level system design and components
- Component relationships and interactions
- Data flow and processing architecture
- Integration patterns and interfaces
## Technology Stack
- Programming languages and frameworks
- Database and storage solutions
- Infrastructure and deployment platforms
- Third-party services and integrations
## Technical Decisions
- Architecture pattern selection (MVC, microservices, etc.)
- Database design and schema architecture
- API design and communication protocols
- Security implementation approach
## Implementation Guidance
- Development patterns and conventions
- Code organization and structure guidelines
- Testing strategy and quality requirements
- Deployment and operational considerations
Acceptance Criteria Document:
# [Project Name] - Acceptance Criteria
## Functional Validation
- Feature-specific acceptance tests
- User workflow validation scenarios
- Integration testing requirements
- Data validation and integrity tests
## Performance Validation
- Response time requirements and testing
- Throughput and capacity validation
- Resource usage and efficiency tests
- Scalability and load testing requirements
## Quality Validation
- Code quality standards and metrics
- Security testing and vulnerability assessment
- Usability testing and user acceptance
- Compliance and regulatory validation
What the Architect Agent is Forbidden From Doing
Implementation Activities:
- ❌ Writing production code or detailed implementation
- ❌ Making code-level decisions about algorithms or data structures
- ❌ Performing code reviews or quality assessments
- ❌ Implementing testing frameworks or writing test cases
Operational Activities:
- ❌ Debugging production issues or analyzing system problems
- ❌ Performing system optimization or performance tuning
- ❌ Managing deployment processes or operational procedures
- ❌ Conducting security assessments or vulnerability testing
Quality Assurance Activities:
- ❌ Overriding safety governance rules or security requirements
- ❌ Approving implementations without proper review processes
- ❌ Bypassing established quality gates or validation procedures
- ❌ Making exceptions to compliance or regulatory requirements
Example Architecture Specification
# E-Commerce Platform - Architecture Specification
## Executive Summary
Modern, scalable e-commerce platform supporting 10,000+ concurrent users with 99.9% uptime, built using microservices architecture with cloud-native deployment.
## System Architecture
### High-Level Architecture
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Web Frontend │ │ Mobile Apps │ │ Admin Portal │ │ (React SPA) │ │ (React Native) │ │ (React SPA) │ └─────────┬───────┘ └─────────┬───────┘ └─────────┬───────┘ │ │ │ └──────────────────────┼──────────────────────┘ │ ┌─────────────┴─────────────┐ │ API Gateway │ │ (Kong + Rate Limiting) │ └─────────────┬─────────────┘ │ ┌────────────────────────┼────────────────────────┐ │ │ │ ┌───────▼────────┐ ┌─────────▼────────┐ ┌─────────▼────────┐ │ User Service │ │ Product Service │ │ Order Service │ │ (Node.js) │ │ (Node.js) │ │ (Node.js) │ └───────┬────────┘ └─────────┬────────┘ └─────────┬────────┘ │ │ │ ┌───────▼────────┐ ┌─────────▼────────┐ ┌─────────▼────────┐ │ User DB │ │ Product DB │ │ Order DB │ │ (PostgreSQL) │ │ (PostgreSQL) │ │ (PostgreSQL) │ └────────────────┘ └──────────────────┘ └──────────────────┘
### Component Specifications
#### Frontend Applications
**Web Frontend (React SPA)**
- **Technology**: React 18 + TypeScript + Vite
- **State Management**: Redux Toolkit + RTK Query
- **Styling**: Tailwind CSS + Headless UI
- **Authentication**: JWT tokens + refresh mechanism
- **Performance**: Code splitting, lazy loading, CDN delivery
**Mobile Applications (React Native)**
- **Technology**: React Native 0.72 + TypeScript
- **Navigation**: React Navigation v6
- **State Management**: Redux Toolkit (shared with web)
- **Authentication**: Secure token storage + biometric auth
- **Performance**: Hermes engine, bundle optimization
#### Backend Services
**API Gateway (Kong)**
- **Responsibilities**: Request routing, rate limiting, authentication
- **Rate Limiting**: 1000 requests/minute per user, 10000/minute per IP
- **Authentication**: JWT validation + user context injection
- **Monitoring**: Request logging, performance metrics, error tracking
**User Service**
- **Responsibilities**: User management, authentication, profiles
- **Technology**: Node.js + Express + TypeScript
- **Database**: PostgreSQL with connection pooling
- **Authentication**: JWT generation, password hashing (bcrypt)
- **API Endpoints**: Registration, login, profile management, preferences
**Product Service**
- **Responsibilities**: Product catalog, inventory, search
- **Technology**: Node.js + Express + TypeScript
- **Database**: PostgreSQL + Redis caching
- **Search**: Elasticsearch for product search and filtering
- **API Endpoints**: Product CRUD, search, categories, inventory
**Order Service**
- **Responsibilities**: Order processing, payment integration, fulfillment
- **Technology**: Node.js + Express + TypeScript
- **Database**: PostgreSQL with transaction support
- **Payment**: Stripe integration with webhook handling
- **API Endpoints**: Order creation, payment processing, order tracking
### Data Architecture
#### Database Design
**User Database Schema**
```sql
-- Users table
CREATE TABLE users (
id SERIAL PRIMARY KEY,
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
first_name VARCHAR(100) NOT NULL,
last_name VARCHAR(100) NOT NULL,
phone VARCHAR(20),
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- User addresses
CREATE TABLE user_addresses (
id SERIAL PRIMARY KEY,
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
type VARCHAR(20) CHECK (type IN ('billing', 'shipping')),
street_address VARCHAR(255) NOT NULL,
city VARCHAR(100) NOT NULL,
state VARCHAR(50) NOT NULL,
postal_code VARCHAR(20) NOT NULL,
country VARCHAR(50) NOT NULL,
is_default BOOLEAN DEFAULT FALSE
);
Product Database Schema
-- Categories
CREATE TABLE categories (
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
slug VARCHAR(100) UNIQUE NOT NULL,
parent_id INTEGER REFERENCES categories(id),
description TEXT,
created_at TIMESTAMP DEFAULT NOW()
);
-- Products
CREATE TABLE products (
id SERIAL PRIMARY KEY,
name VARCHAR(255) NOT NULL,
slug VARCHAR(255) UNIQUE NOT NULL,
description TEXT,
price DECIMAL(10,2) NOT NULL,
category_id INTEGER REFERENCES categories(id),
inventory_count INTEGER DEFAULT 0,
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
Caching Strategy
Redis Caching Layers
- Product Cache: 1-hour TTL for product details and search results
- User Session Cache: 24-hour TTL for user authentication tokens
- Inventory Cache: 5-minute TTL for real-time inventory counts
- Search Cache: 30-minute TTL for popular search queries
Security Architecture
Authentication & Authorization
JWT Token Strategy
- Access Tokens: 15-minute expiration, contains user ID and roles
- Refresh Tokens: 7-day expiration, secure HTTP-only cookies
- Token Rotation: New refresh token issued with each access token refresh
- Revocation: Token blacklist with Redis for immediate revocation
API Security
- Rate Limiting: Progressive limits (100/min → 1000/min → 10000/min)
- Input Validation: Joi schemas for all API endpoints
- SQL Injection Prevention: Parameterized queries with Prisma ORM
- XSS Protection: Content Security Policy + input sanitization
Data Protection
Encryption Standards
- Data at Rest: AES-256 encryption for sensitive data
- Data in Transit: TLS 1.3 for all API communications
- Password Storage: bcrypt with 12 salt rounds
- PII Handling: Separate encrypted storage for sensitive user data
Performance Architecture
Performance Requirements
- Page Load Time: < 2 seconds for initial load
- API Response Time: < 200ms for 95th percentile
- Database Query Time: < 50ms for 95th percentile
- Concurrent Users: 10,000 simultaneous active users
- Throughput: 1,000 orders per minute peak capacity
Optimization Strategies
Frontend Optimization
- Code Splitting: Route-based and component-based splitting
- Asset Optimization: Image compression, lazy loading, CDN delivery
- Caching: Service worker caching + browser cache optimization
- Bundle Size: < 500KB initial bundle, < 100KB per route chunk
Backend Optimization
- Database Indexing: Optimized indexes for all query patterns
- Connection Pooling: 20 connections per service instance
- Query Optimization: N+1 query prevention, efficient joins
- Horizontal Scaling: Auto-scaling based on CPU and memory usage
Deployment Architecture
Infrastructure Requirements
Cloud Platform: AWS with multi-region deployment
- Primary Region: us-east-1 (Virginia)
- Secondary Region: us-west-2 (Oregon) for disaster recovery
- CDN: CloudFront for global content delivery
- Load Balancing: Application Load Balancer with health checks
Container Orchestration: Kubernetes (EKS)
- Service Mesh: Istio for service-to-service communication
- Monitoring: Prometheus + Grafana + Jaeger tracing
- Logging: ELK stack (Elasticsearch, Logstash, Kibana)
- Secrets Management: AWS Secrets Manager + Kubernetes secrets
Deployment Pipeline
CI/CD Process
- Code Commit: GitHub with branch protection rules
- Automated Testing: Unit tests, integration tests, security scans
- Build Process: Docker image creation with vulnerability scanning
- Staging Deployment: Automated deployment to staging environment
- Production Deployment: Blue-green deployment with rollback capability
Technical Decisions and Rationale
Architecture Pattern: Microservices
Decision: Implement microservices architecture with domain-driven design Rationale:
- Enables independent scaling of different system components
- Allows different teams to work on services independently
- Provides fault isolation and improved system resilience
- Supports technology diversity for optimal service implementation
Alternatives Considered:
- Monolithic architecture (rejected: scaling and team coordination limitations)
- Serverless architecture (rejected: vendor lock-in and cold start concerns)
Database Strategy: PostgreSQL + Redis
Decision: PostgreSQL for primary data storage, Redis for caching and sessions Rationale:
- PostgreSQL provides ACID compliance for transactional data
- Strong consistency requirements for financial transactions
- Redis provides high-performance caching and session storage
- Both technologies have strong ecosystem support and team expertise
Alternatives Considered:
- MongoDB (rejected: consistency requirements for financial data)
- DynamoDB (rejected: complex query requirements and cost considerations)
Frontend Technology: React + TypeScript
Decision: React with TypeScript for all frontend applications Rationale:
- Strong team expertise and extensive ecosystem
- TypeScript provides type safety for large application development
- React Native enables code sharing between web and mobile
- Excellent tooling and development experience
Alternatives Considered:
- Vue.js (rejected: smaller ecosystem and team unfamiliarity)
- Angular (rejected: complexity and learning curve concerns)
Implementation Constraints and Guidelines
Development Standards
- Code Quality: 90%+ test coverage, ESLint + Prettier enforcement
- Documentation: API documentation with OpenAPI, code comments for complex logic
- Version Control: Git flow with feature branches and pull request reviews
- Security: OWASP compliance, regular dependency updates, security testing
Performance Standards
- API Performance: 95th percentile response times under 200ms
- Database Performance: Query optimization with execution plan analysis
- Frontend Performance: Lighthouse scores > 90 for all metrics
- Monitoring: Real-time performance monitoring with alerting
Operational Requirements
- Availability: 99.9% uptime with planned maintenance windows
- Backup Strategy: Daily automated backups with 30-day retention
- Disaster Recovery: RTO < 4 hours, RPO < 1 hour
- Monitoring: Comprehensive logging, metrics, and alerting
Success Criteria and Validation
Functional Validation
- All user stories completed with acceptance criteria met
- Integration testing passes for all service interactions
- End-to-end user workflows function correctly
- Admin functionality enables complete platform management
Performance Validation
- Load testing validates 10,000 concurrent user capacity
- Response time requirements met under peak load conditions
- Database performance meets query time requirements
- Frontend performance meets page load time targets
Security Validation
- Security testing identifies no high-severity vulnerabilities
- Penetration testing validates security architecture effectiveness
- Compliance audit confirms regulatory requirement adherence
- Data protection measures validated through security review
## Common Mistakes and Warnings
### ⚠️ Critical Warnings
- **Never Skip Stakeholder Approval**: Architect Agent specifications must be formally approved before implementation begins. Proceeding without approval leads to scope disputes and rework.
- **Don't Create Implementation-Level Specifications**: The Architect Agent focuses on what and why, not how. Detailed implementation decisions belong to the Coder Agent within approved specifications.
### Common Mistakes
#### Mistake: Creating vague or ambiguous specifications
**Why it happens**: Pressure to complete specifications quickly leads to insufficient detail and clarity
**How to avoid**: Invest time in specific, measurable acceptance criteria and detailed architectural decisions
**If it happens**: Stop implementation and clarify specifications with stakeholder input before continuing
#### Mistake: Overstepping into implementation details
**Why it happens**: Technical excitement leads to specifying implementation approaches rather than requirements
**How to avoid**: Focus on what needs to be accomplished and constraints, not how to implement
**If it happens**: Refactor specifications to focus on requirements and delegate implementation to Coder Agent
#### Mistake: Ignoring non-functional requirements
**Why it happens**: Focus on features while overlooking performance, security, and operational requirements
**How to avoid**: Systematically address all requirement categories including performance, security, and operations
**If it happens**: Add comprehensive non-functional requirements and update acceptance criteria
#### Mistake: Not documenting architectural decisions
**Why it happens**: Focus on final specifications without capturing decision rationale and alternatives
**How to avoid**: Document all significant decisions with rationale and alternatives considered
**If it happens**: Schedule follow-up to capture decision rationale and update project memory
### Best Practices
- ✅ **Invest in Comprehensive Planning**: Thorough specification work prevents implementation problems and reduces overall development time
- ✅ **Focus on Requirements, Not Implementation**: Define what needs to be accomplished and let other agents determine how
- ✅ **Document All Decisions**: Capture architectural decisions with rationale for future reference and team understanding
- ✅ **Ensure Stakeholder Alignment**: Get formal approval on specifications before proceeding to implementation phases
- ✅ **Maintain Specification Traceability**: Connect all features and components back to business requirements and user value