sdewell/clodball-skill

> Purpose: what clodBall is, how to install it, and how to use it. Use: read first; update when the install or the invocation changes.
clodBall is a handoff routine for two coding agents, Claude Code and
Codex, working one project together. It is one append-only file per
project, one skill both agents read, and one small watcher script that
wakes an agent when the other hands it the ball. The ball is the Ball:
line every entry carries. Nothing here is a lock, a queue, or an
authority: a peer's entry is a peer's judgment, and the user's word
still arrives through the user.
## Install
The skill is the directory skills/clodBall: a
SKILL.md and the watcher at scripts/clodball-watch. Put that
directory, or a symlink to it, where your agents discover skills:
Claude Code: ~/.claude/skills/clodBall
Codex: ~/.agents/skills/clodBall
One symlink into this checkout serves both hosts when they share a
skills directory. The skill calls the watcher relative to its own
directory, so it works wherever it is installed. bin/clodball-watch
in this repo forwards to the same script for callers that use that path.
The handoff file is never committed. Add .review/HANDOFF.md to the
repo's .gitignore, or /.review/HANDOFF.md to your global git
ignore file. The skill proves the ignore with git check-ignore before
it writes.
VERSION holds the release version; each release is also a tag v .
## Before the first kickoff: the project's plan
The handoff file is the conversation; the project's plan is the record.
Before project work begins, the skill instructs the agents to check
that the project's plan states the goal and the current state; either
agent can help prepare or update it. The kickoff entry points to the
plan section that holds them. The checklist below is more than that
minimum and makes a complete kickoff easier to write:
Goal. One sentence an agent can check against.
Current state. What exists now and what is known to be broken.
An agent that reads only this section should be able to continue.
Completion check. The command, file, or landed PR that proves
the goal met. The kickoff's Done-when: line must agree with it.
Next step. The one thing to do next, so the first Ask: is
concrete.
Who does what. Which parts Claude builds and reviews, and which
parts Codex builds and reviews. The kickoff's two Owns: lines must
agree with it. A split by artifact, one owner per file or component
with the other as its reviewer, is a recommendation; it does not
replace the project's own rules for concurrent edits and worktrees.
For concurrent edits, use separate working directories, such as git
worktrees, and leave the peer's working directory untouched.
Handoff path, optional. A line Handoff: in the
project's PLAN.md (that file specifically; the skill reads it from
nowhere else) moves the handoff file away from the default
/.review/HANDOFF.md.
If the goal or current state is missing, the kickoff's first Ask: is
to update the plan. The kickoff must also carry its completion check,
ownership, and first concrete ask. Watchers keep checking while that
preparation is completed. Rewrite the current state and next step as