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:

Read design/index.md and every story related to the requested behavior.
Update an existing story or create a new design/us-NNN-short-name.md story before implementation.
Define observable acceptance criteria using user or operator language.
Set story status to proposed or in-progress while the work is incomplete.

While implementing:

Work in vertical slices against the documented acceptance criteria.
Add tests for important behavior before implementation when practical.
Keep implementation references and related-story links current.
Do not mark an acceptance criterion complete until the behavior exists and has been validated.

Before completing or committing:

Set completed story status to implemented or verified as appropriate.
Check completed acceptance criteria and record validation evidence.
Update design/index.md whenever stories are added, renamed, moved, or materially reclassified.
Add a high-level entry to design/log.md under the verified current date.
Run npm run design:validate along with relevant tests, type checks, lint, and builds.

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.

Always run date -u +%Y-%m-%dT%H:%M:%SZ before adding or updating story timestamps or dated log entries. Never guess dates.