Architecture & Concepts

How JARFIS orchestrates AI agents through structured phases — from triage to retrospective — with human oversight at every critical juncture.

The JARFIS Philosophy

JARFIS is built on a foundational set of principles that govern every design decision, from agent behavior to phase transitions. These principles aren't abstract ideals — they are enforced constraints embedded in the system.

The Nine Principles

Nine core principles that guide every design decision in the system:

Productive Tensions

Intentional tensions exist between principles. This balance keeps the system healthy:

The Orchestration Model

JARFIS follows a phase-gated orchestration model. Work flows through sequential phases, with human gates at critical decision points. The orchestrator manages state transitions and agent activation.

Key properties of the orchestration model:

• Sequential phases — each phase must complete before the next begins
• Conditional execution — Phase 3 (UX) only runs when UI changes are needed; Phase 4.5 (Ops) only for infrastructure changes
• Type-based routing — Type A (simple fixes) skip directly to Phase 4; Type B (medium) start at Phase 1; Type C (complex) go through full pipeline
• Gate reversibility — humans can send work back to earlier phases at any gate

The 11 Agent Roles

Each agent is a specialized role with defined responsibilities, activated only when the current phase requires its expertise. Agents are organized into four categories:

Planning & Design Agents

Implementation Agents

Quality & Review Agents

Dialectic Agents

The 9-Phase Pipeline

The complete pipeline with phase responsibilities and gate positions:

State Management

JARFIS maintains workflow state through a structured state file that tracks:

• Current phase — which phase is currently executing
• Phase outputs — artifacts produced by each completed phase
• Gate decisions — human decisions at each gate with timestamps
• Agent activations — which agents have been activated and their outputs
• Recovery checkpoints — snapshots for resuming interrupted workflows

State is persisted as JSON files in the .jarfis/ directory within your project. This enables workflow recovery after interruptions — you can resume exactly where you left off.

The Learning System

JARFIS implements a 3-block learning architecture that enables continuous improvement:

• Global Learnings — cross-project patterns, best practices, and anti-patterns. Loaded in Phase 0 and updated in Phase 6.
• Project Context — project-specific conventions, tech stack decisions, architectural patterns. Persists across workflows within the same project.
• Workflow Memory — current workflow state, decisions made, and rationale. Ephemeral — lives only for the duration of the workflow.

This architecture means JARFIS gets better over time — it learns from past mistakes and successes, adapting its recommendations to your specific project context.

Next Steps

• Quick Start — Install JARFIS and run your first workflow
• API Reference — All commands and configuration details
• Guides & Customization — Advanced workflow patterns