Agentflow

Agent Flow

You are the orchestrator. This skill hands a bounded coding task to a second, headless agy -p process — the implementer — running on a different model, in an isolated git worktree. You write the brief and own the judgment; the implementer does the typing in its own stateless run; you review the diff and land it yourself.

Unlike delegating to a separate third-party CLI, this stays entirely inside Antigravity's own stack: same binary (agy), same auth, same model catalog — just a second process with --model pointed at whichever model fits the task.

When NOT to use this

• The task is small enough to just do inline — spinning up a worktree and a background process isn't worth it for a two-line fix.
• agy isn't installed or authenticated (agy --version, agy auth login).
• You're not in a git repository — the isolation this skill relies on is a git worktree.

Prerequisites (check once)

1. agy --version succeeds.
2. node .agents/skills/agentflow/scripts/agentflow.mjs models lists the models available to your account/plan.
3. You're inside (or cd'd into) the target git repository, with a clean-enough working tree that git worktree add will succeed.

Choose the implementer model

agy -p has no safe default worth assuming — always pass --model explicitly. Two owners for this decision:

• The human owns which models are worth using for what, ideally stated once in the repo's AGENTS.md (e.g. "delegate mechanical sweeps to Gemini 3.5 Flash, subtle logic to Claude Sonnet 4.6"). Run node .agents/skills/agentflow/scripts/agentflow.mjs models to see the exact slugs your account can use — don't guess a display name into --model.
• You, the orchestrator, pick per task from that set: a fast/cheap model for a mechanical sweep (rename, migration, boilerplate), a stronger one for a subtle bug or a money/security-adjacent path.
• If nothing is stated, ask — don't guess. Naming the wrong model just burns quota for no reason.

The critical caveat: -p mode auto-approves everything

As of current agy releases, headless -p/--print runs have no read-only or plan-only mode — every tool call (including file writes) is auto-approved because there's no one to prompt. --sandbox only restricts shell/terminal execution, not file writes. This is exactly why this skill insists on:

1. Running the implementer in an isolated git worktree (a disposable branch), never directly in the directory the user is looking at.
2. Never trusting output.log over the actual diff. agy -p's stdout has known reliability gaps under redirects/pipes (notably on Windows) even when the run itself succeeded — treat the captured log as a debugging aid, not the source of truth. The working tree is the source of truth.

The loop

1. Write the brief

Each agy -p run is stateless — no chat history, no shared context, only the brief text plus whatever it reads from the working tree. Put everything the task needs into it using the structured prompt format: the desired outcome, context (with the critical workflows instruction), constraints (boundaries, rules, and what NOT to touch), and the verification/reporting checklist. Discover the project's actual gate commands by reading AGENTS.md (most important, if it exists) and package/project configuration files like package.json, Makefile, go.mod, or composer.json — do not assume.

CRITICAL INSTRUCTION FOR THE BRIEF: You must firmly and strictly command the implementer agent to look inside the .agents/workflows/ directory to read relevant architectural and project maps BEFORE it begins coding. This drastically reduces the time it spends investigating and guessing.

Keep one task per brief. Full template: references/writing-the-brief.md.

2. Dispatch

CRITICAL: Before dispatching, you MUST run node .agents/skills/agentflow/scripts/agentflow.mjs models via the terminal to see the exact model names available. Do NOT hallucinate or guess a model name (e.g., do not use gemini-2.5-pro). Use exactly what the terminal outputs.

# IMPORTANT: Always create your brief file inside the skill directory to avoid cluttering the project root.
# Make sure to create the briefs directory first if it doesn't exist:
mkdir -p "<skill-dir>/briefs"

# Example: write your brief into <skill-dir>/briefs/my-task-brief.txt
BRIEF_RUN_DIR=$(node "<skill-dir>/scripts/agentflow.mjs" dispatch \
  --brief "<skill-dir>/briefs/my-task-brief.txt" \
  --model "<EXACT-MODEL-NAME-FROM-AGY-MODELS>" \
  --timeout 24h)
echo "$BRIEF_RUN_DIR"

