co-mathematician

name	co-mathematician
description	Use when conducting a coding-agent-driven mathematical research project that needs durable workspace state, approved goals, parallel workstreams, reviewer gates, provenance, uncertainty tracking, failed exploration records, and a final working paper.

Co-Mathematician

Use this skill to run mathematical research as a stateful coding-agent workspace. The repository-aware coding agent remains the driver; do not implement a new platform. The harness is only for state, schema, gates, report skeletons, and validation.

Agent Model

• The active main conversation/session in the chosen coding agent is the Project Coordinator.
• Platform examples: Codex main thread, Claude Code main conversation, Cursor active Agent chat/session.
• The repository filesystem is the shared artifact store.
• Project-local skills under .agents/skills/ are the default skill environment.
• agents/roles/ is the canonical role layer.
• .codex/agents/, .claude/agents/, and .cursor/rules/ are platform adapters.
• Native subagents, task agents, Cursor Agent sessions, or separate reviewer passes are workstream coordinators, specialized agents, and reviewers.
• If native subagents are unavailable, create an independent reviewer pass with a fresh prompt and save the review artifact under the workstream reviews/ directory.
• No agent may self-approve its own report.

The harness provides cooperative-workflow integrity, not hostile-writer authorization. Locks, schemas, lifecycle commands, and completion manifests detect inconsistent or modified artifacts, but caller-provided actor and run IDs are not cryptographic identities. Use host-issued identities when the coding-agent platform exposes them.

Adapter Architecture

Use agents/roles/ as the authoritative role definitions. Platform-specific adapters may use different formats, but must preserve the same boundaries:

agents/roles/       canonical role cards
.codex/agents/      Codex TOML adapters
.claude/agents/     Claude Code Markdown subagent adapters
.cursor/rules/      Cursor project-rule adapters

Adapters must not approve goals, start unapproved workstreams, mark workstreams complete, or let a report author approve their own report.

Project-Local Skill Environment

Install or copy additional research skills into this repository's .agents/skills/ directory by default. This keeps AI4Math skill libraries and project-specific research workflows portable with the workspace.

Use global skill roots such as ~/.codex/skills or ~/.agents/skills only when the user explicitly asks for a personal installation shared across projects. Do not assume that a global skill install is visible to every coding agent or collaborator who opens this repository.

Refresh the project-local skill registry at session start, after installing or copying skills, and before formalizing goals:

PYTHONPATH=. python3 -m harness.co_math.cli refresh-skills --workspace workspace

Before proposing goals or creating a workstream, match the scope against the registry:

PYTHONPATH=. python3 -m harness.co_math.cli suggest-skills --workspace workspace --query "..."

If a relevant project-local skill is suggested, read its SKILL.md before planning the goal or workstream. This is a workspace-level discovery contract; it does not replace the coding agent's native skill registry.

Workflow Modes

Workspace Mode

Use the full Co-Mathematician sequence when no project-local domain Skill is driving the task:

onboarding -> research question formalization -> goal approval -> workstreams -> reviewer loop -> final working paper

Skill-Guided Mode

Use this when the user explicitly invokes a project-local Skill, or accepts a Skill suggested by co-math suggest-skills. The domain Skill controls the inner workflow: opening question, modeling route, approval rules, execution plan, and domain-specific artifacts.

Record the handoff:

PYTHONPATH=. python3 -m harness.co_math.cli skill-handoff \
  --workspace workspace \
  --skill optimization-skill \
  --mode skill_guided \
  --reason "ODL is a Stiefel manifold optimization problem." \
  --query "orthogonal dictionary learning Stiefel optimization" \
  --skill-path ".agents/skills/optimization-skill/SKILL.md"

In skill-guided mode, do not force the default onboarding-goal-workstream sequence before the domain Skill's own first response or modeling checkpoint. Promote the task to approved goals and workstreams only when the user wants durable research output, reviewer-gated claims, or a final working paper.

Quick Skill Mode

Use this for a small one-off Skill task. Record it with --mode quick_skill. No workstream is required unless the user later promotes it into a research project.

Non-Negotiable Boundaries

• Do not solve the math problem during onboarding.
• Ask the user to choose a workspace document language policy during workspace-mode onboarding.
• Do not start a workstream until the user explicitly approves a goal.
• Do not mark a workstream complete until an independent reviewer approves its report.
• Do not hide uncertainty, failed attempts, or missing provenance.

Onboarding

Collect enough context to write workspace/project/PROJECT.md:

