@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,146 @@
1
+ #!/usr/bin/env -S uv run --script
2
+ # /// script
3
+ # requires-python = ">=3.11"
4
+ # dependencies = []
5
+ # ///
6
+ """Run the Antigravity CLI (agy) headless from Python.
7
+
8
+ Examples:
9
+ agy_run.py "What is git rebase?"
10
+ agy_run.py -m claude-opus-4-6-thinking -e high "Explain this repo" --cwd ~/projects/hivey
11
+ agy_run.py -m gemini-3.1-pro-high --schema '{"type":"object","properties":{"major":{"type":"integer"}}}' "Parse v2.14.3"
12
+ echo "long prompt" | agy_run.py -
13
+ agy_run.py --chat -m gemini-3.8-flash-high # multi-turn session over stream-json
14
+ agy_run.py --cwd ~/out --yolo --expect cat.png "Generate ... save as cat.png"
15
+ agy_run.py --models # list model slugs
16
+ """
17
+ import argparse
18
+ import json
19
+ import os
20
+ import subprocess
21
+ import sys
22
+ from pathlib import Path
23
+
24
+ AGY = os.environ.get("AGY_BIN", str(Path.home() / ".local/bin/agy"))
25
+
26
+
27
+ def base_cmd(a) -> list[str]:
28
+ cmd = [AGY]
29
+ if a.model:
30
+ cmd += ["--model", a.model]
31
+ if a.effort:
32
+ cmd += ["--effort", a.effort]
33
+ if a.agent:
34
+ cmd += ["--agent", a.agent]
35
+ if a.yolo:
36
+ cmd += ["--dangerously-skip-permissions"]
37
+ if a.sandbox:
38
+ cmd += ["--sandbox"]
39
+ if a.cont:
40
+ cmd += ["--continue"]
41
+ if a.conversation:
42
+ cmd += ["--conversation", a.conversation]
43
+ return cmd
44
+
45
+
46
+ def ask(a, prompt: str) -> dict:
47
+ """One headless turn; returns the JSON envelope (response, status, usage, ...)."""
48
+ cmd = base_cmd(a) + ["-p", prompt, "--output-format", "json", "--print-timeout", a.timeout]
49
+ if a.schema:
50
+ cmd += ["--json-schema", a.schema]
51
+ p = subprocess.run(cmd, capture_output=True, text=True, cwd=a.cwd)
52
+ try:
53
+ return json.loads(p.stdout)
54
+ except json.JSONDecodeError:
55
+ return {"status": "ERROR", "error": (p.stderr or p.stdout).strip(), "exit_code": p.returncode}
56
+
57
+
58
+ def chat(a) -> None:
59
+ """Multi-turn session: one agy process, prompts as NDJSON on stdin."""
60
+ cmd = base_cmd(a) + ["--input-format", "stream-json", "--output-format", "stream-json"]
61
+ proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True, bufsize=1, cwd=a.cwd)
62
+ try:
63
+ while True:
64
+ try:
65
+ msg = input("you> ").strip()
66
+ except EOFError:
67
+ break
68
+ if msg in ("", "exit", "quit"):
69
+ break
70
+ proc.stdin.write(json.dumps({"event": "user", "message": {"content": msg}}) + "\n")
71
+ proc.stdin.flush()
72
+ for line in proc.stdout:
73
+ ev = json.loads(line)
74
+ step = ev.get("step_update") or {}
75
+ if step.get("text_delta"):
76
+ print(step["text_delta"], end="", flush=True)
77
+ elif ev.get("event") == "result":
78
+ r = ev["result"]
79
+ if r.get("status") != "SUCCESS":
80
+ print(f"\n[{r.get('status')}] {r.get('error', '')}", file=sys.stderr)
81
+ print()
82
+ break
83
+ finally:
84
+ proc.stdin.close()
85
+ proc.wait()
86
+
87
+
88
+ def main() -> int:
89
+ ap = argparse.ArgumentParser(description="Run agy (Antigravity CLI) headless")
90
+ ap.add_argument("prompt", nargs="?", help="prompt text, or '-' to read stdin")
91
+ ap.add_argument("-m", "--model", help="model slug (see --models)")
92
+ ap.add_argument("-e", "--effort", choices=["low", "medium", "high"])
93
+ ap.add_argument("--agent")
94
+ ap.add_argument("--schema", help="JSON schema (string, .json path, or string/number/integer/boolean)")
95
+ ap.add_argument("--cwd", type=lambda s: str(Path(s).expanduser()), help="workspace dir for the agent")
96
+ ap.add_argument("--timeout", default="10m", help="--print-timeout (e.g. 5m, 0s = no limit)")
97
+ ap.add_argument("--yolo", action="store_true", help="--dangerously-skip-permissions")
98
+ ap.add_argument("--sandbox", action="store_true")
99
+ ap.add_argument("-c", "--continue", dest="cont", action="store_true", help="continue last conversation")
100
+ ap.add_argument("--conversation", help="resume conversation id")
101
+ ap.add_argument("--json", action="store_true", help="print the full JSON envelope")
102
+ ap.add_argument("--expect", action="append", default=[], metavar="FILE",
103
+ help="file the run must create (relative to --cwd); exit 3 if missing. agy can say SUCCESS when a tool failed")
104
+ ap.add_argument("--chat", action="store_true", help="interactive multi-turn via stream-json")
105
+ ap.add_argument("--models", action="store_true", help="list model slugs and exit")
106
+ a = ap.parse_args()
107
+
108
+ if a.models:
109
+ return subprocess.run([AGY, "models"]).returncode
110
+ if a.chat:
111
+ chat(a)
112
+ return 0
113
+ if not a.prompt:
114
+ ap.error("prompt required (or --chat / --models)")
115
+ prompt = sys.stdin.read() if a.prompt == "-" else a.prompt
116
+
117
+ r = ask(a, prompt)
118
+ denied = r.get("denied_actions") or []
119
+ if denied:
120
+ names = ", ".join(d.get("action", "?") for d in denied)
121
+ print(f"[DENIED] agy was not allowed to: {names} (rerun with --yolo, or allow them in "
122
+ "~/.gemini/antigravity-cli/settings.json)", file=sys.stderr)
123
+ if r.get("status") == "SUCCESS" and not (r.get("response") or "").strip() and r.get("structured_output") is None:
124
+ r["status"] = "EMPTY"
125
+ r.setdefault("error", "agy finished without an answer" + (" (actions were denied)" if denied else ""))
126
+ if a.json:
127
+ print(json.dumps(r, indent=2, ensure_ascii=False))
128
+ elif r.get("status") == "SUCCESS":
129
+ out = r.get("structured_output")
130
+ print(json.dumps(out, indent=2, ensure_ascii=False) if out is not None else r.get("response", ""))
131
+ else:
132
+ print(f"[{r.get('status')}] {r.get('error', '')}", file=sys.stderr)
133
+ if r.get("status") == "EMPTY":
134
+ return 4
135
+ if r.get("status") != "SUCCESS":
136
+ return 1
137
+ base = Path(a.cwd or ".")
138
+ missing = [f for f in a.expect if not (base / Path(f).expanduser()).exists()]
139
+ if missing:
140
+ print(f"[MISSING] expected file(s) not created: {', '.join(missing)}", file=sys.stderr)
141
+ return 3
142
+ return 0
143
+
144
+
145
+ if __name__ == "__main__":
146
+ sys.exit(main())
@@ -0,0 +1,66 @@
1
+ ---
2
+ name: hivey-codex
3
+ description: >
4
+ Run a task with OpenAI's Codex CLI (`codex`) headless from the shell with `codex exec`: coding
5
+ work in a folder, code review, research, quick answers or structured JSON extraction, with the
6
+ right model, sandbox and output options, then check the result. Also resumes or forks earlier
7
+ Codex sessions. Use whenever the user wants something done "with Codex", "ask Codex", "codex
8
+ exec", wants a Codex / GPT second opinion or review, or hands a task to Codex, even if they
9
+ don't say "CLI". Not for the ChatGPT app or for calling the OpenAI API from code.
10
+ allowed-tools:
11
+ - Bash
12
+ - Read
13
+ ---
14
+
15
+ > Local additions: if `EXTRA_SKILL.md` exists in this skill's folder, read it too and follow it.
16
+ > It holds this machine's own additions; hivey updates never touch it, so put local changes
17
+ > there, never here.
18
+
19
+ # hivey codex: run Codex headless
20
+
21
+ `codex exec` runs one Codex task without the interactive UI and exits when it's done: the
22
+ final message goes to stdout (progress to stderr). Check `codex --version`; install with
23
+ `bun install -g @openai/codex` (or npm), sign in once with `codex login`.
24
+
25
+ ## Run a task
26
+
27
+ ```bash
28
+ codex exec -C <folder> -s workspace-write -o /tmp/codex-answer.md "<prompt>"
29
+ ```
30
+
31
+ - `-C, --cd <DIR>`: the folder Codex works in (its root). `--add-dir <DIR>` lets it write more.
32
+ - `-s, --sandbox`: `read-only` (answers, reviews, research), `workspace-write` (edits in the
33
+ folder; the usual choice for coding), `danger-full-access` (only when asked).
34
+ - `--approve-for-me`: approvals reviewed automatically, with `workspace-write`.
35
+ `--dangerously-bypass-approvals-and-sandbox` only in a sandboxed environment the user set up.
36
+ - `-m, --model <MODEL>`: leave it out to use the user's configured model; set it when they
37
+ ask for one. Effort: `-c model_reasoning_effort="low|medium|high|xhigh"` (low for quick
38
+ answers, high for hard coding or review).
39
+ - `-o, --output-last-message <FILE>`: also write the final message to a file; read it after.
40
+ - `--json`: one JSON event per line on stdout (to follow tool calls and the session id).
41
+ - `--output-schema <FILE>`: the final answer must match this JSON Schema (extraction).
42
+ - `-i, --image <FILE>`: attach images. `--skip-git-repo-check`: run outside a git repo.
43
+ - `--ephemeral`: don't keep the session. `-p, --profile <name>`: a config profile.
44
+ - The prompt can come on stdin: `cat brief.md | codex exec -`.
45
+
46
+ ## Review, resume, fork
47
+
48
+ ```bash
49
+ codex exec review # review the current repository's changes
50
+ codex exec resume --last "<follow-up>" # continue the latest session in this folder
51
+ codex exec resume <SESSION_ID> "<follow-up>"
52
+ codex exec fork <SESSION_ID> "<prompt>" # a new session from an earlier one
53
+ ```
54
+
55
+ ## Writing the prompt
56
+
57
+ Say the goal, the files or folder, constraints (don't touch X, keep the API), and what "done"
58
+ means (tests pass, a file exists). Ask for a short summary of what changed at the end. For
59
+ long briefs, write them to a file and pipe it in.
60
+
61
+ ## Check the result
62
+
63
+ Never pass Codex's answer on unchecked: read the `-o` file, look at `git diff` (or the files it
64
+ should have made), run the tests or the check the task named, and report what Codex did, what
65
+ you verified and anything that failed. On a non-zero exit, show the error (stderr) and the
66
+ likely cause (not signed in, sandbox refused a write, no git repo).
@@ -0,0 +1,56 @@
1
+ ---
2
+ name: hivey-context7
3
+ description: >
4
+ Look up current documentation for any library, framework, SDK, API, CLI or cloud service in
5
+ seconds with Context7 (context7.com), straight from the shell: find the library, then fetch
6
+ the docs and code snippets for the exact question. Works in every agent hivey runs (Claude
7
+ Code, Codex, Grok, Antigravity) with no MCP setup. Use it FIRST whenever you need API syntax,
8
+ configuration, setup steps, version changes or library-specific debugging, even for
9
+ well-known libraries (React, Next.js, Expo, Prisma, Tailwind, Django…): your training data
10
+ may be out of date. Not for general programming concepts or the user's own code.
11
+ allowed-tools:
12
+ - Bash
13
+ ---
14
+
15
+ > Local additions: if `EXTRA_SKILL.md` exists in this skill's folder, read it too and follow it.
16
+ > It holds this machine's own additions; hivey updates never touch it, so put local changes
17
+ > there, never here.
18
+
19
+ # hivey context7: fast, current docs
20
+
21
+ Context7 serves up-to-date documentation and code snippets for thousands of libraries, picked
22
+ for a question. It is faster and more precise than a web search for library docs, so use it
23
+ before searching the web or guessing from memory.
24
+
25
+ ## 1. Find the library ID
26
+
27
+ ```bash
28
+ curl -s "https://context7.com/api/v2/libs/search?libraryName=<library>&query=<what you need>" \
29
+ ${CONTEXT7_API_KEY:+-H "Authorization: Bearer $CONTEXT7_API_KEY"}
30
+ ```
31
+
32
+ The JSON `results` list each library's `id` (e.g. `/vercel/next.js`), `title`, `description`,
33
+ `totalSnippets` and `trustScore`. Pick the official one (highest trust and snippets, matching
34
+ title). Skip this step when you already know the ID, or when the user gave one
35
+ (`/org/project`, optionally `/org/project/<version>`).
36
+
37
+ ## 2. Fetch the docs for the question
38
+
39
+ ```bash
40
+ curl -s "https://context7.com/api/v2/context?libraryId=<id>&query=<specific question>&type=txt" \
41
+ ${CONTEXT7_API_KEY:+-H "Authorization: Bearer $CONTEXT7_API_KEY"}
42
+ ```
43
+
44
+ Plain text: titled snippets with their source URL and code. URL-encode the query (spaces as
45
+ `%20`). Make the query specific ("app router root layout", not "next.js"): the snippets are
46
+ chosen for it. Ask again with another query for another part of the answer. `type=json`
47
+ returns `codeSnippets` and `infoSnippets` instead.
48
+
49
+ ## Rules
50
+
51
+ - Answer from what Context7 returns and cite the source URLs it gives. If it has nothing
52
+ useful, say so, then fall back to the library's official docs on the web.
53
+ - Without an API key the rate limit is low: on HTTP `429`, wait for `Retry-After` seconds. A
54
+ key (free at context7.com) goes in `CONTEXT7_API_KEY` (from the user's secret store, never
55
+ written into a file or prompt).
56
+ - Never send private code, secrets or personal data in a query: it goes to context7.com.
@@ -0,0 +1,329 @@
1
+ ---
2
+ name: hivey-create-wiki
3
+ description: >
4
+ Create the Obsidian wiki of a hivey agent or swarm (LLM Wiki pattern, Karpathy): a
5
+ <name>-wiki/ vault inside the agent's or swarm's own folder with raw/ + wiki/, a CLAUDE.md
6
+ schema tailored to the agent's domain, index.md and log.md, and a section in the agent's
7
+ CLAUDE.md (each swarm agent's) pointing at it. Only for agents and swarms. Use whenever the
8
+ user wants a wiki, a knowledge base or long-term memory for an agent or a swarm ("create
9
+ wiki", "new wiki", "wiki for <agent>", "/hivey-create-wiki"), and whenever an agent or swarm
10
+ creator sets up its memory.
11
+ argument-hint: <agent-or-swarm-name> [--in <folder>] [--agent <dir>]...
12
+ allowed-tools:
13
+ - Bash
14
+ - Read
15
+ - Write
16
+ - Edit
17
+ - Glob
18
+ ---
19
+
20
+ > Local additions: if `EXTRA_SKILL.md` exists in this skill's folder, read it too and follow it.
21
+ > It holds this machine's own additions; hivey updates never touch it, so put local changes
22
+ > there, never here.
23
+
24
+ # hivey create wiki
25
+
26
+ Scaffold the Obsidian wiki vault of a hivey agent or swarm, following Andrej
27
+ Karpathy's [LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
28
+
29
+ The wiki is a **persistent, compounding knowledge artifact** that an LLM maintains over time,
30
+ separate from the agent's operational state. Sources go into `raw/` (read-only), the LLM writes
31
+ synthesised pages into `wiki/`, and `index.md` + `log.md` track the catalog and history.
32
+
33
+ ## Arguments
34
+
35
+ `$ARGUMENTS`: the **agent or swarm name** (e.g. `btc`, `gap-finder`), then optional flags:
36
+
37
+ - `--in <folder>`: the agent's or swarm's folder; the vault is created at
38
+ `<folder>/<slug>-wiki/`, next to the agents that use it, so the agent or swarm and its
39
+ knowledge travel together and can be shared as one folder. **Default when the current
40
+ folder (or one given by the caller) has a `CLAUDE.md`:** `--in .`. Agent and swarm creators
41
+ always pass it; never ask the user where their Obsidian is.
42
+ - `--agent <dir>` (repeatable): agent folders whose `CLAUDE.md` gets the wiki section (a
43
+ swarm's agents). With `--in` and no `--agent`, the folder's own `CLAUDE.md` is patched when
44
+ it exists.
45
+ This skill only makes wikis for agents and swarms. With no `--in` and no `CLAUDE.md` in the
46
+ current folder, ask which agent or swarm folder the wiki is for (it must have a `CLAUDE.md`,
47
+ or be a swarm root with agent folders); don't create a wiki that belongs to no agent.
48
+
49
+ If no name is given, use the folder's name; the hivey agent's folder `~/.hivey/agent` is named
50
+ `hivey` (its wiki is `~/.hivey/agent/hivey-wiki`).
51
+
52
+ Why `<slug>-wiki`: Obsidian lists vaults by folder name, so each wiki gets its own name in the
53
+ vault switcher. Older hivey vaults are called `obsidian/`; `hivey migrate` renames them. The
54
+ wiki skills (`/hivey-wiki-ingest`, `/hivey-wiki-query`, `/hivey-wiki-lint`,
55
+ `/hivey-wiki-log`, `/hivey-wiki-list`; `$hivey-wiki-ingest`, … in Codex) find the nearest `<slug>-wiki/` with a `CLAUDE.md`,
56
+ walking up from the current folder.
57
+
58
+ ## Solo agent or swarm (detected, never asked)
59
+
60
+ - **Solo agent**: the folder has a `CLAUDE.md` and no `--agent` folders: one brief to read
61
+ and patch, the vault at `<folder>/<slug>-wiki/`.
62
+ - **Swarm**: `--agent` folders were given (or the folder's sub-folders have their own
63
+ `CLAUDE.md`): read the root's and every agent's brief, one shared vault at
64
+ `<root>/<slug>-wiki/`, every agent's brief patched with `../<slug>-wiki/…` paths.
65
+
66
+ ## Step 1: Validate
67
+
68
+ 1. Slugify the name: lowercase, hyphenated, no surrounding whitespace. Reject a path
69
+ separator, a leading dot, or an empty result. Drop a trailing `-wiki` (it is added).
70
+ 2. If `<folder>/<slug>-wiki/CLAUDE.md` (or an older `<folder>/obsidian/CLAUDE.md`) already
71
+ exists, say the wiki exists and stop. Never overwrite: it protects accumulated knowledge.
72
+
73
+ ## Step 2: Gather context
74
+
75
+ Read the folder's `CLAUDE.md` and each `--agent` folder's `CLAUDE.md` and extract:
76
+
77
+ - **Purpose**: what the agent or swarm does, in one paragraph.
78
+ - **Key concepts / domain entities** it reasons about repeatedly.
79
+ - **Recurring source types**: where its inputs come from (digests, reports, emails, articles,
80
+ papers, transcripts).
81
+ - **What the wiki must NOT duplicate**: notebooks or logs it already keeps (a progress file,
82
+ a strategies list, task boards).
83
+
84
+ Infer 4-6 sub-folders for `wiki/` and 2-4 for `raw/`:
85
+
86
+ | Agent kind | wiki/ sub-folders | raw/ sub-folders |
87
+ |---|---|---|
88
+ | trading bot | strategies, indicators, regimes, signals, lessons | digests, reflects, research, market |
89
+ | email reviewer | senders, threads, topics, actions, lessons | inbox-snapshots, rules, research |
90
+ | research agent | sources, topics, entities, syntheses, lessons | papers, articles, transcripts |
91
+ | content creator | formats, audiences, voice, ideas, lessons | drafts, refs, examples |
92
+
93
+ If the domain fits none of these, infer reasonable names from the briefs and go on without
94
+ asking; the schema says this is an initial structure.
95
+
96
+ ## Step 3: Create the vault
97
+
98
+ Use hivey's script (in the hivey skill: `~/.claude/skills/hivey/scripts/new_wiki.py`, or
99
+ `~/.agents/skills/hivey/scripts/new_wiki.py` for Codex). It creates `<folder>/<slug>-wiki/` with `raw/`,
100
+ `wiki/`, `index.md`, `log.md`, a starter `CLAUDE.md` and `.obsidian/` (so Obsidian opens it as
101
+ a vault), copies the user's Obsidian look (theme, snippets, Style Settings) from the vault
102
+ remembered in `~/.hivey/wiki.json`, and adds a short "Memory" section to each `--agent`
103
+ folder's `CLAUDE.md`:
104
+
105
+ ```bash
106
+ python3 ~/.claude/skills/hivey/scripts/new_wiki.py <slug> --root <folder> \
107
+ --agent <folder or each swarm agent folder> ... --about "<one line: what it does>"
108
+ ```
109
+
110
+ It prints JSON with the vault `path`.
111
+
112
+ If the user has a main vault whose look new vaults should copy and none is remembered yet,
113
+ pass `--look-from <that vault>` once (it is remembered).
114
+
115
+ Then add the sub-folders from Step 2:
116
+
117
+ ```bash
118
+ mkdir -p <vault>/raw/<sub1> <vault>/raw/<sub2> ... <vault>/wiki/<sub1> <vault>/wiki/<sub2> ...
119
+ ```
120
+
121
+ ## Step 4: Write the wiki's CLAUDE.md
122
+
123
+ Replace the starter `<vault>/CLAUDE.md` with the "Wiki CLAUDE.md template" below, filled with
124
+ the context from Step 2. Keep every section (the wiki LLM reads only this file to learn its
125
+ contract): Purpose (concrete, not template wording), Scope rules, Folder structure (the actual
126
+ sub-folders), Ingest workflow, Page format, Citation rules (adapted to the source types),
127
+ Question answering, Lint workflow, Log format, Hard rules.
128
+
129
+ ## Step 5: Seed index.md and log.md
130
+
131
+ `<vault>/index.md`: a section header per `wiki/` sub-folder, each empty with a note that pages
132
+ are filed on first ingest. `<vault>/log.md`: a one-line preamble, the log format, and one
133
+ `bootstrap` entry dated today (`date -u +%Y-%m-%d`).
134
+
135
+ ## Step 6: Patch the agents' CLAUDE.md
136
+
137
+ The script added a short "Memory" section. Below it, add the "Agent CLAUDE.md section
138
+ template" to the folder's `CLAUDE.md` and each `--agent` folder's `CLAUDE.md`. Write vault
139
+ paths **relative to that file's folder**: `<slug>-wiki/…` for the agent's own folder,
140
+ `../<slug>-wiki/…` for a swarm agent one level down. Never absolute, so the folder still works
141
+ after it's moved or shared.
142
+
143
+ If `~/Obsidian/` exists and has no `<slug>-wiki` yet, also link it there so the user finds it
144
+ next to their other vaults: `ln -s <vault> ~/Obsidian/<slug>-wiki`.
145
+
146
+ ## Step 7: Report
147
+
148
+ A short summary: vault path, solo agent or swarm, sub-folders, which `CLAUDE.md` files were patched, how to
149
+ open it ("Obsidian → Open another vault → Open folder as vault → `<vault>`"; on first open,
150
+ "Turn on community plugins" so Style Settings loads, when a look was copied), and how to test:
151
+ `/hivey-wiki-ingest <path-to-source>` from the agent's folder.
152
+
153
+ End with `DONE: created <slug> wiki`.
154
+
155
+ ---
156
+
157
+ ## Wiki CLAUDE.md template
158
+
159
+ Replace the `{{...}}` placeholders with values from Step 2. Keep all section headings.
160
+
161
+ ```markdown
162
+ # LLM Wiki: {{Domain Title}}
163
+
164
+ A persistent, compounding knowledge base for {{the agent / the swarm}}.
165
+ Maintained by its agents following Andrej Karpathy's LLM Wiki pattern.
166
+
167
+ ## Purpose
168
+
169
+ {{One paragraph on what this wiki accumulates, from the briefs.}}
170
+
171
+ The wiki accumulates everything learned over time about:
172
+
173
+ {{- bullet list of 4-8 areas, from the key concepts in Step 2}}
174
+
175
+ The wiki is **separate from** {{any notebook/log the agent keeps, named}} and **separate
176
+ from** {{any raw daily input, named}}. Those are sources; the wiki is the synthesis on top.
177
+
178
+ ## Scope rules
179
+
180
+ - The wiki is **knowledge / synthesis only**: never live config, runnable code, or current
181
+ operational state. Link to operational state, do not duplicate it.
182
+ - {{Any agent-specific boundary.}}
183
+
184
+ ## Folder structure
185
+
186
+ \```
187
+ raw/ -- immutable sources (never modify)
188
+ {{sub-folders chosen in Step 2}}
189
+ wiki/ -- pages maintained by the agents
190
+ {{sub-folders chosen in Step 2}}
191
+ index.md -- catalog of all pages
192
+ log.md -- append-only operations log
193
+ \```
194
+
195
+ Sub-folders are an initial guess. Flatten when a folder has fewer than ~3 pages, split when
196
+ it exceeds ~15. Discuss reorganisations with the user.
197
+
198
+ ## Ingest workflow
199
+
200
+ When a new source arrives in `raw/` (or the user asks to ingest something):
201
+
202
+ 1. Read the full source.
203
+ 2. Discuss key takeaways with the user before writing when they are around; confirm what's
204
+ worth filing.
205
+ 3. Create a summary page in the right `wiki/` sub-folder, named after the source
206
+ (lowercase-hyphenated).
207
+ 4. Update or create concept pages for each major idea, entity, or topic the source touches.
208
+ **A single source typically touches 10-15 wiki pages; that is normal.**
209
+ 5. Add wiki-links (`[[page-name]]`) so every page has inbound and outbound links.
210
+ 6. Update `index.md` with new pages and one-line descriptions.
211
+ 7. Append an entry to `log.md` (see Log format).
212
+
213
+ ## Page format
214
+
215
+ \```markdown
216
+ # Page Title
217
+
218
+ **Summary**: One to two sentences describing this page.
219
+
220
+ **Sources**: List of raw source files this page draws from.
221
+
222
+ **Last updated**: YYYY-MM-DD
223
+
224
+ ---
225
+
226
+ Main content. Clear headings, short paragraphs. Link related concepts with [[wiki-links]].
227
+
228
+ ## Related pages
229
+
230
+ - [[related-concept-1]]
231
+ - [[related-concept-2]]
232
+ \```
233
+
234
+ Use Obsidian callouts when warranted (`> [!warning] Title`); types: `note`, `tip`, `warning`,
235
+ `danger`, `info`, `example`, `quote`.
236
+
237
+ ## Citation rules
238
+
239
+ - Every factual / quantitative claim references its source: `(source: filename.pdf p.42)`,
240
+ `(source: 2026-05-11 — title.md)`, or any unambiguous pointer to a file in `raw/`.
241
+ - If two sources disagree, note it in a `> [!warning]` callout and track the open question on
242
+ a `lessons/` (or equivalent) page.
243
+ - A claim without a source is marked `> [!info] Unverified` and flagged at the next lint.
244
+
245
+ ## Question answering
246
+
247
+ 1. Read `index.md` first to find relevant pages.
248
+ 2. Read those pages and synthesize an answer with wiki-page citations.
249
+ 3. {{If applicable: also read fresh operational data; never invent numbers.}}
250
+ 4. If the answer is not in the wiki, say so.
251
+ 5. If the answer is valuable, **offer to file it back as a new wiki page**.
252
+
253
+ ## Lint workflow
254
+
255
+ When asked to lint or audit, look for: contradictions between pages, stale claims newer
256
+ sources superseded, orphan pages (no inbound links), concepts in 3+ pages without their own
257
+ page, cross-reference gaps, format compliance (Summary / Sources / Last updated)
258
+ {{, source-coverage gaps if applicable}}. Report a numbered list with suggested fixes; do not
259
+ auto-fix, discuss first.
260
+
261
+ ## Log format
262
+
263
+ Every entry in `log.md` starts with a parseable prefix:
264
+
265
+ \```
266
+ ## [2026-05-12] ingest | <source name>
267
+ - Created: wiki/<folder>/<page>.md
268
+ - Updated: wiki/<folder>/<page>.md, index.md
269
+ - Notes: <one-line context>
270
+
271
+ ## [2026-05-12] query | "<question>"
272
+ - Read: wiki/<folder>/<page>.md, ...
273
+ - Filed answer back as: wiki/<folder>/<new-page>.md (if applicable)
274
+
275
+ ## [2026-05-12] lint
276
+ - Findings: N contradictions, M orphan pages, K stale points
277
+ \```
278
+
279
+ `grep "^## \[" log.md | tail -10` gives the last 10 operations.
280
+
281
+ ## Hard rules
282
+
283
+ - **Never** modify anything in `raw/`.
284
+ - **Never** put live config, runnable code, or current operational state in the wiki.
285
+ - **Always** update `index.md` and `log.md` after any wiki write.
286
+ - Page filenames: lowercase-hyphenated.
287
+ - {{If applicable: measured data wins over wiki narrative; when they disagree, update the
288
+ wiki.}}
289
+ ```
290
+
291
+ ---
292
+
293
+ ## Agent CLAUDE.md section template
294
+
295
+ Paths relative to the patched file's folder (`{{vault}}` = `<slug>-wiki` or `../<slug>-wiki`).
296
+
297
+ ```markdown
298
+ # {{Slug Title}} wiki: long-term knowledge base
299
+
300
+ You own the Obsidian wiki `{{vault}}/` (an independent vault). Its schema, page format,
301
+ citation rules and workflows are in `{{vault}}/CLAUDE.md`: **always** read it on your first
302
+ wiki touch in a session and follow it exactly.
303
+
304
+ - `{{vault}}/raw/`: immutable sources ({{sub-folders}}). Read-only.
305
+ - `{{vault}}/wiki/`: pages you write ({{sub-folders}}).
306
+ - `{{vault}}/index.md`: table of contents. Read it first when answering.
307
+ - `{{vault}}/log.md`: append-only operations log.
308
+
309
+ Scope: knowledge / synthesis ({{domain examples}}), never live config, runnable code or
310
+ current operational state. Do not duplicate {{named notebook}} or {{named raw input}}.
311
+
312
+ **This wiki is the default place for anything substantive you learn**: research findings,
313
+ summaries of what you read, decisions and their reasons, lessons from successes and failures,
314
+ useful references. Before writing a standalone note or report, ask whether it belongs in the
315
+ wiki instead; durable knowledge almost always does. Exceptions: live state, today's progress,
316
+ ephemeral status.
317
+
318
+ When to touch it:
319
+ 1. After every task that produces a finding: create or update the page, update `index.md`,
320
+ add a `log.md` entry. Filing is the default.
321
+ 2. When the user adds a source: the Ingest workflow.
322
+ 3. When the user asks a question: `index.md` first, answer from the pages, cite them, offer
323
+ to file a valuable answer back.
324
+ 4. When asked to lint or audit: the Lint workflow.
325
+ 5. When you'd otherwise write a report: write it as a wiki page instead.
326
+
327
+ Hard rules: never modify `{{vault}}/raw/`; no live config or operational state in the wiki;
328
+ always update `index.md` and `log.md` after a wiki write; filenames lowercase-hyphenated.
329
+ ```