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