Add agent workflow and domain documentation

1 files changed, 32 insertions, 0 deletions

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.