@workflow-manager/runner/skills/doc-sync/SKILL.md

CLI runner for in-memory and markdown workflow orchestration using ATEP-like envelopes

---
name: doc-sync
description: >
  Load this skill whenever a change affects user-visible behavior in
  workflow-manager: CLI flags, command output, workflow schema, public
  TypeScript types, adapters, the remote registry surface, or environment
  variables. Ensures README, doc/, AGENTS.md, and in-CLI help stay in sync.
type: core
applies_to:
  - "src/index.ts"
  - "src/parser.ts"
  - "src/engine.ts"
  - "src/types.ts"
  - "src/remote/**"
  - "apps/remote-registry/**"
  - "doc/**"
  - "README.md"
  - "AGENTS.md"
---

# Doc Sync

Use this skill to keep documentation honest. In this repo, documentation is part of the product surface — the CLI is published, workflows are shared via the remote registry, and the docs site is built from `doc/`. Out-of-date docs are a bug.

## When to use this skill

Load it whenever the change does any of the following:

- Adds, removes, or renames a CLI command, flag, or argument in `src/index.ts`.
- Changes workflow schema, defaults, or validation rules in `src/parser.ts` or `src/types.ts`.
- Changes engine semantics (approvals, retries, rollback, restart, snapshot shape) in `src/engine.ts`.
- Adds or changes an adapter (`mock`, `opencode`, `codex`, `claude-code`, future adapters).
- Changes remote registry behavior in `src/remote/**` or `apps/remote-registry/**`.
- Introduces or renames an environment variable or required local service.
- Bumps a public type or contract referenced by docs or other packages.

If none of the above is true, this skill is not needed.

## Required updates by change type

| Change | Update |
| --- | --- |
| New / renamed CLI command or flag | Usage text in `src/index.ts`, `README.md` Quickstart and CLI section, the matching `doc/` page, and the man page source if behavior is reflected there. |
| Workflow schema change | `README.md` schema section, the relevant page under `doc/guide/` or `doc/reference/`, plus the `workflow-manager-cli` skill checklist if authoring rules shift. |
| Engine semantics change | The corresponding `doc/` engine page and any example workflows in `example-workflow.{md,json}` that no longer demonstrate the new behavior accurately. |
| Adapter added or changed | List of supported adapters in `AGENTS.md`, `README.md`, and `doc/`. The `workflow-manager-cli` skill must also list it. |
| Remote registry change | `apps/remote-registry/DESIGN.md` if UI/UX shifts, `README.md` remote section, `doc/` remote pages, and any onboarding snippets. |
| New env var or required service | `README.md` setup section, `AGENTS.md` Install And Setup, and any `.env.example` files. Never commit real secrets. |

## Workflow

1. Diff your change and list every user-visible surface it touches.
2. For each surface, open the matching doc file and update it in the same PR. Do not defer to a follow-up.
3. Rebuild docs to catch broken links or examples:
   ```bash
   bun run docs:build
   ```
4. If you changed the remote-registry app, also run:
   ```bash
   bun run remote-registry:build
   ```
5. Re-read the README quickstart end-to-end and confirm the commands you ship still work as written.

## Style rules

- Match the existing tone of the surrounding doc. Do not introduce a new voice.
- Prefer runnable examples over prose. Examples should match the actual current CLI output.
- Keep command examples copy-pasteable. No invented flags or fictitious env vars.
- When you remove or rename a flag, document the migration in the same section, not in a separate changelog-only entry.
- Cross-link related docs sparingly and only when they meaningfully help the reader.

## Anti-patterns to refuse

- Updating code without updating docs "because the docs are out of date anyway".
- Adding a doc page that is not linked from the docs nav or another page.
- Copying README content into `doc/` instead of linking, creating two sources of truth.
- Leaving `TODO: update docs` markers in a finished PR.

## Definition of done

- Every user-visible behavioral change is reflected in `README.md`, the relevant `doc/` pages, in-CLI `--help`, and `AGENTS.md` where applicable.
- `bun run docs:build` passes.
- Examples in updated docs were actually executed (or visually verified) against the new behavior.