@akagilnc/pi-workflow-roles 0.1.2101 → 0.1.2107

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.2101",
+  "version": "0.1.2107",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/resources/engines/codex.md

@@ -0,0 +1,55 @@
+# codex engine method material
+
+This file is packaged method material for the optional `codex` labor engine
+(Codex CLI on the host). When a role run selects this engine, read these
+bytes and follow the local CLI's actual interface for the labor detour. Return
+the labor result to the same role session so typed submission stays on the
+existing in-session path.
+
+Material is data for the model, not a code contract. Do not invent package flags.
+
+## Invocation examples (local Codex CLI)
+
+The machine entrypoint is `codex`. Run from the role project root. Non-interactive
+labor uses `codex exec` (alias `e`). Always pass `--skip-git-repo-check` so the
+labor subprocess can start outside a Git work tree when needed:
+
+```bash
+codex exec --skip-git-repo-check "YOUR_LABOR_PROMPT"
+```
+
+For concurrent or disposable labor turns, add `--ephemeral` so session files are
+not persisted to disk:
+
+```bash
+codex exec --skip-git-repo-check --ephemeral "YOUR_LABOR_PROMPT"
+```
+
+Working-root override when the seat cwd is not the project root:
+
+```bash
+codex exec --skip-git-repo-check --ephemeral -C "$PROJECT_ROOT" "YOUR_LABOR_PROMPT"
+```
+
+Default (non-`--json`) mode prints the session banner and progress on stderr
+(measured on this host). Collect the labor body from stdout so that stderr log
+noise is not mixed into the returned body; the package idle clock can still see
+activity on both streams. Use `--json` only when the seat itself needs
+machine-readable event rows (those rows land on stdout as JSONL; measured event
+types include `thread.started`, `turn.started`, `item.completed`, `error`,
+`turn.failed`):
+
+```bash
+codex exec --skip-git-repo-check --ephemeral --json "YOUR_LABOR_PROMPT"
+```
+
+Prefer `codex exec --help` on the host over any remembered flag set. Do not wrap
+this engine behind `ak-role` flags. Later host quota/auth failures are separate
+from argv acceptance — re-check the local CLI if a turn fails after session start.
+
+When the package detour tool is available, start exactly one subprocess per
+labor invocation through it with argv assembled from this material and the
+local CLI; return the stdout labor content to the same session for the existing
+typed submission path. One labor turn = one process (not one process for the
+whole role run). If the detour fails, continue labor in-session on the seat main
+road and still submit via the existing typed path.

package/resources/engines/kimi.md

@@ -0,0 +1,61 @@
+# kimi engine method material
+
+This file is packaged method material for the optional `kimi` labor engine
+(Kimi Code CLI on the host). When a role run selects this engine, read these
+bytes and follow the local CLI's actual interface for the labor detour. Return
+the labor result to the same role session so typed submission stays on the
+existing in-session path.
+
+Material is data for the model, not a code contract. Do not invent package flags.
+
+## Invocation examples (local Kimi Code CLI)
+
+The machine entrypoint on this host is installed at `~/.kimi-code/bin/kimi`
+(put that directory on PATH, or pass the absolute path as argv[0]). Run from
+the role project root.
+
+Non-interactive labor uses `-p` / `--prompt` alone. On this host (kimi 0.36.1),
+`-p` cannot be combined with `--yolo` or `--auto` — both are rejected at parse
+time with `Cannot combine --prompt with --yolo.` / `... --auto.`. Do not add
+those flags to prompt-mode argv:
+
+```bash
+kimi -p "YOUR_LABOR_PROMPT"
+```
+
+Pin a model alias configured in the host `config.toml` when the seat needs a
+known Kimi model id (example alias shape measured: `kimi-code/k3-256k`):
+
+```bash
+kimi -m <model-alias> -p "YOUR_LABOR_PROMPT"
+```
+
+Use `--output-format stream-json` (choices measured on this host: `text`,
+`stream-json`; default is `text`) so the package idle clock can see subprocess
+activity while the engine works. Take the labor body from
+`{"role":"assistant","content":...}` rows, not from `role:meta` rows:
+
+```bash
+kimi -p "YOUR_LABOR_PROMPT" --output-format stream-json
+```
+
+Text / default mode when stream events are not needed. Measured on this host
+with separate fd redirects (`1>` / `2>`): stdout is the labor answer body;
+stderr carries the version line, thinking bullets, and the trailing
+`To resume this session:` hint. Collect the labor body from stdout only — do
+not treat resume lines as same-stream noise to strip from stdout (they are not
+on that stream; stripping bullet-shaped lines risks deleting answer content):
+
+```bash
+kimi -p "YOUR_LABOR_PROMPT" --output-format text
+```
+
+Prefer `kimi --help` on the host over any remembered flag set. Do not wrap this
+engine behind `ak-role` flags.
+
+When the package detour tool is available, start exactly one subprocess per
+labor invocation through it with argv assembled from this material and the
+local CLI; return the stdout labor content to the same session for the existing
+typed submission path. One labor turn = one process (not one process for the
+whole role run). If the detour fails, continue labor in-session on the seat main
+road and still submit via the existing typed path.

package/resources/engines/opus.md

@@ -11,21 +11,31 @@ Material is data for the model, not a code contract. Do not invent package flags
 ## Invocation examples (local Claude Code CLI)
 
 The machine entrypoint is `claude`. Run from the role project root. Non-interactive
-print mode (`-p` / `--print`) is verified available on this host:
+print mode (`-p` / `--print`) is verified available on this host.
+
+On this host (Claude Code 2.1.233), `--print` with `--output-format=stream-json`
+requires `--verbose` — without it the CLI exits immediately with
+`Error: When using --print, --output-format=stream-json requires --verbose`.
+Include `--verbose` in stream-json argv. Measured with separate fd redirects
+(`1>` / `2>`): NDJSON event rows land on stdout (including intermediate
+`system` / `assistant` activity and a final `type:"result"` row); stderr is
+empty on the success path:
 
 ```bash
-claude -p --output-format=stream-json "YOUR_LABOR_PROMPT"
+claude -p --verbose --output-format=stream-json "YOUR_LABOR_PROMPT"
 ```
 
-Pin the Opus model explicitly (`--model opus` verified accepted on this host):
+Pin the Opus model explicitly (`--model opus` verified accepted on this host;
+init event reports `claude-opus-5`):
 
 ```bash
-claude -p --model opus --output-format=stream-json "YOUR_LABOR_PROMPT"
+claude -p --model opus --verbose --output-format=stream-json "YOUR_LABOR_PROMPT"
 ```
 
-Use `--output-format=stream-json` (verified present on this host) so the package
-idle clock can see subprocess activity while the engine works; take the labor body
-from the final `result` event, not from intermediate stream rows.
+Use `--output-format=stream-json` (choices measured on this host: `text`, `json`,
+`stream-json`) so the package idle clock can see subprocess activity while the
+engine works; take the labor body from the final `result` event's `result` field,
+not from intermediate stream rows.
 
 Prefer `claude --help` on the host over any remembered flag set. Do not wrap this
 engine behind `ak-role` flags.