kobold

kobold is a CLI-first Planner -> Executor -> Evaluator runtime with structured observability.

Current iteration adds OpenBet-specific Jira planning with approval gating and AssertFlip-style fail-to-pass verification metadata.

Why this exists

This project follows a soft-routing approach:

• Planner decides actions dynamically.
• Executors stay deterministic and capability-scoped.
• Evaluator catches bad executions and controls retry/stop behavior.

The implementation is TypeScript/Node and uses provider-style planner adapters (including an OpenCode scaffold) while keeping loop control inside Kobold.

Quickstart

cd /space/repo/kobold
npm install
cp .env.example .env
npm run dev -- run --prompt "hello from kobold"
npm run dev -- run --prompt "read README.md" --feature "bootstrap"

CLI

kobold run --prompt "<request>" [--feature "<feature-name>"]
kobold plan --jira "<JIRA-KEY>" [--max-repos 5] [--assertflip-authoring auto|human_assisted|hybrid] [--assertflip-max-gen 3] [--assertflip-max-validate 3] [--assertflip-timeout-ms 30000]
kobold approve --plan-id "<plan-id>" --by "<name>" [--notes "<text>"]
kobold execute --plan-id "<plan-id>" [--assertflip-dry-run]

Commands:

• run --prompt "<text>": runs one loop and writes a trace file.
• plan --jira "<key>": builds OpenBet context + dynamic AssertFlip plan and writes markdown/json artifacts under runs/plans/.
• approve --plan-id "<id>" --by "<name>": creates approval artifact required for execution.
• execute --plan-id "<id>": enforces approval gate, runs preflight, then executes through planner/executor/evaluator loop.
  • writes a resolution bundle under runs/resolution/<planId>.json.
  • fails if repro/fix AssertFlip gates do not complete.
• --feature "<name>" (optional on run): appends a context-anchoring session hint entry to context/features/<name>.md.

Loop behavior (V1)

1. Planner returns either:
   • tool action (toolName, args, reason)
   • final action (answer, reason)
2. Executor runs deterministic tools from a registry.
3. Evaluator applies lightweight rules:
   • required arg checks
   • success/error checks
   • empty payload checks
   • retry budget checks
4. Runtime decides continue, retry, or stop.

Observability

• JSON log events are emitted to stdout.
• Trace files are written to runs/<timestamp>-<runId>.json.
• Every event includes correlation metadata:
  • runId
  • stepId (for step-level events)

Captured trace events:

• run_started
• planner_decision
• tool_executed
• evaluator_decision
• run_completed

Included deterministic tools

• echo_context: returns sanitized prompt context.
• read_local_file: reads UTF-8 files under KOBOLD_FILE_ALLOWLIST_ROOT.
• search_local_wiki: searches local Confluence snapshot (/space/obsidian-all/lq-confluence) first.
• query_jira: queries Jira via query-agents CLI.
• query_wiki: queries Confluence via query-agents CLI.
• query_bitbucket: queries Bitbucket via query-agents CLI.

Environment

See .env.example:

• KOBOLD_PROVIDER
• KOBOLD_MODEL
• KOBOLD_PLANNER_MODEL
• KOBOLD_EVALUATOR_MODE
• KOBOLD_EVALUATOR_MODEL
• KOBOLD_EVALUATOR_ESCALATION_MODEL
• KOBOLD_EVALUATOR_LOW_CONFIDENCE_THRESHOLD
• KOBOLD_OPENCODE_BIN
• KOBOLD_OPENCODE_TIMEOUT_MS
• KOBOLD_MAX_ITERATIONS
• KOBOLD_MAX_RETRIES_PER_STEP
• KOBOLD_FILE_ALLOWLIST_ROOT

Planner provider

• KOBOLD_PROVIDER=mock uses the deterministic local planner.
• KOBOLD_PROVIDER=opencode uses the OpenCode planner adapter scaffold and falls back safely if unavailable.
• KOBOLD_MODEL is the general default model (use github-copilot/gpt-5-mini for most tasks).
• KOBOLD_PLANNER_MODEL overrides planner-only model selection (for example github-copilot/gpt-5.3-codex for higher-quality planning).
• KOBOLD_EVALUATOR_MODE=rules keeps deterministic evaluation only (default).
• KOBOLD_EVALUATOR_MODE=hybrid enables LLM fallback for ambiguous evaluator outcomes; default evaluator model should stay github-copilot/gpt-5-mini and can escalate to KOBOLD_EVALUATOR_ESCALATION_MODEL for low-confidence checks.

Context Anchoring

Kobold supports feature-level external memory:

• Template: context/features/_template.md
• Guide: docs/context-anchoring.md

Use --feature during runs to append session-level anchoring hints and trace references.

OpenBet Ticket Planning

kobold plan --jira <KEY> builds a decision artifact with:

• Jira issue context and VM metadata.
• Multi-repo candidates discovered from local /space/repo.
• Local-first wiki evidence (/space/obsidian-all/lq-confluence) with remote fallback.
• AssertFlip section:
  • candidate WDIO/Karate tests,
  • dynamically generated passing/inverted tests in run workspaces,
  • generation + validation loop budgets (--assertflip-max-gen, --assertflip-max-validate, --assertflip-timeout-ms),
  • repro/fix acceptance criteria,
  • optional human-assist prompts (--assertflip-authoring human_assisted|hybrid).

Execution requires explicit approval via kobold approve. Use kobold execute --plan-id <id> --assertflip-dry-run to verify planning/execution flow without strict gate enforcement.

Docs

• docs/usage.md: setup, commands, planner provider modes, and troubleshooting
• docs/architecture.md: loop architecture and data flow
• docs/context-anchoring.md: feature-level external memory workflow
• docs/adr/README.md: architecture decision records (ADRs) index and authoring guide

Tests

npm test

Coverage includes planner schema validation, evaluator rule behavior, and runtime success/failure paths with trace validation.

Next iteration

• Auto-materialize AssertFlip draft tests directly into target repos after approval.
• Stronger repo candidate scoring from Jira development links and Bitbucket metadata.
• Trace replay command (kobold replay <run_id>).