feat(docs): add generated AGENT.md and improve README.md #106
Conversation
WalkthroughA new documentation file, AGENT.md, was added to provide comprehensive guidance for AI agents and contributors, detailing repository structure, development commands, code architecture, and standards. README.md was extensively rewritten to reorganise and expand documentation, offering a more detailed and structured overview of package features, usage, and conventions. Changes
Possibly related PRs
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
|
Here's the code health analysis summary for commits Analysis Summary
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
AGENT.md (2)
38-39: Add missing article for clarityThe phrase should read “Only the Go standard library and minimal golang.org/x packages” to improve readability.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~38-~38: You might be missing the article “the” here.
Context: ...inciples - Zero dependencies: Only Go standard library and minimal golang.org...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
72-72: Add missing punctuationAdd a period at the end of this bullet to maintain consistency with other list items.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~72-~72: A period might be missing here.
Context: ...nsive coverage for generic functions is expected ## Important Notes - Go 1.22 is the m...(AI_EN_LECTOR_MISSING_PUNCTUATION_PERIOD)
README.md (2)
71-72: Add missing article for clarityChange “converts value using provided function” to “converts value using a provided function” for improved readability.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~72-~72: You might be missing the article “a” here.
Context: ...AsFn[T,V](v, fn)converts value using provided function *AsError[T](v)attempts to ...(AI_EN_LECTOR_MISSING_DETERMINER_A)
234-234: Hyphenate modifier for consistencyChange “capture specific stack frame” to “capture-specific stack frame” to match compound modifier style.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~234-~234: When ‘capture-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...rent stack frame *StackFrame(skip)- capture specific stack frame *StackTrace(skip, depth)...(SPECIFIC_HYPHEN)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
AGENT.md(1 hunks)README.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
AGENT.md
[uncategorized] ~38-~38: You might be missing the article “the” here.
Context: ...inciples - Zero dependencies: Only Go standard library and minimal golang.org...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~72-~72: A period might be missing here.
Context: ...nsive coverage for generic functions is expected ## Important Notes - Go 1.22 is the m...
(AI_EN_LECTOR_MISSING_PUNCTUATION_PERIOD)
README.md
[uncategorized] ~72-~72: You might be missing the article “a” here.
Context: ...AsFn[T,V](v, fn) converts value using provided function * AsError[T](v) attempts to ...
(AI_EN_LECTOR_MISSING_DETERMINER_A)
[uncategorized] ~234-~234: When ‘capture-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...rent stack frame * StackFrame(skip) - capture specific stack frame * StackTrace(skip, depth)...
(SPECIFIC_HYPHEN)
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (8)
AGENT.md (8)
3-4: Clarify file purpose and linkage.Consider adding a brief note or link to
README.mdfor developers and AI agents to get high-level context before diving into AGENT.md.
12-32: Add prerequisite setup steps.It may be helpful to include initial environment setup instructions (e.g. installing Go, setting
$GOPATH, and ensuringmakeis available) before running these commands.
38-43: Consistent punctuation in bullet list.For consistency, end each bullet item with a full stop. For example, change:
- **Zero dependencies**: Only the Go standard library and minimal golang.org/x packagesto
- **Zero dependencies**: Only the Go standard library and minimal golang.org/x packages.
56-66: Link to revive configuration.Consider adding a reference or path to the actual
reviveconfig file (e.g..revive.toml) so contributors know where to inspect or modify the enforced rules.
80-81: Capitalise JavaScript/TypeScript.Ensure proper casing for the tool names:
- Always use `pnpm` instead of `npm` for any JavaScript/TypeScript tooling.
88-91: Capitalise Markdown for consistency.Change:
- **Markdownlint**: Follow standard markdown formatting rulesto
- **Markdownlint**: Follow standard Markdown formatting rules.🧰 Tools
🪛 LanguageTool
[grammar] ~90-~90: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...ers - Markdownlint: Follow standard markdown formatting rules ### Common Documentat...(MARKDOWN_NNP)
102-105: Ensure punctuation in examples.Add full stops at the end of example list items to align with documentation standards:
- ❌ "capture specific stack frame" - ✅ "capture-specific stack frame."
106-112: Extend pre-commit checklist.Add an item to remind contributors to update this
AGENT.mdwhen documentation conventions or code architecture change:5. Update `AGENT.md` to reflect any changes in development workflow or standards.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
AGENT.md(1 hunks)README.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- README.md
🧰 Additional context used
🪛 LanguageTool
AGENT.md
[grammar] ~90-~90: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...ers - Markdownlint: Follow standard markdown formatting rules ### Common Documentat...
(MARKDOWN_NNP)
🔇 Additional comments (1)
AGENT.md (1)
1-112: Excellent addition.AGENT.md offers a thorough and well-structured guide for AI agents. With the above minor refinements, it will be even clearer and more consistent.
🧰 Tools
🪛 LanguageTool
[grammar] ~90-~90: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...ers - Markdownlint: Follow standard markdown formatting rules ### Common Documentat...(MARKDOWN_NNP)
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (8)
AGENT.md (8)
17-21: Ensure consistent punctuation in prerequisites
According to the documented standards, all bullet points should end with a full stop. Please add a full stop at the end of each item in this prerequisites list.
56-65: Add full stops to major components list
Each bullet under “Major Components” should end with a period to comply with the markdown style guidelines for consistency.
67-78: Code quality standards bullets need trailing full stops
All linting rules listed under “Code Quality Standards” must finish with a full stop for consistency across documentation.
80-84: Complete testing patterns bullets with full stops
Please ensure that each item in the “Testing Patterns” list ends with a full stop in line with the project’s documentation standards.
85-92: Important Notes list requires punctuation consistency
The bullet items under “Important Notes” should conclude with a full stop to maintain uniform styling.
103-112: Standardise punctuation in common documentation issues
Numbered and nested list items in “Common Documentation Issues to Check” should all end with full stops.
117-135: Writing guidelines bullets need trailing full stops
For “Writing Documentation Guidelines,” each bullet point should end with a full stop to adhere to Markdown style rules.
141-149: Pre-commit checklist items should end with full stops
To keep consistency across all lists, add a full stop to the end of each checklist item.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
AGENT.md(1 hunks)README.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- README.md
🔇 Additional comments (4)
AGENT.md (4)
1-6: Introductory section is clear and links appropriately
The opening heading and pointer to README.md correctly guide both AI agents and human developers.
24-43: Development commands block looks good
Thebashcode fence and listedmaketargets comprehensively cover common workflows and are formatted correctly.
46-53: Code architecture section is well-structured
The design principles are clearly outlined and aligned with project conventions.
94-102: Documentation standards section is solid
The guidance on LanguageTool and markdownlint checks is accurate and aligns with project requirements.
Signed-off-by: Alejandro Mery <amery@apply.co>
Signed-off-by: Alejandro Mery <amery@apply.co>
Summary by CodeRabbit