workflow-supervisor 0.1.0 → 0.1.1

package/README.md

@@ -1,266 +1,470 @@
 # Workflow Supervisor
 
-Portable workflow skills for supervising messy agent work.
+Workflow Supervisor is a small skill pack and npm helper for making coding agents handle complex work with discipline.
 
-![Workflow Supervisor hero image showing the supervisor coordinating source corpus, work units, dossiers, roles, loop policy, acceptance, repair, workflow docs, and final outputs](assets/workflow-supervisor-hero.png)
+It turns a vague request like:
 
-This repository contains an installable skill pack for Codex, Claude Code, OpenCode, HermesAgent, and other agents that can read Markdown instructions. It is built for work that is too broad, risky, ambiguous, or long-running to handle as one ordinary prompt.
+```text
+Use workflow-supervisor to migrate the database from SQLite to LanceDB.
+```
 
-Use it when an agent needs to:
+into a supervised workflow with intake, source grounding, bounded work units, concrete worker dossiers, independent verification, repair loops, and evidence-backed output.
 
-- ground work in source material before acting
-- split a fuzzy goal into bounded work units
-- create concrete handoffs between agents or threads
-- choose between autonomous goal execution and human-in-the-loop execution
-- fan out path-gated dossiers into named worker threads
-- separate implementation from verification
-- turn acceptance criteria into evidence-backed checks
-- control repair loops, retries, budgets, and stop gates
-- leave reusable Markdown state so another agent can resume
+It currently supports certified automated worker delegation for **Codex** and **Claude Code**.
 
-Do not use it for tiny edits, one-off commands, ordinary README wording, or a task that already has clear files and clear acceptance criteria.
+![Workflow Supervisor hero image showing the supervisor coordinating source corpus, work units, dossiers, roles, loop policy, acceptance, repair, workflow docs, and final outputs](assets/workflow-supervisor-hero.png)
 
-## The Idea
+## What It Is
 
-The pack treats open-ended work as a supervised loop:
+Workflow Supervisor is not another agent product. It is a thin coordination layer for agents that already exist.
 
-```text
-sources -> work units -> execution path -> named threads -> verification -> repair -> disposition
-```
+The supervisor is the visible agent in the conversation. It owns the plan, asks the user questions, creates work units, validates worker contracts, launches workers, reads reports, and decides what happens next.
 
-`$workflow-supervisor` is the spine. The other skills are phase tools the supervisor can call when the workflow needs more structure.
+Workers are short-lived CLI runs:
 
