@jesdi/skills 0.0.31 → 0.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.31",
+  "version": "0.0.32",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {

package/skills/implement-spec/ARCHITECTURE.md

@@ -78,7 +78,7 @@ and do not know about the run, except `driver_run.py`, which the three deciding
 ### Work is never dropped
 
 - A role that commits keeps its tree after a timeout or an interrupt; its rerun continues from it.
-- A read-only role (reviewer, correctness, final-reviewer) has no work to keep. When it changes its slot, the
+- A read-only role (reviewer, correctness, final-reviewer, pr-writer) has no work to keep. When it changes its slot, the
   driver restores the slot and runs the review one more time (`Run.read_only`).
 - A slot with uncommitted work of an interrupted or parked ticket is kept for that ticket (`driver_state.kept`).
 - A blocked ticket keeps its slot when the slot is not clean.

package/skills/implement-spec/README.md

@@ -44,7 +44,7 @@ One driver runs in a repository at a time. The driver holds a kernel file lock o
 | `--only ROLE` | Test only. Run one role (`test-writer`, `implementer`, `reviewer` or `correctness`) on the first ticket, with no gate and no merge. |
 | `--help`, `-h` | Print the flags and exit. |
 
-Default timeouts in minutes: explorer 30, test-writer 30, implementer 90, reviewer 45, correctness 30, fixer 60, final-reviewer 60, conflict 30.
+Default timeouts in minutes: explorer 30, test-writer 30, implementer 90, reviewer 45, correctness 30, fixer 60, final-reviewer 60, conflict 30, pr-writer 20.
 
 `run.sh` downloads `uv`, Python 3.13 and `jsonschema` once into `~/.cache/implement-spec`. `IMPLEMENT_SPEC_CACHE_DIR` moves that cache. `IMPLEMENT_SPEC_OFFLINE=1` forbids the download. `run.sh` supports macOS and Linux only, on x86_64 or ARM64, and needs `curl`, `tar` and `sha256sum` or `shasum` for the first download.
 
@@ -81,7 +81,7 @@ Everything is under `.agent/`, which is never committed.
 | `.agent/implement/<NN>/<role>-<K>.json`, `.log`, `.prompt.md` | The report, the log and the prompt of one agent. K is the fix round. |
 | `.agent/implement/<NN>/gate-<sha7>.log` | One gate record: start, commit, status, command, output, exit, the state after the command, end. |
 | `.agent/implement/<NN>/findings-<K>.json` | The merged findings of the review after fix round K. |
-| `.agent/implement/final/` | The same files for the end of run, and `pr-body.md`. |
+| `.agent/implement/final/` | The same files for the end of run, and `pr-body.md`: the pr-writer's body, then the facts of the run. |
 | `.agent/implement/pycache/` | Compiled Python of the gate, kept out of the slots. |
 | `.agent/implement-review.html` | The page with the open questions. |
 | `.agent/implement-answers.json` | The answers: `{"v": 1, "stage": "implement", "submitted": …, "revision": …, "answers": {…}}`. |
@@ -131,7 +131,7 @@ The end of run starts only when every ticket is merged and every slot is idle. I
 3. **Gate**, then the **final-reviewer** (`prompts/final-reviewer.md`) on the whole range, with the method of the `review-diff` skill. It gets the minor findings of the tickets and the rulings of the operator.
 4. **Fix batch.** Critical and important findings go to one fixer (`prompts/final-fixer.md`). The driver names each of its commits `fix(NN): …` from the ticket in the report. Then the gate, then one scoped review of those commits.
 5. Findings that are open after the second review become questions of kind `final-finding`. There is no third review.
-6. **Push.** With `--push` or `--unattended`, the driver pushes the reviewed tip once, with no force, and opens the PR with `gh`, ready for review. Without them it prints the two tips and the command to run again with `--push`.
+6. **Push.** With `--push` or `--unattended`, the driver pushes the reviewed tip once, with no force, and opens the PR with `gh`, ready for review. The **pr-writer** (`prompts/pr-writer.md`) writes the body with the method of the `pr` skill; the driver puts the facts of the run after it: the ticket-to-commit map, the fix commits, the rulings and the review coverage (`prompts/pr-body.md`). A push stops before any agent when no `pr` skill is next to this skill, in `${CLAUDE_CONFIG_DIR:-~/.claude}/skills` or in `~/.agents/skills`. Without them it prints the two tips and the command to run again with `--push`.
 
 History rules:
 
@@ -174,6 +174,7 @@ Every report has `status` (`DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, `BLOCK
 | correctness | `prompts/correctness.md` | the same as the reviewer | `mutations` is optional. |
 | fixer | `prompts/fixer.md` | `green`, `ticket` | With DONE: one commit or more. |
 | final-reviewer | `prompts/final-reviewer.md` | `findings` | None. |
+| pr-writer | `prompts/pr-writer.md` | `body`; `commits` is empty | None. |
 | fixer of the final review | `prompts/final-fixer.md` | `green`; `commits` is a list of (`sha`, `ticket`) | Each new commit on the branch is in `commits`, with a ticket of the run. |
 | conflict | `prompts/conflict.md`, `prompts/rebase-conflict.md` | none | With DONE: one commit or more. No locked file may change. |
 

package/skills/implement-spec/driver_agents.py

@@ -18,10 +18,10 @@ from pathlib import Path
 SKILL = Path(__file__).resolve().parent
 # Minutes per role.
 TIMEOUTS = {"explorer": 30, "test-writer": 30, "implementer": 90, "reviewer": 45, "correctness": 30, "fixer": 60,
-            "final-reviewer": 60, "conflict": 30}
+            "final-reviewer": 60, "conflict": 30, "pr-writer": 20}
 PROVIDERS = {"anthropic": ("claude", ("low", "medium", "high", "xhigh", "max")),
              "openai": ("codex", ("minimal", "low", "medium", "high", "xhigh"))}
-READ_ONLY = ("reviewer", "correctness", "final-reviewer")
+READ_ONLY = ("reviewer", "correctness", "final-reviewer", "pr-writer")
 # A process group is here only while its leader is not reaped: then no other process can have its id.
 LIVE: set[int] = set()
 STOPPED = False

package/skills/implement-spec/driver_final.py

@@ -41,6 +41,14 @@ ROUNDS = 2  # the full review and the scoped one after the fix batch
 REVIEW_DIFF = driver_agents.SKILL.parent / "review-diff" / "SKILL.md"
 
 
+def pr_skill() -> Path | None:
+    """The SKILL.md of the pr skill, which the PR body follows: next to this skill, else in the skill folder of the
+    Claude home or of the shared home of Codex and OpenCode."""
+    claude = Path(os.environ.get("CLAUDE_CONFIG_DIR") or Path.home() / ".claude")
+    homes = (driver_agents.SKILL.parent, claude / "skills", Path.home() / ".agents" / "skills")
+    return next((home / "pr" / "SKILL.md" for home in homes if (home / "pr" / "SKILL.md").is_file()), None)
+
+
 def _has_origin() -> bool:
     return git(".", "remote", "get-url", "origin").returncode == 0
 
@@ -51,6 +59,9 @@ def precondition_errors(push: bool) -> list[str]:
     if not REVIEW_DIFF.exists():
         errors.append(f"{REVIEW_DIFF} is missing: the final review runs through it; install the review-diff skill "
                       "next to implement-spec")
+    if push and not pr_skill():
+        errors.append("the pr skill is missing: the PR body follows it; install it with "
+                      "`npx skills add mattpocock/skills --skill pr`, or run without --push and --unattended")
     if push and not _has_origin():
         errors.append("the repository has no origin remote: --unattended and --push push the PR branch to origin; "
                       "add the remote, or run without them to stop before the push")
@@ -401,8 +412,8 @@ def _name(run: Run) -> str:
     return next((line[2:].strip() for line in lines if line.startswith("# ")), run.pr)
 
 
-def _body(run: Run, final: dict, tickets: list[Ticket]) -> str:
-    """The PR body: the ticket-to-commit map, the fix commits, the rulings and the review coverage."""
+def _facts(run: Run, final: dict, tickets: list[Ticket]) -> str:
+    """The end of the PR body: the ticket-to-commit map, the fix commits, the rulings and the review coverage."""
     titles, tip = {ticket.number: ticket.title for ticket in tickets}, final["reviewed"]
     fixes = git(".", "log", "--reverse", "--format=- %h %s", f"{final['tidied']}..{tip}").stdout.strip()
     rulings = driver_decisions.rulings(run.state.read()["run"]["questions"])
@@ -413,10 +424,28 @@ def _body(run: Run, final: dict, tickets: list[Ticket]) -> str:
         "scoped": f"{final['tidied']}..{tip}" if fixes else "not needed"})
 
 
