Knowledge Base

What is LaneConductor?

LaneConductor is a professional-grade orchestrator designed to manage AI agents (like Claude or Gemini) as they work through complex software engineering tasks. Unlike simple chat interfaces, LaneConductor provides a **persistent, file-based state machine** that coordinates multiple agents across multiple repositories.

Figure 1: High-level architecture of the LaneConductor ecosystem.

It acts as the "connective tissue" between your local development environment and the AI agent, providing visibility, guardrails, and automated verification for every change the agent makes.

The Conductor Pattern

The core philosophy of LaneConductor is based on the Conductor Pattern. In this model, the AI agent is not just a chatbot, but a worker moving through a series of discrete "Lanes" (phases of development).

Each Lane represents a specific level of commitment and verification:

Figure 2: The standard track lifecycle and automation flow.

• Backlog: Ideas and requested features.
• Plan: The agent drafts a technical specification (spec.md) for human approval.
• Implement: The agent is actively writing code and performing internal iterations.
• Review: The work is staged for human or peer-AI review.
• Quality Gate: Automated verification (tests, linting, builds) is executed.
• Done: The feature is merged and the track is closed.

Installation

LaneConductor is designed to be lightweight and sovereign. It runs entirely on your hardware.

Global Setup

First, clone the core orchestrator and register the lc command.

git clone https://github.com/meller/laneconductor.git
cd laneconductor
make install

Project Setup

Navigate to any repo you want to track. LaneConductor needs to be initialized in each repository.

cd ~/Code/my-awesome-app
                lc install  # Installs local deps like chokidar
                lc setup    # Scaffolds conductor/ directory

After initializing with the CLI, use any AI Agent (Claude or Gemini) to generate your AI context files automatically:

# In Claude Code
/laneconductor setup scaffold

# In Gemini CLI
Prompt with instructions from .claude/skills/laneconductor/SKILL.md

Use as a Pure Claude Skill — Default Configuration

Claude is the default and recommended primary agent for LaneConductor. While the CLI handles infrastructure, the /laneconductor skill provides Claude Code with the instructions and tools it needs to operate autonomously. This is the most stable and well-tested configuration.

How to Invoke

Once you've run lc setup, the skill is automatically symlinked into your project's .claude/skills/. You can then use it directly in your chat:

/laneconductor implement 101

Pure Skill Workflow

In this mode, Claude uses its internal "System Prompt" (defined in SKILL.md) to:

• Understand the **Conductor Workflow**.
• Read/Write to the **Filesystem Bus** (conductor/tracks/).
• Perform **Bidirectional Sync** with the local database.
• Coordinate with other agents through shared Markdown state.

The Setup Scaffold Process

The /laneconductor setup scaffold command is the fastest way to give an AI agent context about your project. It uses AI reasoning to scan your codebase and generate documentation.

What happens during Scaffold?

1. Codebase Scan: The agent reads your package.json, README.md, source directories, and configuration files (ESLint, Prettier, etc.).
2. Inference: It infers the project's purpose, tech stack, and coding standards.
3. File Generation: It automatically scaffolds the conductor/ directory:
   • product.md: Business logic and high-level goals.
   • tech-stack.md: Frameworks, libraries, and architectural patterns.
   • workflow.md: Human-readable development process.
   • code_styleguides/: Detailed rules inferred from your config files.
4. Skill Linking: It ensures the LaneConductor skill is symlinked so it can be used locally.

LLM Configuration

LaneConductor allows you to define which AI agents and models are used for specific tasks, providing a robust fallback system.

Primary vs. Secondary LLMs

Configured during lc setup or manually in .laneconductor.json, you can specify:

• Primary Agent: The default worker. (Default: claude using haiku). Claude is the most thoroughly tested and recommended configuration.
• Secondary Agent: Experimental: A fallback worker used if the primary hits rate limits or specific task failures. (Default: gemini using latest). This feature is still under active development and may have compatibility issues.

