Skip to main content

​
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.
The core purpose is to enable repeatable, high-quality workflows for agentic development and beyond, supporting both greenfield and brownfield projects.

​
System Architecture

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

​
Core Components

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

​
Agents

Agent Definitions

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.)
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: 
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

Team Bundles

Collections of agents packaged together for specific purposes (full-stack development, backend-only, etc.)

Web UI Distribution

Teams are compiled into single .txt bundles for web-based AI interfaces
Team files use wildcards to include agents: 
agents:
  - "*"  # Include all agents
# OR specific agents:
  - dev
  - qa
  - devops

​
Workflows

Workflows define prescribed sequences of steps for specific project types:
New projects starting from scratch:
  • greenfield-fullstack.yaml
  • greenfield-service.yaml
  • greenfield-ui.yaml
Existing codebases requiring assessment:
  • brownfield-fullstack.yaml
  • brownfield-discovery.yaml (10-phase technical debt assessment)
  • brownfield-service.yaml
  • brownfield-ui.yaml
Environment and tooling setup:
  • setup-environment.yaml
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

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}}

​
Template Processing System

A sophisticated three-component system handles document generation:
1

template-format.md

Defines the markup language:
  • Variable substitution: {{placeholders}}
  • AI processing directives: [[LLM: instructions]]
  • Conditional logic blocks
2

create-doc.md

Orchestrates the workflow:
  • Template selection
  • User interaction modes (incremental vs. rapid)
  • Validation and processing
3

advanced-elicitation.md

Provides interactive refinement:
  • 10 structured brainstorming actions
  • Section-by-section review
  • Iterative improvement
Key Principle: Templates embed both output structure AND processing intelligence, often eliminating the need for separate task files.

​
Technical Preferences System

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

Consistency

All agents reference the same preferences across projects

Efficiency

Eliminates repeated technology specification

Personalization

Agents provide aligned recommendations

Learning

Evolves with lessons learned over time
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

Direct Agent Access

Users interact directly with agent markdown files in .aiox-core/agents/. The IDE integration (Cursor, Claude Code, etc.) handles agent invocation.
Workflow:
  1. Agent file loaded from .aiox-core/development/agents/
  2. Dependencies resolved dynamically
  3. Tasks/templates loaded on-demand

​
Web UI Environment

Pre-built Bundles

The web-builder.js script creates .txt bundles containing entire agent teams with all dependencies.
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:
1

Ideation & Planning

  • Brainstorming sessions
  • Market research
  • Project briefs
2

Architecture & Design

  • System architecture definition
  • UI/UX specifications
  • Technical decision documentation
3

Development Execution

  • Cyclical workflow: SM drafts stories → Dev implements
  • Works for both greenfield and brownfield
  • Quality gates throughout

​
Key Architectural Principles

Separation of Concerns: Template markup is processed internally by agents but never exposed to users.
Modularity: All resources are modular and reusable across agents and workflows.
Self-Contained Intelligence: Templates and tasks embed their own processing logic.
Environment Flexibility: Same core framework supports IDE and web UI environments.

​
Next Steps

CLI First Principle

Learn why the CLI is the source of truth

Agent System

Deep dive into agent architecture

Workflows

Explore available workflows

Story-Driven Development

Understand the development methodology

Build docs developers (and LLMs) love

Get started for freeTalk to us