---

📌 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:

😩 Five chats	🏭 Lane Stack
You re-explain context to every model	One PM holds context, workers get task cards
Models overwrite each other's files	Each card lists owned paths — workers stay in their lane
Nobody reviews the AI's code	A dedicated review lane (Codex) gates every merge
You merge branches manually	The PM merges to main after checks pass
Next morning: "what were we doing?"	/resume-project — Now / Blocked / Next in seconds
Onboard is a thin CLAUDE stub	Deep forensic passport on mature repos
Long Grok runs die at ~2 min	lane-ctl + user-systemd — detached lifecycle survives host cleanup
Parallel tasks wait for the slowest	Event-driven accept — detached Grok + lifecycle events + separate verify pool

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

Role	Who	What they do
👑 Owner	You	Say what you want (chat may be any language)
🤖 Project manager	Claude Code agent dev-orchestrator	Plans, dispatches, verifies, merges
⚡🔧 Write lanes	, Grok (optional)	Implement task cards (detached via lane-bg)
🔍 Review / write / onboard	Codex (optional)	Review gate, emergency write, project passport
🗂️ Task cards	YAML in .agents/runs/	Factory floor — fully inspectable
📦 Official code	Git branch main	Where every successful job ends

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:

Command	When
/project-onboard	First time on a repo — passport + docs (auto minimal/full + fast/deep)
/project-onboard deep	Force forensic analysis
/resume-project	Cold start after a break — Now / Blocked / Next

[!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)

	🟢 minimal	🟣 full
When	score < 5 (small / greenfield)	score ≥ 5 or multi-package monorepo
Seeds	CLAUDE · AGENTS · ARCHITECTURE · memory · plans	+ GOTCHAS · GLOSSARY · TESTING · deployment · nested apps/*/CLAUDE.md · SECURITY when domain-heavy

Axis 2 — Depth (how hard Codex digs)

	⚡ fast	🔬 deep (default on full)
Explore	top dirs + manifests	entrypoints, top modules, 3–7 flows, wiki↔code, run tests
Model	gpt-5.6-terra high	gpt-5.6-sol high
Report	passport filled	MODULES_READ · FLOWS · WIKI_MISMATCHES · VERIFY

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"

Tool	Role
lane-ctl	typed start/status/events/tail/retry/cancel/verify control plane
lane-bg	low-level transient user-systemd service; explicit nohup fallback
lane-exec	activity-aware idle + absolute max on the detached process
lane-session	resumes run-scoped Grok context; provider default 5/max 10

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

Command / phrase	What it is	When
./install.sh	Install kit into ~/.agents	Once per computer
agents-doctor --apply .	Detect CLIs → routing profile	Once per project
claude --agent dev-orchestrator	The only chat you need	Every session
/project-onboard	Passport via Codex (scenario + depth auto)	First time on a repo
/project-onboard deep	Force forensic onboard	Mature / messy repos
«Add dark mode…»	Work request — any language	Features & fixes
/resume-project	Now / Blocked / Next	After a break
«It's stuck»	PM checks silent workers	Long silence

🤖 Usually only the PM / implementers type these

Command	What it is
run-board	Job scoreboard
lane-session status --run-dir .agents/runs/<slug>	Inspect that run's Grok session pool
wt-create / wt-merge-main	Worktree + merge into main
check-owns-paths	Did the worker stay in its file list?
lane-ctl	Typed detached lifecycle control + independent verify
lane-bg / lane-exec / lane-session	Low-level process lifetime, activity timeouts, and warm provider pool
lane-heartbeat / lane-stall-check	Alive? Silent?
project-onboard	Shell seed + deep-scan (Codex fills)
docs-maintain-project	Nightly/daily docs honesty
project-memory-init	PROGRESS / LESSONS
night-audit	Housekeeping

---

🚦 Capability profiles

agents-doctor writes one of five profiles:

Profile	You have	Write lane	Review lane
full	Grok + Codex	Grok	Codex Sol
claude-			Claude
claude-grok	Grok	Grok	Claude
claude-codex	Codex	Codex Terra/Sol	Codex Sol
claude-only	Claude Code only	Claude subagents	Claude subagents

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

Do I need, Grok and Codex all installed?

No — only Claude Code is required. Everything else is optional. agents-doctor adapts down to claude-only.

How is this different from plain Claude Code?

Plain Claude is one worker in one chat. Lane Stack adds management: task cards with ownership, multi-vendor lanes, independent review, auto-merge to main, deep onboard, cold-start recovery.

My run dies after ~2 minutes — is that lane-exec?

Usually no. Claude kills foreground Bash and may reap ordinary nohup descendants. Current runs start through lane-ctl, while lane-bg uses a transient user-systemd service. See docs/LANE-EXEC.md. After upgrading, start a fresh dev-orchestrator session.

minimal vs full vs deep — which do I pick?

Usually nothing — auto. Toy repo → minimal + fast. Mature monorepo → full + deep. Override with /project-onboard deep or project-onboard . --full --deep.

Does it need a database or cloud service?

No. State is files in your repo (.agents/runs/) + git.

Will it work on my existing project?

Yes. agents-doctor --apply . then /project-onboard. Existing wiki pages are linked, not blindly duplicated (gotchas.md wins over GOTCHAS.md).

Is my code safe?

Each CLI talks only to its own vendor. No extra servers. Don't put secrets in task YAML; use the review lane for auth/pay. SECURITY.md.

---

📚 Documentation map

Topic	Doc
🐣 Plain-language walkthrough	docs/BEGINNER.md
🧭 Onboard scenarios + depth	docs/ONBOARD-SCENARIOS.md
⏱️ Lane timeouts + background	docs/LANE-EXEC.md
🌐 Language policy (EN files / RU chat)	docs/LANGUAGE.md
🔀 Who writes / who reviews (Sol/Terra)	docs/ROUTING.md
⚖️ Comparison with alternatives	docs/COMPARISON.md
🧑‍✈️ Solo rules — you never merge	docs/SOLO-ORCHESTRATION.md
🗂️ Task card YAML	docs/FILE-CONTRACT.md
🛡️ Safety hooks	docs/HOOKS.md
🧠 Project memory	docs/PROJECT-MEMORY.md
📝 Ideas backlog	docs/TODOS.md
🔌 MCP (lean / hybrid)	docs/MCP-LEAN.md · docs/MCP-HYBRID.md
📰 Changelog	CHANGELOG.md
🚀 Release v1.3.1	GitHub Releases
🤝 Contributing	CONTRIBUTING.md
🔐 Security	SECURITY.md

---

📜 License

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

---