You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit ccfe394
Browse filesBrowse the repository at this point in the historyBrowse files
docs(agents): bring the agent docs in line with their markdown rules
overview.md now requires a language on every code fence and a blank
line around every list and after every heading. It broke these rules
itself, and AGENTS.md broke the list and heading ones. Label the
directory-tree fences as text, separate headings and lead-in lines
from the lists under them, and wrap the one bare URL.
Assisted-by: LLM
Signed-off-by: Aleksei Sviridkin <[email protected]>
Copy file name to clipboardExpand all lines: AGENTS.md
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,6 +47,7 @@ This file provides structured guidance for AI coding assistants and agents worki
47
47
- PR titles: a Conventional Commits header (`type(scope): description`, types from [`contributing.md`](./docs/agents/contributing.md)) auto-applies `kind/*` and `area/*` via `.github/workflows/pr-labeler.yaml`. Append `!` (or add a `BREAKING CHANGE:` footer) to apply `kind/breaking-change`
48
48
49
49
**Important rules:**
50
+
50
51
-**Match scope, then read first.** Load a process file only when the task genuinely falls in its scope, and load it before starting work — not midway through. Tasks outside a file's scope should not pull it into context.
51
52
-**Follow it exactly.** Do not assume you already know the process, and do not skip steps (`changelog.md` especially). Where the documentation and your instinct disagree, the documentation wins.
52
53
-**[`overview.md`](./docs/agents/overview.md) is the standing reference** for structure and conventions, useful even when no route above points at it.
@@ -68,6 +69,7 @@ These hold for every task, whichever document the routes above point at.
-**Git Commits**: Conventional Commits (`type(scope): description`) with `--signoff`; an agent-assisted commit adds one `Assisted-by: LLM` trailer
82
85
-**Comments and commit bodies**: WHY, not a narration of WHAT; see [Review Blockers](./docs/agents/contributing.md#review-blockers-messages-trailers-comments) in contributing.md
83
86
-**Prose**: One continuous line per paragraph — see [Prose Formatting](#prose-formatting)
@@ -50,7 +50,7 @@ The platform exposes infrastructure services via the Kubernetes API with ready-m
50
50
51
51
Every package is a Helm chart following the umbrella chart pattern:
52
52
53
-
```
53
+
```text
54
54
packages/<category>/<package-name>/
55
55
├── Chart.yaml # Chart definition and parameter docs
56
56
├── Makefile # Development workflow targets
@@ -129,6 +129,7 @@ Markdown follows these markdownlint rules: every code fence names a language (`t
129
129
## Conventions
130
130
131
131
### Helm Charts
132
+
132
133
- Follow **umbrella chart** pattern for system components
133
134
- Include upstream charts in `charts/` directory (vendored, not referenced)
134
135
- Override configuration in root `values.yaml`
@@ -144,6 +145,7 @@ A new first-party image is built from a `Containerfile`, which the package `Make
144
145
Addresses and names in docs, examples and test fixtures come from the reserved documentation ranges, never from a routable value that merely looks realistic: IPv4 from RFC 5737 (`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`), IPv6 from RFC 3849 (`2001:db8::/32`), domains from RFC 2606 and RFC 6761 (`example.com`, `.example`, `.test`, `.invalid`), ASNs from RFC 5398 (`64496`–`64511`, `65536`–`65551`), MAC addresses from RFC 7042 (`00:00:5E:00:53:00`–`00:00:5E:00:53:FF`). Where no reserved range exists, use an obviously synthetic placeholder such as `<NODE_IP>`.
145
146
146
147
### Go Code
148
+
147
149
- Follow standard **Go conventions** and idioms
148
150
- Use **controller-runtime** patterns for Kubernetes controllers
149
151
- Prefer **kubebuilder** for API definitions and controllers
@@ -164,10 +166,11 @@ Do **not** set `CreateReplace` blindly: it overwrites every CRD in `crds/` and c
164
166
### Documentation
165
167
166
168
Documentation is organized as follows:
169
+
167
170
-`docs/` - General documentation
168
171
-`docs/agents/` - Instructions for AI agents
169
172
-`docs/changelogs/` - Release changelogs
170
-
- Main website: https://github.com/cozystack/website
173
+
- Main website: <https://github.com/cozystack/website>
171
174
172
175
### Domain references for specific tasks
173
176
@@ -179,20 +182,24 @@ Before working on these areas, read the relevant doc first:
179
182
## Things Agents Should Not Do
180
183
181
184
### Never Edit These
185
+
182
186
- Do not modify files in `/vendor/` (Go dependencies)
183
187
- Do not edit generated files: `zz_generated.*.go`
184
188
- Do not change `go.mod`/`go.sum` manually (use `go get`)
185
189
- Do not edit upstream charts in `packages/*/charts/` directly (use patches)
186
190
- Do not modify image digests in `values.yaml` (generated by build)
187
191
188
192
### Version Control
193
+
189
194
- Do not commit built artifacts from `_out`
190
195
- Do not commit test artifacts or temporary files
191
196
192
197
### Git Operations
198
+
193
199
- Do not force push to main/master
194
200
- Do not update git config
195
201
- Do not perform destructive operations without explicit request
196
202
197
203
### Core Components
204
+
198
205
- Do not modify `packages/core/platform/` without understanding migration impact
0 commit comments