Grove Spec Writing A comprehensive guide for writing technical specifications in the Grove ecosystem. Use this skill to create new specs that feel like storybook entries, or to validate and standardize existing specs. When to Activate Creating a new technical specification Reviewing an existing spec for completeness Adding ASCII art headers to specs missing them Adding diagrams, mockups, or visual elements to text-heavy specs Standardizing frontmatter across spec files Validating a spec against Grove standards before finalizing The Spec as Storybook Entry Grove specs aren't just technical documents. They're storybook entries in a larger narrative. Each spec should feel like opening a page in a beautifully illustrated field guide to the forest. The formula: Cover page (frontmatter + ASCII art + tagline) Introduction (what is this, in nature and in Grove) The journey (architecture, flows, implementation) The details (API, schema, security) The path forward (implementation checklist) Required Structure 1. Frontmatter (REQUIRED) Every spec MUST have this exact frontmatter format:

aliases : [ ] date created : [ Day ] , [ Month ] [ Ordinal ] [ Year ] date modified : [ Day ] , [ Month ] [ Ordinal ] [ Year ] tags : - primary - domain - tech - stack - category type : tech - spec

Date format examples: Monday, December 29th 2025 Saturday, January 4th 2026 Type options: tech-spec — Technical specification (most common) implementation-plan — Step-by-step implementation guide index — Index/navigation document 2. ASCII Art Header (REQUIRED) Immediately after frontmatter, include a code block with ASCII art that visually represents the concept:

[Name] — [Short Description]

ASCII ART HERE representing the concept in a visual way

