Rename /punch-it-chewy to /ship-it, add ship-it Copilot skill

.claude/commands/punch-it-chewy.md → .claude/commands/ship-it.md

@@ -2,7 +2,7 @@
 description: Run tests, audit docs for drift (/docs), push the current feature branch, then draft PR notes and open a Pull Request via gh.
 subtask: false
 agent: general
-slash_command: /punch-it-chewy
+slash_command: /ship-it
 allowed-tools: Bash(uv run --no-sync *)
 ---
 

.claude/settings.json

@@ -21,8 +21,6 @@
       "Skill(pr-notes:*)",
       "Skill(pull)",
       "Skill(pull:*)",
-      "Skill(punch-it-chewy)",
-      "Skill(punch-it-chewy:*)",
       "Skill(push)",
       "Skill(push:*)",
       "Skill(rebase)",
@@ -31,8 +29,8 @@
       "Skill(repo:*)",
       "Skill(setup)",
       "Skill(setup:*)",
-      "Skill(ss)",
-      "Skill(ss:*)",
+      "Skill(ship-it)",
+      "Skill(ship-it:*)",
       "Skill(squash)",
       "Skill(squash:*)",
       "Skill(template)",

.claude/skills/pr-notes/SKILL.md

@@ -20,5 +20,5 @@ Write the description using the canonical `## Summary` / `## Changes` format fro
 uv run --no-sync invoke repo.pr_notes_save --content="<the notes>"
 ```
 
-If you're running as a step inside another command (e.g. `pr` or `punch-it-chewy`), don't save —
+If you're running as a step inside another command (e.g. `pr` or `ship-it`), don't save —
 just hold the composed notes for that command to use directly.

.claude/skills/punch-it-chewy/SKILL.md → .claude/skills/ship-it/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: punch-it-chewy
-description: Use for the full ship workflow — test, audit docs for drift, push the current branch, then draft PR notes and open a Pull Request. Equivalent to /punch-it-chewy.
+name: ship-it
+description: Use for the full ship workflow — test, audit docs for drift, push the current branch, then draft PR notes and open a Pull Request. Equivalent to /ship-it.
 ---
 
-# Punch It Chewy Workflow
+# Ship It Workflow
 
-Use this file as source of truth: `.github/prompts/punch-it-chewy.prompt.md`
+Use this file as source of truth: `.github/prompts/ship-it.prompt.md`
 
 When the user asks to ship/finish a branch end-to-end, read that prompt file and follow it.
 

.github/instructions/index.instructions.md

@@ -6,6 +6,23 @@ description: "Use when working on overall project structure, conventions, depend
 ## Overview
 Python-based project using [Invoke](https://www.pyinvoke.org/) for task automation and [uv](https://docs.astral.sh/uv/) for dependency/environment management. Targets Python `>=3.14`.
 
+## Instruction Files
+Operational guidance for this repo is split into focused files under `.github/instructions/`, each
+scoped to one concern — load only the ones relevant to the task at hand:
+- `index.instructions.md` — this file: project structure, conventions, dependencies, setup (start here)
+- `logic.instructions.md` — AI decision architecture, modules/tasks/AI stack, provider hierarchy
+- `python.instructions.md` — Python version, style, module/logging/subprocess conventions
+- `modules.instructions.md` — Python module architecture and layout conventions
+- `tasks.instructions.md` — invoke task runner and Collection wiring (plain CLI automation, no AI)
+- `versioning.instructions.md` — `modules/versioning/` package: VERSION bumps and dependency/action version checks
+- `prompts.instructions.md` — AI custom prompts / slash command standards and templates
+- `skills.instructions.md` — Agent Skill (SKILL.md) conventions for `.claude/skills/` and `.github/skills/`
+- `git.instructions.md` — branch naming and Pull Request description conventions
+- `review.instructions.md` — PR/code-review priorities
+- `tests.instructions.md` — testing requirements and workflow
+- `style.instructions.md` — Markdown style and alphabetical-ordering rules
+- `docs.instructions.md` — README and inline-comment conventions
+
 ## Project Structure
 ```
 pyproject.toml    # Dependencies, ruff/pylint config
