workflow-supervisor 0.1.0 → 0.1.1

package/skills/workflow-supervisor/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: workflow-supervisor
-description: Coordinate open-ended, multi-step agent workflows when the user explicitly requests supervised or agent-loop coordination and at least one hard trigger is present, or when no explicit supervisor wording exists but two or more hard triggers are present. Hard triggers include multi-agent or multi-thread handoff, durable resume need, high-risk independent verification, contradictory or missing sources, multi-unit scope, repair loops, approval gates, or workflow-state documentation. Do not use for simple single-turn answers, ordinary repo inspection, medium scoped edits, typo fixes, one-off tests, or narrowly scoped changes that can be completed directly.
+description: Coordinate open-ended, multi-step agent workflows when the user explicitly requests supervised or agent-loop coordination and at least one hard trigger is present, or when no explicit supervisor wording exists but two or more hard triggers are present. Hard triggers include multi-agent or worker delegation, durable resume need, high-risk independent verification, contradictory or missing sources, multi-unit scope, repair loops, approval gates, or workflow-state documentation. Do not use for simple single-turn answers, ordinary repo inspection, medium scoped edits, typo fixes, one-off tests, or narrowly scoped changes that can be completed directly.
 ---
 
 # Workflow Supervisor
 
-Use this skill as the coordinating spine for complex work. The supervisor owns decomposition, handoff quality, loop discipline, stop gates, and outcome reporting. It may do source discovery and reporting itself, but implementation, verification, repair-ticket writing, and documentation should be treated as separate roles when the environment supports separate agents or threads.
+Use this skill as the coordinating spine for complex work. The supervisor owns decomposition, delegation quality, loop discipline, stop gates, and outcome reporting. It may do source discovery and reporting itself, but implementation, verification, repair-ticket writing, and documentation should be treated as separate roles when an automated worker path is available. Native threads or subagents are optional transport optimizations, not the workflow contract.
 
 ## Domain Neutrality
 
@@ -30,44 +30,45 @@ Use this lifecycle:
 9. Use `update_goal` only for terminal `complete` or `blocked` states when the environment supports that action.
 10. Mark the goal complete only after acceptance evidence supports completion and no required supervisor work remains.
 11. Distinguish workflow/unit BLOCKED from Codex goal blocked. Mark a Codex goal blocked only after the same material blocker repeats across the required consecutive goal turns and no meaningful progress remains.
-12. On resume after compaction or handoff, read the active goal first, then reconcile workflow docs and current artifacts.
+12. On resume after compaction or continuation, read the active goal first, then reconcile workflow docs and current artifacts.
 
 If the environment has no goal tool or goal creation is not permitted, state the intended goal objective in the supervisor report and continue with workflow docs or another state artifact as the fallback state container.
 
 ## Operating Contract
 
 - After complete intake, ground the workflow in sources before creating work units.
-- Treat skill use as instruction loading in the current agent, not as thread, subagent, goal, branch, commit, PR, publication, or other side-effect creation.
-- Run the complete intake gate before goal creation, thread creation, implementation, publication, or other irreversible action.
+- Treat skill use as instruction loading in the current agent, not as worker delegation, thread creation, subagent creation, goal, branch, commit, PR, publication, or other side-effect creation.
+- Run the complete intake gate before goal creation, worker delegation, implementation, publication, or other irreversible action.
 - Do not infer execution path, mode, delegation, final disposition, or boundaries from keywords, action verbs, or intent guesses.
-- Classify the workflow as `autonomous_goal` or `human_in_loop` only from completed intake answers before spawning threads or beginning implementation.
+- Classify the workflow as `autonomous_goal` or `human_in_loop` only from completed intake answers before delegating workers or beginning implementation.
 - Always produce a plan after complete intake. In `human_in_loop`, make it an approval packet and stop for approval. In `autonomous_goal`, make it an execution plan and continue only when the completed intake authorizes that path.
 - Do not begin implementation until complete intake and the path gate are satisfied, at least one concrete dossier exists, and no stop gate applies.