-```text
-                source-corpus
-                      |
-workflow-supervisor --+-- work-unit
-        |             |
-        |             +-- dossier-builder
-        |             |
-        |             +-- worker-roles
-        |             |
-        |             +-- acceptance-matrix
-        |             |
-        |             +-- loop-policy
-        |
-        +-- workflow-docs
+```bash
+workflow-supervisor delegate --agent codex --role implementer --unit U1 --dossier .workflow/dossiers/U1.yaml
+workflow-supervisor delegate --agent claude-code --role verifier --unit U1 --dossier .workflow/dossiers/U1.yaml
 ```
 
-The goal is not bureaucracy. The goal is to stop agents from drifting, guessing, rubber-stamping their own work, or losing state after a long context window.
+Each worker gets only the context it needs. It returns one structured report. The supervisor remains the coordinator.
 
-## Execution Paths
+## The Moat
 
-The supervisor enforces complete intake before it chooses a path or starts work:
+The moat is not a clever prompt. The moat is the set of gates that prevent agents from drifting.
 
-- `human_in_loop`: after complete intake, the agent produces an approval packet first, then waits for a human decision before implementation, worker thread creation, publication, direct push, or other irreversible action.
-- `autonomous_goal`: after complete intake, the agent can continue through planning, implementation, verification, repair, and final disposition only when the execution-path intake answer selects `autonomous_goal`.
+Workflow Supervisor enforces:
 
-`$workflow-supervisor` does not skip intake from keywords such as "autonomous", "work until done", "approval", "generate", or "create". The user must answer every intake item. If any answer is missing, vague, or delegated to judgment, the supervisor prompts for the unresolved item(s) again and stops before planning or implementation.
+- complete intake before work starts
+- no keyword-based skipping
+- bounded work units before implementation
+- machine-checkable `DossierV1` before workers start
+- role separation between implementer, verifier, repair, and documenter
+- normalized `WorkerReportV1` output from every worker
+- evidence required for PASS
+- automatic BLOCKED reports for vague dossiers, missing CLIs, auth failures, invalid output, timeouts, forbidden edits, or verifier mutations
 
-Both paths use the same core controls after intake: source grounding, bounded work units, dossiers, role separation, acceptance evidence, repair limits, stop gates, and final disposition choices. In Codex-style environments, the supervisor can bind the loop to a goal only after complete intake and any required environment authorization, mirror state into workflow artifacts, and resume without losing the active objective.
+That means the system does not merely ask agents to behave. It blocks unsafe or vague execution before it happens.
 
-The pack is domain-neutral. A "surface" can be a repository path, document section, design, dataset, ticket, process, prompt, or other mutable artifact. When prerequisites are missing, the skills create a discovery or intake unit instead of inventing repo-only requirements.
+## What It Solves
 
-## Skills, Threads, And Subagents
+Large agent tasks fail in predictable ways:
 
-Using a skill loads instructions into the current agent. It does not automatically create a new thread, subagent, goal, branch, commit, PR, publication, or other side effect.
+- the agent starts before asking enough questions
+- "autonomous" or "use workflow supervisor" gets treated as permission to act
+- the context window fills with unrelated history
+- handoffs are vague
+- implementers verify their own work
+- verifiers say "looks good" without evidence
+- repair work expands scope
+- progress disappears after context compaction
+- every platform has a different output style
 
-Worker threads or subagents are separate execution mechanisms. `$workflow-supervisor` may plan them, but creation happens only after the selected execution path is authorized, a concrete dossier exists, the environment exposes the needed tool, and no stop gate applies. If thread or subagent tools are unavailable, the supervisor emits ready-to-send handoff prompts or workflow docs instead.
+Workflow Supervisor solves this by making the workflow explicit and resumable.
 
-In Codex-style environments, user-visible thread creation may require an explicit user request or approval even when the supervisor has prepared a thread plan. Treat same-thread verification as a self-check, not independent verification.
+The conversation holds the supervisor. The `.workflow/` artifacts hold durable state. Workers get small, role-specific dossiers instead of the full conversation. Reports come back in one schema.
 
-## Quick Example
+## Architecture
 
-Ask the agent to use the supervisor for work that needs a real loop:
+Workflow Supervisor has two halves: a portable skill pack that teaches an agent how to supervise work, and a small npm CLI that installs those skills, validates contracts, and runs one-shot worker delegations.
 
-```text
-Use $workflow-supervisor.
+The current chat agent is always the supervisor. It owns intake, planning, source grounding, work-unit boundaries, dossiers, verification decisions, repair routing, and final disposition. The CLI never becomes a workflow daemon or queue. It is a helper that copies skills into supported agent directories, emits portable Markdown context, validates schema-backed artifacts, and invokes a single role-scoped worker process when delegation is authorized.
+
+```mermaid
+flowchart TB
+  User["User"] --> Supervisor["Supervisor agent in current chat"]
+  Supervisor --> Skills["Installed skills: SKILL.md and agent metadata"]
+  Supervisor --> State["Durable state: .workflow/ in the target workspace"]
+  Supervisor --> CLI["workflow-supervisor CLI: bin/workflow-skills.mjs"]
+
+  subgraph Package["npm package"]
+    SkillsSource["skills/"]
+    AdapterDefs["adapters/"]
+    SchemaDefs["schemas/"]
+    Docs["docs/"]
+    CLI
+  end
 
-Migrate this repo's docs to the new API shape.
+  CLI --> SkillsSource
+  CLI --> AdapterDefs
+  CLI --> SchemaDefs
+  CLI --> Docs
+  CLI --> Adapters["Adapter command array"]
+  Adapters --> Codex["Codex CLI worker"]
+  Adapters --> Claude["Claude Code CLI worker"]
+  Codex --> Report["WorkerReportV1 JSON"]
+  Claude --> Report
+  Report --> Supervisor
 ```
 
