44 lines
2.4 KiB
Markdown
44 lines
2.4 KiB
Markdown
# 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.
|