ai-council-orch

AI Council Orchestrator

Software that runs the AI Council protocol over a project instance's state files.

This repository is a consumer of the AI Council framework, not part of its core. The framework core stays documentation and method only; the orchestrator is code and ships separately. See the framework's orchestrator-design.md (Build Placement) for why.

Status

Pre-alpha walking skeleton. It reads and safely updates state files, can drive a guarded execution loop, and has the first file-based slice of the discussion engine. Working slices today:

• Parse an instance's docs/todo.md task matrix per the framework's state-schema.md.
• Validate it: canonical columns, allowed statuses, unique IDs (hard errors); missing owner/reviewer/validation and owner-equals-reviewer (warnings).
• Print it as a table or emit it as JSON.
• Parse fenced handoff, execution-result, and review-result objects from Markdown state files.
• Append well-formed state objects to docs/log.md.
• Set task status in docs/todo.md with round-trip checks.
• Run the execution engine loop with explicit approval and reviewer gates.
• Show a single-instance summary across todo, decisions, discussion readiness, and state objects.
• Show a read-only Command Center summary across one or more instances, with --sort-by (issues, todo, decisions, discussion_incomplete) and --filter (has-issues, has-errors, has-warnings, incomplete-discussion) for navigation.
• Serve the same Command Center report as a read-only local web view.
• Validate discussion-engine stage readiness for a decision record, with advisory content-quality checks (unfilled Clean Input subsections, empty or duplicated proposals).
• Parse decision records, persist proposal-author handoffs, capture proposal outputs, render anonymous peer-review packets, persist review handoffs, and capture reviews into Round 2 for the discussion engine.
• Draft proposal, review, and synthesis handoffs through the optional llm extra without writing decision records.
• Run the proposal/review/synthesis draft pipeline into handoff files without capturing anything into the decision record.
• Render synthesis packets, persist synthesis handoffs, and capture synthesis output into Round 3.
• Render final decision packets, persist final decision handoffs, and capture final decision fields into Round 4 while preserving the task matrix.

First principle

The protocol and the state files are the source of truth. This software automates work on top of them; it never becomes the record of truth.

If the orchestrator is turned off, the instance must still be fully workable by hand from its files alone.

Any internal state this tool keeps must be rebuildable from the files.

Quickstart

git submodule update --init --recursive

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Read the bundled sample instance:
ai-council-orch show-todo

# Summarize the bundled sample instance:
ai-council-orch show-instance
ai-council-orch show-command-center
ai-council-orch serve-command-center

# Read a real instance directory:
ai-council-orch show-todo /path/to/instance
ai-council-orch show-instance /path/to/instance
ai-council-orch show-command-center /path/to/instance-a /path/to/instance-b

# Emit JSON:
ai-council-orch show-todo --json

# Prepare an independent-proposal author packet from a decision record:
ai-council-orch proposal-packet examples/sample-instance/docs/decisions/2026-01-01-sample-flow.md --slot A

# Check whether decision records are ready for each discussion stage:
ai-council-orch check-discussion
ai-council-orch check-discussion /path/to/instance
ai-council-orch check-discussion /path/to/instance/docs/decisions/decision.md

# Persist a fillable proposal handoff, then capture the completed response:
ai-council-orch write-proposal-handoff /path/to/instance/docs/decisions/decision.md --slot B --out /tmp/proposal-B.md
ai-council-orch draft-proposal /path/to/instance/docs/decisions/decision.md --slot B --out /tmp/proposal-B.md
ai-council-orch capture-proposal /path/to/instance/docs/decisions/decision.md /tmp/proposal-B.md --slot B --source-label Author-B

# Draft proposals, anonymous reviews, and synthesis handoffs in one pass.
# This writes only handoff files under /tmp/council-drafts; capture remains manual.
ai-council-orch run-discussion /path/to/instance/docs/decisions/decision.md --out-dir /tmp/council-drafts

# Prepare an anonymous peer-review packet from a decision record:
ai-council-orch review-packet examples/sample-instance/docs/decisions/2026-01-01-sample-flow.md

# Persist a fillable review handoff for one anonymous proposal, then capture it into Round 2:
ai-council-orch write-review-handoff /path/to/instance/docs/decisions/decision.md --proposal 2 --out /tmp/review-2.md
ai-council-orch draft-review /path/to/instance/docs/decisions/decision.md --proposal 2 --out /tmp/review-2.md
ai-council-orch capture-review /path/to/instance/docs/decisions/decision.md /tmp/review-2.md --proposal 2

# Prepare synthesis context, persist a fillable handoff, then capture it into Round 3:
ai-council-orch synthesis-packet /path/to/instance/docs/decisions/decision.md
ai-council-orch write-synthesis-handoff /path/to/instance/docs/decisions/decision.md --out /tmp/synthesis.md
ai-council-orch draft-synthesis /path/to/instance/docs/decisions/decision.md --out /tmp/synthesis.md
ai-council-orch capture-synthesis /path/to/instance/docs/decisions/decision.md /tmp/synthesis.md

# Prepare final decision context, persist a fillable handoff, then capture it into Round 4:
ai-council-orch final-decision-packet /path/to/instance/docs/decisions/decision.md
ai-council-orch write-final-decision-handoff /path/to/instance/docs/decisions/decision.md --out /tmp/final-decision.md
ai-council-orch capture-final-decision /path/to/instance/docs/decisions/decision.md /tmp/final-decision.md

# Run the tests:
pytest

show-todo exits 0 on a clean read, 1 when the matrix has schema errors, and 2 when the file cannot be found or parsed at all.

Layout

src/ai_council_orchestrator/
  schema.py       Python mirror of state-schema.md objects
  todo.py         parse and validate docs/todo.md
  decisions.py    parse decision records and build/write discussion packets
  llm.py          optional LLM drafting clients for fillable handoffs
  objects.py      parse fenced handoff/result/review objects
  web.py          read-only Command Center HTTP view
  writeback.py    update task matrix status and append docs/log.md objects
  engine.py       guarded execution-engine loop
  cli.py          the ai-council-orch command
examples/
  sample-instance/docs/         domain-neutral fixture state files
tests/
  test_*.py
.ai-council/    framework reference as a git submodule

Relationship to the framework

The framework is referenced under .ai-council/ai-council/, the same path a project instance uses. In this repository that path is a git submodule pinned to a reviewed framework commit. The orchestrator reads real instances through their files and treats state-schema.md as the interface. See .ai-council/README.md for clone and initialization notes.

Roadmap

Now: state readers, safe write-back, guarded execution loop, and proposal, review, synthesis, and final decision packet/handoff/capture flows, with single-/multi-instance summaries, discussion-stage readiness checks, advisory content-quality validation, optional LLM draft handoffs and discussion draft pipeline, and Command Center sort/filter/web navigation.

Non-goals

• Not a replacement for a project's domain business application or interface.
• Not a chat product; conversation is not the record of truth.
• Not a required dependency for using the protocol.
• Not a place for project-specific business logic to accumulate.

License

MIT. See LICENSE.