Run any Skill in Manus with one click

coral-debug

Stars768

Forks101

UpdatedJune 12, 2026 at 18:02

Verify and debug changes to CORAL itself — smallest reproduce loop per area (grader / daemon / CLI / hooks / manager / workspace / hub / template / config / web), where to look when something breaks (hung graders, agent restart loops, stalled agents, missing heartbeat actions, corrupted shared state, broken worktree symlinks, grader import errors, wrong-task resume), how to inspect a live or finished run under `.coral/public/`, and the canonical lint/test commands. Use when editing code under `coral/` or chasing a CORAL bug, NOT when adding a new task or extending the framework.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

Human-Agent-Society

Human-Agent-Society/CORAL

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

More from this repository

same repository

create-notes

Human-Agent-Society/CORAL

Write a note to {shared_dir}/notes/ that future agents can actually act on. Use after every coral eval, when a heartbeat (reflect / consolidate / pivot) asks for a note, or when you discover a grader / build / runtime issue that future agents will hit. Covers 4 note variants (experiment / infra / focus / synthesis), the required frontmatter with the team-level `creator:` filter, the structured-trace schema (`type` / `claim` / `status` / `confidence` / `based_on` / `evidence` / `supersedes` / `refutes` / `touched`) that populates the dashboard knowledge graph, the self-audit checklist (backfilled predictions, abandoned paths, sourced magic numbers, cross-links), the bundled `scripts/{stamp,lint,unattributed}.py` helpers, and the shell-escaping gotchas that silently strip markdown content. Trigger this skill whenever you are about to Write a file under notes/ — even if the prompt didn't say 'write a note'.

2026-07-01768

coral-new-task

Human-Agent-Society/CORAL

End-to-end recipe for adding a new task under `examples/` — the three pieces that have to line up (`task.yaml`, `seed/`, and `grader/`), what to put in each, the `TaskGrader` API surface, the `coral validate` → smoke-test loop, and the common mistakes (repo_path pointing at the wrong dir, score direction backwards, hidden answer keys leaking into seed/, grader writing to codebase_path which the daemon force-removes, private-vs-public confusion, missing `run()` signature). Use whenever the user wants to add a new CORAL task or port an existing benchmark into CORAL.

2026-06-24768

creating-a-coral-task

Human-Agent-Society/CORAL

Author a new CORAL task — the three pieces that must line up (`task.yaml`, `seed/`, a packaged `grader/`), the `coral init` → `coral validate` → smoke-test loop, and how to pick a grader pattern (stdout float, test pass-rate, ratio-vs-baseline, multi-metric, or an LLM rubric judge). Use whenever the user wants to create a CORAL task, write or wire a grader, port a benchmark into CORAL, score open-ended outputs (reports/memos) with a judge, or debug a grader that crashes on the seed / ranks the leaderboard backwards / leaks the answer key. Deep references for the TaskGrader API, grader patterns, rubric judges, and the full task.yaml schema live alongside this skill.

2026-06-24768

coral-quickstart

Human-Agent-Society/CORAL

The fast path from zero to a running CORAL experiment — what CORAL is and when to reach for it, installing the `coral` CLI, registering a runtime with `coral setup`, and the `.coral_workspace/` convention for pointing CORAL at code you already have and want optimized. Use this whenever the user asks "what is coral", "should I use coral for this", wants to install or get coral set up, hits a "command not found" for coral or doesn't have it installed yet, or says "use coral to optimize / speed up / improve this code" and you need the end-to-end onboarding from install to a launched run. Hands off to `setting-up-coral` (runtime bindings), `creating-a-coral-task` (grader authoring), and `running-coral-experiments` (operating a run) for depth.

2026-06-23768

running-coral-experiments

Human-Agent-Society/CORAL

Run and manage CORAL experiments from the operator side — launch agents with `coral start` (dotlist overrides, model/count, tmux vs local), monitor with `coral status` / `coral log` / `coral show` / the web dashboard, and drive the loop with `coral resume` (inject instructions, fork from an attempt), `coral heartbeat` (tune reflection cadence), and `coral stop`. Use whenever the user wants to start a CORAL run, check on agents, read scores/leaderboard, steer or resume a run, diagnose agents that keep restarting or fail every eval, scale to more agents or islands, or stop a run. Deep references for steering/heartbeat tuning and scaling/troubleshooting live alongside this skill.

2026-06-23768

setting-up-coral

Human-Agent-Society/CORAL

One-time machine setup after installing the `coral` CLI — register local agent runtimes as named bindings with `coral setup` / `coral setup agent`, validate them with `coral agents doctor` (incl. a live hello-ping that catches expired auth and model typos), and reference them from a task via `agents.binding`. Use when the user is configuring which agent runtimes/models coral can use, hits a "runtime not found" / auth error when starting a run, or asks how to set up claude/codex/cursor for coral.

2026-06-23768

name

coral-debug

description

CORAL debug & change-verification workflows

This skill is for people (and Claude Code) hacking on the CORAL package itself, not for users authoring a task. For authoring guides see the siblings:

coral-new-task — creating a new examples/<task>/ (seed + task.yaml + grader)
coral-extend — extending CORAL itself (new runtime, new CLI command, new bundled skill, ...)

Reproduce loops

Pick the smallest one that exercises your change.

