@hagicode/cli 0.1.0-dev.39.1.c7a4f44 → 0.1.0-dev.42.1.b13f8d2

package/skills/hagi/references/openspec-workflow.md

@@ -0,0 +1,130 @@
+# OpenSpec workflow behind `hagi proposal`
+
+Use this reference when a user asks what a `hagi proposal` command does on the OpenSpec side, which stage it starts, where it stops, or how to follow a run until it settles.
+
+Source of these facts: `ProposalSessionGrain` in `repos/hagicode-core` (`PCode.Orleans/Grains/ProposalSessionGrain.cs`, `ProposalSessionHandler.cs`) and the `openspec-v1-*` stage prompts (`new`, `explore`, `ff`, `apply`, `archive`). The command descriptions come from `hagi proposal <command> --help`. When these change, update this file.
+
+## Stage map
+
+Each command starts at most one stage. "Does not" lists what the command must not be assumed to do.
+
+| Command | Starts | Does not |
+| --- | --- | --- |
+| `proposal create` | no stage; creates the session | generate or execute |
+| `proposal optimize-description` | no stage; rewrites the title, description and name in one backend step | generate |
+| `proposal generate` | planning stages: `new`, then `explore` when explore mode is on, then `ff` | implement, execute or archive |
+| `proposal annotate` | no stage; submits review notes, which return the session to planning | execute |
+| `proposal execute` | implementation stage: `apply` | archive, or commit code |
+| `proposal archive` | archive stage: `archive` | complete the session |
+| `proposal complete` | no stage; marks the session completed through its own endpoint | start any stage |
+| `proposal status` | no stage; sets the status directly with a read-before-write merge | start any stage |
+| `proposal send` | no stage; sends a follow-up message on the active session | start a stage by itself, except as noted under "Who drives each step" |
+| `proposal get` | no stage; reads one session, and with `--wait` polls until its status settles | change the session |
+| `proposal messages` | no stage; reads the session's messages | change the session |
+
+Explore mode is chosen with `--enable-explore-mode` or `--disable-explore-mode` on `proposal generate`.
+
+A command returning means the request was accepted and the stage was queued. It does not mean the stage finished. Follow the run with `proposal get` (see "Who drives each step").
+
+## Boundaries of each stage
+
+- **Planning** (`generate`) writes the proposal artifacts. It implements no source files. The next step is `annotate` or `execute`, and the user chooses which.
+- **Implementation** (`execute`) implements the change. It skips tasks that are not implementation, such as archiving or committing, and reports them as out of scope. It does not archive.
+- **Archive** (`archive`) archives the change. It does not implement anything.
+
+No command starts the next stage on its own. An agent that has finished one lifecycle command runs the next command only when the user asked for that step.
+
+## Two kinds of commit
+
+Two different things are called "commit" in this workflow. Neither replaces the other.
+
+- **Archive commit.** The archive stage may make one commit, only in the MonoSpecs repository that holds `openspec/`, and only when the project's option to commit on archive is on. The backend runs it inside the archive stage. It never covers code repositories, and the agent does not run it as a command.
+- **Super Commit.** A separate session that commits the uncommitted changes in a code repository. It is started with `hagi hagitask create --prompt-id auto-compose-commit.<locale>`, and the agent starts it only on request. See [super-commit.md](super-commit.md).
+
+After `proposal execute`, the code changes are still uncommitted. The archive commit does not commit them. To commit code, use Super Commit, and only when the user asks.
+
+## Confirm a stage before moving on
+
+1. Take the session id from the command's `--json` output.
+2. Pass that same id to the next command.
+3. Treat the suggested next command in the output as a suggestion. Do not run it unless the user asked for that step.
+
+The repositories a proposal may change are listed in [Repository scope](proposal-flow.md#repository-scope). Read that section; this file does not restate it.
+
+## Who drives each step
+
+Every step is one of five kinds:
+
+- **Agent-issued command**: the agent runs it, and only when the user asked for that step.
+- **AI run inside the backend**: the backend runs an AI agent for the stage. The agent does not run it by hand.
+- **Automatic**: the backend moves the status with no command.
+- **Needs a person**: the run stops until a person answers or decides.
+- **Needs monitoring**: the agent follows the run with `proposal get --wait` and reports the result.
+
+| Step | Kind | Notes |
+| --- | --- | --- |
+| `proposal create` | agent-issued command | creates the session |
+| `proposal optimize-description` | agent-issued command | moves Init to Optimizing |
+| Optimizing to Drafting | automatic | when the optimization finishes |
+| `proposal generate` | agent-issued command | starts the planning run, an AI run inside the backend |
+| Planning run (Openspecing) | AI run inside the backend, needs monitoring | Openspecing |
+| Openspecing to Reviewing | automatic | when planning ends |
+| `proposal annotate` | agent-issued command | moves Reviewing back to Openspecing |
+| `proposal execute` | agent-issued command | moves Reviewing to Executing, and starts the implementation run |
+| Implementation run (Executing) | AI run inside the backend, needs monitoring | Executing |
+| Run asks a question | needs a person | Executing moves to WaitingForReply |
+| A person answers | needs a person | WaitingForReply moves back to Executing |
+| Executing to ExecutionCompleted | automatic | when the implementation run ends |
+| `proposal archive` | agent-issued command | moves ExecutionCompleted to Archiving |
+| Archiving to Archived | automatic | when the archive run ends |
+| `proposal complete` | agent-issued command | marks the session completed |
+| `proposal status` | agent-issued command | sets the status directly |
+| `proposal send` | agent-issued command | on a session in ExecutionCompleted or Completed, it starts a new execution run; see the warning below |
+| `proposal get --wait` | needs monitoring | reads the status until it settles |
+| `proposal messages` | agent-issued command | reads the messages, for example the final result |
+
+Status moves, and who causes each one:
+
+| From | To | Trigger |
+| --- | --- | --- |
+| Init | Optimizing | agent runs `optimize-description` |
+| Optimizing | Drafting | automatic |
+| Drafting | Openspecing | agent runs `generate` |
+| Openspecing | Reviewing | automatic when planning ends |
+| Reviewing | Openspecing | agent runs `annotate` |
+| Reviewing | Executing | agent runs `execute` |
+| Executing | WaitingForReply | the run asks a question |
+| WaitingForReply | Executing | a person answers |
+| Executing | ExecutionCompleted | automatic when the implementation run ends |
+| ExecutionCompleted | Archiving | agent runs `archive` |
+| ExecutionCompleted | Executing | agent runs `send` (a new execution run) |
+| Archiving | Archived | automatic when the archive run ends |
+
+Only the moves labelled with a command are caused by the agent. The rest are caused by the backend, or wait for a person.
+
+### Warnings
+
+- `proposal send` on a session in **ExecutionCompleted** or **Completed** starts a new execution run. Use it only when the user asks to run again.
+- `proposal annotate` on a session in **Reviewing** returns it to planning. The session goes back to Openspecing and is planned again. Use it only when the user asks for revisions.
+
+### The monitoring rule
+
+After any start command (`generate`, `execute`, `archive`), follow the run:
+
+```bash
+hagi proposal get --session-id <id> --wait --json
+```
+
+Read the `status` and the `wait` object in the output:
+
+- **Openspecing, Executing or Archiving**: the run is still going. The wait ends on its own at the timeout.
+- **WaitingForReply**: a person must answer. Tell the user; waiting longer does not help.
+- **Reviewing, ExecutionCompleted or Archived**: the stage has settled.
+- **Timeout (exit code `31`)**: report the last status to the user. Do not retry in a loop.
+
+A returned start command accepts the request. It does not prove the run succeeded. Confirm the outcome from the settled status and, when the result matters, from `proposal messages`.
+
+Other options of the monitoring commands:
+
+- `--timeout <seconds>`, `--interval <seconds>`, `--grace <seconds>`: only with `--wait`. `--interval` must be less than `--timeout`.
+- `proposal messages --session-id <id> --last <n>`: reads the n newest messages. `--json` prints the list unchanged.

package/skills/hagi/references/proposal-flow.md

@@ -0,0 +1,210 @@
+# Proposal Flow
+
+Treat the proposal lifecycle as explicit, non-interactive backend actions.
+One CLI command maps to one backend action.
+Do not imply hidden chaining between `create`, `optimize-description`, `generate`, `annotate`, `execute`, `archive`, and `complete`.
+
+## Configuration first
+
+Confirm the backend target before discussing proposal commands:
+
+- `--base-url <url>` or `HAGI_API_BASE_URL`
+- `--token <token>` or `HAGI_API_TOKEN`
+- `--lang <lang>` or `HAGI_API_LANG`
+- `--json` for automation and machine-readable output
+
+## Explicit lifecycle sequence
+
+Use this order when explaining or validating proposal flows:
+
+1. `proposal list`
+2. `proposal create`
+3. `proposal optimize-description` (optional)
+4. `proposal generate`
+5. `proposal annotate` (optional review loop)
+6. `proposal execute`
+7. `proposal archive`
+8. `proposal complete`
+9. `proposal send` for follow-up conversation on the active session
+
+`proposal status` sets the session status directly and is not part of the sequence above.
+
+Which stage each command starts, and what it leaves behind, is in [`openspec-workflow.md`](openspec-workflow.md).
+
+Between two lifecycle commands, follow the run with `hagi proposal get --session-id <id> --wait --json` and wait until the status settles. A returned command only accepts the request. Read [`openspec-workflow.md`](openspec-workflow.md#who-drives-each-step) for what each status means.
+
+After `proposal execute` settles and the code changes are still uncommitted, a Super Commit can commit them. Start it only when the user asks; see [`super-commit.md`](super-commit.md).
+
+The CLI may suggest a next command, but it does not call later lifecycle APIs automatically.
+
+## Repository scope
+
+Every proposal names the repositories it may edit (writable) and the repositories it may only read (read-only). Both lists are always present, and an empty list is written as `none`.
+
+1. Run `project repositories` for the proposal's project first:
+
+   ```bash
+   npx @hagicode/cli project repositories --id <project-id> --json
+   ```
+
+   Every `path` in that output (for example `repos/cli`) is a candidate. The human-readable output prints the same paths in its Path column.
+
+2. Begin `--chief-complaint` with a `Repository scope` section. Its `Writable repositories:` and `Read-only repositories:` lists hold paths taken from step 1, one `- ` entry per line. An empty list is written as `- none`. The chief complaint text follows after a blank line.
+
+3. Run `proposal create` with that chief complaint.
+
+The scope is a text convention inside the chief complaint, not a structured field the CLI sends. `proposal create` has no scope flags: do not invent `--writable-repo` or `--readonly-repo`.
+
+Where the scope comes from, in this order:
+
+- The user's request names the writable and read-only repositories. Check each path against the step 1 list.
+- Otherwise, the session's own repository scope, when the session states one. Name that scope with the action and its target before running `proposal create`.
+- Otherwise, ask the user and show the step 1 repositories as the choices. Wait for the answer.
+
+Rules:
+
+- A path that is not in the step 1 list is asked about, never corrected or guessed.
+- Never widen the writable list as a precaution, and never leave the `Repository scope` section out.
+- When the project lists no repositories, the project root `.` is the only candidate: write `- .` as the writable entry and `- none` for read-only. Ask the user only if the request implies something else.
+
+Worked example. The project has three repositories, and the user asks for a change to the CLI that only reads the core API:
+
+```json
+{
+  "projectId": "proj-1",
+  "name": "HagiCode",
+  "isMonoSpecs": true,
+  "hasError": false,
+  "repositories": [
+    { "name": "cli", "path": "repos/cli", "displayName": "CLI", "type": "library", "branch": "main", "isValidGitRepo": true },
+    { "name": "hagicode-core", "path": "repos/hagicode-core", "displayName": "Core", "type": "backend", "branch": "main", "isValidGitRepo": true },
+    { "name": "web", "path": "repos/web", "displayName": "Web", "type": "frontend", "branch": "main", "isValidGitRepo": true }
+  ]
+}
+```
+
+```bash
+npx @hagicode/cli proposal create \
+  --project-id proj-1 \
+  --chief-complaint "Repository scope
+Writable repositories:
+- repos/cli
+Read-only repositories:
+- repos/hagicode-core
+
+Add CLI completion for session workflows" \
+  --default-title \
+  --json
+```
+
+When the change touches only one repository and reads nothing else, the read-only list is written as `none`:
+
+```bash
+npx @hagicode/cli proposal create \
+  --project-id proj-1 \
+  --chief-complaint "Repository scope
+Writable repositories:
+- repos/web
+Read-only repositories:
+- none
+
+Tighten the settings page copy" \
+  --default-title \
+  --json
+```
+
+## Published package examples
+
+List sessions:
+
+```bash
+npx @hagicode/cli proposal list --json
+```
+
+Create a proposal session. The chief complaint begins with the `Repository scope` section; see [Repository scope](#repository-scope):
+
+```bash
+npx @hagicode/cli proposal create \
+  --project-id <project-id> \
+  --chief-complaint "Repository scope
+Writable repositories:
+- repos/cli
+Read-only repositories:
+- none
+
+Add CLI completion for session workflows" \
+  --default-title \
+  --json
+```
+
+Optimize the description explicitly:
+
+```bash
+npx @hagicode/cli proposal optimize-description \
+  --session-id <session-id> \
+  --description "Improve the proposal framing" \
+  --optimization-direction "Focus on implementation risk" \
+  --json
+```
+
+Generate the proposal body:
+
+```bash
+npx @hagicode/cli proposal generate \
+  --session-id <session-id> \
+  --enable-explore-mode \
+  --json
+```
+
+Submit annotations from a file or stdin:
+
+```bash
+npx @hagicode/cli proposal annotate --session-id <session-id> --input annotations.json
+cat annotations.json | npx @hagicode/cli proposal annotate --session-id <session-id> --input - --json
+```
+
+Execute, archive, complete, or continue the session:
+
+```bash
+npx @hagicode/cli proposal execute --session-id <session-id> --json
+npx @hagicode/cli proposal archive --session-id <session-id> --hero-id <hero-id>
+npx @hagicode/cli proposal status --session-id <session-id> --status Reviewing
+npx @hagicode/cli proposal complete --session-id <session-id>
+npx @hagicode/cli proposal send --session-id <session-id> --content "Please continue"
+```
+
+## Session metadata
+
+`proposal create` accepts `--metadata key=value` (repeatable) and `--metadata-json <file|->` (a JSON object of string values; `-` reads stdin). Use them to mark the sessions of one orchestrated run: a master marker on the orchestrator and worker markers on each proposal, so the run can find its sessions again.
+
+```bash
+MASTER_ID=$(hagi chat create --title "Batch master" --project-id <project-id> --metadata role=master --metadata batch=2026-11-07 --json | json_field '.session.sessionId')
+
+hagi proposal create \
+  --project-id <project-id> \
+  --chief-complaint "Repository scope
+Writable repositories:
+- repos/web
+Read-only repositories:
+- none
+
+Tighten the settings page copy" \
+  --default-title \
+  --metadata role=worker \
+  --metadata master="$MASTER_ID" \
+  --json
+```
+
+- Keys: 1 to 64 characters matching `^[a-z][a-z0-9._-]{0,63}$`. Values: 1 to 512 characters with no control characters. At most 16 entries. The backend checks these and its message is shown as it is.
+- Each key appears once across both options. A repeat, a missing `=`, or a non-string JSON value exits `2` with no request sent.
+- Metadata is write-once and visible to every reader of the session. Do not put secrets in it.
+- The output `session` object carries `userMetadata` when the session has entries. Read it to confirm the markers were stored.
+
+## Validation focus
+
+After each lifecycle step:
+
+- inspect JSON output or the suggested next command
+- confirm the session identifier used by the next command
+- check exit codes when the caller needs scripting guarantees
+- switch to `repos/cli` maintainer workflows only if package-level behavior is insufficient

package/skills/hagi/references/session-data.md

@@ -0,0 +1,156 @@
+# Session Data
+
+Use this reference when an agent runs inside a HagiCode session and the user asks about their own projects, proposals, chat sessions, vaults, scheduled plans or installed skills.
+Read-only inspection comes first. Change state only when the user asked for that change in the conversation.
+
+## Runtime variables
+
+A HagiCode session can give you four variables. Each one is defined here, once:
+
+| Variable | Carries |
+| --- | --- |
+| `HAGI_API_BASE_URL` | Address of the backend that started the session. `hagi` reads it when no `--base-url` is given. |
+| `HAGI_VERSION` | Version of the HagiCode server that started the session. |
+| `HAGI_DEPLOYMENT_TYPE` | Deployment type of that server. |
+| `HAGI_API_LANG` | The user's effective AI language, `zh-CN` or `en-US`. `hagi` sends it as `Accept-Language`. |
+
+The server adds them to an agent run only when all of these hold:
+
+- the built-in `hagi` skill is installed and enabled;
+- the run is on Claude Code, Pi, OpenCode, GitHub Copilot or omp, the agent CLIs that load built-in skills at launch;
+- the value is one the server can determine. A value it cannot determine is left out, and the run still starts.
+
+A value the user already set in the environment is kept, not replaced.
+The variables carry facts about the server and the language only. They never carry a token or a file path.
+
+If a variable you rely on is absent, say that it is absent and ask the user. Do not guess a value, install software, or retry in a loop.
+
+## Connection
+
+Run `hagi` with no `--base-url` flag and no token when `HAGI_API_BASE_URL` is set; the variable is enough.
+
+- Pass `--base-url <url>` only when the user gives you an address.
+- If the CLI exits with code `2` and says no backend base URL is configured, the variable is missing from this session. Tell the user, and ask for the address. Do not guess one.
+- Use `--json` for every command whose output you will read or summarize.
+
+## Choosing the runner
+
+1. If `hagi` is on `PATH`, run `hagi ...`.
+2. Otherwise, if `node --version` reports 24 or newer, run `npx @hagicode/cli ...`.
+3. If neither is available, say that the CLI cannot run here and why. Continue without inventing data, and do not install Node.js or the CLI unless the user asks.
+
+## Read-only commands
+
+Run these freely to answer questions. Each list or get command is safe to repeat.
+
+### Projects
+
+```bash
+hagi project list --json
+hagi project repositories --id <project-id> --json
+```
+
+`project repositories` lists one project's repositories. Its paths are the only values a proposal's repository scope may name.
+
+### Proposals
+
+```bash
+hagi proposal list --json
+hagi proposal list --project-id <project-id> --active-only --json
+hagi proposal get --session-id <session-id> --json
+hagi proposal messages --session-id <session-id> --last 1 --json
+```
+
+`proposal get` and `proposal messages` only read. `proposal get --wait` polls the status until it settles and changes nothing.
+
+### Vaults
+
+```bash
+hagi vault list --json
+hagi vault files list --id <vault-id> --path <relative-dir> --json
+hagi vault files preview --id <vault-id> --path <relative-file> --json
+```
+
+`vault files preview` reads one file. Preview only the files the user's question needs.
+
+### Chat sessions
+
+```bash
+hagi chat list --json
+hagi chat list --project-id <project-id> --active-only --json
+```
+
+### HagiTasks
+
+```bash
+hagi hagitask list --json
+hagi hagitask schema --task-id <task-id> --json
+hagi hagitask get --session-id <session-id> --json
+hagi hagitask messages --session-id <session-id> --last 1 --json
+```
+
+Read the schema before creating a HagiTask session. Its `parameters` give the input keys, and `inputSchema` is the JSON Schema the input must satisfy.
+
+### Scheduled plans
+
+```bash
+hagi plan list --json
+hagi plan get --id <plan-id> --json
+```
+
+### Skills
+
+```bash
+hagi skills local list --json
+hagi skills gallery search --query <keyword> --json
+hagi skills gallery detail --id <gallery-id> --source <source> --json
+hagi skills trusted list --json
+```
+
+`hagi skills local list --json` returns one item per installed skill. Read these fields from each item:
+
+- `origin`: `user` for a skill the user installed, `built-in` for a skill the server ships. An item with no `origin` is a user skill.
+- `builtIn.enabled`: whether a built-in skill is on. It is present only for built-in skills. For user skills, availability does not apply.
+- `builtIn.version`: the version the release recorded for a built-in skill. It may be absent.
+- `managedInstallMetadata.version`: the version of a user skill installed through the gallery, when recorded.
+
+## State-changing commands
+
+Run these only when the user has asked for that action in this conversation.
+First name the action and its target (the id, the title or the name), then run it.
+A question such as "what is in my plan" is not a request to run, enable, disable or delete it.
+
+| Family | Commands that change state |
+| --- | --- |
+| `project` | `create`, `update`, `delete` |
+| `proposal` | `create`, `optimize-description`, `generate`, `annotate`, `execute`, `archive`, `status`, `complete`, `send` |
+| `vault` | `create`, `update`, `delete` (`delete --delete-local-files` also removes files) |
+| `chat` | `create`, `archive`, `delete`, `send` |
+| `hagitask` | `create`, `send` |
+| `plan` | `create`, `update`, `enable`, `disable`, `delete`, `run` |
+| `skills` | `local enable`, `local disable`, `local uninstall`, `gallery install`, `trusted upsert`, `trusted delete`, `trusted reset` |
+
+A `send` or `run` starts agent work, and `execute` and `generate` start it too. Treat those as changes of the same kind.
+
+A `send` with Steer (`--steer`, or `HAGI_SEND_STEER` set in the calling shell) inserts its text into a running turn. The result says which happened: `steered` means a running task took it, and `queued` means no running task did, so it went out as the next message. `HAGI_SEND_STEER` belongs to the calling shell; the backend does not set it inside agent sessions.
+
+`hagitask create` with a Super Commit prompt (`--prompt-id auto-compose-commit.<locale>`) creates commits in a code repository, and with `--need-push` publishes them. Start it only when the user asked for it in this conversation, and add `--need-push` only when the user asked for a push. See [`super-commit.md`](super-commit.md).
+
+`skills local enable` and `skills local disable` change whether a built-in skill loads. The change applies to agent runs that start afterwards; a run already in progress keeps its skills. Built-in skills cannot be uninstalled through the CLI.
+
+Before `proposal create`, the proposal's repository scope is settled. Take the writable and read-only repositories from the user's request, or infer them from the session's repository scope when the session states one. When neither gives the scope, ask the user and offer the project's repositories from `project repositories --id <project-id> --json` as the choices. Do not guess the scope, and do not widen the writable list. The scope is written into the chief complaint as a `Repository scope` section; see [`proposal-flow.md`](proposal-flow.md#repository-scope).
+
+When you name the action and its target before running `proposal create`, name its repository scope too.
+
+## Failure handling
+
+| Exit code | Meaning | What to tell the user |
+| --- | --- | --- |
+| `2` | No base URL, or a usage error | The session did not provide `HAGI_API_BASE_URL`, or the command was malformed. Name the missing piece. |
+| `21` / `23` | Unauthorized / forbidden | The backend rejected the request. Report the code; do not try a token. |
+| `24` | Not found | Name the id that was not found and suggest a `list` command to find the right one. |
+| `30` | Operation failed: the backend refused a change and returned a result with `succeeded` false, for example `skills local enable` or `disable` on a name that is not a built-in skill | Quote the backend message from the output and stop. Nothing changed. |
+| `60` | Transport or connection failure | Say the backend is unreachable at the named base URL. Do not retry in a loop, and do not guess another address. |
+| other non-zero | HTTP or unknown error | Quote the error message and stop. |
+
+When a command fails, report the failure. Do not fill the gap with guesses about the user's data.

package/skills/hagi/references/super-commit.md

@@ -0,0 +1,106 @@
+# Super Commit through `hagi`
+
+Use this reference when a user asks to commit the uncommitted changes of a code repository, to publish them, or to explain or check a Super Commit run.
+
+Super Commit commits the uncommitted changes in a code repository. It runs as a separate session, not as part of the proposal lifecycle. It creates commits, and with `--need-push` it also publishes them. Treat it as a state-changing action: start it only when the user asked for it.
+
+For what the archive commit does, and how it differs from Super Commit, see [openspec-workflow.md](openspec-workflow.md#two-kinds-of-commit).
+
+## Start it: a prompt, not a preset task
+
+Super Commit is started with a prompt id:
+
+```bash
+hagi hagitask create --title <title> --project-id <project-id> --prompt-id auto-compose-commit.en-US --json
+```
+
+Use the locale that matches the user's language in place of `en-US`. The prompt id alone marks the session as a Super Commit.
+
+Super Commit is a prompt, not a preset task. It has no preset task id and no schema, so `hagi hagitask schema` does not apply to it. Do not pass `--task-id` or `--input` for it.
+
+Use the name Super Commit in your explanation to the user. The prompt id appears only inside commands.
+
+## Options
+
+Every option below is accepted by `hagi hagitask create`. The CLI checks these rules before any network call, and a violation is a usage error with exit code `2`.
+
+| Option | Meaning |
+| --- | --- |
+| `--repository-path <path>` | MonoSpecs sub-repository to commit in, for example `repos/cli`. |
+| `--need-push` | Publish the commits after they are created. Add it only when the user asked for a push. |
+| `--pull-rebase` | Run `git pull --rebase` before the push. It has effect only with `--need-push`, and only when the run stays on the current branch. |
+| `--target-branch-mode <mode>` | Which branch the commits go on. Modes are below. |
+| `--target-branch-name <name>` | Name of the branch to create. It needs `--target-branch-mode new-custom`. |
+
+Branch modes:
+
+- `current`: commit on the branch that is checked out now.
+- `new-custom`: create the branch named by `--target-branch-name` before the first commit. It needs a name. `--target-branch-name` without this mode is a usage error.
+- `ai-generated-new`: create a new branch with a name the backend generates, before the first commit.
+
+## Server-owned choices
+
+The Git identity, the co-author trailer and the sign-off setting come from the user's saved server settings. The CLI has no option for them.
+
+Do not invent a flag for them, and do not put them in `--message`. If the user wants a different co-author for a run, tell them that the CLI has no option for it and ask them to change the saved setting.
+
+## Read the result
+
+After the session settles (see "Who drives each step"), read the final message:
+
+```bash
+hagi hagitask messages --session-id <id> --last 1
+```
+
+The run ends with a result block:
+
+- `## Commits Created`: every planned commit was made, and the push happened if one was requested.
+- `## Commits Incomplete`: at least one commit failed, files were left uncommitted, or a requested push was skipped or failed.
+
+Then read these lines:
+
+- `**Commits:**` the commit count, for example `2`, or `1 of 2` when the run is incomplete.
+- `**Push:**` the push outcome, for example `pushed to origin/<branch>`, or `skipped (reason)`.
+- A numbered list of the commits, without hashes.
+
+Report the result as it is:
+
+- For `## Commits Created`: report the commit count and, if a push was requested, the push outcome.
+- For `## Commits Incomplete`: report what was left undone. Do not say the commit succeeded.
+- Retry through `hagi hagitask send --session-id <id> --content <text>` only when the user asks for it.
+
+The result contains no commit hashes. To read them, run `git log` in the target repository.
+
+## Explicit request
+
+Starting a Super Commit creates commits in a repository, and with `--need-push` publishes them. So:
+
+- Start one only when the user asked for it in this conversation.
+- Add `--need-push` only when the user asked for a push. If the user asks for a Super Commit and does not mention a push, leave `--need-push` out.
+- After `hagi proposal execute` and a settled wait, if code changes remain uncommitted, offer a Super Commit and wait for the user's answer. Do not start one.
+- Never start one as a side effect of another lifecycle command.
+
+The web Git tab runs the same feature.
+
+## Who drives each step
+
+| Step | Who |
+| --- | --- |
+| `hagi hagitask create --prompt-id auto-compose-commit.<locale>` | the agent, only on request |
+| The commit work | an AI run inside the backend |
+| Following the run | the agent, with `hagi hagitask get --session-id <id> --wait --json` |
+| Archiving the finished session | automatic, by the default rule `ai-commit-auto-archive` |
+
+Monitor the run with:
+
+```bash
+hagi hagitask get --session-id <id> --wait --json
+```
+
+Read the `status` and the `wait` object:
+
+- Optimizing, Openspecing, Executing and Archiving mean the run is still going.
+- WaitingForReply means a person must answer.
+- A timeout (exit code `31`) is reported with the last status. Do not retry in a loop.
+
+The default rule `ai-commit-auto-archive` archives the finished session automatically. So the agent runs no `archive` or `complete` for a Super Commit session. The rule is a user setting and may be off. Do not assume the session is archived: read `status`, and if the status is not Archived, report it as it is.