Assemble

Compile this into a Task Brief — a self-contained description that each sub-agent receives.

Step 1 — Dev Cycle

Spawn a sub-agent (model: sonnet) with the full @Dev persona prompt and the Task Brief.

The dev agent prompt must include:

• The complete @Dev persona instructions (from .antigravity/commands/dev.md)
• The Task Brief from Step 0
• If this is cycle N>1: the Critic Findings from the previous cycle, with explicit instructions to fix each violation

Wait for the dev agent to complete. Capture its summary of changes made.

Step 2 — Critic Cycle

Spawn a sub-agent (model: sonnet) with the full @Critic persona prompt.

The critic agent prompt must include:

• The complete @Critic persona instructions (from .antigravity/commands/critic.md)
• The Task Brief (so the critic knows what was intended)
• The dev agent's summary of what was changed

Wait for the critic agent to complete. Parse the verdict.

Step 3 — Decision Gate

Based on the critic's verdict:

• Ship it — Proceed to Step 4 (finish).
• Fix before commit — Extract the violation list. Go back to Step 1 with the findings as fix instructions.
• Discuss — Present the discussion points to the user and wait for guidance before continuing.

Circuit breaker: If you have completed 3 full cycles without reaching "Ship it", stop and present the remaining findings to the user. Ask whether to continue or adjust the approach. Do not loop forever.

Step 4 — Finish

Report to the user:

• Summary: What was implemented.
• Verdict: Final critic verdict (and any notes).

• [!NOTE] Assemble Stats: Completed in N cycles (Dev-Critic round-trips).

• Next Steps: Suggest running /ship to commit and push.

Sub-Agent Model Policy

• haiku — File search, grep, reading files, listing issues, gathering context
• sonnet — Code edits, writing content, running validation, critic reviews
• opus — Only if a sub-task genuinely requires it (architectural decision, ambiguous spec); ask user first

Model routing and clean contexts

This Assemble workflow supports explicit model routing for sub-agents and prescribes how to construct a minimal, sanitized context for each run.

Goals:

• Use Google Gemini 3 Flash preview selector gemini-3-flash-preview [google-gemini-cli] for Dev/implementation sub-agents (highest throughput for code edits).
• Use GitHub Copilot review model selector gpt-5-mini [github-copilot] for Critic/review sub-agents (strong adversarial review).
• Always provide a narrow, task-specific context (Task Brief) instead of the whole repo to avoid leaking irrelevant data and to keep token usage low.

Notes on model identifiers

• The exact provider/model id depends on your pi deployment / model provider mapping. Replace the example ids above with the IDs configured in your pi settings (e.g. "gemini-3-flash-preview [google-gemini-cli]" for dev and "gpt-5-mini [github-copilot]" for review, or local aliases).

How to build a clean Task Brief (scripted, repeatable)

1. Identify scope
   • If the user provided an issue number: gh issue view <N> --json title,body,labels (include title + acceptance criteria)
   • Else, use $ARGUMENTS as the task description.
2. Find relevant specs/files
   • Search specs: rg "<feature-keyword>" specs/ -n --hidden --no-ignore and include matching spec paths.
   • Determine changed files (if working on an existing branch): git diff --name-only origin/main...HEAD or staged files for the dev cycle.
3. Collect minimal file content
   • For each path in "relevant files", include:
     • full file contents if size < 8KB
     • otherwise include the file header (first 200 lines) + a 200-line tail or a short summary and the git diff for that file: git --no-pager diff --no-color origin/main...HEAD -- <path>
   • Exclude: node_modules/, dist/, public/assets/ (large binaries like .glb), and other heavy binary files. Instead, note their presence and version.
4. Include a short git context
   • git rev-parse --abbrev-ref HEAD (branch)
   • git log --oneline -5 (recent commits)
   • git diff --staged --name-only (what will be committed)
5. Assemble the Task Brief JSON/YAML with these fields:
   • task: short description / issue link
   • acceptance_criteria: list
   • specs: [paths]
   • files: [{path, size, excerpt?, diff?}]
   • recent_commits
   • environment: {node:version, pnpm:version}

