Track issues with git-bug

Issues live in git-bug, inside the Git repository, so they work offline
and travel with the code through git bug push and pull. They are not
files in the checkout, so they stay out of diffs, formatters, and the
rule that files describe only the current state.

The development shell supplies git-bug. The issues skill tells agents
how to read and write issues, and warns that the -F option drops every
line that starts with "#". Commit messages now refer to an issue with an
Issue trailer that holds its git-bug ID, because there are no issue URLs
to link.

git-bug has no links between issues, so relations are Parent and
Depends-on trailers at the end of the body, as in a commit message. git
interpret-trailers can read them, and a search for an issue ID finds the
issues that refer to it.

diff --git a/.agents/skills/commit/SKILL.md b/.agents/skills/commit/SKILL.md
index 6676a8533a1631837c6dd6261fcfc8147fc26353..7e1f65766ba55b8bc9c37816c7ee4f565d679dc8 100644 (file)
--- a/.agents/skills/commit/SKILL.md
+++ b/.agents/skills/commit/SKILL.md
@@ -44,9 +44,10 @@ description: Commit procedure and message rules. Use for every commit.
 
 ## Trailers
 
-- When the change belongs to an issue, end the message with one `Link:`
-  trailer to that issue. Add it with `git commit --trailer`. Never use a
-  closing keyword such as "Fixes" or "Closes".
+- When the change belongs to an issue, end the message with one `Issue:`
+  trailer with the git-bug ID of that issue. Add it with
+  `git commit --trailer`. Never use a closing keyword such as "Fixes" or
+  "Closes".
 - Link the bug report when a change fixes a reported bug.
 - Do not add an AI tool as co-author. Do not add attribution trailers.
 

diff --git a/.agents/skills/issues/SKILL.md b/.agents/skills/issues/SKILL.md
new file mode 100644 (file)
index 0000000..225d95c
--- /dev/null
+++ b/.agents/skills/issues/SKILL.md
@@ -0,0 +1,60 @@
+---
+name: issues
+description: Read and write issues with git-bug. Use for any issue work.
+---
+
+# Issues
+
+Issues live in git-bug, inside the Git repository, not in files. The
+`overview` issue lists the phases and the open decisions. Run the
+commands in the Nix development shell.
+
+## Read
+
+- List the open issues with `git bug bug status:open`.
+- Read an issue and all its comments with `git bug bug show ID` before
+  you start work on it.
+
+## Write
+
+- Give the title and the body with `-t` and `-m`. Do not use `-F`: it
+  drops every line that starts with `#`, so Markdown headings are lost.
+- Write the title like a commit subject: 50 characters or fewer, in the
+  imperative mood, with no final period.
+- Write the body in Markdown. State the result for the user, the scope,
+  and how to check it.
+- Add a comment with `git bug bug comment new ID -m TEXT` for progress
+  that matters: decisions made with the user, measurements, and checks
+  that could not run.
+- Close an issue with `git bug bug status close ID` only when its check
+  passes.
+- Label a phase `phase`, an open question `decision`, and the plan
+  `overview`, with `git bug bug label new ID LABEL`.
+
+## Relations
+
+git-bug has no links between issues. Write them as trailers in the last
+paragraph of the body, one per line, as in a commit message:
+
+- `Parent: ID` names the issue that this issue belongs to. A child has
+  one parent.
+- `Depends-on: ID, ID` names the issues that must be done first.
+- A parent lists the IDs of its children in its body.
+
+`git interpret-trailers --parse` reads the trailers of a body.
+
+Find the issues that relate to an issue with `git bug bug ID`. The
+search finds every issue that mentions the ID, so read the trailers of
+each match. Do not search for more than one word: git-bug finds issues
+that match any of the words, and it reads `Parent:` as a query
+qualifier. Nothing checks the trailers. Before you close a parent, make
+sure that its children are closed.
+
+Push the issues with `git bug push` when the repository has a remote.
+
+This example creates an issue:
+
+```sh
+git bug bug new --non-interactive -t 'Decide the root wake interval' \
+  -m "$(cat body.md)"
+```

diff --git a/AGENTS.md b/AGENTS.md
index 07a8f57086e394062c19a01ec2ed993d8b7d3d80..bfeccf24b3b76c79f2e82f4e4ee0073728810888 100644 (file)
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -19,6 +19,7 @@ Read the `SKILL.md` of a skill before you start the task that it covers:
 | Write or change documentation or prose comments | `.agents/skills/docs`    |
 | Format and check the repository                 | `.agents/skills/check`   |
 | Make any commit                                 | `.agents/skills/commit`  |
+| Read or write an issue                          | `.agents/skills/issues`  |
 
 ## Rules
 

diff --git a/nix/devshell.nix b/nix/devshell.nix
index 9ec0209bd9b453d53019ac1c43232cdf9dbaad86..fdf65e96921cf546d418db10aea78cba0017f46d 100644 (file)
--- a/nix/devshell.nix
+++ b/nix/devshell.nix
@@ -2,6 +2,7 @@
 pkgs.mkShell {
   packages = with pkgs; [
     git
+    git-bug
     go
     gofumpt
     golangci-lint