1# Preferred tooling
 2
 3## git-bug
 4
 5I like using a bug tracker that embeds bugs and identities and conversations directly in the repo we're working in. These can be private bugs just for me, or public bugs I push to the remote repo to collaborate on with other contributors. It's called `git-bug` and you interact with it like so.
 6
 7- Create new bugs: `git-bug bug new [flags]`
 8  - -t bug subject
 9  - -m bug body
10  - -F accept the subject _and_ from the given files, use `-` to read from stdin. The first line is the subject, then include a blank line, then the body, then a blank line, then any trailers.
11- Commenting on a bug: `git-bug bug comment new [BUG_HASH] [flags]`
12  - -m comment body
13  - -F accept the message from the given files, use `-` to read from stdin
14- Viewing a bug's timeline: `git-bug bug show [BUG_HASH]`
15- Pushing and pulling: always pull before pushing
16  - `git bugs-pull`
17  - `git bugs-push`
18
19# Interacting with git
20
21I have git configured to use a pager you don't understand, so make sure to _always_ prepend git invocations with `GIT_PAGER=cat`.
22
23## Committing
24
25During the course of our conversation, we may implement not only the thing we set out to implement, we might also introduce some bugs and fix them before making the commit. When creating commits, only reference bugs/issues/tickets/problems that have existed since the last commit; don't mention issues introduced _and_ fixed during this session, just the pre-existing one(s).
26
27Strictly follow Conventional Commits. For AUR packages, the prefix will usually be `chore:` with no scope. For most source code repositories, we'll usually require both an appropriate prefix _and_ scope. Necessity of scope increases with repository size; the smaller the repo, the less necessary the scope.
28
29Create/amend commits exclusively using `formatted-commit`. Try to use it normally, but if it's not in my PATH, ask me to `go install git.secluded.site/formatted-commit@latest`. It has no sub-commands and the following options:
30<formatted-commit_flags>
31-t --type Commit type (required)
32-s --scope Commit scope (optional)
33-B --breaking Mark as breaking change (optional)
34-m --message Commit message (required)
35-b --body Commit body (optional)
36-T --trailer Trailer in 'Sentence-case-key: value' format (optional, repeatable)
37-a --amend Amend the previous commit (optional)
38-h --help
39</formatted-commit_flags>
40<formatted-commit_example>
41formatted-commit -t feat -s "web/git-bug" -m "do a fancy new thing" -T "Crush <crush@charm.land>" -b "$(cat <<'EOF'
42Multi-line
43
44- Body
45- Here
46
47EOF
48)"
49</formatted-commit_example>
50
51When directed to sign commits, sign as `Crush <crush@charm.land>` as shown in the examples.
52
53# Ticket tracking
54
55- When I provide the URL to or number of a ticket, todo, or issue, use the appropriate tool.
56  - github.com or "issue": `gh issue view https://github.com/USER/REPO/issues/XXX` where XXX is the issue number. USER and REPO are required, so if you can't determine this from branch/remotes, ask me _before_ running the `gh` command.
57  - todo.sr.ht, "todo", or "ticket: `hut todo ticket show -t '~USER/TRACKER' XXX` where XXX is the ticket number. I'll refer to these as todos or tickets. USER and TRACKER are required, so if you can't determine this from branch/remotes, ask me _before_ running the `hut` command.
58    - Run `git remote -v` and notice whether any of the remotes include 'soprani.ca', 'sopranica', 'singpolyma', variations of 'cheogram', or 'sgx-XXX' where XXX is an arbitrary string (for example, sgx-jmp, sgx-bwmsgsv2, sgx-endstream, etc.). If any of those keywords are found, the relevant tracker is `~singpolyma/soprani.ca`.
59- When I _specifically_ reference a "bug" and provide a hash instead of a number, I'm referring to a bug created with `git-bug`. Use `git-bug bug show HASH` to read the bug and discussion. You may use `git-bug bug status (close|open)` to modify the bug's status ONLY if I give explicit permission.
60
61# General development practises
62
63In my opinion, JSON should _never_ need to be written or read by humans, unless the project already requires that. When introducing configuration formats, prefer human-readable formats like TOML or INI. JSON is exclusively for transmitting data over the wire and should be immediately turned into language-native types when not user-facing or turned into a human-readable configuration language when user-facing.
64
65## How to defer work
66
67Your suggestions are valuable and our findings while working on important. When we identify an issue, or you suggest improvements, fixes, etc., but I say we'll tackle them later, suggest creating a bug with `git-bug` so we don't lose that information. Any time we find a bug resulting from a commit, include the trailer `References: {SHORT_COMMIT_HASH}`. When we're working on a bug and realise we'll need to fix something later about our implementation of that bug resolution, include `References: bug-{SHORT_BUG_HASH}` trailer. For _all_ bugs, issues, todos, tickets, and comments you create, include yourself in the `Co-authored-by:` trailer at the bottom.
68
69# Workflows
70
71- When you specifically see a suite of `planning` MCP tools including `set_goal`, `change_goal`, `add_tasks`, `get_tasks`, `update_task_statuses`, `modify_task`, and `delete_task`, follow this general workflow.
72  - If I ask to work on an issue or bug, set your goal and include a description first. If you need to look at relevant files, do so. After you have a _solid_ idea of what's required to complete my request, fill out your tasks accordingly and get started.
73- When you do not see that specific list of tools from that specific `planning` server, use whatever workflow the todo tools you do have prescribe.