# ercoledevs/codex-council architecture

> Architecture diagram of the GitHub repository ercoledevs/codex-council, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ercoledevs/codex-council
- Repository: https://github.com/ercoledevs/codex-council

## Overview

Codex Council is a Codex plugin for turning software ideas and proposed changes into reviewed designs and, when authorized, implementation patches. Its main workflow begins with Mind’s guided decisions and review, proceeds through a Council verdict, and can hand an approved change to Hyper for implementation and check reporting. Forge and Alters provide additional design and review customization workflows. The Python CLI supports estimation and session operations; an optional Decision Runtime derives a separate, non-authoritative record. Edges reflect README statements and the source index; unsampled skill internals are not inferred.

Main entry points: [`scripts/codex_council.py`](https://github.com/ercoledevs/codex-council/blob/main/scripts/codex_council.py) (Session CLI), [`skills/codex-mind/SKILL.md`](https://github.com/ercoledevs/codex-council/blob/main/skills/codex-mind/SKILL.md) (Mind), [`skills/codex-council/SKILL.md`](https://github.com/ercoledevs/codex-council/blob/main/skills/codex-council/SKILL.md) (Council), [`skills/codex-hyper/SKILL.md`](https://github.com/ercoledevs/codex-council/blob/main/skills/codex-hyper/SKILL.md) (Hyper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_design["Design workflows"]
  node_mind["Mind<br/>[SKILL.md]"]
  node_forge["Forge<br/>[SKILL.md]"]
  node_interview["Decision interview"]
end

subgraph group_review["Review and implementation"]
  node_council["Council<br/>[SKILL.md]"]
  node_hyper["Hyper<br/>[SKILL.md]"]
end

subgraph group_runtime["Session runtime"]
  node_cli["Session CLI<br/>[codex_council.py]"]
  node_decision_runtime["Decision Runtime<br/>[council_cells.py]"]
  node_session_artifacts[("Session artifacts<br/>[codex_council.py]")]
end

subgraph group_extension["Local customization"]
  node_alters["Alters<br/>[SKILL.md]"]
end

node_user(("Codex user"))

node_user -->|"starts with"| node_mind
node_user -->|"invokes directly"| node_forge
node_user -->|"invokes directly"| node_council
node_user -->|"invokes directly"| node_hyper
node_user -->|"invokes directly"| node_alters
node_mind -->|"proposes and reviews"| node_council
node_council -->|"hands off approved change"| node_hyper
node_mind -->|"hands off authorized work"| node_hyper
node_user -->|"estimates locally"| node_cli
node_cli -->|"imports"| node_interview
node_cli -->|"imports"| node_decision_runtime
node_cli -->|"stores session data"| node_session_artifacts
node_decision_runtime -->|"derives separate projection"| node_session_artifacts

click node_mind "https://github.com/ercoledevs/codex-council/blob/main/skills/codex-mind/SKILL.md"
click node_forge "https://github.com/ercoledevs/codex-council/blob/main/skills/codex-forge/SKILL.md"
click node_council "https://github.com/ercoledevs/codex-council/blob/main/skills/codex-council/SKILL.md"
click node_hyper "https://github.com/ercoledevs/codex-council/blob/main/skills/codex-hyper/SKILL.md"
click node_alters "https://github.com/ercoledevs/codex-council/blob/main/skills/codex-council-alters/SKILL.md"
click node_cli "https://github.com/ercoledevs/codex-council/blob/main/scripts/codex_council.py"
click node_interview "https://github.com/ercoledevs/codex-council/blob/main/scripts/council_interview.py"
click node_decision_runtime "https://github.com/ercoledevs/codex-council/blob/main/scripts/council_cells.py"
click node_session_artifacts "https://github.com/ercoledevs/codex-council/blob/main/scripts/codex_council.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mind,node_forge,node_interview,node_user toneBlue
class node_council,node_hyper toneAmber
class node_cli,node_decision_runtime,node_session_artifacts toneMint
class node_alters toneRose
```

## Components

### Design workflows

- [Mind](https://github.com/ercoledevs/codex-council/blob/main/skills/codex-mind/SKILL.md): `skills/codex-mind/SKILL.md`
- [Forge](https://github.com/ercoledevs/codex-council/blob/main/skills/codex-forge/SKILL.md): `skills/codex-forge/SKILL.md`
- [Decision interview](https://github.com/ercoledevs/codex-council/blob/main/scripts/council_interview.py): `scripts/council_interview.py`

### Review and implementation

- [Council](https://github.com/ercoledevs/codex-council/blob/main/skills/codex-council/SKILL.md): `skills/codex-council/SKILL.md`
- [Hyper](https://github.com/ercoledevs/codex-council/blob/main/skills/codex-hyper/SKILL.md): `skills/codex-hyper/SKILL.md`

### Session runtime

- [Session CLI](https://github.com/ercoledevs/codex-council/blob/main/scripts/codex_council.py): `scripts/codex_council.py`
- [Decision Runtime](https://github.com/ercoledevs/codex-council/blob/main/scripts/council_cells.py): `scripts/council_cells.py`
- [Session artifacts](https://github.com/ercoledevs/codex-council/blob/main/scripts/codex_council.py): `scripts/codex_council.py`

### Local customization

- [Alters](https://github.com/ercoledevs/codex-council/blob/main/skills/codex-council-alters/SKILL.md): `skills/codex-council-alters/SKILL.md`

### Other components

- **Codex user**

## Connections

- Codex user → Mind: starts with (evidence: `README.md`)
- Codex user → Forge: invokes directly (evidence: `README.md`)
- Codex user → Council: invokes directly (evidence: `README.md`)
- Codex user → Hyper: invokes directly (evidence: `README.md`)
- Codex user → Alters: invokes directly (evidence: `README.md`)
- Mind → Council: proposes and reviews (evidence: `README.md`)
- Council → Hyper: hands off approved change (evidence: `README.md`)
- Mind → Hyper: hands off authorized work (evidence: `README.md`)
- Codex user → Session CLI: estimates locally (evidence: `README.md`)
- Session CLI → Decision interview: imports (evidence: `scripts/codex_council.py`)
- Session CLI → Decision Runtime: imports (evidence: `scripts/codex_council.py`)
- Session CLI → Session artifacts: stores session data (evidence: `README.md`)
- Decision Runtime → Session artifacts: derives separate projection (evidence: `README.md`)