DevTeam / Controller

A multi-agent governance platform for production-ready industrial software generation. The platform orchestrates LLM-driven coding agents under deterministic Python control, with namespace-scoped configuration that pins what each dispatch is allowed to write, which reviewers run on it, and what gate must be human-approved before implementation can proceed.

The platform itself is generic. Industrial domain packs (terminology, state machines, regulatory constraints, approved stack choices, gate ladder semantics) live entirely in namespaces/<env>/<namespace>/ and never leak into platform code under src/.

What this repository contains

• src/ — the platform: feature controller, claude-CLI bridge, config loaders, memory loader (precedence-ordered prompt context), pre-review rules engine, reviewer squad runner, gates, observability scaffolding, drift detector, scope lock.
• prompts/reviewers/ — Senior Reviewer prompt templates (backend, frontend, data, Go, SRE, performance, domain logic, business expert, security, test quality).
• controller/ — platform-wide governance config: platform_invariants.md (P-1..P-13), approved_rules.yaml (filtered, namespace-aware rules).
• docs/ — NAMESPACE_CONTRACT.md (the per-namespace contract shape), RESILIENCE_RULES.md (R-1..R-12 cross-language external-data resilience), PRE_REVIEW_RULES_ROADMAP.md (deferred Go-rule configuration requirements).
• examples/minimal-industrial-namespace/ — a starter domain pack: operating_mode.yaml, capabilities.yaml, approved_stack.yaml, invariants.md, roles.yaml, DOMAIN.md. Copy and replace the fields when onboarding a new namespace.
• run_features.py — the dispatch entry point.
• LICENSE — Apache License 2.0.

Governance flow

The controller composes every layer in a fixed precedence on each dispatch:

Dispatch
   ↓
[1] feature_controller.run() — pre-flight
       · operating_mode.is_implementation_blocked
       · gate_approvals[<current_gate>] check
       · capability binding (validate_capability_binding)
   ↓
[2] build_prompt_context produces:
       1. controller/platform_invariants.md
       2. namespaces/<ns>/invariants.md
       3. operating_mode.yaml block
       3.5 ACTIVE_CAPABILITY sub-block
       4. controller/approved_rules.yaml (filtered)
       5. lessons_learned.md (research mode only)
       6. success_patterns.md (research mode only, advisory)
   ↓
[3] Worker agent runs (claude -p)
   ↓
[4] _capability_post_check
       · forbidden_writes priority
       · capability.artifacts whitelist
   ↓
[5] DETERMINISTIC_RULES — pre-review engine
       · 8 baseline rules + 3 governance rules
       · RULE_APPLIES_TO namespace scoping
   ↓
[6] CONDITIONAL_REVIEWERS
       · ReviewerSpec.when patterns vs files_changed
       · run_code_review_gate(roles=active)
   ↓
Commit (or stuck / failed / needs_commit)

Quickstart

# 1. Create a namespace from the example.
cp -r examples/minimal-industrial-namespace namespaces/dev/my-namespace

# 2. Edit operating_mode.yaml, capabilities.yaml, approved_stack.yaml,
#    invariants.md, roles.yaml, DOMAIN.md to your domain.

# 3. Have a human architect approve the contract gate by editing
#    operating_mode.yaml (status → approved with approved_by /
#    approved_at populated). Agents must NOT flip gates.

# 4. Dispatch a feature.
python3 run_features.py namespaces/dev/my-namespace

The controller refuses the dispatch unless the namespace's mode is implementation (or maintenance), the current gate is approved, and the feature declares a known capability id whose artifacts cover the files the worker is permitted to touch.

Design principles

• Code reads YAML, never writes it. Gate transitions are a manual editorial act by a human architect. No code path flips gate_approvals[*].status.
• Deterministic Python on every governance decision. No LLM is on a governance path. Drift detection, gate gating, capability binding, scope merging, rule filtering, reviewer routing — all deterministic.
• No domain logic in src/. Adding a new namespace is a configuration change under namespaces/<env>/<new>/; no platform edit is needed. Platform invariant P-2 enforces this boundary.
• Every governance source is read fresh per dispatch. Operator edits to operating_mode.yaml (mode flip, gate approval, allowed writes, current_acceptance_focus) take effect on the next dispatch with no cache to invalidate.
• Loud failure on malformed config. A missing operating_mode.yaml for a namespace not listed in controller/legacy_namespaces.txt refuses the dispatch with an actionable error. Same for malformed YAML, unknown gate ids, unknown capability ids, unknown reviewer roles.

Reading order for new contributors

1. docs/NAMESPACE_CONTRACT.md — what a namespace must ship.
2. controller/platform_invariants.md — P-1..P-13 governance rules that bind the platform itself.
3. examples/minimal-industrial-namespace/ — concrete shape of a working namespace.
4. src/feature_controller.py:run — the dispatch entry path.
5. src/memory_loader.py:build_prompt_context — how the precedence stack is assembled.
6. src/rules/engine.py — the pre-review rules engine and namespace-scoping mechanism.
7. src/reviewers/namespace_config.py — ReviewerSpec and conditional reviewer routing.

Status

This is the public Open Source export of the platform. Domain packs maintained against this platform live in their own repositories.