claude-code-workflow
superkaiba/claude-code-workflow
Extracted Claude Code agentic workflow (agents, skills, rules) from explore-persona-space
Instalação
npx convez-ai superkaiba/claude-code-workflow1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
claude-code-workflow
A reusable Claude Code agentic research workflow, extracted from a live ML /
AI-safety research project that has run 650+ experiment tasks through it.
Drop the .claude/ directory, CLAUDE.md, scripts/, and
src/research_workflow/ into a research repo and you get an opinionated,
adversarial-review-driven lifecycle that runs from "proposed idea" to
"published clean result" — across multiple parallel, phone-visible Claude
Code sessions, with autonomous crash-recovered execution, a Claude+Codex
review ensemble, and a multi-cloud compute router.
This repo is periodically re-extracted from the live workflow as it evolves (first extraction May 2026; latest refresh 2026-06-16). It reflects the workflow as actually used: file-based task state (no GitHub-issue control plane), Happy Coder + tmux session orchestration, autonomous sessions with a watchdog cron, campaign-level orchestration, and ~58 control-plane scripts. Hard-won, incident-specific guardrails are kept verbatim — they document why each rule exists — so treat this as a battle-tested reference to adapt, not a turnkey framework.
What's inside
.claude/
agents/ # 27 agent files = 20 primary roles + 5 Codex twin reviewers
# + 2 deprecated (kept for history). Primary: planner, critic,
# consistency-checker, experiment-implementer, experimenter,
# implementer, code-reviewer, analyzer, interpretation-critic,
# clean-result-critic, follow-up-critic, methodology-writer,
# upload-verifier, uploader, follow-up-proposer,
# living-docs-updater, research-pm, reconciler,
# workflow-improver, retrospective. Codex twins: code-reviewer,
# critic, interpretation-critic, clean-result-critic,
# follow-up-critic.
skills/ # 22 skills: issue, issue-tick, adversarial-planner, campaign,
# campaign-tick, pm, clean-results (incl. the clean-result
# SPEC), promote-clean-result, group-promotion-queue,
# paper-plots, ideation, daily, weekly, experiment-runner,
# auto-experiment-runner, experiment-proposer,
# independent-reviewer, cleanup, refactor, deep-clean,
# codebase-debugger, mentor-update-slides
rules/ # 17 rules: workflow-fix-on-bug, agents-vs-skills,
# research-project-structure, code-style, gotchas,
# upload-policy, artifact-reuse, replication-fidelity,
# data-realism, on-policy-completions, background-automation,
# pod-config, arxiv-mcp + 4 domain-specific examples
hooks/ # PreToolUse guard scripts (log-dump guard) wired via
# settings.json
workflow.yaml # the state machine: statuses, marker schemas, gates,
# halt criteria, ensemble-review policy
settings.json # permissions + hooks (paths use $CLAUDE_PROJECT_DIR)
mcp.json # arxiv MCP servers
CLAUDE.md # top-level project instructions Claude Code loads every session
scripts/ # ~58 control-plane scripts (see below) + 6 placeholder
# experiment entrypoints (train.py, eval.py, ... — stubs you
# replace with your own pipelines)
src/research_workflow/ # the task-workflow library + compute-backend router
tasks/ # seeded empty task tree (REGISTRY.json) — ready for task.py new
tests/ # 49 test files pinning workflow invariants
Core ideas
1. The task tree is the control plane
Every experiment is a folder tasks/<status>/<N>/ holding body.md (YAML
frontmatter + body), events.jsonl (append-only progress markers),
comments.jsonl, plans/v{N}.md, and artifacts/. The folder's parent
directory IS the status:
proposed → planning → plan_pending → approved → running → verifying →
interpreting → reviewing → awaiting_promotion → completed | blocked | archived
All reads/writes go through scripts/task.py (CLI) or the importable
research_workflow.task_workflow library — atomic git mv status changes,
file-locked mutations, one commit per mutation. No HTTP, no tokens, no
GitHub-issue dependency; the git history is the audit log.
2. Adversarial review at every stage
- Plans (
/adversarial-planner): planner →scripts/verify_plan.py(mechanical pre-pass gate on plan shape) → fact-checker → critic ensemble ∥ consistency-checker → revise → user approval. Every load-bearing hyperparameter needs a recordedSource:; measurement validity is checked per dependent variable. - Code: experiment-implementer paired with an independent code-reviewer that never sees the implementer's reasoning.
- Results: analyzer ↔ interpretation-critic (content honesty), then analyzer ↔ clean-result-critic (15-lens structure/register/statistics gate).
- Follow-ups: a single-pass
follow-up-criticredundancy screen gates every proposed next experiment before it routes — duplicates of an existing task or a settled question are parked, never silently dropped. - Claude + Codex ensemble: five review sites (critic, code-reviewer,
interpretation-critic, clean-result-critic, follow-up-critic) run a Claude
reviewer and an OpenAI Codex twin in parallel; disagreements go to a
fresh-context
reconcilerwhose verdict is binding (scripts/codex_task.pyhandles dispatch).
3. Sessions: Happy Coder + tmux
The workflow runs as multiple parallel Claude Code sessions on one VM,
all visible (and drivable) from a phone via
Happy Coder (npm i -g happy-coder). The Happy
daemon runs each session as a background child — inside tmux when available —
registered with the Happy relay, so sessions survive SSH disconnects and show
up in the mobile app.
scripts/spawn_session.py— the canonical programmatic entry point. Talks to the daemon's localhost HTTP RPC (/spawn-session,/list,/stop-session; port from~/.happy/daemon.state.json):spawn-pm— the one PM session (queue triage + dispatch, never executes)spawn-issue --issue N [--auto]— per-experiment session;--autoboots/issue Nautonomously, auto-approves plans under a GPU-hour cap, and registers with the crash-recovery watcherspawn-campaign --issue N— campaign session orchestrating child issueslist/stop— enriched live-session view, issue mapping
scripts/patch_happy_daemon.py— surgically patches the vendored Happy daemon so its spawn RPC acceptsclaudeArgs(forwarded to the Claude Code subprocess in both the tmux and non-tmux spawn paths). This is what lets a fresh session boot directly into/issue 263. Idempotent, backs up the original,--check/--restoresupported.scripts/persona.sh— open a persistent daemon-spawned session by hand.- Autonomous sessions set
EPM_AUTONOMOUS_SESSION=1: no questions, every fork auto-resolves toward the task Goal; a PreToolUse hook hard-blocksAskUserQuestion. scripts/autonomous_session_watch.py(cron, every 10 min) — crash-recovery respawn, pod-safety reconciliation, stalled-session detection, zombie-wrapper reaping, auto-stop of sessions whose task is parked or terminal, plus a gate-push pass (phone notification on gate-park/blocked transitions via a pluggable notify script, transition-deduped) and a tick-runaway force-stop./issue-tick+/campaign-tick— lightweight 45-min backstop crons that re-drive a stale session without reloading the full skill; a healthy tick is onescripts/tick_triage.pycall (pure Python), and the 10-min watcher carries fast detection.scripts/session_progress_report.py/session_summarize.py/session_resolver.py— phone-facing titles and roll-up summaries.
4. Compute: multi-lane backend router
scripts/dispatch_issue.py + src/research_workflow/backends/ route every
launch by the task's backend: frontmatter across GCP, SLURM clusters, and
RunPod: credits-backed GCP first, free SLURM lanes as fallback, RunPod only as
an explicit opt-in (never auto — pinned by test). Pods are ephemeral by
design: provision → run → upload artifacts → upload-verification PASS →
auto-terminate. The pod fleet has its own lifecycle CLI (scripts/pod.py),
config single-source (scripts/pods.conf), stale-pod audit cron, and disk
guards.
5. Clean results, verified mechanically
Every experiment ends as a "clean result": the task body is promoted in place
to a spec'd markdown report (TL;DR → Motivation / What I ran / Findings with
one figure per finding → Reproducibility). scripts/verify_task_body.py
checks ~17 mechanical invariants; audit_clean_results_body_discipline.py
sweeps for banned statistical-framing anti-patterns; a findings-blind
methodology-writer agent generates a standalone methodology reference. The
full spec lives at .claude/skills/clean-results/SPEC.md.
6. The workflow improves itself
When any agent hits a bug caused by a gap in the workflow surface itself, it
emits a workflow-fix-candidate block; the orchestrator auto-spawns
workflow-improver in the background to apply, lint, review, and merge the
fix (.claude/rules/workflow-fix-on-bug.md). Hard-won lessons get pinned as
tests (tests/test_no_*), hooks, or always-on rules.
Adopting this in your repo
- Copy
.claude/,CLAUDE.md,scripts/,src/research_workflow/,tests/, andpyproject.toml(or merge the latter into yours; the package uses asrc/layout). - Search-replace the placeholders left by generalization:
your-project,Your Project,your-username,your.username,your-hf-username,your-github-username,dashboard.example.com,YOUR_RUNPOD_TEAM_ID,your-gcp-project,your-gcloud-config,your-cluster-user,your-slurm-account,<project-root>,user@example.com. The SLURM lane names (mila,nibi,fir) and cluster configs insrc/research_workflow/backends/slurm.pyare the source project's compute lanes — swap in your own clusters or drop the lanes you don't have. - Prereqs:
uv,gh,git,jq,ruff. Optional but recommended: Happy Coder + tmux (session layer), the Codex CLI plugin (ensemble review), RunPod / GCP / SLURM credentials (compute), the arxiv MCP servers (plan fact-checking). API keys live in.env— seesrc/research_workflow/orchestrate/env.py. - Patch the Happy daemon if you want prompt-booted sessions:
sudo uv run python scripts/patch_happy_daemon.py. - Arm the crons:
cron_autonomous_session_watch.sh(every 10 min),cron_worktree_audit.sh,cron_pod_audit.sh,cron_session_summarize.sh. - Create your first task:
uv run python scripts/task.py new --kind experiment --title "...", then run/issue <N>in a Claude Code session (oruv run python scripts/spawn_session.py spawn-issue --issue <N> --auto).
Conventions and caveats
- Namespace prefixes are kept.
epm:(event markers),EPM_*(env vars), and assortedeps/wftokens are the source project's namespace. They are load-bearing across scripts, hooks, tests, and docs — treat them as the workflow's namespace rather than renaming. - This is a reference extraction, not a polished framework. Scripts carry incident-hardened logic, dates, and issue numbers from the source project. They are kept deliberately: they document why each guardrail exists.
- Domain-specific rules are examples. Four rules files
(marker-leakage-measurement, marker-training-recipe, contrastive-negatives,
persona-distance-metrics) and parts of
CLAUDE.mdencode the source project's experimental lessons. Replace them with your domain's equivalents — the pattern of "hard-won lesson → always-on rule file" is the point. - Some agents/skills reference per-project docs (
docs/open_questions.md,RESULTS.md,docs/research_ideas.md) that you create as you go. - Experiment entrypoints are stubs.
scripts/train.py,eval.py,run_sweep.py,generate_wrong_answers.py,analyze_results.py, andrun_trait_transfer.pyare placeholders the agents/skills reference — wire up your own pipelines there. - Tests pin the workflow's invariants and pass out of the box
(
uv run pytest: 2323 passed, 20 skipped — the skips are repo-state-dependent tests that resolve live task ids, plus tests of the source project's training pipeline, which is not part of the extraction). None need live credentials.scripts/workflow_lint.pyalso passes on the template itself.