| name | cross-harness-continuation |
| description | Use when work moves between Claude Code and Codex, a session resumes from a handoff, or an agent may rewrite an existing implementation. Loads the shared CONTINUITY.json contract, preserves accepted decisions, checks Git baseline and scope, and requires explicit replan mode for intentional redesign. |
Cross-Harness Continuation
Use this skill when a task continues after another agent, especially when the
handoff is Claude -> Codex, Codex -> Claude, or a plugin has already received
several partial fixes.
Operating contract
The repository is the source of truth for code. The continuation contract is
the source of truth for intent that Git cannot express:
<repo>/.claude/continuity/CONTINUITY.json
The canonical shape is in references/CONTINUITY.example.json. It must contain:
mode: continuation for incremental work, new for greenfield work;baseline: branch, commit, and paths that were already dirty at handoff;scope.files: the files explicitly claimed for the current slice;preserve: accepted design decisions and invariants;do_not_redo: approaches already tested or deliberately rejected;verification: commands and evidence status;scope.enforce and scope.protect_unlisted when the slice must be strict.
Required sequence
- Read
CONTINUITY.json, the newest handoff, AGENTS.md/CLAUDE.md, and
the current Git status. Treat the live checkout as authoritative over stale
prose.
- Verify the baseline commit, branch, dirty paths, and the claimed files.
Preserve existing changes unless a test or the contract proves they are
wrong.
- Make one focused continuation change. Use
Edit for existing files. Do not
replace a whole file merely because another implementation is easier to
write.
- Run the smallest relevant test, then the independent verifier for a
non-trivial or cross-module change. Record commands and outcomes in the
contract or handoff.
- Update the contract with what was preserved, what changed, what failed, and
the single next step. Commit a clean, descriptive checkpoint when the
project workflow allows it.
Replan boundary
Replanning is valid when measured evidence shows the current design is wrong,
the requirements changed, or an explicit user decision authorizes a redesign.
Declare it in the process that launches the agent:
AGENT_CONTINUITY_MODE=replan
AGENT_CONTINUITY_REASON=<specific evidence and intended redesign>
The reason is required. Without it, the guard blocks whole-file overwrites,
out-of-scope edits, and near-whole-file replacements. A replan must also be
recorded in the decision log/handoff; an environment flag alone is not proof.
Plugin cleanup
Do not revert a plugin because its code “looks different”. First classify the
diff as intentional, unverified, or conflicting; reconstruct the baseline from
Git; run the plugin's focused tests and a fresh read-only verifier; then repair
only confirmed regressions. Keep the old implementation available through Git
or an isolated worktree until the replacement passes its acceptance checks.
Gotchas
- A handoff without baseline and changed-file facts is context, not a merge
contract. Do not infer scope from prose alone.
- A clean Git tree does not prove semantic compatibility. Run the focused test
and inspect the dependency boundary before declaring continuation complete.
- Parallel agents need isolated worktrees and an integration verifier; this
skill protects serial handoff and cannot resolve a concurrent merge for you.
CONTINUITY.json is intentionally small. Put long research and transcripts
in the private archive or project docs and link them from the contract.
Troubleshooting
| Symptom | Cause | Fix |
|---|
No CONTINUITY.json found | The prior session left only prose handoff | Create the contract from the current Git baseline before editing existing code |
scope violation | The task expanded beyond the claimed slice | Finish the slice or update scope with a recorded reason |
blocks Write over existing tracked file | Whole-file overwrite would erase prior intent | Use a focused Edit, or explicitly enter replan mode |
near-whole-file replacement | An edit is acting like a rewrite | Split the edit and test each step, or replan with evidence |
| Claude and Codex disagree | No shared decision/evidence was recorded | Re-read preserve, do_not_redo, tests, and Git; do not “pick a side” by intuition |
