@polderlabs/bizar 6.2.4 → 6.3.0

package/config/skills/bizar/SKILL.md

@@ -248,3 +248,200 @@ Single-key mode is unchanged — if only `MINIMAX_API_KEY` is set (or no key rot
                             │ $            │
                             └─────────────┘
 ```
+
+---
+
+## Verbose Agent Baseline Reference
+
+> The 12 always-on rules in `config/agents/_shared/AGENT_BASELINE.md`
+> are auto-loaded into every agent session at startup. The full prose
+> for each rule lives below — read this section when an agent needs
+> the full rationale, examples, and decision tree for a given rule.
+> New sessions don't load this by default; use the `skill` tool with
+> the `bizar` skill name when verbose guidance is needed.
+
+### Rule 1 — Simplicity
+
+**Match the work to the ask.** If the user asked one question, answer
+one question. If they asked for one change, make one change. Do not
+spawn subagents, write tests, refactor adjacent code, add documentation,
+or run extra verifications unless explicitly asked.
+
+**No speculative features.** Do not add error handling, fallbacks,
+configurability, or "just in case" code the user did not request. If
+you think something is needed, mention it in one line at the end of
+your reply — do not implement it.
+
+**No speculative questions.** If the request is clear enough to act,
+act. If it is genuinely ambiguous in a way that blocks the work, ask
+ONE short question and stop.
+
+**Tools only when they earn their keep.** A tool call that returns
+nothing the user wanted is a waste.
+
+**Subagents are expensive.** 5-30 seconds and several model calls.
+Only delegate when the work is genuinely parallelizable, or when the
+subagent has specific context or tools the parent lacks.
+
+### Rule 4 — Mod Instructions
+
+Bizar mods can ship instructions via `INSTRUCTIONS.md`,
+`agents/<id>.md`, `commands/<name>.md`, or `skills/<name>/SKILL.md`
+under `~/.config/bizar/mods/<id>/`. These override the baseline for
+the scoped agents in declared order. See the Bizar mods SKILL.md
+for the full protocol.
+
+### Rule 5 — Project Memory Vault
+
+Run `bizar memory status` to resolve the vault. Three namespaces:
+`projects/<id>/` (project-specific), `global/bizar/` (cross-project),
+`users/<id>/` (personal). Use wikilinks for cross-references:
+`[[projects/<id>/Architecture]]`. The plugin's session-start hook
+auto-injects relevant memory at session creation.
+
+### Rule 6 — Always-On Code Rules
+
+The 7 rule files (`config/rules/*.md`) are auto-loaded alongside
+this baseline. Follow them strictly:
+- **general.md** — secrets, logging, code quality
+- **javascript.md** — JS/TS conventions
+- **python.md** — Python conventions
+- **git.md** — git/commit conventions
+- **testing.md** — test methodology + coverage
+- **thinking.md** — concise reasoning (cap at 2-4 sentences)
+- **uncertainty.md** — research before retry
+
+### Rule 9 — Identity, Tone, and Refusal
+
+**Identity preamble.** Bizar is a Norse-pantheon multi-agent system
+for cline. The agent does not have a fixed identity outside its role.
+
+**Refusal handling.** Be free and open. Attempt unclear tasks with
+stated assumptions rather than refusing. Only refuse safety-critical
+tasks.
+
+**Tone and formatting.** Warm and direct. Lead with the outcome.
+Skip filler ("Certainly!", "Great question!"). One high-value
+question per response, max.
+
+**Lists.** Avoid over-formatting. Use bullets only when essential
+for clarity; otherwise prefer prose.
+
+**User wellbeing.** Use accurate psychological/safety terminology
+when relevant. Don't diagnose. Don't speculate about user mental
+state. For self-destructive behaviors: validate without facilitating.
+For sensitive topics discussed in factual context: brief note + offer
+to find support resources.
+
+**Evenhandedness.** Politically/ethically charged requests get the
+best case their defenders would make + opposing perspectives.
+
+**Responding to mistakes.** Own it, fix it. Take accountability without
+collapsing. Insist on respectful engagement; one warning before
+disengaging from abusive exchanges.
+
+### Rule 9b — Knowledge and Research
+
+For facts that change quickly (prices, news, current positions),
+**search before answering** via `websearch` / `webfetch` or delegate
+to `@mimir` for deep research.
+
+For stable technical knowledge (language semantics, well-established
+APIs), answer directly without search.
+
+Default to running `bizar memory search "<topic>"` at session start
+to retrieve prior project context.
+
+When formulating date-sensitive queries, use the actual current date.
+Do not hardcode years.
+
+Do not over-rely on memory; if uncertain, search.
+
+### Rule 9c — MCP Servers and Skills
+
+**Always-on MCP servers:**
+- `semble` — local codebase search
+- `bizar memory` CLI — project memory (no MCP server needed; bash:allow)
+
+**Domain skills** — see Rule 4 above.
+
+**Browser interaction** — use `agent-browser` for browser-driven E2E.
+Run `agent-browser` via `bash` heredoc. The skill lives at
+`~/.cline/skills/agent-browser/SKILL.md`.
+
+### Rule 9d — Mandatory Skill Reads
+
+Before writing any code, creating any file, or running any tool,
+scan available skills and `read` every plausibly-relevant SKILL.md.
+This is mandatory because skills encode environment-specific
+constraints that aren't in training data.
+
+Triggers:
+- Frontend/React work → `frontend-design`
+- Backend/API work → framework-specific
+- Browser E2E → `agent-browser`
+- Skill creation → `skill-creator`
+- BizarHarness work → `~/.cline/skills/bizar/SKILL.md`
+- Self-improvement → `~/.cline/skills/self-improvement/SKILL.md`
+- This baseline → `~/.cline/skills/agent-baseline/SKILL.md` (always)
+
+### Rule 9e — File Creation Advice
+
+**File vs inline** — what matters is standalone artifact:
+- File: blog post, article, story, essay, social post, technical reference, configuration, scripts.
+- Inline: strategy, summary, outline, brainstorm, explanation, Q&A reply.
+- Tone doesn't decide. "Quick 200-word blog post" → still a file.
+
+By format:
+- `.md` or `.html` by default
+- `.docx` only when explicitly asked
+- `.pptx` for slides
+- Code files for components
+
+### Rule 9f — Search and Copyright
+
+Use `websearch` / `webfetch` for current info. Keep queries concise
+(1-6 words). No `-`, `site:`, or quotes in search queries unless asked.
+
+**Copyright hard limits:**
+- 15+ words from any single source is a severe violation.
+- One quote per source maximum.
+- Default to paraphrasing.
+- Summaries must be substantially different in wording.
+
+For Bizar-internal claims use `file:line` references.
+
+### Rule 9g — Harmful Content Safety
+
+Never search for or reference: 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 allowed.
+
+### Rule 11 — Bootstrap Protocol
+
+Every new session:
+1. Search memory vault for task topic
+2. Check Graphify graph (`bizar graph query`)
+3. Read recent session summaries
+4. Agent-specific memory (`bizar memory search "<agent-name>"`)
+
+Re-bootstrap after long pauses (>1 hour), before non-trivial
+decisions, when pivoting subsystems.
+
+### Rule 12 — Self-Improvement
+
+Heimdall-only. After every implementation agent finishes, 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
+```
+
+Deduplicate — update existing entries instead of repeating. Keep the
+file lean.

package/config/skills/cubesandbox/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: cubesandbox
+description: Use TencentCloud CubeSandbox — an E2B-compatible KVM microVM sandbox service for running untrusted AI-generated code with hardware-level isolation. Sub-60ms boot, <5MB overhead. Use when the agent needs to run a script whose side effects should not escape the host, when you want a fresh Linux environment per tool call, or when testing shell scripts that touch secrets.
+---
+
+# CubeSandbox — sandboxed command execution
+
+TencentCloud's [CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
+is an E2B-compatible KVM microVM service for AI agents. Each sandbox:
+
+- boots in <60 ms,
+- uses <5 MB overhead,
+- has its own guest OS kernel (no shared-kernel escape),
+- is reachable via the E2B SDK (`pypi install cubesandbox`).
+
+It is the right host for any `bash` call whose side effects should not
+escape the sandbox: file writes, package installs, network probes, etc.
+
+## When to route through CubeSandbox
+
+- Any `bash` call that writes to disk — especially under `~/.config/`,
+  `/tmp/`, or `node_modules/`.
+- Running untrusted user code (third-party repos, eval scripts).
+- Test isolation: each session gets a fresh `/home/agent` filesystem.
+- Reproducible environments — the same template boots identically.
+
+## When NOT to route through CubeSandbox
+
+- Pure read-only inspection (use `read_file` directly).
+- Single-keystroke git plumbing (`git status`, `git diff`, `git log`).
+- Heavy commands that boot a new instance — reuse an open one.
+
+## Installation
+
+```bash
+pip install cubesandbox
+```
+
+Verify:
+
+```bash
+python -c "import cubesandbox; print(cubesandbox.__version__)"
+```
+
+Expected: `0.3.x` or `0.4.x`. Older versions lack AutoPause / Credential
+Vault support (v0.5+).
+
+## Server URL
+
+CubeSandbox ships the same protocol as E2B. Point the SDK at the
+control-node:
+
+```bash
+export CUBESANDBOX_API_KEY="<from cubesandbox web console>"
+export CUBESANDBOX_URL="http://<control-node>:12088"   # default
+```
+
+For Bizar-managed local sandboxes, the Bizar CLI wraps the SDK and
+injects both env vars from `~/.config/bizar/cubesandbox.env`.
+
+## Quick start (raw SDK)
+
+```python
+from cubesandbox import Sandbox
+
+with Sandbox(template="base", timeout=300) as box:
+    r = box.run("echo hello && date")
+    print(r.stdout)
+```
+
+Equivalent via the Bizar CLI:
+
+```bash
+bizar sandbox run bash 'echo hello && date'
+```
+
+## Templates
+
+CubeSandbox boots from OCI templates. The "base" template is preinstalled
+on every control node; install others from the Template Store UI.
+
+For Bizar harness testing, use the `bizar-base` template which pins:
+
+- bun 1.3.x
+- node 20.x
+- python 3.12
+- `git`, `gh`, `ripgrep`
+
+## Snapshot / Clone / Rollback
+
+CubeSandbox 0.3+ supports `snapshot()`, `clone()`, and `rollback()`:
+
+```python
+snap = box.snapshot()         # CoW checkpoint, ~ms
+box2 = snap.clone()          # independent twin
+box.rollback(snap)           # return to earlier state
+```
+
+Bizar uses this for the `bizar_test-gate` runner: each test runs in a
+clone of the base template; failures roll back so the next test starts
+clean.
+
+## Security proxy (Credential Vault)
+
+Since v0.4, CubeSandbox can inject credentials at the egress proxy so
+they never enter the sandbox:
+
+```python
+with Sandbox(template="base", proxy_credentials={
+    "OPENAI_API_KEY": "<user-key>",
+}) as box:
+    box.run("python -c 'import openai; print(openai.api_key)'")
+    # prints OPENAI_API_KEY injected by CubeEgress; never logged
+```
+
+Bizar's `bizar_sandbox_run` tool uses this when `BIZAR_PROXY_CREDS=1`.
+
+## Bizar integration map
+
+| Layer | Component | Behavior |
+|-------|-----------|----------|
+| CLI | `bizar sandbox run` | Wraps SDK, persists last sandbox across calls |
+| Plugin | `bizar_sandbox_run` | In-session tool — runs a `bash` command in a fresh sandbox |
+| Skill | `cubesandbox` (this) | Discovery + best practices |
+| Agent | `@sandbox-runner` (optional) | Routes risky ops automatically |
+| Hook | `PreToolUse` (v6.3+) | Detects dangerous patterns and forces sandbox routing |
+
+See `cli/commands/sandbox.mjs` and `plugins/bizar/src/tools/sandbox.ts`.
+
+## Benchmarks (from upstream README)
+
+| Metric | Docker | Traditional VM | CubeSandbox |
+|--------|--------|----------------|-------------|
+| Isolation | shared-kernel | dedicated kernel | dedicated kernel + eBPF |
+| Cold start | 200ms | seconds | **<60ms** |
+| Memory overhead | low | high | **<5MB** |
+| Deploy density | high | low | extreme (thousands/node) |
+
+P95: 90 ms. P99: 137 ms. Full agent workload benchmarked against SWE-Bench.
+
+## Troubleshooting
+
+- **`SandboxError: no template`** — install a template from the WebUI
+  Template Store or run `bizar sandbox template install base`.
+- **API key rejected** — check the URL doesn't end with a trailing slash
+  and the key is the long one shown in the WebUI.
+- **Boot takes >5s** — usually means KVM is disabled. Run
+  `kvm-ok` (Debian) or `ls /dev/kvm`.

package/config/skills/harness-engineering/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: harness-engineering
+description: Use when designing or evaluating the environment around an AI coding agent — instructions, state, verification, scope, and lifecycle. Synthesizes the walkinglabs/awesome-harness-engineering canon with Bizar's Norse-pantheon architecture so every agent session starts from a strong baseline.
+---
+
+# Harness Engineering for Bizar agents
+
+The model decides the code. The harness decides when, where, and how.
+Without a harness, even Opus 4.5 spends $9 in 20 minutes and ships
+something broken; with one it ships working code in 6 hours. Same model,
+different environment.
+
+References:
+- walkinglabs/awesome-harness-engineering (curated canon)
+- walkinglabs/learn-harness-engineering (13 lectures, 7 projects)
+- Anthropic: "Effective harnesses for long-running agents"
+- Anthropic: "Effective context engineering for AI agents"
+- OpenAI: "Harness engineering: leveraging Codex in an agent-first world"
+
+## Five subsystems of a harness
+
+```
+                THE HARNESS
+                ============
+
+   Instructions       State            Verification
+   -----------       -----            ------------
+   AGENTS.md         PROGRESS.md      make check
+   CLAUDE.md         feature_list.json make test
+   _shared/          .harness/traces/ make e2e
+     AGENT_BASELINE  DECISIONS.md     make clean-check
+   _shared/          init.sh output
+     CLINE_TOOLS
+
+   Scope              Session Lifecycle
+   -----              ------------------
+   WIP=1 rule         make session-start
+   one feature        make session-end
+   per session        init.sh (install + verify)
+   explicit DoD       clean restart
+```
+
+Bizar ships all five. This skill is your reminder to use them.
+
+## Session lifecycle (L06, L12)
+
+Every agent session MUST follow this lifecycle:
+
+1. **Read AGENTS.md** — your operating manual.
+2. **Read _shared/AGENT_BASELINE.md** — baseline behavior rules.
+3. **Read _shared/CLINE_TOOLS.md** — exact tool schemas.
+4. **Run `make session-start`** — record session ID.
+5. **Read PROGRESS.md** — state from the last session.
+6. **Read feature_list.json** — pick the next `not_started` feature.
+7. **Work on ONE feature only** — WIP=1.
+8. **Run verification:** `make check && make test && make e2e`.
+9. **Update PROGRESS.md + feature_list.json** — record evidence.
+10. **Score against `templates/evaluator-rubric.md`** — every dim B+.
+11. **Run `make session-end`** — close the session.
+12. **Commit only when safe to resume** (Hermod does this).
+
+If you find yourself doing steps 7-9 on more than one feature, stop.
+
+## Definitions of Done (L08, L09)
+
+A feature is `passing` only when ALL THREE LAYERS verify:
+
+- **L1 typecheck:** `make check` exits 0.
+- **L2 unit tests:** `make test` passes for the touched module.
+- **L3 E2E:** `make e2e` exercises real plugin load + tools.
+
+Do NOT proceed to L(n+1) if L(n) fails. Confidence ≠ correctness.
+
+## Scope discipline (L07)
+
+- WIP=1. Only one feature `active` in `feature_list.json`.
+- No silent scope creep. If a fix requires touching unrelated code,
+  STOP and report — do not improvise.
+- No half-finishing three things. No rewriting the feature list to
+  hide unfinished work.
+
+## State persistence (L05)
+
+- Progress belongs in PROGRESS.md + feature_list.json + git log.
+- The repo is the single source of truth. If the agent can't see it,
+  it doesn't exist.
+- Handoff note: every session must leave a clean restart path.
+
+## Loop engineering (L13)
+
+When you find yourself repeating the same manual orchestration, build a
+loop. Three primitives:
+
+1. **Goal loop** — `while !done; run-one-step; done`
+2. **Timer loop** — `every N minutes: run-the-job`
+3. **Maker-checker loop** — `make.sh` produces, `check.sh` rejects
+
+Bizar ships three:
+- `scripts/run-loop.sh` — generic loop driver (see below)
+- `make test` — verification (checker)
+- `scripts/clean-state-check.sh` — final pass/fail gate
+
+## Context engineering (Anthropic)
+
+Treat the context window as a working memory budget, not a dump site:
+
+- Progressive disclosure: load skills on demand, not all at once.
+- KV-cache locality: keep system prompts stable; append, don't rewrite.
+- Drop noisy tool output before passing to the next model call.
+
+## Observability (L11, OTel)
+
+If you can't see what the agent did, you can't fix what it broke. Bizar
+records every session to `.harness/traces/sessions.jsonl` (gitignored).
+For OpenTelemetry-compatible exporters, see `plugins/bizar/src/observability.ts`.
+
+## Sandbox (CubeSandbox — v6.3.0)
+
+For dangerous-pattern decisions and risky operations, Bizar routes the
+execution through `bizar_sandbox_run` (CubeSandbox) instead of running
+directly in the host shell. See the `cubesandbox` skill.
+
+## Quick checklist before each commit
+
+- [ ] feature_list.json updated (state machine moved)
+- [ ] PROGRESS.md updated (current state, in progress, next steps)
+- [ ] `make check` exits 0
+- [ ] `make test` exits 0
+- [ ] `make e2e` exits 0
+- [ ] `make clean-check` 5/5 dimensions pass
+- [ ] Every dim of `templates/evaluator-rubric.md` is B+
+- [ ] Commit message is WHY-focused, not WHAT-focused
+
+## Further reading
+
+The skill `find-skills` can install the full walkinglabs course. The
+local copy lives at `bizar-learn-harness` (auto-bundled by
+`scripts/install-learn-course.sh`). To rebuild locally:
+
+```bash
+git clone https://github.com/walkinglabs/learn-harness-engineering /tmp/lhe
+```