From 235cdce071928c8517acd5b98b1fe19dbe73f36e Mon Sep 17 00:00:00 2001 From: Dylan Garvis Date: Fri, 14 Aug 2026 22:15:12 -0400 Subject: [PATCH] docs(agent): add repository guidance --- AGENTS.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c62a81a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,53 @@ +# Repository Agent Guidance + +## User-story-driven development + +The `design/` directory is the OKF v0.1 product record for this repository. Use user stories to plan, implement, verify, and track all behavior. + +Before changing behavior: + +1. Read `design/index.md` and every story related to the requested behavior. +2. Draft updates to an existing story or create a new `design/user-stories/us-NNN-short-name.md` story before implementation. +3. Define observable acceptance criteria using user or operator language. +4. Present the relevant new or updated stories and acceptance criteria to the user for review, and wait for explicit confirmation before changing implementation code. +5. Incorporate requested story changes before proceeding. +6. Set story status to `in-progress` while approved implementation is incomplete. + +While implementing: + +1. Work in vertical slices against the documented acceptance criteria. +2. Add tests for important behavior before implementation when practical. +3. Keep implementation references and related-story links current. +4. Do not mark an acceptance criterion complete until the behavior exists and has been validated. + +Before completing or committing: + +1. Set a completed story status to `done` only when all acceptance criteria are complete and verified. +2. Check completed acceptance criteria and record validation evidence where appropriate. +3. Update `design/index.md` and `design/user-stories/index.md` whenever stories are added, renamed, moved, or materially reclassified. +4. Add a high-level entry to `design/log.md` under the verified current date. +5. Run OKF validation along with relevant Gradle tests, lint checks, and builds. + +## OKF conventions + +- Every non-reserved Markdown file in `design/` must have YAML frontmatter with a non-empty `type`. +- User stories use `type: User Story` and include `status`, `title`, and `description`. +- Allowed story statuses are `backlog`, `in-progress`, and `done`. +- Every user story includes an acceptance-criteria section using Markdown task-list items. +- `design/index.md` and `design/log.md` are reserved OKF files and follow the OKF index/log structures. +- Store user stories in `design/user-stories/` and keep their catalog current. +- Use standard Markdown links and keep repository-local links valid when files move. +- Preserve unknown frontmatter extensions. + +## Java and Spigot development + +- Use the Java version and Spigot API version declared by the Gradle build. +- Treat compiler warnings as errors. +- Prefer test-first development for domain rules and state transitions when practical. +- Run `./gradlew clean check jar` before completing implementation work. +- Keep Bukkit event handlers thin and move testable game rules into focused domain services. +- Do not perform blocking file or network operations on the server tick thread. + +## Timestamps + +Always run `date +%Y-%m-%d` before adding or updating dates in stories or the design log. Use RFC 3339 UTC timestamps (`YYYY-MM-DDTHH:MM:SSZ`) when a date-time is required. Never guess dates.