v1.4.8

Release v1.4.8

Compare: v1.4.7...v1.4.8

---

Highlights

Claude Code plugin works end-to-end

v1.4.7 published the Claude Code plugin, but every install path had a blocker: the marketplace listing was missing, the manifest shape was wrong, agents weren't discoverable, and the MCP runtime couldn't launch from the plugin cache. This release fixes all four.

1 · Plugin marketplace listing

New .claude-plugin/marketplace.json at the repo root registers hive as a plugin sourced from ./packages/claude-code-hive. Users can now install with:

/plugin marketplace add tctinh/agent-hive
/plugin install hive@agent-hive

No more manual npm install + path-pointing ceremony.

2 · Manifest shape matches the current spec

Two independent schema bugs made Claude Code reject the manifest before installing:

• Location — the manifest must live at .claude-plugin/plugin.json, not plugin.json at the plugin root. Moved.
• Component fields — the agents field does not accept a directory string; it requires an array of file paths. And commands, once an object map with { source, description, argumentHint }, must be a path string or array. The cleanest fix was to drop agents, skills, and commands entirely and let Claude Code auto-discover them from the default ./agents/, ./skills/, ./commands/ paths.

The current manifest now has just name, metadata, hooks, and mcpServers — everything else is discovered.

3 · Agent frontmatter carries a name

Claude Code reads the agent name from YAML frontmatter, not the filename. Every Hive agent (hive, forager, hygienic) now declares name: so auto-discovery registers them correctly. After this fix /hive can dispatch hive:forager and hive:hygienic without the orchestrator complaining that those agents don't exist.

Also stripped OpenCode-only frontmatter fields (user-invocable, isolation, maxTurns) that Claude Code ignored.

4 · MCP runtime launches via npx

The old scripts/launch-hive-mcp.mjs used require.resolve('@tctinh/agent-hive-mcp') from the plugin cache directory, where there is no node_modules/ — so a globally installed MCP package was never on the resolution path. Every real plugin in the wild (ChromeDevTools, Google Clasp, Aztec, Fulcrum) uses npx -y for the MCP spawn. Hive now does the same:

"mcpServers": {
  "hive": {
    "command": "npx",
    "args": ["-y", "-p", "@tctinh/agent-hive-mcp@latest", "hive-mcp"]
  }
}

No global install required. npx fetches and caches on the first /hive invocation. The custom launcher scripts and their tests are gone.

5 · README rewrite

README.md is now a user-facing install guide with three platform paths (Claude Code, OpenCode, VS Code) and a fixed-scope description for each. Previous version conflated the VS Code extension with "a full Copilot runtime alternative," which it is not — it's a review/status companion over .hive/ state written by a CLI runtime. Corrected.

---

What Changed

Added

• .claude-plugin/marketplace.json at repo root — enables /plugin marketplace add tctinh/agent-hive
• Release-contract check asserting the Claude Code plugin wires its MCP runtime via npx without a local dependency

Fixed

• Claude Code manifest relocated to .claude-plugin/plugin.json and stripped down to just metadata + hooks + mcpServers
• Agents now carry name: in YAML frontmatter so Claude Code auto-discovery registers them
• MCP runtime spawns via npx -y -p @tctinh/agent-hive-mcp@latest hive-mcp — no more broken require.resolve in plugin cache
• Top-level README reflects actual platform capabilities (corrects Copilot-runtime framing, adds npx install flow)

Removed

• scripts/launch-hive-mcp.mjs, scripts/prepare-workspace-hive-mcp.mjs, and their tests — obsolete under the npx spawn model
• @tctinh/agent-hive-mcp from claude-code-hive package.json dependencies — npx resolves it at runtime
• Root-README assertions for detailed hive-helper runtime docs in packages/opencode-hive/src/agents/prompts.test.ts — those details now live in the package README where they belong

Changed

• All version-bearing surfaces bumped to 1.4.8: root/workspace manifests, plugin manifests, marketplace manifest, MCP runtime version string, lockfiles, dependency pins, changelog, philosophy, release note

---

Breaking Changes

None for OpenCode or VS Code consumers. The Claude Code plugin's install flow has changed (marketplace now works instead of requiring manual npm install + path pointing). Users on the npm-only install path can keep using it — they just need to point at .claude-plugin/plugin.json inside the package instead of plugin.json at the package root.

---

Upgrade Notes

Claude Code users

/plugin marketplace remove agent-hive  (if previously added)
/plugin marketplace add tctinh/agent-hive
/plugin install hive@agent-hive

If you installed a previous build via npm install, re-install pointing at the new manifest location:

npm install claude-code-hive@1.4.8 @tctinh/agent-hive-mcp@1.4.8
# then register Claude Code against node_modules/claude-code-hive/.claude-plugin/plugin.json

OpenCode users

npm install opencode-hive@1.4.8

VS Code users

Update from the marketplace (tctinh.vscode-hive 1.4.8).

---

Philosophy Alignment

P7 (Iron Laws + Hard Gates): Plugin schema validation is enforced by Claude Code's installer and by our own verify-plugin-assets.mjs — a manifest that passes the local check should now also pass the marketplace check. We assert the name: frontmatter requirement so a regression can't silently re-break agent discovery.

P8 (Cross-Model Prompts): The agent role definitions remain model-agnostic; this release only adjusts the frontmatter keys Claude Code's loader needs, not the prompts themselves.

P9 (Deterministic Contracts Beat Soft Memory): The release contract test now covers the npx-based MCP wiring explicitly. A future edit that accidentally reintroduces the node-launcher path, re-adds the MCP package to claude-code-hive dependencies, or drops name: from an agent will fail release:check.

See the PHILOSOPHY.md § v1.4.8 evolution note for the full rationale.