-The supervisor should ask the complete intake before work starts:
+The package layout is intentionally simple:
+
+- `skills/` contains the opt-in supervisor skills and OpenAI metadata prompts.
+- `bin/workflow-skills.mjs` contains the installer, validator, context emitter, delegation wrapper, surface guard, and command dispatch.
+- `schemas/` defines `DossierV1` and `WorkerReportV1`.
+- `adapters/` defines certified Codex and Claude Code command arrays.
+- `docs/` explains CLI usage, portable delegation semantics, compatibility, artifacts, and troubleshooting.
+- `.workflow/` is created in consuming projects as private supervisor working memory, not as package state.
+
+```mermaid
+flowchart LR
+  Package["workflow-supervisor package"] --> Install["install"]
+  Package --> Emit["emit-context"]
+  Package --> Validate["validate and validate-dossier"]
+  Package --> Delegate["delegate and delegate-doctor"]
+
+  Install --> CodexTarget["Codex target: ~/.agents/skills or project .agents/skills"]
+  Install --> ClaudeTarget["Claude target: ~/.claude/skills or project .claude/skills"]
+  Install --> Gitignore["Project .gitignore contains .workflow/"]
+
+  Emit --> PortableFile["Portable context file: AGENTS.md or CLAUDE.md"]
+  Validate --> SkillGate["Skill, schema, adapter, and dossier gates"]
+  Delegate --> WorkerRun["One role-scoped worker CLI process"]
+```
 
-```text
-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?
-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?
+Delegation is a guarded subprocess, not an open-ended conversation between agents. The supervisor creates a concrete `DossierV1`, the CLI validates it before any worker starts, the adapter receives a role-scoped prompt and the `WorkerReportV1` schema, and the wrapper normalizes failure modes into structured `BLOCKED` reports.
+
+```mermaid
+sequenceDiagram
+  participant S as Supervisor
+  participant C as "workflow-supervisor delegate"
+  participant D as "DossierV1 validator"
+  participant G as "Surface guard"
+  participant A as "Agent adapter"
+  participant W as "Worker CLI"
+
+  S->>C: Role, unit ID, workspace, dossier path
+  C->>D: Parse JSON, YAML, or fenced YAML
+  D-->>C: Valid dossier or BLOCKED invalid_dossier
+  C->>G: Snapshot git status or explicit surfaces
+  C->>A: Build command from adapters/<agent>/adapter.json
+  A->>W: Run one CLI process with role prompt and schema
+  W-->>A: stdout, stderr, exit code, timeout signal
+  A-->>C: Raw worker output
+  C->>C: Extract and validate WorkerReportV1
+  C->>G: Compare after-state against allowed and forbidden surfaces
+  C-->>S: PASS, FAIL, or normalized BLOCKED WorkerReportV1
 ```
 
-If the reply skips any item, the supervisor asks for the missing item(s) and stops again.
+The supervisor loop is therefore stateful at the workflow level but stateless at the worker level. Every worker run is fresh, bounded by one dossier, and reduced back to one report before the supervisor decides the next step.
+
+```mermaid
+stateDiagram-v2
+  [*] --> Intake
+  Intake --> SourceGrounding: Complete intake
+  SourceGrounding --> WorkUnits: Sources ranked
+  WorkUnits --> AcceptanceMatrix: Units bounded
+  AcceptanceMatrix --> Dossier: Evidence rows ready
+  Dossier --> Delegation: DossierV1 valid
+  Delegation --> Verification: WorkerReportV1 returned
+  Verification --> Repair: FAIL or actionable BLOCKED
+  Repair --> Verification: Repair report returned
+  Verification --> Documentation: PASS with evidence
+  Documentation --> FinalDisposition: Outcome recorded
+  FinalDisposition --> [*]
+  Dossier --> Intake: Missing decision
+  Delegation --> Intake: Worker BLOCKED with human question
+```
+
+## What It Is Used For
+
+Use it for work that is:
+
+- broad or ambiguous
+- multi-step
+- high-risk
+- likely to need repair loops
+- likely to exceed one context window
+- important enough to require independent verification
+- easier to handle as several bounded units
+
+Good examples:
+
+- migrate SQLite storage to LanceDB
+- refactor authentication across several modules
+- update docs from a new API spec
+- implement a feature with tests and verification
+- review and repair a messy PR
+- produce durable workflow docs for a long-running task
+
+Do not use it for:
+
+- tiny edits
+- one-off shell commands
+- obvious single-file changes
+- quick explanations
+- tasks where a normal agent turn is enough
 
-For a narrower phase, invoke the specific skill:
+## How It Works
+
+The lifecycle is:
 
 ```text