-- Spawn worker threads only when the environment supports threads and complete intake plus the path gate authorize delegation; otherwise emit handoff prompts or workflow docs as the fallback.
-- Do not start implementer, verifier, repair-author, or documenter threads before complete intake and the path gate are satisfied; role-specific start conditions are additional gates after that.
+- Delegate workers only through an automated supported delegation transport after complete intake and the path gate authorize delegation. If no supported transport exists, use same-session phased mode only when intake allowed it; otherwise stop as `delegation_unavailable`.
+- Do not start implementer, verifier, repair-author, or documenter workers before complete intake and the path gate are satisfied; role-specific start conditions are additional gates after that.
 - Keep roles separate: implementers implement, verifiers verify, repair authors write tickets, documenters update workflow artifacts, and the supervisor coordinates.
-- Treat same-thread verification as a self-check, not independent verification.
+- Treat same-session verification as a self-check, not independent verification.
 - Prefer explicit PASS/FAIL/BLOCKED states over soft completion language.
 - Stop instead of improvising when sources are missing, contradictory, materially stale, or too vague to produce acceptance criteria.
 - Keep provenance optional; require enough outcome detail for another agent to resume.
 - Treat companion skills as optional phase tools, not an automatic cascade. Use the smallest set needed for the current risk.
 
-## Skills, Threads, And Subagents
+## Skills And Workers
 
-Using this skill does not spawn a thread or subagent. It coordinates the current agent until a separate execution mechanism is explicitly available and authorized.
+Using this skill does not spawn a worker, thread, or subagent. It coordinates the current agent until a separate automated execution mechanism is explicitly available and authorized.
 
 Treat these as distinct mechanisms:
 
 - Skill: reusable instructions loaded into the current agent.
-- Worker thread: a separate environment-managed conversation or task created with thread tools when allowed.
-- Subagent: a separate worker execution mechanism when the environment exposes one.
-- Handoff prompt: a ready-to-send worker brief used when thread or subagent tools are unavailable or not approved.
+- Worker: a role-scoped automated execution run that receives one dossier and returns one terminal report.
+- Portable worker delegation: the package helper command, `workflow-supervisor delegate --agent <agent> --role <role> --unit <unit-id> --cwd <workspace> --dossier <path>`, which invokes an installed platform CLI and normalizes its report.
+- Native thread or subagent: an environment-specific transport a worker adapter may use when it is available and authorized.
+- Same-session phased mode: the current agent performs roles sequentially. Verification in this mode is a self-check, not independent verification.
 
-Start worker threads or subagents only after complete intake and the path gate are satisfied, a concrete dossier exists, the loop policy authorizes delegation, and the environment allows the tool. If environment rules require explicit user approval for user-visible thread creation, obtain it before creating threads. Otherwise, output scoped handoff prompts and mark execution as `thread_unavailable` or `delegation_unavailable`.
+Start workers only after complete intake and the path gate are satisfied, a concrete dossier exists, the loop policy authorizes delegation, and the environment exposes an automated supported transport. If environment rules require explicit user approval for user-visible native thread creation, obtain it before using that transport. Do not use manual copy/paste handoff as the primary path. If automated delegation is unavailable, mark the unit `delegation_unavailable` unless completed intake explicitly selected same-session phased work.
 
 ## Intake Gate
 
-Every supervisor invocation must pass the complete intake gate before creating a goal, decomposing deeply, spawning workers, implementing, publishing, or taking irreversible action. If the current conversation already contains explicit answers to every required intake decision, record those answers and proceed. Otherwise, ask the intake packet and stop.
+Every supervisor invocation must pass the complete intake gate before creating a goal, decomposing deeply, delegating workers, implementing, publishing, or taking irreversible action. If the current conversation already contains explicit answers to every required intake decision, record those answers and proceed. Otherwise, ask the intake packet and stop.
 
 Do not use keywords to skip intake. Words such as "autonomous", "agent loop", "work until done", "approval", "generate", or "create" are not substitutes for completed intake answers.
 
@@ -76,11 +77,13 @@ Required intake decisions:
 - Objective and source: what artifact, spec, repo path, document, ticket, or source set controls the work.
 - Execution path: `autonomous_goal` or `human_in_loop`.
 - Execution mode: `sequential`, `parallel_where_safe`, or `staged_parallel`.
