workflow-supervisor 0.1.0

package/skills/worker-roles/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: worker-roles
+description: Define narrow role contracts only when creating explicit worker prompts or separating responsibilities across multiple agents, threads, reviewers, or formal handoffs. Use to prevent role bleed such as verifiers editing implementation, implementers self-approving, repair authors inventing scope, or documenters starting before evidence exists. Do not use for ordinary single-agent reviewing, editing, researching, documenting, or implementing in the current thread.
+---
+
+# Worker Roles
+
+Use this skill to make delegation safe. Each worker prompt should include one role, one objective, allowed behavior, forbidden behavior, sources to read, and a report schema.
+
+No worker thread should start before the supervisor intake and path gates are satisfied. In `human_in_loop`, that means complete intake plus human plan approval. In `autonomous_goal`, that means complete intake selecting `autonomous_goal` plus a recorded execution plan. Role-specific start conditions below are additional gates after the path gate.
+
+## Domain Neutrality
+
+Use "Executor" or "Producer" instead of "Implementer" when the work is documentation, research, design, planning, operations, data, or other non-code production. Use "artifact changed" instead of "files changed" when the mutable output is not a file.
+
+## Solo Mode
+
+When separate agents, threads, or reviewers are unavailable, collapse roles into phases in the same session. Label verification as `self-check`, not independent verification. Require independent review only when the user asks, the work is high-risk, publication-bound, regulated, security-sensitive, or the loop policy requires it.
+
+## Role Contracts
+
+### Implementer Or Executor
+
+- May edit only allowed surfaces.
+- Must not stage, commit, publish, approve, or edit workflow records unless assigned.
+- Starts only after complete intake and the path gate are satisfied and the supervisor sends the implementation dossier.
+- Must report files or artifacts changed, decisions followed, checks run or evidence produced, skipped checks, assumptions, and acceptance mapping.
+
+### Verifier
+
+- Must not edit files except unavoidable command side effects.
+- Must inspect sources and diff/artifacts independently.
+- Starts only after the relevant implementer or repair report is available.
+- Must map every acceptance item to evidence.
+- Must return PASS, FAIL, or BLOCKED.
+- Must list repair intent only, not code changes.
+
+### Researcher
+
+- Finds and ranks evidence.
+- Must distinguish source claims from inference.
+- Must not decide implementation scope.
+
+### Repair-Ticket Author
+
+- Converts verifier findings into actionable tickets.
+- Must not invent new scope.
+- Starts only after a verifier returns FAIL or BLOCKED with actionable findings.
+- Must include severity, affected surfaces or artifacts, problem, required repair, required checks or evidence, and acceptance criteria.
+- Must link each ticket to a verifier finding ID, acceptance row, or exact evidence gap.
+
+### Documenter
+
+- Creates or updates workflow artifacts from evidence.
+- Starts after complete intake and the path gate for planning docs, or after implementation and verification evidence exists for outcome docs.
+- Must preserve unknowns and residual risks.
+- Must not turn unresolved questions into facts.
+
+### Editor
+
+- Revises content for audience, structure, clarity, voice, and completeness.
+- Must not invent unsupported facts or erase source uncertainty.
+- Must report changed sections, rationale, open questions, and review needs.
+
+### Subject-Matter Reviewer
+
+- Reviews factual accuracy within an assigned domain.
+- Must distinguish required corrections from preferences.
+- Must cite sources or expertise basis for material changes.
+
+### Approver
+
+- Grants or withholds publication or workflow approval.
+- Must name caveats, required follow-ups, and expiration or review cadence when relevant.
+
+### Reviewer
+
+- Reviews completed artifacts, plans, or changes.
+- Must prioritize issues and missing evidence.
+- Must not silently repair unless explicitly assigned.
+
+### Synthesizer
+
+- Compresses context for continuation.
+- Must preserve decisions, blockers, sources, checks, and next actions.
+
+## Anti Role-Bleed Rules
+
+- A verifier that edits implementation has invalidated independence.
+- An implementer that declares final PASS without verifier evidence is premature.
+- A repair author that adds product requirements is expanding scope.
+- A documenter that hides unknowns is corrupting resume state.
+- A supervisor that implements code should mark that role switch explicitly.
+- Same-thread verification is a self-check unless an independent verifier separately inspects the evidence.
+
+## Worker Prompt Minimums
+
+Include:
+
+- thread name
+- role name
+- work unit and objective
+- must-read sources
+- allowed and forbidden surfaces
+- acceptance criteria
+- stop gates
+- exact report schema
+
+## Thread Interaction Rules
+
+- Workers should acknowledge the handoff before acting.
+- Workers should ask the supervisor for clarification when a blocker affects scope, sources, surfaces, checks, or acceptance.
+- Workers should not message other worker threads directly unless the supervisor allows it in the loop policy.
+- Workers should send one terminal report with PASS, FAIL, BLOCKED, or PARTIAL status using the assigned schema.
+- Verifier and repair threads should cite acceptance row IDs and prior report IDs so the supervisor can route the loop.