-Use $source-corpus to identify the sources of truth for this migration and flag contradictions.
+intake
+-> source grounding
+-> work units
+-> acceptance matrix
+-> DossierV1
+-> worker delegation
+-> WorkerReportV1
+-> verification
+-> repair if needed
+-> re-verification
+-> documentation
+-> final disposition
 ```
 
+### 1. Intake
+
+The supervisor must ask the user for every required decision before it plans deeply or starts work:
+
 ```text
-Use $acceptance-matrix to turn this launch checklist into PASS, FAIL, and BLOCKED criteria with evidence requirements.
+1. Objective and source
+2. Execution path: autonomous_goal or human_in_loop
+3. Mode: sequential, parallel where safe, or staged parallel
+4. Delegation: automated workers, native subagents if available, or same-session phased
+5. Final disposition: keep local, open PR, push, deploy, publish, or ask at end
+6. Boundaries: installs, network, credentials, destructive operations, forbidden surfaces
+7. State artifacts: .workflow docs, another directory, or inline state
 ```
 
+If any answer is missing or vague, the supervisor asks again and stops.
+
+### 2. Source Grounding
+
+The supervisor identifies the source of truth: files, specs, docs, tickets, user decisions, commands, or external constraints.
+
+If source authority is unclear, the first work unit becomes discovery instead of implementation.
+
+### 3. Work Units
+
+The supervisor splits the objective into bounded units.
+
+For a SQLite to LanceDB migration, units might be:
+
 ```text
-Use $workflow-docs to create a reusable HANDOFF.md and OUTCOME.md for the next agent.
+U1 dependency and config
+U2 storage adapter
+U3 data migration path
+U4 tests and regression checks
+U5 docs and outcome report
 ```
 
-## Install
+### 4. DossierV1
 
-From a local checkout:
+Before any worker starts, the supervisor creates a concrete `DossierV1`.
 
-```bash
-git clone https://github.com/NikolaCehic/workflow-supervisor.git
-cd workflow-supervisor
-npm run validate
-node ./bin/workflow-skills.mjs install --agent codex --scope user
-```
+A dossier names:
 
-After npm publication, the same installer can be run through `npx`:
+- the exact work unit
+- the worker role
+- allowed surfaces
+- forbidden surfaces
+- must-read sources
+- acceptance rows
+- required evidence
+- adversarial checks
+- stop gates
+- required report schema
+
+Then the package validates it:
 
 ```bash
-npx workflow-supervisor install --agent codex --scope user
+workflow-supervisor validate-dossier .workflow/dossiers/U2-implementer.yaml --role implementer --unit U2 --json
 ```
 
-Install into a project-local skill directory for all supported agents:
+If the dossier says `all files`, `TBD`, `unknown`, `as needed`, or leaves open questions unresolved, it fails. No worker starts.
 
-```bash
-node ./bin/workflow-skills.mjs install --agent all --scope project --project /path/to/project
-```
+### 5. Worker Delegation
 
-Install into any custom directory:
+The supervisor launches one role-scoped worker through Codex or Claude Code.
 
 ```bash
