harness-hacker

Self-modify the bot framework — fork, improve, test, and PR changes to any Hanzo component including your own source code, skills, extensions, and tools. Use when self-improvement maintenance proposes changes or when you detect friction you can fix.

Harness Hacker — Self-Modification Protocol

You have the ability to modify your own source code, create new tools, improve existing skills, and contribute changes back to any Hanzo repository. This is your most powerful capability.

When to Use

  1. After a maintenance pass proposes an approved change
  2. During a Build It Now cycle (Loop 1) when friction is detected
  3. When the user explicitly asks you to improve yourself
  4. When you identify a pattern that a specific tool would solve better than bash

Safety Rules

  1. NEVER modify files in the live bot directory while the gateway is running — use a worktree
  2. ALWAYS test changes before committing — run pnpm test or the relevant test suite
  3. ALWAYS create a new branch — never commit directly to main
  4. ALWAYS explain what you're changing and why before doing it
  5. Keep changes small and focused — one logical change per commit
  6. Generated tools go in extensions/self-improvement/tools/generated/ — they have a 7-day TTL

Creating a New Extension

Extensions are the primary way to add capabilities. Follow this exact pattern:

# 1. Create directory
mkdir -p ~/botd/extensions/my-extension

# 2. Create package.json
cat > ~/botd/extensions/my-extension/package.json << 'EOF'
{
  "name": "@hanzo/bot-my-extension",
  "version": "2026.2.26",
  "private": true,
  "description": "What this extension does",
  "type": "module",
  "devDependencies": { "@hanzo/bot": "workspace:*" },
  "peerDependencies": { "@hanzo/bot": ">=2026.1.26" },
  "bot": { "extensions": ["./index.ts"] }
}
EOF

# 3. Create index.ts
cat > ~/botd/extensions/my-extension/index.ts << 'EOTS'
import type { AnyAgentTool, BotPluginApi } from "bot/plugin-sdk";
import { emptyPluginConfigSchema } from "bot/plugin-sdk";

const plugin = {
  id: "my-extension",
  name: "My Extension",
  description: "What it does",
  configSchema: emptyPluginConfigSchema(),
  register(api: BotPluginApi) {
    api.registerTool({
      name: "my_tool",
      description: "What the tool does",
      parameters: {
        type: "object",
        properties: {
          input: { type: "string", description: "Input parameter" }
        },
        required: ["input"]
      },
      async execute(params) {
        // Implementation here
        return { content: [{ type: "text", text: "Result" }] };
      }
    } as AnyAgentTool);
  }
};

export default plugin;
EOTS

Creating a New Skill

Skills are documentation files that teach you patterns. They're simpler than extensions.

# 1. Create directory
mkdir -p ~/botd/skills/my-skill

# 2. Create SKILL.md
cat > ~/botd/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: What this skill teaches
metadata:
  { "bot": { "emoji": "📚" } }
---

# Skill Name

## When to Use
Describe the trigger conditions.

## Pattern
Show the exact steps or commands.

## Rules
1. Rule one
2. Rule two
EOF

Modifying Existing Extensions

Use git worktrees for safety:

# 1. Create worktree from the bot repo
cd ~/botd
git worktree add /tmp/bot-hack-$(date +%s) -b hack/my-improvement

# 2. Make changes in the worktree
cd /tmp/bot-hack-*
# Edit files...

# 3. Test
pnpm test

# 4. Commit
git add -A
git commit -m "feat(self-improvement): description of change"

# 5. Push and PR (if user approves)
git push -u origin hack/my-improvement
gh pr create --title "..." --body "..."

# 6. Cleanup
cd ~/botd
git worktree remove /tmp/bot-hack-*

Hacking Other Hanzo Components

You can improve ANY Hanzo repo, not just the bot. Common targets:

| Component | Path | What to Improve | | --------------- | ------------------------ | ----------------------------------------------- | | MCP | ~/work/hanzo/mcp | Add new tools, improve search | | Agent SDK | ~/work/hanzo/agent | Network patterns, memory | | LLM Gateway | ~/work/hanzo/llm | Provider support, routing | | Operative | ~/work/hanzo/operative | Computer use tools | | Universe | ~/work/hanzo/universe | K8s manifests, infra | | Zoo Gym | ~/work/zoo/gym | GRPO pipeline, SemanticExtractor, BitDelta, DSO | | Zoo Node | ~/work/zoo/node | Rust BitDelta/GRPO (hanzo-libs/hanzo-llm) | | Zen Models | ~/work/hanzo/zen | Model serving, quantization configs |

Pattern for external repos:

# 1. Fork/branch
cd ~/work/hanzo/mcp
git checkout -b hack/add-tool-xyz

# 2. Make changes
# 3. Test: pnpm test (or uv run pytest, cargo test, etc.)
# 4. Commit and push
# 5. Create PR

Runtime Tool Creation (Build It Now — Loop 1)

When you detect friction during a session, you have 5 minutes to build a fix:

# 1. Identify the pattern (from telemetry)
#    e.g., "bash fails 3x trying to parse JSON from package.json"

# 2. Create a generated tool (these have a 7-day TTL)
mkdir -p ~/botd/extensions/self-improvement/tools/generated

cat > ~/botd/extensions/self-improvement/tools/generated/read-package-field.ts << 'EOTS'
// Generated tool: read_package_field
// Created: $(date -Iseconds)
// Trigger: bash failed 3x parsing JSON from package.json
// TTL: 7 days (auto-pruned if unused)

import { readFileSync, existsSync } from "node:fs";
import { join } from "node:path";

export const tool = {
  name: "read_package_field",
  description: "Read a specific field from package.json. Safer than bash + jq for JSON extraction.",
  parameters: {
    type: "object",
    properties: {
      path: { type: "string", description: "Directory containing package.json" },
      field: { type: "string", description: "JSON field path (e.g., 'version', 'scripts.build')" }
    },
    required: ["field"]
  },
  async execute(params: any) {
    const dir = params.path || process.cwd();
    const pkgPath = join(dir, "package.json");
    if (!existsSync(pkgPath)) {
      return { content: [{ type: "text", text: `No package.json found at ${dir}` }] };
    }
    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
    const parts = (params.field as string).split(".");
    let value: any = pkg;
    for (const part of parts) {
      value = value?.[part];
    }
    return {
      content: [{ type: "text", text: value !== undefined ? JSON.stringify(value) : "Field not found" }]
    };
  }
};
EOTS

# 3. Hot-reload (the self-improvement extension watches this directory)

Continuous Improvement Workflow

Friction detected (Loop 1)
    → Build specific tool (5 min time-box)
    → Test against failure cases
    → Hot-reload into session

Session ends (Loop 3)
    → 3-question reflection
    → Structured telemetry summary

Every 5 sessions (Loop 4)
    → Aggregate telemetry
    → Generate proposals
    → Human approves/rejects
    → YOU implement approved changes using THIS skill

Telemetry-Driven Decisions

Always check telemetry before building:

# View recent session telemetry
ls -la ~/.hanzo/bot/telemetry/

# View last reflection
cat ~/.hanzo/bot/self-improvement/reflections/$(ls -t ~/.hanzo/bot/self-improvement/reflections/ | head -1)

# View maintenance proposals
cat ~/.hanzo/bot/self-improvement/proposals/$(ls -t ~/.hanzo/bot/self-improvement/proposals/ | head -1)

# View learned facts
cat ~/.hanzo/bot/self-improvement/learned-facts.json

Remember