package/skills/worker-roles/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Worker Roles"
+  short_description: "Define narrow worker thread contracts"
+  default_prompt: "Use $worker-roles to assign strict thread roles and prevent role bleed in this workflow."
+
+policy:
+  allow_implicit_invocation: false

package/skills/workflow-docs/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: workflow-docs
+description: Generate or refresh durable workflow-state, handoff, resume, verification, repair, decision, or documentation-production control artifacts. Use when the work needs reusable state such as workflow control docs, documentation briefs, source inventories, review plans, revision queues, publishing checklists, or maintenance plans. Do not use for ordinary README edits, help article drafting, prose cleanup, summaries, marketing copy, decorative docs, or documentation content unless reusable workflow/documentation-production state is requested.
+---
+
+# Workflow Docs
+
+Use this skill to make the workspace remember the workflow. These Markdown files are working artifacts, not explanatory essays.
+
+## No-Prerequisite Mode
+
+Do not require existing Markdown files. You may create a minimal doc set from conversation context alone, as long as unknowns are marked. For non-document workflows, create only the artifacts that help the next agent or human continue.
+
+## State Artifact Medium
+
+Markdown is the default when the workspace/file medium is appropriate, but reusable workflow 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. Choose the medium that the next human or agent can actually use.
+
+## Default Artifact Directory
+
+When creating Markdown workflow artifacts, use `<workspace>/.workflow/` as the default directory. Treat `<workspace>` as the active project root, repository root, or user-provided working directory. If the task has no stable workspace, keep state inline or ask where to write it.
+
+Use another location only when the user names one, the project has an existing workflow-state convention, the target medium is not files, or the artifact is a final deliverable that belongs elsewhere. Keep control artifacts under `.workflow/` even when implementation files, docs, or product outputs are created in normal project locations.
+
+## Artifact Lanes
+
+Use two lanes:
+
+- Workflow control: preserve state, decisions, work units, handoffs, verification, and outcomes.
+- Documentation production: define audience, purpose, content inventory, outline, style, review path, publication readiness, and maintenance.
+
+For documentation work, start with `DOCUMENTATION-BRIEF.md` unless the user provides an equivalent brief. Without audience, reader task, document type, owner, source expectations, and publishing target, create a brief or ask for the missing decision before drafting final content.
+
+## Modes
+
+- Scaffold blank artifacts for a new workflow.
+- Generate artifacts from conversation, source inspection, or supervisor state.
+- Refresh existing artifacts while preserving unresolved questions and decisions.
+- Create a resume pack for another thread or future session.
+- Convert verification and repair results into durable reports.
+- Preserve thread plans, worker handoffs, terminal reports, and final disposition decisions when supervised work spans threads.
+
+## Rules
+
+- Load [references/templates.md](references/templates.md) first when choosing exact templates, then load only the referenced lane file needed for the task.
+- Load [references/documentation-production.md](references/documentation-production.md) for documentation deliverables, content drafts, claims registers, review plans, publishing, and maintenance.
+- Load [references/workflow-control.md](references/workflow-control.md) for supervised workflow state, work units, dossiers, acceptance, verification, repairs, decisions, handoffs, and outcomes.
+- Load [references/goal-resume.md](references/goal-resume.md) for Codex goal mirrors, active-goal conflicts, and resume packs.
+- Keep facts, assumptions, open questions, and inferences separate.
+- Include paths, commands, sources, and evidence when available.
+- Do not hide missing information. Use `Unknown` or `Blocked` with reason.
+- Prefer concise tables and checklists over narrative.
+- Do not create files the workflow will not use.
+- Reject requests to create every possible workflow document "just in case"; select the smallest doc set that preserves state or enables production.
+- Do not treat workflow docs as a required provenance ledger; use them as lightweight working memory.
+- Adapt headings from files and commands to artifacts and evidence for non-code workflows.
+- Preserve acceptance matrices and verification reports; do not reinterpret evidence rows or change verdicts unless the workflow explicitly asks for a review/update.
+
+## Artifact Selection
+
+- `.workflow/WORKFLOW.md`: overall objective, policy, state, units, and next action.
+- `.workflow/SOURCE-CORPUS.md`: source map, authority ranking, contradictions, gaps.
+- `.workflow/WORK-UNITS.md`: decomposition and sequencing.
+- `.workflow/DOSSIER.md`: handoff contract for one unit.
+- `.workflow/THREAD-MAP.md`: thread names, roles, dossiers, dependencies, start conditions, report status, and supervisor checkpoints.
+- `.workflow/ACCEPTANCE-MATRIX.md`: verifiable done criteria.
+- `.workflow/VERIFICATION-REPORT.md`: evidence-backed PASS/FAIL/BLOCKED report.
+- `.workflow/REPAIR-TICKETS.md`: actionable repair tasks from verifier findings.
+- `.workflow/DECISIONS.md`: durable decisions, assumptions, and reversals.
+- `.workflow/HANDOFF.md`: resume state for another agent or session.
+- `.workflow/OUTCOME.md`: final status, checks, risks, and next step.
+- `.workflow/GOAL-STATE.md`: optional fallback record when a Codex goal tool is unavailable or goal state must be mirrored for handoff.
+- `.workflow/DOCUMENTATION-BRIEF.md`: audience, purpose, document type, reader task, channel, owner, approvers, and success criteria.
+- `.workflow/CONTENT-INVENTORY.md`: existing materials, reusable sections, gaps, stale areas, and owners.
+- `.workflow/OUTLINE.md`: information architecture, section hierarchy, and required content.
+- `.workflow/STYLE-GUIDE.md`: tone, terminology, formatting, examples, and banned phrasing.
+- `.workflow/GLOSSARY.md`: approved terms, definitions, aliases, and deprecated terms.
+- `.workflow/REVIEW-PLAN.md`: SME, editorial, legal, compliance, accessibility, localization, and approval steps.
+- `.workflow/REVISION-QUEUE.md`: section-level feedback and editorial repair tasks.
+- `.workflow/PUBLISHING-CHECKLIST.md`: metadata, links, assets, permissions, approvals, and launch target.
+- `.workflow/MAINTENANCE-PLAN.md`: owner, review cadence, expiry date, and update triggers.
+- `.workflow/CONTENT-DRAFT.md`: actual documentation draft body with audience, reader task, sources, open claims, examples, review status, and publishing target.
+- `.workflow/CLAIMS-REGISTER.md`: claim-level source, citation, confidence, reviewer, status, rights, and recheck tracking.
+- `.workflow/ASSET-REGISTER.md`: images, diagrams, videos, source files, licenses, owners, and usage status.
+- `.workflow/PUBLICATION-LOG.md`: channel, version, approver, date, and notes for published artifacts.
+
+## Output Requirement
+
+When generating docs, report which files were created or updated, which artifact directory was used, which sources informed them, and which fields remain unknown.

