agy-delegation-workflow

agy Delegation Workflow Regulations (agy Delegation Workflow)

Overview

agy(Antigravity CLI) is a dedicatedExecution-Only Backend. The foreground agent (responsible for high-level planning, architectural decisions, and quality review) delegates specific coding, scaffolding, refactoring, and unit testing tasks to an independent agy headless process (agy -p), forming a clear "Plan -> Delegate -> Execute -> Review" closed loop.

graph LR
    A["前台智能体<br/>规划 + 编写自包含 Prompt"] -->|委派| B["agy 后台执行器<br/>(Gemini 3.8 Flash 独立进程)"]
    B -->|产出代码与单测| C["前台智能体<br/>Diff 审查 + 审计命令 + 双轮终审"]
    C -->|审查通过| D["提交入库 ✅"]
    C -->|存在阻断项| A

---

When to Use

Must/Recommended to Delegate

• Delegate well-decomposed independent feature capabilities, page components, backend API endpoints, or utility functions for background implementation.
• Write unit tests, build mock data systems, batch code refactoring.
• Multi-task batch parallel execution (parallel within a batch, isolated context, avoiding foreground token congestion).

Strictly Prohibited to Delegate (Anti-Trigger Conditions)

• Host environment native anti-trigger (agy host prioritizes dispatching sub-agents): When the current Agent itself is running in the Antigravity (agy) / Antigravity IDE host environmentand has the invoke_subagent tool,it is strictly prohibited to invoke the agy command line to start another process via nested terminal calls; it must directly use native sub-agents (invoke_subagent) for delegation.
• Architecture and design documents：IMPLEMENTATION_PLAN.md、task.md, requirements specifications and design master plans (core responsibility of the foreground, the background is strictly prohibited from overstepping authority).
• Git write operations and destructive operations：git commit、git push、git reset, batch file deletion.
• Security credentials and interactive decisions: key handling, permission changes, user interaction clarification when requirements are uncertain.

---

Scope Boundary

