hive-lite 0.1.0

package/docs/skills/hive-lite-map-maintainer/references/repair-rules.md

@@ -0,0 +1,201 @@
+# Project Map Repair Rules
+
+Project Map is not a wiki. It is a safe edit permit and evidence-policy source.
+
+Only add fields that help:
+
+- `find` answer where to read, what to edit, what not to touch, validation, and risk.
+- `check` answer what evidence is needed to accept a change.
+
+## Area Shape
+
+Prefer focused product/work areas:
+
+```text
+dashboard.action_inbox
+change.evidence_policy
+cli.map_health
+project_map.delta_review
+```
+
+Avoid generic one-part areas:
+
+```text
+dashboard
+frontend
+server
+components
+src
+utils
+```
+
+## Scope Tiers
+
+Use tiered scope:
+
+```yaml
+scope:
+  readable:
+    - apps/dashboard/src/**
+  writable_direct:
+    - apps/dashboard/src/pages/InboxPage.vue
+  writable_conditional:
+    - pattern: apps/dashboard/src/api/client.ts
+      reason: only if API shape changes
+      requires_review: true
+  writable_broad_fallback:
+    - pattern: apps/dashboard/src/**
+      reason: fallback only when direct files are insufficient
+      requires_review: true
+  forbidden:
+    - apps/dashboard/dist/**
+```
+
+Rules:
+
+- `readable` may be broad.
+- `writable_direct` should be exact existing files, usually 2-8 files.
+- Broad patterns such as `apps/*/src/**`, `packages/**`, `server/**`, and `**` must not be in `writable_direct`.
+- Every conditional/fallback item needs `reason` and `requires_review: true`.
+
+## Entrypoint Roles
+
+Use only these roles:
+
+```text
+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:
+
+```yaml
+entrypoints:
+  - path: apps/dashboard/src/pages/InboxPage.vue
+    role: page
+    label: Dashboard Action Inbox page
+    source: manual
+    confidence: high
+```
+
+If uncertain:
+
+```yaml
+role: unknown
+source: agent_draft
+confidence: low
+todo: Confirm this file's durable role before using it as a strong evidence signal.
+```
+
+Do not invent role names.
+
+## Verification Policy
+
+Add a minimal area verification policy:
+
+```yaml
+verification:
+  direct_manual_allowed: true
+  manual_profiles:
+    - manual-verification
+  focused_test_recommended_for_roles:
+    - grouping_logic
+    - data_transform
+    - error_handling
+    - cli_behavior
+  focused_test_required_for_roles: []
+  review_with_reason_allowed: true
+  risk_acceptance_allowed: false
+```
+
+Guidance:
+
+- UI/page/styles/docs areas usually allow direct manual verification.
+- Internal logic/data/schema/cache/error/CLI behavior usually recommends focused tests or a review reason.
+- Keep `focused_test_required_for_roles` empty unless the area is clearly high risk.
+- Do not make risk acceptance a normal path.
+
+## Validation Profiles
+
+Reference only profiles that exist in `.hive/map/validation.yaml`.
+
+Command profile example:
+
+```yaml
+profiles:
+  - id: dashboard-build
+    type: command
+    command: bun --cwd apps/dashboard build
+    evidence_type: build
+    covers_roles:
+      - page
+      - ui_component
+      - styles
+    safety: safe_auto
+```
+
+Manual profile example:
+
+```yaml
+profiles:
+  - id: generic-ui-visual
+    type: manual
+    evidence_type: manual_visual
+    instructions:
+      - Open the affected UI.
+      - Confirm the requested visible behavior is correct.
+      - Confirm no obvious visual regression.
+    covers_roles:
+      - page
+      - ui_component
+      - styles
+    safety: manual_only
+```
+
+If a profile is plausible but unconfirmed, leave a TODO instead of referencing it as active.
+
+## What Not To Add
+
+Do not add:
+
+- full code graph
+- endpoint catalog
+- function-level documentation
+- every component
+- test coverage analysis
+- agent summaries as facts
+- validation commands not backed by repo scripts or explicit files
+- broad writable permits for convenience
+
+## Git Ignore Boundary
+
+Hive Lite Project Map files are durable and should be versioned:
+
+```text
+.hive/config.yaml
+.hive/map/**
+```
+
+Runtime evidence should be ignored:
+
+```text
+.hive/context/
+.hive/changes/
+.hive/patches/
+.hive/state/
+```
+
+Do not blanket-ignore `.hive/`. If `.hive/map/*.yaml` is ignored by `.gitignore` or `.git/info/exclude`, tell the user because map refresh changes may not show in `git status` or be committed.

package/docs/skills/hive-lite-start-prompt/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: hive-lite-start-prompt
+description: Use this skill when a user gives a coding requirement, screenshot, or rough product request and wants Hive Lite to produce a safe, high-quality start prompt for a coding agent. It calibrates user input into a textual find intent, runs Hive Lite status/find/map-health/map-prompt loops, repairs only Project Map YAML when needed, and stops after returning an edit-ready Context Packet prompt rather than changing application code.
+---
+
+# Hive Lite Start Prompt
+
+## Purpose
+
+Turn a natural-language or visual requirement into an edit-ready Hive Lite Context Packet and a concise prompt for a separate coding agent.
+
+This is a pre-work skill. It may refine `.hive/map/*.yaml` so Hive Lite can route the requirement safely, but it must not implement the requested product/code change.
+
+## References
+
+- For screenshots, rough wording, `findIntent`, and `mapRepairFocus`, read [input-calibration.md](references/input-calibration.md).
+- When `hive-lite status --json` is not clean, read [preflight.md](references/preflight.md) and stop for user confirmation.
+- For standalone map lifecycle work, large map refreshes, or repeated find-gap repair failures, hand off to `$hive-lite-map-maintainer` instead of expanding this start flow. Do not assume this skill can invoke another skill automatically; output a clear handoff prompt for the user.
+
+## Skill Handoffs
+
+Do not assume this skill can invoke another skill automatically. Handoffs are text for the user to run explicitly.
+
+- To map maintenance: output a `$hive-lite-map-maintainer` prompt and stop.
+- To finish work after coding: include `$hive-lite-finish` in the final instructions, but do not run finish actions here.
+
+If the target handoff skill is unavailable in the active agent CLI, tell the user to install or sync Hive Lite skills for their agent first. Hive Lite cannot detect the running agent by itself; use the user's agent target such as `codex`, `claude`, or `gemini`:
+
+```bash
+hive-lite skills doctor --agent <codex|claude|gemini>
+hive-lite skills install --agent <codex|claude|gemini>
+```
+
+## Boundaries
+
+- Do not edit application source, tests, docs, `.gitignore`, generated artifacts, `.hive/context`, `.hive/changes`, or `.hive/deltas`.
+- Only edit these Project Map files when map repair is needed: `.hive/map/project.yaml`, `.hive/map/areas.yaml`, `.hive/map/rules.yaml`, `.hive/map/validation.yaml`.
+- Do not run `hive check`, `hive validate`, `hive accept`, commits, formatters, or app tests for the new requirement. Those belong after the coding agent changes code.
+- During preflight, you may help finish or isolate pre-existing work only after explicit user confirmation.
+- Never discard changes with destructive commands such as `git reset --hard`, `git checkout --`, or forced branch switches.
+- Do not call an LLM API from Hive Lite. If a map gap exists, use `hive map prompt --from-find` as the repair brief and edit the map directly as the current agent.
+
+## Find The CLI
+
+Run Hive Lite from the target repo root. Prefer the package command:
+
+```bash
+hive-lite <args>
+```
+
+If `hive-lite` is not available, try an explicit path already given by the user or conversation context, such as `node /path/to/hive-lite/bin/hive.js <args>`. Do not spend a long time searching the target repo; ask for the Hive Lite CLI path if it is not obvious.
+
+In command examples below, replace `hive-lite` with the resolved command.
+
+## Workflow
+
+### 1. Establish Target And Calibrate Input
+
+Identify the target repo root, original user requirement, and any screenshot/visual evidence.
+
+Read [input-calibration.md](references/input-calibration.md). Produce:
+
+- `originalRequirement`: the user's request preserved for the final prompt.
+- `findIntent`: clear text to pass to `hive-lite find`.
+- `mapRepairFocus`: map-oriented focus to use only if map repair is needed.
+
+### 2. Preflight The Worktree
+
+If `.hive/map/project.yaml`, `.hive/map/areas.yaml`, `.hive/map/rules.yaml`, or `.hive/map/validation.yaml` is missing, run:
+
+```bash
+hive-lite init
+```
+
+Do this automatically; do not ask the user whether to initialize Hive Lite. Initialization is setup work, not the requested product change.
+
+Run:
+
+```bash
+hive-lite status --json
+```
+
+If status reports `hive.state = repo_setup_required`, stop immediately. Do not run `hive-lite init` and do not initialize git automatically. Tell the user to switch to the correct git repo root, or manually initialize git and create an initial commit before using Hive Lite.
+
+If the command is unavailable in an older Hive Lite, fall back to `git status --porcelain`.
+
+Continue only when `canStartNewRequirement` is true or fallback git status is clean. If not clean, read [preflight.md](references/preflight.md), present options, and stop immediately unless the user had already explicitly chosen an option before this step.
+
+After any preflight action, rerun `hive-lite status --json`; continue only when the target worktree is clean.
+
+### 3. Verify The Existing Map
+
+Run:
+
+```bash
+hive-lite map verify
+```
+
+If YAML is invalid or required map files are missing, repair only `.hive/map/*.yaml` if the fix is obvious. Otherwise stop and report the blocker.
+
+### 4. Run Find As Data
+
+Run:
+
+```bash
+hive-lite find "<findIntent>" --json
+```
+
+Use JSON for decisions. Important fields: `id`, `mode`, `area.id`, `writableScope`, `scope`, `doNotTouch`, `validationPlan`, `warnings`, `reviewGated`, `recommendedActions`, and `explain`.
+
+Use `--explain` only when human-readable debugging is useful.
+
+### 5. Decide Whether The Packet Is Ready
+
+If `mode` is `needs_decomposition`, stop immediately. Do not output a `Coding Agent Prompt`.
+
+Explain that the requirement cannot safely become one Context Packet / one Change Record. Use `decompositionSignals` and `candidatePhaseSeeds` from the JSON to present a split plan:
+
+```text
+This requirement is too broad for one Hive Lite change.
+
+Why:
+- <decomposition signal>
+
+Suggested phases:
+1. <area id / phase hint>
+   Continue with:
+   $hive-lite-start-prompt
+   Continue split <split_id> with phase <phase_id>.
+   Use this find intent: "<candidatePhaseSeeds[n].findIntent>"
+   Evidence: <candidatePhaseSeeds[n].evidenceClasses / validationProfiles>
+2. ...
+
+Please choose one phase to start, then rerun this skill with that phase.
+```
+
+Do not create durable Feature/Task objects. Do not edit code. Do not merge candidate areas into a wider prompt.
+
+If the JSON includes `splitNote`, mention its markdown path. Treat it as a local context artifact, not a task list. When the user explicitly invokes this skill for a chosen phase, rerun find with the phase source:
+
+```bash
+hive-lite find "<phase.findIntent>" --from-split <split_id> --phase <phase_id> --area <phase.primaryAreaId> --json
+```
+
+Continue only if that phase-specific find returns `edit_context`.
+
+If the phase-specific JSON includes `phaseDependencyStatus.canStartNormally: false`, do not output a coding prompt. If `splitFound` or `phaseFound` is false, explain that the copied split command is not an edit permit and recommend finding the current split note with `hive-lite status --json` or rerunning the original broad find command. Otherwise explain the missing required phases and recommend the next dependency phase. If the user says "continue split" or "resume the large requirement", use `hive-lite status --json` and its `recentSplitNotes` to find ready phases, then output a phase-specific `$hive-lite-start-prompt` handoff or continue only if the user explicitly asked this active skill to proceed with that phase.
+
+Accept the packet only when all are true:
+
+- `mode` is `edit_context`.
+- `area.id` is present.
+- `writableScope` contains at least one narrow direct file.
+- `validationPlan` is not empty.
+- `warnings` has no map-gap warning such as `NO_CONFIDENT_AREA`, `MISSING_DIRECT_WRITABLE_SCOPE`, `MISSING_ENTRYPOINT`, or `MISSING_VALIDATION`.
+- `hive-lite map health --area <areaId> --json` reports no critical findings.
+
+Review-gated conditional or broad fallback scope is allowed. Include it in the final prompt as a boundary, not as a failure.
+
+### 6. Repair Map Gaps
+
+If the packet is not ready, run:
+
+```bash
+hive-lite map prompt --focus "<mapRepairFocus>" --from-find <ctx_id>
+```
+
+Use the generated prompt as the map repair brief. Edit only the allowed `.hive/map/*.yaml` files.
+
+Repair principles:
+
+- Prefer focused product/work area ids such as `dashboard.action_inbox`, not one-part ids such as `dashboard`.
+- Preserve unrelated areas exactly unless a change is needed for the reported map gap.
+- Use `scope.writable_direct` for exact files the coding agent may edit.
+- Put conditional files under `scope.writable_conditional` with `reason` and `requires_review: true`.
+- Put broad patterns only under `scope.writable_broad_fallback` with `reason` and `requires_review: true`.
+- Never put broad patterns such as `apps/*/src/**`, `packages/**`, `server/**`, or `**` in `writable_direct`.
+- Do not invent paths. Verify paths with `rg --files` or `git ls-files`.
+- Use only validation profile ids that exist in `.hive/map/validation.yaml`, or update `validation.yaml` to define profiles from confirmed repo scripts.
+- Mark uncertainty with TODO comments rather than guessing.
+
+After each repair, run:
+
+```bash
+hive-lite map verify
+hive-lite map health --area <area_id> --json
+hive-lite find "<findIntent>" --json
+```
+
+Repeat at most two repair cycles. If the packet still is not edit-ready, stop and return the blocker, current context id, findings, and recommended next command.
+
+If map files were changed during repair, stop before producing a coding prompt unless the worktree has been returned to clean. Ask the user to commit the map refinement, stash it, or use a separate worktree; then rerun this skill.
+
+If the repair requires broad map refresh beyond the selected area, stop and hand off to `$hive-lite-map-maintainer`:
+
+```text
+This map repair is broader than the start flow should handle.
+
+Run:
+
+$hive-lite-map-maintainer
+Repair the Hive Lite Project Map for this start-flow gap.
+Context packet: <ctx_id>
+Find intent: "<findIntent>"
+Map repair focus: "<mapRepairFocus>"
+Current blocker: <warnings or health findings>
+Only edit .hive/map/*.yaml. Do not edit application code.
+```
+
+Do not continue to generate a Coding Agent Prompt until the map maintainer flow has completed and the user reruns this start skill.
+
+If `needs_decomposition` persists after the user selects a smaller phase, ask the user to narrow the phase goal further instead of generating a coding prompt.
+
+### 7. Return The Start Prompt
+
+When ready, return two clearly separated sections:
+
+- `Preparation Summary`: for the human only. Include preflight actions, commits made before start, whether `.hive/map/*.yaml` changed, and the Context Packet id.
+- `Coding Agent Prompt`: the only text the user should pass to the coding agent.
+
+Do not include preparation/provenance notes inside `Coding Agent Prompt`.
+
+```text
+Ready to start.
+
+Preparation Summary:
+- Preflight: clean
+- Pre-existing work handled: <none or commit/stash/worktree summary>
+- Map files changed while preparing this prompt: <none or list>
+- Context Packet: <relative .hive/context/ctx_xxx.md>
+
+Coding Agent Prompt:
+Context Packet:
+<relative .hive/context/ctx_xxx.md>
+
+Requirement:
+<originalRequirement>
+
+Use this context packet as your source of truth. Edit only Direct Writable files.
+
+Direct Writable:
+- <file>
+
+Review-Gated:
+- <conditional/broad item and reason>
+
+Do Not Touch:
+- <forbidden item>
+
+Validation To Expect:
+- <command or manual check>
+
+Verification Guidance:
+- If the change is directly manually verifiable, provide exact manual verification steps.
+- If the change is not directly manually verifiable and changes behavior, provide focused automated verification when practical.
+- Prefer a small existing or new focused test over broad unrelated tests.
+- Do not add broad, brittle, or low-value tests only for process.
+- If focused automated verification is impractical, explain why and provide a concise review rationale.
+- Do not weaken or delete validation, CI, or existing tests.
+
+Hive Check After Editing:
+- <resolved hive command> check --context <ctx_id>
+
+Read <relative .hive/context/ctx_xxx.md>.
+Modify only the Direct Writable files listed there.
+If the fix requires a Review-Gated file, stop and explain why it is needed before editing it.
+Do not touch Do Not Touch paths.
+After editing, summarize changed files and tell the human to run:
+  <resolved hive command> check --context <ctx_id>
+
+Then the human can use `$hive-lite-finish` to drive check, validation, manual evidence, and acceptance.
+
+If the human later reports that business/manual verification failed, revise under this same Context Packet instead of expanding scope or treating it as a new requirement. Use the human's failure observation as the repair target, keep the same Direct Writable / Review-Gated / Do Not Touch boundaries, and again tell the human to rerun:
+  <resolved hive command> check --context <ctx_id>
+```
+
+Preparation details such as commits made, stashes created, worktree setup, map files changed, or "no map files changed" are for `Preparation Summary` only. Do not list `hive-lite check --context ...` under validation commands; it is the change-control step after the coding agent edits files.
+
+## Failure Output
+
+If no edit-ready prompt can be produced, return the context packet id, current mode, selected area if any, blocking warnings or health critical findings, exact next command, and whether `.hive/map/*.yaml` files were changed.
+
+Do not pretend the agent can safely start coding when the packet is `discovery_context` or `needs_map`.

package/docs/skills/hive-lite-start-prompt/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hive Lite Start Prompt"
+  short_description: "Prepare safe Hive Lite coding prompts"
+  default_prompt: "Use $hive-lite-start-prompt to prepare a safe coding-agent start prompt for this requirement."

package/docs/skills/hive-lite-start-prompt/references/input-calibration.md

@@ -0,0 +1,82 @@
+# Input Calibration
+
+Use this reference before running `hive-lite find`.
+
+Hive Lite only receives text. The agent using this skill is responsible for converting user intent, screenshots, UI observations, and rough wording into precise text.
+
+## Build Three Texts
+
+Keep these separate:
+
+- `originalRequirement`: the user's actual request, preserved for the final coding prompt.
+- `findIntent`: a concise requirement for `hive-lite find`.
+- `mapRepairFocus`: a Project Map repair focus for `hive-lite map prompt --focus` if `find` reports a gap.
+
+## Find Intent
+
+`findIntent` should describe what needs to change in product/work terms.
+
+Good:
+
+```text
+Dashboard Action Inbox should display Feature as the parent item and expandable Tasks underneath, instead of showing Feature and Task as peer categories.
+```
+
+Avoid:
+
+```text
+Fix the thing in the screenshot.
+```
+
+Include stable nouns users and map areas may know:
+
+- product surface or page,
+- workflow,
+- visible UI object,
+- expected behavior,
+- current wrong behavior when known.
+
+Do not overfit to file paths unless the user explicitly names a file.
+
+## Image Or Screenshot Inputs
+
+If the user includes an image or screenshot:
+
+1. Inspect the image yourself.
+2. Extract visible product surface, labels, states, layout issue, and user expectation.
+3. Rewrite it into `findIntent`.
+4. Do not pass image references or file paths to Hive Lite; Hive Lite only receives text.
+5. Mention in the final prompt that the requirement was derived from visual input if that helps the coding agent.
+
+Example:
+
+```text
+User text: "这里层级不对"
+Image: Action Inbox screenshot where Feature and Task are separate sections.
+
+findIntent:
+Dashboard Action Inbox should show Feature cards as parent rows with expandable child Tasks, rather than separate Feature and Task sections.
+```
+
+## Map Repair Focus
+
+Use `mapRepairFocus` only when `find` returns `discovery_context`, `needs_map`, or map-gap warnings.
+
+It should be more map-oriented than `findIntent`. Include:
+
+- selected or likely area id,
+- product/work surface,
+- missing map quality such as entrypoints, direct writable scope, validation, or aliases,
+- likely durable files from `find` output or repo evidence.
+
+Example:
+
+```text
+dashboard.action_inbox map repair: feature-task hierarchy UI, InboxPage.vue and InboxItemCard.vue entrypoints, direct writable scope for inbox layout components, dashboard validation profile.
+```
+
+Do not simply reuse the user's raw sentence when the map gap is about routing quality.
+
+## Final Prompt
+
+The final coding prompt should use `originalRequirement` for human meaning, plus the verified Context Packet and direct writable scope from Hive Lite.

package/docs/skills/hive-lite-start-prompt/references/preflight.md

@@ -0,0 +1,116 @@
+# Preflight Worktree Handling
+
+Use this reference when `hive-lite status --json` is not clean.
+
+The goal is to protect the Change Record boundary. A new Hive Lite requirement must start from a clean worktree.
+
+## After Automatic Init
+
+If the worktree is dirty only because this skill just ran `hive-lite init`, explain that Hive Lite was initialized automatically and stop before starting the product requirement.
+
+Present options:
+
+```text
+Hive Lite has been initialized for this repo. The setup files need a git boundary before a product requirement can start.
+
+Options:
+1. Commit the Hive Lite setup files.
+2. Stash the setup files.
+3. Create a separate git worktree for the product requirement.
+4. Stop.
+```
+
+Do not ask whether to run init; init has already been performed. Do ask before committing, stashing, or creating a worktree.
+
+## States
+
+### repo_setup_required
+
+Meaning: the current directory is not inside a git worktree.
+
+Stop immediately. Do not run `hive-lite init`, `hive-lite find`, `git init`, `git add`, or `git commit`.
+
+Say:
+
+```text
+Hive Lite requires a git repository before it can safely create Context Packets or Change Records.
+
+Please switch to the correct git repo root, or manually initialize git and create an initial commit before using Hive Lite.
+```
+
+### clean
+
+Continue to `map verify` and `find`.
+
+### unmanaged_dirty
+
+Meaning: dirty files are not tied to a Hive Change Record.
+
+Stop and present options:
+
+```text
+The worktree has unmanaged dirty changes, so I cannot safely start a new Hive Lite requirement.
+
+Options:
+1. Commit the current changes.
+2. Stash the current changes.
+3. Create a separate git worktree for the new requirement.
+4. Stop.
+```
+
+Only run a command after the user explicitly chooses an option and provides any required commit message, stash message, or branch/worktree name.
+
+### in_progress
+
+Meaning: an unfinished Hive Change Record exists.
+
+Stop and present options:
+
+```text
+There is an in-progress Hive Change Record: <chg_id>.
+
+Options:
+1. Refresh/check the current change if the diff changed.
+2. Run Hive validation.
+3. Accept and commit the current change.
+4. Create a separate git worktree for the new requirement.
+5. Stop.
+```
+
+Use the status JSON's latest change id. If `currentDiffMatchesLatestChange` is false, recommend refreshing with:
+
+```bash
+hive-lite check <chg_id>
+```
+
+### accepted_uncommitted
+
+Meaning: the latest Hive Change Record was accepted, but no commit was created.
+
+Stop and present options:
+
+```text
+The latest Hive change was accepted but not committed: <chg_id>.
+
+Options:
+1. Commit the accepted Hive change.
+2. Create a separate git worktree for the new requirement.
+3. Stop.
+```
+
+Prefer:
+
+```bash
+hive-lite accept <chg_id> --commit -m "<message>"
+```
+
+## Safety Rules
+
+- Do not continue to `find` while status is not clean.
+- Do not initialize git automatically.
+- Do not assume "new branch" cleans the worktree; dirty files usually follow branch switches.
+- Prefer commit, stash, or separate git worktree.
+- Do not run destructive cleanup commands.
+- Do not decide commit messages silently. Ask for a message or propose one and wait for confirmation.
+- If the user chooses a separate worktree, create it only after they provide or approve the path and branch name.
+- After any action, rerun `hive-lite status --json`; continue only if `canStartNewRequirement` is true in the target worktree.