Add generic flow authoring skills

README.md

@@ -9,6 +9,10 @@ metadata for Codex to load each skill without extra setup.
 
 | Skill | Use When |
 | --- | --- |
+| [`bun-flow-author`](./skills/bun-flow-author/SKILL.md) | Writing or reviewing Bun-based flow step scripts that read flow context from stdin and emit `FLOW_RESULT`. |
+| [`code-mode-flow-author`](./skills/code-mode-flow-author/SKILL.md) | Writing or reviewing Code Mode flow snippets that execute through `thread/codeMode/execute`. |
+| [`flow-backend-author`](./skills/flow-backend-author/SKILL.md) | Designing or implementing flow backend adapters, run state, idempotent dispatch, retries, and worker/app-server handoff. |
+| [`flow-package-author`](./skills/flow-package-author/SKILL.md) | Creating or updating portable flow bundles with `flow.toml`, schemas, exec snippets, fixtures, and result contracts. |
 | [`jojo-development-flow`](./skills/jojo-development-flow/SKILL.md) | Working on `peezy-tech/codex-flows` remotes, jojo.build operations, Codeberg mirroring, jojo Actions, branch tracking, release validation, or npm trusted publishing. |
 
 ## Layout

skills/bun-flow-author/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: bun-flow-author
+description: Use when writing or reviewing Bun-based flow step scripts that run under a Codex flow runner, read flow context from stdin, use Bun shell or JavaScript runtime APIs, and emit FLOW_RESULT.
+---
+
+# Bun Flow Author
+
+Use this skill for `runner = "bun"` flow steps.
+
+## Runtime Contract
+
+- The runner executes `bun <script>`.
+- The script reads one JSON object from stdin containing flow context, including `flow.config` and the triggering flow event.
+- The script must print exactly one `FLOW_RESULT <json>` line to stdout.
+- Use stderr for progress logs that should not be parsed as the result.
+
+## Step Pattern
+
+```ts
+const context = JSON.parse(await Bun.stdin.text());
+const config = context.flow.config ?? {};
+
+function result(value: Record<string, unknown>): never {
+  process.stdout.write(`FLOW_RESULT ${JSON.stringify(value)}\n`);
+  process.exit(0);
+}
+
+try {
+  // Use Bun shell or JS APIs here.
+  result({ status: "completed", artifacts: {} });
+} catch (error) {
+  result({
+    status: "failed",
+    message: error instanceof Error ? error.message : String(error),
+  });
+}
+```
+
+## Rules
+
+- Prefer structured parsing and APIs over shell text scraping when practical.
+- Use Bun shell for concise host automation, but keep commands explicit and logged.
+- Treat `event.id` as the idempotency key.
+- Do not hardcode secrets. Read environment variable names from flow config or backend config.
+- Do not encode project release/remotes policy unless the flow package points to the relevant guidance skill or local docs.
+- Return `needs_intervention` when a human or Codex turn must continue from a preserved external state.

skills/bun-flow-author/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Bun Flow Author"
+  short_description: "Write Bun flow steps that consume context and emit FLOW_RESULT."
+  default_prompt: "Author a Bun runner flow step that reads JSON context from stdin, uses Bun APIs or Bun shell safely, handles idempotency, and emits a single FLOW_RESULT line."

skills/code-mode-flow-author/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: code-mode-flow-author
+description: Use when writing or reviewing Code Mode flow step snippets that execute through a Codex app-server with thread/codeMode/execute, use injected flow context, call tools from JavaScript, and emit FLOW_RESULT.
+---
+
+# Code Mode Flow Author
+
+Use this skill for `runner = "code-mode"` flow steps.
+
+## Runtime Contract
+
+- The runner starts or connects to a Codex app-server with Code Mode enabled.
+- The runner injects `flow` and `result(value)` before the `.code-mode.js` body.
+- The snippet runs through raw `thread/codeMode/execute`.
+- The snippet must call `result(...)` once; the runner converts it to `FLOW_RESULT`.
+- Code Mode execution should be feature-flagged by the runtime or backend, not isolated on a separate branch.
+
+## Available Shape
+
+```js
+text("starting");
+const config = flow.config || {};
+
+const status = await tools.exec_command({
+  cmd: "git status --short",
+  workdir: flow.cwd,
+  yield_time_ms: 1000,
+  max_output_tokens: 4000
+});
+
+result({
+  status: "completed",
+  artifacts: { status }
+});
+```
+
+## Rules
+
+- Use `tools.exec_command` for host actions; include `workdir` explicitly when touching repos.
+- Use `text(...)` for concise progress and collected context.
+- Preserve external recovery state on conflicts or partial integrations, then return `needs_intervention`.
+- Do not assume generated client types include fork-only methods. The runner can call raw `thread/codeMode/execute`.
+- Keep the same flow package usable from `main`; use runtime/backend flags such as `CODEX_FLOWS_ENABLE_CODE_MODE=1` for Code Mode availability.
+- Avoid global installs unless the flow package explicitly requires them.
+- Keep project-specific release/remotes policy in flow README or referenced guidance skills.

