Skip to main content

​
What We Learned

The loadCouncilConfig() function in packages/cli/src/lib/council.ts casts the parsed YAML to a typed subset — only protectedAgents and gateAuthorityAgents are extracted. All other top-level keys are silently discarded. This is an architectural feature, not a bug. This means council.yaml can carry rich agent metadata (designation, role, capabilities, descriptions, default assignments) alongside the two machine-consumed keys. A single file serves as both:
  1. Machine layer: protectedAgents and gateAuthorityAgents — consumed by CI pipeline (FM-04, FM-05, blast radius classification)
  2. Documentation layer: agents[] array with full registry — consumed by humans and skill files

​
Why This Matters

Most config file formats force a choice: either the file is machine-only (and you maintain separate docs) or it’s documentation-only (and you parse it manually). The dual-layer pattern avoids this by exploiting TypeScript’s structural typing — the parser extracts what it needs and ignores the rest, so the documentation layer is free-form without risking parse failures. This pattern should be preserved as councils expand. New metadata fields (e.g., default_for, description, capabilities) can be added to the agents[] block without touching the parser or schema.