Handing Off IDE Work to the Chat Agent: Passing Context Through a File After the Two-App Split

A Script That Validates the Brief's Freshness and Consistency

Just placing a file guarantees you will eventually get a stale brief — you kept editing in the IDE, but updated_at stayed old. So I wrote a script that mechanically checks whether the brief has fallen out of sync with the actual work. It is written in Node, but what it does is simple.

// scripts/check-handoff.mjs
import { readFileSync } from "node:fs";
import { execSync } from "node:child_process";
 
const raw = readFileSync(".antigravity/handoff.md", "utf8");
const fm = raw.match(/^---\n([\s\S]*?)\n---/);
if (!fm) {
  console.error("❌ handoff.md has no frontmatter");
  process.exit(1);
}
 
// Minimal YAML read (self-rolled to avoid adding a dependency)
const meta = {};
let key = null;
for (const line of fm[1].split("\n")) {
  const kv = line.match(/^(\w+):\s*(.*)$/);
  const item = line.match(/^\s*-\s*(.*)$/);
  if (kv) { key = kv[1]; meta[key] = kv[2] ? kv[2].replace(/^"|"$/g, "") : []; }
  else if (item && Array.isArray(meta[key])) meta[key].push(item[1].replace(/^"|"$/g, ""));
}
 
const problems = [];
 
// (1) Freshness: is the brief's updated_at older than any touched file's last change?
const touched = Array.isArray(meta.touched) ? meta.touched : [];
const briefTime = new Date(meta.updated_at).getTime();
for (const f of touched) {
  try {
    const mtime = execSync(`git log -1 --format=%cI -- "${f}"`).toString().trim();
    if (mtime && new Date(mtime).getTime() > briefTime) {
      problems.push(`Stale: ${f} changed after the brief was updated`);
    }
  } catch { /* uncommitted is covered separately by status */ }
}
 
// (2) Consistency: done, yet open_checks remain?
const checks = Array.isArray(meta.open_checks) ? meta.open_checks : [];
if (meta.status === "done" && checks.length > 0) {
  problems.push(`status is done but ${checks.length} checks remain`);
}
 
// (3) Explicit recipient
if (meta.status === "ready_for_verify" && !meta.handoff_to) {
  problems.push("awaiting verification but handoff_to is empty");
}
 
if (problems.length) {
  console.error("🛑 The handoff brief has problems:");
  for (const p of problems) console.error("  - " + p);
  process.exit(1);
}
console.log("✅ The handoff brief is consistent with the current work");

The script compares the last commit time of each file in touched against the brief's updated_at to see whether the brief has been left behind. It also rejects the self-contradiction of remaining checks while marked done. I run it both in a pre-commit hook and at the moment the chat side receives the work. It once caught exactly the drift I feared — I had touched content.ts afterward but forgotten to update the brief.

Pinning "Update the Brief When Done" Toward Determinism with a Guide Skill

The built-in Guide skill added in the 6/26 update is good at making an agent reproduce a recurring procedure. I pinned the procedure "when you reach a stopping point, update handoff.md and pass check-handoff before handing off" into it. Rather than trusting the agent's goodwill, it is a scaffold that makes it walk the same order every time.

# .antigravity/guides/handoff.md
name: handoff-brief
description: The handoff procedure to run before passing work to another app or agent
 
steps:
  - Reflect changed files into the frontmatter's touched list
  - Re-select status from in_progress / ready_for_verify / done
  - List checks not yet run under open_checks (no guessing them away)
  - Update updated_by and updated_at to the current actor and time
  - Run `node scripts/check-handoff.mjs`, confirm ✅, then hand off

Because a Guide skill works advisorily, I do not make it the sole gate; I always sandwich the final check-handoff.mjs as a deterministic backstop. The skill prompts the procedure, the script guarantees the result — a two-stage split. Since adopting this division, the mismatch where the brief advances on one app while the other stays stale has all but disappeared.

Avoiding "Taking It at Face Value" on the Receiving Side

When I have the chat-style agent read the brief, I add a line that keeps it from believing the contents outright. The brief is only the sender's claim, not a guarantee of fact. Concretely, I place constraints like these in the receiving prompt.

Shaping it so "the receiver re-checks the given assumptions from the ground up" means the verification net catches things even when the brief is a bit sloppy. Conversely, writing quick key points and confirming on the receiving side fit the speed of solo development better than laboring to write a perfect brief.

Pitfalls I Noticed in Operation

Running this for about two weeks surfaced a few things.

First, do not get greedy about the brief's granularity. Stuff several tasks into one file and it becomes unclear which open_checks belongs to which work. I commit to one brief per unit of work, mark it status: done when finished, and treat it as archived.

Second, if the two apps' time references drift, the updated_at comparison breaks. Always write the brief's time as ISO 8601 with a timezone (+09:00), and I aligned the script to git log's commit time (%cI) as well. Write a bare time string and this freshness check becomes meaningless.

Finally, treat the brief as a "map of the current position," not a replacement for conversation history. Try to record the entire past, and you have merely built a long history in another place. Narrowing to two points — where we are now and where we go next — made cross-app handoff dramatically lighter.

I take the tooling splitting into two apps, IDE and chat, as a positive: a place has appeared for a human to explicitly put context. Start by dropping a single .antigravity/handoff.md into your repo and passing check-handoff.mjs once. Cross-app handoff will start from confirmation instead of re-explanation.