Skip to content

feat(framework): read action files before running, across all skills#389

Merged
blafourcade merged 3 commits into
nextfrom
fix/brainstorm-finalize-persist-order
Jul 6, 2026
Merged

feat(framework): read action files before running, across all skills#389
blafourcade merged 3 commits into
nextfrom
fix/brainstorm-finalize-persist-order

Conversation

@blafourcade

Copy link
Copy Markdown
Contributor

What

Every router skill now tells the host to read an action's file before running it, and the brainstorm finalize step is reordered so it persists before pointing to the next move.

Why

On hosts that don't follow the SKILL.md router into the actions/ files (codex, copilot), skills were improvising steps from SKILL.md alone. The clearest symptom: brainstorm finalize never offered to persist (file/ticket/session) because that detail lives only in actions/04-finalize.md, which those hosts never opened. Two fixes:

  1. Read the action file — a uniform routing line added to all 38 router skills' SKILL.md and the skill-generate template:

    Before running an action, read its file in actions/, not only the table or assets.

  2. Persist before next move — brainstorm finalize reordered so the persist offer runs before the next-move pointer, making the truncatable closing beat the guidance, never the durable artifact.

Testing (headless, codex + Claude)

  • Codex: rebuilt + installed the native tree, drove each skill with a realistic intent. ~32/38 skills now open their action file(s), including every multi-action flow (bootstrap, plan, user-stories, pull-request, sdlc, audit 7/7, review 3/3, generate family). Validated flow, step-entry, fallback, menu-all, and menu-subset paths.
  • Claude: plan and brainstorm read their action files and their assets (plan-template, phase-template) — the not only the table or assets wording does not make Claude skip assets. No regression.

Known limits (out of scope here)

  • ~6 single-shot / interactive skills (commit, spec, fact-check, skill-generate, challenge, brainstorm) still improvise on trivial one-shot tasks on codex: the host answers directly without framing it as "running action X", so the trigger doesn't arm. A stronger wording fixed some but broke precise subset control, so it was reverted. The important multi-action flows all follow.
  • aidd-orchestrator/00-async-dev uses nested actions/setup/ + actions/run/ dirs; the generic line was not applied there.

Future skills

The line is baked into skill-generate's template, so newly generated skills carry it automatically.

blafourcade and others added 3 commits July 6, 2026 06:39
Reorder brainstorm finalize so the persist offer (file/ticket/session)
runs before the next-move pointer, and slim the persist step. The
truncatable closing beat becomes the guidance, never the durable
artifact, which weak-adherence hosts were dropping.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt
Add a uniform routing line to every router skill's SKILL.md and the
skill-generate template: before running an action, read its file in
actions/, not only the table or assets. Hosts that do not follow the
SKILL router into the action files (codex, copilot) were improvising
steps from SKILL.md alone and skipping action-only detail such as the
brainstorm persist offer. Verified on codex and Claude: multi-action
flows and the majority of skills now open their action files; Claude
still reads assets, no regression.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt
@blafourcade blafourcade marked this pull request as ready for review July 6, 2026 04:52
@blafourcade blafourcade merged commit 871b9f6 into next Jul 6, 2026
7 checks passed
blafourcade added a commit that referenced this pull request Jul 6, 2026
…389)

* fix(refine): finalize persists before pointing to the next move

Reorder brainstorm finalize so the persist offer (file/ticket/session)
runs before the next-move pointer, and slim the persist step. The
truncatable closing beat becomes the guidance, never the durable
artifact, which weak-adherence hosts were dropping.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt

* feat(framework): read the action file before running it

Add a uniform routing line to every router skill's SKILL.md and the
skill-generate template: before running an action, read its file in
actions/, not only the table or assets. Hosts that do not follow the
SKILL router into the action files (codex, copilot) were improvising
steps from SKILL.md alone and skipping action-only detail such as the
brainstorm persist offer. Verified on codex and Claude: multi-action
flows and the majority of skills now open their action files; Claude
still reads assets, no regression.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt

* docs(framework): record the PR template in vcs memory

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant