docs(design): add OKF user story catalog

2026-08-01 14:49:37 -04:00
parent 2657399628
commit fa5346458a
21 changed files with 777 additions and 1 deletions
@@ -0,0 +1,41 @@
+# 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. Update an existing story or create a new `design/us-NNN-short-name.md` story before implementation.
+3. Define observable acceptance criteria using user or operator language.
+4. Set story status to `proposed` or `in-progress` while the work 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 completed story status to `implemented` or `verified` as appropriate.
+2. Check completed acceptance criteria and record validation evidence.
+3. Update `design/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 `npm run design:validate` along with relevant tests, type checks, lint, 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 `story_id`, `status`, `title`, `description`, `tags`, and `timestamp`.
+- Allowed story statuses are `proposed`, `in-progress`, `implemented`, and `verified`.
+- `design/index.md` and `design/log.md` are reserved OKF files and follow the OKF index/log structures.
+- Prefer structured sections: `# User Story`, `# Acceptance Criteria`, `# Implementation`, `# Validation`, and `# Related Stories`.
+- Use repository-relative links and keep them valid when files move.
+- Preserve unknown frontmatter extensions.
+
+## Timestamps
+
+Always run `date -u +%Y-%m-%dT%H:%M:%SZ` before adding or updating story timestamps or dated log entries. Never guess dates.