feat(skills): single-source skill compilation for pi + codex hosts

AGENTS.md

@@ -44,21 +44,26 @@ packages/
 │  │  ├─ render.ts / runs-view.ts / approval-view.ts  ← pi-tui rendering + interactive views
 │  │  └─ init.ts           ← /tf init command: scaffolds a taskflow / model roles interactively
 │  ├─ test/              ← pi-adapter unit tests + .mts e2e scripts
-│  └─ skills/            ← SKILL.md files that teach the LLM how to write taskflows
+│  └─ skills/            ← GENERATED per-host skill files (do not edit; see skills-src/)
 └─ codex-taskflow/         ← Codex adapter (depends on taskflow-core)
    ├─ src/
    │  ├─ codex-runner.ts   ← codex subagent runner (`codex exec --json`) + CodexSubagentRunner
    │  └─ mcp/              ← dependency-free stdio MCP server (jsonrpc.ts, server.ts, bin.ts)
    ├─ plugin/            ← Codex plugin scaffold (`codex plugin add taskflow@taskflow`)
    │  ├─ .codex-plugin/plugin.json  ← plugin manifest (skills + mcpServers pointers)
    │  ├─ .mcp.json         ← declares the taskflow MCP server via `npx codex-taskflow`
-   │  ├─ skills/taskflow/  ← SKILL.md (trigger) + agents/openai.yaml (Codex interface)
+   │  ├─ skills/taskflow/  ← GENERATED per-host skill files (do not edit; see skills-src/)
    │  └─ assets/           ← plugin icons (taskflow.svg, taskflow-small.svg)
    └─ test/              ← codex-adapter unit tests + .mts e2e scripts
 
 .claude-plugin/           ← marketplace.json (repo-root; `codex plugin marketplace add heggria/taskflow`)
 
-scripts/                  ← build helpers (copy-agents.mjs copies agent .md into dist)
+skills-src/taskflow/      ← SINGLE SOURCE for both hosts' skills: entry.pi.md + entry.codex.md
+                            (frontmatter + host binding) + core.md/patterns.md/advanced.md/
+                            configuration.md (shared body with <!-- host:pi/codex --> blocks).
+                            Compiled by scripts/build-skills.mjs (npm run build:skills);
+                            drift-guarded by packages/pi-taskflow/test/skills-build.test.ts.
+scripts/                  ← build helpers (copy-agents.mjs, build-skills.mjs)
 examples/                 ← runnable flow definitions (.json)
 docs/                     ← design docs, RFCs, dogfooding reports, codex-mcp guide
 tsconfig.base.json        ← shared compiler options; per-package tsconfig.build.json emits dist
@@ -174,7 +179,7 @@ npm run test:e2e-codex-mcp-full  # codex MCP comprehensive e2e against the built
 2. Add per-type validation in `validateTaskflow()`.
 3. Add the execution branch in `executePhase()` in `runtime.ts`.
 4. Add tests in `packages/taskflow-core/test/runtime-branches.test.ts` (or a new file).
-5. Update `SKILL.md` with usage guidance.
+5. Update the skill sources in `skills-src/taskflow/` (never the generated files) and run `node scripts/build-skills.mjs`.
 
 ### Adding a New Condition Operator
 1. Add the token to `OPS` in `interpolate.ts`.
@@ -192,7 +197,7 @@ npm run test:e2e-codex-mcp-full  # codex MCP comprehensive e2e against the built
 2. Update `validateTaskflow()` if new constraints are needed.
 3. Update `desugar()` if the shorthand needs to emit the new field.
 4. Update `interpolate.ts` if new placeholder paths are introduced.
-5. Update `SKILL.md` and `README.md`.
+5. Update the skill sources in `skills-src/taskflow/` and `README.md`, then run `node scripts/build-skills.mjs`.
 
 > All of `schema.ts`, `runtime.ts`, `interpolate.ts`, `cache.ts`, `agents.ts` live in `packages/taskflow-core/src/`.
 

RELEASE.md

@@ -33,6 +33,28 @@ npm test               # 918/918 green
 npm run build          # emit dist/ for all three packages (tsc → .js + .d.ts)
 ```
 
+### Skill coverage check (before every release)
+
+The skills are the LLM-facing API surface — an engine feature the skill doesn't
+teach effectively does not exist. **Skills are authored ONCE in
+`skills-src/taskflow/` and compiled per host** by `scripts/build-skills.mjs`
+(pi → `packages/pi-taskflow/skills/taskflow/`, codex →
+`packages/codex-taskflow/plugin/skills/taskflow/`). Never edit the generated
+files — `skills-build.test.ts` fails CI on drift. For every feature/change in
+this release's CHANGELOG section, verify:
+
+- [ ] New DSL fields, phase types, actions, and commands appear in the right
+      **source** layer: `core.md` (core DSL + actions), `patterns.md` (if it
+      changes best practice), `advanced.md` (context sharing / dynamic flows /
+      isolation / recompute), `configuration.md` (knobs), or the per-host
+      entry files (`entry.pi.md` / `entry.codex.md`) for host bindings.
+- [ ] Host-only capabilities are wrapped in `<!-- host:pi -->` /
+      `<!-- host:codex -->` blocks — never teach a host a tool it can't reach.
+- [ ] `node scripts/build-skills.mjs` ran and the generated files are committed.
+- [ ] The `taskflow` tool description in the pi adapter (`src/index.ts`) lists
+      any new `action` values.
+- [ ] Removed/renamed fields are purged from `skills-src/` (grep the old name).
+
 > **Why a build step.** Node refuses to type-strip `.ts` files under
 > `node_modules`, so the published packages ship compiled `dist/*.js` + `.d.ts`.
 > `prepublishOnly` runs `npm run build` automatically, so `npm publish` always

package.json

@@ -13,7 +13,8 @@
     "packages/codex-taskflow"
   ],
   "scripts": {
-    "build": "npm run build -w taskflow-core && npm run build -w pi-taskflow && npm run build -w codex-taskflow",
+    "build": "npm run build:skills && npm run build -w taskflow-core && npm run build -w pi-taskflow && npm run build -w codex-taskflow",
+    "build:skills": "node scripts/build-skills.mjs",
     "typecheck": "tsc --noEmit",
     "test": "PI_TASKFLOW_BUILTIN_AGENTS_DIR= node --conditions=development --experimental-strip-types --test 'packages/*/test/*.test.ts'",
     "test:core": "PI_TASKFLOW_BUILTIN_AGENTS_DIR= node --conditions=development --experimental-strip-types --test 'packages/taskflow-core/test/*.test.ts'",