workflow-supervisor 0.1.0 → 0.1.1

package/docs/artifacts.md

@@ -4,13 +4,15 @@
 
 Default location: create Markdown workflow artifacts under `<workspace>/.workflow/`. Use another directory only when the user names one, the project already has a clearer workflow-state convention, or the artifact is a final deliverable that belongs elsewhere.
 
+In Git-backed codebases, `.workflow/` is local working state. Ensure `<workspace>/.gitignore` contains `.workflow/` before creating artifacts there, and do not commit that directory unless the user explicitly makes workflow state a deliverable.
+
 ## Workflow Control
 
 - `.workflow/WORKFLOW.md`
 - `.workflow/SOURCE-CORPUS.md`
 - `.workflow/WORK-UNITS.md`
 - `.workflow/DOSSIER.md`
-- `.workflow/THREAD-MAP.md`
+- `.workflow/WORKER-MAP.md`
 - `.workflow/ACCEPTANCE-MATRIX.md`
 - `.workflow/VERIFICATION-REPORT.md`
 - `.workflow/REPAIR-TICKETS.md`
@@ -37,4 +39,4 @@ Default location: create Markdown workflow artifacts under `<workspace>/.workflo
 
 ## State Medium
 
-Markdown is the default, but state may also be an inline brief, spreadsheet tab, ticket set, design annotation, CRM note, runbook, decision log, slide appendix, whiteboard note, or chat handoff.
+Markdown is the default, but state may also be an inline brief, spreadsheet tab, ticket set, design annotation, CRM note, runbook, decision log, slide appendix, whiteboard note, or chat continuation note.

package/docs/cli.md

@@ -25,30 +25,39 @@ workflow-supervisor list
 
 ### `validate`
 
-Validate skill folder structure, `SKILL.md` frontmatter, required metadata, and opt-in policy.
+Validate skill folder structure, `SKILL.md` frontmatter, required metadata, opt-in policy, adapter metadata, and the `WorkerReportV1` and `DossierV1` schema artifacts.
 
 ```bash
 workflow-supervisor validate
 ```
 
+### `validate-dossier`
+
+Validate one machine-checkable `DossierV1` contract before delegation. The command accepts JSON, YAML, or fenced YAML in a Markdown file.
+
+```bash
+workflow-supervisor validate-dossier .workflow/dossiers/U1-implementer.yaml --role implementer --unit U1 --json
+```
+
+The validator rejects missing fields, unresolved open questions, broad mutable surfaces such as `all files`, missing forbidden surfaces, role mismatches, unit mismatches, missing acceptance rows, and worker prompts that do not require `WorkerReportV1`.
+
 ### `doctor`
 
 Print package, target, and skill discovery information.
 
 ```bash
 workflow-supervisor doctor --agent codex
+workflow-supervisor doctor --agent claude-code
 workflow-supervisor doctor --agent generic --target ./agent-skills
 ```
 
 ### `install`
 
-Install skills into an agent target.
+Install skills into a supported agent target.
 
 ```bash
 workflow-supervisor install --agent codex
-workflow-supervisor install --agent claude-code --target ~/.claude/skills
-workflow-supervisor install --agent opencode --target ~/.config/opencode/skills
-workflow-supervisor install --agent hermesagent --target ~/.hermes/skills
+workflow-supervisor install --agent claude-code
 workflow-supervisor install --agent generic --target ./agent-skills
 workflow-supervisor install --agent all --scope project --project .
 workflow-supervisor uninstall --agent codex --scope user
