Skip to content

Commit ccfe394

Browse files
committed
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]>
1 parent 3293d12 commit ccfe394

2 files changed

Lines changed: 14 additions & 3 deletions

File tree

‎AGENTS.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ This file provides structured guidance for AI coding assistants and agents worki
4747
- 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`
4848

4949
**Important rules:**
50+
5051
- **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.
5152
- **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.
5253
- **[`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.
6869
## Quick Reference
6970

7071
### Code Structure
72+
7173
- `packages/core/` - Core platform charts (installer, platform)
7274
- `packages/system/` - System components (CSI, CNI, operators)
7375
- `packages/apps/` - User-facing applications in catalog
@@ -76,13 +78,15 @@ These hold for every task, whichever document the routes above point at.
7678
- `api/` - Kubernetes CRDs
7779

7880
### Conventions
81+
7982
- **Helm Charts**: Umbrella pattern, vendored upstream charts in `charts/`
8083
- **Go Code**: Controller-runtime patterns, kubebuilder style
8184
- **Git Commits**: Conventional Commits (`type(scope): description`) with `--signoff`; an agent-assisted commit adds one `Assisted-by: LLM` trailer
8285
- **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
8386
- **Prose**: One continuous line per paragraph — see [Prose Formatting](#prose-formatting)
8487

8588
### What NOT to Do
89+
8690
- ❌ Edit `/vendor/`, `zz_generated.*.go`, upstream charts directly
8791
- ❌ Modify `go.mod`/`go.sum` manually (use `go get`)
8892
- ❌ Force push to main/master

‎docs/agents/overview.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ The platform exposes infrastructure services via the Kubernetes API with ready-m
1616

1717
## Code Layout
1818

19-
```
19+
```text
2020
.
2121
├── packages/ # Main directory for cozystack packages
2222
│ ├── core/ # Core platform logic charts (installer, platform)
@@ -50,7 +50,7 @@ The platform exposes infrastructure services via the Kubernetes API with ready-m
5050

5151
Every package is a Helm chart following the umbrella chart pattern:
5252

53-
```
53+
```text
5454
packages/<category>/<package-name>/
5555
├── Chart.yaml # Chart definition and parameter docs
5656
├── Makefile # Development workflow targets
@@ -129,6 +129,7 @@ Markdown follows these markdownlint rules: every code fence names a language (`t
129129
## Conventions
130130

131131
### Helm Charts
132+
132133
- Follow **umbrella chart** pattern for system components
133134
- Include upstream charts in `charts/` directory (vendored, not referenced)
134135
- Override configuration in root `values.yaml`
@@ -144,6 +145,7 @@ A new first-party image is built from a `Containerfile`, which the package `Make
144145
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>`.
145146

146147
### Go Code
148+
147149
- Follow standard **Go conventions** and idioms
148150
- Use **controller-runtime** patterns for Kubernetes controllers
149151
- Prefer **kubebuilder** for API definitions and controllers
@@ -164,10 +166,11 @@ Do **not** set `CreateReplace` blindly: it overwrites every CRD in `crds/` and c
164166
### Documentation
165167

166168
Documentation is organized as follows:
169+
167170
- `docs/` - General documentation
168171
- `docs/agents/` - Instructions for AI agents
169172
- `docs/changelogs/` - Release changelogs
170-
- Main website: https://github.com/cozystack/website
173+
- Main website: <https://github.com/cozystack/website>
171174

172175
### Domain references for specific tasks
173176

@@ -179,20 +182,24 @@ Before working on these areas, read the relevant doc first:
179182
## Things Agents Should Not Do
180183

181184
### Never Edit These
185+
182186
- Do not modify files in `/vendor/` (Go dependencies)
183187
- Do not edit generated files: `zz_generated.*.go`
184188
- Do not change `go.mod`/`go.sum` manually (use `go get`)
185189
- Do not edit upstream charts in `packages/*/charts/` directly (use patches)
186190
- Do not modify image digests in `values.yaml` (generated by build)
187191

188192
### Version Control
193+
189194
- Do not commit built artifacts from `_out`
190195
- Do not commit test artifacts or temporary files
191196

192197
### Git Operations
198+
193199
- Do not force push to main/master
194200
- Do not update git config
195201
- Do not perform destructive operations without explicit request
196202

197203
### Core Components
204+
198205
- Do not modify `packages/core/platform/` without understanding migration impact

0 commit comments

Comments
 (0)