Konductor - AI Orchestration Workflow

In plain English

Konductor is a document-based AI Orchestration Workflow that manages all your AI Coding Agents. The Konductor is the humanized persona we gave to the master coordinator. It sits on top of the AI Agents and is designed to be self-aware, self-evolving, and remember-everything!

In Technical terms

It is 100% document-based set of guidelines and rules, no-code, Markdown format, and AI-provider agnostic it is to be embedded as part of your codebase and evolve with your project. It is designed to be context-efficient, self-updating. It works with all IDEs and modern-ish JS/TS/Python/PHP/ Go/Rust/Java/C#/C/C++ languages, framework, and tools! Bring-Your-Own-Agents!

In AI Agent terms

Konductor is an AI Boss for AI Agents. The framework guideline and instructions will guide AI agents through the development process, with behavior layer to make sure they are always on the right track. Konductor boss always available in codebase as structured markdown-files, and it remembers all historical decisions made!

Installation & Setup

Let AI Agent do it

Run `npx konductor-workflow@latest`

Or Manually Install the npm package

npx konductor-workflow@latest

(Note: If you installed locally via npm i konductor-workflow, you should run npx konductor-workflow from your repository root to execute the persona initialization.)

This install path now writes the universal skill into .agents/skills/konductor-workflow/ from SKILL.md.

First step in your IDE/Coding Agent

Copy paste this into your favourite IDE workspace (Claude, Antigravity, Cursor, etc.) to initialize the workflow framework:

I have just installed or updated the Konductor framework for this repository. Please review @KONDUCTOR.md and the latest core files. Reorganize any unstructured project documentation into docs/ and .konductor/memory/KONDUCTOR_MEMORY.md, update the scaffolding in docs/PROJECT_SKILLS_WORKFLOW.md to match our specific tasks and repo-local commands, and give me a brief summary of our current status and tech debt so we can safely resume work.

Let it run for a few minutes with your Best thinking model (GPT 5.4 / Opus 4.6 / Claude 4.5 Sonnet / Gemini 3.1 Pro / GLM 5.1 etc) for best accuracy. This will align your project documentation with the Konductor workflow framework, and set up the AI agents to work with the framework. After this, the Konductor persona will be embedded in your project, and you can use it to manage your AI agents.

Konductor now ships an explicit behavior layer too: KONDUCTOR.md holds the compact rules, SKILL.md is the repo source for the universal agent skill, .agents/skills/konductor-workflow/SKILL.md is the installed runtime copy, .konductor/KONDUCTOR_WORKFLOW.md carries the machine contract (reference loop, behavior defaults, communication policy) as structured XML and the full human guide as Markdown below it, and .konductor/memory/AGENT_BEHAVIOR.md gives compact anti-pattern examples for day-to-day coding work.

Example workflows

A typical working session workflow

Human : Where are we? What should we do next? @KONDUCTOR.md
Coding Agents: ...
Human : Ok do #1,2,3 for me
Coding Agents: ...
Human : Check-in your work and deploy @KONDUCTOR.md
Coding Agents: ...

One-command production critical issue fixing

Human : Investigate and fix this error below, and deploy and monitor until done @KONDUCTOR.md [...paste error messages...]
Coding Agents: Investigate -> Fix -> Update Test -> Test -> Check-in -> Commit -> Deploy -> Monitor -> Auto-Fix if needed.

💡 Tag @KONDUCTOR.md at the start of every session, at and/or every new turn request, and/or after a long or distracting response. This acts as a forced memory reload, ensuring the AI strictly adheres to your architectural choices instead of hallucinating standalone logic. The file context is short and toke-efficient, it will save your token usage, not adding more noise to the context.

Power Tips & Beginner Guide

For a full set of workflows, power tips, and everyday cheat codes on how to interact with the Konductor persona as a human developer, please check out the Human's Guide to Konductor.

Compatible AI Editors & IDEs

