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