Foreground agent exclusive responsibilities (strictly prohibited to delegate)	agy background execution responsibilities
Development planning, phase plans, task decomposition	Production code implementation (business logic/core modules/utility functions)
Interface contracts and data model definitions (type definitions/interface specifications/domain models)	Writing unit tests and integration tests
Task Prompt file writing (.agy-tasks/*.md）	Code refactoring and code smell cleanup
Test infrastructure pre-checks (framework/scripts/config ready)	Run local tests and fix own compilation errors
Full-scale review of output, audit command verification, and submission to repository	Report execution summary and list of modified files

Red-line principle: if agy oversteps authority and generates any planning or design document (such as generating in the root directory task.md), the foreground agentmust immediately delete itand write it itself.

---

Execution Agent Priority Chain & Host Awareness

When delegating, the foreground must follow the principles of host awareness and degradation protection (see priority-fallback-chain.md）：

1. Host environment native dispatch (agy host first choice)：
   • Applicable conditions: When the current Agent itself is running in the Antigravity (agy) / Antigravity IDE host environmentand has the invoke_subagent tool.
   • Execution Principles: Directly and mandatorily call invoke_subagent to dispatch sub-agents; nesting calls is strictly prohibited for agy command line.
2. Headless Command-Line Execution (Preferred for Non-agy Hosts)：
   • Applicable Conditions: When the host environment is not agy (such as Claude Code, Cursor, a general-purpose terminal without a native sub-agent scheduler, or a pure command-line CI/batch environment),prefer using agy command line to dispatch background headless processes。
   • Default Model：Gemini 3.8 Flash (High); thoroughly clear environment proxy variables before startup.
3. Fallback: Direct-Write in the Foreground：
   • When in 2+ consecutive batches >50% of the output requires complete rewriting, and the foreground has fully grasped the target context, the foreground should decisively write directly.

---

Standard Delegation SOP (5-Step Delegation Procedure)

1. Write a Self-Contained Task Prompt

• Skill-First Linkage: If a skill for writing plans/tasks exists in the skill library (such as writing-plans), the foreground agent, when planning and decomposing tasks,must activate and use that skill first, and closely combine it with task-prompt-template.md to write the implementation plan.
• Self-Contained Task Solidification: Each specific subtask must be materialized as an independent .agy-tasks/<task-name>.md file, strictly following the task-prompt-template.md specified 7-Dimensional General Golden Elements(working directory and target scope, data contracts and interface models, dependency calls and API specifications, data sources and test fixture specifications, behavioral specifications and architectural constraints, automated acceptance commands, prohibited items and security red lines).

2. Clean Up Environment Proxies and Launch the Task (Dispatch)

Use an auxiliary script or forcibly prepend the clearing of WSL/Linux proxy variables in the command to eliminate connection refusals:

# 方式 A：使用辅助脚本（推荐，自动注入 Gemini 3.8 Flash、代理清除与 workspace 注册）
bash skills/agy-delegation-workflow/scripts/dispatch-agy.sh -f .agy-tasks/task-a.md

# 方式 B：原生命令（必须自带 --add-dir "$PWD"，否则 Hindsight 记忆库会落错）
unset HTTPS_PROXY HTTP_PROXY http_proxy https_proxy ALL_PROXY all_proxy; \
agy --add-dir "$PWD" -p "$(cat .agy-tasks/task-a.md)" \
  --model 'Gemini 3.8 Flash (High)' \
  --dangerously-skip-permissions \
  --print-timeout 20m

Memory Bank Ownership (Hindsight bank)：agy -p headless mode has no active workspace —— in hook events workspacePaths is an empty array, and the cwd that agy gives to hook / MCP server subprocesses is fixed to ~/.gemini/config (not agy's own cwd). When no workspace is explicitly registered, the bank template coding-agent::{gitProject} will degrade to the directory basename, and the entire batch of sessions will be written into coding-agent::config(in actual testing it once mistakenly ingested 75 documents / 3,237 memory units, spanning 6 repositories). The auxiliary script has already handled this automatically; when writing commands by hand, please include --add-dir。

3. Multi-Task Orchestration and Parallelism Guidelines (Batch Orchestration)

• Tasks on the Same File Must Be Merged: If two tasks modify the same file, they must be merged into one Prompt; launching them in parallel is strictly prohibited to avoid conflict races.
• Dependency-Free Tasks Run in Parallel Within a Batch: Tasks without file conflicts can be triggered in parallel using background commands.
• Build Operations Run Serially Between Batches：pnpm build global builds are extremely expensive; running builds in parallel in the background is strictly prohibited, and the foreground should execute one unified build at the end of the entire batch.

4. False-Failure Troubleshooting and Timeout Defense (Silent Landing Check)

If agy reports OAuth EOF or exits due to timeout,do not immediately judge it a failure and rerun(see infrastructure-troubleshooting.md）：

• Run git status -s to check whether the target file has already landed on disk (Silent Landing);
• Run the unit test command to verify whether the feature has been implemented; if it passes, treat it directly as success and proceed to review.

5. Strict 6-Step Acceptance Review (Mandatory Review Checklist)

Before merging any agy output, the front-end agent must execute the following checks item by item (see failure-modes-audit.md）：

1. Diff Scope：git diff --stat Confirm that the changes are convergent and that no out-of-scope planning documents are mixed in;
2. Static Types and Lint: Run the type checker and code linter for the corresponding tech stack (e.g., tsc --noEmit, mypy, cargo check, golangci-lint), zero warnings and zero errors;
3. Failure Mode Audit: Run the dedicated grep command to check for self-made Fallbacks, fabricated APIs, leftover disabled debug code, etc.;
4. Unit Tests: The full test suite is all green;
5. Global Build: Execute the project-wide compile/package build (e.g., pnpm build, cargo build, go build), to catch global type generalization breaks;
6. Two-Round Final Review: Invoke the dual-round-review skill to complete the final review loop.

---

Reference and Support Resource Navigation

Procedures and Diagnostic Guides

• infrastructure-troubleshooting.md - WSL proxy contamination, OAuth EOF false failure, and delayed disk write diagnosis
• failure-modes-audit.md - High-frequency large model failure modes and the list of mandatory grep audit commands
• priority-fallback-chain.md - Execution priority chain, 3-Tries degradation, and direct authoring decision criteria

Task Templates and Tool Scripts

• task-prompt-template.md - Task Prompt specification template containing the 7-dimensional golden standard
• dispatch-agy.sh - One-click helper script for clearing proxy and injecting Gemini 3.8 Flash model for background delegation