Konductor has been extensively tested with and is fully compatible (now and in the future) with all major AI coding platforms, including:
Antigravity, Codex CLI, Codex UI, WindSurf, VS Code, Open Code, Claude Code, Cursor, Trae, Warp.dev, Kilo Code, and Roo Code.

Documentation Layout

• Keep README.md, KONDUCTOR.md, and SKILL.md at the repository root.
• Keep the universal skill source in SKILL.md.
• The installed runtime skill lives at .agents/skills/konductor-workflow/.
• Place all other project documentation under docs/.
• Use docs/CHECK_IN.md as the single live coordination file.
• Use .konductor/memory/AGENT_BEHAVIOR.md as the compact examples file for coding anti-patterns and preferred responses.
• Treat docs/CHECK_IN.md as short-term memory, .konductor/memory/KONDUCTOR_MEMORY.md as long-term memory, and .konductor/memory/KONDUCTOR_ADR_HISTORY.md as the ADR ledger.
• Keep KONDUCTOR.md, KONDUCTOR_WORKFLOW.md, KONDUCTOR_VISION_ROADMAP.md, and docs/CHECK_IN.md compact and agent-oriented.
• Keep SKILL.md aligned with the repo workflows and installed skill copy.
• Repo-specific slash-command examples live in docs/PROJECT_SKILLS_WORKFLOW.md: /k-init, /k-update, /k-history, /k-compact, and /k-checkin cover first-time review, framework refresh, memory/history inspection, context compaction, and live status check-ins.

Prompting with @KONDUCTOR

Token Usage & Context Optimization

By deploying our new token-reduction techniques, we force the AI to write and read documentation using stripped-out filler text. This greatly reduces prompt bloat and keeps the AI's attention entirely on the technical requirements.

Why this was made and open-source

We have all gone through the questionable 'vibe-coding' experience with AI coding assistants, where they usually forget your project's architectural choices and rules when the chat context fills up. In addition to that, the broken sessions, quota overages, and the AI's tendency to hallucinate or generate suboptimal code due to context loss are common pain points.

Konductor workflow fixes this by saving what the AI learns into lightweight, highly compressed Markdown files right inside your codebase. No external dependencies. The workflow does not deviate from the normal SDLC, it actually enforces a stricter, but auto-evolving modern 'agile development' process. D.R.Y and K.I.S.S are the essential principles.

Konductor came first as a common set of steps and guidelines and hard rules that we follow internally across different IDEs (2020-2026) while adapting to fast-evolving AI frameworks. Later on we standardize it across our dozen of large ERP projects, legacy and greenfield, and it evolved by learning and update itself from other libraries and AI coding agent building techniques.

We believe that this will survive the AI hype cycle and will be a standard practice in the future of software development. As our tools and your tools evolves, The Konductor grows and learn with you.

Read the full backstory: Why we built Konductor Workflow — the AI agent framework we made for ourselves

What enabled this magical technology in 2026?

Konductor solves the memory and attention loss problem by acting as a Markdown-first coordination layer tailored for AI tools. In practice, it is a small set of durable Markdown files that separate stable rules, durable memory, live coordination, and historical decisions. We found out that regardless of the size and complexity of your spaghetti codebase, it works well as long as you are disciplined enough to maintain the documentation. It's all human principles really.

As highlighted by the widespread Claude Code leak implications in April 2026, maintaining secure, verifiable, and transparent memory architectures for AI agents is more critical than ever.

We won't bury the workflow in extra tooling. The agent contract files use structured XML for reliable machine parsing: KONDUCTOR.md for the compact agent contract, SKILL.md for the universal skill source, .agents/skills/konductor-workflow/SKILL.md for the installed runtime copy, and KONDUCTOR_WORKFLOW.md for the operating machine contract (reference loop, behavior defaults, communication policy). All memory, coordination, and history files remain plain Markdown: docs/CHECK_IN.md for short-term working state, .konductor/memory/AGENT_BEHAVIOR.md for compact coding-behavior examples, .konductor/memory/KONDUCTOR_MEMORY.md for long-term memory, .konductor/memory/KONDUCTOR_VISION_ROADMAP.md for the WHY, and .konductor/memory/KONDUCTOR_ADR_HISTORY.md for critical architectural decisions in embedded ADR format. The main usage guide for operating the framework is KONDUCTOR_WORKFLOW.md.