+def _write_body(run: Run, final: dict, tickets: list[Ticket]) -> Path:
+    """Write the PR body: what the pr-writer wrote with the method of the pr skill, then the facts of the run. A body
+    written for the reviewed tip is kept, so a PR that failed to open costs no second agent."""
+    body, tip = OUT / FINAL / "pr-body.md", final["reviewed"]
+    if final["body"] == tip and body.is_file():
+        return body
+    method, facts = pr_skill(), _facts(run, final, tickets)
+    if not method:
+        raise Blocked("the pr skill is missing: the PR body follows it; install it with "
+                      "`npx skills add mattpocock/skills --skill pr`")
+    values = {**_prompt_values(run), "start_sha": tip, "range": f"{final['onto']}..{tip}",
+              "gate": str(OUT / FINAL / f"gate-{tip[:7]}.log"), "pr_skill": str(method), "facts": facts}
+    with during("the PR body"):
+        report = run.read_only(FINAL, ".", run.pr, tip, lambda: run.agent("pr-writer", FINAL, ".", values))
+    body.write_text(f"{report['body'].strip()}\n\n{facts}")
+    run.state.update(lambda state: state["run"]["final"].update(body=tip))
+    return body
+
+
 def _open_pr(run: Run, final: dict, tickets: list[Ticket]) -> str:
     """Open the PR, ready for review, and return its URL."""
