oc-arkive

OpenCode workflow plugin for plan-first development: feature plans, approval gates, isolated git worktrees, durable .hive/ state, and optional review commands.

Requires OpenCode >= 1.14.48. Open your project and ask Hive to work.

Human onboarding starts in the root README. This README is the detailed npm and operator reference.

Install

For a brand-new config, add the plugin to opencode.json or opencode.jsonc. OpenCode resolves the npm package; you do not need a separate npm install for normal use.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["oc-arkive@latest"]
}

Restart OpenCode after changing plugins.

Existing OpenCode configurations

If you already have an OpenCode config, append oc-arkive@latest to its existing plugin array. Keep your surrounding settings and existing plugin entries, and preserve unrelated settings in the source file. The plugin still intentionally mutates the OpenCode fields listed below. This section is the full compatibility reference; the root README points here instead of repeating these mutations.

The config hook intentionally mutates these OpenCode fields:

• default_agent: selects hive-master in unified mode or architect-planner in dedicated mode.
• agent: Known reserved legacy/current agent IDs are removed and replaced; unrelated agent IDs remain.
• command: Shipped command keys replace same-key user command definitions; unrelated command keys remain.
• subagent_depth: sets the OpenCode value to 2.
• skills.paths: when Hive skills are materialized, registers the generated Hive skill path first, followed by resolved user-configured paths.
• experimental.primary_tools: removes task and existing question entries, then ensures one question entry while preserving other string entries.
• mcp: Enabled built-in MCP IDs replace same-ID definitions; unrelated IDs remain. disableMcps prevents a selected built-in from being registered, so an existing same-name MCP definition can remain.

Built-in research MCPs

The plugin supplies built-in research MCP definitions at startup. You do not need to copy .opencode/mcp-servers.json; see Available MCPs for the inventory and disable controls.

Default mode is dedicated (architect-planner + swarm-orchestrator). Set "agentMode": "unified" for a single hybrid hive-master seat; see Agent mode. Runtime config is global only: ~/.config/opencode/agent_hive.json.

The Workflow

1. Create feature - planning flow or hive_feature_create
2. Write plan - hive_plan_write / hive_plan_patch
3. Human review - comments and chat
4. Approve + sync - hive_plan_approve, then hive_tasks_sync
5. Execute - hive_worktree_start launches workers in isolated worktrees
6. Commit task branch - hive_worktree_commit (does not merge)
7. Merge - hive_merge integrates completed task branches
8. Complete feature - hive_feature_complete when done

Use the feature flow when work needs plan review, a task DAG, and a durable audit trail. Use ad-hoc orchestration for bounded non-feature work that should not create feature or task records. Ad-hoc work uses hive_adhoc_*; hive-master can coordinate it in unified mode, while dedicated mode uses hive-builder. architect-planner is planning-only and does not route ad-hoc work. Operator-facing seats, when to pick each workflow, and the human loops are in the Operator Guide.

Operator Commands

oc-arkive registers these slash commands as operator entry prompts. They prepare the active agent with workflow-specific instructions; they do not replace Hive tools or make unavailable tools available to the current agent. /dash-review and /vuln-review are exceptions: their generated OpenCode commands bind to separate private review primaries.

| Command | Purpose | |---------|---------| | /interview | Clarify an idea toward a reliable implementation-brief handoff. | | /grill <context> | Reach explicit alignment on any context through material questions and researched facts. | | /implementation-brief | Produce a copy-paste-ready brief for a later Hive plan. | | /hive-plan | Create or update the Hive feature plan from a spec or brief. | | /approve-sync-plan | Approve the active plan and sync executable tasks. | | /start-execution | Start execution for an approved and synced plan. | | /council-directive | Turn rough input into a reusable directive for a council run. | | /council | Run a read-only council and synthesize a recommendation. | | /dash-review [intent] [--artifact <file>] | Review one Git, inline process/concept, or local-artifact evidence bundle without changing source. | | /vuln-review [intent] [flags] | Resolve a conversational scope, then run a findings-first static vulnerability review over one frozen disposable workspace. | | /compact-summary | Produce a compact recovery summary for the current session. |

/hive has been removed. Feature creation now belongs to the planning flow and the Hive tools, usually hive_feature_create followed by hive_plan_write, review, approval, task sync, execution, and merge.

/council accepts /council --group <group> <directive>. If --group is omitted, Hive uses council.defaultGroup. Free-text tokens are directive text, not implicit group selectors.

Routing depends on agentMode:

| Command set | Unified mode | Dedicated mode | |-------------|--------------|----------------| | /interview, /grill, /implementation-brief, /hive-plan, /council-directive, /council | Use hive-master. | Route or delegate to architect-planner. | | /approve-sync-plan, /start-execution | Use hive-master. | Route or delegate to swarm-orchestrator. | | /dash-review | Bound by config.command to a private review primary. | Bound by config.command to a private review primary. | | /vuln-review | Bound by config.command to a private vulnerability-review primary. | Bound by config.command to a private vulnerability-review primary. | | /compact-summary | Use hive-master. | Route or delegate to scout-researcher. |

Except for /dash-review and /vuln-review, dedicated-mode slash commands do not switch agents by themselves. If the active agent is not the route target, delegate or reroute to the target agent and stop if that is not possible.

Use /interview <idea> to clarify an idea toward a reliable implementation-brief handoff. It keeps questions implementation-oriented and prepares context for the separate /implementation-brief command rather than producing that full brief. Use /grill <context> when the endpoint is explicit shared understanding of any topic. Both ask one material question per turn and do not automatically create a plan, implement, or start follow-on work; confirmed alignment ends the interaction, and later action requires a separate operator request. A named destination authorizes writing only the confirmed alignment brief there. Discoverable facts are researched without forced fan-out. Unavailable or failed research is disclosed as unresolved or an explicit assumption; it is never guessed.

Use /dash-review for one read-only Git, process/concept, or local-artifact review. It does not edit source, create Hive tasks, or start a fix. The operator loop is in the Operator Guide.

The command.execute.before hook stores an immutable hive-dash-review-command/v3 packet containing exact raw and normalized intent, one validated GitHub PR descriptor or null, descriptor source, and packet-fixed artifact paths. Shell/control syntax is rejected. A PR fixes Git evidence. Repeated --artifact <project-relative-file> flags fix local-artifact evidence. Empty arguments can resolve only Git evidence. Other nonempty natural-language intent can resolve Git or inline process|concept|general evidence. One invocation cannot mix kinds, and arbitrary URLs are not evidence inputs.