• Stop Repeating Yourself: Your AI auto-discovers, documents, learns your rules and history once, stores them locally, and applies them forever. It evolves over time too.
• Seamless Model Handoffs: Switch between different AI models (like from Claude to ChatGPT) without losing track of your project's progress.
• 100% Local & Offline: No cloud subscriptions. Your AI's memory is plain Markdown stored safely inside your Git repository.

Behavior Layer

Konductor now treats coding behavior as part of the framework contract, not just a side effect of memory files.

• Assumption discipline: if ambiguity changes implementation meaningfully, agents should ask or state assumptions before editing.
• Simplicity first: solve the current request without speculative abstractions, generic frameworks, or unused configuration.
• Surgical changes: keep diffs traceable to the active task; avoid unrelated cleanup and formatting churn.
• Goal-driven execution: convert vague asks into explicit checks such as a repro, failing test, metric, or acceptance condition before coding.

The compact examples file installed into adopting repositories is .konductor/memory/AGENT_BEHAVIOR.md.

Contributing

AI Agents generating contributions natively must adhere to these compact instructions:

• READ_CONTRACT_FIRST: Always read @KONDUCTOR.md before generating code to establish alignment.
• ISSUE_AS_PLAN: Detail proposed changes, bug fixes, or feature additions in an Issue.
• PR_AS_ADR: Treat each PR as an Architecture Decision Record. Explicitly log thinking process, causality, alternatives considered, and architectural reasoning in the PR description.
• SYNC_PATTERNS: Strictly adhere to blueprints/KONDUCTOR_WORKFLOW.md, blueprints/memory/AGENT_BEHAVIOR.md, blueprints/memory/KONDUCTOR_VISION_ROADMAP.md, and blueprints/memory/KONDUCTOR_ADR_HISTORY.md.
• PASS_CI: Ensure all headless CI/CD tests pass locally to uphold stability before submitting your PR.

Acknowledgments & References

We believe in giving credit where it is due. Some of the core concepts we used to make this workflow framework possible include:

• Hyperagent & Darwin Gödel Machine (DGM) Provides the foundational concepts for autonomous self-improvement architecture and metacognitive looping used to guide our reasoning workflows. Reference: arXiv:2603.19461

• Architecture Decision Records (ADR) The foundational methodology we use to capture our causal memory and long-term architectural decisions, ensuring context is preserved across development phases. Reference: adr.github.io

• "Caveman" Token Reduction Technique A critical influence on our workflow structures to optimize LLM interactions, dramatically reducing token bloat without sacrificing necessary context. Reference: JuliusBrussee/caveman on GitHub

• Behavior Guardrail Patterns for Coding Agents Helped sharpen Konductor's explicit behavior layer around thinking before coding, simplicity-first execution, surgical diffs, and example-driven anti-pattern teaching. Reference: forrestchang/andrej-karpathy-skills on GitHub

• Verifiable Memory Architectures Highlights the critical necessity of maintaining secure, verifiable, and transparent memory architectures for AI agents, as discussed in recent industry events. Reference: Claude Code leak implications

• Field Notes & Shared Learnings A collection of our ongoing trials, errors, and practical lessons learned while adapting to fast-evolving AI workflows in real-world projects. Reference: alphabits.team/news

• Second Brains "Conductor" Node (March 2024) The conceptual predecessor to this framework. Originally implemented in Node-RED, the "conductor" served as a critical orchestration node for routing flows and managing agents across our entire enterprise architecture. Reference: AlphaBitsCode/second.brains on GitHub

For full version history, see CHANGELOG.md.

MIT License

Copyright (c) 2026 Alpha Bits Technology alphabits.team 🧑🏻‍💻 ☕️ 🛵 🇻🇳

Built by Human and AI for AI and Humans ♥