DX charter: self-onboarding for humans and agents — tested examples, packaged tooling, and docs that cannot lie

The bar: someone — human or agent, in an editor or a terminal, via Claude Code or Codex — encounters Flowstate or one of its plugins cold, and gets productive without a guide, because every surface they touch teaches them and none of it can be stale. Like a real programming-language project: the README compiles, the examples run, the editor talks back, and the pieces fit like they were designed together — because they were.

This repo already invented the mechanisms. The charter is to apply them everywhere, deliberately:

1. Examples that cannot rot, extended to plugins

The house pattern exists: examples/*/workflow.yaml runs in CI on both drivers; examples/README.md's index is test-pinned against the directories on disk; docs/reference/ is generated and diff-pinned. What plugins need on top:

• Every plugin example executes in CI, not just validates — the reachability work in flight covers registration/validation; execution against stand-ins (the NewUndoServer recording pattern, a local git repo built by the test) covers the rest. No real network in tests, ever.
• The README's commands are the test's commands. A plugin README shows flow run local … --plugin-dir …; a Go test runs that same invocation. Where prose shows output, the test asserts it. One source, mirrored by machinery (the cmd/flow/internal/reference mirror pattern exists for exactly this), so a reader of the markdown is reading something proven that morning.
• Plugins are usable as test fixtures by users: a documented, supported way to run a workflow against a plugin in one's own Go test — build, launch, register, run — packaged as a helper rather than folklore. Today that knowledge lives inside pkg/flowstate/v1/plugin's own tests. This is also the seed of flow test (#135).

2. The editor path: it talks back, everywhere

flow lsp exists with five editors documented; --plugin-dir makes it plugin-aware. The gaps to close so the loop is effortless:

• Plugin task completion, hover, and type-checking parity with built-ins when --plugin-dir is given — the manifest carries the schema; the LSP should use all of it.
• A one-command editor setup per editor in each plugin's README — not a page of config, one block, copied from EDITORS.md's pattern.
• Diagnostics stay the product surface they are: an author misusing a plugin task learns in their editor, with a position, before anything runs.

3. Agent packaging: idiomatic in each ecosystem, one source of truth

Agents are first-class users. The repo already carries .claude/commands/ skills (ci-check, test-fast, both-drivers) and an MCP server (flow mcp) with resources. What "just works" means per ecosystem:

• Claude Code: a Flowstate plugin — MCP server config + the skills + hooks packaged so flow projects light up: validation on save, flowstate_run_local for authoring loops, the DSL docs as MCP resources (already served). The skills that exist were written for this repo's development; the packaged set is for users of Flowstate — authoring, running, debugging a workflow.
• OpenAI Codex: AGENTS.md at the root (the ecosystem's convention) distilled from CLAUDE.md's user-relevant half, and MCP config for Codex's client shape. Same content, each ecosystem's native spelling.
• Anti-drift rule: ecosystem files are derived — generated or test-pinned against one canonical source, exactly like docs/reference/. Two hand-maintained copies of "how to use Flowstate" is a drift generator; this repo's whole doc philosophy says no.

4. The self-onboarding test

The honest check for all of it, and a real CI job eventually: can an agent, given only the repo and the packaged tooling, author a new workflow that uses a plugin, validate it, run it locally, and read the result — without a human in the loop? That is measurable. When it passes cold, the DX is real; until then it is aspiration. (The MCP flowstate_run_local + resources work got most of the way there for built-ins; plugins are the frontier.)

Sequencing

(1) rides the reachability stream now in flight and #149's factoring. (2) is mostly LSP work sized small. (3) is packaging over existing machinery. (4) is the acceptance test for the lot. None of it blocks the engine streams; all of it compounds — every plugin added after this charter inherits the pattern instead of re-earning it.

Related: #135 (flow test), #149 (plugin factoring), #151 (remote plugins — the agent-auth story there is this charter's security half), #152 (CEL coherence — the "it talks back" substrate).

Start by reading examples/README.md and the existing examples/*/workflow.yaml CI pattern, then inspect pkg/flowstate/v1/plugin tests, cmd/flow/internal/reference, flow lsp, and flow mcp. Break the charter into a focused slice before changing anything. Done requires a tested, non-drifting onboarding path that lets a cold user author, validate, run, and inspect a plugin workflow without human guidance.