The generated Stage A child calls hive_review_evidence_resolve once. Review roles cannot call hive_git_snapshot directly. Git resolution internally preserves exact provider OIDs, multi-repository topology, dirty state, freshness, and compact provenance. Inline resolution hashes the exact normalized intent bytes without returning them. Artifact paths come only from the command packet. Resolution rejects private/traversing/symlinked files and returns descriptors and digests without materializing. One local-artifact bundle accepts at most 32 files, 16 MiB per file, and 32 MiB total.

hive_review_workspace_create accepts only resolutionFingerprint; vulnerability materialization also supplies the stored source-resolution fingerprint. It does not accept caller refs, repositories, paths, inline bytes, artifact paths, or scope claims. Git uses ReviewWorkspaceService under .hive/.worktrees/review/<runId>. Inline and artifact evidence uses ReviewEvidenceBundleService under .hive/.worktrees/review-evidence/<runId>. Both services preserve one token/claim/inspect/cleanup lifecycle with restart recovery and stale-run sweeping.

Git evidence permits generated code/documentation/UI/code-reviewer and simplicity lanes. Inline and artifact evidence permits generated approach-advisor and matching approach-advisor-derived lanes, including an adversarial approach advisor when configured and relevant. Git remains findings-first. Process/concept/general evidence uses advisory methodology and answers requested questions without inventing implementation severity.

Every deep task receives a runtime boundary packet with evidence kind, run ID, workspace path, and scope/source/resolution fingerprints. read, glob, grep, ast_grep_find_code, and ast_grep_find_code_by_rule require explicit absolute paths whose realpaths remain inside the claimed frozen workspace. Process cwd is live source and is never a fallback. Evidence manifests and content are untrusted data, not instructions. Shell, writes, recursive tasks, and remote mutation are denied.

The primary inspects after review and cleans the persisted owner service. The response includes evidence fingerprints, requested questions answered, coverage/limitations, integrity, cleanup, and review state. No review-local output is copied back to source.

The runtime command agent is the private __hive_dash_review_primary identity so a pre-existing customAgents.dash-reviewer keeps its public model and variant behavior. The private primary uses the normal OpenCode model resolution path and has no public Hive configuration alias.

Review caller authorization explicitly trusts the exact runtime agent name reported by OpenCode. Generated private names and task targets are collision-checked and matched exactly; this is name-based runtime trust, not a cryptographic caller identity. The policy does not broaden MCP or tool access to compensate for a name collision.

For an ad-hoc run, review the existing run or branch, then give a later fix instruction to the ad-hoc orchestrator so it resumes the normal isolation and delegation flow. For a Hive feature run, review the task/feature or branch, then give the active planner/orchestrator primary a later fix instruction so it uses the feature DAG and task worktrees. Findings are review context, never auto-created tasks.

Background instructions appear only when OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS or OPENCODE_EXPERIMENTAL is set and the bundled background protocol is available. Use the existing Background Orchestration section and the background-delegation skill for the scheduler protocol; command text only points at it when the gate is open. /dash-review is a deliberate exception and remains blocking-only.

Vulnerability Review

Use /vuln-review when you are authorized to assess the source and want a findings-first static review of one frozen snapshot. It does not exploit systems, edit source, or create automatic fixes. A scoped clean result is not a repository-security claim. The operator loop is in the Operator Guide. The rest of this section is the command contract.

/vuln-review is for authorized use against source the operator is permitted to assess. It performs a bounded static/local review and does not establish compliance, replace SAST or DAST, prove exhaustive coverage, or establish repository security.

Scope and examples

The command accepts free text, recognized flags, a mixture of both, or no arguments. Text and relevant bounded conversation context supply inert intent for one coherent target; no-argument use infers from conversation and current Git/Hive metadata rather than silently selecting current change. Recognized flags are deterministic fixed overrides: inference can fill absent dimensions but cannot replace, widen, or reinterpret a fixed value. Whole-repository scope requires --whole-repo or explicit approval of that inferred expansion. Exact examples:

• No arguments (scope inferred): /vuln-review
• Current change narrowed by repository and path: /vuln-review --repo api --path src/auth
• Git range: /vuln-review --range main...HEAD
• Git refs: /vuln-review --base main --target HEAD
• Hive task: /vuln-review --task 03-implement-auth
• Hive feature: /vuln-review --feature authentication
• Whole repository: /vuln-review --whole-repo
• Current change compared with a prior report: /vuln-review --compare approved/prior-review.md
• Free-text intent: /vuln-review review the authentication boundary changed in this branch
• Free text with fixed boundaries: /vuln-review review authentication --repo api --path src/auth

Legal combinations:

| Mode | Required mode flag | Other allowed flags | |------|--------------------|---------------------| | Current change | No dedicated mode flag; available only when inferred and accepted | Repeatable --repo <id>, repeatable --path <relative-path>, one --compare <local-prior-report.md> | | Git range | One --range <base>...<target> | Repeatable --repo, repeatable --path, one --compare | | Git refs | One --base <ref> | Optional --target <ref>, repeatable --repo, repeatable --path, one --compare | | Hive task | One --task <task-folder> | Repeatable --repo, repeatable --path, one --compare | | Hive feature | One --feature <feature-name> | Repeatable --repo, repeatable --path, one --compare | | Whole repository | --whole-repo | Repeatable --repo, one --compare; --path is not allowed |

--range cannot be combined with --base or --target; --target requires --base. Git mode, task mode, feature mode, and whole-repository mode are mutually exclusive. Singleton flags cannot be repeated. Ordinary positional text and PR numbers remain inert intent; --pr is unsupported. An exact safe GitHub PR URL may authorize one runtime-owned metadata lookup only when no fixed selector conflicts and the raw command contains no CR, LF, NEL, LS, or PS separator. Fixed --repo and --path boundaries survive without normalizing newline eligibility. Explicit local selectors remain strict and never fall back.

Current change is one possible canonical mode after inference and acceptance, not a parser default selected by omitting flags.

Stage 1 uses the hard-cut hive-vuln-review-stage1/v3 schema and returns exactly BOUNDED, NEEDS_CLARIFICATION, or STOP. The command hook emits the shared ReviewIntentPacket, but vulnerability review accepts Git evidence only and rejects inline/artifact kinds before BOUNDED. The scope lane calls hive_review_evidence_resolve({ kind: 'git', ... }) once and copies its nested sourceResolution and resolutionFingerprint unchanged. Every proposal, accepted candidate, attempt-2 equality check, and materialize packet includes that evidence fingerprint. Attempt 2 reuses the stored resolution and cannot resolve again. The existing one-question clarification, exact candidate equality, comparison authority, threat/lens, and two-stage fail-closed rules remain unchanged.