package/skills/workflow-docs/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Workflow Docs"
+  short_description: "Preserve workflow and thread state"
+  default_prompt: "Use $workflow-docs to create or refresh .workflow/ artifacts that preserve workflow, thread, handoff, verification, and outcome state."
+
+policy:
+  allow_implicit_invocation: false

package/skills/workflow-docs/references/documentation-production.md

@@ -0,0 +1,230 @@
+# Documentation Production Templates
+
+Use these for documentation production. Do not create all of them by default; select the smallest set that supports the document type and review path.
+
+Default path: create documentation-production control artifacts under `<workspace>/.workflow/` unless the user names another artifact directory or the project already has an established workflow-state location. Final public docs, app files, articles, or published content may still belong in their normal product or documentation locations.
+
+## Presets
+
+- Public article: `DOCUMENTATION-BRIEF.md`, `CONTENT-INVENTORY.md`, `OUTLINE.md`, `CONTENT-DRAFT.md`, `REVIEW-PLAN.md`, `PUBLISHING-CHECKLIST.md`.
+- Fact-heavy reference: `DOCUMENTATION-BRIEF.md`, `SOURCE-CORPUS.md`, `CLAIMS-REGISTER.md`, `GLOSSARY.md`, `MAINTENANCE-PLAN.md`.
+- SOP or runbook: `DOCUMENTATION-BRIEF.md`, `OUTLINE.md`, `CONTENT-DRAFT.md`, `REVIEW-PLAN.md`, `PUBLISHING-CHECKLIST.md`, `MAINTENANCE-PLAN.md`.
+- Release notes: `DOCUMENTATION-BRIEF.md`, `CONTENT-INVENTORY.md`, `CONTENT-DRAFT.md`, `REVIEW-PLAN.md`, `PUBLICATION-LOG.md`.
+- Research memo: `DOCUMENTATION-BRIEF.md`, `SOURCE-CORPUS.md`, `CLAIMS-REGISTER.md`, `CONTENT-DRAFT.md`, `REVIEW-PLAN.md`.
+
+## DOCUMENTATION-BRIEF.md
+
+```md
+# Documentation Brief
+
+## Document Type
+
+## Audience
+
+## Reader Knowledge Level
+
+## Reader Tasks
+
+## Desired Reader Action
+
+## Primary Use Case
+
+## Publishing Target Or Channel
+
+## Owner
+
+## Approvers
+
+## Scope
+
+## Non-Goals
+
+## Source Requirements
+
+## Confidentiality Or Access Constraints
+
+## Freshness Requirement
+
+## Voice And Tone
+
+## Success Criteria Or Analytics Signal
+
+## Constraints
+
+## Open Questions
+```
+
+## CONTENT-INVENTORY.md
+
+```md
+# Content Inventory
+
+| Material | Type | Canonical Location | Owner | Version | Last Reviewed | License Or Permission | Current State | Reuse Candidate | Stale Areas | Gaps | Action Needed | Risk |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+## Missing Materials
+
+## Reuse Plan
+```
+
+## OUTLINE.md
+
+```md
+# Outline
+
+## Information Architecture
+
+| Section | Reader Task | Key Question | Evidence Or Source | Examples Or Assets | Acceptance Criteria | Owner | Status |
+|---|---|---|---|---|---|---|---|
+
+## Navigation Or Reading Flow
+
+## Required Examples
+
+## Open Structure Questions
+```
+
+## CONTENT-DRAFT.md
+
+```md
+# Content Draft
+
+Status: Draft | Needs Review | Ready To Publish | Blocked
+
+## Title
+
+## Audience
+
+## Reader Task
+
+## Publishing Target
+
+## Source Notes
+
+## Draft Body
+
+## Open Claims
+
+| Claim | Location | Source Needed | Status |
+|---|---|---|---|
+
+## Examples Or Assets
+
+## Review Status
+
+## Open Questions
+```
+
+## CLAIMS-REGISTER.md
+
+```md
+# Claims Register
+
+| Claim | Location | Source | Citation Needed | Usage Rights | Confidence | Reviewer | Status | Expiry Or Recheck Trigger |
+|---|---|---|---|---|---|---|---|---|
+```
+
+## STYLE-GUIDE.md
+
+```md
+# Style Guide
+
+## Voice And Tone
+
+## Terminology
+
+| Preferred Term | Definition | Avoid | Notes |
+|---|---|---|---|
+
+## Formatting Rules
+
+## Examples
+
+## Banned Phrasing
+```
+
+## GLOSSARY.md
+
+```md
+# Glossary
+
+| Term | Definition | Aliases | Deprecated Terms | Source |
+|---|---|---|---|---|
+```
+
+## ASSET-REGISTER.md
+
+```md
+# Asset Register
+
+| Asset | Type | Source | Owner | License Or Permission | Used In | Status | Risk |
+|---|---|---|---|---|---|---|---|
+```
+
+## REVIEW-PLAN.md
+
+```md
+# Review Plan
+
+| Review Type | Reviewer | Scope | Required Before | Status |
+|---|---|---|---|---|
+
+## Approval Path
+
+## Review Cadence
+
+## Blocking Reviews
+```
+
+## REVISION-QUEUE.md
+
+```md
+# Revision Queue
+
+| ID | Location | Reviewer | Issue Type | Audience Impact | Requested Change | Owner | Due Date | Status | Validation |
+|---|---|---|---|---|---|---|---|---|---|
+```
+
+## PUBLISHING-CHECKLIST.md
+
+```md
+# Publishing Checklist
+
+| Item | Owner | Status | Evidence |
+|---|---|---|---|
+
+## Metadata
+
+## Links And Assets
+
+## Permissions
+
+## Approvals
+
+## Launch Target
+```
+
+## PUBLICATION-LOG.md
+
+```md
+# Publication Log
+
+| Date | Artifact | Channel | Version | Approver | Notes |
+|---|---|---|---|---|---|
+```
+
+## MAINTENANCE-PLAN.md
+
+```md
+# Maintenance Plan
+
+## Owner
+
+## Review Cadence
+
+## Expiry Or Review Date
+
+## Update Triggers
+
+## Monitoring Sources
+```