Example Task Brief (trimmed):

{ "task": "#42 — implement immutable export for grid", "acceptance_criteria": ["unit tests pass", "export format stable"], "specs": ["specs/track-format.spec.md"], "files": [ {"path":"src/lib/grid/store.svelte.ts","size":5120,"diff":"...git diff..."} ], "recent_commits": ["fix(grid): use $state.snapshot ..."], }

Spawning Dev (Gemini 3 Flash) sub-agent — recommended payload

• model: "gemini-3-flash-preview [google-gemini-cli]" (or your local alias)
• persona: Dev / sonnet prompt (include full Dev persona)
• context: Task Brief (as above)
• allowed_tools: [read, bash, edit, write] (explicit tool list)
• file_allowlist: only the listed paths in Task Brief
• max_runtime: 30m (safeguard)
• output: structured summary + patchset (files changed + brief rationale)

Example wrapper (pseudo):

/agent.spawn { "model": "google/gemini-3-flash", "persona": "dev", "allowed_tools": ["read","bash","edit","write"], "context": <TaskBrief> }

Spawning Critic (GitHub-Copilot Claude 4.5) sub-agent — recommended payload

• model: "gpt-5-mini [github-copilot]"
• persona: Critic / sonnet prompt (full Critic persona)
• context: Task Brief + Dev summary + unified git diff
• allowed_tools: [read, bash] (no edit/write)
• file_allowlist: specs/ and the changed files only
• instructions: produce findings grouped by lens (Hard Constraints, Module Boundaries, Spec Compliance, Tests, etc.)
• output: a structured findings list (file, line ref, severity, fix suggestion)

Example wrapper (pseudo):

/agent.spawn { "model": "github-copilot/claude-4-5", "persona": "critic", "allowed_tools": ["read","bash"], "context": {"task_brief": ..., "dev_summary": ..., "diff": ...} }

Sanitization & security

• Remove secrets: strip any .env, .env.*, or API keys from files included in the brief.
• Redact emails or tokens in commit messages if present.
• Limit binary inclusion; prefer file metadata + diffs.

Token budgeting & truncation

• Prefer diffs + small excerpts instead of full-file dumps for large files.
• If a file is >50KB, include only: header (first 300 lines) + git diff + file size. Offer to re-open a follow-up dev cycle if the sub-agent requests more context.

Verifiable outputs

• Dev agent must return:
  • A short patchset (paths changed) and a compact git-style patch for each change
  • A verification plan (commands run, tests added/updated)
  • A short checklist of acceptance criteria satisfied
• Critic agent must return a structured list of findings with severity and suggested fixes. If any finding is blocking, Assemble must re-run a Dev cycle with the finding as a fix instruction.

Implementation notes for pi integrations

• pi's skill loader exposes the SKILL.md; the assemble skill should call the Agent tool/CLI with the above payloads. How you call models depends on your pi provider configuration — the important bit is to pass the correct model field and a minimal context object.
• Keep each sub-agent run ephemeral and stateless: create a fresh context bundle per-run and pass only what's necessary.

If you want, I can:

• Edit this SKILL.md to include these exact sample payloads and helper commands (e.g. scripts/make-task-brief.sh and scripts/spawn-dev.sh).
• Implement a small helper script in .agents/skills/assemble/scripts/ that generates a Task Brief and invokes the Agent tool with the right model id. Request if you'd like that added.

Principles

• Fresh context per cycle — Each dev/critic run is a separate sub-agent. No stale state accumulation.
• Self-healing — Critic findings feed directly into the next dev cycle as fix instructions.
• Silent unless stuck — Do not ask the user for confirmation between cycles. Only interrupt if genuinely blocked (ambiguous requirement, conflicting specs, architectural question).
• Deterministic exit — The loop has a clear termination condition (Ship it) and a circuit breaker (3 cycles).
• Module boundaries enforced — Both dev and critic agents receive ARCHITECTURE.md boundary rules.

Boundaries

• Does NOT commit or push — that's /ship's job.
• Does NOT modify specs — that's /spec's job. If a spec update is needed, flag it to the user.
• Does NOT spawn opus sub-agents without asking.