AIF Handoff: autonomous agent for code development

# Autonomous Development Agent: How AIF Handoff Replaces Manual Workflows

Created a task in the interface, closed your laptop—a few minutes later, a Telegram notification arrives about the ready PR. This isn't science fiction, but reality powered by AIF Handoff: a system of autonomous agents built on top of AI Factory and compatible with any LLM tools like Claude Code or Cursor. At its core: context management, iterative planning, and self-learning based on patches.

Why Classic "Vibe-Coding" Doesn't Scale

Most developers go through three stages of interacting with LLMs:

• Lottery—one prompt, hoping for luck. The model generates plausible but non-working code because it lacks project context. Every query starts from scratch, with no history of prior decisions.
• "Grandma's Prompts"—instructions like "you're a senior dev with 15 years of experience." They change the response tone but not its quality. The model fakes confidence, not competence.
• Manual Workflow—you assemble the context yourself: copy files, specify constraints, run commands one by one. Results improve, but the process stays labor-intensive and error-prone due to missed context.

Key insight: LLMs can't read minds. They only work with what you provide. The more precise and complete the context, the more predictable the output. Example:

Bad:

Implement JWT auth using best practices

Good:

Here's AuthService (code), here's how sessions are stored (code), here's middleware (code).
Need to add refresh token. Use Laravel Sanctum, no changes allowed.
Here's the test that must pass.

In the second case, the model's room for imagination is minimized. Success is measured by concrete criteria, not vague "best practices."

How AI Factory Systematizes Context

AI Factory is a CLI tool and skills ecosystem that automatically manages context for any coding agent. After installation (npm install -g ai-factory && ai-factory init), it scans the project, identifies the stack, and creates the structure:

your-project/
├── .claude/
│   └── skills/           ← markdown files with agent instructions
├── .ai-factory/
│   ├── DESCRIPTION.md    ← project description, stack, architecture
│   ├── PLAN.md           ← current plan
│   ├── patches/          ← self-learning patches
│   └── evolutions/       ← skill evolution logs
└── .ai-factory.json

Skills aren't generic advice—they're specific instructions: "how exactly to create a plan in this project," "which files to touch for auth changes." Key commands:

• /aif—initialize session context
• /aif-plan—create plan and git branch
• /aif-implement—execute tasks with checkpoint commits
• /aif-fix—fix bug + create self-learning patch
• /aif-evolve—analyze patches and update skills
• /aif-verify—check result against plan

Self-learning happens continuously: every /aif-fix saves a patch, and /aif-evolve finds patterns in them to adapt skills. Before each /aif-implement, the agent reads all accumulated patches—the system learns even without explicit evolve calls.

AIF Handoff: Human on the Loop, Not in the Loop

AI Factory solves context issues but still requires manual command launches. AIF Handoff removes this final barrier—it's a web app with a Kanban board that fully automates the agent pipeline:

Backlog → Planning → Plan Ready → Implementing → Review → Done

You create a task in the UI—the system moves it through statuses via WebSocket. Inside, specialized coordinators handle the work:

• plan-coordinator—not just generates a plan but iteratively refines it via plan-polisher until quality criteria are met.
• implement-coordinator—analyzes task dependencies and launches parallel workers in separate git worktrees where safe.
• review-sidecar + security-sidecar—concurrently check code against the plan and for vulnerabilities (XSS, SQL injections, data leaks). With MCP Playwright, they run browser tests.

If review finds issues, the task auto-retries—but with a strict iteration limit to avoid burning through your entire token budget overnight.

Human-on-the-Loop ≠ Human-in-the-Loop

• Human-in-the-loop: you intervene at every step. Max control, min speed.
• Human-on-the-loop: you set the task and criteria—the system runs autonomously. You approve or reject the final result. That's how Handoff works.

Two execution modes:

• Subagents (default)—full pipeline with iterative refinement, parallel workers, and quality sidecars. Higher quality, higher cost.
• Skills—single-pass execution via core AI Factory commands. Faster and cheaper, ideal for simple tasks.

Setup and Bidirectional Sync

Launch Handoff:

git clone https://github.com/lee-to/aif-handoff
cd aif-handoff
npm install
npm run init
npm run dev

Or via Docker (recommended):

docker compose up

It spins up three services: API (Hono + WebSocket), Web (React UI), and Agent (coordinator). First run requires Claude Code OAuth. Config in .env:

AI_LANGUAGE=ru                  # agent language
MAX_REVIEW_ITERATIONS=3         # review iteration limit
AGENT_USE_SUBAGENTS=true        # execution mode
TELEGRAM_BOT_TOKEN=...          # for notifications
TELEGRAM_CHAT_ID=...

Handoff and AI Factory sync bidirectionally via MCP. Start a task in Handoff, switch to direct Claude Code work—changes reflect on the Kanban board automatically. Any MCP-compatible agent can join.

How It Differs from Paperclip and Other Features

Paperclip orchestrates agents for marketing, content, SEO. It handles text and info flows. AIF Handoff is built for development: it knows your stack, verifies code (not text), uses git worktrees for worker isolation, and learns from project-specific patches.

Key Points:

• Context > prompts. More specific inputs = more stable outputs.
• Self-learning via patches (/aif-fix → /aif-evolve)—key to project adaptation.
• Human-on-the-loop delegates routine work while keeping final control.
• Parallel workers and iterative review boost quality but need token limits.
• Bidirectional sync lets you switch freely between Handoff and direct agent work.

Tech stack: Node.js + TypeScript (Turborepo), SQLite (drizzle-orm), Hono API, React + TailwindCSS, node-cron. >70% test coverage, ESLint guards for layer protection. Roadmap: JetBrains plugin and CI/CD integration.

— Editorial Team