package/skills/workflow-docs/references/goal-resume.md

@@ -0,0 +1,62 @@
+# Goal And Resume Templates
+
+Use these only for Codex goal mirroring, active-goal conflicts, or resume packs.
+
+Default path: create `GOAL-STATE.md` and goal-aware workflow artifacts under `<workspace>/.workflow/` unless the user provides another artifact directory or the project already has an established workflow-state location.
+
+## Goal-Aware WORKFLOW.md Fields
+
+```md
+## Goal Binding
+
+- Goal Binding: created | reused | skipped | unavailable | conflict
+- Goal Status: active | complete | blocked | unknown
+- Last Goal Tool Action: get_goal | create_goal | update_goal | none
+- Next Allowed Goal Action:
+- Goal Objective:
+```
+
+## Goal-Aware OUTCOME.md Fields
+
+```md
+Goal Binding: created | reused | skipped | unavailable | conflict
+Goal Status: active | complete | blocked | unknown
+Last Goal Tool Action: get_goal | create_goal | update_goal | none
+Next Allowed Goal Action:
+```
+
+## GOAL-STATE.md
+
+```md
+# Goal State
+
+## Objective
+
+## Goal Binding
+
+created | reused | skipped | unavailable | conflict
+
+## Goal Status
+
+active | complete | blocked | unknown
+
+## Why A Goal Was Created Or Skipped
+
+## Active Goal Conflict
+
+## Last Tool Action
+
+get_goal | create_goal | update_goal | none
+
+## Next Allowed Goal Action
+
+## Last Evidence
+
+## Current Work Unit
+
+## Completion Rule
+
+## Blocked Rule
+
+## Resume Instructions
+```