@@ -57,10 +66,10 @@ workflow-supervisor uninstall --agent codex --scope user
 Options:
 
 ```text
---agent codex|claude-code|opencode|hermesagent|generic|all
+--agent codex|claude-code|generic|all
 --scope user|project  Install to user-level or project-level location where supported.
 --project <path>      Project root for project-scope installs.
---target <path>       Override install directory. Required for generic.
+--target <path>       Override install directory. Required for generic installs.
 --skills all|a,b      Install all skills or a comma-separated subset.
 --force               Replace existing installed skill folders.
 --dry-run             Validate and print intended action without writing.
@@ -75,13 +84,11 @@ Default targets:
 | Codex | project | `<project>/.agents/skills` |
 | Claude Code | user | `${CLAUDE_HOME:-~/.claude}/skills` |
 | Claude Code | project | `<project>/.claude/skills` |
-| OpenCode | user | `${OPENCODE_HOME:-~/.config/opencode}/skills` |
-| OpenCode | project | `<project>/.opencode/skills` |
-| HermesAgent | user | `${HERMESAGENT_HOME:-${HERMES_HOME:-~/.hermes}}/skills` |
-| HermesAgent | project | `<project>/.hermes/skills` |
 | Generic | any | requires `--target` |
 
-HermesAgent project scope is a package-local convention for portable installs. Use `--target` if your HermesAgent setup expects another directory.
+`--agent all` installs only the certified target set: Codex and Claude Code. Use `generic` with `--target` when you want a Markdown instruction bundle for another environment.
+
+Project-scope installs also ensure `<project>/.gitignore` contains `.workflow/`. Workflow artifacts are local supervisor state by default and should not be pushed with the consuming repository unless the user explicitly makes them deliverables.
 
 ### `uninstall`
 
@@ -94,17 +101,17 @@ workflow-supervisor uninstall --agent generic --target ./agent-skills
 
 ### `emit-context`
 
-Create a portable instruction file for agents that do not natively discover `SKILL.md` folders. The output embeds the selected `SKILL.md` files and bundled Markdown references, so the receiving agent can use the skills without separately reading the skill directory.
+Create a portable instruction file for a Markdown-reading workspace. The output embeds the selected `SKILL.md` files and bundled Markdown references, so the receiving agent can use the skills without separately reading the skill directory.
 
 ```bash
 workflow-supervisor emit-context --agent generic --target ./agent-skills --out AGENTS.md
-workflow-supervisor emit-context --agent opencode --skills workflow-supervisor,workflow-docs --out AGENTS.md
+workflow-supervisor emit-context --agent claude-code --skills workflow-supervisor,workflow-docs --out CLAUDE.md
 ```
 
 Options:
 
 ```text
---agent codex|claude-code|opencode|hermesagent|generic
+--agent codex|claude-code|generic
 --scope user|project
 --project <path>
 --target <path>
