# verymath/co-mathematician architecture

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

- Interactive diagram: https://gitdiagram.com/verymath/co-mathematician
- Repository: https://github.com/verymath/co-mathematician

## Overview

1. **Repository purpose**
   - This repo is not a math engine or a web app; it is a **stateful research workspace** for repository-aware coding agents.
   - The core architectural idea is: a human + coding agent collaborate through files in `workspace/`, with the Python harness enforcing structure, gates, and final-paper rendering.

2. **Top-level split: protocol, adapters, and harness**
   - The repository separates into three major concerns:
     - **Workspace protocol and instructions**: `README.md`, `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `agents/roles/`
     - **Agent-specific adapters**: `.codex/agents/`, `.claude/agents/`, `.cursor/rules/`
     - **Executable harness**: `harness/co_math/`
   - This separation matters because the same workspace protocol is meant to work across Codex, Claude Code, Cursor, and generic repository-aware agents.

3. **Persistent workspace state is file-backed**
   - The real project state lives under `workspace/`, not in memory:
     - `workspace/project/` holds project-level state such as `PROJECT.md`, `GOALS.yaml`, `PROJECT_STATUS.md`, `messages.jsonl`, and `skill_handoffs.jsonl`
     - `workspace/workstreams/` holds approved workstream folders
     - `workspace/final/` holds the final rendered paper, especially `working_paper.md`
   - This design makes the repository itself the durable database for research progress, provenance, and review outcomes.

4. **Coordinator-centric workflow**
   - The README defines a single main-thread role: the **Project Coordinator**, which is the coding agent session driving the workspace.
   - The coordinator owns onboarding, goal formalization, workstream creation, message logging, and deciding when to invoke gates.
   - The harness supports this workflow but does not perform research itself; it only validates and materializes workspace state.

5. **Goal → workstream → review pipeline**
   - The workflow is staged:
     - onboarding and project formalization
     - goal creation in `GOALS.yaml`
     - approval gate for goals
     - creation of workstreams for approved goals
     - report drafting inside workstreams
     - independent review
     - final paper rendering
   - This is the main data flow to diagram: user context enters the project, becomes goals, then workstreams, then reviewed reports, and finally the working paper.

6. **Workstream types encode research modes**
   - Workstreams are not generic tasks; they are typed as **proof, computation, literature, or review**.
   - That type determines the intended output and evidence style:
     - proof exploration preserves failed attempts and uncertainty
     - computation preserves artifacts and logs
     - literature work emphasizes theorem provenance and citations
     - review work focuses on independent verification
   - These categories are important architectural boundaries because they separate kinds of evidence rather than just kinds of tasks.

7. **Reviewer loop is a first-class boundary**
   - The architecture explicitly requires independent reviewer output before completion.
   - Reviewers are conceptually separate from the main coordinator and include roles such as logic reviewer, adversarial reviewer, and citation checker.
   - Reviews are stored under each workstream’s `reviews/` area, and unresolved issues are expected to feed back into revision rather than being hidden.

8. **Final output is derived, not authored directly**
   - `workspace/final/working_paper.md` is rendered only from reviewed reports.
   - That means the final paper is an assembly artifact, not a free-form chat summary.
   - The architecture therefore enforces a provenance chain: workstream artifacts and reviews must exist before the final output can be produced.

9. **Harness responsibilities and boundaries**
   - `harness/co_math/` is the executable package that provides the workspace machinery:
     - CLI entry points in `cli.py`
     - gate validation in `gating.py`
     - message persistence in `messages.py`
     - report rendering in `reports.py`
     - data models/schemas in `schemas.py`
     - skill and handoff management in `skills.py` and `skill_handoff.py`
     - workspace initialization and layout management in `workspace.py`
   - The harness is intentionally bounded: it initializes files, appends messages, creates workstreams, checks gates, and renders the final paper, but does not run the agents themselves.

10. **Skill registry as an extension layer**
   - The repository supports local mathematical skill libraries through `.agents/skills/`.
   - The harness can refresh the registry and suggest relevant skills, then record a handoff when a domain skill should drive part of the task.
   - This creates a second layer of modularity: the workspace protocol handles durable project state, while skills encapsulate domain-specific methods.

11. **Adapter layer for different agent platforms**
   - The repository provides platform-specific entry points for the same underlying role system:
     - `.codex/` for Codex
     - `.claude/` for Claude Code
     - `.cursor/` for Cursor
     - `agents/roles/` as the canonical, platform-neutral role definitions
   - In architectural terms, these are thin compatibility layers around the same workflow and should be shown as adapters feeding the same workspace protocol.

12. **Tests validate the protocol, not math content**
   - `harness/tests/` focuses on harness behavior: agent adapters, gating, report rendering, skill handoff, skill registry, and workspace structure.
   - This test suite is a strong signal that the repo’s primary correctness concerns are **state management and workflow enforcement**, not theorem proving itself.

13. **External dependencies and runtime**
   - The system is a Python package installed via `pyproject.toml`.
   - It runs locally in a repository clone, relying on the filesystem as the main persistence layer.
   - External “services” are really human or AI agent runtimes; the repo does not appear to depend on a backend server or database.

14. **What to emphasize in an architecture diagram**
   - The most accurate diagram would show:
     - user input into the coordinator
     - coordinator updating `workspace/project/`
     - goal approval gate
     - approved workstreams in `workspace/workstreams/`
     - reviewer loop feeding back into reports
     - final rendering into `workspace/final/working_paper.md`
     - the harness as the validator/orchestrator around those file-based states
   - The critical boundary is between **agent behavior** and **harness-enforced durable state**.

Main entry points: [`workspace/workstreams`](https://github.com/verymath/co-mathematician/tree/main/workspace/workstreams) (Workstreams), [`workspace/project`](https://github.com/verymath/co-mathematician/tree/main/workspace/project) (Project state), [`agents/roles`](https://github.com/verymath/co-mathematician/tree/main/agents/roles) (Roles), [`harness/co_math/workspace.py`](https://github.com/verymath/co-mathematician/blob/main/harness/co_math/workspace.py) (Workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_protocol["Workspace protocol"]
  node_readme["README<br/>protocol overview<br/>[README.md]"]
  node_agents_md["AGENTS<br/>protocol guide<br/>[AGENTS.md]"]
  node_claude_md["CLAUDE<br/>platform guide<br/>[CLAUDE.md]"]
  node_roles["Roles"]
end

subgraph group_group_adapters["Agent adapters"]
  node_codex_adapters["Codex<br/>adapter set<br/>[agents]"]
  node_claude_adapters["Claude agents<br/>adapter set<br/>[agents]"]
  node_cursor_rules["Cursor rules<br/>adapter rules<br/>[rules]"]
end

subgraph group_group_harness["Executable harness"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_gating["Gates<br/>validation<br/>[gating.py]"]
  node_messages["Messages<br/>persistence<br/>[messages.py]"]
  node_reports["Reports<br/>rendering<br/>[reports.py]"]
  node_schemas["Schemas<br/>models<br/>[schemas.py]"]
  node_skills_mod["Skills<br/>registry<br/>[skills.py]"]
  node_handoff["Handoffs<br/>routing<br/>[skill_handoff.py]"]
  node_workspace_mod["Workspace<br/>layout manager<br/>[workspace.py]"]
end

subgraph group_group_workspace["Persistent workspace"]
  node_project_state[("Project state<br/>persistent state")]
  node_goals["Goals<br/>approval queue<br/>[GOALS.yaml]"]
  node_workstreams[("Workstreams<br/>research units")]
  node_final_paper["Working paper<br/>derived output"]
end

subgraph group_group_skills["Skill registry"]
  node_skill_library["Skill library<br/>local extension<br/>[co-mathematician]"]
end

node_readme -->|"defines roles"| node_roles
node_readme -->|"orients workflow"| node_project_state
node_agents_md -->|"operating rules"| node_roles
node_claude_md -->|"platform binding"| node_claude_adapters
node_cursor_rules -->|"role mapping"| node_roles
node_codex_adapters -->|"role mapping"| node_roles
node_claude_adapters -->|"role mapping"| node_roles
node_cli -->|"orchestrates"| node_workspace_mod
node_workspace_mod -->|"creates layout"| node_project_state
node_workspace_mod -->|"provisions"| node_workstreams
node_workspace_mod -->|"prepares output"| node_final_paper
node_gating -->|"validates"| node_goals
node_gating -->|"checks readiness"| node_workstreams
node_messages -->|"appends log"| node_project_state
node_schemas -->|"defines format"| node_project_state
node_skills_mod -->|"refreshes"| node_skill_library
node_handoff -->|"selects skill"| node_skill_library
node_reports -->|"renders"| node_final_paper
node_project_state -->|"contains"| node_goals
node_project_state -->|"contains"| node_messages
node_goals -->|"spawns"| node_workstreams
node_workstreams -->|"feeds"| node_final_paper
node_workstreams -->|"produce reports"| node_reports
node_workstreams -.->|"review loop"| node_gating
node_skill_library -->|"supports methods"| node_workstreams

click node_readme "https://github.com/verymath/co-mathematician/blob/main/README.md"
click node_agents_md "https://github.com/verymath/co-mathematician/blob/main/AGENTS.md"
click node_claude_md "https://github.com/verymath/co-mathematician/blob/main/CLAUDE.md"
click node_roles "https://github.com/verymath/co-mathematician/tree/main/agents/roles"
click node_codex_adapters "https://github.com/verymath/co-mathematician/blob/main/.codex/agents"
click node_claude_adapters "https://github.com/verymath/co-mathematician/blob/main/.claude/agents"
click node_cursor_rules "https://github.com/verymath/co-mathematician/blob/main/.cursor/rules"
click node_cli "https://github.com/verymath/co-mathematician/blob/main/harness/co_math/cli.py"
click node_gating "https://github.com/verymath/co-mathematician/blob/main/harness/co_math/gating.py"
click node_messages "https://github.com/verymath/co-mathematician/blob/main/harness/co_math/messages.py"
click node_reports "https://github.com/verymath/co-mathematician/blob/main/harness/co_math/reports.py"
click node_schemas "https://github.com/verymath/co-mathematician/blob/main/harness/co_math/schemas.py"
click node_skills_mod "https://github.com/verymath/co-mathematician/blob/main/harness/co_math/skills.py"
click node_handoff "https://github.com/verymath/co-mathematician/blob/main/harness/co_math/skill_handoff.py"
click node_workspace_mod "https://github.com/verymath/co-mathematician/blob/main/harness/co_math/workspace.py"
click node_project_state "https://github.com/verymath/co-mathematician/tree/main/workspace/project"
click node_goals "https://github.com/verymath/co-mathematician/blob/main/workspace/project/GOALS.yaml"
click node_workstreams "https://github.com/verymath/co-mathematician/tree/main/workspace/workstreams"
click node_final_paper "https://github.com/verymath/co-mathematician/tree/main/workspace/final"
click node_skill_library "https://github.com/verymath/co-mathematician/blob/main/.agents/skills/co-mathematician"

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_readme,node_agents_md,node_claude_md,node_roles toneBlue
class node_codex_adapters,node_claude_adapters,node_cursor_rules toneAmber
class node_cli,node_gating,node_messages,node_reports,node_schemas,node_skills_mod,node_handoff,node_workspace_mod toneMint
class node_project_state,node_goals,node_workstreams,node_final_paper toneRose
class node_skill_library toneIndigo
```