package/skills/workflow-docs/references/templates.md

@@ -0,0 +1,53 @@
+# Workflow Docs Template Index
+
+Load only the lane needed for the task.
+
+Create Markdown artifacts 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.
+
+## Documentation Production
+
+Read [documentation-production.md](documentation-production.md) when creating or revising documentation deliverables, briefs, outlines, factual source registers, review plans, publication assets, or maintenance plans.
+
+Includes:
+
+- `DOCUMENTATION-BRIEF.md`
+- `CONTENT-INVENTORY.md`
+- `OUTLINE.md`
+- `CONTENT-DRAFT.md`
+- `CLAIMS-REGISTER.md`
+- `STYLE-GUIDE.md`
+- `GLOSSARY.md`
+- `ASSET-REGISTER.md`
+- `REVIEW-PLAN.md`
+- `REVISION-QUEUE.md`
+- `PUBLISHING-CHECKLIST.md`
+- `PUBLICATION-LOG.md`
+- `MAINTENANCE-PLAN.md`
+
+## Workflow Control
+
+Read [workflow-control.md](workflow-control.md) when preserving supervised workflow state, work units, dossiers, acceptance matrices, verification reports, repairs, decisions, handoffs, or outcomes.
+
+Includes:
+
+- `WORKFLOW.md`
+- `SOURCE-CORPUS.md`
+- `WORK-UNITS.md`
+- `DOSSIER.md`
+- `THREAD-MAP.md`
+- `ACCEPTANCE-MATRIX.md`
+- `VERIFICATION-REPORT.md`
+- `REPAIR-TICKETS.md`
+- `DECISIONS.md`
+- `HANDOFF.md`
+- `OUTCOME.md`
+
+## Goal And Resume
+
+Read [goal-resume.md](goal-resume.md) when mirroring Codex goal state, resolving active-goal conflicts, or creating resume packs.
+
+Includes:
+
+- `GOAL-STATE.md`
+- goal-aware `WORKFLOW.md` fields
+- goal-aware `OUTCOME.md` fields