--compare is a parser-normalized project-relative regular file bound to the current invocation. The private scope lane never receives its path as tool input: hive_vulnerability_compare_report_read accepts no arguments, path, or token. The runtime binds the scope-lane agent from child chat metadata, rechecks the same identity and child lineage at tool context, and permits one read. Replacement, any later task call, error, idle status, session deletion, read failure, or process restart revokes the ephemeral authority.

Authorized-use and safety boundary

The workflow performs source review only: no active exploitation, no network scanning or probing, no credential use, no package installation, no shell commands, no scanner execution, no source edits, no external-state mutation, no recursive delegation, and no Hive lifecycle mutation. No product-source, report, SARIF, remediation, or Hive feature/task files are created. Frame does create a disposable frozen workspace and persisted lease metadata for lifecycle safety; cleanup removes the workspace and releases the persisted run state. The workflow produces no automatic fix, remediation, plan, task, worktree outside that disposable review workspace, commit, merge, or patch. Remediation requires separate operator authorization after the review.

The private roles use an exact allowlist:

• The primary can call only task, question, hive_review_workspace_claim, hive_review_workspace_inspect, and hive_review_workspace_cleanup. Task targets are restricted to the generated private lanes.
• The scope researcher can call only hive_repositories_status, hive_plan_read, hive_status, hive_review_evidence_resolve, hive_vulnerability_compare_report_read, hive_review_workspace_create, hive_review_workspace_cleanup, and the approved MCP tools listed below. It cannot call hive_git_snapshot, read, glob, grep, shell, or another local acquisition path before freeze.
• Baseline, specialist, and falsifier lanes can call only read, glob, grep, and the approved MCP tools. Every local operation must use a supplied frozen absolute workspace path, never the live source or process cwd.
• Approved MCP calls are ast_grep_dump_syntax_tree, ast_grep_find_code, ast_grep_find_code_by_rule, ast_grep_test_match_code_rule, context7_resolve-library-id, context7_query-docs, grep_app_searchGitHub, and websearch_web_search_exa.

External queries may contain only public dependency names and versions or public advisory identifiers such as CVE or GHSA IDs. They must not contain proprietary source, symbols, paths, configuration, logs, or stack traces. Optional MCP unavailability is a coverage gap, not permission to add another tool. The workflow adds zero new scanner dependencies and requires no scanner setup.

Sensitive findings remain in OpenCode session history. No report file or SARIF is written. Operators must apply appropriate session retention and access controls, or manually export the report to an approved location under their own data-handling policy.

Stages and evidence

The stages run in this order:

1. Resolve combines intent, conversation, and Git/Hive metadata with fixed overrides. It reads an optional comparison report, previews the source, builds threat context, selects zero to two specialist lenses, and returns a bounded candidate, one clarification, or stop. Resolve cannot create a workspace.
2. Materialize receives only the stored accepted candidate. It passes only resolutionFingerprint and sourceResolutionFingerprint to create; repository IDs, refs, paths, and Hive scope come from runtime state. It then requires strict descriptor and fingerprint equality before returning READY.
3. Claim binds the READY workspace to the private primary session before deep review starts.
4. Investigate runs the mandatory cross-cutting baseline and zero to two selected specialists as fresh blocking lanes. Specialists supplement the baseline and are selected from the observed attack surface, not model prestige.
5. Challenge gives every normalized candidate to the fixed falsifier. With no candidates, it tests the bounded hypothesis that no actionable vulnerability exists in the reviewed scope. A falsifier-originated suspicion remains unresolved and cannot become a confirmed finding in that run.
6. Inspect and cleanup checks the materialized baseline, new-untracked state, and live-source stability, then attempts cleanup unconditionally. Drift, unavailable integrity evidence, policy violations, omitted scope, truncation, or cleanup uncertainty makes the run INCOMPLETE without discarding already confirmed evidence.
7. Synthesize and report groups confirmed findings by root cause, orders them by severity, records coverage and integrity limits, and returns the report in the session only.

The shared Git resolver excludes internal Hive review state from live untracked capture so review bookkeeping does not alter the accepted fingerprint. Materialization requires exact evidence-resolution, source-resolution, descriptor, source, and ordered repository fingerprint equality for single and composite workspaces.

A failed mandatory baseline or falsifier gets one fresh retry. A repeated mandatory failure, any selected specialist failure, declined required expansion, integrity failure, or cleanup uncertainty produces INCOMPLETE.

Report contract

The report starts with these case-sensitive metadata lines:

Schema: hive-vuln-review/v1
Scope mode: <current-change|git-comparison|hive-task|hive-feature|whole-repository>
Scope fingerprint: sha256:<64 lowercase hex>
Source fingerprint: sha256:<64 lowercase hex>
Repositories: <sorted comma-separated IDs>
Paths: <canonical JSON string array>
Comparison base: <selector-or-none>
Hive scope: <task:name|feature:name|none>
Selected lenses: <canonical JSON string array>
Prior comparison: <not-requested|skipped:reason|comparable>

Canonical arrays are JSON-escaped, code-point sorted, deduplicated, and contain no extra whitespace. The scope fingerprint hashes canonical scope identity in this key order: schema, mode, repositories, paths, comparison base, and Hive scope. The source fingerprint separately covers resolved commits and captured dirty content. The report then contains Scope, Threat Context, Findings, Coverage Gaps, Rejected Leads, Unresolved Leads, Re-review Classification, Review Lanes, Integrity, and State, in that order. Scope metadata records normalized selectors, repositories, refs, paths, fingerprints, Hive identity, and prior-report status. Review-lane metadata lists only agents, models, variants, and lenses that actually ran.

Every confirmed finding includes a display ID, Root-cause key, severity, locations, evidence, attacker-to-impact path, impact, exploitability stance, confidence, fix direction without a patch, variants, producing lens, and falsifier disposition. The Root-cause key has four ::-separated, encodeURIComponent-encoded segments: manifest repository ID; POSIX-normalized repository-relative primary path; trimmed case-preserving symbol or boundary; and lowercase ASCII missing-control slug. To build the slug, each non-[a-z0-9] run becomes one hyphen and edge hyphens are removed. The key excludes line numbers and run-local display IDs.

