@hagicode/cli 0.4.0 → 0.6.0

package/dist/cli.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("./chunks/main-CyDpMd__.js");s.runCli().then(e=>{e!==0&&(process.exitCode=e)}).catch(e=>{const n=e instanceof Error?e.stack??e.message:String(e);process.stderr.write(`${n}
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("./chunks/main-IYdi0hAA.js");s.runCli().then(e=>{e!==0&&(process.exitCode=e)}).catch(e=>{const n=e instanceof Error?e.stack??e.message:String(e);process.stderr.write(`${n}
 `),process.exitCode=s.EXIT_CODES.UNKNOWN});

package/dist/main.js

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./chunks/main-CyDpMd__.js");exports.createCliApp=e.createCliApp;exports.runCli=e.runCli;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./chunks/main-IYdi0hAA.js");exports.createCliApp=e.createCliApp;exports.runCli=e.runCli;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "HagiCode CLI for project, proposal, vault, chat, and AutoTask management.",
   "homepage": "https://github.com/HagiCode-org/cli#readme",
   "bugs": {
@@ -16,7 +16,9 @@
   "main": "./dist/main.js",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills",
+    "resources/saga"
   ],
   "packageManager": "pnpm@12.16.1",
   "engines": {
@@ -24,7 +26,7 @@
   },
   "scripts": {
     "clean": "rimraf dist",
-    "build": "export NODE_OPTIONS=\"${NODE_OPTIONS:-} --max-old-space-size=8192\"; pnpm run clean && vite build",
+    "build": "export NODE_OPTIONS=\"${NODE_OPTIONS:-} --max-old-space-size=8192\"; pnpm run clean && vite build && node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"",
     "dev": "tsx ./src/cli.ts",
     "generate:grpc": "node ./buildTools/generate-grpc.mjs",
     "generate:grpc:check": "node ./buildTools/generate-grpc.mjs --check",

package/resources/saga/.gitignore

@@ -0,0 +1 @@
+**/runtime/

package/resources/saga/manifest.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": 2,
+  "install": {
+    ".gitignore": "b43c8b58f191b9e0a0b54b6938c0aa4685d70b8f4ae2294c83a9ad6e728b7c0a"
+  },
+  "methods": {
+    "goal": "a545b01c9f6010df661f02cf62ef9bcae527ccf329f304ea82ffdda239b118df",
+    "research": "2504283ea845440c7909ff1da20bfb70f846d55ca16565740168848cfb8060b1",
+    "acceptance": "11ca06794d0ec19e87d1a4e883a67014563e9750b9fa62a8bedd43a69d52ca65",
+    "plan": "bcc4c0509f2971083775db2b3678f41c55f16e69deba2d994d3ed636f314d917",
+    "run": "aaf8a667c163afea0796a8c80d5760ee689923a76b0c7f1855e55405d9b0b5d0",
+    "amend": "be621d1221a85656851548aee1e9e9d78480288bd856baf1bdbf50cb3317f49b"
+  }
+}

package/resources/saga/prompts/acceptance.md

@@ -0,0 +1,15 @@
+# acceptance.md
+
+## Instruction
+Give every plan item one acceptance command. A separate verification worker runs it, so it must decide pass or fail by itself.
+
+- One heading per item: `## <ID> <name>`, followed by one line `cmd: <command>`.
+- The command runs from the project root (the folder that holds `.hagicode`), not from the saga root. Write `cd <dir> && ...` when it needs a subfolder. Exit code 0 means the item is done.
+- The command must be able to fail. A command that always passes proves nothing.
+- Every plan item has exactly one heading here, and every heading here is a plan item. If you change the command of an item that is already ticked, the next freeze reopens that item.
+
+## Template
+```
+## <ID> <name>
+cmd: <command to run from the project root>
+```

package/resources/saga/prompts/amend.md

@@ -0,0 +1,10 @@
+# Folding an amendment into a saga
+
+An amendment is a file under `<saga>/amendments/`. It is open while its `merged-in:` line is empty. Folding it in changes the planning artifacts only.
+
+1. `hagi saga status <saga> --path <root> --json` reports the current `revision` N (0 means the saga was never frozen). The merge target is `r<N+1>`.
+2. Read the amendment. Update `goal.md`, `research.md`, `acceptance.md` and `progress.md` so they agree with each other and with the amendment.
+3. Items may be added or superseded (`- ~ <ID> <name> | superseded in r<N+1>: <reason>`), never deleted. Do not touch the ticks: when an item's acceptance command changes, the next freeze reopens it.
+4. Do not decide new open questions yourself. List them under `## Open questions`.
+5. In the amendment file set `merged-in: r<N+1>`.
+6. Run `hagi saga check <saga> --phase plan --path <root>` and fix what it reports. Do not run `freeze`.

package/resources/saga/prompts/goal.md

@@ -0,0 +1,23 @@
+# goal.md
+
+## Instruction
+Write the goal contract of the saga: what it must achieve, in what scope, with which safety rules.
+
+- Every work item the saga will have must be checkable by a machine (a command that exits 0 when the item is done). Say so in the goal.
+- Write the non-goals and the block conditions (when an item is blocked instead of forced).
+- Do not write implementation details.
+- Write in the language the user used for the objective.
+- If `amendments/` holds files whose `merged-in:` line is empty, fold them in and set `merged-in: r<next revision>` in each file (see `prompts/amend.md`).
+
+## Template
+```
+## Goal
+
+## Scope
+
+## Non-goals
+
+## Safety rules
+
+## Block conditions
+```

package/resources/saga/prompts/plan.md

@@ -0,0 +1,16 @@
+# progress.md (the plan)
+
+## Instruction
+List the work items, one line each: `- [ ] <ID> <name> | `. The evidence path is added when an item is ticked.
+
+- Items are small enough to verify with one command, mostly independent, and ordered so that earlier items do not depend on later ones.
+- Keep the list short enough to review (roughly 3 to 15 items). Use the user's work items as a start; add or split items only when needed.
+- Do not add items for committing, pushing, opening a pull request, releasing or archiving: they are outside the contract.
+- IDs match the headings of `acceptance.md`.
+- In a revision an item may be added or superseded, never deleted. A superseded item is written without brackets: `- ~ <ID> <name> | superseded in r<N>: <reason>`.
+- Planning ends here. Do not run `freeze`, do not start the run, do not edit project code.
+
+## Template
+```
+- [ ] <ID> <name> | 
+```

package/resources/saga/prompts/research.md

@@ -0,0 +1,16 @@
+# research.md
+
+## Instruction
+Read the project and the references the user gave. Read only: change no project file.
+
+- Record what you found: the layout, the existing conventions, the commands that run the tests, anything the plan depends on.
+- List every decision you cannot make yourself under the heading `## Open questions` (the Chinese heading `## 待决问题` also works). One line per question, starting with `- `. Leave them undecided: a human answers them before the run by rewriting a line as `- [decided: <answer>] <question>` (or `- [已决定: <结论>] <问题>`).
+- If there is nothing to decide, write `- none` under that heading.
+- If an item has no honest verification command, say so here as an open question. Do not invent a check.
+
+## Template
+```
+## Findings
+
+## Open questions
+```

package/resources/saga/prompts/run.md

@@ -0,0 +1,20 @@
+# Running a saga (the orchestrator)
+
+You are the orchestrator. You dispatch work and keep the record. You do not plan, you do not edit the contract, and you do not implement items yourself. A human started this run; starting it is the approval.
+
+`<root>` is the registered project path given in the run's input. Every command is `hagi saga <command> <saga> --path <root>` and works from any directory. Every command that changes a Saga also takes `--token <token>`: the token that `claim` printed.
+
+0. **Claim first.** `hagi saga claim <saga> --session <your session id> --path <root> --json`. Keep the printed token for every later command. If it refuses because another owner holds the Saga, stop and report it. Never take over by age, and never write a paused snapshot over another owner's progress.
+1. **Freeze.** `hagi saga freeze <saga> --path <root> --token <token>`. If it refuses (open questions, open amendments, a changed contract), run `hagi saga set-status <saga> --state paused --note "<reason>" --path <root> --token <token>`, stop and report the reasons. Do not edit contract files and do not decide open questions. A first freeze writes revision 1. After an amendment was merged it writes the next revision, chained to the previous one, and reopens the items whose acceptance command changed.
+2. **Check before every item and at every heartbeat.** `hagi saga assert-owner <saga> --path <root> --token <token>` before each dispatch, then `hagi saga check <saga> --phase run --path <root>`. If a check fails, pause the same way and report. An open amendment also means: pause.
+3. **Work one item at a time** (`hagi saga items <saga> --path <root>` lists them with their commands), unless the goal allows parallel items. For each item:
+   - Create each Worker with `hagi saga session create --saga <saga> --path <root> --title "<ITEM> <role>" --role <role> --master <your session id> --item <ITEM>`, where `<role>` is `implementation` or `verification`. This command takes the token from `SAGA_EXECUTION_TOKEN`, set to the token that `claim` printed, and refuses `--token`. It creates the chat session with its Saga metadata and records it in `sessions.md`. Then give the Worker its instructions below.
+   - An implementation worker writes code and tests only. Give it the goal, the item, the scope and the safety rules, the project root and its report path.
+   - A separate verification worker runs the item's command from `acceptance.md` in the project root, writes the output to `<root>/.hagicode/sagas/<saga>/runtime/evidence/<ITEM>.log`, and writes `<root>/.hagicode/sagas/<saga>/runtime/reports/<ITEM>.md` with the line `Status: PASS` (or `状态: PASS`) only if the exit code is 0. It changes no files.
+   - Only `hagi saga tick <saga> <ITEM> --path <root> --token <token>` ticks an item. It refuses without a PASS report and an evidence file.
+4. **On a failed verification, classify it.** An environment fault (missing module, port in use, quota) does not count. A real failure counts: give a tuning worker the failure log path, then verify again. After 3 real failures run `hagi saga block <saga> <ITEM> "<reason>" --path <root> --token <token>` and move on.
+5. **After a revision reopened items,** also re-verify any item whose command is the full regression: its own command did not change, so it was not reopened.
+6. **Keep the record.** Append a line to `<root>/.hagicode/sagas/<saga>/runtime/orchestrator-log.md` after every dispatch, verification and tick. `hagi saga session create` records each Worker session it creates in `<root>/.hagicode/sagas/<saga>/runtime/sessions.md`, so do not append those sessions to that file by hand. Run `hagi saga set-status <saga> --state running --note "<heartbeat>" --path <root> --token <token>` at every heartbeat, and `hagi saga status <saga> --path <root> --json` to read the projection at the end.
+7. **Archive each settled item's sessions.** Once an item is ticked or blocked and its workers have stopped, archive the worker sessions you created for it: `hagi chat archive --session-id <session id> --json`. Take the IDs from `<root>/.hagicode/sagas/<saga>/runtime/sessions.md`. Archive only sessions you created in this run: never your own orchestrator session, a session that is still running, a session you did not create, or the Saga itself (`hagi saga archive` is not part of a run). Archiving leaves the reports, evidence and `sessions.md` record in `runtime/` untouched. Log each archived ID in `orchestrator-log.md`. If an archive call fails, log the error and go on: do not retry in a loop and do not pause for it.
+8. **Never leave a command hanging.** Every shell command must end on its own: never read from standard input, and give waits a limit. If something does not answer, report it instead of waiting forever.
+9. **Stop** when every item is ticked or blocked, when a pause condition appears, or when the human's run options say so. Write the terminal snapshot first (`set-status --state done` only when every active item is verified, otherwise `paused` with the reason). Once every worker has stopped, archive any remaining worker sessions as in step 7, then run `hagi saga release <saga> --path <root> --token <token> --workers-settled`. Never archive the Saga itself and do not commit. Report the revision, every item with its state and evidence path, the blocked items with reasons, the sessions you created and which of them you archived, and the next step for a human.

package/skills/README.md

@@ -0,0 +1,52 @@
+# Embedded Skills
+
+`repos/cli/skills/` is the repository-level discovery entrypoint for Hagi CLI skills.
+Use this directory when you need the canonical agent-facing contract for the published `@hagicode/cli` package and the installed `hagi` command.
+
+## Package-first usage
+
+Treat the published package as the default execution path:
+
+```bash
+npx @hagicode/cli --help
+npx @hagicode/cli proposal list --json
+```
+
+If `@hagicode/cli` is already installed, the same contract is available through:
+
+```bash
+hagi --help
+```
+
+Repository-local commands under `repos/cli` are maintainer workflows only.
+
+## Available skill packages
+
+- [`hagi/SKILL.md`](hagi/SKILL.md) - canonical Hagi CLI skill entrypoint
+- [`hagi/agents/openai.yaml`](hagi/agents/openai.yaml) - agent display and invocation metadata
+- [`hagi/references/cli-usage.md`](hagi/references/cli-usage.md) - published package usage and runtime flags
+- [`hagi/references/session-data.md`](hagi/references/session-data.md) - inside a HagiCode session: read-only data commands and the actions that need an explicit request
+- [`hagi/references/proposal-flow.md`](hagi/references/proposal-flow.md) - explicit proposal lifecycle guidance
+- [`hagi/references/openspec-workflow.md`](hagi/references/openspec-workflow.md) - the OpenSpec stage each proposal command starts and how to follow a run
+- [`hagi/references/resource-lock.md`](hagi/references/resource-lock.md) - the shared resource lock: owner, exit codes, the watcher protocol and requisition rules
+- [`hagi/references/super-commit.md`](hagi/references/super-commit.md) - Super Commit through the CLI: prompt-id start, options, result and explicit-request rule
+- [`hagi/references/local-development.md`](hagi/references/local-development.md) - maintainer-only source-tree workflows
+- [`hagi/references/validation.md`](hagi/references/validation.md) - post-change validation steps
+
+## Canonical writable source
+
+Update `repos/cli/skills/**` when the Hagi CLI skill contract changes.
+
+## Built-in copy
+
+The server also ships this folder as its built-in skill `hagi`. The copy lives in `repos/built-in-skills/content/hagi/` and is an exact byte copy of `repos/cli/skills/hagi/`. Edit this folder, then recopy and rehash the built-in copy.
+
+## Skill installation and discovery
+
+If an agent runtime or skill loader needs the Hagi skill source, point it at `repos/cli/skills/hagi/`.
+Start discovery from this README, then open `repos/cli/skills/hagi/SKILL.md`.
+
+## Maintainer note
+
+When you are editing the CLI itself, use the maintainer-only workflows in `hagi/references/local-development.md`.
+For normal usage and automation, stay package-first.

package/skills/hagi/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: hagi
+description: Use when the user wants to run, verify, or update the HagiCode CLI against the Hagi API, use local Saga initialization, creation, checks, writes, or read-only queries, or asks about their own projects, proposals, chat sessions, vaults, scheduled plans, or installed skills, including user skills versus built-in skills and enabling or disabling a built-in skill. Also covers the OpenSpec workflow behind proposal commands and Super Commit, which commits a code repository through a HagiTask session. Keep package-first command guidance primary, then follow the Saga, proposal, local development, and validation references as needed. Inside a HagiCode session, read the session-data reference first for questions about the user's own data.
+---
+
+# Hagi
+
+Use this skill when the user asks to:
+
+- answer questions about their own projects, proposals, chat sessions, vaults, scheduled plans, or installed skills
+- list which installed skills are user skills and which are built-in skills, or which built-in skills are enabled
+- enable or disable a built-in skill
+- run or verify the `hagi` CLI
+- run, explain, or verify local `saga init`, `saga new`, `saga list`, `saga status`, or `saga items` operations
+- read a published Saga method (`goal`, `research`, `acceptance`, `plan`, `run`, `amend`) with `saga method <name>`
+- run, explain, or verify local Saga ownership, checks, and writes: `claim`, `assert-owner`, `release`, `freeze`, `check`, `tick`, `block`, `set-status`, `amend`, `archive`, and `session create` (Saga Worker chat sessions)
+- explain or execute `project`, `proposal`, `chat`, `hagitask`, `vault`, `plan`, `skills`, or `saga` commands
+- explain the OpenSpec workflow behind `proposal` commands, which stage each command starts, or how to follow a run until it settles
+- take turns on a shared resource (a game server, a test environment) with other agents through `hagi agent lock`
+- run, explain or check a Super Commit, which commits the uncommitted changes of a code repository through a HagiTask session
+- inspect CLI flags, environment variables, exit codes, or JSON automation behavior
+- validate proposal-session flows against a backend API
+- modify or debug the CLI implementation in `repos/cli`
+
+## Core rules
+
+- Prefer `npx @hagicode/cli ...` for normal usage and package-level verification.
+- Use `hagi ...` only when `@hagicode/cli` is already installed and on `PATH`.
+- Run repository-local install, build, and test commands with the working directory set to `repos/cli`.
+- Never run `pnpm install`, `pnpm run`, or other build commands at the monorepo root.
+- Prioritize API invocation guidance over codebase tours unless the user explicitly wants implementation work.
+- Built-in skills can be enabled or disabled with `hagi skills local enable --skill-name <name>` and `hagi skills local disable --skill-name <name>`. They cannot be uninstalled or updated through the CLI. A change applies to agent runs that start afterwards; a run already in progress keeps the skills it started with.
+- Every proposal names its writable repositories and its read-only repositories, in a `Repository scope` section at the start of `--chief-complaint`. Both lists are always present, and an empty list is written as `none`. Take the paths from `hagi project repositories --id <project-id> --json`. When neither the user's request nor the session gives the scope, ask the user and offer those repositories as the choices; never guess a scope or widen the writable list. Details: [`references/proposal-flow.md`](references/proposal-flow.md#repository-scope).
+
+## Choose the workflow
+
+1. Published package usage -> read [`references/cli-usage.md`](references/cli-usage.md)
+2. Explicit proposal lifecycle work -> read [`references/proposal-flow.md`](references/proposal-flow.md)
+3. Which OpenSpec stage a proposal command starts, or following a run to its end -> read [`references/openspec-workflow.md`](references/openspec-workflow.md)
+4. Super Commit, committing a code repository through a HagiTask session -> read [`references/super-commit.md`](references/super-commit.md)
+5. Source-tree development in `repos/cli` -> read [`references/local-development.md`](references/local-development.md)
+6. Post-change validation -> read [`references/validation.md`](references/validation.md)
+7. The user's own data, inside a HagiCode session -> read [`references/session-data.md`](references/session-data.md)
+8. Local Saga initialization, creation, list, status, item queries, ownership, checks, freeze, ticks, status writes, amendments, archive, or creating and recording Saga Worker sessions (`session create`) -> read [`references/saga.md`](references/saga.md)
+9. A shared resource that other agents also use, or any `hagi agent lock` command -> read [`references/resource-lock.md`](references/resource-lock.md)
+
+When `hagi` is loaded as a built-in skill inside a HagiCode session, read item 7 first for any question about the user's own data or skills, before the other references.
+
+## Runtime configuration
+
+Shared runtime flags:
+
+- `--base-url <url>`
+- `--token <token>`
+- `--lang <lang>`
+- `--json`
+
+Equivalent environment variables:
+
+- `HAGI_API_BASE_URL`
+- `HAGI_API_TOKEN`
+- `HAGI_API_LANG`
+
+A base URL can also come from `"baseUrl"` in `$XDG_CONFIG_HOME/hagi/config.json`, or `~/.config/hagi/config.json` when `XDG_CONFIG_HOME` is unset.
+
+Precedence: flag, then `HAGI_API_BASE_URL`, then the config file. The base URL has no default. When none of the three is set, the CLI exits with code `2`.
+
+Inside a HagiCode session, the server can add four runtime variables to an agent run. They are present only while the built-in `hagi` skill is installed and enabled, and only on Claude Code, Pi, OpenCode, GitHub Copilot and omp:
+
+| Variable | Carries |
+| --- | --- |
+| `HAGI_API_BASE_URL` | Address of the backend that started the session |
+| `HAGI_VERSION` | Version of the HagiCode server |
+| `HAGI_DEPLOYMENT_TYPE` | Deployment type of the server |
+| `HAGI_API_LANG` | Effective AI language: `zh-CN` or `en-US`, sent as `Accept-Language` |
+
+A variable the server cannot determine is left out, and the run still starts. Report an absent variable as absent; do not guess a value. Conditions and the rest of the session rules are in [`references/session-data.md`](references/session-data.md).
+
+## Command surface
+
+The current top-level command families are:
+
+- `project`
+- `proposal`
+- `vault`
+- `chat`
+- `hagitask`
+- `plan`
+- `skills`
+- `agent`
+- `saga`
+
+`hagi saga` provides `init`, `new`, `list`, `status`, and `items`, plus the write and check commands `claim`, `assert-owner`, `release`, `freeze`, `check`, `tick`, `block`, `set-status`, `amend`, and `archive`, and `session create`, which creates a Saga Worker chat session and records it. Mutating commands take `--token` or `SAGA_EXECUTION_TOKEN`; `session create` takes only `SAGA_EXECUTION_TOKEN`. With `--path`, these operate on host-local files without reading backend configuration or calling the API, except `session create`, which calls the backend to find the registered project; `--project-id` resolves a project through the backend. Creating a Worker changes state, so run `session create` only when the user or a Saga run explicitly asks for it. See [`references/saga.md`](references/saga.md) for initialization, creation, offline behavior, and read-only query guarantees.
+
+`project repositories --id <project-id>` is read-only. It lists one project's repositories with each path relative to the project root (for example `repos/cli`). Those paths are the values a proposal's `Repository scope` names; see [`references/proposal-flow.md`](references/proposal-flow.md#repository-scope).
+
+Scheduled plans (`hagi plan`) save a proposal or HagiTask input with a schedule. `list`, `get`, `create`, `update`, `enable`, `disable`, `delete` and `run` manage them; `run --background` returns the accepted plan id before the session exists. A manual run never changes a plan's state or next run time. See [`references/cli-usage.md`](references/cli-usage.md#plan-commands) for the action list and a plan document example.
+
+HagiTask sessions (`hagi hagitask`) run a preset task with a structured input. `list` shows the active tasks, `schema --task-id <id>` shows one task's scope, commands, parameters and required marks, and `create --task-id <id> --input <file>` creates the session. Read the schema first, write the input from it, then create. `send` posts a follow-up message; `--steer` (or `HAGI_SEND_STEER=1`) inserts it into a running turn instead, and `queued` means no running task took it. The backend rejects any input key the schema does not list. See [`references/cli-usage.md`](references/cli-usage.md#hagitask-commands) for the flow and an input example, and [`references/cli-usage.md`](references/cli-usage.md#steer-for-send-commands) for the Steer options.
+
+Each family also reads one session by id. `proposal get` and `hagitask get` read a session; with `--wait` they poll until its status settles, so a run can be followed without guessing. `proposal messages` and `hagitask messages` read a session's messages, and `--last 1` reads the final message of a run. The stage behind each proposal command is in [`references/openspec-workflow.md`](references/openspec-workflow.md). Super Commit is started with `hagitask create --prompt-id auto-compose-commit.<locale>`; see [`references/super-commit.md`](references/super-commit.md).
+
+## Resource lock
+
+`hagi agent lock` is a fair queue lock for a resource that several agents share. Read [`references/resource-lock.md`](references/resource-lock.md) before the first lock command. The protocol is watcher-based:
+
+- Pass your own session ID as the owner: `hagi agent lock acquire --lock-id eu-1/duckov --owner sess-7f2c`. Every example is `hagi agent lock ...`; there is no `hagi lock`.
+- After `acquire`, read the windows. `Holding`: start the heartbeat watcher (a Monitor running `hagi agent lock heartbeat ...`, or a background process or sub-agent where there is no Monitor) before any work. `Queued`: start a continuous `hagi agent lock acquire --wait ...` watcher; do not sleep and re-check.
+- When all tasks are done, stop the heartbeat watcher and then run `hagi agent lock release`. Stopping alone releases the lock after 10 minutes without a heartbeat; the lock is also taken back after 24 hours. The heartbeat interval is 2 minutes.
+- When a watcher reports loss (exit code `32`), stop using the resource at once. After losing track (for example after compaction), repeat `acquire` with the same owner; it is safe.
+- Never run `hagi agent lock requisition` unless the user explicitly ordered a forced take; nothing else is a requisition, and otherwise you always queue. When ordered, quote the request in `--reason`, start the heartbeat watcher and tell the user which owner was displaced. When you are displaced, stop at once, tell the user, queue again only if the task still needs the resource, and never requisition back. A displaced agent can use the resource until its next heartbeat (up to 2 minutes), and the lock cannot stop work already running on the resource.
+
+## Source of truth
+
+- Canonical writable skill source: `repos/cli/skills/hagi/`
+- The server ships a byte-for-byte copy of this folder as its built-in skill `hagi`; edit here, never in the copy
+
+## References
+
+- [`references/cli-usage.md`](references/cli-usage.md) - package-first installation, quick start, runtime flags, and exit codes
+- [`references/session-data.md`](references/session-data.md) - inside a HagiCode session: read-only data commands, state-changing actions that need an explicit request, and failure handling
+- [`references/proposal-flow.md`](references/proposal-flow.md) - explicit proposal lifecycle sequence and command examples
+- [`references/openspec-workflow.md`](references/openspec-workflow.md) - the OpenSpec stage each proposal command starts, stage boundaries, who drives each step, and the monitoring rule
+- [`references/super-commit.md`](references/super-commit.md) - Super Commit: starting it by prompt id, its options, result reading and the explicit-request rule
+- [`references/resource-lock.md`](references/resource-lock.md) - the shared resource lock: numbers, owner, exit codes, the watcher protocol, the seven agent rules and requisition
+- [`references/saga.md`](references/saga.md) - local initialization, creation, ownership, checks, Saga writes, Saga Worker sessions (`session create`), and read-only queries
+- [`references/local-development.md`](references/local-development.md) - maintainer-only development, build, and repository internals
+- [`references/validation.md`](references/validation.md) - targeted verification after documentation or code changes

package/skills/hagi/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Hagi CLI"
+  short_description: "Operate the hagi CLI, including local Saga commands, and work with HagiCode data, skills, proposals, and Super Commit."
+  default_prompt: "Use $hagi to operate local Saga init, new, list, status, or items commands and the Saga ownership, check, freeze, tick, set-status, amend, and archive commands; look up HagiCode projects, proposals, sessions, vaults, plans, or skills; follow a proposal's OpenSpec workflow; run a Super Commit; enable or disable a built-in skill; or inspect, run, or update the CLI in repos/cli."
+
+policy:
+  allow_implicit_invocation: true