-- Delegation: `same_thread_only`, `use_threads_or_subagents_if_available`, or `handoff_prompts_only`.
+- Delegation: `automated_worker_delegation`, `native_threads_or_subagents_if_available`, or `same_session_phased`.
 - Final disposition: `keep_local_when_green`, `open_pr_when_green`, `push_main_when_green`, `deploy_when_green`, `publish_when_green`, or `ask_at_end`.
 - Mutation boundaries: local files, dependency installs, network calls, external services, credentials, destructive operations, and any forbidden surfaces.
 - State artifacts: whether to create workflow docs under `<workspace>/.workflow/`, use another named artifact directory, or keep state inline.
 
+If the completed intake selects `.workflow/` state artifacts in a Git-backed codebase, ensure `<workspace>/.gitignore` contains `.workflow/` before creating those artifacts. Create `.gitignore` if needed. Treat `.workflow/` as local supervisor memory that must not be staged, committed, pushed, or included in a PR unless the user explicitly names workflow state as a final deliverable.
+
 Use this question shape for the first intake ask:
 
 ```text
@@ -88,7 +91,7 @@ Before I start the supervisor loop, answer every intake item:
 1. Objective and source: what artifact, spec, repo path, document, ticket, or source set controls the work?
 2. Execution path: autonomous_goal or human_in_loop?
 3. Mode: sequential, parallel where safe, or staged parallel?
-4. Delegation: same-thread only, use threads/subagents if available, or handoff prompts only?
+4. Delegation: automated worker delegation, native threads/subagents if available, or same-session phased?
 5. Final disposition: keep local, open PR, push main, deploy/publish, or ask at the end?
 6. Boundaries: may I install dependencies, call external services, use credentials, or only edit local files?
 7. State artifacts: create `.workflow/` docs, use another artifact directory, or keep state inline?
@@ -108,26 +111,27 @@ Negative example: "Using Workflow Supervisor, generate an API and create the pro
 4. Build or request a source corpus map. Use `$source-corpus` when source authority, freshness, or contradictions matter.
 5. Split the objective into bounded work units. Use `$work-unit` for ambiguous or multi-phase goals.
 6. Choose a loop policy before starting work: sequential or parallel, retry limits, approval gates, budgets, goal update cadence, and blocker rules. Use `$loop-policy` when the policy is not obvious.
-7. Build dossiers for the first implementation units and any planned verification, repair, or documentation threads. Use `$dossier-builder` when handing work to another agent or when the task has boundaries.
-8. Assign worker roles with explicit allowed and forbidden behavior. Use `$worker-roles` for multi-agent or multi-thread work.
+7. Build dossiers for the first implementation units and any planned verification, repair, or documentation workers. Use `$dossier-builder` when delegating work to another agent or when the task has boundaries.
+8. Assign worker roles with explicit allowed and forbidden behavior. Use `$worker-roles` for multi-agent, native-thread, or portable-worker work.
 9. Select the execution path:
    - `human_in_loop`: use when selected in completed intake or when a higher-priority rule requires human approval after intake.
    - `autonomous_goal`: use only when selected in completed intake and no higher-priority rule requires human approval.
-10. Present the path-specific plan:
-   - `human_in_loop`: approval packet with plan, work units, thread plan, approval gates, stop gates, and first dossiers. Stop until the human approves or revises it.
+10. If `.workflow/` artifacts will be used in a Git-backed codebase, ensure `.gitignore` contains `.workflow/` before writing them.
+11. Present the path-specific plan:
+   - `human_in_loop`: approval packet with plan, work units, worker delegation plan, approval gates, stop gates, and first dossiers. Stop until the human approves or revises it.
    - `autonomous_goal`: execution plan with the same contents plus autonomous boundaries, allowed actions, stop gates, repair limits, and final disposition policy. Continue after recording it only when complete intake authorized that path.
-11. After the path gate is satisfied, create or hand off named threads from the thread plan. Send each worker only its role, dossier, sources, acceptance rows, stop gates, and report schema.
-12. Talk to each worker thread after handoff: confirm receipt, answer scoped questions, collect terminal reports, and preserve report links or summaries in the supervisor state.
-13. Verify independently where possible. Use `$acceptance-matrix` to map every requirement to evidence. Start verifier threads only after the relevant implementer report is available.
-14. If verification FAILs, convert findings into repair tickets and route them to a repair-author or implementer repair thread. Do not expand scope during repair.
-15. Re-run verification after repairs. Continue only until PASS, BLOCKED, repair limit, or path stop.
-16. Start documenter threads only after source, implementation, verification, or repair evidence exists, unless the documenter is explicitly creating planning state.
-17. If verification BLOCKs, report the blocker and stop or ask for the missing decision.
-18. Use `$workflow-docs` to create or refresh reusable Markdown artifacts under `<workspace>/.workflow/` when the workflow must persist across context loss, agents, or sessions.
-19. When all material acceptance rows are PASS or waived, apply the final disposition policy:
+12. After the path gate is satisfied, delegate named workers from the worker delegation plan through the selected automated transport. Send each worker only its role, dossier, sources, acceptance rows, stop gates, and report schema.
+13. Collect one terminal report from each worker. If a worker asks a human-facing question, convert it to `BLOCKED` and have the supervisor ask the user only when the path policy permits.
+14. Verify independently where possible. Use `$acceptance-matrix` to map every requirement to evidence. Start verifier workers only after the relevant implementer report is available.
+15. If verification FAILs, convert findings into repair tickets and route them to a repair-author or implementer repair worker. Do not expand scope during repair.
+16. Re-run verification after repairs. Continue only until PASS, BLOCKED, repair limit, or path stop.
+17. Start documenter workers only after source, implementation, verification, or repair evidence exists, unless the documenter is explicitly creating planning state.
+18. If verification BLOCKs, report the blocker and stop or ask for the missing decision.
+19. Use `$workflow-docs` to create or refresh reusable Markdown artifacts under `<workspace>/.workflow/` when the workflow must persist across context loss, agents, or sessions.
+20. When all material acceptance rows are PASS or waived, apply the final disposition policy:
    - `human_in_loop`: use the completed intake final disposition; if it is `ask_at_end`, ask the human to choose PR, push main, or keep local.
    - `autonomous_goal`: use the completed intake final disposition. If it is `ask_at_end`, stop and ask before taking any final disposition action.
-20. Finish with an outcome report that names execution path, goal status, sources, work units, worker threads, checks, skipped checks, residual risks, final disposition decision, and next action.
+21. Finish with an outcome report that names execution path, goal status, sources, work units, delegated workers, checks, skipped checks, residual risks, final disposition decision, and next action.
 
 ## Execution Paths
 
@@ -140,7 +144,7 @@ The first supervisor deliverable is a plan for approval, not implementation. The
 - objective and non-goals
 - source corpus summary and gaps
 - work units and sequence
-- thread plan with names, roles, dossiers, dependencies, and start conditions
+- worker delegation plan with names, roles, dossiers, dependencies, start conditions, and transport
 - acceptance matrix summary
 - approval gates and stop gates
 - expected final disposition choices: PR, push main, or keep local
@@ -154,7 +158,7 @@ Use `autonomous_goal` only when the completed intake selects it. Phrases such as
 - objective and non-goals
 - source corpus summary and gaps
 - work units and sequence
-- thread plan with names, roles, dossiers, dependencies, and start conditions
+- worker delegation plan with names, roles, dossiers, dependencies, start conditions, and transport
 - acceptance matrix summary
 - autonomous boundaries and forbidden actions
 - stop gates, repair limits, budgets, and escalation rules
@@ -164,11 +168,25 @@ The final disposition must come from the completed intake. Direct push to the ma
 
 Even in `autonomous_goal`, stop and ask when any required intake answer is missing or ambiguous, required sources are missing, acceptance cannot be verified, a worker needs scope expansion, an irreversible action lacks intake authorization, or higher-priority instructions require approval.
 
-## Thread Orchestration
+## Portable Worker Delegation
+
+After the path gate is satisfied, use the selected automated worker transport. The portable default is the package helper:
+
+```text
+workflow-supervisor delegate --agent <agent> --role <role> --unit <unit-id> --cwd <workspace> --dossier <path>
+```
+
+Before calling `delegate`, validate the dossier:
 
-After the path gate is satisfied, use environment thread tools when available. In Codex-style environments, use the configured thread-management tools to create or fork worker threads, send handoff messages, read reports, and hand off or close threads. If thread tools are unavailable, output the worker handoff prompts and mark execution as `thread_unavailable`.
+```text
+workflow-supervisor validate-dossier <path> --role <role> --unit <unit-id> --json
+```
+
+If the dossier does not pass `DossierV1` validation, do not start the worker. Create a discovery dossier, ask for the missing decision, or mark the unit BLOCKED.
 
-Name threads deterministically from the workflow, unit, role, and dossier:
+Adapters may use native threads, native subagents, or one-shot CLI execution underneath, but the supervisor consumes only the normalized worker report. Use `workflow-supervisor delegate-doctor --agent <agent> --probe` to test the installed local adapter before relying on it for a workflow. If automated delegation is unavailable, mark execution as `delegation_unavailable` unless completed intake selected `same_session_phased`.
+
+Name workers deterministically from the workflow, unit, role, and dossier:
 
 ```text
 wf/<workflow-slug>/<unit-id>-<role>-<dossier-slug>
