From 646ccf9d995963a5e94b40c2e2a38ef5c88fa4b3 Mon Sep 17 00:00:00 2001 From: Alexander Trotsenko Date: Mon, 12 Oct 2026 16:32:02 -0400 Subject: [PATCH] Configure Wayfinder agent workflows --- AGENTS.md | 32 +++++ docs/agents/domain.md | 69 +++++++++++ docs/agents/issue-tracker.md | 226 +++++++++++++++++++++++++++++++++++ docs/agents/triage-labels.md | 47 ++++++++ 4 files changed, 374 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md create mode 100644 docs/agents/triage-labels.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..dc015cb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,32 @@ +# Aleksandr-test + +Aleksandr-test is an independent test project for learning Wayfinder +and AI-agent workflows. Do not import domain assumptions, terminology, +or architectural decisions from other projects. + +## Agent skills + +Use the original installed Matt Pocock skills without modifying their +SKILL.md files, frontmatter, or supporting resources. + +When a requested skill is missing from the session's available-skills +list, read its installed SKILL.md directly and follow its instructions. +When instructions refer to a Skill tool that is unavailable, read and +apply the named skill's SKILL.md instead. + +### Issue tracker + +Issues and specs live in Gitea Issues for tararar/Aleksandr-test. +Use the existing tea CLI with login agavagroup. +See `docs/agents/issue-tracker.md`. + +### Triage labels + +Use the five standard state labels and the bug/enhancement categories. +See `docs/agents/triage-labels.md`. + +### Domain docs + +Use single-context documentation: root GLOSSARY.md and docs/adr/. +Create domain documents lazily. +See `docs/agents/domain.md`. diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..ff0619c --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,69 @@ +# Domain Docs + +Aleksandr-test uses a single-context documentation layout. + +It is an independent test project for learning Wayfinder and AI-agent +workflows. Do not import the Amazon domain context or decisions from +Andrey's project or any other project. + +## Before exploring, read these + +- GLOSSARY.md at the repository root, if it exists. +- ADRs in docs/adr/ that concern the area being explored. + +If these files do not exist, proceed silently. Do not flag their absence +or propose creating empty files upfront. + +The domain-modeling skill creates documents lazily when terms or +decisions are actually resolved. + +## File structure + +```text +/ +├── GLOSSARY.md +├── docs/ +│ └── adr/ +│ ├── 0001-slug.md +│ └── 0002-slug.md +└── ... +``` + +Create GLOSSARY.md only when the first project-specific term is resolved. +Create docs/adr/ only when the first qualifying ADR is needed. + +Do not create GLOSSARY-MAP.md or per-context documentation as part of +this single-context setup. + +## Use the glossary's vocabulary + +When output names a domain concept in an issue, proposal, hypothesis, +or test, use the term defined in GLOSSARY.md. + +Avoid synonyms that the glossary explicitly rejects. + +If a needed concept is missing, reconsider whether it belongs to this +project or is a real gap to resolve with domain-modeling. + +Keep the glossary limited to project-specific terms. It is not a spec, +an implementation guide, or a scratch pad. + +Use the installed domain-modeling/GLOSSARY-FORMAT.md when writing entries. + +## Architectural decisions + +Read relevant ADRs before proposing changes. + +If a proposal contradicts an existing ADR, surface the conflict +explicitly and explain why reopening the decision may be appropriate. + +Offer an ADR only when all three conditions hold: + +1. The decision is meaningfully costly to reverse. +2. A future reader would find it surprising without context. +3. It results from a real trade-off between alternatives. + +Use the installed domain-modeling/ADR-FORMAT.md. + +Number ADR files sequentially, starting at 0001 and incrementing the +highest existing number. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..534a7b9 --- /dev/null +++ b/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 +``` + +### Read comments + +```powershell +& $tea comments list --login agavagroup --repo tararar/Aleksandr-test --output json --limit 100 --page 1 +``` + +### 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 "" --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. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..4931d8a --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,47 @@ +# Triage Labels + +The skills use canonical roles. This file maps those roles to the +actual Gitea label strings for tararar/Aleksandr-test. + +## State roles + +| Label in mattpocock/skills | Label in our tracker | Meaning | +| --- | --- | --- | +| needs-triage | needs-triage | Maintainer needs to evaluate the issue | +| needs-info | needs-info | Waiting on the reporter for more information | +| ready-for-agent | ready-for-agent | Fully specified and ready for an AFK agent | +| ready-for-human | ready-for-human | Requires human implementation | +| wontfix | wontfix | Will not be actioned | + +## Category roles + +| Canonical role | Label in our tracker | Meaning | +| --- | --- | --- | +| bug | bug | Something is broken | +| enhancement | enhancement | New feature or improvement | + +## Rules + +Every triaged issue must carry exactly one category label and exactly +one state label. Preserve unrelated labels. + +If multiple state labels conflict, flag the conflict and ask the +maintainer before changing anything. + +Use these mapped strings whenever a skill refers to a canonical role. + +The normal state path starts at needs-triage and proceeds to needs-info, +ready-for-agent, ready-for-human, or wontfix. Once the reporter supplies +the requested information, needs-info returns to needs-triage for +re-evaluation. + +Follow the installed triage skill for verification, recommendations, +agent briefs, closure, and recording rejected enhancements. + +Every issue or comment posted during triage must begin with: + +> *This was generated by AI during triage.* + +Check Gitea for existing labels before creating missing ones. +This configuration file defines the vocabulary; writing it does not +itself create labels on the server.