Skip to content
Sixnix Desk

An example AGENTS.md

Instructions for an assistant working in this repository. Everything here is about Panel on the desk at https://desk.example.com.

Tracking work

Issues for this project live on the desk, not in a to-do file. The sixnix-desk command talks to it. It is authorised for Panel alone and can do nothing else on the desk: it cannot read a client, a ticket or anybody’s settings, and it cannot email a soul.

Set it up once:

export DESK_URL=https://desk.example.com
export DESK_KEY='…'          # made on the project's Automation section

That is the desk’s own address, deliberately, even where the brand this project belongs to answers on an address of its own. A key is scoped to a project by the key rather than by the name it is called on, so both work; the difference is that a brand’s address can be cleared on the brand, and a job that had it written down would then stop with nothing to say why.

sixnix-desk whoami says which project the key works on and what it may do. If a command is refused, the message names the permission that is missing, so say so rather than working around it.

Before opening anything

Look first. A second issue for a fault already filed is worse than no issue at all:

sixnix-desk find "count query timeout"

The loop

ref=$(sixnix-desk new "Search times out over 10k rows" "Reproduced on staging with 12k rows.")
git commit -m "$ref Cache the count query"
sixnix-desk status "$ref" done

sixnix-desk new prints the reference and nothing else on stdout, so it can be caught in a variable. Put that reference in the commit message: the desk links the commit to the issue on its own, and anybody reading the issue later can see exactly what was done about it.

While working

sixnix-desk show PNL-42                      # details, what is left to tick off, who is waiting
sixnix-desk check PNL-42 "Add a regression test"
sixnix-desk tick PNL-42 2
sixnix-desk note PNL-42 "Cause: the count query runs per row."
sixnix-desk assign PNL-42 me
sixnix-desk progress PNL-42 60
sixnix-desk link PNL-42 duplicates PNL-31
sixnix-desk attach PNL-42 build.log
sixnix-desk kind PNL-42 Bug
sixnix-desk label PNL-42 +regression
sixnix-desk plan PNL-42 1.6

Add --json to any command for the desk’s full answer. A body given as - is read from stdin, which is how anything longer than a line should arrive:

sixnix-desk describe PNL-42 - < notes.md

Worked examples

Something noticed while working on something else. File it, do not fix it now:

sixnix-desk find "n+1 invoices"
sixnix-desk new "Invoice list runs a query per row" "Noticed while fixing search. 40 queries for 40 rows."

A bug you are about to fix. Look first, open it, carry the reference into the commit:

sixnix-desk find "count query timeout"
ref=$(sixnix-desk new "Search times out over 10k rows" "Reproduced on staging with 12k rows.")
sixnix-desk status "$ref" in_progress
git commit -m "$ref Cache the count query"
sixnix-desk status "$ref" done

Picking up work that already exists:

sixnix-desk issues                       # or sixnix-desk mine
sixnix-desk show PNL-42               # details, what is left, who is waiting
sixnix-desk status PNL-42 in_progress

Breaking a job down, then working through it:

ref=$(sixnix-desk new "Move uploads to object storage")
sixnix-desk check "$ref" "Write the adapter"
sixnix-desk check "$ref" "Migrate existing files"
sixnix-desk check "$ref" "Switch the writer over"
sixnix-desk tick "$ref" 1               # the number sixnix-desk show prints

The same fault reported twice. Link them rather than working both:

sixnix-desk link PNL-58 duplicates PNL-42
sixnix-desk note PNL-58 "Same cause as PNL-42: the count query is not cached."

A piece of a bigger job:

ref=$(sixnix-desk new "Adapter for object storage")
sixnix-desk link "$ref" under PNL-60

Stuck on somebody else:

sixnix-desk status PNL-42 blocked
sixnix-desk note PNL-42 "Waiting on the storage credentials; nothing to do here until they land."

Recording what you found, at length:

sixnix-desk describe PNL-42 - <<'EOF'
The count query runs once per row because the eager load is dropped when a filter is applied.
Reproduced on staging with 12k rows; 40 queries for 40 rows.
EOF
sixnix-desk attach PNL-42 slow-query.log

Sorting it for the people who plan the work:

sixnix-desk kind PNL-42 Bug
sixnix-desk label PNL-42 +regression -needs-triage
sixnix-desk plan PNL-42 1.6

Telling the user where things stand at the end of a session:

sixnix-desk mine
sixnix-desk issues in_progress

When a command is refused. Read the message: it names the missing permission. Do not work around it, and do not try another route. Say which permission the key needs:

sixnix-desk whoami                       # what this key may do

When somebody is waiting. sixnix-desk says so on stderr after a change:

sixnix-desk status PNL-42 done
# 1 person is waiting to hear about this: R-88 (Ada Reporter).
# Tell the user. Answering them is a person's job in the desk.

House rules

  • Ask before opening an issue for something the user has not asked to be tracked. A tidy tracker is one where every issue is somebody’s decision.
  • Notes are for what you found, not for narrating that you are working. The trail already records what changed.
  • If desk says people are waiting to hear about an issue, somebody outside the desk reported it. Tell the user in your summary. Answering a reporter emails a member of the public: it is a person’s job, and this key cannot do it at any permission.
  • Never put a secret in an issue. Descriptions and comments are readable by everyone who can see the project.
  • Exit codes mean what they say: 0 done, 1 asked wrongly, 2 the desk refused, 3 could not reach the desk. Check them rather than assuming a command worked.

What a key may be allowed to do

Whoever made the key ticked some of these; the rest are refused:

  • Open new issues
  • Comment on issues
  • Change an issue’s status
  • Plan an issue into a version
  • Assign an issue to someone
  • Add and remove labels and tags, and say what kind of work it is
  • Keep the checklists, and tick things off
  • Link issues to each other, and hang one under another
  • Attach files to an issue
  • Edit the title, description, priority and dates

Opening a project, changing its settings, deleting an issue, bulk edits and anything that emails a client or a reporter are not on the list at all, at any permission.