@hivey/cli 0.0.0-stage → 0.9.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/README.md +235 -2
  2. package/bin/hivey.js +98 -0
  3. package/native/darwin-arm64/hivey +0 -0
  4. package/package.json +36 -4
  5. package/platforms.json +3 -0
  6. package/repo/LICENSE +201 -0
  7. package/repo/NOTICE +18 -0
  8. package/repo/README.md +148 -0
  9. package/repo/install.sh +365 -0
  10. package/repo/pets/README.md +25 -0
  11. package/repo/pets/hivey-dot/CLAUDE.md +55 -0
  12. package/repo/pets/hivey-dot/build.sh +34 -0
  13. package/repo/pets/hivey-dot/main.swift +750 -0
  14. package/repo/pets/hivey-h/CLAUDE.md +75 -0
  15. package/repo/pets/hivey-h/build.sh +34 -0
  16. package/repo/pets/hivey-h/main.swift +739 -0
  17. package/repo/pets/hivey-prompt/CLAUDE.md +59 -0
  18. package/repo/pets/hivey-prompt/build.sh +34 -0
  19. package/repo/pets/hivey-prompt/main.swift +691 -0
  20. package/repo/pets/pet.py +288 -0
  21. package/repo/pets/shared/HiveyWatch.swift +437 -0
  22. package/repo/pets/test_pet.py +122 -0
  23. package/repo/plugins/README.md +108 -0
  24. package/repo/plugins/agent-creator/herdr-plugin.toml +17 -0
  25. package/repo/plugins/dashboard/dashboard.py +507 -0
  26. package/repo/plugins/dashboard/herdr-plugin.toml +14 -0
  27. package/repo/plugins/dashboard/test_dashboard.py +134 -0
  28. package/repo/plugins/github/github.py +261 -0
  29. package/repo/plugins/github/herdr-plugin.toml +14 -0
  30. package/repo/plugins/github/test_github.py +49 -0
  31. package/repo/plugins/skills/herdr-plugin.toml +11 -0
  32. package/repo/plugins/skills/skills.md +41 -0
  33. package/repo/plugins/slack-relay/connect.py +198 -0
  34. package/repo/plugins/slack-relay/create_channel.py +134 -0
  35. package/repo/plugins/slack-relay/herdr-plugin.toml +15 -0
  36. package/repo/plugins/slack-relay/relay.py +401 -0
  37. package/repo/plugins/slack-relay/slack-app-manifest.json +30 -0
  38. package/repo/plugins/slack-relay/test_connect.py +66 -0
  39. package/repo/plugins/slack-relay/test_create_channel.py +61 -0
  40. package/repo/plugins/slack-relay/test_relay.py +254 -0
  41. package/repo/plugins/swarm-creator/herdr-plugin.toml +17 -0
  42. package/repo/plugins/swarm-watcher/dashboard.py +333 -0
  43. package/repo/plugins/swarm-watcher/herdr-plugin.toml +16 -0
  44. package/repo/plugins/swarm-watcher/usage.py +129 -0
  45. package/repo/plugins/swarm-watcher/watcher.py +191 -0
  46. package/repo/plugins/team-template/herdr-plugin.toml +15 -0
  47. package/repo/plugins/team-template/setup.py +211 -0
  48. package/repo/plugins/team-template/test_setup.py +73 -0
  49. package/repo/plugins/tts/herdr-plugin.toml +15 -0
  50. package/repo/skills/herdr/SKILL.md +214 -0
  51. package/repo/skills/hivey/SKILL.md +322 -0
  52. package/repo/skills/hivey/scripts/handoff.py +27 -0
  53. package/repo/skills/hivey/scripts/new_wiki.py +143 -0
  54. package/repo/skills/hivey-agent-creator/SKILL.md +303 -0
  55. package/repo/skills/hivey-agent-creator/references/agent-claude-md.md +256 -0
  56. package/repo/skills/hivey-agent-creator/references/global-guidelines.md +67 -0
  57. package/repo/skills/hivey-agent-creator/references/reviewer-agent.md +35 -0
  58. package/repo/skills/hivey-agent-creator/scripts/agent_context.py +76 -0
  59. package/repo/skills/hivey-agent-creator/scripts/agent_gate.py +78 -0
  60. package/repo/skills/hivey-agent-creator/scripts/setup_agent.py +288 -0
  61. package/repo/skills/hivey-agy/SKILL.md +123 -0
  62. package/repo/skills/hivey-agy/references/gemini-prompting.md +134 -0
  63. package/repo/skills/hivey-agy/scripts/agy_run.py +146 -0
  64. package/repo/skills/hivey-codex/SKILL.md +66 -0
  65. package/repo/skills/hivey-context7/SKILL.md +56 -0
  66. package/repo/skills/hivey-create-wiki/SKILL.md +329 -0
  67. package/repo/skills/hivey-grok/SKILL.md +101 -0
  68. package/repo/skills/hivey-grok/scripts/grok_run.py +139 -0
  69. package/repo/skills/hivey-swarm-creator/SKILL.md +384 -0
  70. package/repo/skills/hivey-swarm-creator/references/agent-claude-md.md +313 -0
  71. package/repo/skills/hivey-swarm-creator/references/archify-report.md +24 -0
  72. package/repo/skills/hivey-swarm-creator/references/dashboard.md +46 -0
  73. package/repo/skills/hivey-swarm-creator/references/retrospective.md +23 -0
  74. package/repo/skills/hivey-swarm-creator/references/shared-rules.md +39 -0
  75. package/repo/skills/hivey-swarm-creator/references/wiki-memory.md +30 -0
  76. package/repo/skills/hivey-swarm-creator/scripts/setup_agent.py +76 -0
  77. package/repo/skills/hivey-swarm-creator/scripts/shared_rules.py +50 -0
  78. package/repo/skills/hivey-swarm-creator/scripts/swarm_tasks.py +171 -0
  79. package/repo/skills/hivey-wiki-ingest/SKILL.md +45 -0
  80. package/repo/skills/hivey-wiki-lint/SKILL.md +38 -0
  81. package/repo/skills/hivey-wiki-list/SKILL.md +46 -0
  82. package/repo/skills/hivey-wiki-log/SKILL.md +45 -0
  83. package/repo/skills/hivey-wiki-query/SKILL.md +44 -0