-    body = OUT / FINAL / "pr-body.md"
-    body.write_text(_body(run, final, tickets))
+    body = _write_body(run, final, tickets)
     made = subprocess.run(["gh", "pr", "create", "--base", final["base"], "--head", run.pr, "--title", _name(run),
                            "--body-file", str(body)], capture_output=True, text=True, stdin=subprocess.DEVNULL)
     if made.returncode:

package/skills/implement-spec/driver_state.py

@@ -26,7 +26,8 @@ def _ticket() -> dict:
 def _final() -> dict:
     """The end-of-run record before it starts. Every key is here, so a reader uses [] and a wrong name fails."""
     return {"skipped": "", "recovery": None, "tidied": None, "onto": None, "base": None, "commits": {},
-            "reviewed": None, "round": 0, "open": [], "batch": None, "green_gates": [], "pushed": None, "pr": None}
+            "reviewed": None, "round": 0, "open": [], "batch": None, "green_gates": [], "pushed": None, "body": None,
+            "pr": None}
 
 
 class State:
@@ -44,6 +45,8 @@ class State:
                 "revision": uuid.uuid4().hex, "pr_branch": pr_branch, "gates": 0, "stops": 0, "agents": [],
                 "questions": [], "start": git(".", "rev-parse", f"refs/heads/{pr_branch}").stdout.strip(),
                 "landed": [], "final": _final()})
+            for key, value in _final().items():  # a run of an older driver lacks the newer keys
+                state["run"]["final"].setdefault(key, value)
             tickets = state.setdefault("tickets", {})
             for number in numbers:
                 tickets.setdefault(number, _ticket())

package/skills/implement-spec/models.json

@@ -6,5 +6,6 @@
   "correctness": ["openai/gpt-astra@medium", "claude-opus-5@medium"],
   "fixer": ["claude-opus-5@medium"],
   "final-reviewer": ["openai/gpt-astra@medium", "claude-opus-5@medium"],
-  "conflict": ["claude-opus-5@medium"]
+  "conflict": ["claude-opus-5@medium"],
+  "pr-writer": ["claude-opus-5@medium"]
 }

package/skills/implement-spec/prompts/pr-writer.md

@@ -0,0 +1,31 @@
+# PR writer
+
+Spec: {spec}
+Tickets: {tickets}
+PR branch: {pr_branch}, at commit {start_sha}
+Range: {range}
+Gate record of the driver for {start_sha}: {gate}
+PR method: {pr_skill}
+Facts of the run, which the driver puts after your body:
+{facts}
+
+Write the body of the PR of the range with the method of the pr skill in the file above: its sections, in its order. Read the spec, the tickets and the range first. The gate record and the tests of the range are the execution-based evidence; you cannot take screenshots. Do not repeat the facts of the run: the driver puts them after your body.
+Do not commit. Leave the branch and the tree as you found them.
+
+Write one JSON report at {report} that matches this schema:
+
+```json
+{
+  "type": "object",
+  "required": ["status", "commits", "files", "concerns", "body"],
+  "properties": {
+    "status": {"enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"]},
+    "commits": {"type": "array", "maxItems": 0},
+    "files": {"type": "array", "items": {"type": "string"}},
+    "concerns": {"type": "array", "items": {"type": "string"}},
+    "body": {"type": "string", "minLength": 1}
+  }
+}
+```
+
+Never run `git stash`, never reset, and never check out another branch: worktrees share one stash and one ref store.

