foreman-start: progress in the workspace name, mechanical steps in a script

.github/workflows/skills.yml

@@ -0,0 +1,13 @@
+name: skills
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: bin/sync-skills --check
+      - run: python3 .claude/skills/foreman-start/scripts/foreman.py --help > /dev/null

.gitignore

@@ -0,0 +1 @@
+__pycache__/

README.md

@@ -29,22 +29,29 @@ The foreman:
 - runs the deploy-level check (end-to-end tests, recordings) once at the end of the cycle.
 
 It keeps its state in a comment block at the top of the TODO file. So `/foreman-start` also
-resumes a cycle after a restart or a lost context.
+resumes a cycle after a restart or a lost context. While a cycle runs, the foreman's own
+workspace is named after the run's progress, such as `Foreman (3/7)`. The foreman keeps that
+count in its own session; it isn't stored in the TODO file or anywhere else.
+
+The mechanical steps run through one script, `scripts/foreman.py`, rather than through the
+model: picking the TODO file, writing the block and the checklist markers, renaming the workspace, moving tickets, the heartbeat scan of all workers, checking that a PR is
+really merged, and checking the machine before raising the parallel limit. Run it with `--help`
+for the commands.
 
 ### Requirements
 
 - The paseo MCP server, with workspaces, agents and heartbeats.
 - `git` with a remote, and the GitHub CLI `gh`, authenticated.
+- `python3` and the paseo CLI (`paseo`), for the script.
 - Optional: paseo agent profiles, each with notes on what it is for. Without them, the workers
   copy the foreman's own settings.
 - Optional: a `merge-to-main` skill in the workers' client. Without it, the workers merge with
   plain `gh`.
 
 ### Install
 
-The two copies hold the same procedure. The Claude Code copy uses Claude's tool names. The
-other follows the general Agent Skills layout (`.agents/skills/`), which Kimi Code and other
-clients read.
+The two copies are identical. `.claude/skills/` is for Claude Code; `.agents/skills/` follows the
+general Agent Skills layout, which Kimi Code and other clients read.
 
 ```sh
 # Claude Code, for all projects
@@ -102,6 +109,11 @@ for d in .claude .agents; do gh api repos/ankitpokhrel/jira-cli/contents/llm.md
   -H 'Accept: application/vnd.github.raw' > $d/skills/jira-cli/llm.md; done
 ```
 
+## Editing the skills
+
+Edit `.claude/skills/` only, then run `bin/sync-skills` to copy it to `.agents/skills/`.
+`bin/sync-skills --check` fails when the copies differ; CI runs it on every push.
+
 ## License
 
 MIT, see [LICENSE](LICENSE). The `llm.md` in the jira-cli skill is © 2022 Ankit Pokhrel, also MIT,

bin/sync-skills

@@ -0,0 +1,17 @@
+#!/bin/sh
+# .claude/skills is the source; .agents/skills is a plain copy for other Agent Skills clients.
+# Both clients read the same text, so the copy is byte for byte.
+#   bin/sync-skills          copy .claude/skills over .agents/skills
+#   bin/sync-skills --check  exit 1 when the copies differ (CI)
+set -eu
+cd "$(dirname "$0")/.."
+if [ "${1:-}" = "--check" ]; then
+  if diff -r -x __pycache__ .claude/skills .agents/skills; then echo "skills in sync"; exit 0; fi
+  echo "skills out of sync: edit .claude/skills, then run bin/sync-skills" >&2
+  exit 1
+fi
+rm -rf .agents/skills
+mkdir -p .agents
+cp -R .claude/skills .agents/skills
+find .agents/skills -name __pycache__ -prune -exec rm -rf {} +
+echo "copied .claude/skills → .agents/skills"