---

Verification Coverage

• node --test release-artifacts.test.mjs — verifies 1.4.8 release note, changelog order, version-bearing surfaces, Claude Code plugin pack contract, and the npx-based MCP wiring contract
• node --test release-workflow.test.mjs — verifies workflow contracts, publish helper, and recovery docs
• bun test — full package test suite (no root-README drift tests anymore)
• bun run release:check — full preflight

v1.4.7

Release v1.4.7

Compare: v1.4.6...v1.4.7

---

Highlights

1 · Release workflow now skips already-published targets

The CI release workflow previously failed hard when a publish target was already live — blocking every downstream job in the same run. Starting with v1.4.7, each publish job checks whether the version already exists before attempting to publish:

• npm jobs (opencode-hive, @tctinh/agent-hive-mcp, claude-code-hive): query npm view <pkg>@<version> before each npm publish. If the version is already on the registry, the publish step is skipped and the job completes successfully.
• VS Code Marketplace: publish is attempted normally, but an "already exists" error is treated as success rather than a failure.

This makes the workflow re-entrant: if a tag-triggered run partially completes (some targets publish, others fail), a recovery run skips the already-published targets and retries only the missing ones. No manual selector flags needed for the common case.

Why it matters: The previous behaviour turned a routine partial failure into a manual recovery problem. The workflow should be a safe operation to re-run.

2 · @tctinh/agent-hive-mcp now carries a repository field

The hive-mcp package was missing repository, homepage, and bugs fields. npm's provenance validation requires repository.url to match the source repository declared in the GitHub Actions OIDC token. Without it, npm publish --provenance fails with E422 Error verifying sigstore provenance bundle.

This completes the package metadata so provenance can be generated correctly for @tctinh/agent-hive-mcp.

---

What Changed

Added

• Skip-if-already-published guard in every npm publish job — npm view check before npm publish, skips with a notice if the version is already live
• Graceful "already exists" handling in the VS Code Marketplace publish step — non-zero exit is ignored when the error message indicates the version is already published

Fixed

• @tctinh/agent-hive-mcp was missing repository, homepage, and bugs fields — npm publish --provenance rejected the package with E422 because provenance validation requires repository.url to match the GitHub repo
• Release workflow no longer blocks all downstream jobs when a single publish target is already live

Changed

• All version-bearing surfaces bumped to 1.4.7: root/workspace manifests, plugin manifests, MCP runtime version string, dependency pins, lockfiles, changelog, release note, and PHILOSOPHY

---

Breaking Changes

None. This is a patch release focused on release-pipeline reliability.

---

Upgrade Notes

npm install opencode-hive@1.4.7           # OpenCode plugin
npm install @tctinh/agent-hive-mcp@1.4.7  # MCP runtime
npm install claude-code-hive@1.4.7         # Claude Code plugin assets

---

Philosophy Alignment

P7 (Iron Laws + Hard Gates): The release pipeline is now idempotent by default. Re-running the workflow after a partial failure is safe — it does the minimum work still needed, not the full sequence again.

P9 (Deterministic Contracts Beat Soft Memory): A publish step that silently skips an already-live version is a stronger contract than one that fails and requires the operator to remember what succeeded in a previous run.

See the PHILOSOPHY.md § v1.4.7 evolution note for the full rationale.

---

Verification Coverage

• node --test release-artifacts.test.mjs — verifies 1.4.7 release note, changelog order, and version-bearing surfaces all align
• node --test release-workflow.test.mjs — verifies workflow contracts, npm publish helper, and recovery docs
• bun run release:check — full preflight: lockfiles, builds, and workspace tests before tag

v1.4.5

Release v1.4.5

Compare: v1.4.4...v1.4.5

---

Highlights

1 · Hive now loads the right Copilot skill for the job instead of listing everything equally

v1.4.5 turns the generated Hive prompt from a generic skill catalog into a trigger-based workflow contract.

Multi-domain read-only research now points directly at parallel-exploration, bugs and failing tests point at systematic-debugging, implementation points at test-driven-development, and completion claims point at verification-before-completion.

Why it matters: Copilot already had these skills available, but availability alone did not guarantee good choices. This patch reduces that gap by teaching the generated Hive surface when each procedural layer should activate.

2 · Browser, Playwright, todo, and memory guidance now ship as role-aware instructions instead of ambient capability

The generated Scout, Forager, and Hygienic prompts now explain when browser inspection, repeatable Playwright automation, active todo tracking, and durable memory are worth using.

The repository-wide Copilot instructions and Hive workflow instruction now mirror that same task-triggered guidance, so the browser / Playwright / memory / todo story is consistent across the top-level operator-facing surfaces.

Why it matters: Tool lists are not enough. Operators get better outcomes when the shipped prompts tell the agent when a tool materially reduces guesswork instead of assuming the agent will infer that from frontmatter alone.

3 · Built-in skills now teach task lookup and evidence-driven tool use end to end

This release also upgrades the procedural skills themselves.

Writing-plans now starts from hive_status() when a feature already exists, execution and parallel-dispatch flows explain when todo or vscode/memory are justified, and the debugging / TDD / verification skills now treat browser and Playwright evidence as first-class options for UI and end-to-end work.

