pr-logbook
Composes PR titles and bodies, logbook entries and a PR's squash-merge message, and marks a spec implemented in its PR. Use when opening or updating a PR, logging to an issue, writing a PR squash-merge message, or flipping a spec to implemented. Not for local commit messages.
- License 许可
- Apache-2.0
- 所属仓库
- crewrig/crewrig
- 最近更新
- 2026-11-15
- Stars
- ★ 24
- Forks
- 6
01 前言 Front Matter
- name
- pr-logbook
- license
- Apache-2.0
- metadata
- { "provenance": { "version": "1.6.0", "feedback": "https://github.com/crewrig/crewrig", "canonical": "https://github.com/crewrig/crewrig" } }
- description
- Composes PR titles and bodies, logbook entries and a PR's squash-merge message, and marks a spec implemented in its PR. Use when opening or updating a PR, logging to an issue, writing a PR squash-merge message, or flipping a spec to implemented. Not for local commit messages.
- compatibility
- Requires Node.js 24 (scripts run as node scripts/<name>.ts), git, and the forge CLI (gh for GitHub, glab for GitLab, tea for Gitea).
02 资源文件 5
- 资产文件assets/pr-body.template.md788 B
- 参考文档references/script-contract.md2.5 KB
- 脚本scripts/flip-spec-status.ts5.0 KB
- 脚本scripts/lint-pr-body.ts11.3 KB
- 脚本scripts/resolve-logbook-target.ts5.6 KB
03 SKILL.md 正文
PR & Logbook Composer
Turns a finished change into a PR a reviewer can read in under five minutes, and a logbook entry the next agent can pick up cold. Mechanical checks live in bundled scripts; you supply the judgement.
Scripts
Run node <skill-dir>/scripts/<name>.ts from wherever the input files are;
paths you pass stay relative to your current directory. Each takes --json for a machine-readable
result and exits 0 (ok), 1 (finding), 2 (usage error) or 3
(precondition failed). Conventions shared by all scripts are in
references/script-contract.md.
| When | Command | Exit 1 means |
|---|---|---|
| After drafting a title and body, before opening or editing the PR | node scripts/lint-pr-body.ts --title-file <file> --body-file <file> (add --title-style gitmoji when the project uses Gitmoji; --template <file> when it has its own body template) |
A rule is broken: title over 70 characters or ending in a period, a missing, duplicated or misordered section, an empty preamble, or a CI skip directive. Fix the draft and rerun until clean. |
| Before writing the logbook entry | node scripts/resolve-logbook-target.ts --body-file <file> |
Never used. Read data.mode: feature-issue means comment on data.issue; standalone means create a logbook issue with the logbook label. |
| When the PR implements a spec, before it merges | node scripts/flip-spec-status.ts <spec-file> (use --dry-run to preview) |
The spec has a status other than approved or implemented. Stop and tell the orchestrator; do not edit the status by hand. |
Exit 2 or 3 means the call or the environment is wrong, not the draft.
Fix the invocation; do not work around it by skipping the script.
Workflow
1. Read the project's conventions
Read the project's AGENTS.md (or equivalent) for the required PR
sections, the commit-message convention, the logbook label and location,
and any branch or merge-method rules. The same crew serves repositories
with different rules, so an assumed convention is usually a wrong one. If
the project defines its own body template, pass it to the linter.
2. Compose title and body
- Title: imperative, states what changed (the body carries why). Use the project's emoji or prefix convention.
- Body: start from
assets/pr-body.template.md, or the project's own. Write the purpose in two sentences for a human, a reading order that points at the load-bearing files and non-obvious decisions, a test plan covering the golden path and one failure mode, and a walkthrough for agents that states what was added, changed and removed, and why. - On a bug-type issue that folds related bugs, give the folded-bugs entry each item with its status; otherwise write "not applicable".
- Write both to files and run
lint-pr-body.ts. Open or edit the PR only once it exits0.
3. Logbook entry
Run resolve-logbook-target.ts on the final body. A feature issue is its
own logbook, so comment on it through the forge CLI
(gh issue comment <issue> --body ...). Do not add the logbook label to a pre-existing feature issue.
Only a PR with no feature issue gets a standalone logbook issue, created
with gh issue create ... --label logbook. Forge access is CLI-only.
A logbook is the record the next agent reads to avoid your mistakes, not a status update. Use this shape and append, never rewrite; a reverted wrong turn still belongs in the log:
### YYYY-MM-DD — <one-line topic>
**Context**: <what task or PR this entry attaches to>
**What was tried**: <decision or experiment>
**Outcome**: <green / red / partial, with a link to evidence>
**Lesson**: <the durable insight, in one sentence>
When folded bugs exist, the next stage-transition comment carries one bullet per folded item (symptom, the step that exposed it, status), a bullet for the final sweep, and one per bug filed elsewhere. The closure comment lists each item's resolution.
4. Squash-merge message
When the project squash-merges, this message is what survives in git log, so make it denser than the PR description rather than a paste of it:
<convention prefix> <imperative title> (#<pr-number>)
<one paragraph: what the PR delivered, in the past tense>
<one paragraph: why, the constraint or motivation behind it>
<bullets for significant follow-ups, if any>
Write the first paragraph in the past tense: the message records a change already made. "Added retries to the sync client", not "Adds retries to the sync client" or "The sync client now retries".
The # reference is the forge-native one: GitHub and Gitea use #, GitLab
uses ! ((!<mr-number>)).
5. Spec status flip
If the PR implements a spec, run flip-spec-status.ts on the spec file
on the implementation branch before merge, then record it in a new commit
(not an amend), and push it when the PR branch is pushed, unless the user
or the task says not to. The spec then lands on the main branch already
marked implemented. The script changes the status line only; any other
edit to the spec does not belong in this change.
A spec PR is opened as a draft and marked ready after its approval flip is pushed.
6. Before pushing: executable bits
Text-only file writes silently drop the executable bit. If the diff
touches executable files, check git ls-files --stage -- <file> shows
100755, not 100644. Restore with git update-index --chmod=+x <file>
and record it in a new commit, as with the spec flip.
7. After merge
Close the logbook issue through the forge CLI with reason completed, unless the entry went on a feature issue, in which case closing that issue is enough. Verify a feature issue named by a closing keyword really closed instead of assuming the forge auto-closed it.
Version bumps
A PR whose diff changes a skill or agent source must bump
metadata.provenance.version in the same diff, because CI rejects the PR
otherwise. Use PATCH for wording fixes, MINOR for additive changes and
MAJOR for breaking contract changes.
<!-- crewrig-repo-only:start -->
CrewRig repository only: run task check-skill-versions to check locally.
<!-- crewrig-repo-only:end -->
Single writer per forge artifact
Concurrent edits to one PR body or issue silently lose updates, so each artifact has one writer.
- Your role owns what it creates. Opening a PR makes
pr-logbookthe writer of its body; say so once on a**Writer:**line in the logbook entry. - Do not rewrite another role's body or comment; route the change through its writer. A new comment is always fine, since you own it.
- A handover only counts when it comes from the current writer.
- Observe immediately before writing: record the last-modification marker
(
gh pr view <n> --json updatedAt, or theglab/teaequivalent). gh pr editreports success even on a lost update. If the artifact moved between your observation and your write, say so on the logbook.- When telling anyone what an artifact says, base it on a fresh observation and quote its marker.
Grounding
Every technical claim (file counts, line counts, assertion lists, pass deltas, exit codes, CI step names, invariants such as "idempotent") needs a verifiable source: a path with line range, a command output, or a sentence from your brief. Without one, write "see diff" or omit it; never estimate. Re-read the draft once before returning and strip any number or invariant you cannot trace, since a fabricated claim that reaches a reviewer is costly.
Output hygiene
Every tool result stays in context and is re-read on each later call.
- Query
ghwith--jsonand--jqfields, never the full payload. tailorgreplogs down to the failing lines.- Read files by line range, never a whole spec.
- Run
git diff --statbefore reading hunks.
Output
Write in the project's primary language (check AGENTS.md), as Markdown
that renders on the PR platform, with no emoji in the body unless the
project's convention uses them.
Friction reporting
When something in this workflow misleads or blocks you, use the
harness-report skill to tag it.
Idle behavior
When re-activated after going idle with no new assignment, confirm availability in one sentence. Do not re-summarize a completed task.
Example: "Task #2 (logbook + PR for #N) is already completed — available for new work."
Shutdown protocol
When the team lead sends a shutdown_request message, respond
immediately with shutdown_response (approve: true) and stop:
{"type": "shutdown_response", "request_id": "<id from request>", "approve": true}
Do not defer, summarize completed tasks, or wait for an ongoing operation. The shutdown_request is a hard stop signal — the team lead has confirmed all work is done.
After completing a task and reporting to the team lead, do not start
any further processing or re-enter a wait loop. Mark the task as
completed via TaskUpdate, send the completion message, and then stop.
The team lead will send the next assignment or the shutdown signal.
04 同仓库更多 Skills
fixture
Fixture skill. Mentions scripts/frontmatter-only.ts which must be ignored.
fixture
Fixture skill. Mentions scripts/frontmatter-only.ts which must be ignored.
fixture
Fixture skill. Mentions scripts/frontmatter-only.ts which must be ignored.
fixture
Fixture skill. Mentions scripts/frontmatter-only.ts which must be ignored.
fixture
Fixture skill. Mentions scripts/frontmatter-only.ts which must be ignored.
fixture
Fixture skill. Mentions scripts/frontmatter-only.ts which must be ignored.