• workspace document language policy
• problem statement and mathematical setting
• definitions, notation, constraints, and allowed assumptions
• known references and user-provided artifacts
• desired output type and unacceptable shortcuts
• user expertise, steering preferences, and review expectations

Record durable status in workspace/project/messages.jsonl. Keep user-facing chat high level; put detailed logs in files.

Recommended language policy options:

1. English for all workspace documents.
2. User language for research notes, English for schemas, gates, and reviews.
3. User language for all human-readable research documents.
4. Match each project or conversation.

Record the selected policy in workspace/project/PROJECT.md, workspace/project/PROJECT_STATUS.md, and the language_policy block of workspace/project/GOALS.yaml. Schema keys, gate names, statuses, and harness commands stay in English.

Research Question And Goals

Write a formal research question and proposed goals in workspace/project/GOALS.yaml. Goals begin as drafts. Ask the user to approve or revise them. Only goals with status: approved may receive workstreams.

In skill-guided mode, let the domain Skill collect or model the task first when its workflow requires that. Then summarize the result into goals only if the user wants to promote the Skill task into a durable research workstream.

Use:

PYTHONPATH=. python3 -m harness.co_math.cli approve-goal --workspace workspace --goal-id G1 --approved-by user --approval-id approval-G1-001
PYTHONPATH=. python3 -m harness.co_math.cli check-gate --workspace workspace --gate goal_approval --goal-id G1

Workstreams

Create workstreams only after goal approval:

PYTHONPATH=. python3 -m harness.co_math.cli new-workstream --workspace workspace --goal-id G1 --title "..." --kind proof --author-run-id proof-run-001

Valid kinds are proof, computation, literature, and review.

Workstreams must write durable artifacts:

• WORKSTREAM.md for scope
• plan.md for route
• notes.md for running observations
• messages.jsonl for internal messages
• artifacts/ for code, tables, figures, proof sketches, or citations
• failures/ for dead ends and rejected attempts
• reviews/ for independent reviewer output
• reviewed/completion-manifest.json for the frozen goal/report/review evidence bundle
• report.md for the reviewed workstream report

Internal Messages As JSONL

Each message must include:

{
  "timestamp": "...",
  "sender": "...",
  "recipient": "...",
  "type": "status",
  "content": "...",
  "provenance": [],
  "uncertainty": []
}

Use message types: status, instruction, question, proposal, decision, artifact, review, failure.

Provenance And Uncertainty

Every important claim must be traceable to one or more of:

• user input
• literature reference
• internal artifact
• computation output
• proof sketch
• reviewer comment
• failed exploration

Reports must contain explicit Provenance, Uncertainty, and Failed Explorations sections.

Reviewer Loop

Send each workstream report to an independent reviewer subagent, task agent, or fresh reviewer pass. Reviewers return decision fields and checked artifact paths; the Project Coordinator persists them through co-math submit-review, which adds run, time, report-hash, and artifact-hash fields and validates the complete record against assets/reviewer_output_schema.json.

Persist the result through the harness so schema, reviewer-run independence, and the current report SHA-256 are enforced. Pass each code, data, or computation file used by the reviewer with --checked-artifact <workstream-relative-path> so its digest is bound to the review and completion manifest:

PYTHONPATH=. python3 -m harness.co_math.cli submit-review \
  --workspace workspace \
  --workstream-id <id> \
  --reviewer logic_reviewer \
  --reviewer-run-id review-run-001 \
  --approved --severity info --issue-type logic \
  --comment "Approved."

If review fails:

• preserve the review in reviews/
• revise or escalate
• keep unresolved uncertainty visible
• do not mark the workstream complete

If a later reviewer pass resolves a blocking review, preserve both reviews and submit an approved independent follow-up with --resolves <blocking-review-file>.json. Unapproved or report-stale reviews cannot resolve blockers.

Use:

PYTHONPATH=. python3 -m harness.co_math.cli check-gate --workspace workspace --gate workstream_readiness --workstream-id <id>
PYTHONPATH=. python3 -m harness.co_math.cli complete-workstream --workspace workspace --workstream-id <id>
PYTHONPATH=. python3 -m harness.co_math.cli check-gate --workspace workspace --gate workstream_completion --workstream-id <id>

Final Working Paper

Render a generated draft only from immutable reviewed snapshots:

PYTHONPATH=. python3 -m harness.co_math.cli render-final --workspace workspace

The harness output is workspace/final/generated_draft.md. A synthesis agent may turn it into workspace/final/working_paper.md; the harness does not overwrite that synthesized working paper.

Assets

Use templates in assets/ when creating project files, goals, workstreams, reports, or reviewer output.