Why it matters: The quality of the Copilot path depends on the surrounding teaching materials as much as the code. v1.4.5 closes the loop by making the skills, generators, and committed .github/* artifacts describe the same operational workflow.

---

What Changed

Added

• Trigger-based skill-loading guidance in the generated Hive prompt and repository-wide Copilot instructions so research, debugging, implementation, and completion verification each point at the right procedural skill
• Tool-aware task lookup guidance via hive_status() in the planning and execution skills
• Role-specific browser / Playwright / todo / memory guidance across the generated Scout, Forager, and Hygienic prompts

Changed

• Built-in Copilot skills now explain when browser tools, Playwright MCP, todo, and vscode/memory improve planning, orchestration, research, debugging, TDD, and verification instead of treating those capabilities as generic always-on helpers
• The committed .github/agents, .github/instructions, .github/copilot-instructions.md, and .github/skills/* artifacts now stay aligned with the updated generator contract for the Copilot workflow
• Root/workspace manifests, packages/opencode-hive/plugin.json, tracked workspace lockfile markers, the changelog, the dedicated release note, and the PHILOSOPHY evolution history now report 1.4.5

Fixed

• Hive no longer leaves parallel-exploration implicit for multi-domain read-only investigations
• Copilot guidance no longer relies on flat capability lists for browser, Playwright, todo, and memory usage where the task needs a more explicit rule
• Committed generated Copilot artifacts no longer drift behind the source generators for the updated tool-aware workflow

---

Breaking Changes

None.

This is a patch release focused on making the existing Copilot surface more explicit and reliable. Existing repositories should regenerate their .github/* artifacts to pick up the refined guidance.

---

Upgrade Notes

npm install opencode-hive@1.4.5   # or: bun add opencode-hive@1.4.5

• Regenerate the generated Copilot / VS Code artifacts so your repository picks up the new trigger-based skill-loading and tool-usage guidance
• If you maintain custom .github/agents, .github/instructions, or .github/skills content, review it against the updated generated contract before assuming your local variants still teach the same workflow
• For UI- or browser-dependent work, prefer the new guidance around quick browser inspection first and repeatable Playwright automation when the repro path is clear

---

Philosophy Alignment

This release sharpens four of Hive's core principles:

P2 (Plan → Approve → Execute): The Copilot path now makes the correct procedural skill part of the execution contract instead of leaving it as a soft hint.

P3 (Human Shapes, Agent Builds): The generated workflow is more honest about when the agent should use browser tools, Playwright, todo tracking, and durable memory, which makes the human-facing operator story easier to trust.

P8 (Cross-Model Prompts): The same task-triggered guidance now shows up consistently across the generators, committed .github/* artifacts, and built-in skills.

P9 (Deterministic Contracts Beat Soft Memory): Capability lists are now backed by explicit situational rules and committed-artifact parity, so the Copilot path depends less on lucky prompt interpretation.

See the PHILOSOPHY.md § v1.4.5 evolution note for the full rationale.

---

Verification Coverage

• node --test release-artifacts.test.mjs — verifies the 1.4.5 release note exists, the changelog is ordered correctly, and all version-bearing release surfaces move together
• ~/.bun/bin/bun test src/generators/agents.test.ts src/generators/instructions.test.ts src/generators/skills.test.ts src/generators/committedArtifactsParity.test.ts src/__tests__/generators.test.ts — verifies the updated Copilot generator contract and committed artifacts stay aligned
• bun run release:check — validates release artifacts, workflow contracts, builds, and workspace package tests before PR merge or tag creation

v1.4.4

Release v1.4.4

Compare: v1.4.3...v1.4.4

---

Highlights

1 · Copilot-native Hive workflow alignment is now the shipped generated default

v1.4.4 ships the broad Copilot alignment work across the generated .github artifact surface and the VS Code extension contract.

The release centers the Copilot path on a single review/execution document (plan.md), trims the Copilot-facing Hive tool surface down to the structured domain tools that still add value, and refreshes the generated agents, prompts, instructions, hooks, and skills so they teach the same workflow the code now supports.

Why it matters: The VS Code/Copilot preview path is only useful if the generated repo scaffolding matches the real supported workflow. This patch removes a lot of lingering drift from the older overview-first, helper-heavy guidance and replaces it with the simpler plan-first contract the product now expects.

2 · Response-first worker tuning and agent contract cleanup now ship together

This release also carries forward the worker/agent contract cleanup:

• direct @forager execution remains the default Copilot path
• structured hive_task_update remains the machine-readable progress/completion surface
• Forager still ends with a short natural-language handoff so operators and orchestrators get a usable summary instead of only tool output
• generated agent metadata now matches current GitHub Copilot model naming and curated-tool expectations

Why it matters: Operators need both trustworthy state and fast human comprehension. v1.4.4 keeps the structured contract for orchestration while making sure the generated worker behavior and agent metadata still feel usable in day-to-day review and execution.

3 · Official ast-grep MCP adoption replaces the older implied launcher contract

The OpenCode-side package, templates, and related docs now prefer the official ast-grep MCP server path.

Why it matters: Structural search and code-aware verification are more maintainable when Hive points at the upstream maintained MCP surface rather than a private launcher story users have to infer from generated files and package metadata.

---

What Changed

Added

• A complete Copilot-native scaffolding refresh across .github/agents, prompts, instructions, hooks, and skills so generated repos start from the current plan-first workflow instead of legacy helper guidance
• Committed-artifact parity coverage for the generated Copilot asset surface, helping keep source generators and checked-in artifacts aligned
• A dedicated docs/releases/v1.4.4.md release body for publishing the 1.4.4 tag cleanly

Changed

• plan.md is now the single required review and execution document for the Copilot-facing path; generated guidance no longer depends on a required context/overview.md review surface
• Generated agent tool contracts now use the current Copilot-facing IDs and curated capabilities where appropriate, including web, browser, io.github.upstash/context7/*, playwright/*, todo, and vscode/memory
• Agent model metadata is aligned with current Copilot display-name expectations: Hive uses GPT-5.4 (copilot), Scout and Hygienic use Claude Sonnet 4.6 (copilot), and Forager supports both models
• Root/workspace manifests, packages/opencode-hive/plugin.json, and tracked workspace lockfile markers now report 1.4.4
• CHANGELOG.md and PHILOSOPHY.md now document the release as a single coherent patch rather than leaving the operator story split across commit history and generated artifacts

Fixed

• Stale generated agent metadata no longer advertises old tool IDs like web/fetch or outdated model strings that no longer match current GitHub Copilot expectations
• Curated subagents no longer miss browser, Context7, memory, or todo support where the updated Copilot flow depends on them
• Response-first worker completion no longer loses the human-readable handoff after structured task-state reporting
• opencode-hive plan approval no longer references the removed reviewCounts.overview field, restoring a clean package build for release verification and packaging
• Ast-grep MCP references across package metadata and generated scaffolding now reflect the supported official server path

---

Breaking Changes

None.

This is a patch release focused on aligning generated Copilot assets, worker guidance, and MCP packaging with the currently supported workflow. Existing Hive repositories should regenerate their .github/* artifacts to pick up the new Copilot contract.

---

Upgrade Notes

npm install opencode-hive@1.4.4   # or: bun add opencode-hive@1.4.4

• Regenerate Copilot / VS Code artifacts from the updated release so the plan.md-only review contract and refreshed agent metadata land in your repository
• If your repo still relies on older generated guidance around context/overview.md, web/fetch, or worktree/merge-heavy Copilot instructions, follow the new plan.md-first workflow instead
• If you use the generated MCP templates for structural search, adopt the official ast-grep MCP server path from the updated package/templates

---

Philosophy Alignment

This release sharpens four of Hive's core principles:

P2 (Plan → Approve → Execute): The Copilot path now points at one required review/execution document instead of splitting human review across extra required surfaces.

P3 (Human Shapes, Agent Builds): The generated Copilot surface is simpler and more honest: the human reviews plan.md, the agent executes, and optional notes stay optional.

P8 (Cross-Model Prompts): Generated agents, prompts, skills, and instructions now describe the same workflow and tool surface instead of diverging by surface or artifact age.

P9 (Deterministic Contracts Beat Soft Memory): Agent frontmatter, curated tool lists, committed artifact parity tests, and official MCP references make the Copilot path a tested contract instead of a set of conventions users have to rediscover.

See the PHILOSOPHY.md § v1.4.4 evolution note for the full rationale.

---

Verification Coverage

• node --test release-artifacts.test.mjs — verifies versioned manifests, lockfile markers, release notes, and changelog ordering for 1.4.4
• node --test release-workflow.test.mjs — verifies the release workflow still enforces the expected rehearsal, publish, and release-note handling rules
• cd packages/vscode-hive && bun test src/generators/agents.test.ts src/generators/committedArtifactsParity.test.ts src/__tests__/generators.test.ts src/commands/initNest.test.ts — verifies the generator and committed Copilot artifacts stay aligned for the shipped agent contract

v1.4.3

Release v1.4.3

Compare: v1.4.2...v1.4.3

---

Highlights

1 · Copilot askQuestions parity lands in the shipped artifact surface (PR #82)

v1.4.3 carries forward the merged askQuestions parity work so the generated Copilot / VS Code artifacts stay aligned with Hive's current execution model instead of lagging behind it.

Why it matters: Agent Hive's OpenCode-first direction only works if adjacent operator-facing artifacts tell the same story. This patch keeps the Copilot-facing generated prompts and supporting material aligned with the actual Hive workflow, reducing drift between what users read, what the generated artifacts ask for, and what the runtime really supports.

2 · Release rehearsal and selective recovery are now explicit, tested operator paths

This release also ships the release-hardening work that makes the publication path safer:

• release:check enforces both the release artifact contract and the release workflow contract
• the npm publish access verification now lives in a checked-in helper script instead of inline workflow shell
• docs/RELEASING.md now documents rehearsal-before-tagging and tag-backed selective recovery for partially finished releases

Why it matters: Release recovery used to be something operators had to reconstruct from workflow YAML and memory. v1.4.3 makes the supported path explicit before the next failure happens.

---

What Changed

Added

• Operator-facing release guidance for selective recovery after a partial tagged release, including target-specific reruns for npm, VS Code Marketplace, and GitHub Release publishing
• A dedicated docs/releases/v1.4.3.md release body that the GitHub Actions release workflow can publish directly from the matching tag

Changed

• Version-bearing manifests now consistently report 1.4.3, including the root workspace, all packages, and packages/opencode-hive/plugin.json
• Tracked workspace version markers in package-lock.json and bun.lock are refreshed to 1.4.3
• CHANGELOG.md now records both the merged Copilot askQuestions parity work (PR #82) and the release workflow / recovery hardening that ships alongside it
• PHILOSOPHY.md now adds a v1.4.3 evolution note connecting parity and release recovery to the core principles

Fixed

• Release prep no longer leaves lockfiles advertising older workspace versions than the manifests they accompany
• Operator-facing release guidance now matches the real workflow gates: manual runs rehearse only, tag pushes publish, and recovery is limited to existing tags plus explicit target toggles

---

Breaking Changes

None.

This is a patch release focused on alignment and release safety. No .hive data model changes or new required operator migrations are introduced.

---

Upgrade Notes

npm install opencode-hive@1.4.3   # or: bun add opencode-hive@1.4.3

• If you consume generated Copilot / VS Code artifacts, regenerate them from the updated release so the askQuestions parity improvements land in your repo
• Before cutting future tags, follow the documented preflight in docs/RELEASING.md: credential checks, bun run release:check, then a workflow_dispatch rehearsal
• If a tagged release partially fails, recover from the existing tag only and enable only the unfinished targets

---

Philosophy Alignment

This release sharpens three of Hive's core principles:

P7 (Iron Laws + Hard Gates): Release safety now depends less on operator memory and more on checked-in contracts. The workflow contract is tested, the release artifact contract is tested, and the docs describe the same bounded recovery path the workflow enforces.

P8 (Cross-Model Prompts): The askQuestions parity work keeps generated Copilot-facing artifacts aligned with Hive's actual planning/execution model instead of letting one surface drift into a different user experience.

P9 (Deterministic Contracts Beat Soft Memory): Selective recovery is now an explicit contract — tag-backed, opt-in, and target-specific — rather than an oral tradition about how to rerun a broken release.

See the PHILOSOPHY.md § v1.4.3 evolution note for the full rationale.

---

Verification Coverage

• node --test release-artifacts.test.mjs — verifies versioned manifests, lockfile markers, release notes, and changelog ordering for 1.4.3
• node --test release-workflow.test.mjs — verifies rehearsal/recovery workflow gates and required release-note handling
• git diff -- package-lock.json bun.lock — reviewed to confirm the lockfile refresh remains limited to expected workspace version-marker updates

v1.4.2 — Honest Contracts: Project-Local Config, Bounded Helper, Copilot VS Code Preview

Highlights

1 · Project-Local Config at .hive/agent-hive.json (PR #77)

Agent Hive now has an explicit, documented config resolution chain:

Priority	Path
1 (highest)	<project>/.hive/agent-hive.json — new preferred project config
2	<project>/.opencode/agent_hive.json — legacy fallback during migration
3	~/.config/opencode/agent_hive.json — global fallback

Teams with multiple repos can now set per-repo sandbox mode, model overrides, and skill exclusions without touching the global config. An invalid project config emits a [hive:config] warning and falls back to global defaults instead of silently using stale state.

2 · hive-helper Is Now a Bounded Hard-Task Operational Assistant (PR #79)

Formalises three bounded modes — merge recovery, state clarification, and safe append-only manual follow-up — while keeping the tool boundary exact (hive_merge, hive_status, hive_context_write only). DAG-changing requests still route back to Hive/Swarm for plan amendment.

New: helperStatus in hive_status() — machine-readable interrupted wrap-up state:

{
  "helperStatus": {
    "doneTasksWithLiveWorktrees": [...],
    "dirtyWorktrees": [...],
    "nonInProgressTasksWithWorktrees": [...],
    "manualTaskPolicy": { "order": {...}, "dependsOn": {...} },
    "ambiguityFlags": [...]
  }
}

Also: OpenCode runtime contract trimmed to verifiable surfaces, plugin.json regenerated, and an integrated issue #72 (3b/3c) regression added to the test suite.

3 · GitHub Copilot Restored as a VS Code Desktop Preview Path (PR #80)

v1.4.0 correctly identified OpenCode as the first-class runtime. VS Code desktop was over-cut. The LM tool registration is back and the generated artifacts are modernised:

• copilot-instructions.md — concise repository-wide steering complementing AGENTS.md
• .github/prompts/*.prompt.md — reusable planning, execution, review-request, and verification entry points
• Guidance leans on Copilot's built-in browser tools, MCP, and Playwright

OpenCode remains first-class. VS Code desktop is a supported preview for teams not yet ready to commit full-time.

---

Upgrade

npm install opencode-hive@1.4.2
# or
bun add opencode-hive@1.4.2

No configuration changes are required to keep existing behaviour. To use project-local config, create <project>/.hive/agent-hive.json with your per-repo overrides.

---

Verification

Package	Tests
hive-core	237 pass, 0 fail
opencode-hive	457 pass, 0 fail
vscode-hive	69 pass, 0 fail

bun run build — all three packages build cleanly.

---

Philosophy

All three threads answer the same meta-question: Does the code match the contract?

• Config resolution had a hidden fallback chain → now explicit and tested
• The helper role had undocumented modes → now a documented bounded contract
• VS Code support was listed as deprecated when it actually worked → now an honest preview path

See PHILOSOPHY.md § v1.4.2 and docs/releases/v1.4.2.md for full details.

---

Full Changelog: v1.4.1...v1.4.2

v1.4.0

Release v1.4.0

Compare: v1.3.6...v1.4.0

---

Highlights

Deterministic Hive Network Foundation (PR #75)

v1.4.0 adds the first deterministic cross-feature retrieval mechanism: NetworkService and the hive_network_query tool. Planning, orchestration, and review roles (Hive, Architect, Swarm, Hygienic) can now query prior feature history for deterministic, network-safe snippets with ordered JSON results. Scout, Forager, and hive-helper are explicitly excluded from network visibility.

Why it matters: Historical lookup is useful only when it is narrow, predictable, and subordinate to the live repository. v1.4.0 adds retrieval without turning Hive into a fuzzy memory system or an embeddings-first RAG product — live-file verification remains mandatory after every retrieval.

Clarified Context Model and Reserved Context Semantics (PR #75)

v1.4.0 makes Hive's memory model explicit and unambiguous:

• context/overview.md is the primary human-facing branch summary/history artifact
• plan.md remains execution truth for workers
• draft is planner-only scratch space, not user-facing documentation
• execution-decisions records orchestration history, not plan content
• AGENTS.md promotion is limited to durable context only

Why it matters: Hive works best when every artifact has one clear job. This release resolves ambiguity about which files humans review, which files workers execute against, and which context safely graduates into persistent agent memory.

Prompt Hardening: Evidence-Backed Delegation and Research Discipline (PR #74)

Using patterns from Claude's system prompt design, v1.4.0 sharpens Hive's prompt contracts across all five agent roles:

• Hive/Swarm must now synthesize concrete task packets before delegation — including file paths, line ranges, expected result, and what "done" looks like. Workers cannot inherit context from prior conversation turns.
• Scout gets a named read-only contract: local discovery first (glob, grep, read, ast_grep), structured lookups second, external sources as a last resort. No file edits, no state changes.
• Forager verification wording is command-first: workers report observed output, not narrative confidence. A conditional verification path covers new behavior vs. refactor-only work.
• Hygienic now distinguishes plan/document review from implementation verification, and can load verification-reviewer for falsification-first implementation checks.

Why it matters: The most expensive failure mode in multi-agent orchestration is a task that starts from ambiguity. PR #74 closes the gap between "directionally correct" prompt guidance and execution-grade precision.

Compaction-Safe Assignment Recovery Hardened (PR #73)

v1.4.0 extends the durable recovery foundation from v1.3.5/v1.3.6 with tighter assignment-recovery semantics:

• Context-window-sized discovery with conservative return-to-Hive guidance across all five agent roles and the parallel-exploration skill
• Primary/subagent directive recovery state tracking with one-attempt escalation before requesting human guidance
• Tighter compaction replay semantics: recovered sessions re-anchor to their exact role and task boundary rather than recovering into a generic assistant posture
• Custom Scout-derived session classification to handle subagent identity edge cases

Why it matters: Recovery after compaction works reliably only when the re-anchoring is bounded and deterministic. PR #73 adds the guardrails that prevent recovered sessions from over-recovering into broad investigation or incorrect roles.

OpenCode-First Support Policy Made Explicit

v1.4.0 makes the platform support posture honest and unambiguous:

• OpenCode is the first-class supported execution harness for Hive planning and orchestration
• vscode-hive remains supported as a review/sidebar companion — overview surfacing, approval UX, sidebar visibility, and task launching around the .hive/ workspace
• GitHub Copilot / VS Code language-model-tool support is no longer first-class from v1.4.0 onward — Copilot LM tool registrations and wiring removed from vscode-hive
• Existing .github/* bootstrap generation is retained for continuity, but it is continuity scaffolding rather than the recommended primary workflow

Why it matters: Issue #70 made the strategic direction clear. Maintaining two first-class execution paths degrades both. v1.4.0 names the winner explicitly so documentation, testing, and development effort can concentrate on the right surface.

---

What Changed

New: deterministic cross-feature retrieval (PR #75)

• Added packages/hive-core/src/services/networkService.ts — queries prior features for network-safe snippets with deterministic ordering and explicit JSON output
• Added hive_network_query to the OpenCode plugin with structured JSON results (query, currentFeature, snippet results)
• Limited network access to Hive, Architect, Swarm, and Hygienic roles
• Forager, Scout, and hive-helper remain network-blind to preserve their execution-scoped isolation

Changed: context model roles are now explicit and enforceable (PR #75)

• context/overview.md is reserved as the primary human-facing summary/history — workers do not execute against it
• plan.md is the execution contract — workers read this, not overview
• draft and execution-decisions are now reserved names with documented semantics in both the Hive prompt and AGENTS.md
• AGENTS.md sync via hive_agents_md is limited to durable free-form context files

Changed: prompt delegation contracts hardened (PR #74)

• Hive and Swarm: added mandatory synthesis step before any delegation — must name files, line ranges, expected result, and done criteria
• Scout: added explicit read-only contract with preferred search sequence (local → structured → external → shell as narrow fallback)
• Forager: replaced narrative verification guidance with command-first, evidence-backed verification contract; added conditional path for refactor-only vs. new-behavior work
• Hygienic: added explicit implementation-verification routing via verification-reviewer skill for falsification-first implementation checks
• Updated packages/opencode-hive/src/agents/hive.ts, swarm.ts, scout.ts, forager.ts, hygienic.ts
• Added packages/opencode-hive/skills/verification-reviewer/SKILL.md
• Updated packages/opencode-hive/src/utils/worker-prompt.ts with command-first verification wording

Changed: compaction replay semantics tightened (PR #73)

• Primary/subagent sessions now track directive recovery state and escalate to human guidance after one recovery attempt instead of re-recovering indefinitely
• Context-window-sized discovery ceiling enforced across Hive, Architect, Swarm, Scout, and parallel-exploration skill
• Compaction replay for all roles now re-anchors to the stored role and task assignment deterministically

Changed: vscode-hive demoted to companion role (PR #75)

• Removed Copilot LM tool registration and agent wiring from packages/vscode-hive/src/extension.ts and packages/vscode-hive/src/tools/
• Updated packages/vscode-hive/README.md to reflect companion-first scope and OpenCode-first primary workflow
• vscode-hive remains fully functional as a review/sidebar companion — the change is scope clarification, not feature removal

Fixed: helper and runtime boundary drift (PR #75)

• hive-helper remains merge-only and network-blind even with Hive Network added elsewhere
• Historical context overreach addressed: Hive Network and AGENTS.md sync respect network-safe and durable-only boundaries

---

Breaking Changes

None at the feature-directory or data-model level. Existing .hive/ nests continue to work without a manual migration.

The only behavioral change that could affect existing users is the removal of GitHub Copilot LM tool wiring from vscode-hive. If you were using Copilot as the Hive execution harness, move to OpenCode before upgrading.

---

Support Policy

Harness	Status in v1.4.0
OpenCode	✅ First-class — planning, execution, all Hive tools
vscode-hive	✅ Companion — review/sidebar, overview, approvals, task launch
GitHub Copilot LM Tools	❌ No longer first-class from v1.4.0 onward
.github/* bootstrap	⚠️ Retained for continuity, not recommended for new setups

---

Upgrade Notes

1. From v1.3.x: No migration required. Existing .hive/ feature directories, plans, tasks, and context files are all compatible.
2. Copilot users: Move day-to-day Hive execution to OpenCode. Keep vscode-hive installed for sidebar visibility, overview review, and approval UX.
3. Context model: Treat context/overview.md as your branch summary/history. Keep plan.md as execution truth. Use draft only for planner scratch work; use execution-decisions only for orchestration history.
4. Hive Network: Treat hive_network_query results as historical leads. Always verify against live repository files before acting on retrieved snippets.
5. Delegation quality: Ensure orchestrator task dispatches include file paths and done criteria — PR #74 makes this a formal contract, and workers will behave more reliably when the task packet is complete.

---

Stats

• PRs merged: #73 (compaction recovery), #74 (prompt hardening), #75 (context model + Hive Network)
• New capabilities: hive_network_query, NetworkService, verification-reviewer skill
• Roles affected by prompt changes: Hive, Architect, Swarm, Scout, Forager, Hygienic (all six)
• Tests: 723 pass across hive-core (220), opencode-hive (445), vscode-hive (58) — verified on the pre-merge branch; full build + test verification confirmed clean

---

Installation

Install the VS Code companion extension from the attach...

v1.3.6

Release v1.3.6

Compare: v1.3.5...v1.3.6

---

Highlights

Bounded Task-Worker Replay After Compaction (PR #67)

v1.3.6 hardens the compaction-recovery foundation introduced in v1.3.5. PR #67 adds worker-specific post-compaction replay for task workers, so a resumed Forager is re-bound to the exact current task instead of merely recovering a generic worker identity. The replay text now tells the worker to resume only that task, not merge, not start the next task, and re-read the original worker-prompt.md before continuing from the existing worktree state.

Why it matters: v1.3.5 made durable recovery possible; v1.3.6 makes task-worker recovery narrower and safer. The highest-cost failure mode after compaction was not losing all context, but resuming with just enough context to drift into the wrong goal. PR #67 closes that gap.

DAG-Aware Review Follow-up and Manual Tasks (PR #69)

PR #69 makes review follow-up routing explicit. Hive and Swarm now distinguish between inline fixes, isolated manual tasks, and true plan amendments that change downstream sequencing. Manual tasks are no longer second-class follow-up notes: they now support structured metadata, richer generated specs, explicit dependsOn, and clearer worker prompts.

Why it matters: Review feedback often reveals real work that should be tracked, not buried in ad-hoc prose. v1.3.6 gives that work first-class DAG semantics, so agents can add follow-up tasks without accidentally smuggling in hidden sequential dependencies.

Refresh Pending Plan Tasks Without Rewriting History

PR #69 also adds hive_tasks_sync({ refreshPending: true }), which refreshes pending tasks from the latest approved plan while preserving manual tasks and anything that already has execution history.

Why it matters: Plan amendments should safely rewrite the future, not erase the past. This gives orchestrators a clean way to update pending work after review-driven plan changes without destroying evidence of what has already happened.

---

What Changed

New: worker-specific synthetic replay for compacted task workers

• Re-bound resumed task workers to the exact feature/task assignment stored in durable session metadata
• Replayed an explicit bounded resume contract that says to resume only the current task
• Pointed recovered workers back to the original worker-prompt.md path before further tool use

New: structured manual-task metadata and specs

• Added richer manual-task metadata so ad-hoc follow-up work can record goal, description, acceptance criteria, files, references, and origin
• Generated structured spec.md content for manual tasks instead of relying on thin placeholder text
• Kept manual tasks as first-class execution units rather than informal orchestration side notes

Changed: review follow-up is now routed by scope

• Distinguished local inline fixes from isolated manual-task work and true plan amendments
• Kept cross-task dependency changes behind the plan-amendment path instead of allowing review-sourced manual tasks to invent DAG edges implicitly
• Surfaced the routing guidance in orchestrator prompts and execution skills so the follow-up path matches the scope of the feedback

Changed: pending-task refresh is DAG-aware

• Added refreshPending support to hive_tasks_sync()
• Rewrote pending plan tasks from the latest plan, including dependsOn, titles, and generated specs
• Preserved manual tasks and tasks with execution history instead of flattening everything back to a fresh sync

Fixed: post-compaction worker drift and dependency ambiguity

• Reduced the chance that a recovered worker resumes as a generic assistant instead of a task-bound executor
• Removed more of the hidden “folder order equals dependency order” behavior from manual follow-up work
• Hardened the line between recovery, execution, and orchestration so compaction and review handling stay deterministic

---

Breaking Changes

None. v1.3.6 is a patch release on top of v1.3.5 that tightens worker recovery boundaries and makes review follow-up / manual-task DAG behavior more explicit without requiring a migration.

---

Upgrade Notes

• Upgrade from v1.3.5 to v1.3.6 to pick up PR #67’s bounded task-worker replay after compaction.
• If your workflows rely on review-created follow-up work, adopt PR #69’s explicit dependsOn and refreshPending semantics instead of assuming numeric task order encodes dependencies.
• Treat v1.3.5 as the durable recovery base and v1.3.6 as the follow-up hardening pass that narrows recovery behavior and clarifies DAG-aware execution.
• Existing feature directories do not need a manual migration, but operators should expect manual tasks and plan refresh behavior to preserve execution history more deliberately.

---

Stats

• Primary features: PR #67 — “Follow up task-worker compaction recovery”; PR #69 — “Make Plan & Review Follow-up DAG-aware and Harden Manual Tasks”
• User-facing scope: bounded worker replay, explicit follow-up routing, structured manual-task metadata/specs, explicit dependsOn, and hive_tasks_sync({ refreshPending: true })
• Verification coverage: compaction-anchor and runtime smoke coverage for worker replay, plus task-service / plugin regression coverage for manual-task metadata, DAG semantics, and pending-task refresh

v1.3.5

Release v1.3.5

Compare: v1.3.4...v1.3.5

---

Highlights

Durable Recovery After OpenCode Compaction (PR #64)

v1.3.5 brings the PR #64 session-recovery model from main into the 1.3.x release line. Hive now persists durable session identity in .hive/sessions.json, classifies each recovered session as primary, subagent, task-worker, or unknown, and uses compact re-anchor payloads so resumed sessions recover the right role boundaries without replaying full prompts.

Why it matters: OpenCode compaction no longer has to guess which kind of Hive session is resuming. Primary agents come back with the right planning/orchestration constraints, subagents recover their delegated role cleanly, and task workers resume with the assignment they were already executing.

Task Workers Recover from the Original Assignment

PR #64 also hardens task-worker recovery specifically. When a worker session resumes after compaction, Hive binds recovery metadata from durable worktree context and the original worker-prompt.md launch contract before the first tool call, so the recovered worker stays attached to the correct feature/task assignment.

Why it matters: This reduces a high-cost failure mode where a compacted worker could lose assignment context and resume like a generic assistant instead of a task-specific executor.

Main-Branch Release History Is Now Complete

This release note intentionally separates two stories: the carried-forward v1.3.4 history repair and the new PR #64 product work on main. v1.3.4 already documented the missing PR #62 release-branch history; v1.3.5 is the first release note on main that adds new user-facing behavior beyond that historical repair.

Why it matters: Users reading the 1.3.x series from main can now distinguish between the history-repair release (v1.3.4) and the new compaction-recovery functionality (v1.3.5).

---

What Changed

New: durable session tracking and classification

• Persisted global session identity in .hive/sessions.json
• Classified recovered sessions as primary, subagent, task-worker, or unknown
• Mirrored feature-bound session data into feature-local session files so recovery can resolve role and scope before later task binding

New: compact re-anchors for each recovery path

• Added dedicated recovery anchors for primary agents, subagents, task workers, and unknown sessions
• Restored role constraints through output.prompt and output.context instead of depending on OpenCode prompt preservation
• Kept worker-specific recovery scoped to task-worker sessions instead of replaying generic planner instructions everywhere

Fixed: worker recovery after compaction

• Recovered task-worker context from durable worktree metadata before the first Hive tool call
• Preserved the @path / worker-prompt.md task launch contract during resume
• Locked global session writes so resumed workers do not lose assignment state during recovery

Fixed: directive replay for resumed sessions

• Persisted original directives for primary and subagent sessions
• Marked compacted sessions for one-shot recovery
• Replayed the stored directive on the first resumed turn so assignment context and role metadata are restored together

Docs and tests

• Added root README and plugin README guidance covering recovery after OpenCode compaction
• Added regression coverage for session persistence, compaction hooks, plugin smoke behavior, variant-hook recovery, and the new compaction-anchor utilities
• Preserved anti-loop safeguards by keeping recovery anchors away from broad rediscovery behavior such as hive_status, hive_plan_read, or full-codebase exploration

---

Breaking Changes

None. v1.3.5 is a patch release on top of v1.3.4 that hardens session recovery and release documentation without requiring a new project structure or migration.

---

Upgrade Notes

• Upgrade from v1.3.4 to v1.3.5 to pick up PR #64’s durable recovery after OpenCode compaction.
• If you are reading release history on main, treat v1.3.4 as the carried-forward PR #62 history correction and v1.3.5 as the new compaction-recovery release.
• Existing .hive/ feature directories do not need manual migration, but recovery behavior now depends on the durable session records written by the updated runtime.
• If you operate long-lived worker sessions, expect resumed workers to recover from worker-prompt.md and durable worktree metadata rather than from best-effort prompt memory alone.

---

Stats

• Primary feature: PR #64 — “Harden Hive recovery after OpenCode compaction”
• User-facing recovery scope: durable .hive/sessions.json, session classification, compact re-anchors, directive replay, and task-worker recovery from worker-prompt.md
• Verification coverage: session-service tests, compaction-hook regression coverage, plugin/runtime smoke checks, variant-hook recovery tests, and compaction-anchor unit tests

v1.3.4

Release v1.3.4

What Changed

Documented: PR #62 user-facing scope

• Recorded the reserved context/overview.md workflow as the human-facing review/history artifact
• Reaffirmed that plan.md remains the execution truth for workers and generated task specs
• Called out document-aware review handling so plan and overview feedback remain distinct in approval flows

Documented: overview-first product surfaces

• Described overview-first status and sidebar surfacing for humans
• Noted indexed feature-folder storage and the .hive/active-feature pointer as part of the PR #62 release story
• Preserved the prompt, planner, and orchestrator guidance updates tied to the overview-first workflow

---

Breaking Changes

None. v1.3.4 is a corrective patch release on top of v1.3.3 focused on history correction, documentation alignment, and release-note honesty.

---

Upgrade Notes

• Upgrade from v1.3.3 to v1.3.4 if you want the 1.3.x patch line to carry the corrected PR #62 release history.
• If you reviewed earlier v1.3.2 notes, use the corrected v1.3.2 record together with this v1.3.4 note as the accurate PR #62 timeline.
• Continue using context/overview.md for human-facing review/history and plan.md for worker execution.

---

Stats

• Correction scope: PR #62 / 488aa29, changelog and historical release-note alignment, no source conflict resolution
• Release philosophy called out explicitly: overview as human-facing artifact, plan.md as execution truth, document-aware review, overview-first status/sidebar surfacing, and worker execution context purity
• Technical basis: release-branch history differs, but the shipped 1.3.x tree already matches the PR #62 tree