Configure Wayfinder agent workflows

docs/agents/issue-tracker.md

@@ -0,0 +1,226 @@
+# Issue tracker: Gitea
+
+Issues and specs for this repository live in Gitea Issues.
+
+- Server: https://gitea.agavagroup.com
+- Repository: tararar/Aleksandr-test
+- Git remote: origin
+- CLI: existing tea 0.15.1
+- Login: agavagroup
+
+Use tea for issue operations. Do not substitute GitHub gh commands
+or GitLab glab commands.
+
+## PowerShell session
+
+If tea is unavailable in PATH, use the verified executable directly.
+The existing login configuration is located under the following
+XDG_CONFIG_HOME:
+
+```powershell
+$env:XDG_CONFIG_HOME = 'C:\Users\tarar\AppData\Local'
+$tea = 'C:\Users\tarar\AppData\Local\Programs\tea\tea.exe'
+```
+
+These are process-local settings. Do not change persistent environment
+variables or login configuration as part of issue operations.
+
+Use the existing login. Never print, copy into project files, or pass
+the API token as a command-line argument. Do not enable debug logging.
+
+## Conventions
+
+The commands below use the PowerShell variable $tea defined above.
+Replace placeholders with actual values.
+
+### Read an issue
+
+```powershell
+& $tea issues --login agavagroup --repo tararar/Aleksandr-test --comments <number>
+```
+
+### Read comments
+
+```powershell
+& $tea comments list --login agavagroup --repo tararar/Aleksandr-test --output json --limit 100 --page 1 <number>
+```
+
+### List issues
+
+```powershell
+& $tea issues list --login agavagroup --repo tararar/Aleksandr-test --state open --kind issues --output json --fields index,state,author,url,title,body,created,updated,assignees,labels --limit 100 --page 1
+```
+
+Use --labels "needs-triage" to filter by a label.
+
+List commands are paginated. Read subsequent pages until an empty page
+is returned when complete results are required.
+
+### Create an issue
+
+```powershell
+& $tea issues create --login agavagroup --repo tararar/Aleksandr-test --title "<title>" --description "<body>"
+```
+
+Add --labels "<label1>,<label2>" when labels are required.
+
+### Edit an issue body
+
+```powershell
+& $tea issues edit --login agavagroup --repo tararar/Aleksandr-test --description "<complete updated body>" <number>
+```
+
+Read the current body first. Preserve unrelated content and discussion.
+The description argument replaces the body.
+
+### Add a comment
+
+```powershell
+& $tea comments add --login agavagroup --repo tararar/Aleksandr-test --description "<body>" <number>
+```
+
+### Apply or remove labels
+
+```powershell
+& $tea issues edit --login agavagroup --repo tararar/Aleksandr-test --add-labels "<label>" <number>
+& $tea issues edit --login agavagroup --repo tararar/Aleksandr-test --remove-labels "<label>" <number>
+```
+
+Use separate operations for addition and removal: tea gives
+--add-labels precedence over --remove-labels.
+
+During triage, preserve unrelated labels and ensure the final result has
+exactly one category label and one state label. If existing state labels
+conflict, ask the maintainer before changing them.
+
+### Assign an issue
+
+```powershell
+& $tea issues edit --login agavagroup --repo tararar/Aleksandr-test --add-assignees "<username>" <number>
+```
+
+Use a verified Gitea username. Do not assume that the login alias
+agavagroup is a username or that @me is supported.
+
+### Close or reopen an issue
+
+```powershell
+& $tea issues close --login agavagroup --repo tararar/Aleksandr-test <number>
+& $tea issues reopen --login agavagroup --repo tararar/Aleksandr-test <number>
+```
+
+When closing with an explanation, post the comment first and close
+the issue only after the comment succeeds.
+
+### List or create labels
+
+```powershell
+& $tea labels list --login agavagroup --repo tararar/Aleksandr-test --output json --limit 100 --page 1
+& $tea labels create --login agavagroup --repo tararar/Aleksandr-test --name "<name>" --color "<hex color>" --description "<description>"
+```
+
+Check existing labels before creating any. Use agreed colors and
+descriptions; do not create duplicates.
+
+### Multiline text
+
+Use a PowerShell single-quoted here-string or read an approved UTF-8
+body file into a variable, then pass that variable to --description.
+
+Do not use Bash heredoc syntax in PowerShell. Do not evaluate issue text
+as shell code.
+
+## Pull requests as a triage surface
+
+PRs as a request surface: no.
+
+Do not include pull requests in automatic triage discovery.
+If the maintainer explicitly requests work on a pull request, inspect
+the installed tea help and establish the necessary workflow first.
+
+## When a skill says "publish to the issue tracker"
+
+Create a Gitea issue using the conventions above.
+
+## When a skill says "fetch the relevant ticket"
+
+Read the Gitea issue and its comments.
+
+## Wayfinding operations
+
+Use issue bodies and links to represent the map and its relationships.
+This workflow does not rely on unverified native sub-issue or dependency
+features of the server.
+
+### Map
+
+The map is one issue carrying the wayfinder:map label and the sections
+required by the installed wayfinder skill: Notes, Decisions-so-far, Fog,
+and its ordered ticket list.
+
+### Child ticket
+
+Create one issue per decision ticket.
+
+Put `Part of #<map-number>` near the top of the body.
+Add a link to the child issue in the map's ordered task list.
+
+Use one of the type labels:
+
+- wayfinder:research
+- wayfinder:prototype
+- wayfinder:grilling
+- wayfinder:task
+
+Check for these labels and create missing ones only when authorized
+Wayfinder work requires them.
+
+### Blocking
+
+Put `Blocked by: #<number>, #<number>` near the top of the child body.
+Omit this line when there are no blockers.
+
+A ticket is unblocked only when all listed blocker issues are closed.
+Read blocker state from Gitea; do not infer it from stale map text.
+
+### Frontier
+
+Read the map's ordered ticket list and inspect its children.
+
+A frontier candidate must be:
+
+- open;
+- unblocked;
+- unassigned.
+
+Choose the first eligible ticket in map order.
+
+### Claim
+
+Assign the ticket to the verified driving developer's username before
+starting work. This is the first write of a ticket-working session.
+
+Re-read the ticket immediately before claiming it. This workflow does
+not provide an atomic claim; if a competing assignment is observed,
+stop and resolve ownership with the maintainer.
+
+### Resolve
+
+1. Post the answer as a comment.
+2. Close the child issue after the comment succeeds.
+3. Update its task-list entry in the map.
+4. Append a concise decision and a link to the answer in Decisions-so-far.
+
+Preserve the rest of the map body.
+
+In human-facing output, refer to maps and tickets by their titles,
+with links, rather than bare issue numbers.
+
+## API capability boundary
+
+tea 0.15.1 provides an authenticated api command. Prefer the verified
+issue commands above.
+
+Before using an additional API endpoint, verify its method, path,
+request shape, and availability against the target server's API
+documentation. Do not assume GitHub API endpoints work on Gitea.