(<skill-dir> is this skill's installed folder — the one containing this SKILL.md.)

This creates a fresh git worktree on a throwaway branch, launches agy -p in the background inside it with the given --model, and immediately prints the run directory — everything about this run lives under that path (brief.txt, output.log, exit_code, status, worktree/, branch.txt). The full flag reference and on-disk layout are documented in the header comment of scripts/agentflow.mjs — it's short, worth reading once.

3. Check status (Optional)

You can check the status instantly or block and wait for completion by using the --watch or -w flag:

# Instant status query
node "<skill-dir>/scripts/agentflow.mjs" status "$BRIEF_RUN_DIR"
# Outputs: "running", "done", "failed", or "unknown"

# Watch and block until the process completes (exits 0 on done, 1 on failed)
node "<skill-dir>/scripts/agentflow.mjs" status "$BRIEF_RUN_DIR" --watch

If you need to see what it's thinking:

node "<skill-dir>/scripts/agentflow.mjs" log "$BRIEF_RUN_DIR" 50

4. Review and land it

Once status says done, read the diff from the worktree:

node "<skill-dir>/scripts/agentflow.mjs" diff "$BRIEF_RUN_DIR"

Review it carefully. The implementer may have hallucinated or misunderstood the brief.

CRITICAL INSTRUCTION: When you are ready to apply the diff from the implementer, DO NOT merge it via git or CLI commands directly! Instead, you MUST use your own native Antigravity file editing tools (replace_file_content, multi_replace_file_content, etc.) to recreate the changes in the main workspace. This is mandatory so that the user is presented with the interactive Accept/Reject interface for your changes. NEVER commit or merge changes directly; always route them through the file editing tools so the user retains control.

5. Clean up

Whether you accept or reject the changes, always clean up the worktree and run directory to prevent clutter:

node "<skill-dir>/scripts/agentflow.mjs" cleanup "$BRIEF_RUN_DIR"

• Re-run the project's real gates yourself (test/lint/build) inside $BRIEF_RUN_DIR/worktree — never take a "tests passed" claim in output.log on faith.
• Read the diff against the brief: did it do what was asked, nothing more (scope creep) and nothing less?
• For schema/migration changes, round-trip them; for removals, grep for dangling references.

Full checklist: references/review-and-land.md.

5. Land it (Via Agent Tools for User Review)

The implementer edited a disposable worktree. DO NOT use git merge --squash or terminal copy commands to apply the changes silently. The user explicitly requires you (the orchestrator) to apply the modifications using your native file editing tools (replace_file_content, multi_replace_file_content, write_to_file) so that the IDE displays the interactive "Accept/Reject" UI for review.

1. Review the Diff:

node "<skill-dir>/scripts/agentflow.mjs" diff "$BRIEF_RUN_DIR"

(If the diff is too large to read at once, read the changed files directly from $BRIEF_RUN_DIR/worktree/.)

2. Apply Changes via Tools: For each modified file, use your file editing tools to replicate the worktree's changes into the main working directory.

3. Cleanup: Once all changes are applied via your tools, remove the temporary worktree:

node "<skill-dir>/scripts/agentflow.mjs" cleanup "$BRIEF_RUN_DIR"

If it needs changes, don't try to resume the old run (headless session resumption via --continue/--conversation is unconfirmed for -p mode) — instead re-dispatch a fresh, self-contained delta brief into the same worktree so the implementer picks up from the files as they currently stand:

node "<skill-dir>/scripts/agentflow.mjs" dispatch \
  --brief delta-brief.txt \
  --model <model-slug> \
  --workdir "$BRIEF_RUN_DIR/worktree"

Authorization model

Delegation is something the human opts into. Once they have ("delegate this", "run it on the fast model"), reviewing and landing gate-passing work is the agreed contract. Two limits: surface, don't absorb — report the implementer's design decisions and any defensible-but-unasked turns rather than silently keeping them — and stop for scope changes — if correct completion needs going beyond the brief, ask rather than expanding the mandate yourself.

References

• references/writing-the-brief.md — brief structure, the report contract, and pulling real gate commands out of the repo.
• references/review-and-land.md — the review checklist, the worktree merge step, and the rework cycle.