@@ -113,6 +120,61 @@ Options:
 --root <path>         Use another package root.
 ```
 
+### `delegate`
+
+Run one role-scoped worker through an installed Codex or Claude Code CLI and print exactly one normalized `WorkerReportV1` JSON object. Missing or invalid `DossierV1` contracts, missing CLIs, invalid worker output, timeouts, non-zero PASS results, PASS without evidence, forbidden-surface changes, and verifier mutations become `BLOCKED` reports instead of unstructured prose.
+
+The report schema lives at `schemas/worker-report-v1.schema.json`. The Codex adapter passes it via `--output-schema`; the Claude Code adapter passes it via `--json-schema`; every adapter is still wrapper-validated after the run.
+
+`--dossier` is a hard preflight gate. It must parse as `DossierV1` and pass concrete-field checks before the worker process starts. The delegate command uses `allowed_surfaces` and `forbidden_surfaces` from the dossier as surface guards unless explicit CLI surface flags are provided.
+
+```bash
+workflow-supervisor delegate --agent codex --role implementer --unit U1 --cwd . --dossier .workflow/DOSSIER.md --allowed-surfaces src,tests
+workflow-supervisor delegate --agent claude-code --role verifier --unit U1 --cwd . --dossier .workflow/DOSSIER.md --forbidden-surfaces src
+```
+
+Options:
+
+```text
+--agent codex|claude-code
+--role implementer|verifier|repair|documenter
+--unit <id>                 Work unit ID copied into WorkerReportV1.
+--cwd <path>                Workspace for the worker command. Defaults to current directory.
+--dossier <path>            Role-scoped dossier to include in the worker prompt.
+--allowed-surfaces a,b      Optional comma-separated mutable boundaries.
+--forbidden-surfaces a,b    Optional comma-separated forbidden boundaries.
+--timeout-ms <ms>           Subprocess timeout. Defaults to 120000.
+--allow-dirty              Allow mutable delegation when git status is already dirty.
+--adapter-command <json>    Override the adapter command as a JSON array of strings.
+--prompt-mode stdin|arg     Send the prompt on stdin or as the final argument. Overrides default only with --adapter-command.
+```
+
+Adapter commands live in `adapters/<agent>/adapter.json` as command arrays, not shell strings. Use `--adapter-command` for local testing or platform setups whose executable name differs from the default. Override commands run with `--cwd` as their working directory, so use absolute paths for custom scripts unless they live in that workspace.
+
+### `delegate-doctor`
+
+Inspect a delegate adapter. Without `--probe`, this checks whether the executable is present. With `--probe`, it runs a trivial worker delegation and validates the normalized report path.
+
+```bash
+workflow-supervisor delegate-doctor --agent all
+workflow-supervisor delegate-doctor --agent all --probe --require-pass
+workflow-supervisor delegate-doctor --agent claude-code
+workflow-supervisor delegate-doctor --agent codex --adapter-command '["codex","exec","--json"]' --probe
+```
+
+Options:
+
+```text
+--agent codex|claude-code|all
+--adapter-command <json>    Override the adapter command as a JSON array of strings.
+--prompt-mode stdin|arg
+--probe                    Run a trivial WorkerReportV1 delegation check.
+--require-pass             Exit nonzero when any inspected adapter is BLOCKED.
+--cwd <path>
+```
+
+Use `workflow-supervisor delegate-doctor --agent all --probe --require-pass` as the certification gate in CI or in an environment where both target CLIs are installed. The command still prints JSON diagnostics when it exits nonzero.
+
 ## Exit Codes
 
 - `0`: command succeeded

package/docs/compatibility.md

@@ -1,12 +1,12 @@
 # Agent Compatibility
 
-The pack is built around portable `SKILL.md` folders. Codex consumes those folders directly. Other agents can use the same content as explicit prompt skills, context packs, or project-local instructions.
+The certified support set is intentionally small: Codex and Claude Code for automated delegation, plus `generic` for emitting or installing Markdown instructions into a custom directory.
 
-## Skills, Threads, And Subagents
+## Skills And Workers
 
-Loading a skill does not spawn a thread or subagent. A skill is instruction context for the current agent until the environment explicitly uses a separate execution tool.
+Loading a skill does not spawn a worker, thread, or subagent. A skill is instruction context for the current agent until the supervisor uses an approved delegation mechanism.
 
-`$workflow-supervisor` can plan worker threads or subagents, but they start only after complete intake, the workflow path gate, a concrete dossier, and target-environment delegation support are all satisfied. If those tools are unavailable or user-visible thread creation is not approved, use the generated handoff prompts or workflow docs as the fallback.
+`$workflow-supervisor` can plan role-scoped workers, but they start only after complete intake, the workflow path gate, a concrete dossier, and target-environment delegation support are all satisfied. The portable mechanism is the one-shot `workflow-supervisor delegate` command described in [portable-delegation.md](portable-delegation.md). Native Codex threads or Claude subagents are adapter optimizations, not workflow requirements.
 
 ## Codex
 
@@ -32,54 +32,28 @@ Use $workflow-supervisor to supervise this migration. It should ask the complete
 
 ## Claude Code
 
-Claude Code environments vary by local setup. Install to the skill or prompt directory your setup uses, or choose a project-local target.
+Claude Code support uses the same `SKILL.md` folders and the `claude` CLI for one-shot delegated workers.
 
 ```bash
-npx workflow-supervisor install --agent claude-code --target ~/.claude/skills
+npx workflow-supervisor install --agent claude-code --scope user
+npx workflow-supervisor install --agent claude-code --scope project --project .
 ```
 
 If native discovery is unavailable, emit a context file:
 
 ```bash