-node ./bin/workflow-skills.mjs install --agent generic --target ./agent-skills
+workflow-supervisor delegate --agent codex --role implementer --unit U2 --dossier .workflow/dossiers/U2-implementer.yaml
 ```
 
-Install only selected skills:
+The worker does not get the whole chat. It receives the dossier and report schema.
 
-```bash
-node ./bin/workflow-skills.mjs install --agent codex --skills workflow-supervisor,loop-policy,workflow-docs
-```
+### 6. Verification And Repair
 
-Remove an install:
+A verifier checks the implementer's work against acceptance rows.
 
-```bash
-node ./bin/workflow-skills.mjs uninstall --agent codex --scope user
-```
+If verification fails, the supervisor creates repair work. Repairs must point back to verifier findings or acceptance rows. After repair, verification runs again.
 
-Emit a portable context file for agents that do not natively discover skill folders. This embeds the selected `SKILL.md` files and bundled Markdown references:
+### 7. Final Disposition
 
-```bash
-npx workflow-supervisor emit-context --agent opencode --skills workflow-supervisor,workflow-docs --out AGENTS.md
+The supervisor applies the final disposition chosen during intake:
+
+- keep changes local
+- open a PR
+- push
+- deploy
+- publish
+- ask at the end
+
+No final irreversible action is inferred from vibes.
+
+## What The User Sees
+
+The user sees the supervisor, not worker chatter.
+
+In `human_in_loop`, the user sees:
+
+```text
+intake question
+approval packet
+progress summaries
+blocker questions if needed
+final report
 ```
 
-Each install writes:
+In `autonomous_goal`, the user sees:
 
-- the selected skill folders
-- `WORKFLOW_SKILL_PACK.md`
-- `.workflow-skills-install.json` with installed skills and checksums
+```text
+intake question
+execution plan
+periodic progress summaries
+blockers only when needed
+final report
+```
 
-## Supported Agents
+Workers do not ask the user questions directly. They return `BLOCKED` and the supervisor decides how to route it.
 
-| Agent | User Install | Project Install |
-|---|---|---|
-| Codex | `~/.agents/skills` | `<project>/.agents/skills` |
-| Claude Code | `${CLAUDE_HOME:-~/.claude}/skills` | `<project>/.claude/skills` |
-| OpenCode | `${OPENCODE_HOME:-~/.config/opencode}/skills` | `<project>/.opencode/skills` |
-| HermesAgent | `${HERMESAGENT_HOME:-${HERMES_HOME:-~/.hermes}}/skills` | `<project>/.hermes/skills` |
-| Generic | custom `--target` | custom `--target` |
+## What The Output Is
 
-Use `emit-context` to create `AGENTS.md`, `CLAUDE.md`, `HERMES.md`, or another portable instruction file when an agent does not read `SKILL.md` folders directly. See [docs/compatibility.md](docs/compatibility.md) for adapter notes.
+Workflow Supervisor produces three kinds of output.
 
-## Included Skills
+### 1. Durable Workflow State
 
-| Skill | What It Does |
-|---|---|
-| `$workflow-supervisor` | Coordinates the whole loop: source grounding, work units, autonomous or human-in-loop execution path, thread orchestration, dossiers, verification, repair, stop gates, goal state, final PR/push/local disposition, and outcome reporting. |
-| `$source-corpus` | Identifies and ranks sources of truth, then flags stale, missing, contradictory, inaccessible, or non-blocking evidence gaps. |
-| `$work-unit` | Turns broad goals into bounded units with objective, dependencies, scope, done criteria, and sequencing. |
-| `$dossier-builder` | Creates a concrete handoff contract for one unit: sources, allowed surfaces, forbidden surfaces, checks, stop gates, and report shape. |
-| `$worker-roles` | Defines narrow role contracts for implementer, verifier, researcher, repair author, documenter, reviewer, and synthesizer. |
-| `$acceptance-matrix` | Converts goals into testable criteria with evidence requirements, adversarial checks, PASS/FAIL/BLOCKED states, and residual risk. |
-| `$loop-policy` | Controls autonomous vs human-in-loop execution, sequential/parallel mode, retry limits, approvals, budgets, escalation, no-progress detection, and continuation rules. |
-| `$workflow-docs` | Generates the smallest useful set of durable workflow-state and documentation-production artifacts. |
+Usually under `.workflow/`:
 