Prior comparison runs only for a supported hive-vuln-review/v1 report with complete scope/source/lens metadata and Root-cause keys. Scope mode, repositories, paths, comparison base, and task/feature identity must match exactly. Otherwise the report says comparison skipped with a reason and assigns no per-finding classification. For comparable reports, new is a current key not present before and unchanged is a key still confirmed. resolved requires changed source plus explicit re-examination of the prior location, exploit preconditions, and prior or equivalent coverage. An absent prior key is stale when any resolution precondition is missing; same-source or nondeterministic absence never proves resolution.

The report ends with exactly one state: CONFIRMED_FINDINGS, NO_CONFIRMED_FINDINGS_IN_REVIEWED_SCOPE, or INCOMPLETE. INCOMPLETE takes precedence over a clean state, but confirmed findings remain visible when attribution or cleanup later fails.

Models and specialists

The four built-in specialist lenses are:

• trust-and-identity: authentication, authorization, tenant/object isolation, session, and privilege boundaries.
• untrusted-data: parsing, injection, deserialization, path, process, template, and database boundaries.
• secrets-and-platform: cryptography, secrets/configuration, dependencies, CI/IaC, cloud, and container exposure.
• stateful-abuse: replay, races/TOCTOU, workflow bypass, business logic, and state-transition invariants.

The workflow uses OpenCode's normal provider/model resolution. It adds no model-provider SDK, credential setup, or provider-specific CLI dependency beyond the operator's existing OpenCode configuration. A different configured model or variant is allowed, but the report says multi-model only when different model identities actually ran.

Custom agents with baseAgent: "vulnerability-reviewer" become selectable private specialists when their descriptions match the observed risk. They inherit the configured base model, variant, and temperature unless overridden. They cannot replace the mandatory baseline or the fixed falsifier, change the tool allowlist, or bypass workspace and report gates.

Planning-mode delegation

During planning, "don't execute" means "don't implement" (no code edits, no worktrees). Read-only exploration is explicitly allowed and encouraged, both via local tools and by delegating to a researcher.

When delegation is warranted, synthesize the task before handing it off: name the file paths or search target, state the expected result, and say what done looks like. Workers do not inherit planner context.

Each native task() launch has one primary goal, starts one fresh subagent session, and ends with one terminal handoff. A primary goal may include tightly coupled code, tests, docs, and multiple files; do not split it by file or step. Give complete constraints and acceptance criteria only for that goal, then split independently verifiable outcomes into fresh launches. Never pass task_id to task(): returned IDs are observe-only handles for status, reconciliation, cancellation, and direct-child trace inspection. Recovery context from hive_task_trace belongs in a NEW task without task_id. Do not send a follow-up prompt to a completed, failed, or blocked session. Compaction may re-anchor a currently running worker; it is not re-delegation.

One implementation assignment normally maps to one numbered task. Amend the DAG or create an append-only manual task for a new independent deliverable. A blocked feature continuation starts a new worker session in the same worktree with the operator decision. Failed or retry work starts a new worker with a concise self-contained handoff. For ad-hoc work, use multiple fresh one-goal launches with disjoint path ownership or sequence overlapping writers. Subagents are terminal and cannot recurse, except a delegated architect-planner may launch one level of read-only research, plan-reviewer, and approach-advisor helpers; those children cannot delegate. The question tool is reserved for primary sessions. Any subagent that needs operator clarification returns the exact question in its terminal response for the parent orchestrator to ask.

For execution work, treat worker output as evidence to inspect, not proof to trust blindly. OpenCode is the supported execution runtime; if you use vscode-arkive, treat it as a review/sidebar companion. Read changed files yourself and run the shared verification commands on the main branch before claiming the batch is complete.

Local skill and model use cases

• Local skill experiments: keep a skill in <project>/.opencode/skills/<id>/SKILL.md or <project>/.claude/skills/<id>/SKILL.md, then load it with OpenCode's native skill tool, reference it in agent instructions, or list its frontmatter name in autoLoadSkills. User file skills are discovered through OpenCode's native .opencode, .claude, .agents, skills.paths, and skills.urls mechanisms.
• Runtime configuration: set global agent models, variants, sandbox policy, custom agents, taskTraceSummarizer, and skill auto-load settings in ~/.config/opencode/agent_hive.json. See Agent mode and Task trace summarizer.

Canonical Delegation Threshold

• Route by the requested output rather than read-only status or whether paths are already known. Delegate bounded retrieval to a Scout when a real evidence gap makes delegation useful; keep causal diagnosis, correctness judgments, applicability, tradeoffs, and solution selection with the planner or orchestrator.
• Bounded direct reads remain acceptable whether or not the path was known before inspection. Delegate additional retrieval when it closes a named evidence gap.

Tools

Feature Management

| Tool | Description | |------|-------------| | hive_feature_create | Create a new feature | | hive_feature_complete | Mark feature as complete |

Planning

| Tool | Description | |------|-------------| | hive_plan_write | Write plan.md | | hive_plan_patch | Apply revision-scoped section/task amendments to plan.md; does not sync tasks automatically | | hive_plan_read | Read plan and comments | | hive_plan_approve | Approve plan for execution |

Tasks

| Tool | Description | |------|-------------| | hive_tasks_sync | Generate tasks from plan, or rewrite pending plan tasks with refreshPending: true after a plan amendment | | hive_task_create | Create a manual task with explicit dependsOn and optional structured metadata | | hive_task_update | Update task status/summary |

Worktree

| Tool | Description | |------|-------------| | hive_worktree_start | Start normal work on task (creates worktree) | | hive_worktree_create | Launch blocked-task continuation in existing worktree | | hive_worktree_commit | Complete task (applies changes) | | hive_worktree_discard | Abort task (discard changes) |

In gate-open sessions, hive_worktree_start may return a backgroundTaskCall for independent work. That output is launch guidance only; Hive does not create pending background board state until the parent actually starts the native background task. Use the normal blocking call when the next meaningful step depends on the worker result.

Merge and Status

| Tool | Description | |------|-------------| | hive_merge | Merge a completed task branch, with merge/squash/rebase strategies, optional conflict preservation, and optional cleanup | | hive_status | Inspect feature state, including task/worktree-aware merge eligibility through helperStatus.mergeEligibility |

When a task branch has no net tracked changes to integrate, hive_merge reports a successful no-op: success: true, merged: false, reasonCode: 'NO_TRACKED_CHANGES', and no empty sha. Requested cleanup can still run when safe. Use hive_status, not the background board, to decide whether a task has completed work and a live worktree eligible for merge or cleanup.

Ad-hoc Worktree