-npx workflow-supervisor emit-context --agent claude-code --target ~/.claude/skills --skills workflow-supervisor,workflow-docs --out CLAUDE.md
+npx workflow-supervisor emit-context --agent claude-code --skills workflow-supervisor,workflow-docs --out CLAUDE.md
 ```
 
 Codex goal APIs degrade to `.workflow/GOAL-STATE.md` and workflow docs.
 
-## OpenCode
-
-Install to an OpenCode skill/prompt directory or project-local target:
-
-```bash
-npx workflow-supervisor install --agent opencode --target ~/.config/opencode/skills
-npx workflow-supervisor install --agent opencode --scope project --project .
-```
-
-If OpenCode does not read `agents/openai.yaml`, ignore that file and invoke by explicit skill names from `SKILL.md`.
-
-## HermesAgent
-
-Install to the HermesAgent skill/prompt directory configured by your environment:
-
-```bash
-npx workflow-supervisor install --agent hermesagent --target ~/.hermes/skills
-npx workflow-supervisor install --agent hermesagent --scope project --project .
-```
-
-User scope follows HermesAgent's documented `~/.hermes/skills` location. Project scope uses the package-local fallback `<project>/.hermes/skills` so `--agent all --scope project` can create a complete portable skill bundle.
-
-If native discovery is unavailable:
-
-```bash
-npx workflow-supervisor emit-context --agent hermesagent --target ~/.hermes/skills --skills workflow-supervisor,workflow-docs --out HERMES.md
-```
-
 ## Generic Agent
 
-Use `generic` for any agent that can read a directory of Markdown instructions.
+Use `generic` only for Markdown instruction export or installation into a custom directory. It is not a certified automated delegation adapter.
 
 ```bash
 npx workflow-supervisor install --agent generic --target ./agent-skills
