git:20260610.d3a7849 to git:20260829.0838b35

- 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.

- 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.

-

- ## Adapter Architecture

-

- Use `agents/roles/` as the authoritative role definitions. Platform-specific

- adapters may use different formats, but must preserve the same boundaries:

-

- ```text

- 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:

-

- ```bash

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

- ```

-

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

- registry:

-

- ```bash

- 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:

-

- ```text

- 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:

-

- ```bash

- 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:

-

- ```bash

- PYTHONPATH=. python3 -m harness.co_math.cli check-gate --workspace workspace --gate goal_approval --goal-id G1

- ```

-

- ## Workstreams

-

- Create workstreams only after goal approval:

-

- ```bash

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

- ```

-

- 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

- - `report.md` for the reviewed workstream report

-

- ## Internal Messages As JSONL

-

- Each message must include:

-

- ```json

- {

- "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 should output JSON matching `assets/reviewer_output_schema.json`.

-

- 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. Mark

- the follow-up reviewer JSON with `resolves: ["<blocking-review-file>.json"]`, or

- mark the original review with `resolved: true`, so the completion gate can

- distinguish archived blocking feedback from unresolved blockers.

-

- Use:

-

- ```bash

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

- ```

-

- ## Final Working Paper

-

- Render final output only from reviewed workstream reports:

-

- ```bash

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

- ```

-

- The final output is `workspace/final/working_paper.md`. It is a working paper, not a chat summary.

-

- ## Assets

-

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