skills/code-mode-flow-author/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Code Mode Flow Author"
+  short_description: "Write Code Mode flow snippets for thread/codeMode/execute."
+  default_prompt: "Author a Code Mode runner flow step that uses injected flow context, tools.exec_command, concise progress text, intervention-safe failure handling, and result(value)."

skills/flow-backend-author/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: flow-backend-author
+description: Use when designing or implementing Codex flow backend adapters, including local host execution, dispatch-only ingress, Convex orchestration, event idempotency, run state, retries, and external worker handoff.
+---
+
+# Flow Backend Author
+
+Use this skill for flow backend infrastructure, not individual flow business logic.
+
+## Backend Responsibilities
+
+A backend should provide:
+
+- `dispatch(event)` to accept generic flow events.
+- `startRun({ flow, step, event })` to start a matching step.
+- `recordStepResult({ runId, step, result })` to persist the outcome.
+- `getRun(runId)` for inspection and recovery.
+
+## Backend Kinds
+
+- **Dispatch-only ingress**: accepts or observes external events, persists audit records, and forwards generic flow events. It does not execute long-running steps.
+- **Local host execution**: stores events/runs locally and executes Bun or Code Mode steps on the host.
+- **Systemd-local execution**: a local host backend supervised by systemd; it may execute steps directly or wrap each step in a transient `systemd-run` unit.
+- **Orchestrated remote execution**: stores durable run state in a service, queues executable jobs, and uses external workers or remote app-servers for actual execution.
+
+## Rules
+
+- Treat `event.id` as the idempotency key.
+- Make dispatch and result recording safe to retry.
+- Keep payload semantics opaque to the backend except for trigger matching and schema validation.
+- Do not put organization-specific release/remotes policy into the backend.
+- For Code Mode, support either a worker-owned app-server or a configured remote app-server URL.
+- Preserve enough run state to resume or inspect `needs_intervention`, `blocked`, and `failed` runs.

skills/flow-backend-author/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Flow Backend Author"
+  short_description: "Design dispatch, local execution, and orchestration backends for flows."
+  default_prompt: "Design or implement a flow backend adapter with generic events, idempotent dispatch, run state, retries, and worker/app-server handoff without encoding project-specific policy."

skills/flow-package-author/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: flow-package-author
+description: Use when creating or updating portable Codex flow packages, including flow.toml manifests, generic FlowEvent contracts, JSON Schema payload validation, exec snippets, fixtures, and installed/source flow bundle layout.
+---
+
+# Flow Package Author
+
+Use this skill for the mechanics of packaging arbitrary flows. It does not define project-specific release, remote, mirror, credential, or publishing policy.
+
+## Core Rules
+
+- Use `flow` naming: flow bundle, `flow.toml`, flow step, flow event, `FLOW_RESULT`.
+- Keep the event envelope generic: `id`, `type`, optional `source`, optional `occurredAt`, `receivedAt`, and `payload`.
+- Put domain-specific payload shape in `schemas/*.schema.json`; do not bake repo, package, release, or git fields into the core event envelope.
+- If a flow needs project-specific behavior, declare it in `guidance.skills` and read those skills/docs before writing push, publish, mirror, branch-protection, or credential behavior.
+- Flow packages should be idempotent by `event.id`.
+
+## Layout
+
+Packageable source layout:
+
+```text
+flows/<name>/
+  flow.toml
+  schemas/*.schema.json
+  exec/*.js
+  exec/*.code-mode.js
+  README.md
+  fixtures/
+  tests/
+```
+
+Installed operational layout:
+
+```text
+.codex/flows/<name>/
+  flow.toml
+  schemas/*.schema.json
+  exec/
+```
+
+## Manifest
+
+`flow.toml` should define:
+
+```toml
+name = "example-flow"
+version = 1
+description = "Short purpose."
+
+[guidance]
+skills = []
+
+[config]
+# Package-specific, portable settings. Prefer env var names over secrets.
+commit = false
+
+[[steps]]
+name = "step-name"
+runner = "bun" # or "code-mode"
+script = "exec/step-name.js"
+timeout_ms = 300000
+
+[steps.trigger]
+type = "example.event"
+schema = "schemas/example-event.schema.json"
+```
+
+## Result Contract
+
+Every step must emit exactly one line:
+
+```text
+FLOW_RESULT {"status":"completed","message":"...","artifacts":{},"next":[]}
+```
+
+Valid statuses are `skipped`, `completed`, `changed`, `needs_intervention`, `blocked`, and `failed`.
+
+## Authoring Checklist
+
+- Add a schema for every nontrivial event payload.
+- Add at least one fixture event for each trigger.
+- Keep exec snippets relative to the flow bundle.
+- Put portable defaults and environment variable names in `[config]`; do not put secret values in the manifest.
+- Avoid hidden local handled-state as truth; prefer event ids, durable artifacts, remote refs, or backend run records.
+- Keep org-specific instructions out of this skill and inside the flow package README or referenced guidance skills.

skills/flow-package-author/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Flow Package Author"
+  short_description: "Portable flow bundle layout, manifests, schemas, and result contracts."
+  default_prompt: "Use the generic flow package conventions for flow.toml, schemas, exec snippets, fixture events, idempotency, and FLOW_RESULT contracts without encoding project-specific release policy."