@nodeint/migent 0.1.5 → 0.1.7

package/dist/templates/migent/SKILL.md

@@ -6,166 +6,168 @@ description: Set up Migent in a project, or configure, run, inspect, and resume
 # Migent
 
 Migent runs a project's multi-stage agent workflows from the `migent` CLI.
-A workflow is a set of stages; each stage runs a role; a role uses a model
-name defined in `.migent/config.yaml`. Each run is a session.
-
-## Working rules
-
-- For an existing project, work from the root containing
-  `.migent/config.yaml`.
-- Read `.migent/config.yaml` and the relevant file under
-  `.migent/workflows/` before changing or running a workflow.
-- Before writing `.migent/config.yaml` or a file under `.migent/workflows/`,
-  read `.agents/skills/migent/references/schema-config.yaml` and
-  `.agents/skills/migent/references/schema-workflow.yaml`. They list every
-  accepted key. A key absent from those files is ignored.
-- Run `migent doctor --json` after editing configuration or workflows. If it
-  reports an outdated schema, run `migent migrate --yes`. Pass `--json` on
-  `config model` and `config role` writes too. The object includes the doctor
-  result.
+A workflow is a set of stages. A stage runs a role, or runs `verify` alone when `role` is omitted. A role uses a model name
+defined in `.migent/config.yaml`. Each run is a session, stored under
+`.migent/sessions/<session-id>/`.
+
+This skill is already in the prompt. Do not open its file again.
+
+## Rules
+
+- Work from the project root, the directory containing `.migent/config.yaml`.
+- Read `.migent/config.yaml` and the relevant `.migent/workflows/` file before
+  running a workflow.
+- Before writing either, read `.agents/skills/migent/references/schema-config.yaml`
+  and `schema-workflow.yaml` in the same folder. A key absent from them is
+  ignored. Then run `migent doctor --json`; if it reports an outdated schema,
+  run `migent migrate --yes`.
 - You have no terminal for prompts. Pass `--no-input` (or set
   `MIGENT_NO_INPUT=1`) to `init`, `config model`, and `config role`, and give
   every value as a flag.
