cross-harness-continuation

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. Do NOT use for fresh work with no prior agent's decisions to preserve, for a single-harness session that no one else is continuing, or as a general handoff-writing helper (see the session-handoff rule); this skill governs the contract between agents, not the notes one agent leaves itself.

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

1. Read CONTINUITY.json, the newest handoff, AGENTS.md/CLAUDE.md, and the current Git status. Treat the live checkout as authoritative over stale prose.
2. Verify the baseline commit, branch, dirty paths, and the claimed files. Preserve existing changes unless a test or the contract proves they are wrong.
3. Make one focused continuation change. Use Edit for existing files. Do not replace a whole file merely because another implementation is easier to write.
4. 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.
5. 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