[OCaml] Mobile-friendly clone of cgit.
chore extract guidance into focused topic files
Split the monolithic agents.md into three focused steering files: - git.md: conventional commits and branches - ocaml.md: Dune build, opam switch, formatting, testing - web-design.md: WCAG 2.1 AA, semantic HTML, CSS, no-JS philosophy agents.md now contains only normative language definitions, scope, and the code repo URL.
Changed files
.kiro/steering/agents.md
@@ -16,81 +16,6 @@
16
16
17
17
- The project SHALL implement a lightweight, mobile-friendly alternative to the cgit software.
18
18
19
Removed:
## Architecture
20
Removed:
21
Removed:
### Opam switch
22
Removed:
23
Removed:
- The project SHALL rely on a project-local opam switch found at `./_opam/`.
24
Removed:
25
Removed:
### Build system
26
Removed:
27
Removed:
- The project SHALL use the Dune build system.
28
Removed:
29
Removed:
## Repository Map
30
Removed:
31
Removed:
- `README.org` — describes the overall architecture.
32
Removed:
- `bin/` — contains the main ogit executable target.
33
Removed:
- `lib/` — contains libraries used by ogit.
34
Removed:
- `test/` — contains tests.
35
Removed:
36
19
## Code
37
20
38
21
The public code repo is hosted at <https://git.mlnp.fr/ogit>.
39
Removed:
40
Removed:
### Versions
41
Removed:
42
Removed:
- The project SHALL target OCaml 5.2.1.
43
Removed:
44
Removed:
### Format
45
Removed:
46
Removed:
- The project code SHALL be formatted using the `.ocamlformat` config file located at the project root.
47
Removed:
- Before committing code, agents SHALL run `dune fmt` and ensure that it completes successfully.
48
Removed:
49
Removed:
### Version control system
50
Removed:
51
Removed:
- The project SHALL use Git as its version control system.
52
Removed:
53
Removed:
#### Conventional Commits
54
Removed:
55
Removed:
- Commit messages SHALL follow the [Conventional Commits](https://www.conventionalcommits.org) specification.
56
Removed:
- The commit message structure SHALL be: `<type>(<optional scope>): <description>`.
57
Removed:
- Allowed types include: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
58
Removed:
- Breaking changes SHALL be indicated by a `!` after the type/scope, or by a `BREAKING CHANGE:` footer.
59
Removed:
- Commits created by an AI agent SHALL indicate so in the commit fields:
60
Removed:
- `user.name` — concatenate agent model name, and intelligence or reasoning level.
61
Removed:
- `user.email` — fictitious e-mail address identifying the agent's parent company.
62
Removed:
- A commit SHALL be created after every modification request.
63
Removed:
- If the next request is an adjustment, additional steering, or concerns the same files as those already committed, the latest commit SHALL be amended rather than a new commit being created.
64
Removed:
65
Removed:
#### Conventional Branch
66
Removed:
67
Removed:
- Branch names SHALL follow the [Conventional Branch](https://conventional-branch.github.io/) v1.1.0 specification.
68
Removed:
- The branch name structure SHALL be: `<type>/<description>`.
69
Removed:
- Allowed purpose prefixes: `feature/` (or `feat/`), `bugfix/` (or `fix/`), `hotfix/`, `release/`, `chore/`.
70
Removed:
- Branches created by an AI agent SHALL use the appropriate AI agent source prefix (e.g. `ai/`, `claude/`, `copilot/`, `cursor/`, `codex/`).
71
Removed:
- Trunk branches (`main`, `master`, `develop`) do not use a prefix.
72
Removed:
- Branch descriptions SHALL use lowercase alphanumerics and hyphens only (dots permitted in release versions).
73
Removed:
- Consecutive, leading, or trailing hyphens or dots MUST NOT appear in descriptions.
74
Removed:
- Ticket numbers SHOULD be included where applicable (e.g. `feat/issue-42-add-pagination`).
75
Removed:
76
Removed:
## Documentation
77
Removed:
78
Removed:
- This repository SHALL use Org Mode for project documentation. New project docs SHALL use `.org` files.
79
Removed:
- Architecture docs SHALL be updated when MQTT topics, payload schema, host roles, or data flow change.
80
Removed:
81
Removed:
## Testing
82
Removed:
83
Removed:
- Modifications to the code SHALL be followed by running regression tests.
84
Removed:
- When attempting to compile this project, agents SHALL use a non-default Dream server listening port, so that agent test builds won't clash with an existing Dream server.
85
Removed:
86
Removed:
## Accessibility
87
Removed:
88
Removed:
- All rendered HTML SHALL conform to WCAG 2.1 AA.
89
Removed:
- Text and interactive elements SHALL meet a minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text (>=18.66px bold or >=24px).
90
Removed:
- Interactive targets (links, buttons) SHALL have a minimum target size of 44×44 CSS pixels, or sufficient spacing to compensate per WCAG 2.5.8.
91
Removed:
- Focus indicators SHALL be visible on all interactive elements (`:focus-visible` outline).
92
Removed:
- Semantic HTML elements SHALL be preferred over `div`/`span` where an appropriate element exists (e.g. `nav`, `header`, `main`, `footer`, `time`).
93
Removed:
- Images SHALL have descriptive `alt` text; decorative images SHALL use `alt=""` with `role="presentation"`.
94
Removed:
- Skip navigation links SHALL be provided.
95
Removed:
- ARIA landmarks and labels SHALL be used where native semantics are insufficient.
96
Removed:
- When adding or modifying UI components, agents SHOULD verify contrast ratios against the page background and component background using computed values rather than assumptions.
.kiro/steering/git.md
@@ -0,0 +1,35 @@
1
Added:
---
2
Added:
inclusion: auto
3
Added:
---
4
Added:
5
Added:
# Git Workflow
6
Added:
7
Added:
## Version Control System
8
Added:
9
Added:
- The project SHALL use Git as its version control system.
10
Added:
11
Added:
## Conventional Commits
12
Added:
13
Added:
- Commit messages SHALL follow the [Conventional Commits](https://www.conventionalcommits.org) specification.
14
Added:
- The commit message structure SHALL be: `<type>(<optional scope>): <description>`.
15
Added:
- Allowed types include: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
16
Added:
- A commit SHALL be created after every modification request.
17
Added:
- If the next request is an adjustment, additional steering, or concerns the same files as those already committed, the latest commit SHALL be amended rather than a new commit being created.
18
Added:
19
Added:
## AI Agent Authorship
20
Added:
21
Added:
- When a commit is authored by an AI agent, the **author** field SHALL identify the agent:
22
Added:
- `user.name` — agent model name and intelligence or reasoning level (e.g. `Claude Sonnet 4`).
23
Added:
- `user.email` — a fictitious e-mail address identifying the agent's parent company (e.g. `claude@anthropic.invalid`).
24
Added:
- The **committer** field SHALL default to the system Git configuration (`user.name` and `user.email` from `git config`), i.e. the human operator.
25
Added:
- Agents SHALL use `git commit --author="<name> <email>"` to set the author while leaving the committer as the configured user.
26
Added:
27
Added:
## Conventional Branch
28
Added:
29
Added:
- Branch names SHALL follow the [Conventional Branch](https://conventional-branch.github.io/) v1.1.0 specification.
30
Added:
- The branch name structure SHALL be: `<type>/<description>`.
31
Added:
- Allowed purpose prefixes: `feature/` (or `feat/`), `bugfix/` (or `fix/`), `hotfix/`, `release/`, `chore/`.
32
Added:
- Branches created by an AI agent SHALL use the appropriate AI agent source prefix (e.g. `ai/`, `claude/`, `copilot/`, `cursor/`, `codex/`).
33
Added:
- Trunk branches (`main`, `master`, `develop`) do not use a prefix.
34
Added:
- Branch descriptions SHALL use lowercase alphanumerics and hyphens only (dots permitted in release versions).
35
Added:
- Consecutive, leading, or trailing hyphens or dots MUST NOT appear in descriptions.
.kiro/steering/ocaml.md
@@ -0,0 +1,39 @@
1
Added:
---
2
Added:
inclusion: auto
3
Added:
---
4
Added:
5
Added:
# OCaml & Dune
6
Added:
7
Added:
## Opam Switch
8
Added:
9
Added:
- The project SHALL rely on a project-local opam switch found at `./_opam/`.
10
Added:
11
Added:
## Build System
12
Added:
13
Added:
- The project SHALL use the Dune build system.
14
Added:
15
Added:
## Versions
16
Added:
17
Added:
- The project SHALL target OCaml 5.2.1.
18
Added:
19
Added:
## Format
20
Added:
21
Added:
- The project code SHALL be formatted using the `.ocamlformat` config file located at the project root.
22
Added:
- Before committing code, agents SHALL run `dune fmt` and ensure that it completes successfully.
23
Added:
24
Added:
## Repository Map
25
Added:
26
Added:
- `README.org` — describes the overall architecture.
27
Added:
- `bin/` — contains the main ogit executable target.
28
Added:
- `lib/` — contains libraries used by ogit.
29
Added:
- `test/` — contains tests.
30
Added:
31
Added:
## Testing
32
Added:
33
Added:
- Modifications to the code SHALL be followed by running regression tests.
34
Added:
- When attempting to compile this project, agents SHALL use a non-default Dream server listening port, so that agent test builds won't clash with an existing Dream server.
35
Added:
36
Added:
## Documentation
37
Added:
38
Added:
- This repository SHALL use Org Mode for project documentation. New project docs SHALL use `.org` files.
39
Added:
- Architecture docs SHALL be updated when MQTT topics, payload schema, host roles, or data flow change.
.kiro/steering/web-design.md
@@ -0,0 +1,36 @@
1
Added:
---
2
Added:
inclusion: auto
3
Added:
---
4
Added:
5
Added:
# Web Design
6
Added:
7
Added:
## Scope
8
Added:
9
Added:
- The project SHALL implement a lightweight, mobile-friendly alternative to the cgit software.
10
Added:
11
Added:
## Design Philosophy
12
Added:
13
Added:
- The UI SHALL be semantic-first: structure and meaning come from HTML elements, not from CSS classes or JavaScript behaviour.
14
Added:
- The project MUST NOT rely on client-side JavaScript for core functionality. Pages SHALL be fully usable with JavaScript disabled.
15
Added:
- Visual design SHALL be expressed through CSS custom properties and minimal, composable utility styles.
16
Added:
17
Added:
## Accessibility (WCAG 2.1 AA)
18
Added:
19
Added:
- All rendered HTML SHALL conform to WCAG 2.1 AA.
20
Added:
- Text and interactive elements SHALL meet a minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text (>=18.66px bold or >=24px).
21
Added:
- Interactive targets (links, buttons) SHALL have a minimum target size of 44×44 CSS pixels, or sufficient spacing to compensate per WCAG 2.5.8.
22
Added:
- Focus indicators SHALL be visible on all interactive elements (`:focus-visible` outline).
23
Added:
- When adding or modifying UI components, agents SHOULD verify contrast ratios against the page background and component background using computed values rather than assumptions.
24
Added:
25
Added:
## Semantic HTML
26
Added:
27
Added:
- Semantic HTML elements SHALL be preferred over `div`/`span` where an appropriate element exists (e.g. `nav`, `header`, `main`, `footer`, `time`).
28
Added:
- Images SHALL have descriptive `alt` text; decorative images SHALL use `alt=""` with `role="presentation"`.
29
Added:
- Skip navigation links SHALL be provided.
30
Added:
- ARIA landmarks and labels SHALL be used where native semantics are insufficient.
31
Added:
32
Added:
## CSS
33
Added:
34
Added:
- Layout SHALL use modern CSS (grid, flexbox) without framework dependencies.
35
Added:
- Colour tokens SHALL be defined as CSS custom properties to enable consistent theming and ease contrast verification.
36
Added:
- Media queries SHALL ensure usability from 320px viewport width upward.