// Discipline for developing Hive itself — PR sizing, review handling, merge discipline, release workflow, delegation, and cleanup hygiene. Use this skill when working on Hive repo changes that span multiple PRs or review cycles.
| name | hive-maintainer |
| description | Discipline for developing Hive itself — PR sizing, review handling, merge discipline, release workflow, delegation, and cleanup hygiene. Use this skill when working on Hive repo changes that span multiple PRs or review cycles. |
Use this skill when you are developing Hive itself, not just using it. It covers the discipline needed for changes that span multiple PRs, subagents, review cycles, or release gates.
main releasable at all timesBefore substantial work:
make workspace-status
hive doctor --json
uv sync --extra dev
If you are in a fresh maintainer worktree, do the uv sync --extra dev step before
running pytest or make check. The focused maintainer/docs suites need the
dev-only test dependencies.
Classify current work into:
Prefer the smallest slice that removes a real blocker.
When current state, docs, skills, and memory disagree, trust them in this order:
Do not stall on tiny cleanup once the next real blocker is known. Do not keep adding unrelated work to an already-mergeable PR.
Prefer one subsystem or one risk cluster per PR.
Warning signs that a PR is too large:
When that happens:
"Literal green" means:
make check)After merging, watch the push CI run on main. A red merge commit is new blocking work immediately, even if the PR checks were green.
Before requesting review:
make check for broad slicesAfter requesting review:
eyes reaction alone is not completionWhen review lands, classify each finding:
| Classification | Action |
|---|---|
| Confirmed bug | Must-fix before merge |
| Missing test / truthfulness gap | Must-fix before merge |
| False alarm disproven by current code | Respond with evidence, non-blocking |
| Valid follow-up but non-blocking | Track as debt, do not block merge |
Rules:
For a deterministic local fallback: claude -p "/review <pr-number>" works well when the GitHub-managed review is delayed.
Delegate when the task is concrete, independent, and non-blocking for your next step.
Good delegation targets:
Keep local ownership for:
Every delegated task should include:
After delegation:
make bump-version BUMP=patch|minor|major updates pyproject.toml and src/hive/common.py automatically. You must also update manually:
docs/V2_3_STATUS.md, docs/V2_4_STATUS.md, or docs/V2_5_STATUS.md — update the active release ledger for the line you are cutting. Keep shipped lines as compact historical ledgers, and keep the current draft or active line aligned with its status doc before you call the release ready.tests/test_maintainer_surfaces.py — the test_v23_status_doc_tracks_release_gates_and_next_blocker test asserts the current version string in the status doc. Update the assertion and add one for the new version in the release history.uv.lock — run uv sync or uv lock after the pyproject.toml bump so the lockfile stays in sync (or let uv run do it implicitly).make check # lint + tests (must pass before commit)
make release-check # build, validate, smoke-test artifacts
git add pyproject.toml src/hive/common.py docs/V2_4_STATUS.md tests/test_maintainer_surfaces.py uv.lock
git commit -m "chore: bump version to X.Y.Z"
git tag vX.Y.Z
git push && git push --tags
uv publish does not read ~/.pypirc. Use twine, which does:
uv build # creates dist/mellona_hive-X.Y.Z.*
uv run twine upload dist/mellona_hive-X.Y.Z* # reads ~/.pypirc [pypi] token
Alternatively, pass the token directly: UV_PUBLISH_TOKEN=pypi-... uv publish.
The make publish target wraps twine but has an interactive confirmation prompt and refuses to run in CI.
After PyPI publish, create a GitHub release with the built artifacts:
gh release create vX.Y.Z dist/mellona_hive-X.Y.Z* \
--title "vX.Y.Z" \
--notes "release notes here"
main — a red merge commit is immediate blocking work.uv tool install 'mellona-hive[console]' (allow CDN propagation time).docs/V2_5_STATUS.md for the active v2.5 draft line, docs/V2_4_STATUS.md for the shipped v2.4 line, and docs/V2_3_STATUS.md for the shipped v2.3 line.After every merge, push, or major handoff, capture:
main head if relevantKeep this compact enough to survive a long session or context compaction.
Periodically check for:
git status --short
git worktree list
pgrep -fl "codex_app_server_worker.py|claude_sdk_worker.py|agent_dispatcher|hive "
Watch for:
.hive/events/*.jsonl noiseClean generated artifacts promptly so they do not masquerade as intentional work.
Before you stop or hand off:
Coordinate work across multiple agents and projects in Hive. Covers task claims, blockers, handoffs, campaigns, portfolio management, briefs, and shared memory.
Hive mental model and orientation. Read this first before using any other Hive skill. Covers the entity hierarchy, observe-and-steer pattern, drivers, sandboxes, console vs CLI, and workspace conventions.
Use the Hive MCP server for the thin v2 search and execute tool surface. Use this skill when configuring MCP access to Hive or when an agent needs workspace search and bounded local execution.
Set up and configure Hive workspaces, projects, tasks, and evaluator policy. Use this skill when bootstrapping, creating projects, managing tasks, or configuring PROGRAM.md.
The core agent work cycle in Hive — from finding a task through claiming, launching a run, handling approvals, finishing, and promoting. Use this skill for task-first project work, governed runs, and clean handoff.