[AAASM-2886] 📝 (skill): Restructure release-tag-cut to Agent Skills spec (EXAMPLES + REFERENCE + bundled script)

[Chisanan232]

Description

Restructures the release-tag-cut skill to the Anthropic Agent Skills spec
(progressive disclosure). The skill previously crammed the full executable
plan, a verbose worked example, and all post-conditions into a single 376-line
SKILL.md. This PR splits that content across the spec's three disclosure
levels and bundles the helper script inside the skill directory.

Restructure:

• Level 1 (always loaded) — rewrote the YAML frontmatter description to
  state both what the skill does and when to use it ("Use when an
  operator is ready to cut a new alpha-series agent-assembly release…"), the
  spec's discovery signal. Third-person, well under 1024 chars.
• Level 2 (loaded when triggered) — slimmed SKILL.md from 376 → 142
  lines (spec target < 500, recommended < 200). It now carries only a lean
  overview, When/When-NOT-to-use, How-to-use, a concise 6-step plan as short
  bullets, brief pre/post-conditions, the do-NOT-manually-run callout, the
  "does not do" list, and a ## Detailed references section linking one level
  deep.
• Level 3 (loaded on demand) — moved bundled files:
  • EXAMPLES.md — the full alpha-10 worked example, verbatim, with a TOC.
  • REFERENCE.md — the detailed per-step executable-plan prose (commands,
    edge-cases, no-op guard rationale, full pre/post-conditions, auto-handled
    rationale), with a ## Contents TOC at the top (it is > 100 lines).
  • scripts/release-tag-cut.sh — git mv'd from repo-root scripts/ into
    the skill dir so the script is bundled with the skill (forward-slash,
    one-level-deep reference, stays executable 755).

No content was lost — everything was relocated. All links from SKILL.md are
one-level-deep relative links ([EXAMPLES.md](EXAMPLES.md),
[REFERENCE.md](REFERENCE.md), scripts/release-tag-cut.sh).

Type of Change

• ✨ New feature
• 🐛 Bug fix
• ♻️ Refactoring
• 🍀 Performance improvement
• 📝 Documentation update
• 🔧 Configuration / CI change
• ⬆️ Dependency upgrade
• 🚀 Release

Breaking Changes

Does this PR introduce any breaking changes to public APIs or behaviour?

• No
• Yes (describe below)

The skill's runtime behaviour is unchanged — only its file layout and
discovery metadata. The repo-root scripts/release-tag-cut.sh path is gone;
the bundled copy lives at .claude/skills/release-tag-cut/scripts/release-tag-cut.sh.

Related Issues

• Related Jira ticket: AAASM-2886
• Related GitHub issues: [AAASM-2886] 📝 (skill): Restructure release-tag-cut to Agent Skills spec (EXAMPLES + REFERENCE + bundled script) #1044

Testing

Describe the testing performed for this PR:

• Unit tests added / updated
• Integration tests added / updated
• Manual testing performed
• No tests required (docs/skill-layout change; no code paths altered)

Manual verification:

• wc -l SKILL.md → 142 (< 500 spec limit, < 200 recommended).
• Frontmatter name + improved description present (head -5).
• REFERENCE.md and EXAMPLES.md exist; both carry a ## Contents TOC.
• scripts/release-tag-cut.sh exists inside the skill dir and is executable
  (755); repo-root scripts/release-tag-cut.sh removed.
• All SKILL.md links are one-level-deep relative links.

Checklist

• Code follows project style guidelines (cargo fmt, cargo clippy)
• Self-review of the diff completed
• Documentation updated if behaviour changed
• All CI checks passing
• Commits are small and follow the Gitmoji convention

[Chisanan232]

Claude Code review — AAASM-2886

CI

3/3 green: Analyze (javascript-typescript), Analyze (python), dev-verify (smoke tests + gateway health). The dev-verify check ran (didn't path-skip) because scripts/ is in its path filter — that's the most useful signal here since it covers the new helper. Mergeable.

Scope vs. AAASM-2886

AC	Status
scripts/release-tag-cut.sh created and executable	✓ confirmed -rwxr-xr-x; bash -n clean; 0-arg path exits with usage; no-op (current==target) exits with clear error
Helper enumerates via git grep, surfaces file list before mutating, regenerates Cargo.lock	✓
5 new SKILL.md sections (When to use / When NOT to use / How to use / Worked example / What's expected when done)	✓
## What's auto-handled (do NOT manually run) callout names: gh release create, cargo publish, opening tap PR, downstream SDK fanout, AAASM-2883 FFI pin auto-PRs	✓
Worked example uses concrete 0.0.1-alpha.10 against the alpha-9 baseline (43 literals / ~16 crates from AAASM-2849)	✓
Steps 2-4 of executable plan now reference scripts/release-tag-cut.sh instead of inlining the bash	✓ (bonus 7th commit ♻️ (skill): Reference release-tag-cut.sh from executable plan steps 2-4)
6 atomic commits + 1 bonus refactor = 7 total	✓ GitEmoji format throughout

Quality observations

• Bonus commit e399044a (the ♻️ refactor) is the right call: the helper script wouldn't be load-bearing if the SKILL.md still inlined the same bash. Granular-commit rule honored.
• scripts/ is in a CI path filter so dev-verify runs — meaningful end-to-end signal beyond CodeQL. Best CI coverage of any v2 PR so far.
• PR body is well-filled and links the parent Story.

Verdict

Ready for approval and merge. Strongest v2 PR (most ACs, most CI coverage, helper script extracted cleanly). Companion to AAASM-2888 (homebrew-tap-merge enhancement) which extracts the verify-tap-sha256 helper.

— Claude Code

[Chisanan232]

Claude Code review — AAASM-2886 (spec-compliance restructure)

1. CI state

3/3 green incl. dev-verify (smoke tests + gateway health) — which runs because the bundled scripts/ path is in its filter, so the moved helper gets an end-to-end smoke. Mergeable. Diff +507/−115 across 4 files.

2. Anthropic Agent Skills spec compliance

Spec requirement	Status
SKILL.md body < 500 lines	✓ 376 → 142
Examples bundled, not inline	✓ EXAMPLES.md (114) — alpha-10 worked example
Detailed reference bundled	✓ REFERENCE.md (204) — per-step plan detail
Reference >100 lines has TOC	✓ REFERENCE.md ## Contents
Scripts bundled in the skill dir	✓ git mv repo-root → .claude/skills/release-tag-cut/scripts/release-tag-cut.sh (executable, history preserved); repo-root copy removed
References one level deep	✓
description = what + when	✓ "Cut a coordinated agent-assembly release tag… Use when an operator is ready to cut a new alpha-series release on a green master…"
No content lost	✓

The git mv (not delete+add) preserves the script's history — good. The skill execution-intent is clear per spec: SKILL.md says "run scripts/release-tag-cut.sh" (execute), and the verbose per-step rationale is in REFERENCE.md (read-as-reference).

3. Scope vs AAASM-2886 (re-scoped)

Matches: EXAMPLES.md + REFERENCE.md split, bundled script, lean SKILL.md, description rewrite.

Verdict

Ready for approval and merge. Strongest CI coverage of the five (dev-verify exercises the bundled script). Clean lossless restructure.

— Claude Code