conductor
structured agent workflow · for any project
conductor
Agents
forget.
conductor
State lives in files, not in the model.
Without conductor
With conductor
conductor
The Conductor loop.
Every session does three things: read, execute, hand off.
No state lives in the agent's memory. Everything the next session needs is in the files — the intent, the queue, the active slice, and the last handoff.
conductor
A slice is the atomic unit of work.
# conductor/slice-04-promotions-view.md objective: Add fct_promotions view and a 9th explore to the gold_marts model. out_of_scope: - field enrichment (slice-05) - backfill logic - join configuration acceptance: - [ ] view file generated - [ ] dimensions match schema 1:1 - [ ] count measure present - [ ] explore added to model - [ ] python3 scripts/validate.py passes gate: python3 scripts/validate.py status: active
Bounded scope.
One commit or PR. Completable in a single agent session.
Out-of-scope is explicit.
Scope drift is the default failure mode. Every slice names what it isn't.
Acceptance criteria are checkboxes.
Not "looks good" — measurable. The agent ticks them off as it goes.
Validation is the gate.
No handoff is written until validate.py passes. The validator is non-optional.
conductor
Drop into any repo. Fill intent.md.
Twelve files. No service.
The entire workflow runs from the filesystem. No hosted backend, no database, no API. Lives in your repo, ships with your commits.
Drop-in adaptation.
Everything below conductor/ is identical regardless of domain — LookML, REST API, dbt pipeline, frontend app. The format doesn't change.
One sentence to start.
"Read AGENTS.md and execute the active slice."
conductor
Built on a Google pattern. Extended for the loop.
Google Conductor
conductor/as filesystem context store- Tracks with
spec.md,plan.md,metadata.json - Slash commands for session-independent context
- The "filesystem-as-state" idea traces further back to Anthropic's CLAUDE.md convention
aug-conductor-wrkflw
- Slice-based execution replaces single spec+plan
- Exact Next Steps replaces open-ended proposals
- Multi-agent — Codex / Claude / Gemini, one scaffold
- validate.py governance gate · stdlib only
- Cross-repo tracks coordinate without merging codebases
- Zero external dependencies — no hosted service, no database
conductor
Real repos. Real numbers.
Three repos. Three stacks. One Conductor scaffold governing all of them — same slice format, same handoff loop, same validator. Different codebases, same workflow.
conductor
Bootstrap a project from zero session context.
Orient.
Agent reads project/AGENTS.md → intent.md → conductor/index.md → active slice spec. That's it.
Branch.
Cuts feat/slice-01-lookml-bootstrap from main. Every commit lands on this branch.
Generate.
Reads 8 table schemas from demo/schema/gold_marts.md. Writes 8 .view.lkml files — one commit per view.
Model.
Generates models/gold_marts.model.lkml with 8 explores. No joins — facts are independently aggregated.
Validate & hand off.
Runs python3 scripts/validate.py — required gate. Marks slice stable, advances the queue, writes handoff with Exact Next Steps.
$ git checkout main $ # Prompt: "Read DEMO.md and execute it." ── agent session ────────────────────── reading conductor/index.md reading slice-01-initial-bootstrap.md reading demo/schema/gold_marts.md # 8 tables ✓ generated fct_finance_revenue.view.lkml ✓ generated fct_sales_operations.view.lkml ✓ generated fct_customer_segments.view.lkml ✓ generated fct_product_profitability.view.lkml ✓ generated fct_marketing_attribution.view.lkml ✓ generated fct_shipping_analysis.view.lkml ✓ generated fct_cart_abandonment.view.lkml ✓ generated fct_daily_dashboard.view.lkml ✓ generated models/gold_marts.model.lkml $ python3 scripts/validate.py All checks passed. handoff slice-01 → stable next Exact Next Steps written
conductor
Agent proposes. Operator approves. Agent executes.
A new business requirement arrives. The data team has provisioned fct_promotions. Two phases — one autonomous, one collaborative — both governed by the same spine.
Phase 1 — Autonomous
Phase 2 — Collaborative
## Slice 04 — Promotions View Date: 2026-05-24 Commit: a3f9c21 Status: stable Files Changed + project/views/fct_promotions.view.lkml ~ project/models/gold_marts.model.lkml # 9 explores Validation scripts/validate.py: 12 passed | 0 warnings | 0 failed Exact Next Steps # ← scheduling mechanism 1. Enrich fct_promotions — typed measures (sum for revenue_attributed, cost; average for roas, discount_value) 2. Add dimension_group for start_date, end_date 3. Add value_format_name for financial measures 4. Add group_label for field picker organization 5. Consider hidden: yes on promotion_id Blockers None
conductor
A nightly cron job orients from the spine alone.
0 6 * * 1 · Monday 06:00 · no human present
Cold orient.
Zero session context. Agent reads intent.md, conductor/index.md, latest handoff, and the maintenance slice.
Read-only investigation.
Runs validate.py. Checks the queue. Reads blockers from the last handoff. Does not auto-fix.
Write the status entry.
Records pass/warn/fail counts, queue state, and open blockers. Commits with chore(maintenance):. Exits.
## Maintenance Check — 2026-05-25 Date: 2026-05-25 Commit: 8b2e44a Type: automated-maintenance Status ● clean Validation scripts/validate.py: 12 passed | 0 warnings | 0 failed Queue State Slices: 5 total — 5 STABLE, 0 ACTIVE, 0 QUEUED Open Blockers None Next Run Cron-driven — operator sets schedule. No action required.
conductor
Format and commits verified before every handoff. Diff review closes the loop.
Every handoff passes through scripts/validate.py. Stdlib only · zero deps · CI-safe.
Core checks · domain-agnostic
- Spine structure present (
index.md,handoff-log.md) - Handoff has
Commit:andExact Next Stepssections - Commit hash in handoff exists in git (
git cat-file -e) - All acceptance criteria checked — unchecked items block handoff
- CI workflow stub is present
- Git branch state is sane (no uncommitted spine edits)
Domain extension · demo/scripts/validate_lookml.py
- manifest.lkml + project_name present
- View blocks, dimensions, and at least one measure
- Model file has connection + explore blocks
$ python3 scripts/validate.py ── conductor spine ────────────────── ✓ conductor/index.md present ✓ conductor/handoff-log.md present ✓ handoff has Commit: ✓ handoff has Exact Next Steps ✓ active slice: none — all slices stable ✓ CI workflow stub ✓ Git branch: feat/slice-04-promotions ── lookml extension ───────────────── ✓ manifest.lkml + project_name ✓ 9 view files · all baseline-valid ✓ gold_marts.model.lkml · 9 explores ───────────────────────────────────── All checks passed. 12 passed | 0 warnings | 0 failed
conductor
Run a demo.
Clone the repo, check out a branch, paste one sentence into your agent. Fifteen minutes to see the loop end to end — on your machine, with your CLI of choice.