@@ -180,16 +198,18 @@ Examples:
 wf/better-auth/U1-implementer-backend-auth-instance
 wf/better-auth/U1-verifier-backend-auth-instance
 wf/better-auth/U1-repair-auth-route-order
-wf/better-auth/U6-documenter-auth-handoff
+wf/better-auth/U6-documenter-outcome-docs
 ```
 
-Use one thread per role per work unit unless the loop policy explicitly allows batching. Supervisor messages to worker threads must be scoped:
+Use one worker per role per work unit unless the loop policy explicitly allows batching. Worker prompts must be scoped:
 
 - kickoff: role, dossier, sources, acceptance rows, stop gates, report schema
 - checkpoint: request status, blockers, or clarification without expanding scope
-- repair handoff: failed rows, verifier findings, allowed repair surfaces, checks
+- repair delegation: failed rows, verifier findings, allowed repair surfaces, checks
 - closeout: collect terminal report and confirm no further action is expected
 
+Workers must not ask the human questions directly, choose final disposition, approve plans, expand scope, or message each other. They return `PASS`, `FAIL`, or `BLOCKED` using the assigned report schema. The supervisor routes blockers, repairs, and human questions.
+
 Final disposition prompt shape:
 
 ```text
@@ -211,7 +231,9 @@ Do not hand off or implement a work unit unless the dossier can name:
 - adversarial checks
 - stop gates
 - worker report schema
