GIAL 3.0

AI Agent Orchestration Framework with Squad Mode, Fix Loop, and Multi-Runtime Support

GIAL (Generative Intelligent Agent Lifecycle) is a production-grade orchestration system for AI-driven software engineering tasks. It coordinates multiple agent runtimes through an event-driven architecture with deterministic state management, parallel squad execution, adaptive fix loops, policy enforcement, and full observability.

Features

• Event-Driven Architecture — States emit events, handlers react. No linear orchestrator loop. Enables parallelism, observability, and extensibility without modifying core.
• State Machine with Crash Recovery — Atomic writes, checksum integrity validation, idempotent transitions. Tasks survive process crashes and resume from safe points.
• Squad Parallel Execution — DAG-based task decomposition across Architect, Coder, Verifier, and Auditor roles. Independent subtasks execute concurrently via Promise.allSettled.
• Adaptive Fix Loop — Failure classification (test/build/runtime/git/permission/network/contract), strategy selection (retry/decompose/switch-runtime/human-escalation), learned pattern budgets.
• Policy Engine — Glob-pattern rules for blocking destructive commands, requiring approval for sensitive operations. Wired via events, not hardcoded.
• Plugin System — Pre/post hooks at every lifecycle point. Manifest-validated plugins with isolated error handling.
• Multi-Runtime Adapters — Hermes, Claude Code, and OpenCode with strict availability checking. No silent fallbacks.
• Verification Gate — Auto-detects test/lint/build commands per project language. Configurable timeouts and retry policies.
• Observability — Structured event logging (JSONL), per-state duration tracking, token/cost accumulation, timeline visualization.
• Smart Context Windowing — Token-budget-aware context selection with relevance scoring. Sliding, summary, and selective strategies.
• Multi-Project Workspace — Manage multiple project roots with isolated .gial directories and shared contracts.
• Migration from 2.0 — Automated state and config migration with backup, dry-run support, and integrity validation.

Prerequisites

• Node.js >= 20
• At least one agent runtime installed and on PATH:
  • Hermes (hermes)
  • Claude Code (claude)
  • OpenCode (opencode)

Installation

npm install gial-cli

Or use directly via npx:

npx gial-cli init

Quick Start

# Initialize GIAL in your project
gial init

# Check environment health
gial doctor

# Start a task
gial task "add user authentication with JWT tokens"

# Monitor progress
gial status

# Resume a paused task
gial resume <task-id-prefix>

CLI Reference

gial init

Initialize GIAL in the current project. Creates .gial/ directory structure and default config.yaml.

gial init            # Create .gial/ with defaults
gial init --force    # Overwrite existing config

gial task <intent>

Start a new task from a natural language description.

gial task "fix login bug in auth module"
gial task "refactor database layer" --no-squad
gial task "add API endpoint" --runtime claude

| Option | Description | Default | |--------|-------------|---------| | --squad / --no-squad | Enable/disable squad mode | true | | --runtime <name> | Agent runtime (auto, hermes, claude, opencode) | auto |

gial status

List all incomplete tasks with state, age, and pause status.

gial status

Output:

Task ID  │ State        │ Intent                          │ Age   │ Paused
─────────┼──────────────┼─────────────────────────────────┼───────┼───────
a1b2c3d4…│ IMPLEMENTATION│ add user authentication         │ 12m ago│ ▶ No
e5f6g7h8…│ VERIFICATION │ fix login bug                   │ 2h ago │ ⏸ Yes

gial resume <taskId>

Resume a paused or incomplete task. Supports full UUID or 8-character prefix.

gial resume a1b2c3d4
gial resume a1b2c3d4-e5f6-7890-abcd-ef1234567890

Validates state integrity via checksum before resuming. Reports safe resume point if corruption detected.

gial doctor

Check environment health: Node version, available runtimes, .gial directory, config validity.

gial doctor

gial migrate

Migrate GIAL 2.0 state and config to 3.0 format.

