🏭 Claude Lane Stack

A small AI coding factory for one person · v1.6.0

Multi-agent orchestration for Claude Code — you talk to one AI project manager, it runs durable AGY or Grok work through acceptance, merges finished code to main, and sends independent review/fixes through the night shift. No five chats. No manual merges.

🌍 README: Русский · 简体中文 · 日本語 · Español · Deutsch · Français · 한국어 · Português 🐣 Beginner guide: EN · RU · 中文 · 日本語 · ES · DE · FR · KO · PT

• Why this exists · Who it's for · How it works
• Quick start · Onboard 2.0 · Lanes that finish · Progressive accept
• Task cards · You never merge
• Cheat sheet · Profiles · FAQ · Docs

Working with AI coding tools usually looks like this: five chat windows, copy-pasted snippets, branches you merge by hand at midnight, and no one checking anyone's work.

Claude Lane Stack turns that into a conveyor:

No task database. No required cloud service. Plain files + plain git — everything is inspectable in your repo.

• 🧑‍💻 Solo developers who want an agentic coding workflow — parallel AI agents without chat chaos
• 🚀 Indie hackers who'd rather describe features than babysit branches
• 🧠 Vibe-coders — you know what you want; the factory handles how
• 🏢 A one-person agency running several client repos with the same discipline

You talk to one agent — dev-orchestrator, the project manager. It routes work across lanes:

flowchart LR
    subgraph you ["🧑 You"]
        A["Plain language:<br/>«add dark mode»"]
    end
    subgraph pm ["🤖 PM — dev-orchestrator"]
        B["Plan → task cards<br/>.agents/runs/"]
    end
    subgraph lanes ["👷 Worker lanes (optional)"]
        D["🔧 AGY / Grok — heavy writes"]
        E["🌙 Codex — night review"]
    end
    A --> B
    B --> D
    D -->|exact checks| F[("📦 main")]
    F -.-> E
    E -.->|typed findings / writer fixes| B

Language policy: durable files (contracts, CLAUDE, reports, docs) are English. Chat with the human may be Russian (or your language) — the PM translates. See docs/LANGUAGE.md.

Models (Codex): GPT-5.6 only — Sol (review / deep / high-risk), Terra (scoped write / docs), Luna (trivia only). No 5.5. See docs/ROUTING.md.

# 1️⃣  Install the stack — once per computer
git clone https://github.com/VKirill/claude-lane-stack.git
cd claude-lane-stack && git checkout v1.6.0 # or: main
./install.sh
export PATH="$HOME/.agents/bin:$PATH" # or open a new terminal

# 2️⃣  In YOUR project — detect available workers, once per repo
cd /path/to/your-project
agents-doctor --apply .

# 3️⃣  Start the PM and talk normally
claude --agent dev-orchestrator

Then in chat:

📖 Walkthrough: docs/BEGINNER.md · Release notes: v1.6.0

First-time setup is not a thin stub. project-onboard + Codex build a real passport.

project-onboard . # auto scenario + depth
project-onboard . --deep # force forensic
project-onboard . --minimal --fast

Writes:

• .agents/onboard.scenario.yaml — scenario + depth + score
• .agents/runs/_onboard/artifacts/001/deep-scan.md — evidence pack for Codex
• Prefer pointers to existing wiki (gotchas.md) over UPPERCASE duplicates

Full guide: docs/ONBOARD-SCENARIOS.md

Claude Code kills foreground Bash around ~2 minutes. That is a host limit, not lane-exec.

Long AGY/Grok jobs start through the typed control plane. AGY 3.6 is the default; choose Grok explicitly with --provider grok:

RUN_DIR="$(run-init "$(pwd)" "$SLUG" --score 7)"
run-validate --run-dir "$RUN_DIR" --phase pre-dispatch
run-controller start --run-dir "$RUN_DIR" --project-cwd "$PROJECT_CWD" --provider grok
run-controller watch --run-dir "$RUN_DIR" --timeout 240
run-controller status --run-dir "$RUN_DIR" --json

One read-only run-supervisor visibly watches the durable controller until the run is accepted or blocked. lane-supervisor remains a one-action diagnostic profile. Verification has a separate default 2/max 10 pool. Details: docs/LANE-EXEC.md

AGY and Grok no longer relearn the repository on every task in a run. The first task creates a conversation; later related tasks resume it. A busy conversation is never shared concurrently—parallel tasks lease another slot (five by default, configurable from one to ten). Sessions rotate after seven successful tasks by default, on failure, or when the worktree/model changes. Codex review stays independent and does not reuse writer context. For a sanitized model/catalog/quota/auth/transport availability failure, the controller records a 30-second retry deadline, replays the exact selected request once, then may use one fixed gpt-5.6-sol + high writer attempt. It still requires the same report digest, ownership, verification, and acceptance receipts; this is recovery, not silent model substitution or daytime review.

