{"id":51685995,"url":"https://github.com/hah23255/agy-delegate","last_synced_at":"2026-07-15T20:44:06.480Z","repository":{"id":370775576,"uuid":"1296662173","full_name":"hah23255/agy-delegate","owner":"hah23255","description":"Claude Code skill: delegate implementation briefs to parallel Google Antigravity CLI (agy) agents — worktree isolation, schema output gate","archived":false,"fork":false,"pushed_at":"2026-07-10T22:20:36.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-15T20:43:35.370Z","etag":null,"topics":["agentic-workflows","android","claude-code","google-antigravity","parallel-agents","termux"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hah23255.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-10T15:48:44.000Z","updated_at":"2026-07-10T22:20:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hah23255/agy-delegate","commit_stats":null,"previous_names":["hah23255/agy-delegate"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/hah23255/agy-delegate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hah23255%2Fagy-delegate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hah23255%2Fagy-delegate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hah23255%2Fagy-delegate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hah23255%2Fagy-delegate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hah23255","download_url":"https://codeload.github.com/hah23255/agy-delegate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hah23255%2Fagy-delegate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35520685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-15T02:00:06.706Z","response_time":131,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflows","android","claude-code","google-antigravity","parallel-agents","termux"],"created_at":"2026-07-15T20:44:05.782Z","updated_at":"2026-07-15T20:44:06.471Z","avatar_url":"https://github.com/hah23255.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agy-delegate\nClaude Code skill: delegate implementation briefs to parallel Google Antigravity CLI (`agy`) agents with git-worktree isolation and a JSON-schema output gate. Current version is in the `VERSION` file (and git tags).\n\n[English](#english) · [Български](#български)\n\n## English\n\n### What it is\nTurn Claude into a manager of Google Antigravity CLI (`agy`) agents. Claude does the judgment work—decomposition, briefs, and review—while agy handles the implementation volume.\n\n### Prerequisites\n- Google Antigravity CLI (`agy`) installed in a proot-distro `debian` container with the Termux wrapper at `~/.local/bin/agy`.\n- A Google Pro/Ultra subscription (running this burns credits).\n- The repository must live under `$HOME` (a requirement for the proot bind-mount).\n\n### Install\nClone the private repository under `$HOME`, then run:\n```bash\nbash install.sh\n```\nThis symlinks the repository into `~/.claude/skills/` (you can override this using the `CLAUDE_SKILLS_DIR` environment variable). The skill will then auto-trigger on phrases like \"delegate to agy\".\n\n### The agy contract (critical)\nThis integration relies on a verified invocation contract for the `agy` CLI:\n```bash\nagy -p \"PROMPT\" --dangerously-skip-permissions --print-timeout 15m [--model \"...\"]\n```\nThere is a hard rule: **`-p` binds the very next token as the prompt**. Every other flag must come AFTER the prompt, otherwise `--print` swallows the neighboring flag as prompt text. Since agy self-updates silently, if you notice behavior shifts, re-run the contract check (costs credits):\n```bash\nbash scripts/agy_parallel.sh --verify\n```\n\n### Usage\n1. Copy `assets/brief-template.md` to create one brief per agent. Every section (Goal, Context, Scope, Requirements, Conventions, Verification, Done criteria) is required, as the launcher lints them. You can optionally include frontmatter for `model:`, `timeout:`, and `schema:`.\n2. Launch the agents:\n```bash\nbash scripts/agy_parallel.sh --repo /path/to/repo briefs/*.md\n```\nThis creates a worktree per brief on the `agy/\u003cname\u003e` branch and outputs logs in `.agy-runs/\u003cts\u003e/`. The default is `--max-parallel 3`, and the exit code equals the number of failed agents.\n3. The schema gate: When a brief declares a `schema`, the agent must output a matching JSON object. In the default `salvage` mode, valid fields are saved to `\u003cname\u003e.partial.json` with `_missing`/`_invalid` keys, resulting in a `PARTIAL(schema)` status. You can alter this behavior via `--schema-mode strict|warn`.\n4. Review step: Read the logs and run `git -C \u003crepo\u003e diff base..agy/\u003cname\u003e`. Run the tests yourself and merge manually—never trust agent self-reports.\n\n### Statuses\nThe following statuses are defined in the skill:\n`OK · PARTIAL(schema) · FAILED(exit|timeout|quota|schema|schema-file|empty-brief|bad-timeout|worktree)`\nThe process exit code counts every `FAILED` item. `PARTIAL` statuses never fail the overall run.\n\n### Testing\nAll automated tests use a stub `agy` to ensure zero credits are burned:\n```bash\nbash tests/test_agy_parallel.sh\nbash tests/test_install.sh\npytest tests/ -q\n```\nThe real-agy contract check is for humans to run only (costs credits):\n```bash\nbash scripts/agy_parallel.sh --verify\n```\n\n### Deployment note\nDo NOT run the test suites from shared storage such as `/storage/emulated/0` (sdcardfs is mounted noexec, so the stub `agy` cannot execute and the launcher tests will fail spuriously). First copy the repository into `$HOME` (ext4), which is required anyway for the proot bind-mount.\n\n### On quota\nIf you encounter `FAILED(quota)`, fall back to kimi-delegate, and then to native Claude subagents.\n\n### Architecture Mapping\n```mermaid\ngraph TD\n    A[Task Briefs *.md] --\u003e B[agy_parallel.sh Launcher]\n    B --\u003e C{Linter \u0026 Validator}\n    C --\u003e|Invalid| D[FAILED Prelaunch]\n    C --\u003e|Valid| E[Worktree Allocator]\n    E --\u003e F[Parallel Executor]\n    F --\u003e G[Antigravity CLI agy]\n    G --\u003e H{Schema Gate}\n    H --\u003e|Match| I[Status OK]\n    H --\u003e|Mismatch / salvage| J[Status PARTIAL]\n    H --\u003e|Mismatch / strict| K[Status FAILED]\n```\n\n### Fault Handling Manual\n| Status / Error | Root Cause | Mitigation |\n| :--- | :--- | :--- |\n| `FAILED(exit)` | The `agy` process terminated with a non-zero exit status. | Check the specific log in `.agy-runs/\u003cts\u003e/\u003cname\u003e.log` for tracebacks or system errors. |\n| `FAILED(timeout)` | The agent execution exceeded the timeout limit. | Increase the timeout limit in the command via `--timeout` or override in the brief's frontmatter. |\n| `FAILED(quota)` | Credit or rate limits on the Google Pro/Ultra subscription were reached. | Switch to `kimi-delegate` or invoke native Claude subagents. |\n| `FAILED(schema)` | The generated output failed validation against the provided JSON schema. | Inspect the output log. If in `salvage` mode, look at the parsed values in `\u003cname\u003e.partial.json`. |\n| `FAILED(worktree)` | Git worktree creation failed (commonly because the branch or directory already exists). | Clean up leftover worktrees manually with `git worktree prune` and delete the offending branch. |\n\n### Common Issues \u0026 Golden Rules\n* **Golden Rule 1: Prompt Positioning Contract.** The `-p` flag in `agy` binds the very next token as the prompt. Any CLI flags must be specified *after* the prompt, otherwise they will be swallowed as prompt text.\n* **Golden Rule 2: $HOME Directory Restraint.** Due to `proot` bind-mounting rules, the target repository and brief files must reside under `$HOME`. Run from ext4 storage, never `/storage/emulated/0`.\n* **Golden Rule 3: No Unbounded Runs.** Never run parallel jobs without timeouts. The host wrapper enforces `timeout -k 10` to guarantee cleanup of hanging processes.\n\n## Български\n\n### Какво е това\nПревърнете Claude в мениджър на агенти за Google Antigravity CLI (`agy`). Claude извършва аналитичната работа — декомпозиция, задания и преглед, докато agy поема обема от работата по имплементация.\n\n### Изисквания\n- Инсталиран Google Antigravity CLI (`agy`) в proot-distro `debian` контейнер с Termux wrapper на `~/.local/bin/agy`.\n- Абонамент за Google Pro/Ultra (изпълнението изразходва кредити).\n- Хранилището трябва да се намира под `$HOME` (изискване за proot bind-mount).\n\n### Инсталация\nКлонирайте частното хранилище под `$HOME`, след което изпълнете:\n```bash\nbash install.sh\n```\nТова създава символна връзка (symlink) на хранилището в `~/.claude/skills/` (можете да промените това чрез променливата на средата `CLAUDE_SKILLS_DIR`). След това умението се задейства автоматично при фрази като \"delegate to agy\".\n\n### Договорът на agy (критично)\nТази интеграция разчита на верифициран договор за извикване на `agy` CLI:\n```bash\nagy -p \"PROMPT\" --dangerously-skip-permissions --print-timeout 15m [--model \"...\"]\n```\nСъществува строго правило: **`-p` обвързва следващия токен като промпт (prompt)**. Всеки друг флаг трябва да идва СЛЕД промпта, в противен случай `--print` поглъща съседния флаг как текст на промпта. Тъй като agy се обновява тихо, ако забележите промяна в поведението, изпълнете отново проверката на договора (струва кредити):\n```bash\nbash scripts/agy_parallel.sh --verify\n```\n\n### Употреба\n1. Копирайте `assets/brief-template.md`, за да създадете по едно задание на агент. Всеки раздел (Goal, Context, Scope, Requirements, Conventions, Verification, Done criteria) е задължителен, тъй като стартерът (launcher) ги проверява. Можете по желание да включите frontmatter за `model:`, `timeout:` и `schema:`.\n2. Стартирайте агентите:\n```bash\nbash scripts/agy_parallel.sh --repo /path/to/repo briefs/*.md\n```\nТова създава работно дърво (worktree) за всяко задание в клона `agy/\u003cname\u003e` и записва логове в `.agy-runs/\u003cts\u003e/`. По подразбиране се използва `--max-parallel 3`, а кодът за изход (exit code) е равен на броя на неуспешните агенти.\n3. Проверка на схемата (schema gate): Когато задание декларира `schema`, агентът трябва да изведе съответстващ JSON обект. В режима по подразбиране `salvage`, валидните полета се запазват в `\u003cname\u003e.partial.json` с ключове `_missing`/`_invalid`, което води до статус `PARTIAL(schema)`. Можете да промените това поведение чрез `--schema-mode strict|warn`.\n4. Етап на преглед: Прочетете логовете и изпълнете `git -C \u003crepo\u003e diff base..agy/\u003cname\u003e`. Изпълнете тестовете сами и слейте (merge) ръчно — никога не се доверявайте на самоотчетите на агентите.\n\n### Статуси\nВ умението са дефинирани следните статуси:\n`OK · PARTIAL(schema) · FAILED(exit|timeout|quota|schema|schema-file|empty-brief|bad-timeout|worktree)`\nКодът за изход на процеса брои всеки елемент със статус `FAILED`. Статусите `PARTIAL` никога не маркират цялостното изпълнение като неуспешно.\n\n### Тестване\nВсички автоматизирани тестове използват макетен (stub) `agy`, за да се гарантира, че не се изразходват кредити:\n```bash\nbash tests/test_agy_parallel.sh\nbash tests/test_install.sh\npytest tests/ -q\n```\nПроверката на договора с реалния agy трябва да се стартира само от човек (струва кредити):\n```bash\nbash scripts/agy_parallel.sh --verify\n```\n\n### Бележка за внедряване\nНЕ изпълнявайте тестовите пакети от споделено хранилище като `/storage/emulated/0` (sdcardfs се монтира с флаг noexec, така че макетният `agy` не може да се изпълни и тестовете на стартера ще се провалят фалшиво). Първо копирайте хранилището в `$HOME` (ext4), което така или иначе е необходимо за proot bind-mount.\n\n### При изчерпана квота\nАко срещнете `FAILED(quota)`, преминете към kimi-delegate и след това към нативните подагенти на Claude.\n\n### Архитектурно описание\n```mermaid\ngraph TD\n    A[Task Briefs *.md] --\u003e B[agy_parallel.sh Launcher]\n    B --\u003e C{Linter \u0026 Validator}\n    C --\u003e|Невалидно| D[FAILED Prelaunch]\n    C --\u003e|Валидно| E[Worktree Allocator]\n    E --\u003e F[Parallel Executor]\n    F --\u003e G[Antigravity CLI agy]\n    G --\u003e H{Schema Gate}\n    H --\u003e|Съвпадение| I[Status OK]\n    H --\u003e|Несъвпадение / salvage| J[Status PARTIAL]\n    H --\u003e|Несъвпадение / strict| K[Status FAILED]\n```\n\n### Ръководство за отстраняване на неизправности\n| Статус / Грешка | Причина | Решение |\n| :--- | :--- | :--- |\n| `FAILED(exit)` | Процесът `agy` завърши с ненулев изходен код. | Проверете съответния лог файл в `.agy-runs/\u003cts\u003e/\u003cname\u003e.log` за грешки и изключения. |\n| `FAILED(timeout)` | Времето за изпълнение на агента изтече. | Увеличете времето чрез параметъра `--timeout` или дефинирайте по-голям лимит във frontmatter на заданието. |\n| `FAILED(quota)` | Достигнат лимит на квотата или изчерпани кредити на Google Pro/Ultra. | Превключете към `kimi-delegate` или нативните Claude subagents. |\n| `FAILED(schema)` | Изходът не съответства на зададената JSON схема. | Проверете лог файла. В режим `salvage` разгледайте спасените полета в `\u003cname\u003e.partial.json`. |\n| `FAILED(worktree)` | Грешка при създаване на git worktree (напр. съществуващ клон или папка). | Изчистете остатъчните работни дървета ръчно чрез `git worktree prune` и изтрийте проблемния клон. |\n\n### Чести проблеми и Златни правила\n* **Златно правило 1: Позициониране на промпта.** Флагът `-p` в `agy` обвързва следващия токен като промпт. Всички останали флагове трябва да се подават *след* промпта, в противен случай се поглъщат като част от него.\n* **Златно правило 2: Ограничение до директория $HOME.** Поради изискванията на `proot` за bind-mount, хранилището и заданията трябва да са разположени в `$HOME` (ext4), а не в споделеното хранилище `/storage/emulated/0`.\n* **Златно правило 3: Задължителен лимит за време.** Никога не стартирайте паралелни процеси без лимит за време. Скриптът налага `timeout -k 10` за гарантирано убиване на увиснали процеси.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhah23255%2Fagy-delegate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhah23255%2Fagy-delegate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhah23255%2Fagy-delegate/lists"}