From 170f05697812b2f8b29226b4aa07b1b8db38873e Mon Sep 17 00:00:00 2001
From: Andrew Guschin <guschin@altlinux.org>
Date: Thu, 29 Oct 2026 21:47:30 +0400
Subject: Add agent workflow and domain documentation

---
 docs/agents/domain.md        | 23 +++++++++++++++++++++++
 docs/agents/issue-tracker.md | 32 ++++++++++++++++++++++++++++++++
 docs/agents/triage-labels.md | 15 +++++++++++++++
 3 files changed, 70 insertions(+)
 create mode 100644 docs/agents/domain.md
 create mode 100644 docs/agents/issue-tracker.md
 create mode 100644 docs/agents/triage-labels.md

(limited to 'docs/agents')

diff --git a/docs/agents/domain.md b/docs/agents/domain.md
new file mode 100644
index 0000000..ded5401
--- /dev/null
+++ b/docs/agents/domain.md
@@ -0,0 +1,23 @@
+# Domain docs
+
+This repo uses a single-context domain layout.
+
+## Before exploring the codebase
+
+Read the root `GLOSSARY.md` and any ADRs in `docs/adr/` relevant to
+the work. If either is absent, continue without requesting its creation.
+The domain-modeling skill creates these documents as terms and
+decisions are resolved.
+
+## Vocabulary
+
+Use glossary terms in issue titles, proposals, hypotheses, and tests.
+Respect synonyms the glossary explicitly avoids.
+
+If a needed concept is missing, reconsider whether it belongs in the
+project's vocabulary. Record real gaps for domain-modeling.
+
+## Decisions
+
+If a proposal conflicts with an ADR, identify the ADR and explain why
+the decision should be reconsidered.
diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
new file mode 100644
index 0000000..916536f
--- /dev/null
+++ b/docs/agents/issue-tracker.md
@@ -0,0 +1,32 @@
+# Issue tracker
+
+Issues and specs live as markdown files in `.scratch/`.
+
+## Conventions
+
+- Each feature has a directory at `.scratch/<feature-slug>/`.
+- Its spec lives at `.scratch/<feature-slug>/spec.md`.
+- Each ticket has a separate file at
+  `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`.
+- Record triage state in a `Status:` line near the top of each ticket.
+  Use the role strings in `triage-labels.md`.
+- Append comments under a `## Comments` heading.
+
+## Publishing and fetching tickets
+
+To publish a ticket, create its file in the feature's `issues/` directory.
+To fetch a ticket, read the referenced file.
+
+## Wayfinding
+
+- Keep the effort's map at `.scratch/<effort>/map.md`, with Notes,
+  Decisions-so-far, and Fog sections.
+- Keep child tickets at `.scratch/<effort>/issues/NN-<slug>.md`.
+  Put the question in the body and record a `Type:` of `research`,
+  `prototype`, `grilling`, or `task`.
+- Record dependencies in a `Blocked by: NN, NN` line.
+  A ticket becomes unblocked when all listed tickets are resolved.
+- Choose the first open, unblocked, unclaimed ticket by number.
+- Before starting work, save `Status: claimed`.
+- On completion, append an `## Answer`, set `Status: resolved`,
+  and add a summary and link to the map's Decisions-so-far section.
diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md
new file mode 100644
index 0000000..7ad917c
--- /dev/null
+++ b/docs/agents/triage-labels.md
@@ -0,0 +1,15 @@
+# Triage labels
+
+Use these strings for triage status in local issue files.
+
+| Role | Status string | Meaning |
+| --- | --- | --- |
+| needs-triage | needs-triage | Needs maintainer evaluation |
+| needs-info | needs-info | Waiting for more information |
+| ready-for-agent | ready-for-agent | Specified and ready for an agent |
+| ready-for-human | ready-for-human | Requires human implementation |
+| wontfix | wontfix | Will not be implemented |
+
+When a skill refers to a canonical triage role, use its status string.
+Wayfinding tickets also use `claimed` and `resolved` as described in
+`issue-tracker.md`.
-- 
cgit v1.2.3