# bnet47/codexicon architecture

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

- Interactive diagram: https://gitdiagram.com/bnet47/codexicon
- Repository: https://github.com/bnet47/codexicon

## Overview

Codexicon is a repository-local harness for guiding Codex work, not an application framework. Its user journey is to adopt the harness or start a clean project, route work through task-appropriate skills, verify changes, and cross Git or other external-effect boundaries only with explicit authority. The graph includes the core CLI and documented supporting capabilities; unsampled skill, configuration, and manager internals are represented at their existing paths, so their internal call relationships are not inferred.

Main entry points: [`scripts/release.py`](https://github.com/bnet47/codexicon/blob/main/scripts/release.py) (Release identity check), [`scripts/scaffold.py`](https://github.com/bnet47/codexicon/blob/main/scripts/scaffold.py) (Starter scaffolder), [`.agents/skills`](https://github.com/bnet47/codexicon/tree/main/.agents/skills) (Routed skill workflows), [`.codex`](https://github.com/bnet47/codexicon/tree/main/.codex) (Codex controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_adoption["Project adoption"]
  node_scaffolder["Starter scaffolder<br/>[scaffold.py]"]
  node_adoption_cli["Adoption and updates<br/>[codexicon.py]"]
end

subgraph group_workflow["Workflows and context"]
  node_harness_context["Durable context<br/>[AGENTS.md]"]
  node_skill_catalog["Routed skill workflows<br/>[skills]"]
  node_codex_controls["Codex controls<br/>[.codex]"]
  node_task_manager["Task and evidence manager<br/>[codexicon.py]"]
end

subgraph group_verification["Verification and safety"]
  node_template_validator["Template validation"]
  node_security_scan["Credential scanning<br/>[security_scan.py]"]
  node_skill_provenance["Skill provenance checks"]
end

subgraph group_release["Template distribution"]
  node_release_check["Release identity check<br/>[release.py]"]
  node_starter_manifest["Managed-file manifest<br/>[.codexicon.json]"]
  node_template_version["Template version"]
end

node_new_project(("New project owner"))
node_existing_repo(("Existing repo owner"))
node_codex(("Codex user"))

node_new_project -->|"create starter"| node_scaffolder
node_existing_repo -->|"inspect or adopt"| node_adoption_cli
node_codex -->|"choose workflow"| node_skill_catalog
node_codex -->|"manage task evidence"| node_task_manager
node_harness_context -.->|"sets durable rules"| node_codex_controls
node_skill_catalog -.->|"uses scoped tools"| node_codex_controls
node_codex -->|"verify template"| node_template_validator
node_codex -->|"run security checks"| node_security_scan
node_scaffolder -->|"projects manifest"| node_starter_manifest
node_release_check -->|"checks generated starter"| node_scaffolder
node_release_check -->|"checks manifest"| node_starter_manifest
node_release_check -->|"checks version"| node_template_version
node_codex -->|"verify skill lock"| node_skill_provenance

click node_scaffolder "https://github.com/bnet47/codexicon/blob/main/scripts/scaffold.py"
click node_adoption_cli "https://github.com/bnet47/codexicon/blob/main/scripts/codexicon.py"
click node_harness_context "https://github.com/bnet47/codexicon/blob/main/AGENTS.md"
click node_skill_catalog "https://github.com/bnet47/codexicon/tree/main/.agents/skills"
click node_codex_controls "https://github.com/bnet47/codexicon/tree/main/.codex"
click node_task_manager "https://github.com/bnet47/codexicon/blob/main/scripts/codexicon.py"
click node_template_validator "https://github.com/bnet47/codexicon/blob/main/scripts/validate_template.py"
click node_security_scan "https://github.com/bnet47/codexicon/blob/main/scripts/security_scan.py"
click node_skill_provenance "https://github.com/bnet47/codexicon/blob/main/scripts/skill_provenance.py"
click node_release_check "https://github.com/bnet47/codexicon/blob/main/scripts/release.py"
click node_starter_manifest "https://github.com/bnet47/codexicon/blob/main/.codexicon.json"
click node_template_version "https://github.com/bnet47/codexicon/blob/main/TEMPLATE_VERSION"

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_scaffolder,node_adoption_cli,node_codex toneBlue
class node_harness_context,node_skill_catalog,node_codex_controls,node_task_manager toneAmber
class node_template_validator,node_security_scan,node_skill_provenance toneMint
class node_release_check,node_starter_manifest,node_template_version toneRose
class node_new_project,node_existing_repo toneIndigo
```

## Components

### Project adoption

- [Starter scaffolder](https://github.com/bnet47/codexicon/blob/main/scripts/scaffold.py): `scripts/scaffold.py`
- [Adoption and updates](https://github.com/bnet47/codexicon/blob/main/scripts/codexicon.py): `scripts/codexicon.py`

### Workflows and context

- [Durable context](https://github.com/bnet47/codexicon/blob/main/AGENTS.md): `AGENTS.md`
- [Routed skill workflows](https://github.com/bnet47/codexicon/tree/main/.agents/skills): `.agents/skills`
- [Codex controls](https://github.com/bnet47/codexicon/tree/main/.codex): `.codex`
- [Task and evidence manager](https://github.com/bnet47/codexicon/blob/main/scripts/codexicon.py): `scripts/codexicon.py`

### Verification and safety

- [Template validation](https://github.com/bnet47/codexicon/blob/main/scripts/validate_template.py): `scripts/validate_template.py`
- [Credential scanning](https://github.com/bnet47/codexicon/blob/main/scripts/security_scan.py): `scripts/security_scan.py`
- [Skill provenance checks](https://github.com/bnet47/codexicon/blob/main/scripts/skill_provenance.py): `scripts/skill_provenance.py`

### Template distribution

- [Release identity check](https://github.com/bnet47/codexicon/blob/main/scripts/release.py): `scripts/release.py`
- [Managed-file manifest](https://github.com/bnet47/codexicon/blob/main/.codexicon.json): `.codexicon.json`
- [Template version](https://github.com/bnet47/codexicon/blob/main/TEMPLATE_VERSION): `TEMPLATE_VERSION`

### Other components

- **New project owner**
- **Existing repo owner**
- **Codex user**

## Connections

- New project owner → Starter scaffolder: create starter (evidence: `README.md`)
- Existing repo owner → Adoption and updates: inspect or adopt (evidence: `README.md`)
- Codex user → Routed skill workflows: choose workflow (evidence: `README.md`)
- Codex user → Task and evidence manager: manage task evidence (evidence: `README.md`)
- Durable context → Codex controls: sets durable rules (evidence: `README.md`)
- Routed skill workflows → Codex controls: uses scoped tools (evidence: `README.md`)
- Codex user → Template validation: verify template (evidence: `README.md`)
- Codex user → Credential scanning: run security checks (evidence: `README.md`)
- Starter scaffolder → Managed-file manifest: projects manifest (evidence: `scripts/scaffold.py`)
- Release identity check → Starter scaffolder: checks generated starter (evidence: `scripts/release.py`)
- Release identity check → Managed-file manifest: checks manifest (evidence: `scripts/release.py`)
- Release identity check → Template version: checks version (evidence: `scripts/release.py`)
- Codex user → Skill provenance checks: verify skill lock (evidence: `README.md`)
