handoff-new-window

English | 简体中文

handoff-new-window is a cross-window and cross-CLI task handoff skill for Codex (including multi-account profiles like codex-a), Pi, Antigravity CLI (agy), Claude Code (cc), and Grok CLI (grok).

It turns a single $handoff-new-window invocation into two synchronized deliverables:

1. A persisted, structured HANDOFF.md state-transfer package on disk (the single source of truth for detailed task context).
2. A self-contained, copy-ready 【发给新窗口的完整接力 Prompt】 block printed directly in chat—so the user never has to manually re-explain file ownership, dirty-worktree avoidance, settled corrections, ruled-out dead ends, or governance/review boundaries when switching windows or agents.

---

Highlights

• Dual-Deliverable Closeout by Default: Stops replying with a bare one-line file pointer. Always persists HANDOFF.md and outputs a structured startup prompt block in chat that 100% matches the saved file's mode, permissions, SHA-256 snapshot, and next_action.
• Orthogonal Handoff Modes (handoff_scope × receiver_task): Cleanly separates write/mainline ownership scope (full-takeover vs. scoped-slice) from receiver task type (implement-and-close, plan-to-bugfix, diagnose-or-review-only), preventing side-slice or diagnostic handoffs from accidentally freezing the sender's mainline work.
• Write Ownership & Handoff Snapshot (Not a Fake OS Lock): Records worktree, branch, HEAD, per-file shasum -a 256 (non-existent for deleted or not-yet-created files), read-only reference files, and an explicit Do-Not-Touch Avoid List for other windows' or colleagues' dirty files with recorded ownership basis (用户声明 <name> / 台账登记 / 归属未知).
• Anti-Rework Dual Ledger: Separates Settled Decisions & User Corrections (which must not be reopened without fresh counter-evidence and the applicable decision flow) from Ruled-Out Technical Dead Ends (failed hypotheses and misleading clues with environment/evidence).
• Governance & CCG-016 Review Boundary Preservation: References canonical docs/agent-collab/<change-id>/status.md without duplicating mutable contract state. Separates handoff_package_status from governance_binding_status, enforces read-only preparation when binding is pending (待绑定) or write_authorized=no, and preserves all six CCG-016 review assignment elements using canonical governance values.

---

Why It Exists

When a coding session hits context limits, model quota exhaustion, or a specialized blocker that needs another CLI, ad-hoc handoffs frequently fail in predictable ways:

• Prompt Drift: A bare "Read HANDOFF.md and continue" gives the new window no immediate role anchor, permission gate, or first-step boundary before it starts scanning or editing files.
• Concurrent File Collisions: In multi-window or multi-developer workspaces, the receiving agent may accidentally overwrite, stage, or revert uncommitted changes belonging to another window or colleague.
• Re-litigating Settled Corrections: Without a dedicated ledger of user corrections and architectural decisions already aligned during the session, the new agent often reverts to the exact flawed approach the user already corrected.
• Governance & Review Breakage: Handing off a governed task (openspec-superpower-change / codex-brief-antigravity-review) without distinguishing package delivery from instance binding causes unauthorized status.md edits or malformed review assignments.

handoff-new-window eliminates repetitive manual prompting by baking all of those guardrails directly into the skill contract.

---

Orthogonal Handoff Modes

Every handoff is classified along two orthogonal dimensions—handoff_scope and receiver_task—and exposed through three intuitive user-facing modes:

Mode	handoff_scope	receiver_task	Typical Scenario	Sender Window Post-Handoff Rule
Mode 1 · 全权接力闭环 (Full Takeover)	full-takeover	implement-and-close	Context is heavy or quota is low; move the entire remaining task to a new window/CLI to finish and close out.	Immediately stop writing to all handed-off task files; freeze mainline execution in the sender window.
Mode 2 · 局部支线/卡点拆单 (Scoped Slice)	scoped-slice	implement-and-close or diagnose-or-review-only	Delegate a specific sub-module, environment blocker, or side investigation to another agent while keeping the mainline here.	Stop writing only to the delegated slice files; retain mainline ownership in the sender window and define merge-back criteria.
Mode 3 · 定位方案转交修复 (Diagnosis-to-Bugfix)	full-takeover or scoped-slice	plan-to-bugfix	Sender completed root-cause analysis and fix design; export the evidence chain and plan for another agent to implement.	Export full root-cause evidence chain, ruled-out clues, and target diff plan; explicitly record write_authorized=yes | no.

Important: Diagnosis alone never grants code-modification authority. When write_authorized=no or governance_binding_status=待绑定, both HANDOFF.md and the chat startup prompt restrict the receiver to read-only verification/preparation until authorization or rebinding is completed.

---

Dual-Deliverable Protocol

Sender Window ($handoff-new-window)
  ├─ 1. Inspect git status --short, branch, HEAD, and shasum -a 256 of target files
  ├─ 2. Classify Mode (handoff_scope × receiver_task) + write_authorized + governance_binding_status
  ├─ 3. Write canonical HANDOFF.md to disk (project-local, user-named, or ~/.codex/handoffs/)
  └─ 4. Output in chat:
        ├─ Deliverable 1: Saved path + sender write-freeze confirmation + non-acceptance disclaimer
        └─ Deliverable 2: Copy-ready 【发给新窗口的完整接力 Prompt】 markdown block

