v2.3.1 to v2.3.2

- version: 2.3.1

- Internal skill for the agentic-workflow repo. After editing one or more

- SKILL.md files, bumps their `version:` fields and updates every piece of

- documentation in the repo that must stay in sync: CHANGELOG.md,

- CHANGELOG.es.md, README.md, and README.es.md. Run before committing any

- skill change. On Claude Code and want hand-tuned per-skill model/effort tiers? Install the `#claude` branch instead (`npx skills add gtrabanco/agentic-workflow#claude`) — see the README. This branch is model-agnostic: the skill inherits whatever model and effort your agent session is already using.

- Trigger phrases: "bump the skill version", "update the

- version", "update the changelog", "I just changed a skill", "log this

- change", "version bump".

- ### 1. Identify changed skills

-

- Run `git diff --name-only HEAD` and `git diff --cached --name-only` to find

- every modified `skills/*/SKILL.md`. Union both lists (covers staged and

- unstaged). If the user names specific skills explicitly, use those instead and

- verify the files exist.

-

- If no modified skill files are found, say so and stop.

-

- ### 2. For each changed skill — read the diff and determine the bump

-

- Run `git diff HEAD skills/<name>/SKILL.md` (add `--cached` if staged). Read

- the diff carefully:

-

- - **major** — the `name:` changed, a flag or section was removed, the output

- contract changed fundamentally. Also check `docs/workflow/MIGRATION.md` to

- see if a migration note is needed.

- - **minor** — a new section, new flag, new routing case, or meaningfully

- expanded capability was added.

- - **patch** — wording, examples, formatting, or internal clarifications only.

-

- If the nature of the change is ambiguous, ask the user before proceeding. One

- question covering all ambiguous skills at once is fine.

-

- ### 2b. Lint the repo's authoring rules (flag, don't fix)

-

- For each changed skill, check the seven `CLAUDE.md` authoring invariants and **warn**

- if violated (this skill never edits a SKILL.md beyond its `version:` line, so it

- reports — it does not auto-correct):

-

- - **Closing `→ Next:` block.** A user-facing skill should end with a visible

- `→ Next:` recommendation block (recommended command + open `·` alternatives), not

- just a "Done when" bullet. `grep -L '→ Next:' skills/<name>/SKILL.md` flags a miss.

- - **Phase naming.** Plans use `P1, P2, …` ("phases") only — never `S1`/`S2`/"Step N".

- `grep -nE '\bS[0-9]\b|\bStep [0-9]' skills/<name>/SKILL.md` should return nothing in

- a planning/execution context; flag any hit for the user to fix before committing.

- - **Portability section.** Every user-facing skill (`user-invocable: true`) carries a

- `## Portability` section with the standard non-Claude-Code fallbacks.

- `grep -L '^## Portability' skills/<name>/SKILL.md` flags a miss (skip this check

- for internal skills).

- - **Turn contract.** Every user-facing skill opens with a `## Turn contract`

- section (deliverable in fixed format; `→ Next:` printed last; executors run

- commands, never describe them). `grep -L '^## Turn contract' skills/<name>/SKILL.md`

- flags a miss (skip for internal skills).

- - **`plugin.json` parity.** Every `skills/<name>/` with `user-invocable: true`

- has a matching `./skills/<name>` entry in `.claude-plugin/plugin.json`.

- Compare the two sets (directories vs. array entries) and flag any

- `user-invocable: true` skill missing from the array — this is what left

