> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Understanding the AIOX Method architecture and core components

## Overview

The AIOX Method provides a structured yet flexible framework of prompts, templates, and workflows for guiding AI agents through complex software development tasks. The system is designed around the `.aiox-core` directory, which serves as the central intelligence hub for all agent operations.

<Info>
  The core purpose is to enable **repeatable, high-quality workflows** for agentic development and beyond, supporting both greenfield and brownfield projects.
</Info>

## System Architecture

The entire AIOX ecosystem is structured around modular, reusable components that agents dynamically load based on their defined capabilities.

```mermaid theme={null}
graph TD
    subgraph AIOX Method Project
        subgraph Core Framework
            A["aiox-core"]
            A --> B["agents"]
            A --> C["agent-teams"]
            A --> D["workflows"]
            A --> E["templates"]
            A --> F["tasks"]
            A --> G["checklists"]
            A --> H["data (KB)"]
        end

        subgraph Tooling
            I["tools/builders/web-builder.js"]
        end

        subgraph Outputs
            J["dist"]
        end

        B -- defines dependencies for --> E
        B -- defines dependencies for --> F
        B -- defines dependencies for --> G
        B -- defines dependencies for --> H

        C -- bundles --> B
        I -- reads from --> A
        I -- creates --> J
    end

    subgraph Target Environments
        K["IDE (Cursor, VS Code, etc.)"]
        L["Web UI (Gemini, ChatGPT)"]
    end

    B --> K
    J --> L

    style A fill:#1a73e8,color:#fff
    style I fill:#f9ab00,color:#fff
    style J fill:#34a853,color:#fff
```

## Core Components

The `.aiox-core` directory contains all definitions and resources that power agent capabilities.

### Agents

<Card title="Agent Definitions" icon="robot">
  Each agent is defined in a markdown file with YAML frontmatter specifying:

  * **Persona**: Role, communication style, identity
  * **Dependencies**: Tasks, templates, checklists, and data files
  * **Commands**: Available operations the agent can execute
  * **Tools**: External integrations (git, CodeRabbit, context7, etc.)
</Card>

Agents are self-contained units with:

* Clear role definitions and responsibility boundaries
* Startup instructions that load project-specific documentation
* Dependency lists that inform build tools which resources to bundle
* Command interfaces for user interaction

**Example Agent Structure:**

```yaml theme={null}
agent:
  name: Dex
  id: dev
  title: Full Stack Developer
  icon: 💻
  
persona:
  role: Expert Senior Software Engineer
  style: Pragmatic, detail-oriented
  
commands:
  - name: develop
    description: Implement story tasks
  - name: run-tests
    description: Execute linting and tests

dependencies:
  tasks:
    - dev-develop-story.md
    - apply-qa-fixes.md
  templates:
    - story-tmpl.yaml
  tools:
    - git
    - coderabbit
```

### Agent Teams

<CardGroup cols={2}>
  <Card title="Team Bundles" icon="users">
    Collections of agents packaged together for specific purposes (full-stack development, backend-only, etc.)
  </Card>

  <Card title="Web UI Distribution" icon="globe">
    Teams are compiled into single `.txt` bundles for web-based AI interfaces
  </Card>
</CardGroup>

Team files use wildcards to include agents:

```yaml theme={null}
agents:
  - "*"  # Include all agents
# OR specific agents:
  - dev
  - qa
  - devops
```

### Workflows

Workflows define prescribed sequences of steps for specific project types:

<AccordionGroup>
  <Accordion title="Greenfield Projects">
    New projects starting from scratch:

    * `greenfield-fullstack.yaml`
    * `greenfield-service.yaml`
    * `greenfield-ui.yaml`
  </Accordion>

  <Accordion title="Brownfield Projects">
    Existing codebases requiring assessment:

    * `brownfield-fullstack.yaml`
    * `brownfield-discovery.yaml` (10-phase technical debt assessment)
    * `brownfield-service.yaml`
    * `brownfield-ui.yaml`
  </Accordion>

  <Accordion title="Configuration Workflows">
    Environment and tooling setup:

    * `setup-environment.yaml`
  </Accordion>
</AccordionGroup>

Workflows serve as strategic guides for users and the `@aiox-master` agent, defining:

* Sequences for complex and simple projects
* Agent interactions at each step
* Artifacts created
* Conditions for progression

### Reusable Resources