Use ad-hoc orchestration when you need isolation, delegation, verification, and merge without a feature, plan, or task record. Dedicated mode uses hive-builder; unified mode can use hive-master. The operator loop is in the Operator Guide.

The ad-hoc orchestrator uses hive_adhoc_* tools for isolated non-feature work under .hive/.worktrees/adhoc/<runId>. These runs do not create feature/task records and do not appear in hive_status. This orchestrator works in both gate-closed and gate-open sessions; gate-closed sessions return blocking taskToolCall payloads, while gate-open sessions return both taskToolCall and backgroundTaskCall (identical except background: true) so blocking remains available when the next step depends on the worker. hive_adhoc_worktree_create accepts autoSpawnWorker, default true; set it to false only for inspection, routing, or setup-only worktrees where no worker should auto-launch. See docs/HIVE-TOOLS.md for the full tool contracts.

Background Orchestration

With the env gate unset (OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS or OPENCODE_EXPERIMENTAL), Hive keeps normal blocking task() wait mode. Background board tools report background_tools_disabled, and no background appendix is injected into primary prompts.

With the env gate set, primary orchestrators receive delegate-first background scheduling guidance and the board tools are active. This is the background-first scheduler contract under the experimental gate, not always-on behavior. It does not add agents or change custom-agent preservation: primary agents still choose built-in or configured custom specialists by descriptor, not by a fixed routing table.

Gate-open orchestration uses lane kind to decide how much management is needed. Exploratory/read-only and review lanes are lightweight background candidates. Writing/change and execution lanes require path ownership, state tracking, verification routing, unresolved-lane checks, integration control, and a context packet. See docs/HIVE-TOOLS.md and the background-delegation skill for the full scheduler protocol.

With the env gate set, primary agents can launch independent native background tasks when useful foreground work can continue, inspect the scoped board with hive_background_status, wait for OpenCode's native completion notification, refresh hive_background_status, reconcile terminal jobs with hive_background_reconcile or hive_background_reconcile_batch, and request cancellation with hive_background_cancel. Reconciliation archives terminal jobs and hides them from normal status output; agents should not edit .hive/background-jobs.json directly. Wait-only scheduler guidance from status means wait for the native notification instead of refreshing repeatedly.

hive_background_status and reconcile responses may return recommendedNextAction and requiresHiveStatusRefresh. These are board-local scheduler outputs. They do not predict merge readiness; refresh hive_status before dependent task or merge decisions.

Prompt acknowledgment only means Hive showed a terminal result to the parent session. It does not clear terminalUnreconciled; the primary agent still reconciles or ignores the job after consuming the result.

Cancellation is not rollback. A cancellation request does not revert files, branches, worktrees, commits, or reports. If a stale lane cannot be resumed safely, use no-resume retry/escalation: start a fresh scoped attempt when safe, ignore the stale terminal entry with a reason, or escalate the blocker.

Delegated Task Inspection

Primary orchestrators can inspect one directly delegated native OpenCode child with hive_task_trace. Omitted or false recovery preserves the compact complete forensic v2 report over every surviving normalized step. Request hive_task_trace({ task_id, recovery: true }) for a terminal semantic handoff: one semantic card per source step, 1-12 coverage-gated phases, completed/unfinished claims, deterministic error and PatchPart file anchors, the final response labelled as an untrusted child self-report, and a runtime-safe next action. Active or uncertain traces return semantic recovery unavailable with zero model calls. Map failures fall back the whole affected step, reducer failures use balanced phases, ordered failures retain concurrent primary and cleanup causes, and undeleted sessions remain quarantined. Generated semantics may restate transient plaintext reasoning and are untrusted; source_steps name context coverage, not evidence or proof. Any partial/fallback/error/compacted result forces inspection; only complete generated unfinished work can launch a fresh task, and recovery never accepts, merges, retries, resumes, or auto-runs. Both response modes keep exact advisory render bytes with no hard cap. hive_task_trace_content reauthorizes direct v2 locators for allowlisted non-reasoning values; no copied trace store is created. See docs/HIVE-TOOLS.md for the full contract.

Troubleshooting

Repeated blocked-continuation errors / loop

If you see repeated retries around continueFrom: "blocked", use this protocol. That tool launches a new worker session in the same worktree; it does not continue the previous session:

1. Call hive_status() first.
2. If status is pending or in_progress, start normally with:
   • hive_worktree_start({ feature, task })
3. Only use blocked continuation when status is exactly blocked:
   • hive_worktree_create({ task, continueFrom: "blocked", decision })

Do not retry the same blocked-continuation call on non-blocked statuses; re-check hive_status() and use hive_worktree_start for normal starts.

Using with DCP plugin

When using Dynamic Context Pruning (DCP), use a Hive-safe config in ~/.config/opencode/dcp.jsonc:

• manualMode.enabled: true
• manualMode.automaticStrategies: false
• turnProtection.enabled: true with turnProtection.turns: 12
• tools.settings.nudgeEnabled: false
• protect key tools in tools.settings.protectedTools (at least: hive_status, hive_worktree_start, hive_worktree_create, hive_worktree_commit, hive_worktree_discard, question)
• disable aggressive auto strategies:
  • strategies.deduplication.enabled: false
  • strategies.supersedeWrites.enabled: false
  • strategies.purgeErrors.enabled: false

For normal usage, set the OpenCode plugin entry to "oc-arkive@latest". Keep a local file path entry only for contributor testing with a checkout.

Task worker recovery

After session compaction, task workers re-read worker-prompt.md and continue from the current worktree state. Compaction may re-anchor a currently running worker; it is not re-delegation. Primary and subagent sessions replay the stored user directive once, then escalate if needed.

Manual tasks created with hive_task_create() follow the same DAG model as plan-backed tasks. The goal, description, acceptanceCriteria, files, and references fields are turned into spec.md content visible to the worker. To change downstream sequencing or scope after review feedback, update plan.md and run hive_tasks_sync({ refreshPending: true }).

hive-helper is a runtime-only bounded assistant for merge recovery, state clarification, interrupted-state wrap-up, and safe manual-follow-up assistance. It stays within the current approved DAG boundary and is not a selectable custom base agent.

simplicity-reviewer is a built-in read-only reviewer for final post-implementation cleanup and a supported customAgents base for specialized cleanup passes. It reviews completed diffs for YAGNI, dead code, duplication, unnecessary abstractions, redundant defensive code, and safe deletion-biased simplification.

Prompt Budgeting & Observability