package/skills/implement-spec/tests/conftest.py

@@ -16,6 +16,18 @@ def ticket(number, blocked="None (can start immediately)", touches="`demo/x.py:
     return f"# {number}: Ticket {number}\n\n**Blocked by:** {blocked}\n\n**Seam:** {seam}\n\n**Touches:** {touches}\n\n- [ ] It works\n"
 
 
+@pytest.fixture(scope="session", autouse=True)
+def pr_skill(tmp_path_factory):
+    """The Claude home of every test, module rigs included, has the pr skill, which the PR body follows. Rigs copy
+    os.environ."""
+    home = tmp_path_factory.mktemp("claude-home")
+    (home / "skills/pr").mkdir(parents=True)
+    (home / "skills/pr/SKILL.md").write_text("---\nname: pr\n---\n")
+    with pytest.MonkeyPatch.context() as patch:
+        patch.setenv("CLAUDE_CONFIG_DIR", str(home))
+        yield home / "skills/pr/SKILL.md"
+
+
 @pytest.fixture
 def repo(tmp_path, monkeypatch):
     """A clean git worktree with .agent ignored; returns a writer for the ticket set."""

package/skills/implement-spec/tests/test_cli.py

@@ -13,7 +13,8 @@ RUN = SKILL / "run.sh"
 GIT = ["git", "-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false"]
 TOOLS = ("sh", "uname", "dirname", "readlink", "git", "env", "mktemp", "curl", "tar", "gzip", "mv", "rm", "mkdir",
          "sha256sum", "shasum", "cat", "chmod", "ln", "date", "basename")
-ROLES = ("explorer", "test-writer", "implementer", "reviewer", "correctness", "fixer", "final-reviewer", "conflict")
+ROLES = ("explorer", "test-writer", "implementer", "reviewer", "correctness", "fixer", "final-reviewer", "conflict",
+         "pr-writer")
 NONE = "None (can start immediately)"
 
 

package/skills/implement-spec/tests/test_final.py

@@ -263,10 +263,10 @@ def test_a_rerun_after_the_tidy_runs_no_agent_no_gate_and_sends_no_ticket_back(s
     assert all(stop_lines(now.out))
 
 
-def test_the_push_rerun_pushes_once_opens_the_pr_with_map_and_rulings_and_runs_nothing(story):
+def test_the_push_rerun_pushes_once_opens_the_pr_with_map_and_rulings_and_runs_only_the_pr_writer(story):
     rig, before, now = story.rig, story.again, story.pushed
     assert now.code == 0, rig.output()
-    assert (now.calls, now.gates, now.tip) == (before.calls, before.gates, before.tip)
+    assert (now.calls, now.gates, now.tip) == (before.calls + 1, before.gates, before.tip), "only the pr-writer runs"
     assert rig.pushes() == [f"refs/heads/feat/csv {now.tip}"] and ref(rig.origin, "refs/heads/feat/csv") == now.tip
     (pr,) = rig.prs()
     assert "--draft" not in pr["argv"]

package/skills/implement-spec/tests/test_tidy.py

@@ -66,7 +66,7 @@ def stray(rig, text="by hand"):
 
 # ---------------------------------------------------------------- the story: local stop, rerun, push
 
-def test_a_local_run_stops_before_the_push_and_a_push_rerun_pushes_and_opens_the_pr_once(tmp_path):
+def test_a_local_run_stops_before_the_push_and_a_push_rerun_pushes_and_opens_the_pr_once(tmp_path, pr_skill):
     rig = Inside(tmp_path, THREE, FINAL_MODELS)
     rig.run(plan())
     assert rig.code == 0, rig.out + "\n".join(rig.ledger())
@@ -95,7 +95,11 @@ def test_a_local_run_stops_before_the_push_and_a_push_rerun_pushes_and_opens_the
     (pr,) = rig.prs()
     assert pr["argv"][:10] == ["pr", "create", "--base", "main", "--head", "feat/csv", "--title", "csv spec",
                                "--body-file", ".agent/implement/final/pr-body.md"]
-    assert [f"- {nn}: {row['sha'][:7]} {TITLES[nn]}" for nn, row in zip(order, rows)] == pr["body"].splitlines()[4:7]
+    assert pr["body"].startswith("## Summary\n\nCSV export.\n\n## Tickets\n"), "the pr-writer's body, then the facts"
+    assert [f"- {nn}: {row['sha'][:7]} {TITLES[nn]}" for nn, row in zip(order, rows)] == pr["body"].splitlines()[8:11]
+    (writer,) = rig.final_calls("pr-writer")
+    assert f"PR method: {pr_skill}\n" in writer["prompt"]
+    assert "Facts of the run, which the driver puts after your body:\n## Tickets" in writer["prompt"]
     assert "## Rulings\n\nNone.\n" in pr["body"] and "Scoped review after the fix batch: not needed" in pr["body"]
     assert f"Pushed feat/csv at {tip} to origin." in rig.out and "PR: https://github.example/pull/1" in rig.out
     assert f"feat/csv is pushed at {tip[:7]}; its PR is https://github.example/pull/1." in rig.out
@@ -103,7 +107,7 @@ def test_a_local_run_stops_before_the_push_and_a_push_rerun_pushes_and_opens_the
 
     rig.run(plan(), "--push")
     assert rig.code == 0 and len(rig.pushes()) == 1 and len(rig.prs()) == 1, "a second push rerun sends nothing"
-    assert (len(rig.calls()), len(rig.gates())) == (calls, gates)
+    assert (len(rig.calls()), len(rig.gates())) == (calls + 1, gates), "the one agent of the pushes is the pr-writer"
 
 
 def test_the_final_review_does_not_start_while_a_ticket_is_not_merged_and_the_ledger_says_so_once(tmp_path):
@@ -493,6 +497,24 @@ def test_without_the_review_diff_skill_every_repository_stops_before_any_agent(t
                        "review-diff skill next to implement-spec\n")
 
 
+def test_a_push_without_the_pr_skill_stops_before_any_agent_and_a_local_run_does_not_need_it(tmp_path, monkeypatch):
+    monkeypatch.setenv("HOME", str(tmp_path / "home"))
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path / "empty-claude-home"))
+    rig = Inside(tmp_path, ONE).run(plan(), "--push")
+    assert rig.code == 3 and not rig.calls(), rig.out
+    assert rig.out.startswith("the pr skill is missing: the PR body follows it; install it with ")
+
+    rig.run(plan())
+    assert rig.code == 0 and not rig.final_calls("pr-writer"), rig.out
+
+    (tmp_path / "home/.agents/skills/pr").mkdir(parents=True)
+    (tmp_path / "home/.agents/skills/pr/SKILL.md").write_text("---\nname: pr\n---\n")
+    rig.run(plan(), "--push")
+    assert rig.code == 0 and len(rig.prs()) == 1, rig.out
+    (writer,) = rig.final_calls("pr-writer")
+    assert f"PR method: {tmp_path}/home/.agents/skills/pr/SKILL.md\n" in writer["prompt"]
+
+
 def test_without_an_origin_the_run_ends_reviewed_and_a_push_is_refused_at_the_start_and_after_the_tidy(tmp_path):
     rig = Inside(tmp_path, ONE, remote=False).run(plan())
     assert rig.code == 0, rig.out

