Add comprehensive skill documentation for Grove ecosystem#3
Add comprehensive skill documentation for Grove ecosystem#3AutumnsGrove merged 2 commits intomainfrom
Conversation
- Added 8 new Claude Code skills (grove-documentation, grove-spec-writing, grove-testing, grove-ui-design, heartwood-auth, museum-documentation, npm-publish, walking-through-the-grove) - Updated AGENT.md with new sections: Pull Requests, Authentication, Grove-related skills - Updated TODO Management to mention COMPLETED.md - Synced all existing skills from BaseProject - AgentUsage/ documentation already up to date - .gitignore already contains all BaseProject entries
Greptile SummaryThis PR establishes comprehensive documentation standards for the Grove ecosystem through four new skill files. The skills cover voice guidelines ( The skills provide valuable structure with excellent examples, ASCII art standards, color palette documentation, and testing philosophies. Cross-references between skills create a cohesive system. Critical Issue: All four main Grove skills violate their own em-dash guideline. The
This inconsistency undermines the authority of the voice guidelines and needs correction before merge. Confidence Score: 3/5
|
| Filename | Overview |
|---|---|
| .claude/skills/grove-documentation/SKILL.md | Comprehensive voice guide with strong principles, but violates its own em-dash rule (12 uses vs 2 max allowed) |
| .claude/skills/grove-spec-writing/SKILL.md | Excellent spec structure guide with ASCII art examples, but significantly overuses em-dashes (20 uses vs 1 max) |
| .claude/skills/grove-testing/SKILL.md | Strong testing philosophy with Testing Trophy approach, but overuses em-dashes (19 uses vs 2 max) |
| .claude/skills/grove-ui-design/SKILL.md | Comprehensive UI design system with color palettes and components, but heavily overuses em-dashes (33 uses vs 4 max) |
Sequence Diagram
sequenceDiagram
participant Dev as Developer
participant Agent as Claude Agent
participant Skills as Skill System
participant Output as Documentation/Code
Dev->>Agent: Request: "Write help article for Grove"
Agent->>Skills: Activate grove-documentation skill
Skills-->>Agent: Load voice guidelines, terminology, avoid-lists
Agent->>Agent: Check for em-dashes, AI patterns, "not X but Y"
Agent->>Agent: Apply Wanderer/Rooted terminology
Agent->>Agent: Use short paragraphs, natural transitions
Agent->>Output: Generate help article content
Output-->>Dev: Warm, authentic Grove voice
Note over Agent,Skills: Same workflow for specs, tests, UI
Dev->>Agent: Request: "Create technical spec"
Agent->>Skills: Activate grove-spec-writing skill
Skills-->>Agent: Load ASCII art patterns, frontmatter format
Agent->>Skills: Reference grove-documentation for voice
Skills-->>Agent: Apply voice principles to spec text
Agent->>Output: Generate spec with diagrams + Grove voice
Output-->>Dev: Storybook-style technical spec
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
|
||
| ### Em-Dashes | ||
|
|
||
| **Avoid em-dashes (—).** One tasteful use per thousand words, maximum. Use commas, periods, or parentheses instead. |
There was a problem hiding this comment.
logic: Em-dash guideline violated throughout file
The file states "Avoid em-dashes (—). One tasteful use per thousand words, maximum" but contains 12 em-dashes in 2,311 words (should have max 2).
Examples of violations:
- Line 25: "voice—warm, introspective"
- Line 101: "forest—our home—is where"
- Line 142: "So," "Still." Or no transition at all—just start"
Replace with commas, periods, or parentheses per the guideline.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Prompt To Fix With AI
This is a comment left during a code review.
Path: .claude/skills/grove-documentation/SKILL.md
Line: 99:99
Comment:
**logic:** Em-dash guideline violated throughout file
The file states "Avoid em-dashes (—). One tasteful use per thousand words, maximum" but contains 12 em-dashes in 2,311 words (should have max 2).
Examples of violations:
- Line 25: "voice—warm, introspective"
- Line 101: "forest—our home—is where"
- Line 142: "So," "Still." Or no transition at all—just start"
Replace with commas, periods, or parentheses per the guideline.
<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>
How can I resolve this? If you propose a fix, please make it concise.| - `tech-spec` — Technical specification (most common) | ||
| - `implementation-plan` — Step-by-step implementation guide | ||
| - `index` — Index/navigation document |
There was a problem hiding this comment.
logic: Em-dash overuse violates grove-documentation guideline
File contains 20 em-dashes in 1,493 words (should have max 1-2 per the "one per thousand words" rule from grove-documentation).
Examples:
- Line 58:
tech-spec — Technical specification - Line 59:
implementation-plan — Step-by-step - Line 160:
Architecture — How it's built
Replace with colons, commas, or restructure without em-dashes.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Prompt To Fix With AI
This is a comment left during a code review.
Path: .claude/skills/grove-spec-writing/SKILL.md
Line: 58:60
Comment:
**logic:** Em-dash overuse violates grove-documentation guideline
File contains 20 em-dashes in 1,493 words (should have max 1-2 per the "one per thousand words" rule from `grove-documentation`).
Examples:
- Line 58: `tech-spec — Technical specification`
- Line 59: `implementation-plan — Step-by-step`
- Line 160: `Architecture — How it's built`
Replace with colons, commas, or restructure without em-dashes.
<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>
How can I resolve this? If you propose a fix, please make it concise.| > — Guillermo Rauch | ||
|
|
||
| This captures everything Grove believes about testing: | ||
|
|
||
| **Write tests** — Automated tests are worthwhile. They enable confident refactoring, serve as documentation, and catch regressions before users do. | ||
|
|
||
| **Not too many** — Tests have diminishing returns. The goal isn't coverage numbers. It's confidence. When you feel confident shipping, you have enough tests. | ||
|
|
||
| **Mostly integration** — Integration tests catch real problems without being brittle. They test behavior users actually experience, not internal implementation. |
There was a problem hiding this comment.
logic: Em-dash overuse contradicts Grove voice standards
File contains 19 em-dashes in 1,819 words (should have max 2). Grove documentation skill specifies "one tasteful use per thousand words, maximum."
Examples in this section alone:
- Line 29:
worthwhile. They enable - Line 31:
numbers. It's confidence - Line 33:
brittle. They test
Replace em-dashes with periods, commas, or restructure sentences.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Prompt To Fix With AI
This is a comment left during a code review.
Path: .claude/skills/grove-testing/SKILL.md
Line: 25:33
Comment:
**logic:** Em-dash overuse contradicts Grove voice standards
File contains 19 em-dashes in 1,819 words (should have max 2). Grove documentation skill specifies "one tasteful use per thousand words, maximum."
Examples in this section alone:
- Line 29: `worthwhile. They enable`
- Line 31: `numbers. It's confidence`
- Line 33: `brittle. They test`
Replace em-dashes with periods, commas, or restructure sentences.
<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>
How can I resolve this? If you propose a fix, please make it concise.| - **Welcoming** — like entering a cozy space | ||
| - **Organic** — natural, not rigid or corporate | ||
| - **Readable** — content-first, decorations enhance, never obstruct | ||
| - **Alive** — subtle animations, seasonal changes, randomization |
There was a problem hiding this comment.
logic: Excessive em-dash usage (33 in 4,202 words)
Grove documentation standard allows "one tasteful use per thousand words, maximum" (should be ~4 max here, actual count is 33).
Examples throughout:
- Line 32:
Welcoming — like entering - Line 33:
Organic — natural, not rigid - Line 159:
Overview/Goals — What this system - Line 737:
Consistency — Icons match
Replace with colons, commas, periods, or parentheses to align with Grove voice principles.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Prompt To Fix With AI
This is a comment left during a code review.
Path: .claude/skills/grove-ui-design/SKILL.md
Line: 32:35
Comment:
**logic:** Excessive em-dash usage (33 in 4,202 words)
Grove documentation standard allows "one tasteful use per thousand words, maximum" (should be ~4 max here, actual count is 33).
Examples throughout:
- Line 32: `Welcoming — like entering`
- Line 33: `Organic — natural, not rigid`
- Line 159: `Overview/Goals — What this system`
- Line 737: `Consistency — Icons match`
Replace with colons, commas, periods, or parentheses to align with Grove voice principles.
<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>
How can I resolve this? If you propose a fix, please make it concise.2 participants
Summary
This PR introduces four new skill documentation files that establish standards and best practices for writing in the Grove ecosystem. These skills provide guidance for documentation, specifications, testing, and UI design work across the project.
Changes
grove-documentation.md — Comprehensive guide for writing user-facing text in the authentic Grove voice. Covers tone, terminology (Wanderer, Rooted, Pathfinder, Wayfinder), strict avoidances (em-dashes, AI patterns), structural guidelines, error messages, and queer-friendly language principles.
grove-spec-writing.md — Technical specification standards treating specs as "storybook entries." Includes required frontmatter format, ASCII art header requirements, mandatory visual elements (flow diagrams, UI mockups, state diagrams), validation checklist, and complete examples.
grove-testing.md — Testing philosophy and strategy guide emphasizing the Testing Trophy approach (mostly integration tests, some unit tests, few E2E tests). Covers what to test, anti-patterns, the bug-to-test pipeline, and decision frameworks for test coverage.
grove-ui-design.md — UI design system documentation covering component patterns, accessibility standards, design tokens, and integration with other Grove skills.
Key Features
Implementation Notes
.claude/skills/directory following Claude's skill documentation format