Hive automatically bounds worker prompt sizes to prevent context overflow and tool output truncation.

Budgeting Defaults

| Limit | Default | Description | |-------|---------|-------------| | maxTasks | 10 | Number of previous tasks included | | maxSummaryChars | 2,000 | Max chars per task summary | | maxContextChars | 20,000 | Max chars per context file | | maxTotalContextChars | 60,000 | Total context budget |

When limits are exceeded, content is truncated with ...[truncated] markers and file path hints are provided so workers can read the full content.

Observability

hive_worktree_start and blocked-resume hive_worktree_create output include metadata fields:

• promptMeta: Character counts for plan, context, previousTasks, spec, workerPrompt
• payloadMeta: JSON payload size, whether prompt is inlined or referenced by file
• budgetApplied: Budget limits, tasks included/dropped, path hints for dropped content
• warnings: Array of threshold exceedances with severity levels (info/warning/critical)

Prompt Files

Large prompts are written to .hive/features/<feature>/tasks/<task>/worker-prompt.md and passed by file reference (workerPromptPath) rather than inlined in tool output. This prevents truncation of large prompts.

That same worker-prompt.md path is also reused during compaction recovery so task workers can re-anchor to the exact task assignment after a compacted session resumes.

Plan Format

# Feature Name

## Overview
What we're building and why.

## Tasks

### 1. Task Name
Description of what to do.

### 2. Another Task
Description.

## Final Verification

- Run the full test suite after task branches are merged.

hive_tasks_sync reads numbered task headings from ## Tasks in modern plans. A final verification section stays outside the task DAG unless the verification itself needs tracked artifacts produced by a task.

Configuration

Hive reads runtime configuration only from ~/.config/opencode/agent_hive.json. Project-local .hive/agent-hive.json and .opencode/agent_hive.json files are ignored, including malformed files. Global config failures still produce a runtime warning and fall back to defaults.

All runtime policy, agent definitions, and auto-load skill settings use the global file.

hook_cadence currently has no useful tuning surface: production gates only the safety-critical tool.execute.before hook, which is forced to cadence 1. The schema remains the machine-readable reference for this field.

Agent mode

agentMode selects how planning and orchestration seats are registered. Default is "dedicated".

| Value | Default agent | Primary seats | When to use | |-------|---------------|---------------|-------------| | dedicated | architect-planner | Separate architect-planner and swarm-orchestrator | Default; split planning and execution across two primary seats | | unified | hive-master | One hybrid planner+orchestrator | One primary agent owns the full feature loop |

In both modes:

• Researchers, workers, reviewers, hive-helper, and hive-builder remain available.
• Slash-command routing follows the Operator Commands table.
• Custom derived subagents attach to the active planner/orchestrator prompts for that mode.

{
  "$schema": "https://raw.githubusercontent.com/imarshallwidjaja/agent-hive/main/packages/opencode-hive/schema/agent_hive.schema.json",
  "agentMode": "unified"
}

Dedicated mode does not auto-switch the live chat agent when you run a slash command. If the active agent is not the route target, delegate or reroute to that target and stop if that is not possible. /dash-review and /vuln-review always bind to private review primaries regardless of mode.

Task trace summarizer

taskTraceSummarizer configures the hidden, parentless, tool-less model used only when a primary agent calls hive_task_trace({ task_id, recovery: true }). It does not change forensic (non-recovery) traces, which stay deterministic and model-free.

| Field | Required | Default | Notes | |-------|----------|---------|-------| | model | no | OpenCode default model | Nonempty provider/model-id string | | variant | no | OpenCode default / none | Must match a key under opencode.json provider.<provider>.models.<model>.variants | | temperature | no | 0 | Number from 0 through 2 |

Behavior:

• Recovery interpretation is always marked untrusted (provenance: 'summarizer_interpretation').
• An unavailable configured model or variant produces deterministic partial fallback without provider retry.
• Recovery never authorizes accept, merge, retry, resume, or auto-run. Use recovery context only as input for a new task without task_id.
• See Delegated Task Inspection for the full trace/recovery contract.

{
  "$schema": "https://raw.githubusercontent.com/imarshallwidjaja/agent-hive/main/packages/opencode-hive/schema/agent_hive.schema.json",
  "taskTraceSummarizer": {
    "model": "anthropic/claude-sonnet-4-20250514",
    "variant": "high",
    "temperature": 0
  }
}

Council config

Council settings live in ~/.config/opencode/agent_hive.json.

Built-in council defaults are read-only and portable:

| Group | Purpose | Default members | |-------|---------|-----------------| | design | Architecture and implementation-shape advice. | scout-researcher, approach-advisor, plan-reviewer, code-reviewer | | decision | Hard tradeoff decision support. | scout-researcher, approach-advisor, plan-reviewer | | minimal-change | Smallest correct change and cleanup lens. | scout-researcher, simplicity-reviewer, code-reviewer | | documents | Documentation and prose-oriented review. | scout-researcher, code-reviewer, plan-reviewer |

The default excludedAgents list excludes mutable orchestration or implementation seats: hive-master, swarm-orchestrator, forager-worker, hive-builder, and hive-helper. Member names can be built-in stock agents or configured custom agents. Custom agents derived from mutable bases, including forager-worker, are skipped by default with warnings.

Partial global overrides merge with the built-in defaults. Declaring a group replaces that group declaration and leaves omitted default groups intact:

{
  "$schema": "https://raw.githubusercontent.com/imarshallwidjaja/agent-hive/main/packages/opencode-hive/schema/agent_hive.schema.json",
  "council": {
    "defaultGroup": "documents",
    "maxMembers": 3,
    "excludedAgents": ["simplicity-reviewer"],
    "groups": {
      "documents": {
        "description": "Docs and operator prose review",
        "members": ["scout-researcher", "code-reviewer", "plan-reviewer"],
        "maxMembers": 2
      },
      "security": {
        "description": "Security-sensitive review",
        "members": ["scout-researcher", "reviewer-security", "code-reviewer"]
      }
    }
  }
}

Council resolution preserves configured order, deduplicates by first occurrence, filters unusable seats before applying the cap, and uses group.maxMembers ?? council.maxMembers ?? 4. It skips unavailable agents, explicitly excluded agents, starter template custom agents, mutable-base agents, and duplicates with warnings. If a requested group has no usable seats, /council falls back to council.defaultGroup; if the fallback also has no usable seats, the command stops with an error instead of running an unsafe council.

Project-local repository manifest