The unattended path is a receipt-driven review and repair loop:

night-shift /path/to/project          # one repository
night-shift-all --jobs 2              # active repositories, bounded 1–10

Codex uses the installed night-review profile: gpt-5.6-sol, xhigh, read-only, approval never. It reviews bounded diff chunks and stores every concrete or systemic issue under .agents/findings/<fingerprint>.json; daily REVIEW, OPEN, and TODO files are projections. The selected AGY/Grok repair writer runs without subagents in an isolated worktree. If two primary attempts end in a classified model/catalog/quota/auth/transport availability failure, the runner may use the same single fixed Codex Sol high recovery attempt as the daytime controller. A finding closes only after registered verification, ownership checks, a fresh Codex xhigh re-review, and acceptance.json.

Night merge/push is disabled unless the project opts in:

# .agents/night-shift.yaml
auto_merge: false
verification_executables: [] # optional project-specific executable basenames

Unsafe generated shell commands become needs_human; they are never executed. Schema-v2 verification is also enforced by lane-ctl itself: the allowlist is snapshotted at start and the parsed argv runs directly without a shell.

Multi-task runs no longer wait for the slowest concurrent lane before accepting finished ones.

1. Source-read-only run-supervisor starts one durable controller and stays visible through bounded watches.
2. The detached controller releases lane-bg → lane-exec → lane-session → provider tasks from the DAG.
3. Complete report → ownership check → independent verification → acceptance; AGY/Grok retries once, then only eligible availability failures may use one Codex Sol high fallback.
4. acceptance.json is written immediately; the next ready task fills the free slot (provider default 5/max 10).

Claude uses one visible supervisor per run, not one agent per provider. The deterministic controller survives if that Claude task or session exits. There is no daytime LLM review; the typed night shift remains separate. See docs/LANE-EXEC.md · skills/orchestrator-lanes.

Every job is a small YAML contract in .agents/runs/ — created by the PM, obeyed by workers (English):

schema_version: 2
id: "001"
title: Add dark mode
risk: low
lane: grok             # default writer; agy remains supported
project_cwd: /absolute/path/to/worktree
read_first: [AGENTS.md]
interfaces: ["ThemeToggle(settings)"]
invariants: ["Existing light theme remains the default"]
out_of_scope: ["Server-side account preferences"]
expected_outputs: ["Persistent accessible theme toggle"]
objective: Dark theme toggle on the settings page
owns_paths: # 🔒 the ONLY files this worker may touch
  - src/settings/**
  - src/theme.css
never_touch:
  - .env*
depends_on: []
acceptance:
  - Theme choice persists across reloads
verify: tests
verification:
  - command: npm test
    cwd: /absolute/path/to/worktree
    timeout_sec: 600

• 🔒 owns_paths — parallel workers can't collide: check-owns-paths fails the task if a worker strays
• ✅ verify — merge is blocked until checks pass
• 📜 Cards stay in git history — audit trail of what every agent did

Details: docs/FILE-CONTRACT.md

The end of every successful job is the same: verified code lands on main, merged by the orchestrator via wt-merge-main after exact acceptance checks. Independent review and repair run at night. Workers build in isolated git worktrees.

Rules: docs/SOLO-ORCHESTRATION.md

agents-doctor detects both writer CLIs. It prefers AGY when both are healthy; use --writer-provider grok to select Grok for a project.

agents-doctor # report
agents-doctor --apply . # save into project

More: profiles/README.md · docs/ROUTING.md

claude-lane-stack/
├── agents/ # claude PM + agy/grok/codex lanes (implementers, onboard, review)
├── bin/ # agents-doctor, project-onboard, lane-ctl, lane-bg, lane-exec, lane-session,
│ # wt-*, run-board, docs-maintain-*, …
├── skills/ # orchestration, contracts, memory, onboard,, …
├── profiles/ # full → claude-only
├── hooks/ # shell guard, code-quality, session ledger
├── templates/ # ARCHITECTURE, GOTCHAS, TESTING, deployment, README anamnesis, …
├── docs/ # beginner + deep dives (table below)
└── install.sh # → ~/.agents

Inside your project after onboard:

your-app/
├── CLAUDE.md # always-on rules (≤200 lines body)
├── AGENTS.md # pointer → CLAUDE.md
├── PROGRESS.md / LESSONS.md # living memory
├── .agents/
│ ├── onboard.scenario.yaml # scenario + depth + score
│ ├── routing.profile.yaml # agents-doctor
│ └── runs/ # 🏭 factory floor
└── docs/ # architecture, gotchas, deployment, plans/…

MIT — LICENSE. Use it, fork it, build your own factory.