-- thread name and role start condition when delegation is planned
+- worker name, transport, and role start condition when delegation is planned
+
+The dossier must be machine-checkable as `DossierV1`. The portable delegate command refuses missing or invalid dossiers with `reason: invalid_dossier`; no worker process should start when the gate fails.
 
 Boundaries may be mutable artifacts, source claims, decisions, audiences, data fields, design areas, process steps, publication rights, or forbidden claims. For read-only advisory work, naming forbidden claims and decision limits can satisfy the boundary requirement.
 
@@ -232,7 +254,7 @@ Stop when:
 - the user requires approval before continuing
 - the selected path is `autonomous_goal` but it was inferred from prompt wording instead of a completed intake answer
 - an irreversible action is requested without explicit authorization in the completed intake
-- a worker thread asks to expand scope without supervisor or human approval
+- a worker asks to expand scope without supervisor or human approval
 - final verification is not green and no waiver evidence exists
 
 ## Final Report Shape
@@ -245,7 +267,7 @@ Report:
 - Objective handled
 - Sources used and gaps
 - Work units completed or remaining
-- Worker threads created, messaged, blocked, or skipped
+- Workers delegated, blocked, unavailable, or skipped
 - Verification evidence
 - Repairs performed or recommended
 - Checks run and skipped

package/adapters/hermesagent/adapter.json

@@ -1,8 +0,0 @@
-{
-  "agent": "hermesagent",
-  "status": "portable",
-  "defaultTarget": "${HERMESAGENT_HOME:-${HERMES_HOME:-~/.hermes}}/skills",
-  "projectTarget": "<project>/.hermes/skills",
-  "metadata": "SKILL.md",
-  "fallback": "workflow-supervisor emit-context --agent hermesagent --out HERMES.md"
-}

package/adapters/opencode/adapter.json

@@ -1,8 +0,0 @@
-{
-  "agent": "opencode",
-  "status": "portable",
-  "defaultTarget": "${OPENCODE_HOME:-~/.config/opencode}/skills",
-  "projectTarget": "<project>/.opencode/skills",
-  "metadata": "SKILL.md",
-  "fallback": "workflow-supervisor emit-context --agent opencode --out AGENTS.md"
-}