gial migrate              # Migrate with backup
gial migrate --dry-run    # Validate without writing

Creates backups in .gial/backups/ before overwriting. Adds missing fields (checksum, pausedAt, failurePatterns) and recomputes integrity hashes.

Configuration

After gial init, edit .gial/config.yaml:

fixLoop:
  maxAttempts: 3
  adaptiveBudget: true
  strategies: [retry, decompose, switch-runtime, human-escalation]
  retryBaseDelayMs: 1000   # exponential backoff base for plain retries
  retryMaxDelayMs: 30000   # cap for retry delays (full jitter applied)

verification:
  timeoutMs: 60000
  maxRetries: 2
  requireAllCommands: true

autonomy:
  autoKeywords: [typo, lint, format, rename, comment, docs]
  architectKeywords: [migrate, refactor, architecture, redesign, breaking]
  thresholds:
    autoMax: -1        # -1 disables AUTO; set >= 0 to enable
    architectMin: 4

policy:
  strictMode: true
  rules: []            # User rules prepended before defaults

models:
  default: claude-sonnet-4-20250514
  fallback: claude-haiku-3-20250414
  routing: {}

squad:
  enabled: true
  parallel: true
  personas: {}         # Override systemPrompt, tools, maxConcurrency per role

observability:
  eventsFile: .gial/events.jsonl
  metricsEnabled: true
  tokenTracking: true

plugins:
  directory: .gial/plugins
  enabled: []          # List of plugin names to load

context:
  maxTokens: 100000
  summarizationThreshold: 80000
  windowStrategy: sliding  # sliding | summary | selective

Environment variable overrides use GIAL_ prefix:

GIAL_FIXLOOP_MAXATTEMPTS=10 gial task "complex migration"
GIAL_SQUAD_PARALLEL=false gial task "sequential only task"

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      CLI / API ENTRY                        │
└──────────────────────────┬──────────────────────────────────┘
                           │ emits TASK_CREATED
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                      EVENT BUS                              │
│  (ordered handlers, priority-based, error-isolated)         │
└──┬──────────┬──────────┬──────────┬──────────┬─────────────┘
   │          │          │          │          │
   ▼          ▼          ▼          ▼          ▼
 STATE     POLICY    SQUAD      FIX-LOOP   OBSERVABILITY
 MACHINE   GATE      DISPATCHER STRATEGIES  LOGGER
   │          │          │          │          │
   ▼          ▼          ▼          ▼          ▼
 PERSIST   BLOCK/     PARALLEL   ADAPTIVE   EVENTS.JSONL
 + RECOVER APPROVE    AGENTS     BUDGETS    + METRICS

Module Overview

| Phase | Modules | Purpose | |-------|---------|---------| | Foundation | EventBus, StateMachine, ConfigLoader, CrashRecovery | Core infrastructure | | Orchestration | TaskAnalyzer, TaskDAG, LifecycleCoordinator, Orchestrator | Task lifecycle management | | Squad & Fix Loop | SquadCoordinator, SquadDispatcher, FixLoop, FailureClassifier | Parallel execution + adaptive recovery | | Adapters & Verification | Hermes/Claude/OpenCode adapters, VerificationGate, MatrixBuilder, ContractValidator | Runtime abstraction + quality gates | | Supporting Systems | PolicyEngine, SkillsSelector, ContextWindower, AutonomyClassifier, GitSafetyAnalyzer, Observability | Cross-cutting concerns | | Plugins & Workspace | PluginRegistry, PluginManifest, WorkspaceManager | Extensibility + multi-project | | CLI & Migration | CLI commands, V2ToV3Migrator | User interface + upgrade path |

Plugin Development

Create a plugin in .gial/plugins/<plugin-name>/:

manifest.yaml

name: my-plugin
version: 1.0.0
description: Custom pre-transition validation
hooks:
  - preTransition
  - postVerification
config:
  maxFileSize: 10000

index.ts

import type { GialPlugin } from 'gial';