## Components

### Workspace protocol

Human- and agent-facing instructions and canonical role definitions.

- [README](https://github.com/verymath/co-mathematician/blob/main/README.md): protocol overview · Primary description of the coordinator workflow and workspace conventions. · `README.md`
- [AGENTS](https://github.com/verymath/co-mathematician/blob/main/AGENTS.md): protocol guide · Repository-wide operating instructions for agents. · `AGENTS.md`
- [CLAUDE](https://github.com/verymath/co-mathematician/blob/main/CLAUDE.md): platform guide · Claude-specific workspace instructions. · `CLAUDE.md`
- [Roles](https://github.com/verymath/co-mathematician/tree/main/agents/roles): canonical roles · Platform-neutral role definitions for the coordinator and reviewers. · `agents/roles`

### Agent adapters

Platform-specific entry points that map different runtimes onto the shared role system.

- [Codex](https://github.com/verymath/co-mathematician/blob/main/.codex/agents): adapter set · Codex agent definitions that bind platform behavior to shared roles. · `.codex/agents`
- [Claude agents](https://github.com/verymath/co-mathematician/blob/main/.claude/agents): adapter set · Claude Code agent definitions for the shared role system. · `.claude/agents`
- [Cursor rules](https://github.com/verymath/co-mathematician/blob/main/.cursor/rules): adapter rules · Cursor-specific rules that adapt the shared workflow to that runtime. · `.cursor/rules`

### Executable harness

Python package that enforces workspace structure, gates, persistence, and rendering.

- [CLI](https://github.com/verymath/co-mathematician/blob/main/harness/co_math/cli.py): entrypoint · Command-line entry point for workspace operations. · `harness/co_math/cli.py`
- [Gates](https://github.com/verymath/co-mathematician/blob/main/harness/co_math/gating.py): validation · Approval and readiness checks for goals, workstreams, and completion. · `harness/co_math/gating.py`
- [Messages](https://github.com/verymath/co-mathematician/blob/main/harness/co_math/messages.py): persistence · Append-only message logging for project communication. · `harness/co_math/messages.py`
- [Reports](https://github.com/verymath/co-mathematician/blob/main/harness/co_math/reports.py): rendering · Transforms reviewed workstream reports into the final paper. · `harness/co_math/reports.py`
- [Schemas](https://github.com/verymath/co-mathematician/blob/main/harness/co_math/schemas.py): models · Data models and file schemas for workspace state. · `harness/co_math/schemas.py`
- [Skills](https://github.com/verymath/co-mathematician/blob/main/harness/co_math/skills.py): registry · Discovers and refreshes the local skill registry. · `harness/co_math/skills.py`
- [Handoffs](https://github.com/verymath/co-mathematician/blob/main/harness/co_math/skill_handoff.py): routing · Records when a domain skill should take over part of the task. · `harness/co_math/skill_handoff.py`
- [Workspace](https://github.com/verymath/co-mathematician/blob/main/harness/co_math/workspace.py): layout manager · Initializes and maintains the repository-backed workspace layout. · `harness/co_math/workspace.py`

### Persistent workspace

File-backed project state and research outputs.

- [Project state](https://github.com/verymath/co-mathematician/tree/main/workspace/project): persistent state · Top-level project metadata, goals, status, and communication log. · `workspace/project`
- [Goals](https://github.com/verymath/co-mathematician/blob/main/workspace/project/GOALS.yaml): approval queue · Formalized goals that must pass gating before workstreams begin. · `workspace/project/GOALS.yaml`
- [Workstreams](https://github.com/verymath/co-mathematician/tree/main/workspace/workstreams): research units · Approved goal-specific workstream folders for evidence production. · `workspace/workstreams`
- [Working paper](https://github.com/verymath/co-mathematician/tree/main/workspace/final): derived output · Final rendered paper assembled from reviewed reports. · `workspace/final`

### Skill registry

Local extension layer for domain-specific methods and handoffs.

- [Skill library](https://github.com/verymath/co-mathematician/blob/main/.agents/skills/co-mathematician): local extension · Domain-specific skill package used by the harness and agents. · `.agents/skills/co-mathematician`

## Connections

- README → Roles: defines roles · The repository instructions establish the canonical role system.
- README → Project state: orients workflow · The README describes the file-backed research workspace.
- AGENTS → Roles: operating rules · Agent instructions reference the shared role definitions.
- CLAUDE → Claude agents: platform binding · Claude-specific guidance aligns with the Claude agent adapter layer.
- Cursor rules → Roles: role mapping · Cursor rules map platform behavior onto the canonical roles.
- Codex → Roles: role mapping · Codex agents implement the same shared role system.
- Claude agents → Roles: role mapping · Claude agents implement the same shared role system.
- CLI → Workspace: orchestrates · The CLI drives workspace initialization and updates.
- Workspace → Project state: creates layout · The harness materializes the file-backed project state.
- Workspace → Workstreams: provisions · Workspace management creates approved workstream folders.
- Workspace → Working paper: prepares output · Workspace management supports final output materialization.
- Gates → Goals: validates · Goal approval gates control promotion into active work.
- Gates → Workstreams: checks readiness · Workstreams are gated before and during execution.
- Messages → Project state: appends log · Messages are persisted into the project state area.
- Schemas → Project state: defines format · Schemas define the durable structure of workspace files.
- Skills → Skill library: refreshes · The harness discovers and refreshes local skills.
- Handoffs → Skill library: selects skill · Handoffs route work to the appropriate domain skill.
- Reports → Working paper: renders · Reviewed reports are assembled into the working paper.
- Project state → Goals: contains · Project state includes the goals file as a central control point.
- Project state → Messages: contains · Project state includes the append-only message log.
- Goals → Workstreams: spawns · Approved goals are converted into workstreams.
- Workstreams → Working paper: feeds · Reviewed workstream outputs feed the final assembly artifact.
- Workstreams → Reports: produce reports · Each workstream yields a report that can be reviewed and rendered.
- Workstreams → Gates: review loop · Review outcomes can send work back through validation and revision.
- Skill library → Workstreams: supports methods · Domain skills assist specific workstreams when needed.
