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.
Draft updates to 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.
Present the relevant new or updated stories and acceptance criteria to the user for review, and wait for explicit confirmation before changing implementation code.
Incorporate requested story changes before proceeding.
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.