🏭 Claude Lane Stack

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

Multi-agent orchestration for Claude Code — you talk to one AI project manager, it dispatches optional workers (Grok / Codex), reviews their output and merges finished code to main. No five chats. No manual merges.

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

📌 Table of contents

• 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

💡 Why this exists

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.

👥 Who it's for

• 🧑‍💻 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

[!TIP] Never heard the word "orchestration"? Start with the Beginner guide — it explains everything as a small factory, zero jargon.

🧩 How it works

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["🔧 Grok — heavy writes"]
        E["🔍 Codex — review gate"]
    end
    A --> B
    B --> C & D
    C & D --> E
    E -->|checks passed| F[("📦 main")]
    E -->|issues| 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.

[!NOTE] Only Claude Code is required. Missing workers are fine — agents-doctor detects what's installed and the PM adapts, down to pure claude-only mode.

🚀 Quick start (3 commands)

# 1️⃣  Install the stack — once per computer
git clone https://github.com/VKirill/claude-lane-stack.git
cd claude-lane-stack && git checkout v1.3.1 # 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:

[!IMPORTANT] /resume-project is a "welcome back" command — not an installation step.

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

🧭 Onboard 2.0 — scenario + depth

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

Axis 1 — Scenario (what to seed)

Axis 2 — Depth (how hard Codex digs)

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

🏃 Lanes that finish — background survival

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

Long Grok jobs start through the typed control plane:

lane-ctl start --run-dir "$RUN_DIR" --task-file "$TASK_FILE" --project-cwd "$PROJECT_CWD"
lane-ctl status --run-dir "$RUN_DIR" --task-id "$TASK_ID" --json
lane-ctl verify --run-dir "$RUN_DIR" --task-file "$TASK_FILE" --project-cwd "$PROJECT_CWD"

The read-only lane-supervisor and dev-orchestrator use this pattern. Verification has a separate default 2/max 10 pool. Details: docs/LANE-EXEC.md

Grok no longer relearns 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.

⚡ Event-driven accept — no join-wait

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

1. Source-read-only lane-supervisor calls lane-ctl start and returns immediately.
2. Detached lane-bg → lane-exec → lane-session → grok owns process lifetime.
3. PM reacts to compact lifecycle events, then runs independent verification.
4. Accept now and refill the next ready task (provider default 5/max 10).

Claude does not spend one live subagent per provider process. See docs/LANE-EXEC.md · skills/orchestrator-lanes.

📋 Task cards: how workers stay in their lane

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

task: add-dark-mode
goal: Dark theme toggle on the settings page
owns_paths: # 🔒 the ONLY files this worker may touch
  - src/settings/**
  - src/theme.css
verify:
  - npm test
  - npm run lint
lane: grok             # only write programmer
review: codex-reviewer # who gates the merge

• 🔒 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

📦 You never merge — the PM does

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

[!WARNING] If an agent ever asks you to resolve branches — that's a bug in the flow. Tell the PM: «merging is your job».

Rules: docs/SOLO-ORCHESTRATION.md

🧾 Commands cheat-sheet

You type these

🚦 Capability profiles

agents-doctor writes one of five profiles:

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

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

🧱 What's in the box

claude-lane-stack/
├── agents/ # claude PM + 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/…

❓ FAQ

📚 Documentation map

📜 License

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