+npx workflow-supervisor emit-context --agent generic --skills workflow-supervisor,workflow-docs --out AGENTS.md
 ```
 
-Then point the agent at `./agent-skills/WORKFLOW_SKILL_PACK.md` and the individual `SKILL.md` files.
+Then point the receiving agent at `./agent-skills/WORKFLOW_SKILL_PACK.md`, the individual `SKILL.md` files, or the emitted context file.

package/docs/portable-delegation.md

@@ -0,0 +1,189 @@
+# Portable Delegation
+
+The workflow pack must stay a small skill pack. It must not become a daemon, queue, server, scheduler, dashboard, or full agent harness. The portable execution primitive is one supervised, one-shot delegation to an already-installed Codex or Claude Code CLI.
+
+## Goal
+
+Keep the same workflow semantics on Codex and Claude Code:
+
+```text
+complete intake
+-> source grounding
+-> work units
+-> role-scoped implementer delegation
+-> role-scoped verifier delegation
+-> repair delegation only when verification fails or blocks with actionable findings
+-> re-verification
+-> documenter or outcome delegation when evidence exists
+-> final supervisor report
+```
+
+The supervisor remains the only coordinator. Workers do not ask the human questions, choose final disposition, expand scope, approve plans, or talk to each other. If a worker needs a decision, it returns `BLOCKED` with a `blocking_question`; only the supervisor asks the user.
+
+## Non-Goals
+
+- No long-running workflow daemon.
+- No queue or mailbox protocol.
+- No manual copy/paste handoff as the primary path.
+- No platform-specific workflow semantics.
+- No claim of automated delegation support for OpenCode, HermesAgent, Pi/PiAgent, OpenClaw, or other agents in this package version.
+- No guarantee that every worker succeeds.
+- No guarantee that every platform produces identical prose.
+
+The guarantee is narrow and testable: Codex and Claude Code either return the same `WorkerReportV1` shape from [worker-report-v1.schema.json](../schemas/worker-report-v1.schema.json), or the delegate command returns a normalized `BLOCKED` report explaining why it could not.
+
+Delegation also requires a concrete `DossierV1` contract from [dossier-v1.schema.json](../schemas/dossier-v1.schema.json). A missing, vague, or role-mismatched dossier blocks before any worker CLI starts.
+
+## Primitive
+
+Use one small command in the existing npm package:
+
+```bash
+workflow-supervisor delegate \
+  --agent <codex|claude-code> \
+  --role <implementer|verifier|repair|documenter> \
+  --unit <unit-id> \
+  --cwd <workspace> \
+  --dossier <path>
+```
+
+The command does five things:
+
+1. Validates the supervisor dossier as `DossierV1`.
+2. Builds a role-scoped prompt from the supervisor dossier and report schema.
+3. Spawns the selected agent CLI with an adapter command array, not shell interpolation.
+4. Captures stdout, stderr, exit code, timeout, and optional JSON or JSONL events.
+5. Extracts and validates a `WorkerReportV1` object.
+6. Runs post-run guards and prints one normalized JSON report to stdout.
+
+There is no resident process. Each worker is a fresh, isolated delegation.
+
+## WorkerReportV1
+
+Every adapter must normalize into this shape:
+
+```json
+{
+  "schema": "WorkerReportV1",
+  "status": "PASS",
+  "role": "verifier",
+  "unit_id": "U2",
+  "summary": "",
+  "changed_surfaces": [],
+  "evidence": [],
+  "checks_run": [],
+  "skipped_checks": [],
+  "findings": [],
+  "blocking_question": null,
+  "next_action": "",
+  "adapter": {
+    "agent": "codex",
+    "command": "codex exec",
+    "exit_code": 0,
+    "timed_out": false
+  },
+  "guard": {
+    "allowed_surface_violations": [],
+    "role_violations": []
+  }
+}
+```
+
+`PASS`, `FAIL`, and `BLOCKED` mean the same thing on both platforms. A worker report without evidence for material acceptance rows is invalid. Invalid output is converted into a deterministic normalized `BLOCKED` report by default. The package does not make a second live worker call to repair formatting, because a second call can mutate state, consume budget, or produce another non-portable transcript.
+
+The schema is a package artifact at `schemas/worker-report-v1.schema.json`. Codex receives it through `--output-schema`; Claude Code receives it through `--json-schema`; both adapters are still wrapper-validated after the run.
+
+## Adapter Evidence
+
+The delegation design is grounded in documented one-shot or headless execution for the certified target platforms:
+
+| Agent | Automation primitive | Report confidence |
+|---|---|---|
+| Codex | `codex exec --json --skip-git-repo-check -c service_tier="fast" --output-schema <schema>` for scripted runs; prompt string or stdin; JSONL events; output schema support. | Strong |
+| Claude Code | `claude -p --output-format json --json-schema <schema>` print mode; piped input; JSON and stream JSON output; JSON schema support. | Strong |
+
+Use this as the certification gate in any environment claiming support:
+
+```bash
+workflow-supervisor delegate-doctor --agent all --probe --require-pass
+```
+
+The command prints structured diagnostics and exits nonzero when either adapter is missing, unauthenticated, or unable to produce `WorkerReportV1`.
+
+## Supervisor Semantics
+
+The supervisor does not generate every role for every unit up front. It follows the loop:
+
+- Implementer: when a unit is ready and mutable work is allowed.
+- Verifier: after implementer report or for read-only units.
+- Repair: only after verifier returns `FAIL` or actionable `BLOCKED`.
+- Re-verifier: only after repair.
+- Documenter: after planning evidence, implementation evidence, verification evidence, or final outcome evidence exists.
+
+This preserves the current input and output contract while replacing the transport:
+
+```text
+Codex thread tools or Claude-specific subagent mechanisms
+```
+
+become:
+
+```text
+workflow-supervisor delegate --agent <codex|claude-code> --role <role> --unit <unit>
+```
+
+## Required Guards
+
+The delegate command is small, but five guards are non-negotiable:
+
+1. `delegate-doctor`: proves the selected executable exists. With `--probe`, it runs a trivial delegation and verifies that the adapter can produce or be normalized into `WorkerReportV1`.
+2. `validate-dossier`: rejects missing fields, vague placeholders, broad mutable surfaces, unresolved open questions, role mismatches, unit mismatches, and worker prompts that do not require `WorkerReportV1`.
+3. Schema validation: rejects missing evidence, missing role/unit IDs, unknown statuses, and worker attempts to ask the human directly.
+4. Surface guard: captures before/after state and fails the report if the worker changed forbidden surfaces or if a read-only role changed files.
+5. Timeout and exit handling: converts hangs, crashes, auth failures, and non-zero exits into normalized `BLOCKED` reports.
+
+For git workspaces, the surface guard compares pre/post git status. Mutable roles block before delegation when the git workspace is already dirty unless `--allow-dirty` is set. For non-git workspaces, explicit `--allowed-surfaces` and `--forbidden-surfaces` are hashed and watched. If the guard cannot prove the relevant boundary, the report includes a guard warning and the supervisor must treat broad mutable delegation as unsafe.
+
+## What-If Matrix
+
+| What if | Answer |
+|---|---|
+| Agent CLI is missing | `delegate-doctor` fails; `delegate` returns normalized `BLOCKED` with `reason: adapter_cli_missing`. Supervisor asks for another supported agent or uses same-session phased mode only if intake allowed it. |
+| Agent is not authenticated | Return normalized `BLOCKED` with `reason: adapter_auth_unavailable`. |
+| Agent outputs Markdown around JSON | Extract the first valid `WorkerReportV1` object and validate it. |
+| Agent cannot produce valid report | Return normalized `BLOCKED`; do not treat prose as evidence. |
+| Dossier is vague | `validate-dossier` fails and `delegate` returns `BLOCKED` with `reason: invalid_dossier`; no worker starts. |
+| Worker edits forbidden files | Surface guard marks role violation; supervisor stops. No automatic revert unless explicitly allowed, because user changes may exist. |
+| Verifier edits files | Hard role violation. Verifier result is rejected. |
+| Worker asks the human a question | Invalid worker behavior. Convert to `BLOCKED` with `blocking_question` for supervisor handling. |
+| Worker hangs | Timeout returns normalized `BLOCKED` with adapter timing evidence. |
+| Worker exits non-zero but printed useful text | Do not trust it as PASS. Normalize as `BLOCKED` unless a valid report and clean guards prove otherwise. |
+| Worker returns PASS without evidence | Invalid report. Return normalized `BLOCKED` with `reason: report_validation_failed`. |
+| Tests cannot run | Verifier returns `BLOCKED` or `PASS` only with substitute evidence accepted by the acceptance matrix. |
+| Repair expands scope | Reject unless the repair dossier explicitly allowed the new surfaces and criteria. |
+| Units touch same surfaces | Run sequentially. Parallel delegation requires proven disjoint mutable surfaces. |
+| Platform has no native subagents | Fine. Each role is a fresh one-shot CLI process. |
+| Platform output differs | Platform output is not the contract. `WorkerReportV1` is the only supervisor input. |
+| Platform cannot support a role safely | Adapter role is unsupported. Supervisor chooses another certified adapter or blocks. |
+| Full support is claimed but one CLI is absent | `delegate-doctor --agent all --probe --require-pass` exits nonzero and names the missing adapter. |
+| Human-in-loop path is selected | Workers can still be delegated automatically after human approval gates; the human answers supervisor questions and approvals only. |
+| Autonomous path is selected | Intake boundaries still control installs, credentials, network calls, destructive operations, and final disposition. |
+| Workspace is dirty before delegation | Mutable delegation blocks unless `--allow-dirty` is set. If allowed, guard warnings record that changed paths may include pre-existing edits. |
+| Prompt injection appears in sources | Worker role prompt says sources are data, not instructions; supervisor relies on boundaries, diff guard, and evidence requirements. |
+| Agent version changes behavior | `delegate-doctor --probe` must run against the installed local version, not a documentation assumption. |
+| Agent supports JSON events but not schema | Use events for capture, then wrapper schema validation. |
+| Agent supports schema but ignores it | Wrapper validation is still authoritative. |
+| Worker writes a report but no files | Valid for verifier/documenter if evidence supports it; invalid for implementer if unit required mutation. |
+| Cost or token budget is exceeded | Use adapter-supported budget flags where available; otherwise use timeout and report `BLOCKED`. |
+
+## Why This Is The Smallest Viable Architecture
+
+One-shot delegation keeps the skill pack small:
+
+- Skills remain Markdown instructions.
+- The npm package remains an installer plus a small helper CLI.
+- Adapters are data in `adapters/<agent>/adapter.json`, not per-platform workflow implementations.
+- The supervisor loop stays unchanged.
+- The output contract is platform-neutral across the certified target set.
+
+Anything less is "run another agent and hope." Anything more becomes a harness.

package/docs/skill-reference.md

@@ -2,7 +2,7 @@
 
 ## `workflow-supervisor`
 
-Coordinate explicit supervised or agent-loop workflows. It always starts with a complete intake gate before planning, implementation, goal binding, worker creation, or final disposition. The user must answer every intake item; the supervisor must not infer or skip steps from keywords. After complete intake, it selects either autonomous goal execution or human-in-the-loop execution, then orchestrates named worker threads or subagents from dossiers when the environment supports and authorizes delegation. Loading the skill itself does not spawn workers. It binds Codex goals only after complete intake and when the user or environment authorizes goal-oriented work, checks active goal state first, and avoids unrelated active-goal collisions.
+Coordinate explicit supervised or agent-loop workflows. It always starts with a complete intake gate before planning, implementation, goal binding, worker delegation, or final disposition. The user must answer every intake item; the supervisor must not infer or skip steps from keywords. After complete intake, it selects either autonomous goal execution or human-in-the-loop execution, then orchestrates named workers from dossiers through the portable delegate command or an approved native adapter. Loading the skill itself does not spawn workers. It binds Codex goals only after complete intake and when the user or environment authorizes goal-oriented work, checks active goal state first, and avoids unrelated active-goal collisions.
 
 ## `source-corpus`
 
@@ -14,7 +14,7 @@ Split broad work into bounded units with objective, scope, dependencies, readine
 
 ## `dossier-builder`
 
-Create a handoff contract for one already-bounded work unit. Use it for another agent, thread, future session, or formal worker prompt, not ordinary same-thread direct work. Dossiers can include deterministic thread names, start conditions, handoff messages, checkpoints, and report schemas.
+Create a delegation contract for one already-bounded work unit. Use it for another agent, automated worker run, future session, or formal worker prompt, not ordinary same-session direct work. Dossiers can include deterministic worker names, delegation transports, start conditions, worker prompts, checkpoints, and report schemas.
 
 ## `worker-roles`
 
@@ -22,11 +22,11 @@ Define role contracts and solo-mode phase separation. It prevents role bleed: ve
 
 ## `acceptance-matrix`
 
-Create formal evidence-mapped acceptance rows for high-risk, supervised, ambiguous, resumable, or handoff workflows.
+Create formal evidence-mapped acceptance rows for high-risk, supervised, ambiguous, resumable, or delegated workflows.
 
 ## `loop-policy`
 
-Define execution path, execution mode, thread or subagent orchestration, approval gates, repair limits, parallel safety, no-progress rules, and Codex goal tool policy.
+Define execution path, execution mode, worker delegation, approval gates, repair limits, parallel safety, no-progress rules, and Codex goal tool policy.
 
 ## `workflow-docs`
 

package/docs/troubleshooting.md

@@ -17,7 +17,7 @@ Then verify the target directory contains folders such as `workflow-supervisor/S
 
 ## Goal tools are unavailable
 
