hive-lite 0.1.2 → 0.1.3

package/README.md

@@ -78,8 +78,9 @@ When you pass `next --agent <codex|claude|gemini>` or `next --path <skills-dir>`
 
 ### Install Agent Skills
 
-Hive Lite ships three operator skills:
+Hive Lite ships four operator skills:
 
+- `hive-lite-bootstrap`
 - `hive-lite-start-prompt`
 - `hive-lite-finish`
 - `hive-lite-map-maintainer`
@@ -235,7 +236,7 @@ node bin/hive.js map-dump
 
 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` and `next` report `hive_init_required` until the repo has been initialized with `hive-lite init`. Hive Lite skills should stop in this state and ask the human/operator to run init explicitly before start, finish, or map-maintenance workflows continue.
+Inside a git repo, `status` reports `hive_init_required` until the repo has been initialized with `hive-lite init`. `next` recommends `$hive-lite-bootstrap`, which is the first-time setup skill that may run init, build the first Project Map, and prepare the setup/map commit before product work starts.
 
 Committed by default:
 
@@ -267,7 +268,7 @@ node bin/hive.js next --json
 Typical `phaseGuess` values:
 
 - `repo_setup_required`: current directory is not inside a git repo
-- `hive_init_required`: run `hive-lite init` explicitly before using Hive Lite skills
+- `hive_init_required`: use `$hive-lite-bootstrap` for first-time setup 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`

package/docs/cli-semantics.md

@@ -52,7 +52,7 @@ Hive Lite cannot detect the currently running agent CLI. If the caller provides
 | Value | Meaning | What To Do |
 | --- | --- | --- |
 | `repo_setup_required` | Current directory is not inside a git repo. | Stop. Switch to the correct repo root, or manually initialize git and create an initial commit before using Hive Lite. |
-| `hive_init_required` | Current git repo does not have required Hive Lite setup files. | Stop skill workflows. Run `hive-lite init` explicitly from the repo root, commit or preserve setup files, then rerun `next`. |
+| `hive_init_required` | Current git repo does not have required Hive Lite setup files. | Use `$hive-lite-bootstrap` for first-time setup before product work. |
 | `skill_preflight` | The selected agent target is missing the operator skill needed for the next Hive Lite step. | Run the recommended `skills install` or `skills sync`, then rerun `next`. |
 | `preflight` | Worktree has unmanaged dirty changes. | Stop before starting new work. Commit, stash, use a separate worktree, or stop. |
 | `finish` | A Hive change is in progress, or was accepted without commit. | Use `$hive-lite-finish` to check, validate, record evidence, accept, or commit. |
@@ -103,7 +103,7 @@ node bin/hive.js status --json
 | Value | Meaning | What To Do |
 | --- | --- | --- |
 | `repo_setup_required` | Not inside a git worktree. | Stop. Do not auto-run `git init`. |
-| `hive_init_required` | Inside a git worktree, but required Hive Lite setup files are missing. | Stop all skills. Run `hive-lite init` explicitly from the repo root. |
+| `hive_init_required` | Inside a git worktree, but required Hive Lite setup files are missing. | Stop ordinary start/finish/map-maintainer skills. Use `$hive-lite-bootstrap` for first-time setup, or run `hive-lite init` manually as the low-level fallback. |
 | `clean` | Worktree is clean. | It is safe to start `find`. |
 | `unmanaged_dirty` | Dirty files are not tied to a Hive Change Record. | Stop and ask the human to commit, stash, use a worktree, or stop. |
 | `in_progress` | Dirty files belong to an unfinished Hive Change Record. | Continue finish flow: `check`, `validate`, manual evidence, or `accept`. |
