Configure Wayfinder agent workflows

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`.

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.

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.

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.