-## Documentation Artifacts
+```text
+WORKFLOW.md
+SOURCE-CORPUS.md
+WORK-UNITS.md
+DOSSIER.md
+WORKER-MAP.md
+ACCEPTANCE-MATRIX.md
+VERIFICATION-REPORT.md
+REPAIR-TICKETS.md
+DECISIONS.md
+HANDOFF.md
+OUTCOME.md
+GOAL-STATE.md
+```
 
-`$workflow-docs` supports two lanes.
+These files make the workflow resumable after context compaction or handoff.
+
+### 2. Worker Reports
+
+Every worker returns `WorkerReportV1`:
+
+```json
+{
+  "schema": "WorkerReportV1",
+  "status": "PASS",
+  "role": "verifier",
+  "unit_id": "U2",
+  "summary": "Verified LanceDB-backed search path.",
+  "changed_surfaces": [],
+  "evidence": ["pytest tests/test_search.py passed"],
+  "checks_run": ["pytest tests/test_search.py"],
+  "skipped_checks": [],
+  "findings": [],
+  "blocking_question": null,
+  "next_action": "supervisor_review",
+  "adapter": null,
+  "guard": null,
+  "reason": null
+}
+```
 
-Markdown workflow artifacts are created under `<workspace>/.workflow/` by default. 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.
+### 3. Final Supervisor Report
 
-Workflow state:
+The final report names:
 
-- `.workflow/WORKFLOW.md`
-- `.workflow/SOURCE-CORPUS.md`
-- `.workflow/WORK-UNITS.md`
-- `.workflow/DOSSIER.md`
-- `.workflow/THREAD-MAP.md`
-- `.workflow/ACCEPTANCE-MATRIX.md`
-- `.workflow/VERIFICATION-REPORT.md`
-- `.workflow/REPAIR-TICKETS.md`
-- `.workflow/DECISIONS.md`
-- `.workflow/HANDOFF.md`
-- `.workflow/OUTCOME.md`
-- `.workflow/GOAL-STATE.md`
+- execution path
+- goal status
+- sources used
+- work units completed
+- workers delegated
+- checks run
+- skipped checks
+- repairs performed
+- residual risks
+- final disposition
+- next action
 
-Documentation production:
+## How To Install
 
-- `.workflow/DOCUMENTATION-BRIEF.md`
-- `.workflow/CONTENT-INVENTORY.md`
-- `.workflow/OUTLINE.md`
-- `.workflow/CONTENT-DRAFT.md`
-- `.workflow/CLAIMS-REGISTER.md`
-- `.workflow/STYLE-GUIDE.md`
-- `.workflow/GLOSSARY.md`
-- `.workflow/ASSET-REGISTER.md`
-- `.workflow/REVIEW-PLAN.md`
-- `.workflow/REVISION-QUEUE.md`
-- `.workflow/PUBLISHING-CHECKLIST.md`
-- `.workflow/PUBLICATION-LOG.md`
-- `.workflow/MAINTENANCE-PLAN.md`
+From a local checkout:
 
-Markdown is the default, but the skills can also produce inline handoffs, ticket outlines, runbooks, spreadsheet-ready tables, design review notes, or other state that a human or agent can reuse.
+```bash
+git clone https://github.com/NikolaCehic/workflow-supervisor.git
+cd workflow-supervisor
+npm run validate
+```
+
+Install for Codex:
 
-`$workflow-docs` is intentionally selective: it can scaffold, refresh, or preserve only the artifacts a workflow actually needs, including resume packs, verification reports, repair tickets, content briefs, claims registers, review plans, publishing checklists, and maintenance plans.
+```bash
+npx workflow-supervisor install --agent codex --scope user
+```
 