@@ -0,0 +1,288 @@
1
+ #!/usr/bin/env python3
2
+ """Scaffold (or update) the folder of one hivey solo agent.
3
+
4
+ Writes, inside the agent folder only (never the global Claude Code config):
5
+ CLAUDE.md a skeleton with the brief's sections and Status markers, if missing
6
+ .claude/settings.json additionalDirectories (the folder + --dirs; hivey launch turns them
7
+ into --add-dir), allow/deny rules (git push is always denied),
8
+ enabledMcpjsonServers, and with --gate the done-gate (Stop) and
9
+ resume-context (SessionStart) hooks
10
+ .mcp.json project-scoped MCP servers given with --mcp
11
+ .codex/config.toml the same MCP servers for a Codex agent
12
+ .agent/config.json the run check (--check-cmd) and optional progress log
13
+ .claude/agents/reviewer.md with --reviewer (Claude Code only)
14
+ .gitignore keeps files that may hold keys and runtime state out of git
15
+
16
+ Idempotent: re-running only adds. Skills are not installed here: follow `hivey skills guide`.
17
+ Standard library only. Prints a JSON report.
18
+ """
19
+ import argparse
20
+ import json
21
+ import re
22
+ import shutil
23
+ import subprocess
24
+ from pathlib import Path
25
+
26
+ HERE = Path(__file__).absolute().parent # keep the installed path (hooks point at it)
27
+ PROJECT_HOOKS = { # event -> script registered in the agent's own .claude/settings.json
28
+ "Stop": HERE / "agent_gate.py",
29
+ "SessionStart": HERE / "agent_context.py",
30
+ }
31
+ NAME_RE = re.compile(r"^[a-z][a-z0-9-]{0,31}$")
32
+ KINDS = ("claude", "codex", "grok", "agy")
33
+ ALWAYS_DENY = ["Bash(git push:*)"]
34
+ GITIGNORE = [".mcp.json", ".codex/", ".agent/state/", "logs/"]
35
+
36
+ SKELETON = """# {name} — <one-line role>
37
+
38
+ > You are **{name}**, a solo hivey agent (address `{name}/master`). This file defines your role.
39
+
40
+ ## Rules
41
+
42
+ ## Start of every session
43
+
44
+ ## The ask
45
+
46
+ ## Your mission
47
+
48
+ ## Deliverables
49
+ | # | Deliverable | Path | Done when | Check |
50
+ |---|-------------|------|-----------|-------|
51
+
52
+ ## Where you work
53
+ - Home: `{dir}`
54
+
55
+ ## Your toolkit
56
+
57
+ ## Method
58
+
59
+ ## Run protocol (every run, on demand or scheduled)
60
+
61
+ ## Memory
62
+
63
+ ## Other agents
64
+
65
+ ## Definition of done
66
+
67
+ ---
68
+
69
+ ## Status
70
+ <!-- STATUS:START -->
71
+ _Not started yet._
72
+ <!-- STATUS:END -->
73
+ """
74
+
75
+
76
+ def add_unique(lst, items):
77
+ for item in items:
78
+ if item not in lst:
79
+ lst.append(item)
80
+
81
+
82
+ def read_json(path):
83
+ if not path.exists():
84
+ return {}
85
+ try:
86
+ return json.loads(path.read_text())
87
+ except json.JSONDecodeError as err:
88
+ raise SystemExit(f"{path} is not valid JSON ({err}); fix it first")
89
+
90
+
91
+ def write_json(path, data):
92
+ path.parent.mkdir(parents=True, exist_ok=True)
93
+ path.write_text(json.dumps(data, indent=2) + "\n")
94
+
95
+
96
+ def toml_str(value):
97
+ return json.dumps(str(value)) # JSON string escapes are valid TOML basic strings
98
+
99
+
100
+ def codex_mcp_tables(servers):
101
+ """Render .mcp.json server entries as Codex [mcp_servers.<name>] TOML tables."""
102
+ out = []
103
+ for name, cfg in servers.items():
104
+ out.append(f"[mcp_servers.{toml_str(name)}]")
105
+ if cfg.get("url"):
106
+ out.append(f"url = {toml_str(cfg['url'])}")
107
+ else:
108
+ out.append(f"command = {toml_str(cfg.get('command', ''))}")
109
+ if cfg.get("args"):
110
+ out.append("args = [" + ", ".join(toml_str(a) for a in cfg["args"]) + "]")
111
+ if cfg.get("env"):
112
+ out.append(f"[mcp_servers.{toml_str(name)}.env]")
113
+ out += [f"{toml_str(k)} = {toml_str(v)}" for k, v in cfg["env"].items()]
114
+ out.append("")
115
+ return out
116
+
117
+
118
+ def parse_mcp(spec):
119
+ """NAME=JSON -> (name, server config)."""
120
+ name, sep, raw = spec.partition("=")
121
+ name = name.strip()
122
+ if not sep or not name:
123
+ raise SystemExit(f"--mcp {spec!r}: expected NAME=JSON, e.g. "
124
+ "'fetch={\"command\":\"uvx\",\"args\":[\"mcp-server-fetch\"]}'")
125
+ try:
126
+ cfg = json.loads(raw)
127
+ except json.JSONDecodeError as err:
128
+ raise SystemExit(f"--mcp {name}: invalid JSON ({err})")
129
+ if not isinstance(cfg, dict) or not (cfg.get("command") or cfg.get("url")):
130
+ raise SystemExit(f"--mcp {name}: the JSON needs a \"command\" or a \"url\"")
131
+ return name, cfg
132
+
133
+
134
+ def add_project_hooks(settings):
135
+ """Register the done gate + resume-context hooks in the agent's settings (idempotent)."""
136
+ hooks = settings.setdefault("hooks", {})
137
+ added = []
138
+ for event, script in PROJECT_HOOKS.items():
139
+ cmd = f"python3 {script}"
140
+ entries = hooks.setdefault(event, [])
141
+ if any(h.get("command") == cmd for m in entries for h in m.get("hooks", [])):
142
+ continue
143
+ entries.append({"hooks": [{"type": "command", "command": cmd, "timeout": 330}]})
144
+ added.append(event)
145
+ return added
146
+
147
+
148
+ def in_git_repo(folder):
149
+ try:
150
+ r = subprocess.run(["git", "-C", str(folder), "rev-parse", "--is-inside-work-tree"],
151
+ capture_output=True, text=True)
152
+ except FileNotFoundError:
153
+ return None
154
+ return r.returncode == 0
155
+
156
+
157
+ def main():
158
+ p = argparse.ArgumentParser(
159
+ description="Scaffold or update a hivey solo agent's folder (see SKILL.md step 5).",
160
+ formatter_class=argparse.RawDescriptionHelpFormatter,
161
+ epilog="example:\n setup_agent.py ~/agents/seo-auditor --name seo-auditor --kind claude \\\n"
162
+ " --check-cmd 'bash scripts/check.sh' --gate --reviewer --git")
163
+ p.add_argument("folder", help="the agent folder (created if missing)")
164
+ p.add_argument("--name", required=True, help="agent name / slug, [a-z][a-z0-9-]{0,31}")
165
+ p.add_argument("--kind", choices=KINDS, default="claude", help="coding agent (default claude)")
166
+ p.add_argument("--dirs", default="", help="comma-separated extra folders the agent may use")
167
+ p.add_argument("--allow", action="append", default=[], help="Claude Code allow rule (repeatable)")
168
+ p.add_argument("--deny", action="append", default=[], help="Claude Code deny rule (repeatable)")
169
+ p.add_argument("--mcp", action="append", default=[], metavar="NAME=JSON",
170
+ help="add a project MCP server to .mcp.json (repeatable)")
171
+ p.add_argument("--enable-mcps", default="", help="pre-approve servers already in .mcp.json")
172
+ p.add_argument("--check-cmd", help="run check, run in the agent folder; exit 0 = run done")
173
+ p.add_argument("--progress-log", help="a newest-first log file the resume context summarizes")
174
+ p.add_argument("--gate", action="store_true",
175
+ help="register the done gate and resume-context hooks (Claude Code only)")
176
+ p.add_argument("--reviewer", action="store_true",
177
+ help="install the read-only reviewer subagent (Claude Code only)")
178
+ p.add_argument("--git", action="store_true", help="git init the folder if it isn't in a repo")
179
+ args = p.parse_args()
180
+
181
+ if not NAME_RE.match(args.name):
182
+ raise SystemExit(f"invalid name {args.name!r}: must match {NAME_RE.pattern}")
183
+ agent_dir = Path(args.folder).expanduser().resolve()
184
+ if agent_dir == Path.home().resolve():
185
+ raise SystemExit("refusing to use your home folder as an agent folder")
186
+ if args.gate and not (args.check_cmd or read_json(agent_dir / ".agent" / "config.json").get("check")):
187
+ raise SystemExit("--gate needs a run check: pass --check-cmd")
188
+ agent_dir.mkdir(parents=True, exist_ok=True)
189
+ result = {"agent": args.name, "kind": args.kind, "dir": str(agent_dir), "notes": []}
190
+
191
+ brief = agent_dir / "CLAUDE.md"
192
+ if not brief.exists():
193
+ brief.write_text(SKELETON.format(name=args.name, dir=agent_dir))
194
+ result["claude_md"] = "skeleton written"
195
+ else:
196
+ result["claude_md"] = "kept"
197
+
198
+ settings_path = agent_dir / ".claude" / "settings.json"
199
+ settings = read_json(settings_path)
200
+ perms = settings.setdefault("permissions", {})
201
+ dirs = [str(agent_dir)] + [str(Path(d.strip()).expanduser().resolve())
202
+ for d in args.dirs.split(",") if d.strip()]
203
+ add_unique(perms.setdefault("additionalDirectories", []), dirs)
204
+ if args.allow:
205
+ add_unique(perms.setdefault("allow", []), args.allow)
206
+ add_unique(perms.setdefault("deny", []), ALWAYS_DENY + args.deny)
207
+ if args.kind == "grok" and len(dirs) > 1:
208
+ result["notes"].append("grok can't use extra folders: keep its work inside the agent folder")
209
+ if args.kind != "claude" and (args.allow or args.deny):
210
+ result["notes"].append("allow/deny rules apply to Claude Code only")
211
+
212
+ mcp_names = [m.strip() for m in args.enable_mcps.split(",") if m.strip()]
213
+ mcp_path = agent_dir / ".mcp.json"
214
+ if args.mcp:
215
+ mcp = read_json(mcp_path)
216
+ servers = mcp.setdefault("mcpServers", {})
217
+ for spec in args.mcp:
218
+ name, cfg = parse_mcp(spec)
219
+ servers[name] = cfg
220
+ add_unique(mcp_names, [name])
221
+ write_json(mcp_path, mcp)
222
+ if mcp_names:
223
+ servers = read_json(mcp_path).get("mcpServers", {})
224
+ result["mcps_missing"] = [m for m in mcp_names if m not in servers]
225
+ found = {m: servers[m] for m in mcp_names if m in servers}
226
+ add_unique(settings.setdefault("enabledMcpjsonServers", []), sorted(found))
227
+ result["mcps"] = sorted(found)
228
+ result["mcps_with_env"] = sorted(m for m, cfg in found.items() if cfg.get("env"))
229
+ if args.kind == "codex":
230
+ codex_cfg = agent_dir / ".codex" / "config.toml"
231
+ codex_cfg.parent.mkdir(exist_ok=True)
232
+ all_servers = read_json(mcp_path).get("mcpServers", {})
233
+ codex_cfg.write_text("# Project-scoped Codex config written by hivey-agent-creator "
234
+ "(may hold MCP keys; git-ignored)\n\n"
235
+ + "\n".join(codex_mcp_tables(all_servers)))
236
+ result["codex_config"] = str(codex_cfg)
237
+ elif args.kind in ("grok", "agy"):
238
+ result["notes"].append(f"{args.kind} doesn't read .mcp.json: set up its MCP servers "
239
+ "with its own CLI, or prefer a CLI tool")
240
+
241
+ cfg_path = agent_dir / ".agent" / "config.json"
242
+ if args.check_cmd or args.progress_log:
243
+ cfg = read_json(cfg_path)
244
+ if args.check_cmd:
245
+ cfg["check"] = args.check_cmd
246
+ if args.progress_log:
247
+ cfg["progress_log"] = str(Path(args.progress_log).expanduser())
248
+ write_json(cfg_path, cfg)
249
+ result["agent_config"] = cfg
250
+ (agent_dir / ".agent" / "state").mkdir(parents=True, exist_ok=True)
251
+ (agent_dir / "logs").mkdir(exist_ok=True)
252
+
253
+ if args.gate:
254
+ if args.kind == "claude":
255
+ result["hooks_added"] = add_project_hooks(settings)
256
+ else:
257
+ result["notes"].append("the done gate is a Claude Code hook: the brief tells this "
258
+ "agent to run the check itself")
259
+ if args.reviewer:
260
+ if args.kind != "claude":
261
+ result["reviewer"] = "skipped: the reviewer subagent is Claude Code only"
262
+ else:
263
+ dest = agent_dir / ".claude" / "agents" / "reviewer.md"
264
+ dest.parent.mkdir(parents=True, exist_ok=True)
265
+ shutil.copy(HERE.parent / "references" / "reviewer-agent.md", dest)
266
+ result["reviewer"] = str(dest)
267
+
268
+ write_json(settings_path, settings)
269
+ result["settings"] = str(settings_path)
270
+
271
+ gitignore = agent_dir / ".gitignore"
272
+ lines = gitignore.read_text().splitlines() if gitignore.exists() else []
273
+ add_unique(lines, GITIGNORE)
274
+ gitignore.write_text("\n".join(lines) + "\n")
275
+
276
+ repo = in_git_repo(agent_dir)
277
+ if args.git and repo is False:
278
+ subprocess.run(["git", "init", "-q", str(agent_dir)], check=True)
279
+ repo = True
280
+ result["git"] = "initialized"
281
+ else:
282
+ result["git"] = {True: "in a repo", False: "not a repo (pass --git)", None: "git missing"}[repo]
283
+
284
+ print(json.dumps(result, indent=2))
285
+
286
+
287
+ if __name__ == "__main__":
288
+ main()
@@ -0,0 +1,123 @@
1
+ ---
2
+ name: hivey-agy
3
+ description: Run a task with Google's Antigravity CLI (`agy`, the replacement for Gemini CLI). Picks the right model and effort for the task (Gemini 3.8 Flash low/medium/high, Gemini 3.1 Pro, or Claude / gpt-oss through agy), writes an effective Gemini-style prompt, runs agy headless through a bundled uv Python runner, and checks the result, including any files the task should create. Use it whenever the user wants something done "with agy", "with Antigravity", "with Gemini", "ask Gemini", wants a Gemini second opinion, or wants to hand a coding, research, summarising, extraction or image-generation task to agy. Also use it when they ask which agy model to use or how to prompt Gemini, even if they don't say "agy". Not for driving the Antigravity IDE app, and not for calling the Gemini API from code.
4
+ ---
5
+
6
+ > Local additions: if `EXTRA_SKILL.md` exists in this skill's folder, read it too and follow it.
7
+ > It holds this machine's own additions; hivey updates never touch it, so put local changes
8
+ > there, never here.
9
+
10
+ # agy: run a task with the right model and prompt
11
+
12
+ The user gives a task. Your job is to (1) choose the agy model, (2) write the prompt agy gets,
13
+ (3) run it headless, (4) check the result and report. agy is a full agent: it can read and
14
+ write files in its workspace, run shell commands, search the web, browse, and generate images.
15
+
16
+ Runner: `uv run -q --script ~/.claude/skills/hivey-agy/scripts/agy_run.py` (called `RUN` below).
17
+ It's stdlib-only and wraps `~/.local/bin/agy`. Call agy by full path or through `RUN`: some
18
+ shells still carry an old `alias agy="agy . …"` that breaks bare `agy`.
19
+
20
+ ## 1. Understand the task
21
+
22
+ Work out four things. Usually you can infer them, so don't interrogate the user:
23
+ - **Kind**: quick answer · structured extraction · summary/writing · research (needs web) ·
24
+ coding/file work in a folder · image · multi-turn conversation.
25
+ - **Workspace**: which folder agy should work in (`--cwd`). For pure Q&A, use a scratch dir
26
+ like `/tmp/agy-<slug>` so agy doesn't wander around in your current folder.
27
+ - **Done-when**: what has to be true at the end (a file exists, tests pass, a JSON shape, an answer).
28
+ - **Model override**: if the user named a model or tier, use it.
29
+
30
+ Ask the user only when the missing piece would change what you run, such as which repo or what
31
+ the output file should be. Otherwise assume, and mention the assumption in your report.
32
+
33
+ ## 2. Pick the model
34
+
35
+ Gemini slugs already encode effort (`-low/-medium/-high`), so don't add `--effort` for them.
36
+ Check what's currently available with `RUN --models`. The list changes as Google ships models.
37
+
38
+ | Task | Model | Why |
39
+ |---|---|---|
40
+ | One-line answers, reformatting, classification, `--schema` extraction | `gemini-3.8-flash-low` | Fast and cheap; reasoning isn't the bottleneck |
41
+ | Default: everyday coding, summaries, writing, explanations | `gemini-3.8-flash-medium` | Best speed/quality balance |
42
+ | Hard debugging, multi-file refactors, long agent runs, web research, planning | `gemini-3.8-flash-high` | 3.8 Flash high matches or beats 3.1 Pro on most coding/agent benchmarks |
43
+ | Very long documents (≫100k tokens), deep reasoning where flash-high already failed, a second opinion | `gemini-3.1-pro-high` | Different model family; use it as the escalation tier |
44
+ | User wants Claude through agy, or careful prose / code review | `claude-sonnet-4-6`, or `claude-opus-4-6-thinking` for the hardest | Available in agy at no extra setup |
45
+ | Cheap open-model second opinion | `gpt-oss-120b-medium` | Independent check |
46
+
47
+ Older 3.7/3.6 Flash slugs exist only for comparison. Don't pick them by default.
48
+ If a run fails or gives a shallow result, escalate one step (low → medium → high → pro-high)
49
+ instead of rewriting the prompt into a monster.
50
+
51
+ ## 3. Write the prompt
52
+
53
+ Read `references/gemini-prompting.md` the first time you use this skill in a session. In short:
54
+ - **Direct, compact, structured.** Role, constraints and output format go at the top, in one
55
+ style (XML tags *or* Markdown headers). No hype, no "think step by step", no threats. The
56
+ `-high` tier already does the reasoning.
57
+ - **Long pasted data goes in the middle, and the question at the end**, starting with "Based on
58
+ the information above…".
59
+ - **Spell out output size and shape.** Gemini defaults to terse, so ask for length, sections
60
+ or a full file if you want them.
61
+ - **Give it a done-when and a report line** for agentic work. Headless agy can't ask questions,
62
+ so add "if unclear, assume reasonably and state the assumption".
63
+ - **Phrase rules positively.** Absolute bans ("never infer") make Gemini over-literal.
64
+ - **Use the user's own words for the goal**, and add the context they didn't think to give
65
+ (paths, versions, the repo's test command).
66
+
67
+ Use the templates in the reference: generic, long-context, agentic coding, and the task-type
68
+ patterns (research, extraction, writing, debugging, image).
69
+
70
+ ## 4. Run it
71
+
72
+ ```bash
73
+ RUN=~/.claude/skills/hivey-agy/scripts/agy_run.py
74
+ uv run -q --script $RUN -m <model> [flags] "<prompt>" # or: printf '%s' "$P" | … -
75
+ ```
76
+
77
+ Flags to choose:
78
+ - `--cwd <dir>` is the workspace agy reads and writes. Always set it for file work.
79
+ - `--schema '<json schema>'` returns parsed JSON for extraction. Prefer it over describing
80
+ JSON in prose.
81
+ - `--yolo` (= `--dangerously-skip-permissions`) is needed whenever agy must **run shell
82
+ commands, read web pages (research), or create images**. Headless agy soft-denies those, and
83
+ the run can still "succeed" with an empty or half-done answer. The runner prints
84
+ `[DENIED] …` when that happens. Use `--yolo` only in the task's own folder (a scratch dir for
85
+ research). For untrusted code, add `--sandbox`.
86
+ - `--expect <file>` (repeatable) makes the run exit 3 if the file wasn't created. Use it for
87
+ every task that should produce a file. agy can report SUCCESS after a tool failed upstream.
88
+ - `--timeout 20m` for long agent runs (the default is 10m).
89
+ - `--json` returns the full envelope (`conversation_id`, `usage`). Keep the id when a
90
+ follow-up is likely, then continue with `--conversation <id>` (or `-c` for the last one).
91
+ - `--chat` is an interactive multi-turn session. Use it only when the user wants to talk to
92
+ agy themselves.
93
+
94
+ For long prompts, write the prompt to a temp file and pipe it in (`… - < /tmp/agy-prompt.md`)
95
+ so shell quoting can't mangle it.
96
+
97
+ Runs can take minutes. For anything you expect to exceed ~2 minutes, run it in the background
98
+ and tell the user it's running.
99
+
100
+ ## 5. Check and report
101
+
102
+ - **Exit codes:** 0 = success. 1 = agy error (read stderr: auth, unknown model, timeout).
103
+ 3 = an expected file is missing. 4 = agy finished with an empty answer, usually because an
104
+ action was denied. Rerun with `--yolo`.
105
+ - **Look at the output yourself:** open the created file and run the tests it claimed to pass.
106
+ For images, use Read on the image file to look at it. Don't relay "done" from agy unchecked.
107
+ - **Image fallback:** if agy's image generation keeps failing (it returned upstream 500s on
108
+ 2026-10-11), offer the user the `gemini-image-chrome` skill (Gemini in Chrome) as a fallback.
109
+ - **Report briefly:** which model and why (one line), the prompt you sent (collapsed or short
110
+ if it's long), the result or file paths, anything you verified, and any assumption you made.
111
+
112
+ ## Example
113
+
114
+ User: "with agy, summarise ~/Downloads/report.pdf for my team in 5 bullets"
115
+ - Kind: summary. Model: `gemini-3.8-flash-medium`. Workspace: `~/Downloads`.
116
+ - Prompt:
117
+ ```
118
+ <role>You summarise business documents for a busy engineering team.</role>
119
+ <task>Read report.pdf in the current folder and summarise it.</task>
120
+ <output_format>Exactly 5 Markdown bullets, each ≤25 words, keep key numbers and decisions.
121
+ Then one line "Open questions:" listing anything the report leaves unresolved.</output_format>
122
+ ```
123
+ - Run: `uv run -q --script $RUN -m gemini-3.8-flash-medium --cwd ~/Downloads "<prompt>"`
@@ -0,0 +1,134 @@
1
+ # Prompting Gemini 3.x (what works, with sources)
2
+
3
+ Researched 2026-10-11. Sources at the bottom. Applies to every Gemini slug in `agy models`
4
+ (3.6/3.7/3.8 Flash, 3.1 Pro). Claude and gpt-oss slugs also do fine with these prompts.
5
+
6
+ ## Contents
7
+ 1. Core rules
8
+ 2. Structure templates
9
+ 3. Task-type patterns
10
+ 4. Things that backfire
11
+ 5. Sources
12
+
13
+ ## 1. Core rules
14
+
15
+ - **Direct and short beats clever.** Gemini 3 "responds best to direct, clear instructions" and
16
+ "may over-analyze verbose or overly complex prompt engineering techniques used for older
17
+ models". Drop persuasion, threats, "you are the world's best…", and hand-written
18
+ chain-of-thought scaffolds. Reasoning depth comes from the model tier and effort
19
+ (the `-low/-medium/-high` slug), not from "think step by step".
20
+ - **Say how much output you want.** By default it's terse and direct. To get a long report, a
21
+ friendly tone, or a full file, ask for it explicitly (length, sections, tone).
22
+ - **Role and constraints go first, the question goes last.** Put the role, hard rules and output
23
+ format at the top. With big context (pasted docs, logs, code), put the data in the middle and
24
+ the actual question at the **end**, opening with "Based on the information above…".
25
+ - **One consistent structure.** Use either XML-style tags or Markdown headers, not both. Define
26
+ any ambiguous term ("short" = under 120 words; "recent" = after 2026-01-01).
27
+ - **State the done-condition.** For agentic work, say exactly what counts as finished: the file
28
+ exists, the tests pass, the answer is a JSON object. agy keeps going until it thinks the task
29
+ is done, so a vague done-condition gives you a vague stop.
30
+ - **Persistence for agentic tasks:** "Keep working until the task is completely done. If a tool
31
+ or command fails, read the error and try a different approach." This is useful with
32
+ `--dangerously-skip-permissions` runs.
33
+ - **Ambiguity:** "If something is unclear, make a reasonable assumption, state it in one line,
34
+ and continue." Headless runs can't ask the user, and an `ask_question` call just stalls or
35
+ gets soft-denied.
36
+ - **Leave temperature alone.** (agy doesn't expose it anyway.) Google recommends the default 1.0
37
+ for Gemini 3, because low temperatures cause looping.
38
+
39
+ ## 2. Structure templates
40
+
41
+ ### Generic task (XML)
42
+ ```
43
+ <role>You are a {senior X} helping with {domain}.</role>
44
+
45
+ <task>{one-paragraph statement of the goal, in the user's terms}</task>
46
+
47
+ <context>
48
+ {facts, file paths, constraints the user gave, pasted data}
49
+ </context>
50
+
51
+ <constraints>
52
+ - {hard rule 1}
53
+ - {hard rule 2}
54
+ - Verbosity: {low|medium|high}. Tone: {…}.
55
+ - If something is unclear, assume reasonably and state the assumption.
56
+ </constraints>
57
+
58
+ <output_format>
59
+ {exact shape: "a Markdown table with columns A,B,C", "only the code, one block", "≤5 bullets"}
60
+ </output_format>
61
+ ```
62
+
63
+ ### Long context (data first, question last)
64
+ ```
65
+ <role>…</role>
66
+ <constraints>…</constraints>
67
+
68
+ <document>
69
+ {the long thing}
70
+ </document>
71
+
72
+ Based on the information above, {question}. {output format}.
73
+ ```
74
+
75
+ ### Agentic coding / file work (run with --cwd and usually --yolo)
76
+ ```
77
+ # Goal
78
+ {what must exist or change when you're done}
79
+
80
+ # Context
81
+ - Repo: {path}. Stack: {…}. Relevant files: {…}
82
+ - Conventions: {match existing style, no new deps, …}
83
+
84
+ # Steps you may take
85
+ Read files, run {test/lint commands}, edit files inside this folder only.
86
+
87
+ # Done when
88
+ - {tests command} passes
89
+ - {file} exists and contains {…}
90
+
91
+ # Report
92
+ End with: files changed, commands run and their result, anything left undone.
93
+ ```
94
+
95
+ ## 3. Task-type patterns
96
+
97
+ - **Research / web questions:** "Search the web. Decompose into sub-questions, answer each from
98
+ sources, cite every claim with its URL, and flag anything you couldn't verify." Use
99
+ flash-high. Ask for dates, because models can mix up versions.
100
+ - **Extraction / classification:** Use `--schema` (agy's `--json-schema`) instead of describing
101
+ JSON in prose. The prompt can then be one line. Use flash-low.
102
+ - **Summaries:** Give the audience and the length ("for a busy CTO, 5 bullets, each ≤20 words")
103
+ and say what to keep (numbers, names, decisions).
104
+ - **Writing / creative:** Give the audience, goal, voice, banned phrases, and one short example
105
+ of the tone. Ask for a self-review pass: "before answering, check for corporate jargon and
106
+ rewrite it".
107
+ - **Code review / debugging:** Give the symptom, the exact error, the repro command, and what
108
+ was already tried. Ask for the root cause first and the fix second.
109
+ - **Image generation (generate_image tool):** Describe the subject, style, composition,
110
+ lighting, aspect ratio and any text to render, in quotes. Then give the save path:
111
+ "save it as ./out/name.png and confirm with ls". It can fail upstream while the run still
112
+ reports SUCCESS, so always check the file.
113
+ - **Planning-before-doing (big tasks):** "First write a short numbered plan, then execute it,
114
+ ticking items off. At the end, verify each Done-when item." This is cheap, and it helps flash.
115
+
116
+ ## 4. Things that backfire
117
+
118
+ - **Absolute negatives** like "do not infer" or "never guess". Gemini 3 can follow them too
119
+ literally and refuse basic arithmetic or refuse to connect facts across a document. Say what
120
+ you want instead: "only use facts from the document; if a fact is missing, say 'not in
121
+ document'".
122
+ - **Asking about something it can't access.** Split it: "First check whether X is available;
123
+ if it isn't, say so and stop."
124
+ - **Over-long prompts on flash-low.** Low effort plus a huge rubric gives shallow compliance.
125
+ Either shorten the prompt or raise the effort.
126
+ - **Mixing several unrelated jobs in one `-p`.** Run them as separate calls, or as a `--chat`
127
+ session.
128
+
129
+ ## 5. Sources
130
+ - Google, Gemini 3 developer guide: https://ai.google.dev/gemini-api/docs/gemini-3
131
+ - Google Cloud, Gemini 3 prompting guide: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/gemini-3-prompting-guide
132
+ - Phil Schmid, Gemini 3 prompting best practices: https://www.philschmid.de/gemini-3-prompt-practices
133
+ - Antigravity CLI headless docs: https://antigravity.google/docs/cli/headless/
134
+ - Flash vs Pro: https://benchlm.ai/compare/gemini-3-1-pro-vs-gemini-3-8-flash , https://myclaw.ai/blog/gemini-3-8-flash-vs-3-1-pro