Receiver Window (Cold Start)
  ├─ 1. Read HANDOFF.md + applicable AGENTS.md / CLAUDE.md + required skills
  ├─ 2. Verify Write Ownership Snapshot (branch, HEAD, writable file SHA-256, avoid list)
  ├─ 3. Check permission gates (write_authorized=yes & governance_binding_status != 待绑定)
  ├─ 4. Execute exact next_action without repeating completed items or reopening settled decisions
  └─ 5. Run required verification & cross-review (preserving CCG-016 six elements)

---

Key Guardrails In Detail

1. Write Ownership & Handoff Snapshot (Section 4)

Hashes and git status are treated honestly as a verification snapshot, not an OS-level file lock. Both sender and receiver enforce a three-bucket file table:

Bucket	Sender Rule	Receiver Rule
4.1 移交可写文件 (Transferred Writable Files)	Stop writing immediately after generating the handoff.	Verify current shasum -a 256 matches snapshot (non-existent for deleted/new files) before first edit. If drifted, pause edits on that file and report.
4.2 只读参考文件 (Read-Only Reference Files)	Keep unchanged.	Read for contracts/context only; never modify.
4.3 避让文件 (Do-Not-Touch Avoid List)	Record explicit ownership basis (本会话外修改 / 用户声明 <name> / 台账登记 / 归属未知).	Never edit, format, git checkout, git restore, or stage. If a dirty file blocks the current step, pause the conflicting file and continue independent items.

2. Anti-Rework Dual Ledger (Section 3)

• 3.1 已与用户对齐定案 / 纠正记录 (Settled Decisions & User Corrections): Records the decision/correction, its basis (user instruction, empirical test, architectural constraint), scope, and explicit reopen condition (fresh counter-evidence, environment change, or new user instruction).
• 3.2 已踩坑 / 定位死胡同 (Ruled-Out Dead Ends): Records failed approaches or misleading clues, the exact environment and evidence proving why they failed, and the safer alternative direction.

3. Governance & CCG-016 Six-Element Preservation (Section 6)

• Canonical Contract Reference: When a task is governed by openspec-superpower-change, the sole mutable contract is docs/agent-collab/<change-id>/status.md (while openspec/changes/<change-id>/ holds proposal/specs/tasks). HANDOFF.md references its path, schema, batch, attempt, and SHA-256 without copying mutable contract blocks.
• CCG-016 Canonical Values: Every review or return-review instruction preserves all six elements:
  • review_purpose: e.g. Preflight Review, Implementation Review, Final Review
  • reviewer_product: codex, pi, antigravity-cli, grok-cli (never a vague "other agent")
  • reviewer_role: independent-reviewer (gate-bearing) or advisory-reviewer (advisory)
  • capability_profile: control-plane-high
  • independence_requirement: distinct-contract-instance (gate-bearing) or advisory-not-gate-bearing (advisory)
  • result_authority: governed-review-evidence (gate-bearing) or advisory-input (advisory)
  • Focused R2+ session reuse (same_reviewer_instance) is recorded in a separate field and never replaces executor–reviewer instance independence. Unresolved fields remain explicitly marked as 待解决（unresolved）.

---

Output Locations

1. Project-defined location: Follows the project's AGENTS.md / CLAUDE.md handoff contract (including external Obsidian/workbench paths when required).
2. User-named path: e.g. HANDOFF.md or HANDOFF-<topic>.md resolved from the repository root.
3. Global fallback (used only when neither project-local nor user-named path applies):
   • ~/.codex/handoffs/YYYY-MM-DD-HHMM-<repo-or-topic>.md
   • ~/.codex/handoffs/latest.md

---

Repository Structure

.
├── .gitignore
├── AGENTS.md
├── README.md
├── README_cn.md
├── SKILL.md
├── docs/
│   ├── engineering-invariants.md
│   └── learning-candidates/
│       └── 2026-11-04-handoff-dual-deliverable-and-governance-invariants.md
└── tests/
    └── test_handoff_skill_contract.py

---

Installation & Multi-CLI Sync

Link this repository into your primary Codex skills directory and synchronize across runtimes:

ln -s /path/to/handoff-new-window "${CODEX_HOME:-$HOME/.codex}/skills/handoff-new-window"

In a multi-CLI environment (codex, codex-a, pi, agy, cc, grok), symlink ~/.codex/skills/handoff-new-window, ~/.agents/skills/handoff-new-window, ~/.pi/agent/skills/handoff-new-window, ~/.gemini/antigravity-cli/skills/handoff-new-window, and ~/.claude/skills/handoff-new-window to this canonical repository so every agent loads the exact same revision.

---

Validation

Run the contract unit test suite (including section-scoped assertions and in-memory mutation probes) and quick_validate.py after any edit:

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v
"${PYTHON_BIN:-python3}" "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" .

---

Example Prompts

$handoff-new-window 当前上下文太重，全权交接给新窗口继续并闭环。

$handoff-new-window 只把当前子模块卡点拆单交接给 pi 分析修复，主线任务还是留在本窗口继续。

$handoff-new-window 梳理问题背景、定位证据链、已排除死胡同和修复方案，生成 Mode 3 交接包发给其他窗口执行 bugfix。