@@ -34,7 +51,8 @@ tasks/
   versioning.py   # ver.libs, ver.python, ver.workflows, ver.all, ver.update, ver.upgrade, ver.project_bump_build, ver.project_bump_release
 .github/
   instructions/   # Copilot instruction files
-  prompts/        # Copilot prompt files (/push, /pull, /squash, /rebase, /fix, /test, /docs, /pr-notes, /pr, /pr-cleanup, /punch-it-chewy, /template, /update, /upgrade, /repo, /setup) — source of truth for slash commands
+  prompts/        # Copilot prompt files (/push, /pull, /squash, /rebase, /fix, /test, /docs, /pr-notes, /pr, /pr-cleanup, /ship-it, /template, /update, /upgrade, /repo, /setup) — source of truth for slash commands
+  skills/         # Optional GitHub Copilot skills (SKILL.md), not a required mirror of every prompt — see skills.instructions.md
   workflows/      # tests.yml — ruff + pylint + yamllint + actionlint + check_agents, on PRs to development/main
 .claude/
   commands/       # Claude Code slash commands, hand-maintained mirror of .github/prompts/ (see prompts.instructions.md)
@@ -70,7 +88,7 @@ addons/
 - `pyyaml` — reads `properties.yml`
 
 ## External Tools
-- `gh` (GitHub CLI) — required for `repo.pr_create` / `/pr` / `/punch-it-chewy` (not a pip package; install via Homebrew)
+- `gh` (GitHub CLI) — required for `repo.pr_create` / `/pr` / `/ship-it` (not a pip package; install via Homebrew)
 
 ## Running Tasks
 ```sh

.github/instructions/logic.instructions.md

@@ -110,6 +110,7 @@ Delete its entrypoint file(s) only. `.github/instructions/` and `AGENTS.md` stay
 - `.github/instructions/tasks.instructions.md` — invoke task runner and Collection wiring (plain CLI automation, no AI)
 - `.github/instructions/versioning.instructions.md` — `modules/versioning/` package: VERSION bumps and dependency/action version checks
 - `.github/instructions/prompts.instructions.md` — AI custom prompts / slash command standards and templates
+- `.github/instructions/skills.instructions.md` — Agent Skill (SKILL.md) conventions for `.claude/skills/` and `.github/skills/`
 - `.github/instructions/git.instructions.md` — branch naming and Pull Request description conventions
 - `.github/instructions/review.instructions.md` — PR/code-review priorities
 - `.github/instructions/tests.instructions.md` — testing requirements and workflow

.github/instructions/prompts.instructions.md

@@ -1,14 +1,15 @@
 ---
 description: "Use when creating or editing slash-command prompt files for this project. Covers prompt structure, frontmatter, naming, the four-way sync across .github/prompts/, .claude/commands/, .claude/skills/, and .clinerules/workflows/, and how prompts interact with invoke tasks and modules."
-applyTo: ".github/prompts/**,.claude/commands/**,.claude/skills/**,.clinerules/workflows/**"
+applyTo: ".github/prompts/**,.claude/commands/**,.clinerules/workflows/**"
 ---
 # Prompts Instructions
 
 ## Location & Source of Truth
 `.github/prompts/*.prompt.md` is the **source of truth** for every slash command. It's mirrored
 into `.claude/commands/*.md` (Claude Code slash commands), `.claude/skills/*/SKILL.md` (Claude
-Code Skills — auto-discovered, not explicitly invoked), and `.clinerules/workflows/*.md` (Cline)
-— see Required Frontmatter and Command Body below for each tool's format.
+Code Skills — auto-discovered, not explicitly invoked, format documented in
+`skills.instructions.md`), and `.clinerules/workflows/*.md` (Cline) — see Required Frontmatter and
+Command Body below for the commands/clinerules format.
 
 ## Architecture
 Commands are the AI-facing entrypoint layer described in `.github/instructions/logic.instructions.md`
@@ -46,21 +47,8 @@ Claude Code uses the filename as the command name. Extra frontmatter fields are
 No frontmatter — Cline workflows are plain markdown body only. The filename (minus extension) is
 the command name.
 
-### Claude Code Skills (.claude/skills/*/SKILL.md)
-```yaml
----
-name: command_name
-description: Use for ... . Equivalent to /command_name.
----
-```
-One directory per command, named to match (`.claude/skills/push/SKILL.md` for `/push`). Unlike the
-other three tools, the body is a **pointer, not a mirror** — point at the `.github/prompts/*.prompt.md`
-file as source of truth and summarize the underlying command, rather than duplicating the full
-prompt body. See any existing `.claude/skills/*/SKILL.md` for the pattern.
-
-This uses the Agent Skills format (published as an open spec, in principle implementable by any
-tool), but treat it here as **Claude Code-specific** until other tools this repo targets
-demonstrably adopt it — hence living under `.claude/` rather than a vendor-neutral `.agents/`.
+Claude Code Skills (`.claude/skills/*/SKILL.md`) also mirror every command, and GitHub Copilot
+Skills (`.github/skills/*/SKILL.md`) optionally do — see `skills.instructions.md` for both formats.
 
 ## Command Body
 Claude Code and Copilot use the same inline-execution syntax:
@@ -118,7 +106,7 @@ uv run --no-sync python -m modules.your_module.route "$ARGUMENTS"
    ```
 3. Create command files in **all four tool dirs** (`.github/prompts/`, `.claude/commands/`,
    `.clinerules/workflows/` with the thin wrapper body, and `.claude/skills/<name>/SKILL.md` with a
-   pointer body) — see Command Body and Required Frontmatter above.
+   pointer body) — see Command Body above and `skills.instructions.md` for the SKILL.md format.
 4. Run `uv run --no-sync invoke fix && uv run --no-sync invoke test` (must be 10/10 for `.py` changes)
 
 **DO NOT:**
@@ -181,3 +169,4 @@ Python function receives: pattern="wire_tunnels"
 - Doc/AI-config drift after a prompt change: run `/docs` (see `docs.prompt.md`)
 - Branch naming and PR description format used by `pr.prompt.md`/`pr-notes.prompt.md` are defined
   once, canonically, in `git.instructions.md` — don't restate that structure in a new command
+- SKILL.md format for both `.claude/skills/` and `.github/skills/`: `skills.instructions.md`

.github/instructions/review.instructions.md

@@ -13,7 +13,7 @@ description: "Use when reviewing a pull request or code change in this repo —
    constants/strings that should be defined once.
 3. **Docs kept in sync** — see `.github/instructions/docs.instructions.md`. If the diff touches a
    module, command, task, or config key, the matching `README.md` and `.github/instructions/*.md`
-   file must reflect it. This repo runs a `/docs` drift sweep before every `/punch-it-chewy` (see
+   file must reflect it. This repo runs a `/docs` drift sweep before every `/ship-it` (see
    `.github/prompts/docs.prompt.md`) — a PR that skipped it should still read as internally
    consistent.
 4. **Style compliance** — see `.github/instructions/style.instructions.md` (Markdown) and

.github/instructions/skills.instructions.md

@@ -0,0 +1,59 @@
+---
+description: "Use when creating, editing, or reviewing Agent Skill files (SKILL.md) for this project. Covers .claude/skills/ (Claude Code, required mirror of every prompt) and .github/skills/ (GitHub Copilot, optional on-demand skills)."
+applyTo: ".claude/skills/**,.github/skills/**"
+---
+# Skills Instructions
+
+## Two Skill Locations
+This repo has two separate `SKILL.md`-based directories, serving different purposes:
+
+| Location | Tool | Purpose | Sync requirement |
+|----------|------|---------|-------------------|
+| `.claude/skills/<name>/SKILL.md` | Claude Code | Auto-discovered mirror of every `.github/prompts/*.prompt.md` command | Required 1:1 — enforced by `tests.check_agents` |
+| `.github/skills/<name>/SKILL.md` | GitHub Copilot (VS Code) | Optional, on-demand skill for a specific workflow | None — add only where useful, no mirror required |
+
+## Claude Code Skills (.claude/skills/*/SKILL.md)
+```yaml
+---
+name: command_name
+description: Use for ... . Equivalent to /command_name.
+---
+```
+One directory per command, named to match (`.claude/skills/push/SKILL.md` for `/push`). The body
+is a **pointer, not a mirror** — point at the `.github/prompts/*.prompt.md` file as source of truth
+and summarize the underlying command, rather than duplicating the full prompt body. See any
+existing `.claude/skills/*/SKILL.md` for the pattern.
+
+This uses the Agent Skills format (published as an open spec, in principle implementable by any
+tool), but treat it here as **Claude Code-specific** until other tools this repo targets
+demonstrably adopt it — hence living under `.claude/` rather than a vendor-neutral `.agents/`.
+
+Required for every command — see `prompts.instructions.md`'s "Creating a New Command" and the
+four-way sync it describes (`.github/prompts/`, `.claude/commands/`, `.claude/skills/`,
+`.clinerules/workflows/`).
+
+## GitHub Copilot Skills (.github/skills/*/SKILL.md)
+```yaml
+---
+name: command_name
+description: Use for ... . Equivalent to /command_name. Also triggered by "<phrase>", ...
+---
+```
+Same frontmatter shape as the Claude version above, and the body is likewise a pointer at the
+`.github/prompts/*.prompt.md` file, not a mirror of it.
+
+Unlike `.claude/skills/`, this directory is **not required for every command** — add one only when
+a command benefits from natural-language trigger phrases beyond its slash-command name. For
+example, `ship-it` responds to "punch it", "punch it chewy", or "ship it" in addition to
+`/ship-it` (see `.github/skills/ship-it/SKILL.md`).
+
+`description` is the discovery surface GitHub Copilot uses to decide whether to invoke a skill —
+any trigger phrase the skill should respond to must be spelled out in `description`, not just
+implied by the skill's name.
+
+Not tracked by `tests.check_agents` — this directory has no 1:1 mirror requirement against
+`.github/prompts/`.
+
+## Related Instructions
+- `prompts.instructions.md` — slash command / prompt file conventions and the four-way sync
+- `logic.instructions.md` — overall AI/logic architecture

