Documentation

🏗️
New · Reference
Reference Architectures
10 real-world architectures where architect fits in production systems. Diagrams, YAML configs and code ready for CI/CD, Security, AIOps, MLOps and DevOps.
10 architectures 7 domains 30+ diagrams
→

Introduction

Index of the technical documentation for the Architect v1.0.0 project.

Quick Start Guide

Installation, minimal configuration, most useful commands, and flags reference.

CLI Usage

Practical usage guide: flags, logging, configs, CI/CD, scripts, custom agents.

Architecture

Overview, component diagram, and full execution flow.

Core Loop

The AgentLoop: safety nets, StopReason, graceful close, hooks lifecycle.

Tools and Execution

Tool system: filesystem, editing, search, MCP, ExecutionEngine.

Agents and Modes

Agent system, registry, execution modes, skills, and memory.

Configuration Reference

Complete configuration schema, precedence, and environment variables.

AI Guide

Critical invariants, patterns, where to add things, pitfalls.

Data Models

All data models: Pydantic, dataclasses, and error hierarchy.

Logging System

3 pipelines, HUMAN level, icons, HumanFormatter, structlog.

Testing

Test map: ~817+ tests across 30+ files, coverage by module.

Security Model

19+ defensive layers, threat model, path traversal, command security, hardening.

Creating an MCP Server

MCP server that exposes architect as a remote tool (server.py + tools.py).

Containers

Containerfiles, Kubernetes Deployments, Docker, CI/CD configuration.

Best Practices

Prompts, agents, editing, costs, lifecycle hooks, guardrails, skills, memory, CI/CD.

Sessions

Session persistence and resume: save, list, resume, and clean up between runs.

Reports

Execution reports in JSON, Markdown, and GitHub PR comment for CI/CD.

Dry Run

Execution simulation: DryRunTracker, WRITE_TOOLS/READ_TOOLS, action plan.

Ralph Loop

Automatic iteration with checks: RalphConfig, RalphLoop, clean context, worktrees.

Pipelines

Multi-step YAML workflows: variables, conditions, output_var, checkpoints, dry-run.

Parallel Execution

Multiple agents in worktrees: ParallelRunner, workers, round-robin models.

Checkpoints

Git-based restore points: CheckpointManager, rollback, pipeline integration.

Auto-Review

Post-build review with clean context: AutoReviewer, ReviewResult, fix-pass.

Sub-Agents

Sub-task delegation (explore/test/review) with isolated context and limited tools.

Code Health Delta

Before/after code quality metrics analysis: complexity, duplicates, long functions.

Competitive Evaluation

Multi-model comparison with ranking by quality, efficiency, and cost.

OpenTelemetry Traces

Session, LLM, and tool spans: OTLP, console, JSON file exporters.

Presets

Project initialization with predefined configurations (python, node-react, ci, paranoid, yolo).

Extensibility

Create custom tools, agents, lifecycle hooks, skills, guardrails — with examples.

Prompt Engineering

Writing effective prompts, .architect.md, skills, anti-patterns, recipes.

CI/CD Integration

Recipes for GitHub Actions, GitLab CI, Jenkins: review bots, auto-fix, pipelines.

Cost Management

CostTracker, per-model pricing, budgets, prompt caching, local cache, optimization.

Troubleshooting

Symptom-based diagnosis: LLM errors, loops, tools, hooks, guardrails, exit codes.

No results found.