Hive Lite

Hive Lite is a local Project Map + Change Control CLI for coding agents.

It deliberately starts small:

• no server
• no Dashboard
• no Feature or Task objects
• no agent runner
• no embeddings
• no SQLite

The first loop is:

intent -> hive-lite find -> Context Packet
agent edits code outside Hive
current diff -> hive-lite check -> Change Record
validate -> accept -> optional Map Delta Candidate

Commands

For detailed CLI output meanings and "what to do next" tables, see docs/cli-semantics.md. For a non-technical pilot-user workflow guide in Chinese, see docs/user-pilot-guide.zh.md. For using $hive-lite-discovery to turn vague ideas into Start Intent Handoffs, see docs/hive-lite-discovery-usage.zh.md.

Examples below use node bin/hive.js from this repository. When installed as a package, use hive-lite instead.

Setup And Health

Initialize Hive Lite in a git repo:

node bin/hive.js init

Creates durable map files under .hive/map/ and runtime directories such as .hive/context/ and .hive/changes/. This command requires an existing git repository.

Check basic map file validity:

node bin/hive.js doctor
node bin/hive.js map verify
node bin/hive.js map verify --json

Inspect Project Map readiness for safe find / check behavior:

node bin/hive.js map health
node bin/hive.js map health --area dashboard.action_inbox
node bin/hive.js map health --json

Current State And Next Action

Inspect worktree state, latest Hive change, and recent split notes:

node bin/hive.js status
node bin/hive.js status --json
node bin/hive.js status --all --json

Ask Hive Lite what the operator should do next:

node bin/hive.js next
node bin/hive.js next --json
node bin/hive.js next --agent codex --json

status and next show actionable split notes by default: active split notes with accepted phase progress, or the newest unstarted split note when no active split exists. Use status --all to inspect every runtime split note. next may recommend start, finish, map maintenance, split continuation, dirty-worktree cleanup, or git repo setup. It does not run agents, commit, accept risk, or modify files. In JSON output, splitNoteSummary.primaryRecentSplitNote identifies the split note that status/next treat as primary, and splitNoteSummary.otherActiveSplitNotes lists older active split notes with accepted progress.

When you pass next --agent <codex|claude|gemini> or next --path <skills-dir>, next also checks whether the recommended Hive Lite operator skill is current in that target. If it is missing or stale, next recommends skills sync before the handoff.

Sync Agent Skills

Hive Lite ships five bundled skills for discovery and operator workflows:

• hive-lite-bootstrap
• hive-lite-discovery
• hive-lite-start-prompt
• hive-lite-finish
• hive-lite-map-maintainer

Check installed skill status:

node bin/hive.js skills doctor
node bin/hive.js skills doctor --agent codex
node bin/hive.js skills doctor --path ~/.codex/skills
node bin/hive.js skills doctor --json

skills doctor does not detect which agent CLI is installed or currently running. It checks the selected skills directories: all known target paths by default, one or more paths with --agent, or a custom path with --path.

Codex, Claude, and Gemini targets are global user-skill installs. --agent codex writes to ~/.codex/skills, --agent claude writes to ~/.claude/skills, and --agent gemini writes to ~/.gemini/skills. They do not create or update repo-local .codex/skills, .claude/skills, or .gemini/skills. Use --path <repo-local-skills-dir> only when you intentionally want a custom repo-local copy that Hive Lite can inspect.

Install or update skills in one step:

node bin/hive.js skills sync --agent codex
node bin/hive.js skills sync --agent claude
node bin/hive.js skills sync --agent gemini
node bin/hive.js skills sync --agent all

sync installs missing skills and overwrites stale copies with the bundled version.

install is still available for conservative installs that should not overwrite stale local copies unless --force is passed:

node bin/hive.js skills install --agent codex
node bin/hive.js skills install --agent all

Use --dry-run to preview writes. Use --path <skills-dir> for a custom target.

Start A Requirement

Generate a Context Packet from a user intent:

node bin/hive.js find "Dashboard Action Inbox content should align left" --explain
node bin/hive.js find "Dashboard Action Inbox content should align left" --json
node bin/hive.js find "Dashboard Action Inbox content should align left" --area dashboard.action_inbox
node bin/hive.js find "Dashboard Action Inbox content should align left" --max-files 12

Possible modes:

• edit_context: safe to hand the packet to a coding agent
• discovery_context: useful for investigation, but not an edit permit
• needs_map: Project Map does not support this intent yet
• needs_decomposition: intent is too broad for one Context Packet / Change Record

For decomposed work, continue a specific phase:

node bin/hive.js find "Update server API for Action Inbox hierarchy" --from-split split_xxx --phase phase_server_api --area server.action_inbox_api --json

