AI Coding Factory - Architecture & Design AI Coding Factory is built on a multi-agent orchestration model where specialized OpenCode agents handle different stages of the software development lifecycle. This document describes the system architecture, design decisions, and integration patterns.
┌──────────────────────────────────────────────────────────────────────────────────────────┐
│ OpenCode Platform │
│ (Agent Orchestration Layer) │
└──────────────────────────────────────────────────────────────────────────────────────────┘
│
┌──────────────────────────────┼──────────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Local │ │ Skills │ │ Plugins │
│ Inference │ │ Library │ │ (MCP) │
│ Server │ │ (12 Skills) │ │ │
├───────────────┤ ├─────────────────┤ ├─────────────────┤
│ • vLLM │ │ • net-web-api │ │ • Azure DevOps │
│ • LM Studio │ │ • net-cqrs │ │ • GitHub │
│ • GLM-4.7 │ │ • net-k8s │ │ • SonarQube │
└───────────────┘ └─────────────────┘ └─────────────────┘
Component
Purpose
Count
Agents Stage-specific + Scrum team automation
5 stage + 6 team + 3 subagents
Skills Reusable .NET patterns and templates
12 skills
Plugins External tool integrations
3 MCP servers
Templates Ready-to-use project structures
2 templates
┌─────────────────────────────────────────────────────────────────────┐
│ PRIMARY AGENTS │
├─────────────┬─────────────┬─────────────┬─────────────┬─────────────┤
│ Ideation │ Prototype │ PoC │ Pilot │ Product │
│ Agent │ Agent │ Agent │ Agent │ Agent │
│ │ │ │ │ │
│ temp: 0.7 │ temp: 0.3 │ temp: 0.2 │ temp: 0.1 │ temp: 0.1 │
└──────┬──────┴──────┬──────┴──────┬──────┴──────┬──────┴──────┬──────┘
│ │ │ │ │
└─────────────┴──────┬──────┴─────────────┴─────────────┘
│
▼
┌─────────────────────────────────┐
│ SUBAGENTS │
├───────────┬───────────┬─────────┤
│ Security │ Code │ Test │
│ Auditor │ Reviewer │Generator│
└───────────┴───────────┴─────────┘
Agent
Temperature
Bash Access
Primary Skills
Output Artifacts
Ideation 0.7
No
net-agile, net-scrum
Requirements, user stories, architecture
Prototype 0.3
Yes
net-web-api
MVP code, basic structure
PoC 0.2
Yes
net-jwt-auth, net-repository
Secure code, tests
Pilot 0.1
Yes
net-testing, net-docker, net-github-actions
Production code, CI/CD
Product 0.1
Yes
net-observability, net-kubernetes
Monitoring, scaling
Agent
Responsibilities
product-owner Story IDs, acceptance criteria, backlog priorities
scrum-master DoR/DoD enforcement, traceability compliance
developer Implementation, tests, documentation
qa Test linkage, coverage enforcement
security Threat modeling, security reviews
devops CI/CD, release readiness, deployment validation
┌─────────────┐
│ Request │
│ Received │
└──────┬──────┘
│
▼
┌──────────────────┐ ┌──────────────────┐
│ Agent Selection │────▶│ Skill Loading │
│ (by /agent cmd) │ │ (on-demand) │
└──────────────────┘ └────────┬─────────┘
│
┌──────────────────────────┘
│
▼
┌──────────────────┐ ┌──────────────────┐
│ Tool Execution │────▶│ Artifact Output │
│ (write, bash) │ │ (code, docs) │
└──────────────────┘ └──────────────────┘
Category
Skills
Purpose
API Development net-web-api
ASP.NET Core scaffolding
Domain Modeling net-domain-model, net-cqrs
DDD patterns, CQRS
Data Access net-repository-pattern
Repository, Unit of Work
Security net-jwt-auth
JWT authentication
Testing net-testing
xUnit, integration tests
DevOps net-docker, net-github-actions, net-kubernetes
Containers, CI/CD, K8s
Observability net-observability
Logging, tracing, metrics
Agile net-agile, net-scrum
Ceremonies, artifacts
.opencode/skill/{skill-name}/
└── SKILL.md # Frontmatter + instructions
├── name # Skill identifier
├── description # What the skill does
├── license # MIT
├── compatibility # opencode
└── metadata # audience, framework, patterns
Discovery ──▶ Parsing ──▶ Validation ──▶ Injection ──▶ Execution
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
Scan Parse Validate Inject to Agent
dirs SKILL.md frontmatter context uses it
Clean Architecture Solution templates/clean-architecture-solution/
├── src/
│ ├── Api/ # Presentation Layer
│ │ ├── Controllers/
│ │ ├── Middleware/
│ │ ├── Extensions/
│ │ └── Program.cs
│ ├── Application/ # Application Layer
│ │ ├── Commands/
│ │ ├── Queries/
│ │ ├── Behaviours/
│ │ └── DTOs/
│ ├── Domain/ # Domain Layer
│ │ ├── Entities/
│ │ ├── ValueObjects/
│ │ ├── Events/
│ │ └── Interfaces/
│ └── Infrastructure/ # Infrastructure Layer
│ ├── Data/
│ ├── Repositories/
│ └── Services/
├── tests/
│ ├── UnitTests/
│ └── IntegrationTests/
└── docker/
├── Dockerfile
└── docker-compose.yml
┌────────────────────────────────────────────────────┐
│ Presentation │
│ (ASP.NET Core API) │
└─────────────────────┬──────────────────────────────┘
│ depends on
┌─────────────────────▼──────────────────────────────┐
│ Application │
│ (Services, DTOs, Validators) │
└─────────────────────┬──────────────────────────────┘
│ depends on
┌─────────────────────▼──────────────────────────────┐
│ Domain │
│ (Entities, Value Objects, Events) │
└─────────────────────▲──────────────────────────────┘
│ implements
┌─────────────────────┼──────────────────────────────┐
│ Infrastructure │
│ (EF Core, Repositories, External Services) │
└────────────────────────────────────────────────────┘
Local Inference Architecture
Provider
Type
Recommended For
vLLM High-performance server
Production, CI/CD
LM Studio Desktop application
Development, prototyping
┌──────────────────┐
│ OpenCode │
│ Agent │
└────────┬─────────┘
│
│ HTTP/REST
▼
┌──────────────────┐
│ OpenAI- │
│ Compatible API │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ vLLM / │
│ LM Studio │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Local Model │
│ (GLM-4.7, │
│ MiniMax, etc.) │
└──────────────────┘
{
"provider" : {
"local-inference" : {
"type" : " openai-compatible" "baseUrl" : " http://localhost:8000/v1" "apiKey" : " your-api-key" "timeout" : 120000
}
}
} MCP Integration Architecture
Server
Purpose
Features
Azure DevOps DevOps + tracking
Boards, Repos, Pipelines (via MCP endpoint)
GitHub DevOps + tracking
Issues, Projects, PRs, Actions
SonarQube Code quality
Analysis, quality gates, metrics
┌──────────────────┐
│ OpenCode │
│ Agent │
└────────┬─────────┘
│
│ JSON-RPC
▼
┌──────────────────┐
│ MCP Client │
│ (OpenCode) │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ MCP Server │
│ (External) │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ External │
│ Services │
│ (Azure DevOps / │
│ GitHub) │
└──────────────────┘
┌──────────────────┐
│ OpenCode │
│ Agent │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Permission │ ← Bash, Write, Edit
│ Gate │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Execution │ ← Allow, Ask, Deny
│ Layer │
└──────────────────┘
Operation
Level
Description
git *Allow
Version control operations
dotnet *Allow
.NET CLI commands
docker *Ask
Container operations (user approval)
*Deny
All other commands blocked
editAsk
File modifications require approval
writeAsk
New file creation requires approval
Security Best Practices Enforced
No hardcoded secrets - Secrets via environment variablesParameterized queries - SQL injection preventionInput validation - All user inputs validatedJWT authentication - Stateless, secure tokensHTTPS enforcement - Secure transportSecurity headers - XSS, CSRF, clickjacking protection
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Build │───▶│ Test │───▶│ Scan │───▶│ Deploy │───▶│ Verify │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
│
▼
┌──────────────┐
│ Quality │
│ Gate │
└──────────────┘
Check
Threshold
Tool
Unit Test Coverage
≥80%
Coverlet
Code Duplication
≤3%
SonarQube
Security Vulnerabilities
0 Critical
OWASP, CodeQL
Build Warnings
0
.NET Compiler
Traceability Architecture Story (ACF-###)
│
├── Story file (artifacts/stories)
├── Tests (Trait/comment/naming)
├── Commit messages (git history)
└── Release notes (generated)
scripts/traceability/traceability.py validatescripts/traceability/traceability.py reportscripts/traceability/traceability.py release-notes
Artifacts are stored in artifacts/traceability.
Generated Application Architecture Clean Architecture Pattern Applications generated by AI Coding Factory follow Clean Architecture:
Layer
Responsibility
Dependencies
Domain Business logic, entities, value objects
None
Application Use cases, DTOs, interfaces
Domain
Infrastructure Data access, external services
Domain, Application
Presentation API, controllers, middleware
Application, Infrastructure
Pattern
Implementation
Purpose
Repository Generic + specific repositories
Data access abstraction
Unit of Work DbContext with transactions
Atomic operations
CQRS MediatR commands/queries
Read/write separation
Domain Events IDomainEvent with handlers
Loose coupling
Value Objects Immutable with equality
Type safety
Observability Architecture ┌─────────────────────────────────────────────────────────────────────┐
│ Application │
├─────────────────┬─────────────────┬─────────────────────────────────┤
│ Logging │ Tracing │ Metrics │
│ (Serilog) │ (OpenTelemetry) │ (Prometheus) │
└────────┬────────┴────────┬────────┴────────────┬────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────┐ ┌─────────────────────────────────┐
│ Seq / ELK │ │ Jaeger │ │ Prometheus / Grafana │
└─────────────────┘ └─────────────┘ └─────────────────────────────────┘
Endpoint
Purpose
K8s Probe
/healthOverall status
-
/health/liveApplication alive
Liveness
/health/readyReady for traffic
Readiness
Kubernetes Deployment Architecture Namespace : your-app
├── Deployment (replicas : 2-10)
│ └── Pod
│ └── Container : api
├── Service (ClusterIP)
├── Ingress (with TLS)
├── ConfigMap (app settings)
├── Secret (credentials)
├── HPA (autoscaling)
└── PDB (disruption budget)
Resource
Request
Limit
CPU
100m
500m
Memory
256Mi
512Mi
ai-coding-factory/
├── .opencode/
│ ├── opencode.json # Main configuration
│ ├── agent/ # 5 stage + 6 team + 3 subagent definitions
│ ├── skill/ # 12 reusable skills
│ │ ├── net-web-api/
│ │ ├── net-cqrs/
│ │ ├── net-kubernetes/
│ │ └── ...
│ ├── plugin/ # MCP plugins
│ ├── templates/ # Agile templates
│ │ ├── agile/ # Ceremonies, DoD, DoR
│ │ ├── roles/ # PO, SM, Developer playbooks
│ │ └── artifacts/ # ADR template
│ └── prompts/ # Common agent instructions
├── templates/ # Project templates
│ ├── clean-architecture-solution/
│ └── microservice-template/
├── projects/ # Generated projects
├── scripts/ # Automation
└── docs/ # Documentation
Create .opencode/agent/{agent-name}.md
Add agent config to .opencode/opencode.json
Define skills, permissions, and temperature
Create .opencode/skill/{skill-name}/SKILL.md
Add frontmatter with metadata
Document usage and examples
Create templates/{template-name}/
Add README.md with instructions
Include placeholder tokens for customization