Workflow Overrides

In conductor/workflow.json, you can override models for specific lanes. For example, you might use a faster model for planning and a more powerful one for implementation:

{
  "lanes": {
    "plan": { "model": "haiku" },
    "implement": { "model": "sonnet" }
  }
}

Operating Modes

One of LaneConductor's greatest strengths is its flexibility. You can switch modes based on your environment.

1. Local FS (Headless)

The simplest mode. Everything is stored in Markdown files. There is no database or API server. This is perfect for air-gapped environments or CI/CD pipelines where you want a clean audit trail without infrastructure overhead.

2. Local API (Dashboard)

The standard developer experience. A background worker syncs your files to a local Postgres database, and a Vite-powered dashboard provides a real-time Kanban view of all your projects.

3. Remote API (Team)

For teams. Local workers sync to a shared remote collector. This allows project managers and teammates to see agent progress across the entire organization in a unified view.

Project Status & Verified Environment

LaneConductor is in rapid active development. To ensure a stable experience, we recommend using the following verified configurations:

• Operating Systems: Ubuntu (Linux) and Windows Subsystem for Linux (WSL2).
• Verified AI APIs: Claude CLI (claude) and Gemini CLI (npx @google/gemini-cli).
• Core Mode: local-api (Local Postgres + Vite UI) is the primary tested pathway for daily development.

Other environments (macOS, direct Windows) and mode combinations are currently under development.

Operational Safety & Best Practices

Working with AI agents requires a balance between automation and oversight. We've identified two primary patterns of operation:

The Hallucination Factor

LaneConductor supports a "Full Loop" mode where the agent can automatically move from Plan → Implement → Review. However, this mode carries a higher risk of LLM Hallucinations.

Due to current LLM limitations, an agent might occasionally "think" it has completed a task, updated a file, or passed a test when it hasn't actually performed the action. This can lead to a state drift between the track documentation and the actual codebase.

Bidirectional Sync & Track Status

LaneConductor solves the "source of truth" problem with a deterministic sync loop. It bridges the gap between the Filesystem (where agents work) and the API/UI (where humans coordinate).

The Sync Process

The heartbeat worker (managed by lc start) continuously monitors your conductor/tracks/ directory and syncs track status in both directions:

• Filesystem → Database: When Claude or a human updates a track's index.md, the worker detects the change and updates the database within seconds.
• Database → Filesystem: When you move a card on the Kanban dashboard, the UI writes a signal that the worker detects and updates the corresponding Markdown file.

Sync Strategy: "Newer Wins"

The sync strategy is "Newer Wins". If you edit a Markdown file on disk, the UI updates within 5 seconds. If you move a card on the Kanban board, the UI writes a signal to the filesystem that the agent picks up instantly. This ensures real-time coordination between agents and humans.

Worker Modes

The heartbeat worker operates in two modes:

• Sync-Only (Default): lc start runs the worker in sync-only mode by default. It performs filesystem ↔ database synchronization only, without polling the task queue for automated execution. This is the safe, recommended mode for most workflows.
• Sync-and-Work: lc start --sync-and-work enables full automation. The worker will also poll the queue and automatically execute tracks based on your workflow configuration. Use this for highly repetitive, well-tested tasks.

Filesystem Bus

The Filesystem Bus is the primary communication channel for LaneConductor. Instead of complex API calls, orchestration is handled by reading and writing to standardized Markdown files in your repository's conductor/ directory.

Figure 3: The 'conductor/' directory serves as the stateful Filesystem Bus.

This approach ensures that your project's technical context, workflow, and track states are always part of your version control (Git), enabling full traceability and "headless" operation without any database connectivity.

Track Lifecycle

Every piece of work is a Track. A track is a folder containing its own history, specs, and state.

Anatomy of a Track

Located in conductor/tracks/TRK-ID/, a track typically contains:

• index.md: The main state file (Title, Description, Status, Progress).
• spec.md: The technical plan and architectural decisions.
• plan.md: The step-by-step execution phases.
• test.md: Verification criteria and test plans, driving our context and test-driven approach.
• conversation.md: The full history of comments between the human and the agent.
• quality-gate.md: Track-specific quality criteria and verification results.

State Transitions

Tracks move through the workflow based on the conductor/workflow.json configuration. Transitions can be triggered by the CLI, the UI, or the Agent itself through lc pulse.

Quality Gates

The Quality Gate lane is where trust is established. LaneConductor runs your project's existing verification tools before allowing a track to reach "Done".

Configuration is handled in conductor/quality-gate.md using a simple checklist format that the agent or human can execute.

# Quality Gate Checklist
- [ ] Syntax: `npm run lint`
- [ ] Logic: `npm test`
- [ ] Security: `npm audit`

CLI Reference: General

CLI Reference: Track Management

Configuration

LaneConductor is highly configurable. The two main control files are:

1. .laneconductor.json

Stores project-specific settings like the Project ID, mode, and visibility.

2. conductor/workflow.json

Defines the state machine behavior. You can set parallel execution limits per lane, model overrides, and custom success/failure transitions.

{
  "lanes": {
    "implement": {
      "parallel_limit": 1,
      "max_retries": 3,
      "on_success": "review:queue"
    }
  }
}

Secret Management

LaneConductor follows a strict pattern: no secrets in source code, no secrets in git history. All credentials are stored in GCP Secret Manager and pulled locally on demand via ADC.

The Pattern

Every sensitive value lives in exactly one place: GCP Secret Manager. Local .env files are generated from Secret Manager at dev-time and are always gitignored. Example files with placeholders are committed instead.

Repository (public)          GCP Secret Manager (private)
─────────────────────        ────────────────────────────
.env.example            ←──  CLOUD_DB_PASSWORD
.firebaserc.example     ←──  CLOUD_DB_HOST / CLOUD_DB_USER
.laneconductor.json     ←──  VITE_FIREBASE_API_KEY
  .example                   VITE_FIREBASE_PROJECT_ID
                             GCP_PROJECT_ID
                             ... (all runtime secrets)

Bootstrapping a New Machine

After cloning, a single script pulls everything from Secret Manager and writes the local env files:

gcloud auth application-default login
./scripts/load-env.sh

This writes .env and ui/.env.remote — both gitignored. Access is controlled by GCP IAM: only accounts granted the Secret Manager Secret Accessor role can run the script successfully.

Cloud Functions

Firebase Cloud Functions read secrets at runtime via defineSecret() from firebase-functions/params. Secrets are declared in the function export and injected by Firebase — never hardcoded or passed as environment variables in deployment config:

const dbPassword = defineSecret("CLOUD_DB_PASSWORD");
const dbHost     = defineSecret("CLOUD_DB_HOST");
const dbUser     = defineSecret("CLOUD_DB_USER");

export const api = onRequest({ secrets: [dbPassword, dbHost, dbUser] }, app);

Deploy Scripts

The production migration script (scripts/migrate-prod.sh) fetches all credentials from Secret Manager at runtime — no values are hardcoded:

DB_HOST=$(gcloud secrets versions access latest --secret="CLOUD_DB_HOST" --project="$GCP_PROJECT_ID")
DB_USER=$(gcloud secrets versions access latest --secret="CLOUD_DB_USER" --project="$GCP_PROJECT_ID")
DB_PASSWORD=$(gcloud secrets versions access latest --secret="CLOUD_DB_PASSWORD" --project="$GCP_PROJECT_ID")

What to Gitignore

The following files are always gitignored. Each has a corresponding .example file committed in its place:

Guard Patterns

The .gitignore includes glob guards to prevent accidentally re-adding debug scripts:

tmp_*.mjs
check_*.mjs
fix_*.mjs
reset_*.mjs