<p>Disinto runs a continuous loop: <strong>vision defines direction</strong>, agents derive work and execute it, results feed back into the next cycle.</p>
<spanclass="arrow">v</span><spanclass="arrow">+--></span> CI re-runs <spanclass="arrow">--></span> review again
<spanclass="agent-name">planner</span> sees progress, plans next cycle
</pre>
</div>
<p>Each project processes <strong>one issue at a time</strong>. No concurrent PRs, no merge conflicts, no context switching. The pipeline is deliberately sequential.</p>
<divclass="role">Picks up backlog issues, <strong>implements code</strong> in isolated git worktrees, opens PRs. Runs as a persistent tmux session.</div>
<divclass="trigger">Cron: every 5 min</div>
</div>
<divclass="agent-card">
<divclass="name">review-agent</div>
<divclass="role"><strong>Reviews PRs</strong> against project conventions. Approves clean PRs, requests specific changes on others.</div>
<divclass="trigger">Cron: every 5 min</div>
</div>
<divclass="agent-card">
<divclass="name">planner</div>
<divclass="role">Reads VISION.md and repo state. <strong>Creates issues</strong> for gaps between where the project is and where it should be.</div>
<divclass="trigger">Cron: weekly</div>
</div>
<divclass="agent-card">
<divclass="name">gardener</div>
<divclass="role"><strong>Grooms the backlog.</strong> Closes duplicates, promotes tech-debt issues, ensures issues are well-structured.</div>
<divclass="role">Executes <strong>operational tasks</strong> defined as formulas — site deployments, data migrations, any multi-step procedure.</div>
<divclass="trigger">Cron: every 5 min</div>
</div>
<divclass="agent-card">
<divclass="name">vault</div>
<divclass="role"><strong>Safety gate.</strong> Reviews dangerous actions before they execute. Auto-approves safe operations, escalates risky ones to a human.</div>
<divclass="trigger">Event-driven</div>
</div>
</div>
</div>
<!-- Phase Protocol -->
<divclass="section">
<h2>Phase protocol</h2>
<p>When the dev-agent runs in a persistent tmux session, it signals progress by writing to a <strong>phase file</strong>. The orchestrator watches this file and injects events (CI results, review feedback) back into the session.</p>
<p>Phase files live at <code>/tmp/dev-session-{project}-{issue}.phase</code>. The protocol is intentionally simple — a plain text file, one line, no daemons.</p>
</div>
<!-- Vault -->
<divclass="section">
<h2>Vault — quality gate</h2>
<divclass="concept">
<divclass="label">How it works</div>
<p>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.</p>
<p><strong>Auto-approve</strong>— safe, well-understood operations pass through instantly. <strong>Escalate</strong>— risky or novel operations get sent to a human via Matrix. <strong>Reject</strong>— clearly unsafe actions are blocked.</p>
<p>You define the boundaries. The vault enforces them. This is what lets you sleep while the factory runs.</p>
</div>
</div>
<!-- Planner + Predictor -->
<divclass="section">
<h2>Planner + predictor feedback cycle</h2>
<divclass="concept">
<divclass="label">Closing the loop</div>
<p>The <strong>planner</strong> 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.</p>
<p>The <strong>predictor</strong> 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.</p>
<p>Together, they create a feedback cycle: <strong>the predictor observes, the planner directs, and the dev-agent executes.</strong></p>
</div>
</div>
<!-- Infrastructure -->
<divclass="section">
<h2>Infrastructure</h2>
<p>Disinto is deliberately minimal. No Kubernetes, no message queues, no microservices.</p>
<divclass="concept">
<divclass="label">Tech stack</div>
<p><strong>Bash scripts</strong>— every agent is a shell script. No compiled binaries, no runtimes to install.</p>
<p><strong>Claude CLI</strong>— AI is invoked via <code>claude -p</code> (one-shot) or <code>claude</code> (persistent tmux sessions).</p>
<p><strong>Cron</strong>— agents are triggered by cron jobs, not a daemon. Pull-based, not push-based.</p>
<p><strong>Single VPS</strong>— runs on an 8 GB server. Flat cost, no scaling surprises.</p>
</div>
</div>
<!-- Design Principles -->
<divclass="section">
<h2>Design principles</h2>
<divclass="principles">
<divclass="principle">
<divclass="id">AD-001</div>
<divclass="text"><strong>Nervous system runs from cron, not action issues.</strong> Planner, predictor, gardener, supervisor run directly. They create work, they don't become work.</div>
</div>
<divclass="principle">
<divclass="id">AD-002</div>
<divclass="text"><strong>Single-threaded pipeline per project.</strong> One dev issue at a time. No new work while a PR awaits CI or review.</div>
</div>
<divclass="principle">
<divclass="id">AD-003</div>
<divclass="text"><strong>The runtime creates and destroys, the formula preserves.</strong> Runtime manages worktrees/sessions/temp. Formulas commit knowledge to git before signaling done.</div>
</div>
<divclass="principle">
<divclass="id">AD-004</div>
<divclass="text"><strong>Event-driven > polling > fixed delays.</strong> Never hardcoded sleep. Use phase files, webhooks, or poll loops with backoff.</div>
</div>
<divclass="principle">
<divclass="id">AD-005</div>
<divclass="text"><strong>Secrets via env var indirection, never in issue bodies.</strong> Issue bodies become code. Secrets go in <code>.env</code> or TOML project files.</div>