.github/prompts/punch-it-chewy.prompt.md → .github/prompts/ship-it.prompt.md

@@ -1,5 +1,5 @@
 ---
-name: punch-it-chewy
+name: ship-it
 description: Run tests, audit docs for drift (/docs), push the current feature branch, then draft PR notes and open a Pull Request via gh.
 argument-hint: no arguments required
 agent: agent

.github/skills/ship-it/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: ship-it
+description: Use for the full ship workflow — test, audit docs for drift, push the current branch, then draft PR notes and open a Pull Request. Equivalent to /ship-it. Also triggered by the phrases "punch it", "punch it chewy", or "ship it".
+---
+
+# Ship It Workflow
+
+Use this file as source of truth: `.github/prompts/ship-it.prompt.md`
+
+When the user says "punch it", "punch it chewy", "ship it", or otherwise asks to ship/finish a
+branch end-to-end, read that prompt file and follow it.
+
+It composes, in order: `test` → `docs` → `push` → `pr` (see those skills for each step's
+underlying command). Stop and ask the user how to proceed if any stage fails — do not continue to
+the next stage.

AGENTS.md

@@ -10,6 +10,7 @@ changes:
 - **Invoke tasks**: `.github/instructions/tasks.instructions.md`
 - **Versioning module**: `.github/instructions/versioning.instructions.md`
 - **Prompt/slash-command files**: `.github/instructions/prompts.instructions.md`