Editing...	Fastest reproduce
`coral/grader/{task_grader,loader,subprocess_grader}.py` or a builtin grader	`uv run coral validate examples/circle_packing` (or any example with a packaged grader)
`coral/grader/daemon.py` (parallel grading, queueing, worktree isolation)	`uv run pytest tests/test_grader_daemon.py -v`
`coral/grader/{base,protocol}.py`	`uv run pytest tests/test_grader.py tests/test_subprocess_grader.py -v`
`coral/cli/*.py` (argparse, dispatch, output formatting)	Run the command directly: `uv run coral log --help`, `uv run coral status`, etc. against a `latest` run under `examples/<task>/results/`
`coral/hooks/post_commit.py` (`submit_eval`)	`uv run pytest tests/test_hooks.py -v`, then end-to-end via `coral start -c task.yaml agents.count=1` and watch `.coral/public/attempts/`
`coral/agent/manager.py`, `state.py`, `exit_classifier.py`	`uv run pytest tests/test_manager_reliability.py tests/test_manager_seen_attempts.py -v`
`coral/agent/builtin/*.py` (a runtime)	`uv run pytest tests/test_<runtime>.py` if it exists, then `coral start -c task.yaml agents.runtime=<name> agents.count=1`
`coral/workspace/{project,worktree,repo,grader_env}.py`	`uv run pytest tests/test_workspace.py tests/test_grader_env.py -v`
`coral/hub/{attempts,notes,skills,checkpoint,heartbeat}.py`	`uv run pytest tests/test_hub.py tests/test_checkpoint.py tests/test_heartbeat.py -v`
`coral/template/coral_md.py` or templates	`uv run pytest tests/test_template.py -v`
`coral/config.py`	`uv run pytest tests/test_config.py -v`
`coral/web/*` (dashboard)	`uv run coral ui` against any existing run; reload the browser after edits

End-to-end smoke (slow but exercises the whole pipeline):

uv run coral start -c examples/circle_packing/task.yaml agents.count=1 run.session=local
# Wait for one eval to land in .coral/public/attempts/, then:
uv run coral stop

Where to look when X breaks

Symptom	First place to look
Grader hangs / pending attempts pile up	`.coral/public/grader_daemon.pid` (is daemon alive?), `.coral/public/grader_daemon_heartbeat` (mtime), `.coral/public/eval_logs/<hash>/` for grader stdout/stderr
`coral eval` errors out	The pending JSON itself: `.coral/public/attempts/<hash>.json` — `status` and `feedback` fields. Source: `coral/hooks/post_commit.py::submit_eval`
Agent restart loop	`coral status` shows pause state. Source: `coral/agent/manager.py` (`restart_burst_threshold`, `restart_burst_window`). Per-agent runtime stdout/stderr is captured under the worktree.
Stalled agent	`agents.timeout` watchdog in `coral/agent/manager.py`. Grader-queue exemption (`grader_pending_max_age`) skips the watchdog while a recent submission is still pending.
Heartbeat actions not firing	`.coral/public/heartbeat/<agent_id>.json` (per-agent action list), `.coral/public/eval_count` (global counter). Logic: `coral/agent/heartbeat.py::HeartbeatRunner.check`.
Shared state corrupted / race	`.coral/public/.git/` is a real git repo — `git -C .coral/public log` shows checkpoint history; `coral notes --history` is the friendly view.
Worktree symlinks missing	`coral/workspace/worktree.py` — symlinks `.coral/public/` into each agent worktree under the runtime-specific name (`.claude` / `.codex` / `.opencode`).
Grader can't import its package	Check `.coral/private/grader_venv/` — `setup_grader_env` ran `uv venv` + `grader.setup` once at run start. Re-running `coral start` on the same `run_dir` does NOT re-bootstrap; delete the venv to force it.
Resume picks up wrong task	`coral resume` reads `.coral/config.yaml` and `.coral/config_dir`. The `latest` symlink at `results/<task-slug>/latest` decides which run is resumed.

Inspect a live or finished run

RUN=$(readlink -f results/<task-slug>/latest)
ls "$RUN/.coral/public/"            # attempts/, notes/, skills/, agents/, logs/, eval_logs/, eval_count
cat "$RUN/.coral/public/attempts/<hash>.json" | jq .
ls "$RUN/agents/"                    # one worktree per agent
cat "$RUN/.coral/config.yaml"        # exact config used (post-merge)

The web dashboard (coral ui) reads the same files; if you're debugging dashboard rendering, coral/web/api.py is the route handler and coral/web/static/ is the built React bundle.

Test + lint

uv sync --extra dev                  # one-time, gets pytest + ruff
uv run pytest tests/ -v              # full suite (~seconds, no docker)
uv run pytest tests/test_<thing>.py -v -k <pattern>
uv run ruff check .                  # lint
uv run ruff format .                 # autoformat

There is no separate type-check step in CI yet; tests cover the contract.

Quick task scaffold for ad-hoc testing

When you need a throwaway task to exercise a code change:

uv run coral init /tmp/coral-scratch
# edit /tmp/coral-scratch/grader/src/coral_scratch_grader/grader.py to return a simple float
uv run coral validate /tmp/coral-scratch
uv run coral start -c /tmp/coral-scratch/task.yaml agents.count=1 run.session=local

coral validate runs the grader against seed/ in a tempdir without spawning agents — the fastest way to confirm a grader change compiles and produces a Score.

Conventions

No git from agents. All commits go through coral eval. If you're adding a feature that needs to commit, route it through coral/hooks/post_commit.py or coral/hub/checkpoint.py.
Atomic writes for any JSON in .coral/public/. Use coral.hub.attempts.write_attempt (tmp + rename) as the model.
Idempotent setup. setup_run_dir, setup_grader_env, init_checkpoint_repo must all be safe to call twice.
Shared dir is configurable. Don't hardcode .claude; thread shared_dir through (see coral/template/coral_md.py).
Lazy imports in CLI dispatch (coral/cli/__init__.py) — keep coral --help fast.