Repository navigation
feat(skills): single-source skill compilation for pi + codex hosts - #14
Merged
Merged
Conversation
Skills are now authored ONCE in skills-src/taskflow/ and compiled per
host by scripts/build-skills.mjs, replacing the hand-maintained (and
drifting) pi/codex skill copies.
Authoring model:
- entry.pi.md / entry.codex.md — per-host frontmatter + host binding
(taskflow tool actions + /tf commands vs taskflow_* MCP tools)
- core.md + patterns.md + advanced.md + configuration.md — shared body;
host-only capabilities wrapped in <!-- host:pi --> / <!-- host:codex -->
blocks so a host is never taught a tool it cannot reach
Content upgrades (both hosts):
- progressive loading: SKILL.md (core) → patterns.md (6 production
archetypes, anti-pattern table, quality checklist, flow design ladder)
→ advanced.md (flow{def} contract, workspace isolation; pi also gets
Shared Context Tree + the ir/provenance/why-stale/recompute suite)
→ configuration.md (knobs, caching, fingerprints)
- pi SKILL.md now documents all 13 actions (ir/provenance/why-stale/
recompute/cache-clear were previously undocumented)
- codex skill grows from a 103-line stub to the full capability surface
minus MCP-unreachable features, with an approval-auto-reject caveat
- "When NOT to use", strictInterpolation guidance, expect+retry baked
into every example
Guardrails:
- npm run build:skills wired into npm run build
- skills-build.test.ts: --check drift guard + host-filtering assertions
- mcp-server.test.ts: example verification extended from SKILL.md to
all bundled skill files (≥5 complete flows must pass taskflow_verify)
- RELEASE.md pre-flight + AGENTS.md updated to point at skills-src/
heggria
added a commit
that referenced
this pull request
Jul 3, 2026
…ve + close follow-ups Integrates the single-source skill architecture (#14) with the Top 3 features (#16): the score/reflexion/idempotent documentation, previously edited directly in the generated SKILL.md files, is now authored ONCE in skills-src/taskflow/core.md and compiled to both hosts via build-skills.mjs. The drift guard (skills-build.test.ts) passes. Also resolves all four deferred review follow-ups (issues #17-#20) so the release ships without known debt: - #17 (loop): PhaseState.loop.failures records every failed iteration (bounded to 20, sanitized). A reflexion loop that continues past failures no longer loses the intermediate diagnostics — only the terminal one previously survived in `error`. - #18 (scorer-runtime): code-compiles now runs inside an isolated mkdtempSync directory used as the compiler cwd. Closes the predictable temp-name TOCTOU race AND stops `npx tsc` resolving a repo-planted node_modules/.bin/tsc from the phase cwd (defense-in-depth beyond the dynamic-flow scorer block). The cwd parameter is dropped from the scorer signature. (Process-group kill declined: the codebase's script phase kills the direct child too; orphans are bounded by the 30s timeout and cross-platform process groups would diverge from that.) - #19 (docs): the shared core.md now documents {reflexion}, {loop.*}, and the score.target/judge.task interpolation sites; codex SKILL.md reaches feature parity automatically through the single-source build. - #20 (idempotent): a non-idempotent phase that re-executes on resume (a prior attempt had completed) now surfaces a warning so operators see the side effect re-firing; validation warns that idempotent:false on approval/flow phases is a no-op. Docs (README, both SKILL.md sets) reflect the post-review score semantics: auto-pass only when the judge cannot veto (no judge, or weighted lower-bound), and the dynamic-flow code-compiles/regex blocks. Suite: 1014/1014 (drift guard + 4 new regression tests for the follow-ups). dist rebuilt.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Skills are now authored once in
skills-src/taskflow/and compiled per host byscripts/build-skills.mjs, replacing the two hand-maintained skill copies that had drifted (the Codex skill was a 103-line stub while the pi skill was 683 lines, and neither documented the incremental-recompute action suite).Authoring model
Host-only capabilities are wrapped in
<!-- host:pi -->/<!-- host:codex -->blocks, so a host is never taught a tool it cannot reach (e.g.recompute/save/detachare pi-only; the approval-auto-reject caveat is codex-only). ~85% of the content is shared verbatim.Content upgrades (both hosts)
SKILL.md(core) →patterns.md(6 production archetypes, anti-pattern table, quality checklist, flow design ladder L0–L5) →advanced.md(flow{def}contract, workspace isolation; pi additionally gets Shared Context Tree +ir/provenance/why-stale/recompute) →configuration.md(knobs, caching, fingerprints)SKILL.mdnow documents all 13 actions (ir/provenance/why-stale/recompute/cache-clearwere previously invisible to the LLM)strictInterpolationguidance, andexpect+retrybaked into every example so agents copy best practice by defaultGuardrails
npm run build:skillswired intonpm run buildskills-build.test.ts:--checkdrift guard (CI fails if generated files diverge fromskills-src/) + host-filtering semantic assertionsmcp-server.test.ts: flow-example verification extended fromSKILL.mdto all bundled skill files (≥5 complete flows must passtaskflow_verify)RELEASE.mdpre-flight gains a skill-coverage checklist;AGENTS.mdupdated to point atskills-src/Test plan
npm test)node scripts/build-skills.mjs --checkgreen (no drift)