Issue tracker: Forgejo #

Issues and specs for this repo live as issues on Forgejo, at https://git.jcollie.dev/jeff/winget-submit/issues. Use the fj CLI for all operations. fj infers the repository from the origin remote; pass -R jeff/winget-submit when running outside a clone.

The Tangled mirror, https://tangled.org/jcollie.dev/winget-submit, is where the public is asked to report issues. Its tracker has no labels, so it is not where the skills work; an issue reported there is copied to Forgejo for triage, with a link back.

The design of the action as a whole is tracked in the manifest repository, as winget-pkgs#4. Read it with fj issue view 4 -R jeff/winget-pkgs --comments.

Conventions #

• Create an issue: fj issue create --title "..." --body-file - with a heredoc for multi-line bodies. Add labels with --label a,b.
• Read an issue: fj issue view <number> --comments --json.
• List issues: fj issue list --state open --json with --label, --state (open/closed/all) and --paginate as needed.
• Make an issue a child of a parent: Forgejo has no sub-issues. Put Part of #<parent> at the top of the child body, and add the child to a task list (- [ ] #<child>) in the parent body.
• Comment on an issue: fj issue comment <number> --body "..."
• Apply / remove labels: fj issue edit <number> --add-label "..." / --remove-label "..."
• Close: fj issue close takes no comment, so comment first: fj issue comment <number> --body "...", then fj issue close <number>.

Pull requests as a triage surface #

PRs as a request surface: no. (Set to yes if this repo treats external PRs as feature requests; /triage reads this flag.)

When set to yes, PRs run through the same labels and states as issues, using the fj pr equivalents (fj pr view, fj pr comment, fj pr edit --add-label/--remove-label, fj pr close).

Forgejo shares one number space across issues and PRs, so a bare #42 may be either: resolve with fj pr view 42 and fall back to fj issue view 42.

When a skill says "publish to the issue tracker" #

Create a Forgejo issue.

When a skill says "fetch the relevant ticket" #

Read it as in Read an issue above.

Wayfinding operations #

Used by /wayfinder. The map is a single issue with child issues as tickets.

• Map: a single issue labelled wayfinder:map, holding the Notes / Decisions-so-far / Fog body. fj issue create --label wayfinder:map.
• Child ticket: an issue linked to the map as in Make an issue a child of a parent. Labels: wayfinder:<type> (research/prototype/grilling/task). Once claimed, the ticket is assigned to the driving dev.
• Blocking: Forgejo's native issue dependencies. Make <child> depend on <blocker> by piping the JSON body {"owner":"jeff","repo":"winget-submit","index":<blocker>} into fj api -X POST /repos/jeff/winget-submit/issues/<child>/dependencies --input -; list a ticket's blockers with fj api /repos/jeff/winget-submit/issues/<child>/dependencies. Also put a Blocked by: #<n>, #<n> line at the top of the child body so the edge is readable without the API. A ticket is unblocked when every blocker is closed.
• Frontier query: list the map's open children (fj issue list --state open --json, scoped to the map's task list), drop any with an open blocker or an assignee; first in map order wins.
• Claim: fj issue edit <n> --add-assignee jeff, the session's first write.
• Resolve: fj issue comment <n> --body "<answer>", then fj issue close <n>, then append a context pointer (gist + link) to the map's Decisions-so-far.