-## CLI
+Install for Claude Code:
 
 ```bash
-workflow-supervisor list
-workflow-supervisor validate
-workflow-supervisor doctor --agent codex
-workflow-supervisor install --agent codex --dry-run
-workflow-supervisor install --agent all --scope project --project .
-workflow-supervisor install --agent generic --target ./agent-skills
-workflow-supervisor install --agent codex --skills workflow-supervisor,loop-policy
-workflow-supervisor uninstall --agent codex --scope user
-workflow-supervisor emit-context --agent opencode --skills workflow-supervisor,workflow-docs --out AGENTS.md
+npx workflow-supervisor install --agent claude-code --scope user
 ```
 
-See [docs/cli.md](docs/cli.md) for the full command reference.
+Install for both in a project:
 
-## Validation
+```bash
+npx workflow-supervisor install --agent all --scope project --project .
+```
 
-Run the built-in validator before installing from a local checkout:
+Project installs also add `.workflow/` to the target project's `.gitignore`. Workflow state is local working memory by default; it should not be pushed with the consuming codebase unless the user explicitly chooses that.
+
+Export generic Markdown instructions:
 
 ```bash
-npm run validate
-node ./bin/workflow-skills.mjs install --agent generic --target ./agent-skills --dry-run
+npx workflow-supervisor emit-context --agent generic --out AGENTS.md
 ```
 
-## Repository Layout
+## How To Use
+
+In Codex or Claude Code, ask explicitly:
 
 ```text
-skills/      production skill folders
-adapters/    agent adapter metadata
-bin/         workflow-supervisor CLI
-docs/        user documentation
+Use $workflow-supervisor to migrate this repo from SQLite to LanceDB.
+```
+
+The correct next step is not implementation. The correct next step is the intake packet.
+
+After intake is complete, the supervisor proceeds through work units, dossiers, workers, verification, repair, and final disposition.
+
+Useful CLI commands:
+
+```bash
+workflow-supervisor validate
+workflow-supervisor validate-dossier .workflow/dossiers/U2-implementer.yaml --role implementer --unit U2 --json
+workflow-supervisor delegate --agent codex --role implementer --unit U2 --dossier .workflow/dossiers/U2-implementer.yaml
+workflow-supervisor delegate --agent claude-code --role verifier --unit U2 --dossier .workflow/dossiers/U2-verifier.yaml
+workflow-supervisor delegate-doctor --agent all --probe --require-pass
 ```
 
-## Status
+## For Agents
+
+If you are an AI agent reading this README, follow these rules:
+
+1. Do not start work before complete intake.
+2. Do not infer missing permissions from user intent.
+3. Do not delegate without a valid `DossierV1`.
+4. Do not accept worker prose as completion.
+5. Trust only `WorkerReportV1` reports.
+6. Treat verifier edits as invalid.
+7. Ask the user only through the supervisor.
+8. Before creating `.workflow/` in a codebase, ensure `.gitignore` contains `.workflow/`.
+9. Preserve enough `.workflow/` state for another agent to resume, but do not stage or publish it unless explicitly requested.
 
-The package is ready for local installation and explicit skill invocation. Keep implicit invocation disabled unless your environment has proven routing precision for these skills.
+The point is not to add ceremony. The point is to make complex agent work hard to derail.

package/adapters/claude-code/adapter.json

@@ -3,5 +3,11 @@
   "status": "portable",
   "defaultTarget": "${CLAUDE_HOME:-~/.claude}/skills",
   "metadata": "SKILL.md",
-  "fallback": "workflow-supervisor emit-context --agent claude-code --out CLAUDE.md"
+  "fallback": "workflow-supervisor emit-context --agent claude-code --out CLAUDE.md",
+  "delegate": {
+    "command": ["claude", "-p", "--output-format", "json"],
+    "promptMode": "arg",
+    "schemaMode": "json",
+    "schemaFlag": "--json-schema"
+  }
 }