- `fold-findings` installing outside its category (see #71).

- - **Machine-surface alphabetical order.** `.claude-plugin/plugin.json`'s

- `skills` array and `docs/workflow/model-routing.yml`'s top-level keys must

- each be alphabetical (per `CLAUDE.md`'s Conventions table). Extract each

- surface's ordered list and diff it against its sorted form

- (`sort -c`-equivalent); flag any surface that fails.

- - **Internal-skill discovery exclusion.** Any `skills/<name>/` that is both

- `user-invocable: false` **and** absent from `plugin.json`'s `skills` array

- is repo-internal (meaningless outside this repo) and must carry

- `metadata.internal: true` in its frontmatter — the only mechanism the

- `skills` CLI honors to keep `npx skills add . --list` from discovering and

- offering it (`user-invocable`/`plugin.json` alone do not gate discovery;

- see `docs/fix/74-bump-skill-discovery-exclusion/decisions.md`). Skills

- present in `plugin.json` are **exempt** even if `user-invocable: false`

- (they are shipped sub-skills composed by orchestrators, not repo-internal —

- e.g. the `review-*` pack, `orchestration-envelope`,

- `plan-feature-scaffold`, `plan-feature-from-issue`). For each changed

- skill: if `user-invocable: false` and its `./skills/<name>` entry is absent

- from `plugin.json`, check the **frontmatter block only** (the region

- between the first two `---` lines) for an anchored `internal: true` key —

- e.g. `awk '/^---$/{c++} c==1' skills/<name>/SKILL.md | grep -qE '^\s*internal:\s*true\s*$'`

- — should succeed; flag a miss. Matching anywhere in the body (not just the

- frontmatter) would let this rule's own prose about `metadata.internal: true`

- satisfy the check for a skill that never actually sets the key.

-

- Report violations in the summary; do not block the bump on them.

-

- ### 3. Compute the new version

-

- Parse `version:` from the SKILL.md frontmatter (line matching `^version:`).

- Apply the semver bump: increment the appropriate component, reset lower

- components to zero.

-

- Examples: `1.2.3` + patch → `1.2.4`; `1.2.3` + minor → `1.3.0`;

- `1.2.3` + major → `2.0.0`.

-

- ### 4. Update `version:` in the SKILL.md frontmatter

-

- Replace only the `version:` line in the YAML frontmatter. Touch nothing else

- in the file.

-

- ### 5. Add a row to CHANGELOG.md

-

- Locate the per-skill table for `<name>` under `## Per-skill version history`.

- Insert a new row **at the top** of that skill's table (newest first):

-

- ```

- | <new-version> | <YYYY-MM-DD> | <bump-type> | <one-sentence summary> |

- ```

-

- - Use today's date.

- - Bump type: `major`, `minor`, or `patch`.

- - Summary: one tight sentence describing the actual behavioral change — not

- the name of the bump type. Write it so a reader instantly knows what changed.

-

- If the skill has no table yet (new skill), create one with the standard header:

-

- ```markdown

- #### `<name>`

- | Version | Date | Type | What changed |

- |---|---|---|---|

- | <new-version> | <YYYY-MM-DD> | — | First versioned release |

- ```

-

- Place it in the correct subsection: **User-facing** if `user-invocable: true`,

- **Internal (`user-invocable: false`)** otherwise.

-

- Also append a brief entry to the **Release log** section at the bottom of

- `CHANGELOG.md` if this is the first bump in a new date (i.e. no entry for

- today yet). Merge all same-day bumps into one log line.

-

- ### 6. Add the matching row to CHANGELOG.es.md

-

- Find the same skill's table in `CHANGELOG.es.md` and add the equivalent row

- in Spanish. The content must match exactly — this is a translation, not a

- separate record. Follow the same "newest first" order.

-

- If the skill has no table yet in `CHANGELOG.es.md`, create one following the

- same structure as the English version, adapted to Spanish (see existing entries

- for phrasing conventions).

-

- ### 7. Check and update README.md

-

- Open `README.md` and check two sections:

-

- **a) Skills table** (under `## The skills`): find the row for this skill.

- If the skill's description or primary behavior changed (minor or major bump),

- rewrite the "What it does" cell to reflect the current state. For patch bumps,

- no change is needed unless the cell is already inaccurate.

-

- **b) Model & effort table** (under `## Recommended model & effort`): `main`

- carries no `model:`/`effort:` frontmatter — this table documents the

- `#claude` branch's tiers, sourced from `docs/workflow/model-routing.yml`. If

- the user asks to change this skill's tier, update `model-routing.yml` (never

- the `claude` branch directly — it's force-pushed by CI on every push to

- `main` and a direct edit is lost) and mirror the new value into this table

- row.

-

- Make no other changes to README.md.

-

- ### 8. Check and update README.es.md

-

- Apply the same checks as step 7 to `README.es.md`, translating any updated

- text to Spanish.

-

- ### 8b. `docs/workflow/model-routing.yml` (only when a tier changed)

-

- If step 7b changed a model/effort tier, this file must already reflect it

- (step 7b is where the edit happens — this is a reminder to not skip it, not a

- separate edit). Verify the skill's block matches what you just wrote to the

- README table. `sync-derived-branches.yml` reads this file on every push to

- `main` to regenerate the `claude` branch — a mismatch here means the next

- CI run rewrites `claude` with a value the README doesn't document.

- ### 9. Handle major bumps — migration note

- If any skill received a **major** bump due to a rename or removed/renamed

- flag:

- - Check `docs/workflow/MIGRATION.md`. If it exists, append a migration note.

- If it does not exist yet, create it with the standard header and the note.

- - Update `CLAUDE.md` under "Skills available in this repo" if the skill's

- name or contract description changed there.

- - Search the repo for cross-references to the old name:

- `grep -r "<old-name>" docs/ skills/ --include="*.md" -l`

- and update any that now point to the wrong contract.