When --from-split and --phase point to a recorded split phase, Hive Lite constrains routing to that phase's primary area. Generated split notes include --area <primaryAreaId> so copied commands stay narrowly scoped even if the original intent was broad. If the split note or phase cannot be found, Hive Lite does not treat the copied command as an edit permit. If --area disagrees with the recorded phase area, the recorded phase area wins and Hive Lite prints a warning. When Hive Lite is run from a source checkout, generated split notes may render the caller's current CLI invocation and include hive-lite as a package-alias fallback when available.

Check And Validate A Change

After a coding agent edits files, create or refresh a Change Record from the current diff:

node bin/hive.js check --context ctx_xxx
node bin/hive.js check --context ctx_xxx --json
node bin/hive.js check chg_xxx

Run the validation plan recorded on the Change Record:

node bin/hive.js validate chg_xxx
node bin/hive.js validate chg_xxx --profile dashboard-build
node bin/hive.js validate chg_xxx --cmd "npm test"

Record human/manual evidence:

node bin/hive.js validate chg_xxx \
  --manual manual-verification \
  --result passed \
  --note "Opened the Dashboard and verified the Action Inbox layout."

Manual --result values are passed, failed, or not_applicable. Manual notes should say what was actually checked.

Accept A Change

Accept after evidence is sufficient:

node bin/hive.js accept chg_xxx
node bin/hive.js accept chg_xxx --commit -m "Left align Action Inbox content"

Accept with a human review reason when Hive Lite requires one:

node bin/hive.js accept chg_xxx --reviewed --reason "Reviewed internal behavior; automated validation passed."

Accept explicit risk only when the human knowingly accepts insufficient evidence:

node bin/hive.js accept chg_xxx --accept-risk --reason "No focused test exists yet; accepting low-risk isolated UI logic after review."

blocked changes cannot be accepted in the MVP.

Maintain The Project Map

Generate a prompt for map bootstrap, refresh, or intent-triggered repair:

node bin/hive.js map health --area dashboard.action_inbox
node bin/hive.js map prompt --focus "Dashboard Action Inbox" --from-find ctx_xxx
node bin/hive.js map prompt --focus "Dashboard surfaces" --max-areas 8
node bin/hive.js map prompt --from-find ctx_xxx --json

Inspect and apply durable map delta candidates produced by accepted changes:

node bin/hive.js map delta list
node bin/hive.js map delta apply delta_xxx
node bin/hive.js map delta reject delta_xxx --reason "One-off change; not durable map knowledge."

Debug / Inspection

Show a raw Change Record:

node bin/hive.js show-change chg_xxx
node bin/hive.js show-change

Dump the loaded Project Map as JSON:

node bin/hive.js map-dump

Local Data

Hive Lite requires a git repository. If the current directory is not inside a git worktree, status and next will report repo_setup_required, and workflow commands such as init, find, check, validate, and accept stop. Hive Lite does not initialize git automatically; switch to the correct repo root or manually initialize git and create an initial commit first.

Inside a git repo, status reports hive_init_required until required Hive Lite setup files exist. status and next recommend $hive-lite-bootstrap, which is the first-time setup and setup-repair skill that may run init, build the first Project Map, and prepare the setup/map commit before product work starts.

Committed by default:

.hive/config.yaml
.hive/map/**

Ignored by default:

.hive/context/**
.hive/changes/**
.hive/patches/**
.hive/state/**

Do not blanket-ignore .hive/. If .hive/map/*.yaml is hidden by .gitignore or .git/info/exclude, map refreshes will not show up as normal git changes. Ignore only runtime evidence directories, not the durable Project Map.

Next Action

next is a lightweight local state interpreter. It does not run an agent, change files, accept risk, commit, or manage a workflow. It reads git state plus Hive artifacts and suggests the next operator step:

node bin/hive.js next
node bin/hive.js next --json

Typical phaseGuess values:

• repo_setup_required: current directory is not inside a git repo
• hive_init_required: use $hive-lite-bootstrap for first-time setup or setup repair before product work
• preflight: dirty worktree must be committed, stashed, isolated, or stopped before a new requirement
• finish: an in-progress or accepted-uncommitted Hive change should be closed with $hive-lite-finish
• map: Project Map needs bootstrap, refresh, or repair via $hive-lite-map-maintainer
• split_continue: a recent split note has a ready remaining phase; continue through $hive-lite-start-prompt
• start: safe to begin a new bounded requirement with $hive-lite-start-prompt

This is the CLI layer that a future static report or companion UI should read first.

Core Objects

Worktree Boundary

Hive Lite does not require a new branch for every requirement, but a new requirement should start from a clean working tree.

Use status before generating a start prompt:

node bin/hive.js status
node bin/hive.js status --json

It classifies the current repo as:

• repo_setup_required: not inside a git worktree
• hive_init_required: git repo exists, but required Hive Lite setup files are missing
• clean: safe to start a new find
• unmanaged_dirty: dirty files are not tied to a Hive Change Record
• in_progress: dirty files belong to an unfinished Hive Change Record
• accepted_uncommitted: the latest Hive Change Record was accepted without a commit

For non-clean states, commit, stash, or move to a separate git worktree before starting a new requirement. This keeps check tied to one clear dirty diff.

Project Map

The durable context router under .hive/map.

map prompt prints a copyable prompt for an external agent CLI. It does not call an LLM and does not write map files. Its job is to help draft 3-8 high-value areas from repo evidence, then a human reviews and edits .hive/map/areas.yaml.

map health is a deterministic readiness check for the Project Map. It does not score the map or repair it. It checks whether areas have enough precise routing, writable scope, entrypoints, validation, verification policy, and boundaries for find to safely generate an edit_context and for check to explain evidence needs. An initialized repo with zero configured areas is needs_mapping, not healthy; it still needs $hive-lite-map-maintainer bootstrap work before real requirements can be routed safely.

node bin/hive.js map health
node bin/hive.js map health --area dashboard.action_inbox
node bin/hive.js map health --json

When find reports a map gap, pass the generated context packet back into map prompt:

node bin/hive.js map prompt --from-find ctx_xxx

The prompt will include the intent, selected area, warnings, relevant files, scope quality, and current scope so an external agent can propose a narrow map repair. For --from-find, an editing-capable external agent is instructed to edit only .hive/map/project.yaml, .hive/map/areas.yaml, .hive/map/rules.yaml, and .hive/map/validation.yaml directly, then summarize the map changes. If it cannot edit files, it should fall back to complete replacement YAML for the affected map files.

Areas can use tiered scope:

scope:
  readable:
    - apps/dashboard/src/**
  writable_direct:
    - apps/dashboard/src/components/ActionInbox.tsx
  writable_conditional:
    - pattern: apps/dashboard/src/stores/**
      reason: only if grouping depends on store shape
      requires_review: true
  writable_broad_fallback:
    - pattern: apps/dashboard/src/**
      reason: fallback only
      requires_review: true
  forbidden:
    - apps/dashboard/dist/**

find uses this to choose a packet mode: edit_context, discovery_context, needs_map, or needs_decomposition. check treats direct files as clean, while conditional or broad fallback matches require review.

Areas should also give Hive Lite enough evidence-policy signal for the finish phase. Keep this small: roles and verification policy are not a code graph, they are just hints for whether a change is UI-visible, internal logic, CLI behavior, config, or unknown.

Canonical entrypoint roles:

page
ui_component
styles
state_store
grouping_logic
data_transform
api_contract
schema_logic
cli_behavior
error_handling
cache_logic
config
docs
test
unknown

Example:

entrypoints:
  - path: apps/dashboard/src/pages/InboxPage.vue
    role: page
    source: manual
    confidence: high
  - path: apps/dashboard/src/components/InboxItemCard.vue
    role: ui_component
    source: manual
    confidence: high

verification:
  direct_manual_allowed: true
  manual_profiles:
    - manual-verification
  focused_test_recommended_for_roles:
    - grouping_logic
    - data_transform
    - error_handling
  review_with_reason_allowed: true
  risk_acceptance_allowed: false

Validation profiles can add lightweight metadata so check can describe what kind of evidence a command provides:

profiles:
  - id: dashboard-build
    command: bun --cwd apps/dashboard build
    evidence_type: build
    covers_roles:
      - page
      - ui_component
      - styles
    safety: safe_auto

Context Packet

Generated by find. It tells an agent where to look, what it may edit, what not to touch, and how to validate.

Change Record

Generated by check. It captures the working tree diff, scope result, validation state, evidence policy, deterministic risk, and next action.

Evidence Policy

Hive Lite does not force every change to add tests. It asks whether evidence is sufficient for this change, or whether the human must record a reason.

check adds an Evidence Policy section with verdicts such as:

• acceptable: evidence is sufficient
• needs_validation: required command validation has not run
• needs_manual_verification: a directly verifiable change needs a manual evidence note
• needs_review_reason: accept requires --reviewed --reason "..."
• evidence_insufficient: add focused evidence when practical, or accept with an explicit reason/risk
• blocked: scope violation, failed validation, or another blocker

Manual evidence is recorded through validate:

node bin/hive.js validate chg_xxx \
  --manual dashboard-action-inbox-visual \
  --result passed \
  --note "Opened Dashboard and confirmed the Action Inbox hierarchy."

For internal changes that are not directly manually verifiable, prefer focused automated evidence when practical. If a focused test is not worth the cost, accept with a reason:

node bin/hive.js accept chg_xxx \
  --reviewed \
  --reason "Reviewed grouping logic; typecheck passed and the change is isolated to direct writable files."

MVP Cutline

Hive Lite does not write code in MVP. It helps a coding agent start in the right place and helps a human decide whether the resulting diff is acceptable.