High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Engineering Platform is a unified ecosystem designed to standardize engineering workflows, tools, and templates across multiple projects. It operates as a foundational layer that projects integrate with, primarily through Git submodules, to leverage shared configurations, specialized Model Context Protocol (MCP) servers, and AI-native automation skills.
The architecture focuses on "Chain of Thought" documentation, code protection through automated guardrails, and a bidirectional synchronization strategy between the platform and its consumer projects. It facilitates a data-driven approach to standardization through a built-in tool experimentation framework and engineering velocity tracking via DORA metrics.
Sources: README.md:4-16, CHANGELOG.md:144-155, internal/agents/documentation-agent-context.md:11-20
Core Architectural Components
The platform is structured into several distinct layers that handle different aspects of the engineering lifecycle, from project initialization to ongoing maintenance and AI-assisted development.
Platform Organization
The repository follows a modular structure where each directory serves a specific functional role in the engineering ecosystem:
| Component | Description |
|---|---|
| Configs | Shared standards for ESLint, Prettier, TypeScript, and Git hooks. |
| MCP Servers | Specialized AI tools for research, validation, and analytics. |
| Skills | ÆtherLight skills for AI-native workflow automation (e.g., code analysis, protection). |
| Templates | Context files like CLAUDE.md, PR templates, and CI/CD workflows. |
| Experiments | A framework for A/B testing development tools and measuring effectiveness. |
Sources: README.md:76-114, CHANGELOG.md:8-35
Integration Model
Projects consume the Engineering Platform typically by adding it as a Git submodule at .eng-platform/. This allows projects to reference shared configurations and run local instances of the platform's MCP servers while maintaining project-specific logic.
The diagram shows how a consumer project integrates the platform via a submodule and references its internal components for local configuration.
Sources: README.md:33-46, CHANGELOG.md:41-52, skills/initialize/initialize-eng-platform.md:45-50
AI-Native Workflow & Automation
The platform is designed for AI-assisted development, utilizing "Skills" and specialized agents to automate complex engineering tasks.
ÆtherLight Skills System
Skills are domain-agnostic automation modules used by AI agents (like Claude) to perform standardized actions. The initialize skill, for example, automates the setup of folder structures, Git workflows, and pattern libraries in new or existing repositories.
Key Skills include:
- code-analyze: Performs pattern analysis and technical debt identification.
- sprint-plan: Automates structured sprint planning and Git branch management.
- protect: Annotates code with protection levels (
@protected,@immutable).
Sources: skills/initialize/SKILL.md:1-12, skills/code-analyze/SKILL.md:1-15, CHANGELOG.md:158-175
Agent Orchestration
The platform defines specific roles for agents, such as the Documentation Agent and Infrastructure Agent, each with strict operational protocols (e.g., Pattern-TASK-ANALYSIS-001).
This sequence illustrates the interaction between an engineer and the AI-native automation layer during project startup.
Sources: internal/agents/infrastructure-agent-context.md:14-36, skills/initialize/initialize-eng-platform.md:5-20, CHANGELOG.md:165-175
Specialized MCP Ecosystem
A significant portion of the architecture is dedicated to Model Context Protocol (MCP) servers that extend the capabilities of AI assistants.
Custom MCP Server Catalog
The platform includes 11 specialized servers, many derived from the LegalAI and AdHub innovations:
| Server | Purpose |
|---|---|
| research-swarm | Adaptive Research Engine (ARE/QRE) for multi-step information synthesis. |
| basin-analyzer | Detects context drift and provides confidence scoring for AI outputs. |
| constraint-validator | Uses Z3 SMT solver for logic validation and conflict detection. |
| team-analytics | Tracks tool effectiveness and engineer health metrics. |
| beads-integration | Handles task decomposition and subtask management. |
Sources: README.md:126-140, CHANGELOG.md:255-288, PROMPT-ADD-TO-EXISTING.md:23-45
Evaluation Framework
To ensure quality, the platform enforces a standardized evaluation rubric for adding new MCP servers, scoring them across maintenance, technical quality, relevance, and integration cost.
The flow represents the rigorous evaluation process for third-party or new MCP servers before platform integration.
Sources: mcp/evaluation-criteria.md:5-50
Documentation & Pattern Standards
The platform enforces a "Chain of Thought" (CoT) documentation standard to ensure that design decisions and reasoning are preserved for both humans and AI agents.
Chain of Thought Required Elements
Every function, class, or module must include:
- DESIGN DECISION: The approach taken.
- WHY: Reasoning behind the decision.
- REASONING CHAIN: Step-by-step numbered thought process.
- PATTERN: Reference to applicable platform patterns.
- RELATED: Connected components.
Sources: internal/agents/documentation-agent-context.md:27-42
Code Protection Policy
The platform implements a multi-tier code protection system to prevent accidental regressions in stable code.
- @protected: Released code that requires refactor branches and reviews for modification.
- @immutable: Core logic that should not be changed.
- Protection Guard Hook: A pre-tool-use hook that enforces these annotations in real-time.
Sources: CHANGELOG.md:151-163, skills/initialize/SKILL.md:460-485
Conclusion
The Engineering Platform architecture is built on the principles of modularity and AI-native automation. By centralizing configurations and specialized tools like the research-swarm and constraint-validator MCP servers, it creates a robust foundation for multi-project development. The integration of DORA metrics and the tool experimentation framework ensures that the platform evolves based on empirical data rather than preference.
Sources: README.md:4-10, CHANGELOG.md:5-15