const plugin: GialPlugin = {
  name: 'my-plugin',
  version: '1.0.0',
  hooks: {
    preTransition: (ctx) => {
      if (ctx.state?.currentState === 'IMPLEMENTATION') {
        // Block transition if custom condition fails
        return { proceed: true, message: 'Custom check passed' };
      }
      return { proceed: true };
    },
    postVerification: async (ctx) => {
      // Post-processing after verification completes
      return { proceed: true, metadata: { checkedAt: new Date().toISOString() } };
    },
  },
};

export default plugin;

Available Hook Points

| Hook | Type | Description | |------|------|-------------| | preTransition | Pre | Block or modify state transitions | | postTransition | Post | React to completed transitions | | preVerification | Pre | Block verification or inject criteria | | postVerification | Post | React to verification results | | preImplementation | Pre | Block implementation or modify spec | | postImplementation | Post | React to implementation completion | | onTaskComplete | Post | Final cleanup or notification | | onTaskBlocked | Post | Handle blocked tasks |

Pre-hooks returning { proceed: false } stop execution. Post-hooks always run; errors are isolated.

Enable in config:

plugins:
  enabled: [my-plugin]

A built-in reference plugin ships with the package: task-summary (createTaskSummaryPlugin({ logPath }) from gial) appends one JSON line per completed task to .gial/task-summary.jsonl. See docs/ARCHITECTURE.md for the event flow, state integrity model, and spawn hardening notes.

Migration from 2.0

# Preview what will change
gial migrate --dry-run

# Execute migration with automatic backup
gial migrate

The migrator:

• Detects v2 state files (missing checksum, pausedAt, failurePatterns)
• Adds missing fields with safe defaults
• Computes SHA-256 checksums using canonical serialization
• Backs up originals to .gial/backups/
• Validates output against v3 Zod schemas
• Handles non-UUID task IDs by generating deterministic replacements

Development

# Install dependencies
pnpm install

# Run all unit tests
pnpm vitest run tests/unit/

# Run integration tests
pnpm vitest run tests/integration/

# Type check
pnpm tsc --noEmit

# Build
pnpm build

Test Structure

tests/
├── unit/           # 40 test files, 380+ tests
│   ├── autonomy-classifier.test.ts
│   ├── backoff.test.ts
│   ├── command-safety.test.ts
│   ├── config-loader.test.ts
│   ├── config-revalidation.test.ts
│   ├── context-lazy.test.ts
│   ├── contract-validator.test.ts
│   ├── coordinator-tiers.test.ts
│   ├── crash-recovery.test.ts
│   ├── cli-commands.test.ts
│   ├── event-bus.test.ts
│   ├── event-bus-depth.test.ts
│   ├── failure-classifier.test.ts
│   ├── failure-patterns.test.ts
│   ├── fix-loop-signatures.test.ts
│   ├── fix-loop.test.ts
│   ├── git-safety.test.ts
│   ├── lifecycle.test.ts
│   ├── metrics-persistence.test.ts
│   ├── migration.test.ts
│   ├── path-safety.test.ts
│   ├── persona-context-builder.test.ts
│   ├── plugin-manifest.test.ts
│   ├── plugin-registry.test.ts
│   ├── policy-engine.test.ts
│   ├── process-tracker.test.ts
│   ├── redact.test.ts
│   ├── semaphore.test.ts
│   ├── skills-loader.test.ts
│   ├── skills-selector.test.ts
│   ├── spawn-failure-paths.test.ts
│   ├── squad-coordinator.test.ts
│   ├── squad-dag.test.ts
│   ├── state-hmac.test.ts
│   ├── state-machine.test.ts
│   ├── task-analyzer-complexity.test.ts
│   ├── task-analyzer.test.ts
│   ├── task-summary-plugin.test.ts
│   ├── verification-gate-min.test.ts
│   └── verification-matrix.test.ts
└── integration/
    └── task-lifecycle.test.ts

License

MIT