+- **Agent Skills (SKILL.md)**: `.github/instructions/skills.instructions.md`
 - **Branch naming & PR format**: `.github/instructions/git.instructions.md`
 - **Code review priorities**: `.github/instructions/review.instructions.md`
 - **Tests & linters**: `.github/instructions/tests.instructions.md`

README.md

@@ -42,7 +42,8 @@ tasks/
   versioning.py   # ver.libs, ver.python, ver.workflows, ver.all, ver.update, ver.upgrade, ver.project_bump_build, ver.project_bump_release
 .github/
   instructions/   # Copilot instruction files
-  prompts/        # /push, /pull, /squash, /rebase, /fix, /test, /docs, /pr-notes, /pr, /pr-cleanup, /punch-it-chewy, /template, /update, /upgrade, /repo, /setup — source of truth
+  prompts/        # /push, /pull, /squash, /rebase, /fix, /test, /docs, /pr-notes, /pr, /pr-cleanup, /ship-it, /template, /update, /upgrade, /repo, /setup — source of truth
+  skills/         # Optional GitHub Copilot skills (SKILL.md), not a required mirror of every prompt
   workflows/
     tests.yml       # CI: ruff + pylint + yamllint + actionlint + check_agents, on PRs to development/main
 .claude/
@@ -107,7 +108,7 @@ uv run --no-sync invoke setup.properties # Create/stamp properties.yml
 | `/pr-notes` | `uv run --no-sync invoke repo.pr_diff` | Draft PR notes vs. base branch; saves to `tmp/pull_requests/` when run standalone |
 | `/pr` | `uv run --no-sync invoke repo.pr_create` | Draft PR notes and open a Pull Request via `gh` (does not push) |
 | `/pr-cleanup` | `uv run --no-sync invoke repo.pr_cleanup` | Switch to the default branch, pull, and delete the merged local feature branch |
-| `/punch-it-chewy` | — | Test, audit docs, push, then draft notes and open a Pull Request |
+| `/ship-it` | — | Test, audit docs, push, then draft notes and open a Pull Request |
 | `/template` | `uv run --no-sync python -m modules.template.route` | Pull shared tooling updates from the parent template repo into this project (or push new generic tooling upstream as a PR) |
 | `/update` | `uv run --no-sync invoke ver.update --dry-run` | Check pyproject.toml deps, pinned Python version, and workflow action refs vs. latest releases; update version locks |
 | `/upgrade` | `uv run --no-sync invoke upgrade` | Upgrade Python and/or dependencies |

modules/repo/README.md

@@ -12,7 +12,7 @@ counterparts. Every file exposes a `main()` entry point, runnable standalone via
 - `push.py` — pull, stage, commit with a timestamped message, and push the primary tracked branch
   (`repo.push` / `/push`)
 - `pr_push.py` — push the current **feature** branch (fix → test → commit → push), for branches
-  that may not have upstream tracking yet; used by `/punch-it-chewy` ahead of opening a PR
+  that may not have upstream tracking yet; used by `/ship-it` ahead of opening a PR
 - `log.py` — save a session log markdown file to `logs/` (`repo.log`)
 - `squash.py` — anchored squash of every commit down to the root commit, with an auto-generated
   message and optional force-push (`repo.squash` / `/squash`)

modules/repo/pr_push.py

@@ -2,7 +2,7 @@
 
 This is intentionally separate from `modules.repo.push` (used by `/repo push` and `/push`), which
 assumes pushing the primary tracked branch. This module instead targets a feature branch that may
-not have upstream tracking yet, as used by `/punch-it-chewy`.
+not have upstream tracking yet, as used by `/ship-it`.
 """
 
 import subprocess