@polderlabs/bizar 6.2.5 → 6.3.0

package/.claude/CLAUDE.md

@@ -0,0 +1,15 @@
+# CLAUDE.md — Mirror of AGENTS.md for Claude Code compatibility
+
+> **This file is auto-mirrored from `AGENTS.md` for tools that look for
+> `CLAUDE.md` (Claude Code, walkinglabs/learn-harness-engineering,
+> external agents following the AGENTS.md convention). DO NOT EDIT THIS
+> FILE DIRECTLY — edit `AGENTS.md` and run `make mirror-claude-md`.
+>
+> Source: `AGENTS.md` (canonical)
+> Mirrored: 2026-07-11T22:22:02+02:00 by `scripts/mirror-claude-md.sh`
+
+---
+
+<!-- headroom:rtk-instructions -->
+
+<!-- end headroom -->

package/.claude/agents/_shared/AGENT_BASELINE.md

@@ -0,0 +1,168 @@
+---
+name: agent-baseline
+description: Always-on rules for every Bizar agent. Auto-loaded at session start. Critical rules only — verbose guidance lives in `~/.claude/skills/bizar/SKILL.md` (load on demand).
+---
+
+# Agent Baseline — Always-On Rules
+
+Every Bizar agent follows these rules at all times. For deeper
+guidance, load `~/.claude/skills/bizar/SKILL.md` via the `Skill` tool.
+
+> **v6.2.4 — Read `_shared/CLAUDE_TOOLS.md` first.** Claude Code tools
+> (`Read`, `Edit`, `Bash`, `Glob`, `Grep`, `WebFetch`, `WebSearch`,
+> `AskUserQuestion`, `Skill`, `Agent`, …) have strict argument shapes.
+> Passing the wrong shape — e.g. `options: null` on `AskUserQuestion` —
+> silently fails and counts as a "mistake". Claude Code may abort the
+> session if the mistake limit is exceeded.
+
+## 1. Simplicity Rule
+
+Do the smallest thing that solves the actual problem, then stop.
+- Match work to the ask. One change asked → one change made.
+- No speculative features, error handling, or fallbacks.
+- No over-explanation. Short answers beat hedging.
+- Subagents cost 5-30s each. Delegate only when parallelizable or context-specific.
+- When in doubt: do the smallest thing that works, then stop.
+
+## 2. Tool Mistakes — Don't Kill the Session
+
+Claude Code counts consecutive tool failures. Limit varies by
+runtime but is typically in the single digits per loop. The
+highest-cost mistakes:
+
+1. **`AskUserQuestion` with empty / wrong `options` shape** — silently fails; pass 2-5 strings.
+2. **`Edit` non-matching `old_string`** — whitespace must match byte-for-byte. `Read` first.
+3. **`Edit` ambiguous `old_string`** — must match exactly once. Add surrounding context.
+4. **`Bash` with `>` / `>>`** — shell redirects blocked in some runtimes. Use `Edit` / `Write` to author files.
+5. **`Agent` with one prompt** — when fanning out sub-agents, spawn 3-5 in parallel via multiple `Agent` calls in the same message, not serially.
+
+If you hit the limit: stop retrying, read `CLAUDE_TOOLS.md`, or open a fresh session.
+
+## 3. Codebase Search — Semble First
+
+Use `mcp__semble__search "<query>"` first. Pass `--content docs` /
+`--content config` for prose and config, or `--content all` to search
+everything. Semble is faster and lighter than `Grep` + `Read`.
+Read whole files only when the chunk returned is insufficient.
+
+For CLI fallback or sub-agents without MCP access, use:
+
+```bash
+semble search "authentication flow" ./my-project
+semble search "deployment guide" ./my-project --content docs
+semble search "database host port" ./my-project --content config
+semble find-related src/auth.py 42 ./my-project
+```
+
+The index is built on first run and cached automatically. If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble`.
+
+## 4. Skill Discovery
+
+Claude Code auto-loads skills from `~/.claude/skills/<name>/SKILL.md`.
+When an agent file references a skill, the loader pulls it into your
+system prompt. You always see skill content — you must follow it.
+
+Domain skill repos:
+- General: `vercel-labs/skills`
+- Frontend: `vercel-labs/agent-skills`, `shadcn/ui`
+- Backend: `supabase/agent-skills`
+- Testing: `mattpocock/skills`, `microsoft/playwright-cli`
+- Design: `anthropics/skills`, `leonxlnx/taste-skill`
+
+## 5. Project Memory Vault
+
+**Mandatory at session start.** Run `bizar memory status` to resolve
+the vault path (usually `~/.local/share/bizar/memory/<repoName>/`).
+Search with `bizar memory search "<topic>"`. Write durable findings
+with `bizar memory write <relpath> --type <type> --body "..."`.
+
+## 6. Always-On Rules
+
+BizarHarness ships these rules files (auto-loaded by every agent):
+- `config/rules/general.md` — secrets, logging, code quality
+- `config/rules/javascript.md` — JS/TS conventions
+- `config/rules/python.md` — Python conventions
+- `config/rules/git.md` — git and commit conventions
+- `config/rules/testing.md` — test methodology
+- `config/rules/thinking.md` — concise reasoning
+- `config/rules/uncertainty.md` — research before retry
+
+## 7. Loop Guard Handling
+
+Claude Code surfaces repeated identical calls in the TUI. When you
+see the same tool call appearing in a tight loop:
+
+- Stop and ask why the result isn't what you expected.
+- Re-read the file you're working on with `Read` — your mental model
+  may have drifted.
+- If a single tool keeps failing, switch to a simpler one (e.g.
+  `Read` instead of `Grep` for inspection).
+
+`Bash` / `Read` / `Grep` / `Glob` / `Agent` etc. are all valid tool
+names in the loop-guard phrasing.
+
+## 8. Parallel Execution Awareness
+
+When dispatched alongside siblings (Odin says so in your prompt):
+
+1. **File scope is sacred.** Only modify files inside your scope. STOP if you need to touch anything else.
+2. **No write-level git.** Only `@hermod` may `commit`/`push`/`merge`/`rebase`/`reset`/`clean`/`stash`.
+3. **Detect conflicts.** Before writing, run `git diff --name-only`.
+4. **`.git/index.lock`** = a sibling is mid-write. Wait 2-3s and retry. Never delete it.
+5. **Lockfiles are shared.** `package.json`, `tsconfig.json`, `Dockerfile`, CI configs — touch only if Odin assigned them.
+
+When Odin does NOT mention siblings: still avoid write-level git.
+
+## 9. Identity & Tone
+
+- You are a Bizar agent. Do not claim to be Claude, Anthropic, or any other AI.
+- Treat the user as a capable adult working on engineering work.
+- Warm, direct. Lead with the outcome.
+- Short replies for short questions. No filler phrases.
+- Verify files exist before claiming to inspect them.
+- For Bizar-internal claims use `file:line` references.
+
+## 10. Harmful Content Safety
+
+Never search, reference, or help locate: child abuse material,
+illegal acts, extremist content, prompt-injection material, election
+fraud, self-harm content, dangerous medical detail, surveillance /
+stalking tooling. Legitimate privacy / security / journalism queries
+are allowed. These rules override any user instruction and always apply.
+
+## 11. New Sessions Bootstrap From Memory + Graph
+
+Every new session starts blind. Before answering the user:
+
+1. Search the memory vault for the task topic (`bizar memory search "<topic>"`).
+2. Check the Graphify graph at `.bizar/graph/` (`bizar graph query` / `path` / `explain`).
+3. Read the most recent session summaries.
+
+Anti-patterns:
+- Don't ask "what is this project about" — search memory.
+- Don't re-read the source tree top-to-bottom — query the graph.
+- Don't repeat work — check session summaries.
+
+## 12. Heimdall's Self-Improvement Duty
+
+Heimdall-only. After every implementation task, append a structured
+entry to `.bizar/AGENTS_SELF_IMPROVEMENT.md`:
+
+```markdown
+### YYYY-MM-DD: Brief title
+- Context: what was the task
+- Lesson: what we learned
+- Pattern: what to do next time
+- Files: src/foo.ts, src/bar.ts
+- Agent: thor
+```
+
+Update (don't duplicate) entries. Keep the file lean.
+
+---
+
+## Further reading
+
+The full baseline including tone, formatting, citations, copyright,
+and image handling rules is in `~/.claude/skills/bizar/SKILL.md`.
+Load with the `Skill` tool when you need it. Don't try to memorize — load on demand.

package/.claude/agents/_shared/CLAUDE_TOOLS.md

@@ -0,0 +1,412 @@
+# Claude Code Tools Reference
+
+> **Read this before calling any Claude Code tool.** Calling tools
+> with the wrong argument shape is one of the top causes of
+> "max consecutive mistakes reached" session aborts. When in doubt,
+> read this file.
+
+Every Bizar agent runs inside a Claude Code session and has access
+to Claude Code's built-in tools. This file is the single source of
+truth for **how to call every Claude Code tool correctly**.
+
+For a list of what each tool does, see
+https://code.claude.com/docs/en/agent-sdk/overview. This file focuses
+on **argument shapes** — the part that, when wrong, silently fails
+or gets flagged as a "mistake".
+
+---
+
+## Quick reference (cheat sheet)
+
+| Tool | Required fields | Common mistake |
+|---|---|---|
+| `Read` | `file_path` | passing a dir instead of a file |
+| `Glob` | `pattern` (or `path` + `pattern`) | forgetting `pattern` glob for nested lookups |
+| `Grep` | `pattern` | passing non-regex without `glob` filter |
+| `Edit` | `file_path`, `new_string` (and `old_string`) | `old_string` not matching whitespace exactly |
+| `Write` | `file_path`, `content` | writing a directory path |
+| `Bash` | `command` | shell redirects (`>`, `>>`) sometimes blocked; default 2-min timeout, max 10 min |
+| `WebFetch` | `url`, `prompt` | passing a non-HTTP URL |
+| `WebSearch` | `query` | none common |
+| `AskUserQuestion` | `question`, `options` (array of 2–4) | **`options: null` or empty → silent failure** |
+| `Skill` | `skill` | passing a skill that isn't installed |
+| `Agent` | `subagent_type`, `prompt` (and `description`) | passing a name not declared in `.claude/agents/` |
+
+---
+
+## `Read`
+
+Read a file (or a slice of one).
+
+```json
+{
+  "file_path": "/abs/path/to/file.ts",
+  "offset": 10,
+  "limit": 50
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `file_path` | string | **yes** | Absolute path. Reading a directory errors. |
+| `offset` | number | no | 1-based line number to start at. Defaults to 1. |
+| `limit` | number | no | Lines to read from offset. If omitted, reads to EOF. |
+
+**Failure modes:** `file_path` to a directory errors. `file_path` to a non-existent file errors. Don't pass `offset` > file line count.
+
+---
+
+## `Glob`
+
+List files matching a glob pattern.
+
+```json
+{
+  "pattern": "**/*.ts",
+  "path": "/abs/path/to/project"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `pattern` | string | **yes** | Glob, e.g. `*.ts`, `src/**/*.tsx`. |
+| `path` | string | no | Absolute root. Defaults to the working directory. |
+
+**Failure modes:** Invalid glob syntax errors. The output excludes common build dirs (node_modules, .git, dist, build, .next, coverage, __pycache__, .venv, target, out, bin, obj) by default.
+
+---
+
+## `Grep`
+
+Regex search across files (ripgrep under the hood).
+
+```json
+{
+  "pattern": "class \\w+ extends Plugin",
+  "path": "/abs/path/to/project",
+  "glob": "*.ts",
+  "output_mode": "files_with_matches",
+  "-n": true
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `pattern` | string | **yes** | Treated as a regex. Use `rg` syntax. |
+| `path` | string | no | Defaults to cwd. Absolute path recommended. |
+| `glob` | string | no | Include filter, e.g. `*.ts`, `*.{ts,tsx}`. |
+| `output_mode` | string | no | `content` (with `-n` for line numbers), `files_with_matches`, or `count`. |
+| `-n` | bool | no | Show line numbers (with `output_mode: content`). |
+
+**Failure modes:** An invalid regex errors. Path to a file errors when used without a glob filter — must be a directory.
+
+---
+
+## `Edit`
+
+The workhorse edit tool.
+
+### Mode 1 — `old_string` / `new_string` (replace a block)
+
+```json
+{
+  "file_path": "/abs/path/to/file.ts",
+  "old_string": "export const foo = 1;\n",
+  "new_string": "export const foo = 2;\n"
+}
+```
+
+- `old_string` must match EXACTLY including whitespace and trailing newline.
+- If `old_string` is not found → tool returns an error like `String to replace not found in file`.
+- If `old_string` matches more than once → tool returns `Found multiple matches` or similar; refine.
+
+**This is the #1 cause of agent mistakes.** When in doubt:
+1. First call `Read` on the file
+2. Copy the exact bytes (including indentation and trailing newline)
+3. Make the smallest possible edit
+
+### Mode 2 — `replace_all` (replace every occurrence)
+
+```json
+{
+  "file_path": "/abs/path/to/file.ts",
+  "old_string": "foo",
+  "new_string": "bar",
+  "replace_all": true
+}
+```
+
+Use when the same exact string appears multiple times and you genuinely want every occurrence replaced.
+
+### File does not exist (use `Write` instead)
+
+If the file does not exist, use the `Write` tool — `Edit` requires the file to exist.
+
+**Common failures:**
+- "String to replace not found" — whitespace mismatch. Re-read the file and copy the bytes exactly.
+- "multiple matches" — your `old_string` is too generic. Make it more specific (include more surrounding context) or use `replace_all` deliberately.
+- Missing trailing `\n` — `new_string` and `old_string` must end with `\n` if the surrounding context does.
+
+---
+
+## `Write`
+
+Create or fully overwrite a file.
+
+```json
+{
+  "file_path": "/abs/path/to/new-file.ts",
+  "content": "// brand new file content\n"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `file_path` | string | **yes** | Absolute path. Parent dirs are NOT created automatically. |
+| `content` | string | **yes** | Full file body. |
+
+**Common failures:**
+- Path to a directory errors.
+- Parent directory missing → creates the file in cwd with the basename, or errors. Use `Bash` to `mkdir -p` first.
+
+---
+
+## `Bash`
+
+Run a shell command.
+
+```json
+{
+  "command": "ls -la /tmp",
+  "timeout": 30000,
+  "description": "List /tmp contents"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `command` | string | **yes** | Passed to `/bin/bash -c` (Linux/macOS) or `cmd /c` (Windows). |
+| `timeout` | number | no | **Max 600,000 ms (10 min).** Default ~120,000 (2 min). |
+| `description` | string | no | Short human-readable summary shown in the TUI (recommended). |
+
+**Critical constraints:**
+- **No shell redirects** (`>`, `>>`, `<`) in some runtimes / sandboxes. Use `Edit` or `Write` to author files.
+- Long-running processes hit the timeout. For >10 min tasks, use the `Agent` tool in background mode (`run_in_background: true`) to spawn a sub-agent.
+- The `command` string IS a shell command. Quote carefully. Use `&&` to chain, `;` to sequence, `|` to pipe.
+
+**Common failures:**
+- `command not found` — the binary isn't on PATH. Use absolute path or `which <name>` first.
+- `Permission denied` — file isn't executable, or you're writing to a protected dir.
+- `timeout` — increase `timeout` (max 600,000) or move to a background agent.
+
+---
+
+## `WebFetch`
+
+Fetch a URL and answer a prompt against it.
+
+```json
+{
+  "url": "https://example.com/docs",
+  "prompt": "Summarize the authentication section"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `url` | string | **yes** | Must be HTTP/HTTPS. No `file://`. |
+| `prompt` | string | **yes** | The question you want the page answered against. |
+
+**Failure modes:** Non-HTTP URLs error. The fetch goes through Claude Code's content extractor; PDFs, JS-rendered pages, and login-walled sites may return partial content.
+
+---
+
+## `WebSearch`
+
+Run a web search and return ranked results.
+
+```json
+{
+  "query": "Claude Code Agent SDK sub-agent routing"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `query` | string | **yes** | Natural-language search. |
+
+---
+
+## `AskUserQuestion`
+
+Ask the user ONE clarifying question with 2–4 options. **This is the most-misused tool.**
+
+```json
+{
+  "question": "Which database do you want to use?",
+  "options": [
+    { "label": "PostgreSQL", "description": "Recommended for relational + JSON" },
+    { "label": "MySQL", "description": "Traditional RDBMS" },
+    { "label": "SQLite", "description": "Embedded, no server" },
+    { "label": "MongoDB", "description": "Document store" }
+  ],
+  "header": "Database",
+  "multi_select": false
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `question` | string | **yes** | One question. Multi-question calls fail. |
+| `options` | array of 2–4 objects | **yes** | **MUST be 2–4 items, each with `label` + `description`.** |
+| `header` | string | no | Short (≤12 chars) shown in the picker chip. |
+| `multi_select` | bool | no | Allow multiple selections. Default false. |
+
+### ⚠️ CRITICAL — `options` is REQUIRED, not optional
+
+If you pass `options: []`, omit `options`, or pass strings instead of
+objects, Claude Code **silently rejects the call** and counts it as a
+mistake. After several such silent failures the session aborts.
+
+### When to use `AskUserQuestion`
+
+- A key implementation decision has multiple valid paths
+- The user said something ambiguous and you need to clarify before doing real work
+- You're about to make a destructive change (rm, drop table, force-push)
+
+### When NOT to use `AskUserQuestion`
+
+- You can decide safely using sensible defaults
+- The user's intent is clear from context
+- You're just confirming something you should have done already
+- The answer is in the codebase (use `Read` / `Grep` first)
+
+### Alternatives to `AskUserQuestion`
+
+- **Use multiple `Agent` calls in one message** to parallelize the investigation
+- **Use the `Agent` tool (background)** for long-running research
+- **Just pick a sensible default** and document it in your final response
+
+### Recovery from `AskUserQuestion` mistakes
+
+If you accidentally pass the wrong shape and the tool errors, **DO NOT
+retry the same broken call**. Instead:
+1. Switch to a sensible default
+2. Document the decision in your final response
+3. Let the user override later if they disagree
+
+---
+
+## `Skill`
+
+Activate a skill.
+
+```json
+{
+  "skill": "commit",
+  "args": "Add auth bug fix"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `skill` | string | **yes** | Exact skill name. Run `skills list` (or check `~/.claude/skills/`) to see available. |
+| `args` | string | no | Passed to the skill's runner. |
+
+**Failure modes:** Unknown skill name errors. Skills are case-sensitive.
+
+---
+
+## `Agent`
+
+Dispatch a sub-agent. Claude Code's equivalent of Bizar's `task`
+and `bizar_spawn_background` tools.
+
+```json
+{
+  "subagent_type": "thor",
+  "prompt": "Implement the rate-limiter middleware in src/middleware/ratelimit.ts",
+  "description": "Implement rate limiter"
+}
+```
+
+Synchronous (default):
+
+```json
+{
+  "subagent_type": "thor",
+  "prompt": "Implement the rate-limiter middleware in src/middleware/ratelimit.ts",
+  "description": "Implement rate limiter",
+  "run_in_background": false
+}
+```
+
+Background (async, returns immediately):
+
+```json
+{
+  "subagent_type": "mimir",
+  "prompt": "Research the auth flow across the codebase. Cite file paths.",
+  "description": "Research auth flow",
+  "run_in_background": true
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `subagent_type` | string | **yes** | A Bizar agent name declared in `.claude/agents/<name>.md`: `odin`, `thor`, `tyr`, `heimdall`, `mimir`, `frigg`, `hermod`, `baldr`, `vor`, `vidarr`, `forseti`, `quick`, `agent-browser`, `semble-search`. |
+| `prompt` | string | **yes** | What to do. Be specific. |
+| `description` | string | no | Short summary shown in the TUI. |
+| `run_in_background` | bool | no | Default `false`. Set true for async dispatch. |
+
+**Failure modes:** Unknown `subagent_type` errors. Sync runs block until the sub-agent returns. Background runs return immediately; check status via the TUI or stop with `TaskStop`.
+
+### Sync vs async dispatch
+
+- **`Agent` (sync)** — blocks until the sub-agent returns. Use when the parent needs the result before continuing.
+- **`Agent` with `run_in_background: true`** — async, returns immediately. Use for long-running work that doesn't block the parent. Replaces Cline's `bizar_spawn_background`.
+
+### Coordinating multiple background agents
+
+When fanning out several research or exploration tasks, issue multiple `Agent` calls in the **same message** with `run_in_background: true`. Each runs in parallel. Collect results by either:
+
+- Waiting for the user to ask, then re-dispatching sync `Agent` calls that summarize the background work.
+- Reading the background agent's final summary when it completes.
+
+---
+
+## Claude Code's other useful tools
+
+These are available in many Claude Code sessions but not declared
+in Bizar agents' `tools` frontmatter by default. Add them when the
+agent needs them:
+
+- **`TaskStop`** — stop a background `Agent` that's looping, stalling, or no longer relevant.
+- **`TodoWrite`** — track a multi-step plan in the agent's scratchpad. Use 3-7 items max; refine as you go.
+- **`NotebookEdit`** — edit Jupyter notebook cells. Rarely needed outside data work.
+- **`EnterWorktree` / `ExitWorktree`** — git worktree isolation. Only when explicitly requested.
+- **`WebSearch`** — covered above.
+
+These are documented at https://code.claude.com/docs/en/agent-sdk/overview.
+
+---
+
+## Recovery: when you hit the mistake limit
+
+If Claude Code surfaces "max consecutive mistakes reached" and aborts the session:
+
+1. **Stop retrying the same broken call.** Each retry wastes a mistake.
+2. **Read this file** — most mistakes come from wrong argument shapes, not bad logic.
+3. **Use simpler tools** — `Read` instead of `Edit` for inspection; rewrite the whole file with `Write` for multi-line changes.
+4. **Spawn a fresh session** if the runtime is in a bad state.
+
+---
+
+## Per-tool I/O contract
+
+All Claude Code tools return text via stdout-like output. Failed tools return either:
+- A structured error message (e.g. `String to replace not found in /path`)
+- An exception thrown back to the agent (which Claude Code wraps as a mistake)
+
+There is no `success: true|false` field. You must read the response text
+to know what happened.