# Architecture — Disinto
How Disinto works: agent loop, phase protocol, vault safety gates, and the planner-predictor feedback cycle.

# Architecture

how the factory works
← disinto.ai

## The agent loop

Disinto runs a continuous loop: vision defines direction, agents derive work and execute it, results feed back into the next cycle.

      planner reads VISION.md
         |
         v
      creates backlog issues
         |
         v
      dev-agent picks issue --> implements in worktree --> opens PR
         |
         v
      Woodpecker CI runs tests
         |
         v
      review-agent reviews PR --> approves or requests changes
         |                               |
         v (approved)                     v (changes requested)
      PR merges                       dev-agent addresses feedback
         |                               |
         v                               +--> CI re-runs --> review again
      planner sees progress, plans next cycle

Each project processes one issue at a time. No concurrent PRs, no merge conflicts, no context switching. The pipeline is deliberately sequential.

## Eight agents

Each agent has a single responsibility. They communicate through git, the Codeberg API, and the filesystem.

dev-agent
Picks up backlog issues, implements code in isolated git worktrees, opens PRs. Runs as a persistent tmux session.
Cron: every 5 min
review-agent
Reviews PRs against project conventions. Approves clean PRs, requests specific changes on others.
Cron: every 5 min
planner
Reads VISION.md and repo state. Creates issues for gaps between where the project is and where it should be.
Cron: weekly
gardener
Grooms the backlog. Closes duplicates, promotes tech-debt issues, ensures issues are well-structured.
Cron: every 6 hours
supervisor
Monitors factory health. Kills stale sessions, manages disk/memory, escalates persistent failures.
Cron: every 10 min
predictor
Detects infrastructure patterns — recurring failures, resource trends, emerging issues. Files predictions for triage.
Cron: daily
action-agent
Executes operational tasks defined as formulas — site deployments, data migrations, any multi-step procedure.
Cron: every 5 min
vault
Safety gate. Reviews dangerous actions before they execute. Auto-approves safe operations, escalates risky ones to a human.
Event-driven

## Phase protocol

When the dev-agent runs in a persistent tmux session, it signals progress by writing to a phase file. The orchestrator watches this file and injects events (CI results, review feedback) back into the session.

Phase | Meaning | Next event
--- | --- | ---
awaiting_ci | PR pushed, waiting for CI | Orchestrator injects CI result
awaiting_review | CI passed, waiting for review | Review-agent injects feedback
needs_human | Blocked on a human decision | Matrix notification sent
done | PR merged, work complete | Session cleaned up
failed | Unrecoverable error | Escalated to supervisor

Phase files live at `/tmp/dev-session-{project}-{issue}.phase`. The protocol is intentionally simple — a plain text file, one line, no daemons.

## Vault — quality gate

How it works

The vault sits between agents and dangerous actions. Before an agent can execute a risky operation (force push, deploy, delete), the vault reviews the request.

Auto-approve — safe, well-understood operations pass through instantly. Escalate — risky or novel operations get sent to a human via Matrix. Reject — clearly unsafe actions are blocked.

You define the boundaries. The vault enforces them. This is what lets you sleep while the factory runs.

## Planner + predictor feedback cycle

Closing the loop

The planner runs weekly. It compares the current state of the codebase against VISION.md and creates issues for anything missing. It also triages predictions filed by the predictor.

The predictor runs daily. It analyzes CI logs, git history, and resource metrics to detect patterns — recurring test failures, disk usage trends, code churn hotspots. Predictions are filed as issues for the planner to triage.

Together, they create a feedback cycle: the predictor observes, the planner directs, and the dev-agent executes.

## Infrastructure

Disinto is deliberately minimal. No Kubernetes, no message queues, no microservices.

Tech stack

Bash scripts — every agent is a shell script. No compiled binaries, no runtimes to install.

Claude CLI — AI is invoked via `claude -p` (one-shot) or `claude` (persistent tmux sessions).

Cron — agents are triggered by cron jobs, not a daemon. Pull-based, not push-based.

Codeberg + Woodpecker — git hosting and CI. All state lives in git and the issue tracker. No external databases.

Single VPS — runs on an 8 GB server. Flat cost, no scaling surprises.

## Design principles

AD-001
Nervous system runs from cron, not action issues. Planner, predictor, gardener, supervisor run directly. They create work, they don't become work.
AD-002
Single-threaded pipeline per project. One dev issue at a time. No new work while a PR awaits CI or review.
AD-003
The runtime creates and destroys, the formula preserves. Runtime manages worktrees/sessions/temp. Formulas commit knowledge to git before signaling done.
AD-004
Event-driven > polling > fixed delays. Never hardcoded sleep. Use phase files, webhooks, or poll loops with backoff.
AD-005
Secrets via env var indirection, never in issue bodies. Issue bodies become code. Secrets go in `.env` or TOML project files.

## Directory layout

    disinto/
    ├── dev/           dev-poll.sh, dev-agent.sh, phase-handler.sh
    ├── review/        review-poll.sh, review-pr.sh
    ├── gardener/      gardener-run.sh (cron executor)
    ├── predictor/     predictor-run.sh (daily cron executor)
    ├── planner/       planner-run.sh (weekly cron executor)
    ├── supervisor/    supervisor-run.sh (health monitoring)
    ├── vault/         vault-poll.sh, vault-agent.sh, vault-fire.sh
    ├── action/        action-poll.sh, action-agent.sh
    ├── lib/           env.sh, agent-session.sh, ci-helpers.sh
    ├── projects/      *.toml per-project config
    ├── formulas/      TOML specs for multi-step agent tasks
    ├── bin/           disinto CLI entry point
    └── docs/          internal protocol docs