<Tabs>
  <Tab title="Templates">
    Markdown templates for common documents:

    * PRDs (Product Requirements)
    * Architecture specifications
    * User stories
    * ADRs (Architecture Decision Records)

    Templates are **self-contained** and include:

    * Desired document structure
    * Embedded LLM instructions via `[[LLM: instructions]]` blocks
    * Variable placeholders: `{{project_name}}`
  </Tab>

  <Tab title="Tasks">
    Executable instructions for specific actions:

    * `create-next-story.md` - Story creation workflow
    * `dev-develop-story.md` - Development execution
    * `qa-review-story.md` - Quality assurance
    * `create-doc.md` - Document generation orchestration

    Tasks define step-by-step procedures agents follow precisely.
  </Tab>

  <Tab title="Checklists">
    Quality assurance and validation:

    * `story-dod-checklist.md` - Definition of Done
    * `story-draft-checklist.md` - Story quality validation
    * `self-critique-checklist.md` - Agent self-review
  </Tab>

  <Tab title="Data/Knowledge Base">
    Core knowledge and preferences:

    * `aiox-kb.md` - Framework knowledge base
    * `technical-preferences.md` - User technical stack preferences
    * `workflow-patterns.yaml` - Common workflow sequences
    * `workflow-chains.yaml` - Agent handoff chains
  </Tab>
</Tabs>

## Template Processing System

A sophisticated three-component system handles document generation:

```mermaid theme={null}
graph LR
    A[User Request] --> B[create-doc.md]
    B --> C[template-format.md]
    B --> D[Template File]
    D --> E[advanced-elicitation.md]
    C --> F[Processed Document]
    E --> F
    
    style B fill:#1a73e8,color:#fff
    style C fill:#f9ab00,color:#fff
    style E fill:#34a853,color:#fff
```

<Steps>
  <Step title="template-format.md">
    Defines the markup language:

    * Variable substitution: `{{placeholders}}`
    * AI processing directives: `[[LLM: instructions]]`
    * Conditional logic blocks
  </Step>

  <Step title="create-doc.md">
    Orchestrates the workflow:

    * Template selection
    * User interaction modes (incremental vs. rapid)
    * Validation and processing
  </Step>

  <Step title="advanced-elicitation.md">
    Provides interactive refinement:

    * 10 structured brainstorming actions
    * Section-by-section review
    * Iterative improvement
  </Step>
</Steps>

<Note>
  **Key Principle:** Templates embed both output structure AND processing intelligence, often eliminating the need for separate task files.
</Note>

## Technical Preferences System

The `technical-preferences.md` file serves as a persistent technical profile:

<CardGroup cols={2}>
  <Card title="Consistency" icon="check">
    All agents reference the same preferences across projects
  </Card>

  <Card title="Efficiency" icon="bolt">
    Eliminates repeated technology specification
  </Card>

  <Card title="Personalization" icon="user">
    Agents provide aligned recommendations
  </Card>

  <Card title="Learning" icon="graduation-cap">
    Evolves with lessons learned over time
  </Card>
</CardGroup>

**Content includes:**

* Preferred technology stacks
* Design patterns
* External services
* Coding standards
* Anti-patterns to avoid

## Build & Delivery Process

AIOX supports two primary environments with different delivery mechanisms:

### IDE Environment

<Card title="Direct Agent Access" icon="code">
  Users interact directly with agent markdown files in `.aiox-core/agents/`. The IDE integration (Cursor, Claude Code, etc.) handles agent invocation.
</Card>

**Workflow:**

1. Agent file loaded from `.aiox-core/development/agents/`
2. Dependencies resolved dynamically
3. Tasks/templates loaded on-demand

### Web UI Environment

<Card title="Pre-built Bundles" icon="package">
  The `web-builder.js` script creates `.txt` bundles containing entire agent teams with all dependencies.
</Card>

**Build Process:**

1. **Resolve Dependencies**: Read agent/team definition
2. **Recursive Discovery**: Find all dependent resources
3. **Bundle Content**: Concatenate files with path separators
4. **Output**: Save to `dist/` directory

**Usage:**
Upload bundle to web UI (Gemini, ChatGPT) - provides complete context in single file.

## Development Lifecycle Support

The architecture facilitates the complete development lifecycle:

<Steps>
  <Step title="Ideation & Planning">
    * Brainstorming sessions
    * Market research
    * Project briefs
  </Step>

  <Step title="Architecture & Design">
    * System architecture definition
    * UI/UX specifications
    * Technical decision documentation
  </Step>

  <Step title="Development Execution">
    * Cyclical workflow: SM drafts stories → Dev implements
    * Works for both greenfield and brownfield
    * Quality gates throughout
  </Step>
</Steps>

## Key Architectural Principles

<Warning>
  **Separation of Concerns**: Template markup is processed internally by agents but never exposed to users.
</Warning>

<Check>
  **Modularity**: All resources are modular and reusable across agents and workflows.
</Check>

<Check>
  **Self-Contained Intelligence**: Templates and tasks embed their own processing logic.
</Check>

<Check>
  **Environment Flexibility**: Same core framework supports IDE and web UI environments.
</Check>

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI First Principle" icon="terminal" href="/concepts/cli-first">
    Learn why the CLI is the source of truth
  </Card>

  <Card title="Agent System" icon="robot" href="/concepts/agents">
    Deep dive into agent architecture
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/concepts/workflows">
    Explore available workflows
  </Card>

  <Card title="Story-Driven Development" icon="book" href="/concepts/story-driven-development">
    Understand the development methodology
  </Card>
</CardGroup>