@akagilnc/pi-workflow-roles 0.1.2124 → 0.1.2133

package/package.json

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

package/resources/engines/agy.md

@@ -0,0 +1,27 @@
+# agy engine method material
+
+This file is packaged method material for the optional `agy` labor engine
+(Gemini-family 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 agy CLI)
+
+The machine entrypoint is `agy`. Run from the repository root of the role
+project (repo root matters for its sandbox). Non-interactive labor uses
+sandboxed print mode with the prompt as the positional/print argument and a
+log file for diagnostics:
+
+```bash
+agy --sandbox --print 'YOUR_LABOR_PROMPT' --log-file /tmp/agy-labor.log
+```
+
+- Treat a quota/auth error like any other engine failure (do not retry-loop).
+
+## Failure handling
+
+On any spawn, quota, or model failure, return the soft failure to the session
+and continue labor in-seat per ADR 0071 (seat fallback with typed declaration).

package/resources/engines/grok-4.6.md

@@ -0,0 +1,43 @@
+# grok-4.6 engine method material
+
+This file is packaged method material for the optional `grok-4.6` labor engine
+(Grok 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 Grok CLI)
+
+The machine entrypoint is `grok` (NOT `grok-4.6` — the engine name is the model
+id, not the executable). Run from the role project root. Non-interactive labor
+reads the prompt from a file and prints plain output:
+
+```bash
+grok --prompt-file /path/to/labor-prompt.md -m grok-4.6 --always-approve --output-format plain
+```
+
+- `-m grok-4.6` selects the model; `grok models` lists valid ids (currently
+  `grok-4.6` default, `grok-4.5`).
+- `--always-approve` keeps the run non-interactive (documented).
+- Official docs list `-p/--single` as the canonical headless prompt input;
+  `--prompt-file` exists in the installed CLI (`--help`) and is smoke-verified
+  on this host — prefer it for long prompts, fall back to `-p` if absent.
+- `--output-format plain` keeps stdout clean for capture — but it stays
+  silent until the run finishes. **For labor longer than ~2 minutes use
+  `--output-format streaming-json` instead**: it emits NDJSON events
+  (thought/text deltas) continuously from the first second, which keeps the
+  package idle watchdog fed (verified live 2026-08-21; a plain-format judge
+  run was killed by the 183s idle timeout). Reconstruct the final answer by concatenating each NDJSON
+  object's `data` where `type == "text"`, in stream order; `type == "end"`
+  (stopReason end_turn) marks completion. Do not treat `thought` events as
+  the answer (live-verified stream shape 2026-08-21).
+- Reasoning effort follows the host CLI defaults; grok effort tiers are
+  low/med/high when a flag is exposed by the installed CLI version — check
+  `grok --help` and follow the actual interface. Do not invent flags.
+
+## Failure handling
+
+On any spawn or model-id failure, return the soft failure to the session and
+continue labor in-seat per ADR 0071 (seat fallback with typed declaration).

package/resources/engines/opencode.md

@@ -0,0 +1,32 @@
+# opencode engine method material
+
+This file is packaged method material for the optional `opencode` labor engine
+(OpenCode CLI on the host; the GLM cheap-pool leg runs through it). 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 OpenCode CLI)
+
+The machine entrypoint is `opencode`. Run from the role project root.
+Non-interactive labor uses `run` with an explicit model:
+
+```bash
+opencode run -m opencode-go/glm-5.2 "YOUR_LABOR_PROMPT"
+```
+
+- `-m provider/model` selects the model. **Always confirm the current id with
+  `opencode models` first** — provider prefixes migrate (verified 2026-08-21:
+  GLM lives under `opencode-go/`, e.g. `opencode-go/glm-5.2`; the older
+  `zai/glm-5.2` id errors with "Unexpected server error").
+- `--format json` gives structured output; `--auto` auto-approves non-denied
+  permissions for unattended runs (both per official docs).
+- Output goes to stdout; long prompts may be passed via shell heredoc or a
+  file read into the argument — follow the installed CLI's actual interface.
+
+## Failure handling
+
+On any spawn or model failure, return the soft failure to the session and
+continue labor in-seat per ADR 0071 (seat fallback with typed declaration).