package/skills/implement-spec/tests/test_walk.py

@@ -66,6 +66,8 @@ if role in ("reviewer", "correctness", "final-reviewer") and "report" not in ste
     proofs = [dict(test=r.split()[1], file="demo/export.py", line=1, red=r) for r in reds]
     step = dict(step, stdout="".join(r + "\\n" for r in reds), report=dict(
         status="DONE", commits=[], files=[], concerns=[], findings=[], mutations=proofs))
+if role == "pr-writer" and "report" not in step:  # an unscripted pr-writer writes one section
+    step = dict(step, report=dict(status="DONE", commits=[], files=[], concerns=[], body="## Summary\\n\\nCSV export."))
 for name in step.get("touch", []):
     (rig / "sig" / name).touch()
 for name in step.get("wait", []):

package/skills-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-14T03:34:13.674Z",
+  "generatedAt": "2026-10-15T12:05:36.876Z",
   "skills": [
     {
       "name": "backlog",
@@ -46,8 +46,8 @@
     },
     {
       "name": "implement-spec",
-      "version": "0.1.8",
-      "hash": "sha256-cafda530227caa971251cbe0d677f758630f96d6178f75a5e32b93417efe033e",
+      "version": "0.1.9",
+      "hash": "sha256-a2864cb6013ba8ee10af5b597b4376b89507efce8c6acecfbeca5db7389623ea",
       "description": "Implement a specification in code."
     },
     {