How verymath/co-mathematician works
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: workstreams Workstreams · project Project state · roles Roles · workspace.py Workspace
Components 20
Workspace protocol
Human- and agent-facing instructions and canonical role definitions.
- README · Primary description of the coordinator workflow and workspace conventions.
README.md - AGENTS · Repository-wide operating instructions for agents.
AGENTS.md - CLAUDE · Claude-specific workspace instructions.
CLAUDE.md - 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 · Codex agent definitions that bind platform behavior to shared roles.
.codex/agents - Claude agents · Claude Code agent definitions for the shared role system.
.claude/agents - Cursor 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 · Command-line entry point for workspace operations.
harness/co_math/cli.py - Gates · Approval and readiness checks for goals, workstreams, and completion.
harness/co_math/gating.py - Messages · Append-only message logging for project communication.
harness/co_math/messages.py - Reports · Transforms reviewed workstream reports into the final paper.
harness/co_math/reports.py - Schemas · Data models and file schemas for workspace state.
harness/co_math/schemas.py - Skills · Discovers and refreshes the local skill registry.
harness/co_math/skills.py - Handoffs · Records when a domain skill should take over part of the task.
harness/co_math/skill_handoff.py - Workspace · Initializes and maintains the repository-backed workspace layout.
harness/co_math/workspace.py
Persistent workspace
File-backed project state and research outputs.
- Project state · Top-level project metadata, goals, status, and communication log.
workspace/project - Goals · Formalized goals that must pass gating before workstreams begin.
workspace/project/GOALS.yaml - Workstreams · Approved goal-specific workstream folders for evidence production.
workspace/workstreams - Working paper · Final rendered paper assembled from reviewed reports.
workspace/final
Skill registry
Local extension layer for domain-specific methods and handoffs.
- Skill library · Domain-specific skill package used by the harness and agents.
.agents/skills/co-mathematician
Connections 25
- 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.