-- Treat `.migent/sessions/` as generated, resumable state. Do not edit
-  `manifest.yaml`, `status.json`, `events.jsonl`, or files under
-  `executions/`. In a prepared session, write `task.md` and files next to
-  it before the first stage. Do not change `task.md` after that stage starts.
-- Preserve the user's task wording. Pass a one-line task in `--task`. Write
-  a longer task into `task.md` unchanged.
-- A workflow `session run` or `session continue` prints `session_id`,
-  `session_status`, `stop_reason`, `latest_decision`, and `outputs` on stdout.
-  Stderr carries stage boundaries and errors. A role run prints a table unless
-  `--json`. That JSON is the role result, not this object.
-- This skill is already in the prompt. Do not open its file again.
-- Do not read `task.md` or the documents it names. The stage agent reads
-  them. Still read `.migent/config.yaml` and the workflow file before starting.
-
-## Set up
-
-```
-migent init --no-input --provider <provider> --model <model-id> [--preset implement|plan] [--option KEY=VALUE] [--skill]
+- Do not edit generated session state: `manifest.yaml`, `status.json`,
+  `events.jsonl`, `metrics.json`, or anything under `executions/`.
+- Keep the user's task wording. Do not read `task.md` or the documents it
+  names; the stage agent does.
+- Never start a replacement session to reset limits or get past `blocked`.
+  Resume the same one.
+
+## Run a task
+
+`<workflow>` is a workflow id or a path to a workflow file.
+
+One-line task. The command runs until the session stops:
+
+```
+migent session run --workflow <workflow> --task "<task>"
+```
+
+Longer task. `<title>` is a display label such as `some task title`. The command prints a UUID `session_id`:
+
+```
+migent session prepare "<title>" --workflow <workflow>
+```
+
+Write the task, unchanged, to the printed `task_path` (plus any files next to it).
+Do not edit `task.md` once the first stage has started.
+Then:
+
+```
+migent session run --session <session-id> --workflow <workflow>
+```
+
+Dispatch only one stage: add `--once`.
+
+### Read the result
+
+A workflow run prints plain lines on stderr and leaves stdout empty. It does
+not print JSON, and it does not print the stage report.
+
+- `session_id: <id>` when the session is created.
+- `stage <id> · attempt <n> · <HH:MM:SS> · <provider>/<model> (<options>).` when a stage starts. A description follows the model when the stage has one.
+- `stage <id> · attempt <n> · <duration> · <outcome>.` when it finishes. A decision is `decision=<value>` on that line.
+- A completed session adds `completed · <duration>` and one `artifact: <absolute-path>` line per published file. The path starts at the filesystem root and names the published file, so the suffix stays, such as `plan.md`. Report those paths.
+- Exit 1, 3, 6, and 8 also print `response: executions/<id>/response.md`. Read that file to see why it stopped.
+- Exit 7 prints `verify: executions/<id>/turns/01/verify.md`.
+- A session that stops before it is completed ends with `Resume with:` and `migent session continue <session-id>`.
+
+- Do not pass `--verbose` or `--progress`. Do not use `session follow`.
+- If the command runs in the background, wait for its completion notice. Do not
+  add a watcher that waits on the same exit.
+
+### Exit codes
+
+Read the exit code first. Exit 0 with `completed ·` is a completed session.
+Exit 0 without that line is `--once` after a complete stage.
+
+| Exit | Meaning | What to do |
+| --- | --- | --- |
+| 0 | Completed, or with `--once` the stage is complete | Report each `artifact:` path when the session completed. |
+| 1 | Blocked, or with `--once` the stage is not complete | If the stage line says `blocked`: read the `response:` path, then resume with the user's answer (below), or plain `session continue` once the blocker is fixed in the workspace. Otherwise `session continue` keeps going. |
+| 2 | Configuration error | Run `migent doctor --json`, fix config. |
+| 3 | A stage failed and the command did not wait | Read the `response:` path, fix the cause, `session continue`. Continue runs the stage and does not sleep until an old `retry_at`. |
+| 4 | A route would exceed `max_revisions` | Review why the stage keeps being revised, then `session continue` for another batch. |
+| 5 | `--max-dispatches` spent | `session continue` if more stages are appropriate. |
+| 6 | A stage's `verify` stayed red | Read the `response:` path, fix the cause, `session continue`. |
+| 7 | A stage with no role failed `verify` | Read the `verify:` path, fix the tree, `session continue`. That reruns the commands and does not open a provider. |
+| 8 | `--once` or `--stage` hit a provider quota and did not wait | Read the `response:` path. `session continue` runs the stage and does not sleep until the recorded `retry_at`. |
+| 130 | Cancelled, including a wait that was disarmed | Ask the user before resuming. Continue does not sleep until an old `retry_at`. |
+
+A stopped session that is not `completed` is resumable. Do not call it done.
+
+### Resume
+
+```
+migent session continue <session-id>
+```
+
+Same command for a workflow session and a role session. Read `session_status`, then use one row.
+
+| Kind | When | What to run |
+| --- | --- | --- |
+| Workflow | Not `completed`, including a blocker already fixed in the workspace | The command above. Runs until the session stops and resets revision counts. A blocked stage runs again. |
+| Workflow | The user answered a blocked stage | Add `--reply "<reply>"`. That text is the whole prompt body. |
+| Workflow | One stage, then stop | Add `--once`. Revision counts stay. |
+| Role | `cancelled` | The command above. The cut-off turn resumes in the same execution. Omit `--reply`. |
+| Role | `active` | The command above. The last prompt is sent again. |
+| Role | `blocked` | Add `--reply "<reply>"`. That is the next user turn. With no reply, the agent is only told to continue. |
+| Role | `completed` | Leave it stopped. Add `--reply` only to give a new turn. |
+
+`--reply-file <path>` is a longer reply. Pass only one of `--reply` and `--reply-file`. Do not pass `--once` or `--stage` on a role session.
+
+## Check a session
+
+```
+migent session show <session-id> --json
+migent session list --latest --json
+```
+
+`show` gives status, latest execution, decision, and outputs. `list --latest`
+is the newest session, or `null`. Both include `title` when the session has one.
+Report the session ID, title, status, stop reason,
+decisions, and the outputs that matter. Output paths are relative to
+`.migent/sessions/<session-id>/`; use the paths Migent reports.
+
+## Set up a project
+
+```
+migent provider list --json
+migent init --no-input --provider <provider> --model <model-id> [--preset implement|plan] [--skill]
 migent doctor --json
 ```
 
-`--provider` and `--model` go together. `--preset` picks the workflow to
-create (default `implement`). `--skill` installs this skill at
-`.agents/skills/migent`; `migent skill update` refreshes a managed copy.
-
-## Run
-
-`migent session run` runs a workflow when `--workflow` is set, and one role
-when `--workflow` is omitted.
-
-- Start a one-line task: `migent session run --workflow <workflow> --task "<task>"`.
-  `<workflow>` is a workflow id, or a path to a workflow file (the `id`
-  field defaults to the file name). The sentence is stored in `task.md`.
-  `--task` must be one line. Runs until the session stops.
-- Start a longer task: `migent session prepare <some-id> --workflow <workflow>`.
-  `<some-id>` is a lowercase slug such as `wave-3` (letters, digits, and
-  single hyphens). Write `.migent/sessions/<some-id>/task.md`, then
-  `migent session run --session <some-id> --workflow <workflow>`.
-  `session continue` does not start a prepared session.
-- Start and dispatch one stage only: add `--once`. `--once` requires `--workflow`.
-- If the workflow's `requires` block names a prerequisite workflow and
-  decision, find it with
-  `migent session list --workflow <workflow-id> --status completed --json`
-  and pass `--prior <session-id>`. `session continue` accepts `--prior` too.
-- Resume an active workflow session: `migent session continue <session-id>`.
-  This resets revision counts. `migent session continue <session-id> --once`
-  advances one stage and does not reset them. A blocked session runs that stage
-  again. `migent session continue <session-id> --reply "<reply>"` sends the
-  reply as the new execution's prompt body. Use `--reply-file <path>` for a
-  longer reply. When more than one stage is blocked, pass `--stage`. Without
-  `--reply`, the prompt includes the blocker and the previous response.
-  A cancelled session is resumed the same way, on the same execution: a cut-off
-  provider turn is sent again, and a cut-off verify runs again. Ask the user
-  before resuming a cancellation.
-- Run one role: `migent session run --role <role> --prompt "<prompt>"`.
-  `roles.<role>.instructions` in config, when set, is prepended to that prompt.
-  Use `--file <path>` or `--stdin` for a long prompt. `--task` labels a new
-  role session and cannot be combined with `--session <session-id>`, which
-  continues an earlier role session. `--provider`/`--model` (together) and
-  `--option KEY=VALUE` override the role for this turn. Add `--json` for one
-  result object. Exit 0 means the outcome is complete, 1 not complete.
-- Read the JSON result on stdout for a workflow run. Do not pass `--verbose`
-  or `--progress`. `--verbose` inlines every stage response. `--progress`
-  prints each tool call.
-- Exit 1, 3, and 6 also include `latest_execution_id` and `response_path`,
-  relative to `.migent/sessions/<session-id>/`. Read that file when you must
-  fix the execution.
-- Stderr is not the outcome. Do not read the command log while a run is healthy.
-- When `session run` or `session continue` is in the background, wait for that
-  command's completion notice. Do not add a watcher that only waits for the same exit.
-- To check a run without waiting on the command, use
-  `migent session show <session-id> --json` once.
-- Do not run `session follow` or `--cursor`.
-
-Limits, accepted by workflow `session run` and by `session continue`:
-
-- `--attempts <n>`: failed executions allowed for one stage (default 3). On
-  `session continue` it sets a new total, not extra retries.
-- `--max-dispatches <n>`: stage dispatches allowed in this command (default
-  20). `--unlimited-dispatches` removes the ceiling; use it only if the user
-  agrees.
-
-### Exit codes and stop reasons
-
-A workflow result on stdout includes `stop_reason`. Read the exit code first.
-
-| Exit | Meaning | `stop_reason` | Session | What to do |
-| --- | --- | --- | --- | --- |
-| 0 | Completed (with `--once`: stage complete) | | completed or advancing | Report outputs. |
-| 1 | Blocked (with `--once`: stage not complete) | `blocked`, or `stage` with `--once` | blocked, or active with `--once` | When `stop_reason` is `blocked`, read `response_path`. Pass the user's words with `session continue --reply`, or `session continue` without `--reply` after the blocker is fixed in the workspace. When `stop_reason` is `stage`, `session continue` keeps going. |
-| 2 | Configuration error | | unchanged | Run `migent doctor --json`, fix config. |
-| 3 | `--attempts` spent | `retry_exhausted` | active | Read `response_path`, fix the cause, then `session continue` (add `--attempts` for a higher total). |
-| 4 | A route would exceed `max_revisions` | `revisions_exhausted` | active | Review why the stage keeps being revised; `session continue` (without `--once`) resets counts for another batch. |
-| 5 | `--max-dispatches` spent | `dispatch_limit` | active | `session continue` the same session if more stages are appropriate. |
-| 130 | Cancelled | | see snapshot | Ask the user before resuming. `session continue` resumes that same execution. |
-
-A stopped active session is resumable; do not describe it as completed. A
-blocked session is resumed the same way: `session continue` runs that stage
-again. Do not start a replacement session to reset limits or to get past
-`blocked`. If you change a workflow or
-config while a session is active, that session keeps the workflow, models, and
-role instructions it started with. Run `migent doctor --json` and tell the user.
-`migent session continue <session-id> --refresh-workflow` adopts the current
-workflow, models, and role instructions. `session run --session <id> --workflow <workflow> --refresh-workflow`
-does the same when starting a prepared session.
-
-## Inspect sessions
-
-- Newest match: `migent session list --latest --json`. Add `--workflow <id>` and
-  `--status active|prepared|completed|blocked|cancelled` to narrow it. `--limit <n>`
-  returns the newest n rows. Do not combine `--latest` with `--limit`.
-- `--latest --json` is one object, or `null` when nothing matches. A list is
-  a JSON array. Snapshot: `migent session show <session-id> --json` has the
-  status, latest execution, decision, and outputs. JSON omits the task text.
-- Compare runs with `migent session metrics --json`. One session is one
-  object. Several sessions are one object per line, newest first.
-  `--workflow`, `--status`, and `--limit` match `session list`. Read
-  `usage_missing` and `uncaptured_turns` before comparing totals.
-  `stage_attempt` is not a retry count.
-- `session follow` streams the event trace for a person at a terminal.
-  Do not use it or `--cursor` to coordinate a run.
-
-Report the session ID, status, stop reason, decisions, and published outputs
-that matter to the user. Published output paths are relative to
-`.migent/sessions/<session-id>/`; use the paths Migent reports instead of
-guessing.
-
-## Configure models and roles
-
-- Show: `migent config` or `migent config show`.
-- List models or roles: `migent config model --json`,
-  `migent config role --json`.
-- Change a model name:
-  `migent config model <name> --provider <provider> --model <model-id> --no-input --json`.
-  This updates every role and stage that uses the name. Use
-  `--option KEY=VALUE` and `--clear-option KEY` for provider options.
-- Point roles at an existing model name:
-  `migent config role <role>... --model-name <name> --no-input --json`. The value is
-  a name from `models`, not a provider model id.
-- Override one role without touching the shared name:
-  `migent config role <role> --provider <provider> --model <model-id> --no-input --json`.
-- `roles.<name>.instructions` is an optional list of strings. A stage prompt
-  includes it before that stage's instructions. A role run prepends it to the prompt.
+`--provider` and `--model` go together. The default preset is `implement`.
+`provider list --json` shows which provider CLIs are on PATH and what model
+ids each supports. Use it to pick a `<provider>` and `<model-id>` for `init`.
+`--skill` installs this skill; `migent skill update` refreshes it.
+
+## Change models
+
+Edit a model name (updates every role and stage that uses it):
+
+```
+migent config model <name> --provider <provider> --model <model-id> --no-input --json
+```
+
+Show the config with `migent config`, `migent config model --json`, or
+`migent config role --json`.
+
+## Look up anything else
+
+This skill covers the common path. Every command takes `--help`; use it before
+guessing a flag:
+
+```
+migent --help
+migent session run --help
+```
+
+References, read only when the task needs them:
+
+| File | Read when |
+| --- | --- |
+| `references/schema-config.yaml`, `references/schema-workflow.yaml` | Writing config or a workflow. |
+| `references/sessions.md` | Prerequisite session (`--prior`), several blocked stages (`--stage`), resuming a cancelled session, raising limits, adopting workflow edits (`--refresh-workflow`). |
+| `references/config.md` | Running one role, pointing roles at another model, overriding one role, role instructions. |
+| `references/inspect.md` | Filtering `session list`, comparing runs with `session metrics`, `session follow`. |
+
+All paths are under `.agents/skills/migent/`.

package/dist/templates/migent/references/config.md

@@ -0,0 +1,56 @@
+# Roles and model configuration
+
+Write commands take `--no-input --json`. The JSON includes the doctor result.
+
+Run `migent provider list --json` to see which provider CLIs are available
+and what model ids each supports. Use that output to pick a provider and
+model id before using `config model` or `init`.
+
+## Run one role
+
+Without `--workflow`, `session run` runs a single role:
+
+```
+migent session run --role <role> --prompt "<prompt>"
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--file <path>`, `--stdin` | Supply a long prompt. |
+| `--task` | Labels a new role session. Cannot be combined with `--session`. |
+| `--session <session-id>` | Sends a new prompt to an earlier role session. `session continue <session-id>` resumes a stopped role session. |
+| `--provider`, `--model` | Override the role for this turn. Pass together. |
+| `--option KEY=VALUE` | Override a provider option for this turn. |
+| `--json` | Print one result object (the role result, with `outcome_status`; not the workflow result). |
+
+Without `--json` it prints a table. Exit 0 means the outcome is complete, 1
+not complete. `roles.<role>.instructions`, when set, is prepended to the prompt.
+
+## Model names
+
+Provider options on a model name: `--option KEY=VALUE` to set,
+`--clear-option KEY` to remove.
+
+```
+migent config model <name> --provider <provider> --model <model-id> --no-input --json
+```
+
+## Point roles at an existing model name
+
+The value is a name from `models`, not a provider model id.
+
+```
+migent config role <role>... --model-name <name> --no-input --json
+```
+
+## Override one role without touching the shared name
+
+```
+migent config role <role> --provider <provider> --model <model-id> --no-input --json
+```
+
+## Role instructions
+
+`roles.<name>.instructions` is an optional list of strings. A stage prompt
+includes it before that stage's instructions. A role run prepends it to the
+prompt.

package/dist/templates/migent/references/inspect.md

@@ -0,0 +1,32 @@
+# Inspecting many sessions
+
+For one session use `migent session show <session-id> --json` (SKILL.md).
+
+## List
+
+```
+migent session list --workflow <id> --status completed --limit 5 --json
+```
+
+- Output is a JSON array. `--latest` gives one object, or `null`; do not
+  combine it with `--limit`.
+- `--status` is one of `active|prepared|completed|blocked|cancelled|corrupt`.
+  A session whose `status.json` does not parse is listed as `corrupt`.
+- JSON rows omit the task text.
+
+## Metrics
+
+```
+migent session metrics --json
+```
+
+- One session prints its `metrics.json`. Several print one object per
+  line, newest first. Only a completed session has this file. `--workflow`,
+  `--status`, and `--limit` filter those rows.
+- Read `usage_missing` and `uncaptured_turns` before comparing totals.
+- `stage_attempt` is not a retry count.
+
+## Follow
+
+`session follow` streams the event trace for a person at a terminal. Do not use
+it or `--cursor` to coordinate a run.

package/dist/templates/migent/references/schema-config.yaml

@@ -2,9 +2,11 @@
 schema_version: 2
 
 # models.<name>.model is the provider model id.
+# models.<name>.client is optional: the CLI client id (agy, claude-code, codex, grok, opencode); required for provider byteplus
+# that drives this model. Omit it to use the provider's own client.
 # roles.<name>.default_model and a stage model are this name.
 # Options merge in order: model, then role, then stage.
-# Only keys the adapter marks overridable are stored on the provider session.
+# Only keys the provider marks overridable are stored on the provider session.
 models:
   planner:
     provider: grok
@@ -19,9 +21,16 @@ models:
     # disallowed_tools, max_budget_usd, fallback_model, and append_system_prompt.
     # codex accepts model_reasoning_effort (overridable). Any other key of letters, digits,
     # dots, underscores, and hyphens is passed through as codex exec -c.
+    # opencode accepts agent and thinking (true sends --thinking, false sends nothing). Neither is overridable.
     options:
       reasoning-effort: high
 
+  coder:
+    provider: byteplus
+    # byteplus has no CLI of its own, so client is required and names the CLI that runs it.
+    client: opencode
+    model: coding-plan/deepseek-v4-pro
+
 roles:
   planner:
     default_model: planner

package/dist/templates/migent/references/schema-workflow.yaml

@@ -13,15 +13,25 @@ requires:
   workflow: plan
 
 stages:
+  - id: prepare
+    description: Check the tree before the draft.
+    # No role: Migent runs verify and does not start an agent.
+    verify:
+      - pnpm build
+    verify_timeout: 1800
+    depends_on: []
+
   - id: draft
+    description: Write the draft.
     role: planner
     # model is a name under models in config.yaml, not a provider model id.
     model: planner
     # Options merge in order: model, then role, then stage.
-    # Only keys the adapter marks overridable are stored on the provider session.
+    # Only keys the provider marks overridable are stored on the provider session.
     options:
       reasoning-effort: high
-    depends_on: []
+    depends_on:
+      - prepare
     # max_revisions is allowed only when a route returns to this stage.
     max_revisions: 2
     instructions:

package/dist/templates/migent/references/sessions.md

@@ -0,0 +1,65 @@
+# Sessions: uncommon run and resume cases
+
+The everyday commands are in SKILL.md. This file covers the rest.
+
+## Prerequisite session (`--prior`)
+
+If the workflow's `requires` block names a prerequisite workflow and decision,
+find the session:
+
+```
+migent session list --workflow <workflow-id> --status completed --json
+```
+
+Then pass its id with `--prior <session-id>`. `session continue` accepts
+`--prior` too.
+
+## Several blocked stages
+
+When more than one stage is blocked, `session continue` needs the stage:
+
+```
+migent session continue <session-id> --stage <stage> --reply "<reply>"
+```
+
+The other stages stay blocked.
+
+## Cancelled session (exit 130)
+
+Ask the user first. `session continue <session-id>` resumes that same
+execution. A cut-off verify runs again. A cancelled stage with no role
+reruns its verify list in place and does not open a provider. Role status
+and `--reply` are in the skill's Resume section.
+
+## Limits
+
+Accepted by workflow `session run` and by `session continue`.
+
+| Flag | Meaning |
+| --- | --- |
+| `--max-dispatches <n>` | Stage dispatches allowed in this command (default 20). |
+| `--unlimited-dispatches` | Removes the dispatch ceiling. Use only if the user agrees. |
+
+A failed stage stays stopped until `session continue`. That command runs the
+stage and does not sleep until an old `retry_at`. Exit 3 is `stage_failed`.
+Exit 8 is `quota` for `--once` and `--stage`, which do not wait. Exit 130
+during a wait disarms the timer. A single role result uses 0, 1, and 130.
+Exit 6 remains only the path that reopened more than one role execution.
+
+## `--once` and revision counts
+
+`session continue <id>` resets revision counts. `session continue <id> --once`
+advances one stage and does not.
+
+## Config changed during a session
+
+A session keeps the workflow, models, and role instructions it started with.
+Later edits warn on stderr and do not change it. Run `migent doctor --json`
+and tell the user. To adopt the current versions:
+
+```
+migent session continue <session-id> --refresh-workflow
+migent session run --session <session-id> --workflow <workflow> --refresh-workflow
+```
+
+The second form is for starting a prepared session.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodeint/migent",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Compose AI coding agents into repeatable engineering workflows.",
   "keywords": [
     "ai",
@@ -43,9 +43,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "@nodeint/migent-adapters": "0.1.5",
-    "@nodeint/migent-kernel": "0.1.5",
-    "@nodeint/migent-registry": "0.1.5",
+    "@nodeint/migent-adapters": "0.1.7",
+    "@nodeint/migent-kernel": "0.1.7",
+    "@nodeint/migent-registry": "0.1.7",
     "commander": "^14.0.2",
     "picocolors": "^1.1.1"
   },