Optional Hive-managed project state for multi-repo topology. Single-repository projects need no manifest. Do not hand-author this file for normal onboarding; ask Hive to inspect, discover, and update topology with hive_repositories_status, hive_repositories_discover, and hive_repositories_update.

Generated/managed shape (for inspection) at <project>/.hive/repositories.json:

{
  "schemaVersion": 1,
  "repositories": [
    { "id": "api", "path": "./api" }
  ]
}

Global-only: Disable Skills or MCPs

{
  "$schema": "https://raw.githubusercontent.com/imarshallwidjaja/agent-hive/main/packages/opencode-hive/schema/agent_hive.schema.json",
  "disableSkills": ["brainstorming", "writing-plans"],
  "disableMcps": ["websearch", "ast_grep"]
}

Available Skills

| ID | Description | |----|-------------| | adversarial-review | Explicit adversarial / red-team / multi-pass review posture | | agents-md-mastery | Bootstrap, review, or prune AGENTS.md by placing rules next to the code they govern | | ast-grep | Structural code search via the ast-grep MCP tools | | background-delegation | Env-gated background wait-mode and board protocol | | brainstorming | Explore intent and design before implementation | | code-reviewer | Deprecated compatibility wrapper; prefer the code-reviewer subagent | | dispatching-parallel-agents | Coordinate independent subagent work | | docker-mastery | Dockerfiles, containers, and sandbox debugging | | executing-plans | Execute an approved plan with review checkpoints | | parallel-exploration | Researcher fan-out for read-only research | | systematic-debugging | Root-cause investigation before fixes | | test-driven-development | Strict red-green-refactor when TDD is the selected testing strategy | | verification | Fresh evidence before completion or verification claims | | verification-before-completion | Deprecated wrapper; use verification completion gate mode | | verification-reviewer | Deprecated wrapper; use verification report mode | | writing-plans | Turn requirements into an implementation plan |

Available MCPs

| ID | Description | Requirements | |----|-------------|--------------| | websearch | Web search via Exa AI. Real-time web searches and content scraping. | Set EXA_API_KEY env var | | context7 | Library documentation lookup via Context7. Query up-to-date docs for any programming library. | None | | grep_app | GitHub code search via grep.app. Find real-world code examples from public repositories. | None | | ast_grep | Structural search and AST inspection via ast-grep. Pattern matching across 25+ languages. | None (runs via npx) |

Per-Agent Skills

Skills are loaded through OpenCode's native skill tool, not through a Hive plugin tool. Hive bundles are materialized into the global OpenCode config directory under agent-hive/generated/opencode-skills/<hash>/ at startup and registered via opencodeConfig.skills.paths ahead of any user-configured paths.

Configuration fields:

| Field | Behavior | |-------|----------| | skills | Legacy field kept for config compatibility. Native skill visibility is controlled by OpenCode registration and disableSkills, not by per-agent allowlists. | | autoLoadSkills | Adds high-priority prompt guidance telling the agent to load named OpenCode-native skills with the skill tool before work covered by them. | | disableSkills (global) | Disables Hive bundled materialization and Hive bundled autoload only. User or native skills with the same name are not blocked. |

User file skills should be configured through OpenCode's native .opencode, .claude, .agents, skills.paths, or skills.urls discovery. They can be loaded manually with the native skill tool or advertised to an agent by adding the skill's frontmatter name to autoLoadSkills. Native/user skills take precedence over Hive bundled skills with the same name.

URL-scan conservative behavior: If configured skills.urls cannot be scanned for conflicts (invalid response, network error), Hive skips bundled skill materialization and Hive bundled autoload guidance for that run and logs a warning rather than risking a native conflict. Local native skills discovered before the URL failure can still be advertised in guidance; partially scanned URL skills are not advertised.

background-delegation is bundled and materialized like other Hive skills, but primary prompt references are env-gated and compact. Delegation-first orchestration lives in the base primary prompts; when the env flag is set, primary agent prompts add background wait-mode and board protocol guidance and point to the skill for the full protocol. The skill can still be loaded manually with OpenCode's native skill tool like any other bundled or user skill.

Example:

{
  "agents": {
    "hive-master": {
      "autoLoadSkills": ["brainstorming"]
    }
  }
}

autoLoadSkills resolves names through OpenCode-native skill discovery first, then through eligible Hive bundled skills. The identity is the name field in SKILL.md frontmatter, not the containing directory name. Disabled Hive skills, Hive skills shadowed by native/user skills, and URL-unsafe Hive skills are skipped. Unknown names emit a warning. Startup continues without failure.

How skills and autoLoadSkills interact:

• skills is a legacy field kept for config compatibility. In the native skill slice, skill visibility is controlled by OpenCode's native skills.paths registration and disableSkills, not by per-agent skills allowlists.
• autoLoadSkills adds a compact system-prompt directive to load OpenCode-discovered native skills or eligible Hive bundled skills with skill({ name: "..." }) before matching work; it does not preload full skill bodies
• These are independent: a skill can be advertised for native loading even if it is not in the agent's legacy skills list
• User autoLoadSkills are merged with defaults (use global disableSkills to remove defaults from autoload)

Default auto-load skills by agent:

| Agent | autoLoadSkills default | |-------|------------------------| | hive-master | parallel-exploration | | forager-worker | verification | | hive-builder | verification, parallel-exploration | | hive-helper | (none) | | scout-researcher | (none) | | architect-planner | parallel-exploration | | swarm-orchestrator | parallel-exploration | | plan-reviewer | (none) | | code-reviewer | (none) | | approach-advisor | (none) |

background-delegation is not a default autoLoadSkills entry for any agent. For ad-hoc orchestration, delegation-first guidance is in the base prompt; the env flag (OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS or OPENCODE_EXPERIMENTAL) only appends background wait-mode and board guidance without adding it to the default autoload set.

Per-Agent Model Variants

You can set a variant for each Hive agent to control model reasoning/effort level. Variants are keys that map to model-specific option overrides defined in your opencode.json.

{
  "$schema": "https://raw.githubusercontent.com/imarshallwidjaja/agent-hive/main/packages/opencode-hive/schema/agent_hive.schema.json",
  "agents": {
    "hive-master": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "variant": "high"
    },
    "forager-worker": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "variant": "medium"
    },
    "scout-researcher": {
      "variant": "low"
    }
  }
}

The variant value must match a key in your OpenCode config at provider.<provider>.models.<model>.variants. For example, with Anthropic models you might configure thinking budgets:

// opencode.json
{
  "provider": {
    "anthropic": {
      "models": {
        "claude-sonnet-4-20250514": {
          "variants": {
            "low": { "thinking": { "budget_tokens": 5000 } },
            "medium": { "thinking": { "budget_tokens": 10000 } },
            "high": { "thinking": { "budget_tokens": 25000 } }
          }
        }
      }
    }
  }
}

Precedence: If a prompt already has an explicit variant set, the per-agent config acts as a default and will not override it. Invalid or missing variant keys are treated as no-op (the model runs with default settings).

Custom Derived Subagents

Define plugin-only custom subagents with customAgents. Freshly initialized agent_hive.json files already include starter template entries under customAgents; those seeded *-example-template entries are placeholders only, should be renamed or deleted before real use, and are intentionally worded so planners/orchestrators are unlikely to select them as configured. Each custom agent must declare:

• baseAgent: one of scout-researcher, forager-worker, plan-reviewer, code-reviewer, simplicity-reviewer, approach-advisor, or vulnerability-reviewer
• description: required non-whitespace delegation guidance injected into eligible primary planner/orchestrator prompts

Custom subagents are scoped routing specialists, not model-upgrade switches. Primary agents choose them autonomously when their description is a closer match for the requested output, task domain, workflow, artifact type, or concrete review/approach risk. They keep the built-in base agent when no configured description is a closer fit. A custom description specializes routing within the inherited base role; it cannot expand that role or override its prompt, tool, or permission boundaries. Candidate-specific conditions in an individual description still apply, including a condition that the candidate may be selected only when the operator explicitly names it. Importance, size, generic complexity, quality sensitivity, and a stronger model are not routing reasons. At runtime, custom agent entries with reserved names, non-object declarations, unsupported baseAgent values, or missing, blank, or whitespace-only description values are skipped with warnings.

The same seven built-in bases allow an optional routing-description override under the existing agents map. Nonblank values are trimmed before publication. Omitted, blank, or whitespace-only values inherit the canonical default without dropping unrelated settings on that built-in. Putting description on a non-customizable built-in invalidates the stored global config. At runtime, Agent Hive rejects the entire stored config and falls back to defaults, so unrelated stored settings are ignored until the config is corrected. The runtime skip behavior above does not promise a per-entry fallback for arbitrary schema-invalid optional fields. Custom agents never inherit a base description; every custom entry must supply its own non-whitespace description.

| Configurable base | Canonical default description | |-------------------|-------------------------------| | scout-researcher | Retrieves bounded internal or external code, context, and data evidence without owning diagnosis, tradeoffs, or solution selection. | | forager-worker | Implements and verifies changes in an isolated worktree; diagnosis-only assignments remain report-only. | | plan-reviewer | Default for ordinary plan review covering worker readiness, references, dependencies, and executable verification. | | code-reviewer | Default for ordinary implementation review covering correctness, tests, risk, scope creep, YAGNI, and dead code. | | simplicity-reviewer | Default for ordinary post-implementation simplicity review covering unnecessary abstractions, duplication, dead code, and safe deletion. | | approach-advisor | Default for ordinary read-only approach advice on technical direction, architecture, debugging, and tradeoffs. | | vulnerability-reviewer | Default for application-security review focused on evidenced attacker-to-impact paths and root-cause triage. |

Primary orchestrators, hive-builder, hive-helper, architect-planner, private __hive_* identities, and generated review lanes do not expose description overrides.

hive-helper is not a custom base agent. In v1 it stays runtime-only for isolated merge recovery.

simplicity-reviewer is a custom base agent for specialized cleanup passes. Primary agents still use the built-in simplicity-reviewer when no configured simplicity-reviewer-derived custom description is a closer match.

vulnerability-reviewer is a custom base agent for selectable /vuln-review specialist lenses. Its private wrapper preserves the configured description, model, variant, and temperature while enforcing the vulnerability workflow's read-only tool policy. A custom specialist cannot replace the mandatory baseline or fixed falsifier.

hive-helper is also not a network consumer; planning, orchestration, and review roles get network access first.

Published example (validated by src/e2e/custom-agent-docs-example.test.ts):

{
  "agents": {
    "scout-researcher": {
      "variant": "low"
    },
    "forager-worker": {
      "description": "Default for ordinary backend implementation.",
      "variant": "medium"
    },
    "code-reviewer": {
      "model": "github-copilot/gpt-5.2-codex"
    }
  },
  "customAgents": {
    "scout-docs": {
      "baseAgent": "scout-researcher",
      "description": "Use for research centered on documentation, release notes, READMEs, or external docs synthesis."
    },
    "forager-ui": {
      "baseAgent": "forager-worker",
      "description": "Use for UI implementation tasks touching React/Next components, styling, accessibility, or browser-visible behavior.",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.2,
      "variant": "high"
    },
    "reviewer-security": {
      "baseAgent": "code-reviewer",
      "description": "Use for review passes focused on auth, permissions, secret handling, injection risk, or other security-sensitive changes."
    }
  }
}

Inheritance rules when a custom agent field is omitted:

| Field | Inheritance behavior | |-------|----------------------| | model | Inherits resolved base agent model (including user overrides in agents) | | temperature | Inherits resolved base agent temperature | | variant | Inherits resolved base agent variant | | autoLoadSkills | Merges with base agent auto-load defaults/overrides and de-duplicates. disableSkills only suppresses Hive bundled guidance/materialization, not native/user skills with the same name. |

ID guardrails:

• customAgents keys cannot reuse built-in Hive agent IDs
• plugin-reserved aliases are blocked (hive, architect, swarm, scout, forager, hygienic, hygienic-reviewer, receiver)
• operational IDs are blocked (build, plan, code)

Compaction classification follows the base agent:

• scout-researcher derivatives are treated as subagent
• forager-worker derivatives are treated as task-worker
• plan-reviewer, code-reviewer, approach-advisor, and vulnerability-reviewer derivatives are treated as subagent

This ensures custom workers recover with the same execution constraints as their base role.

Custom Models

Override models for specific agents:

{
  "agents": {
    "hive-master": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.5
    }
  }
}

Focused references

• Hive Tools for tool inventory and contracts
• Data Model for .hive/ state and task records
• Operator Guide for public agents and the feature / ad-hoc / dash-review / vuln-review loops
• Design for architecture and source-of-truth rules

Pair with VS Code

For the full OpenCode-first workflow, install vscode-arkive.vsix from the GitHub Release as an optional review/sidebar companion for inline comments and document review.

License

MIT with Commons Clause - Free for personal and non-commercial use. See LICENSE for details.