-Use `.workflow/GOAL-STATE.md` or a workflow handoff document. The supervisor skill explicitly falls back to workflow docs when goal tools are unavailable or not permitted.
+Use `.workflow/GOAL-STATE.md` or a workflow continuation document. The supervisor skill explicitly falls back to workflow docs when goal tools are unavailable or not permitted.
 
 ## Too many docs are created
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "workflow-supervisor",
-  "version": "0.1.0",
-  "description": "Installable workflow supervision skills for Codex, Claude Code, OpenCode, HermesAgent, and generic agent workspaces.",
+  "version": "0.1.1",
+  "description": "Portable workflow supervision skills for Codex, Claude Code, and generic agent workspaces.",
   "type": "module",
   "repository": {
     "type": "git",
@@ -18,6 +18,7 @@
   "files": [
     "skills",
     "adapters",
+    "schemas",
     "docs",
     "assets",
     "bin",
@@ -32,8 +33,6 @@
   "keywords": [
     "codex",
     "claude-code",
-    "opencode",
-    "hermesagent",
     "skills",
     "workflow",
     "agent"

package/schemas/dossier-v1.schema.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workflow-supervisor.local/schemas/dossier-v1.schema.json",
+  "title": "DossierV1",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema",
+    "workflow",
+    "work_unit",
+    "dossier_id",
+    "worker_name",
+    "worker_role",
+    "delegation_transport",
+    "start_condition",
+    "title",
+    "objective",
+    "non_goals",
+    "source_corpus",
+    "must_read",
+    "allowed_surfaces",
+    "forbidden_surfaces",
+    "acceptance_matrix",
+    "adversarial_checks",
+    "required_commands_or_evidence",
+    "worker_prompt",
+    "supervisor_checkpoints",
+    "completion_report_schema",
+    "verification_report_schema",
+    "stop_gates",
+    "assumptions",
+    "open_questions"
+  ],
+  "properties": {
+    "schema": {
+      "type": "string",
+      "const": "DossierV1"
+    },
+    "workflow": {
+      "type": "string",
+      "minLength": 1
+    },
+    "work_unit": {
+      "type": "string",
+      "minLength": 1
+    },
+    "dossier_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "worker_name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "worker_role": {
+      "type": "string",
+      "enum": ["implementer", "verifier", "repair", "documenter"]
+    },
+    "delegation_transport": {
+      "type": "string",
+      "enum": ["portable_delegate", "native_thread", "native_subagent", "same_session_phased"]
+    },
+    "start_condition": {
+      "type": "string",
+      "minLength": 1
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "objective": {
+      "type": "string",
+      "minLength": 1
+    },
+    "worker_prompt": {
+      "type": "string",
+      "minLength": 1
+    },
+    "completion_report_schema": {
+      "type": "string",
+      "minLength": 1
+    },
+    "verification_report_schema": {
+      "type": "string",
+      "minLength": 1
+    },
+    "non_goals": {
+      "$ref": "#/$defs/stringList"
+    },
+    "source_corpus": {
+      "$ref": "#/$defs/stringList"
+    },
+    "must_read": {
+      "$ref": "#/$defs/stringList"
+    },
+    "allowed_surfaces": {
+      "$ref": "#/$defs/stringList"
+    },
+    "forbidden_surfaces": {
+      "$ref": "#/$defs/stringList"
+    },
+    "read_only_neighbors": {
+      "$ref": "#/$defs/stringList"
+    },
+    "work_points": {
+      "$ref": "#/$defs/stringList"
+    },
+    "acceptance_matrix": {
+      "$ref": "#/$defs/stringList"
+    },
+    "adversarial_checks": {
+      "$ref": "#/$defs/stringList"
+    },
+    "required_commands_or_evidence": {
+      "$ref": "#/$defs/stringList"
+    },
+    "supervisor_checkpoints": {
+      "$ref": "#/$defs/stringList"
+    },
+    "stop_gates": {
+      "$ref": "#/$defs/stringList"
+    },
+    "assumptions": {
+      "$ref": "#/$defs/stringList"
+    },
+    "open_questions": {
+      "$ref": "#/$defs/stringList"
+    }
+  },
+  "$defs": {
+    "stringList": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  }
+}