docs: add AGENTS, CONTRIBUTING, CHANGELOG, and skill playbooks#5
Merged
Conversation
Adds the canonical contributor + agent docs and a set of task-specific
skill playbooks adapted from a production setup. Lockstep versioning
is documented and the dashboard is aligned to the broker's version.
Root docs
- AGENTS.md: rules-of-engagement for any AI agent (Claude Code,
Cursor, Codex, etc.) — conversational style, code quality (Rust
+ TS split), commands map, skills index, PR workflow, comment
hygiene, branch/commit conventions, and the parallel-agent git
safety rules.
- CONTRIBUTING.md: human-facing contribution guide — local setup,
issue/PR quality bar, the verification suite to run before
submitting, commit message format, and security disclosure.
- CHANGELOG.md: Keep a Changelog format. Documents lockstep
versioning policy (broker and dashboard share one version,
Cargo.toml is authoritative).
- .gitignore: whitelist the three new docs from the existing
/*.md ignore rule.
Skill playbooks (.claude/skills/)
- code-review + references/gotchas.md: catch project pitfalls
linters miss (unwrap on Option::None for packet_id, dropped
oneshot replies, missing Zustand reset(), hardcoded colors,
missing i18n keys in en/ko/uz).
- verify: full pre-commit suite — cargo check/clippy/fmt/test +
eslint/prettier/yarn build.
- debug-coremq: symptom→investigation table for broker, REST,
MQTT WebSocket, and dashboard issues.
- coremq-guide: directory map, Makefile commands, default ports.
- new-backend-feature: the 7-step AdminCommand → Engine → Service
→ Controller → Route wiring.
- web-page: page → view → table/drawer + Zustand store + service
scaffold for new dashboard sections.
Lockstep version alignment
- client/package.json: 3.0.0 → 0.1.0 to match
server/coremq-server/Cargo.toml. The 3.0.0 number was
template-inherited and did not reflect project history. Flip
Cargo.toml to 3.0.0 instead if that ordering is preferred —
this commit is the safer cleanup direction.
These changes are docs/config only. No source code is modified.
📝 WalkthroughWalkthroughAdds comprehensive documentation and skill/playbook files: repository conventions, contributor guide, changelog/release rules, verification and debugging procedures, frontend/backend scaffolding guides, code-review gotchas, and minor metadata/gitignore updates. ChangesRepository Documentation & Developer Experience
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (1)
CONTRIBUTING.md (1)
133-143: ⚡ Quick winAdd language identifier to fenced code block.
The fenced code block should specify
plaintextortextas the language identifier for proper markdown rendering.Proposed fix
-``` +```text fix(server): assign packet_id for QoS 1/2 publishes🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@CONTRIBUTING.md` around lines 133 - 143, Add a language identifier (e.g., "text" or "plaintext") to the fenced code block containing the commit message (the block starting with ``` and the line "fix(server): assign packet_id for QoS 1/2 publishes") so the markdown renders correctly; update the opening fence to ```text (or ```plaintext) and leave the content unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/code-review/references/gotchas.md:
- Line 40: Replace the typo '118n' with the correct abbreviation 'i18n' in the
gotchas line; update the sentence so it reads that adding keys requires updates
to ALL THREE: `i18n/en.json`, `i18n/ko.json`, `i18n/uz.json` (ensure the heading
remains "**i18n is mandatory** — Any user-facing string must be t('key')").
In @.claude/skills/coremq-guide/skill.md:
- Line 34: Replace the mistyped directory name "118n/" with the correct "i18n/"
in the documentation line showing the i18n folder (the line containing "└──
118n/ — en.json, ko.json, uz.json"); update that string to "└── i18n/
— en.json, ko.json, uz.json" so the path is correct in the skill.md content.
In @.claude/skills/debug-coremq/skill.md:
- Line 24: Replace the misspelled abbreviation "118n" with the correct "i18n" in
the markdown table row that reads "`i18n key shows as raw `feature.title` | Key
missing from one of `118n/en.json`, `118n/ko.json`, `118n/uz.json`" (update the
`118n/en.json`, `118n/ko.json`, `118n/uz.json` tokens to `i18n/en.json`,
`i18n/ko.json`, `i18n/uz.json`); ensure you change every occurrence of the token
`118n` in this file (look for the literal `118n/...` entries and the line
mentioning `feature.title`) so the documentation consistently uses `i18n`.
In @.claude/skills/web-page/skill.md:
- Around line 22-33: The fenced directory-structure block in
.claude/skills/web-page/skill.md is missing a language identifier; update the
opening fence to include one (e.g., ```text or ```bash) so the block containing
the client/src/ tree and filenames like pages/feature.tsx, sections/feature/
(feature_view.tsx, feature_table.tsx, feature_drawer.tsx),
stores/feature_store.ts, services/feature.ts, types/feature.ts, and routes/
renders and lints correctly.
- Line 45: Fix the typo in the documentation line that references the
localization folder: change the string "client/src/118n/en.json" to
"client/src/i18n/en.json" (and similarly update any other occurrences of "118n"
in that sentence to "i18n") so the instruction reads that all user-facing
strings must be added as keys in client/src/i18n/en.json AND ko.json AND
uz.json; update the text in .claude/skills/web-page/skill.md where the phrase
"9. **i18n** — Add ALL user-facing strings as keys in `client/src/118n/en.json`"
appears.
In `@AGENTS.md`:
- Line 44: Replace the incorrect abbreviation "118n" with "i18n" in the
documentation string that reads "client/src/118n/{en,ko,uz}.json" so it becomes
"client/src/i18n/{en,ko,uz}.json"; update any other occurrences of the token
"118n" in AGENTS.md to "i18n" to ensure the example path and wording are
correct.
In `@CONTRIBUTING.md`:
- Line 81: Update the typo in the CONTRIBUTING.md sentence that references the
localization directory: change the path fragment
"client/src/118n/{en,ko,uz}.json" to "client/src/i18n/{en,ko,uz}.json" so the
example alongside the user-facing string convention t('key') points to the
correct i18n folder.
---
Nitpick comments:
In `@CONTRIBUTING.md`:
- Around line 133-143: Add a language identifier (e.g., "text" or "plaintext")
to the fenced code block containing the commit message (the block starting with
``` and the line "fix(server): assign packet_id for QoS 1/2 publishes") so the
markdown renders correctly; update the opening fence to ```text (or
```plaintext) and leave the content unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: a9b2163e-6515-400d-8716-8727b8bfba57
📒 Files selected for processing (12)
.claude/skills/code-review/references/gotchas.md.claude/skills/code-review/skill.md.claude/skills/coremq-guide/skill.md.claude/skills/debug-coremq/skill.md.claude/skills/new-backend-feature/skill.md.claude/skills/verify/skill.md.claude/skills/web-page/skill.md.gitignoreAGENTS.mdCHANGELOG.mdCONTRIBUTING.mdclient/package.json
Comment on lines
+22
to
+33
| ``` | ||
| client/src/ | ||
| ├── pages/feature.tsx — thin wrapper | ||
| ├── sections/feature/ | ||
| │ ├── feature_view.tsx — orchestrator | ||
| │ ├── feature_table.tsx — table component (optional) | ||
| │ └── feature_drawer.tsx — drawer/dialog (optional) | ||
| ├── stores/feature_store.ts — Zustand store | ||
| ├── services/feature.ts — axios calls | ||
| ├── types/feature.ts — TS types | ||
| └── routes/ — register the route | ||
| ``` |
There was a problem hiding this comment.
Add language identifier to fenced code block.
The directory structure code block should specify a language identifier for proper rendering and linting.
Proposed fix
-```
+```text
client/src/
├── pages/feature.tsx — thin wrapper
├── sections/feature/🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 22-22: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/web-page/skill.md around lines 22 - 33, The fenced
directory-structure block in .claude/skills/web-page/skill.md is missing a
language identifier; update the opening fence to include one (e.g., ```text or
```bash) so the block containing the client/src/ tree and filenames like
pages/feature.tsx, sections/feature/ (feature_view.tsx, feature_table.tsx,
feature_drawer.tsx), stores/feature_store.ts, services/feature.ts,
types/feature.ts, and routes/ renders and lints correctly.
| - Pages are thin wrappers (import view + render). Logic lives in `sections/<feature>/<feature>_view.tsx`. | ||
| - Zustand stores: split `State` (data) and `Actions` (functions), shared `initialState` constant, mandatory `reset: () => set(initialState)` for logout cleanup. Subscribe via selectors, not full destructure. | ||
| - Never call `localStorage` for auth — the axios interceptor owns token refresh. | ||
| - Every user-facing string is `t('key')`, and every key must exist in **all three** of `client/src/118n/{en,ko,uz}.json`. Missing one is a bug, not a nit. |
There was a problem hiding this comment.
Fix typo: 118n → i18n.
The correct abbreviation for internationalization is i18n, not 118n.
Proposed fix
-- Every user-facing string is `t('key')`, and every key must exist in **all three** of `client/src/118n/{en,ko,uz}.json`. Missing one is a bug, not a nit.
+- Every user-facing string is `t('key')`, and every key must exist in **all three** of `client/src/i18n/{en,ko,uz}.json`. Missing one is a bug, not a nit.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - Every user-facing string is `t('key')`, and every key must exist in **all three** of `client/src/118n/{en,ko,uz}.json`. Missing one is a bug, not a nit. | |
| - Every user-facing string is `t('key')`, and every key must exist in **all three** of `client/src/i18n/{en,ko,uz}.json`. Missing one is a bug, not a nit. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@AGENTS.md` at line 44, Replace the incorrect abbreviation "118n" with "i18n"
in the documentation string that reads "client/src/118n/{en,ko,uz}.json" so it
becomes "client/src/i18n/{en,ko,uz}.json"; update any other occurrences of the
token "118n" in AGENTS.md to "i18n" to ensure the example path and wording are
correct.
Sardor-M
added
documentation
4 tasks
Co-authored-by: Sardor Madaminov <Sardor-M@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CONTRIBUTING.md`:
- Line 133: The fenced code block opening in CONTRIBUTING.md is missing a
language tag and triggers markdownlint MD040; update the opening fence to
include a language (e.g., change the opening "```" to "```text") for the block
that contains the commit message "fix(server): assign packet_id for QoS 1/2
publishes" so the block is explicitly labeled and the linter warning is
resolved.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the canonical contributor + agent documentation and six task-specific skill playbooks. Aligns the dashboard's version to the broker's so the project ships in lockstep.
Pairs with #4 (workflow refinements). Docs/config only — no source code is modified.
What's new
Root docs
AGENTS.md— rules-of-engagement for any AI agent operating in this repo (Claude Code, Cursor, Codex, etc.). Covers:/* */block comments only, nounwrap()onOption::None, no blocking syscalls in async, bounded channels, oneshot reply requirement, no DashMap iter across.await, ReDB commit) and TypeScript (typeoverinterface, JSDoc-only, single quotes, theme tokens, Zustandreset(), the en/ko/uz i18n triplet rule)cargo/yarncommands to run after which kind of change, plus an explicit "do not run" list (make dev,cargo run,yarn dev).claude/skills/<name>/@claudemention flow--body-file, never multi-line--body)git add -A, no--no-verify, no destructive ops)CONTRIBUTING.md— human-facing contribution guide. Local setup, default endpoints, issue/PR quality bar, the verification suite to run before submitting, branch/commit conventions extracted from existing history (feat:/fix:/chore:/refactor:), security disclosure policy.CHANGELOG.md— Keep a Changelog format. Documents the lockstep versioning policy: broker and dashboard share a single version,Cargo.tomlis authoritative if drift is found, releases are taggedv<version>. Seeded[Unreleased]with the recent visible work for review..gitignore— whitelists the three new docs (the existing/*.mdrule was correctly excluding stray markdown but blocked these as a side effect).Skill playbooks (
.claude/skills/)Each skill is a self-contained
skill.mdwith frontmatter (name,descriptionwith TRIGGER conditions). All reference.claude/skills.mdas the canonical convention doc — they don't duplicate it.code-review/+references/gotchas.mdunwrap()onOption::None(packet_id panic class), dropped oneshot replies, missing Zustandreset(), hardcoded colors, missing i18n keys in one of en/ko/uzverify/cargo check/clippy/fmt/test+eslint/prettier/yarn builddebug-coremq/coremq-guide/new-backend-feature/web-page/Lockstep version alignment
client/package.json:3.0.0→0.1.0to matchserver/coremq-server/Cargo.toml.The
3.0.0was template-inherited (likely from a Minimals/Sneat MUI starter) and did not reflect project history. Aligning to0.1.0is the more honest direction. If you'd rather bumpCargo.tomlto3.0.0instead, just say so before merging — single-line flip.Test plan
cat AGENTS.md CONTRIBUTING.md CHANGELOG.md— read for tone, accuracy, and broken claims (paths, port numbers, conventions).ls .claude/skills/— confirm six skill folders all present.git diff main -- .gitignore— verify only the markdown whitelist changed.cd client && jq -r .version package.jsonshould print0.1.0.server/**/*.rs,client/src/**) are touched — confirm viagit diff --stat main.Notes
.claude/skills.mdassume the existing project guide stays where it is — no plan to rename it.web-pageshould also cover route registration inroutes/), happy to adjust before or after merge.Summary by CodeRabbit
Documentation
Chores