Poetic tagline in italics Good ASCII art: Relates to the nature metaphor (forest, garden, etc.) Represents the concept visually (layers for backup, rings for analytics) Uses box-drawing characters: ─│┌┐└┘├┤┬┴┼╭╮╰╯ Uses nature emoji sparingly: 🌲🌿🍂✨🌸 Includes a poetic tagline or motto Examples from excellent specs: Wisp (will-o'-the-wisp light): 🌲 🌲 🌲 \ | / \ | / ✨ ╱ ╲ ╱ ╲ ╱ · ╲ ╱ · ╲ ╱ · ╲ · · · gentle guiding light Patina (layered backups): ╭───────────────────╮ ╭┤ ┌─────────────┐ ├╮ ╭┤│ │ 2026-01-05 │ │├╮ │││ │ ▓▓▓▓▓▓▓▓▓▓ │ │││ │││ │ ▒▒▒▒▒▒▒▒▒▒ │ │││ │││ │ ░░░░░░░░░░ │ │││ │││ │ ·········· │ │││ ╰┴┴──└─────────────┘──┴┴╯ ╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱ ────────────────────────────── ~~~~~~~~ oxidation layer ~~~~~~~~ Age as armor. Time as protection. Heartwood (tree rings): ╭──────────╮ ╭──│ ╭──────╮ │──╮ ╭─│ │ │ ╭──╮ │ │ │─╮ │ │ │ │ │♥ │ │ │ │ │ ╰─│ │ │ ╰──╯ │ │ │─╯ ╰──│ ╰──────╯ │──╯ ╰──────────╯ every ring: a year, a story, a layer of growth The center that holds it all. 3. Introduction Section After the ASCII art header:

* Poetic tagline repeated * [2-3 sentence description of what this is in the Grove ecosystem] ** Public Name: ** [Name] ** Internal Name: ** Grove[Name] ** Domain: ** name.grove.place ** Repository: ** [Link if applicable] ** Last Updated: ** [Month Year] [1-2 paragraphs explaining the nature metaphor and how it applies]

1. Body Sections Organize content with clear headers. Include: Overview/Goals — What this system does Architecture — How it's built (with diagrams!) Tech Stack — Dependencies, frameworks API/Schema — Technical details Security — Important considerations Implementation Checklist — Clear action items Required Visual Elements Flow Diagrams Every spec describing a process MUST include at least one ASCII flow diagram: ┌─────────────────────────────────────────────────────────────────────┐ │ Client Sites │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Site A │ │ Site B │ │ Site C │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ └─────────┼─────────────────┼─────────────────┼───────────────────────┘ │ │ │ │ 1. Request │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ Central Service │ │ │ │ ┌─────────────────────────┐ ┌─────────────────────────┐ │ │ │ Handler A │ │ Handler B │ │ │ └─────────────────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ Box drawing reference: Corners: ┌ ┐ └ ┘ (square) or ╭ ╮ ╰ ╯ (rounded) Lines: ─ │ ═ ║ Joins: ├ ┤ ┬ ┴ ┼ Arrows: → ← ↑ ↓ ▶ ◀ ▲ ▼ UI Mockups Specs describing user interfaces MUST include ASCII mockups: ┌─────────────────────────────────────────────────────────────────┐ │ ✧ Panel Title [×] │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─ Label ────────────────────────────────────────────────┐ │ │ │ Content here with proper spacing │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Input field... [↵] │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ ─────────────────────────────────────────────────────────── │ │ [ Action A ] [ Action B ✦ ] │ │ │ └─────────────────────────────────────────────────────────────────┘ State Diagrams For features with multiple states: Idle: Analyzing: Success: . * . . * . * . analyzing . * * . _ . . \ | / . * /|\ . / \ * . -- (o.o) -- thinking * / | \ * / ~ ~ \ . . / | \ /|\ / ______ ~~~~~~~~~~~~~~~~~ ~~~~/ \~~~~ ~~~~~~~~~~~~~~~~~~~ words flowing... all clear Comparison Tables Use tables to compare options, states, or configurations: | Feature | Seedling | Sapling | Oak | Evergreen | |

|

|

|

|

| | Posts | 50 | 250 | ∞ | ∞ | | Storage | 1 GB | 5 GB | 20 GB | 100 GB | | Themes | 3 | 10 | All | All + custom | Timeline/Retention Diagrams For anything involving time: TODAY 12 WEEKS AGO │ │ ▼ ▼ ┌─┬─┬─┬─┬─┬─┬─┐ ┌─┐ │█│█│█│█│█│█│█│ ◀── Daily backups (7 days) │░│ └─┴─┴─┴─┴─┴─┴─┘ └─┘ S M T W T F S Validation Checklist Before finalizing any spec, verify: Structure Frontmatter present with all required fields aliases: [] included (even if empty) Date format correct (Day, Month Ordinal Year) type: tech-spec or appropriate type ASCII art header present after frontmatter Poetic tagline in italics Public/Internal names listed Domain specified (if applicable) Visual Content At least one ASCII flow diagram (if process-based) UI mockups included (if describing interface) Tables for comparisons where appropriate Code blocks for technical details No walls of text without visual breaks Voice (refer to grove-documentation skill) No em-dashes (use periods or commas) No "not X, but Y" patterns No AI-coded words (robust, seamless, leverage, etc.) Short paragraphs Poetic closers earned, not forced Completeness Overview/Goals section Architecture diagram Technical details (API, schema) Security considerations Implementation checklist Creating ASCII Art The Process Identify the core metaphor — What natural thing does this represent? Sketch the concept — What visual would convey this at a glance? Choose your characters — Box drawing, emoji, or creative ASCII Build in layers — Start with outline, add detail, add flourishes Add the tagline — Poetic one-liner that captures the essence Character Palette Box Drawing (safe, consistent): ┌─────┬─────┐ ╭─────╮ │ │ │ │ │ ├─────┼─────┤ ╰─────╯ │ │ │ └─────┴─────┘ Lines and Arrows: → ← ↑ ↓ ↔ ↕ ▶ ◀ ▲ ▼ ⟿ ⟸ ⟹ Nature Emoji (use sparingly): 🌲 🌳 🌿 🍂 🍃 🌸 🌺 🌻 🌷 🌱 🍄 ☀️ 🌤️ ⭐ ✨ 💧 🔥 🦋 🐛 🐌 Decorative: · ∙ • ° ˚ ∘ ~ ≈ ∿ ═ ║ ╔ ╗ ╚ ╝ ░ ▒ ▓ █ Tips Keep ASCII art under 20 lines tall Center the art within its code block Include breathing room (empty lines above/below) Test in a monospace font Consider mobile rendering (simpler is better) Example: Complete Spec Header

aliases : [ ] date created : Monday , January 6th 2026 date modified : Monday , January 13th 2026 tags : - support - user - communication - cloudflare - workers type : tech - spec

Porch — Support System 🏠 │ │ │ ~~~~~~│ PORCH │~~~~~~ ╱│_│╲ ╱ ╲ ╱ ┌───┐ ╲ ╱ │ ☕ │ ╲ ╱ └───┘ 👤 ╲ ════════════════════════ steps Have a seat. We'll figure it out.

Have a seat on the porch. We'll figure it out together. Grove's front porch: a warm, accessible space where users sit down and have a conversation. Not a corporate help desk with ticket numbers. A porch where you chat with the grove keeper about what's going on. Public Name: Porch Internal Name: GrovePorch Domain: porch.grove.place Status: Planned (Launch Priority) A porch is where you sit and talk. You come up the steps, have a seat, and the grove keeper comes out to chat. It's not a ticket counter. It's two people on a porch, figuring things out together.

Integration with Other Skills

Before Writing a Spec

walking-through-the-grove

— If naming a new feature, complete the naming journey first

grove-ui-design

— If the spec involves UI, understand design patterns

While Writing

grove-documentation

— Apply Grove voice throughout, avoid AI patterns

After Writing

grove-spec-writing

(this skill) — Run validation checklist

Review with fresh eyes: Does it feel like a storybook entry?

When to Use museum-documentation Instead

This skill (grove-spec-writing) is for

internal technical specifications

architecture decisions, system design, implementation plans. Documentation for developers. Use museum-documentation when writing for Wanderers who want to understand : Use grove-spec-writing Use museum-documentation Technical specifications "How it works" for curious visitors Architecture decisions Codebase guided tours Implementation plans Knowledge base exhibits Internal system docs Narrative technical explanations If the reader is a developer implementing something , use this skill. If the reader is a Wanderer exploring the forest , use museum-documentation. Quick Reference Element Required Location Frontmatter Yes Top of file ASCII art header Yes After frontmatter Poetic tagline Yes After ASCII art Public/Internal names Yes Introduction Architecture diagram If applicable Body UI mockups If has UI Body Implementation checklist Yes End of spec A good spec is one you'd want to read at 2 AM. Make it beautiful.