@@ -158,6 +158,7 @@ Hive Lite does not detect which agent CLI is installed or currently running. `sk
 
 Bundled skills:
 
+- `hive-lite-bootstrap`
 - `hive-lite-start-prompt`
 - `hive-lite-finish`
 - `hive-lite-map-maintainer`

package/docs/skills/hive-lite-bootstrap/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: hive-lite-bootstrap
+description: Use this skill when a git repository is adopting Hive Lite for the first time. It checks first-time setup state, may run `hive-lite init`, builds the first Project Map without changing product code, verifies readiness, and prepares a user-approved commit for Hive Lite setup and map files before any product requirement starts.
+---
+
+# Hive Lite Bootstrap
+
+## Purpose
+
+Onboard a git repository to Hive Lite for the first time:
+
+```text
+check repo -> run hive-lite init when needed -> build first Project Map -> verify -> commit setup/map after approval
+```
+
+This skill is the only Hive Lite operator skill that may run `hive-lite init`. Use it for first-time project setup, not for ordinary coding work.
+
+## Boundaries
+
+- Do not edit application source, tests, product docs, package files, secrets, CI, or generated artifacts.
+- You may run `hive-lite init` only when the target is already a git repo and the worktree was clean before init.
+- You may directly edit only:
+  - `.hive/map/project.yaml`
+  - `.hive/map/areas.yaml`
+  - `.hive/map/rules.yaml`
+  - `.hive/map/validation.yaml`
+- Preserve setup artifacts created by `hive-lite init`, including `.hive/config.yaml` and Hive Lite `.gitignore` runtime/evidence rules. Do not manually curate or remove them.
+- Do not start a product requirement, run `hive-lite find`, create a Change Record, accept risk, push, merge, deploy, or run app tests.
+- Commit only after explicit human approval, or when the user's request already explicitly asked you to commit the Hive Lite bootstrap.
+- If committing, include only Hive Lite setup/map files and the Hive Lite `.gitignore` change. Never include product-code changes.
+
+## Find The CLI
+
+Run Hive Lite from the target repo root. Prefer:
+
+```bash
+hive-lite <args>
+```
+
+If unavailable, use an explicit path already given by the user or conversation context, such as `node /path/to/hive-lite/bin/hive.js <args>`. Ask for the CLI path if it is not obvious.
+
+## Workflow
+
+### 1. Preflight
+
+Run:
+
+```bash
+hive-lite status --json
+git status --short
+```
+
+Stop if the directory is not a git repo. Tell the user to switch to the repo root, or initialize git and create an initial commit before using Hive Lite.
+
+Stop if `git status --short` shows pre-existing non-Hive changes. Ask the user to commit, stash, or use another worktree first. Do not run `hive-lite init` into a dirty product worktree.
+
+If Hive Lite is already initialized, do not rerun init. Continue only if the user asked to build or repair the first Project Map; otherwise explain that setup already exists and recommend `$hive-lite-map-maintainer` or `$hive-lite-start-prompt`.
+
+### 2. Initialize
+
+If status reports `hive.state = hive_init_required` or `hive.initialized = false`, run:
+
+```bash
+hive-lite init
+```
+
+Then continue in the same turn. Do not ask the user to commit yet; first build the initial Project Map.
+
+### 3. Build First Map
+
+Run:
+
+```bash
+hive-lite map verify --json
+hive-lite map prompt --focus "highest value product and workflow areas" --max-areas 8
+```
+
+Inspect the repo with deterministic commands such as:
+
+```bash
+rg --files
+rg "<routing term>"
+```
+
+Edit only `.hive/map/*.yaml`. Build 3-8 high-value, narrow areas that make near-term product requests routable. Do not try to map the whole project.
+
+### 4. Verify
+
+Run:
+
+```bash
+hive-lite map verify --json
+hive-lite map health --json
+```
+
+If areas were created, spot-check important areas with:
+
+```bash
+hive-lite map health --area <area_id> --json
+```
+
+Success means:
+
+- map verify is ok
+- the first useful areas have no critical health findings
+- the map is not empty
+- no product files were changed
+
+### 5. Commit Boundary
+
+Before any product requirement starts, the Hive Lite setup and initial Project Map should have a git commit boundary.
+
+If the user already explicitly asked to commit, and `git status --short` contains only Hive Lite setup/map files plus the Hive Lite `.gitignore` update, run:
+
+```bash
+git add .hive/config.yaml .hive/map/project.yaml .hive/map/areas.yaml .hive/map/rules.yaml .hive/map/validation.yaml .gitignore
+git commit -m "Initialize Hive Lite Project Map"
+```
+
+If the user did not explicitly approve committing, stop and ask for approval. Provide the exact command above and say that the user can reply with:
+
+```text
+可以提交。commit message 用：Initialize Hive Lite Project Map
+```
+
+Do not start `$hive-lite-start-prompt` until the setup/map files are committed or otherwise isolated.
+
+## Return Summary
+
+Return:
+
+```text
+Hive Lite bootstrap complete.
+
+Setup:
+- hive-lite init: <run / already initialized>
+
+Project Map:
+- changed files: <files>
+- areas created or updated: <area ids>
+
+Verification:
+- hive-lite map verify --json: <ok/fail>
+- hive-lite map health --json: <status and finding counts>
+
+Commit:
+- <committed / waiting for approval>
+- command or commit sha if applicable
+
+Next:
+- After the setup/map commit exists, start the first requirement with `$hive-lite-start-prompt`.
+```
+

package/docs/skills/hive-lite-bootstrap/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Hive Lite Bootstrap"
+  short_description: "Initialize Hive Lite for a repo"
+  default_prompt: "Use $hive-lite-bootstrap when this repository is adopting Hive Lite for the first time. Initialize Hive Lite, build the first Project Map, and prepare the setup/map commit before product work starts."
+
+policy:
+  allow_implicit_invocation: true

package/docs/skills/hive-lite-finish/SKILL.md

@@ -61,7 +61,7 @@ In command examples below, replace `hive-lite` with the resolved command.
 
 Run `hive-lite status --json` first. If it reports `hive.state = repo_setup_required`, stop immediately. Do not run check/validate/accept 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 it reports `hive.state = hive_init_required`, or `hive.initialized = false`, stop immediately. Do not run `hive-lite init` yourself, and do not run check/validate/accept. Tell the user to run `hive-lite init` from the repo root first. If they expected an existing Hive Lite change, they may be in the wrong directory.
+If it reports `hive.state = hive_init_required`, or `hive.initialized = false`, stop immediately. Do not run `hive-lite init` yourself, and do not run check/validate/accept. Recommend `$hive-lite-bootstrap` for first-time setup. If the user expected an existing Hive Lite change, they may be in the wrong directory.
 
 Find one of:
 
@@ -275,6 +275,20 @@ Accepted and committed.
 - Split next phase: <handoff prompt or none>
 ```
 
+If `Map Delta Candidate` is not `none`, do not apply it from this skill. Explain that the accepted change suggests a possible Project Map improvement and output this handoff:
+
+```text
+$hive-lite-map-maintainer
+请 review 这个 Map Delta Candidate：
+<delta_id>
+
+只判断是否 apply 或 reject 这个 map delta。
+不要改应用代码。
+不要开始新需求。
+```
+
+Tell the user that map delta review can happen before or after the next requirement, but reviewing it before similar future requests may improve routing.
+
 If no commit was created because the user explicitly asked not to commit, warn that a new Hive Lite requirement should not start until the worktree is clean.
 
 ## Response Style

package/docs/skills/hive-lite-map-maintainer/SKILL.md

@@ -35,7 +35,7 @@ hive-lite skills install --agent <codex|claude|gemini>
 Setup precondition:
 
 - This skill must not run `hive-lite init`.
-- If Hive Lite is not initialized or is partially initialized, stop immediately and tell the user to run `hive-lite init` from the target repo root, then rerun this skill.
+- If Hive Lite is not initialized or is partially initialized, stop immediately and recommend `$hive-lite-bootstrap` for first-time setup.
 - Do not create `.hive/map` manually, do not edit `.hive/config.yaml`, and do not edit `.gitignore`.
 
 Map-maintenance authority:
@@ -82,12 +82,15 @@ If it reports `hive.state = hive_init_required`, or `hive.initialized = false`,
 ```text
 Hive Lite is not initialized in this repo yet.
 
-Please run this once from the repo root:
-  hive-lite init
+Recommended next step:
+  $hive-lite-bootstrap
+  这是已有项目第一次接入 Hive Lite。请完成初始化，建立第一版 Project Map，不要改应用代码。
 
-Then commit or otherwise preserve the setup files, and rerun:
+If the bootstrap skill is not available, run `hive-lite init` from the repo root, then rerun:
   $hive-lite-map-maintainer
   这是已有项目第一次接入 Hive Lite。请建立第一版 Project Map，不要改应用代码。
+
+Do not commit immediately after init. Build the first Project Map first, then commit Hive Lite setup and map files together before starting the first product requirement.
 ```
 
 For older Hive Lite versions that do not report `hive.initialized`, check for required setup files before continuing:
@@ -125,7 +128,7 @@ Before any mode-specific work, check whether the target repo has the required Hi
 .hive/map/validation.yaml
 ```
 
-If any required map file is missing, stop immediately and tell the user to run `hive-lite init` from the repo root. Do not create missing map files manually.
+If any required map file is missing, stop immediately and recommend `$hive-lite-bootstrap`. Do not create missing map files manually.
 
 ### 3. Verify Current Map
 

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

@@ -8,8 +8,8 @@ Use when an existing project is adopting Hive Lite for the first time.
 
 Precondition:
 
-- `hive-lite init` has already been run explicitly by the user/operator.
-- If Hive Lite setup files are missing, stop and tell the user to run `hive-lite init`; do not run it from this skill.
+- Hive Lite setup already exists, normally because `$hive-lite-bootstrap` ran first.
+- If Hive Lite setup files are missing, stop and recommend `$hive-lite-bootstrap`; do not run `hive-lite init` from this skill.
 
 Goal:
 
@@ -101,7 +101,7 @@ Only apply a delta when the user explicitly asks or confirms. Reject stale or lo
 
 ## recovery
 
-Use when initialized map files are invalid YAML or structurally broken. If required Hive Lite setup or map files are missing, stop and tell the user to run `hive-lite init` from the repo root.
+Use when initialized map files are invalid YAML or structurally broken. If required Hive Lite setup or map files are missing, stop and recommend `$hive-lite-bootstrap`.
 
 Goal:
 

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

@@ -35,7 +35,7 @@ hive-lite skills install --agent <codex|claude|gemini>
 
 - Do not directly 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-lite init`. If Hive Lite is not initialized or is partially initialized, stop and tell the user to run `hive-lite init` from the repo root before using this skill.
+- Do not run `hive-lite init`. If Hive Lite is not initialized or is partially initialized, stop and recommend `$hive-lite-bootstrap` before using this skill.
 - 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.
@@ -80,12 +80,11 @@ If status reports `hive.state = hive_init_required`, or `hive.initialized = fals
 ```text
 Hive Lite is not initialized in this repo yet.
 
-Please run this once from the repo root:
-  hive-lite init
+Recommended next step:
+  $hive-lite-bootstrap
+  这是已有项目第一次接入 Hive Lite。请完成初始化，建立第一版 Project Map，不要改应用代码。
 
-After the setup files are committed or otherwise preserved, rerun:
-  $hive-lite-map-maintainer
-  这是已有项目第一次接入 Hive Lite。请建立第一版 Project Map，不要改应用代码。
+Do not start the product requirement yet. After bootstrap builds the first map, commit the Hive Lite setup and map files together, then rerun this start skill with the original requirement.
 ```
 
 For older Hive Lite versions that do not report `hive.initialized`, check whether these files exist before continuing:

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

@@ -13,12 +13,11 @@ Say:
 ```text
 Hive Lite is not initialized in this repo yet.
 
-Please run this once from the repo root:
-  hive-lite init
+Recommended next step:
+  $hive-lite-bootstrap
+  这是已有项目第一次接入 Hive Lite。请完成初始化，建立第一版 Project Map，不要改应用代码。
 
-After the setup files are committed or otherwise preserved, rerun:
-  $hive-lite-map-maintainer
-  这是已有项目第一次接入 Hive Lite。请建立第一版 Project Map，不要改应用代码。
+After bootstrap builds the first map, commit the Hive Lite setup and map files together before starting the product requirement.
 ```
 
 Do not continue to find/map repair/start prompt until Hive Lite setup exists.
@@ -108,7 +107,7 @@ hive-lite accept <chg_id> --commit -m "<message>"
 ## Safety Rules
 
 - Do not continue to `find` while status is not clean.
-- Do not run `hive-lite init` from a skill.
+- Do not run `hive-lite init` from this start skill; first-time setup belongs to `$hive-lite-bootstrap`.
 - 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hive-lite",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Local Project Map + Change Control for coding agents.",
   "keywords": [
     "codex",

package/src/cli.js

@@ -103,7 +103,7 @@ function requireHiveInitialized(cwd, commandName) {
     const missing = status.hive.missingSetupFiles && status.hive.missingSetupFiles.length > 0
       ? ` Missing: ${status.hive.missingSetupFiles.join(', ')}.`
       : '';
-    throw new Error(`${commandName} requires Hive Lite initialization. Run hive-lite init from the repo root first.${missing}`);
+    throw new Error(`${commandName} requires Hive Lite initialization. Use $hive-lite-bootstrap first, or run hive-lite init from the repo root as the low-level fallback.${missing}`);
   }
 }
 

package/src/lib/next.js

@@ -94,6 +94,13 @@ function startPrompt() {
   ].join('\n');
 }
 
+function bootstrapPrompt() {
+  return [
+    '$hive-lite-bootstrap',
+    '这是已有项目第一次接入 Hive Lite。请完成初始化，建立第一版 Project Map，不要改应用代码。完成后在开始第一个需求前准备 Hive Lite setup/map 提交。',
+  ].join('\n');
+}
+
 function finishPrompt(changeId) {
   return [
     '$hive-lite-finish',
@@ -137,6 +144,7 @@ function chooseSplit(status) {
 
 function requiredSkillForAction(actionItem) {
   if (!actionItem) return null;
+  if (actionItem.kind === 'run_bootstrap_skill') return 'hive-lite-bootstrap';
   if (actionItem.kind === 'run_start_skill' || actionItem.kind === 'continue_split') return 'hive-lite-start-prompt';
   if (actionItem.kind === 'run_finish_skill' || actionItem.kind === 'commit_accepted_change') return 'hive-lite-finish';
   if (actionItem.kind === 'run_map_maintainer') return 'hive-lite-map-maintainer';
@@ -227,13 +235,13 @@ function evaluateNextAction(cwd, options = {}) {
   } else if (workspace.hive.state === 'hive_init_required') {
     phaseGuess = 'hive_init_required';
     primaryAction = action({
-      kind: 'run_hive_init',
-      label: 'Run hive-lite init',
-      command: 'hive-lite init',
-      explanation: 'This git repository has not been initialized for Hive Lite. Run init explicitly before using Hive Lite skills.',
+      kind: 'run_bootstrap_skill',
+      label: 'Use hive-lite-bootstrap',
+      prompt: bootstrapPrompt(),
+      explanation: 'This git repository has not been initialized for Hive Lite. Use the bootstrap skill to initialize, build the first Project Map, and prepare the setup/map commit before product work starts.',
     });
-    summaryForHuman = '当前项目还没有初始化 Hive Lite。请先在项目根目录运行 hive-lite init，然后提交 setup/map 文件，再用 hive-lite-map-maintainer 建立 Project Map。';
-    summaryForAgent = 'Hive Lite is not initialized. Stop all skill workflows and tell the human to run hive-lite init first.';
+    summaryForHuman = '当前项目还没有初始化 Hive Lite。建议使用 hive-lite-bootstrap 完成首次接入：初始化、建立第一版 Project Map，并在开始第一个需求前准备 setup/map 提交。';
+    summaryForAgent = 'Hive Lite is not initialized. Stop ordinary start/finish/map-maintainer workflows and hand off to hive-lite-bootstrap.';
   } else if (!workspace.canStartNewRequirement) {
     if (workspace.hive.state === 'in_progress') {
       phaseGuess = 'finish';

package/src/lib/skills.js

@@ -4,6 +4,7 @@ const os = require('os');
 const path = require('path');
 
 const SKILL_NAMES = [
+  'hive-lite-bootstrap',
   'hive-lite-start-prompt',
   'hive-lite-finish',
   'hive-lite-map-maintainer',

package/src/lib/status.js

@@ -314,7 +314,7 @@ function evaluateWorkspaceStatus(cwd, options = {}) {
 
   if (!initialized) {
     state = 'hive_init_required';
-    reason = 'Hive Lite is not initialized in this git repository. Run hive-lite init before using Hive Lite skills.';
+    reason = 'Hive Lite is not initialized in this git repository. Use $hive-lite-bootstrap for first-time setup, or run hive-lite init as the low-level fallback.';
   } else if (dirty && latest.change) {
     if (accepted(latest.change) && !committed(latest.change) && diffMatches) {
       state = 'accepted_uncommitted';