Write and validate Grove technical specifications with consistent formatting, ASCII art headers, diagrams, and the Grove voice. Use when creating new specs, reviewing existing specs for completeness, or standardizing spec formatting.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Write and validate Grove technical specifications with consistent formatting, ASCII art headers, diagrams, and the Grove voice. Use when creating new specs, reviewing existing specs for completeness, or standardizing spec formatting.
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-categorytype:tech-spec---
โญโโโโโโโโโโโฎ
โญโโโ โญโโโโโโโฎ โโโโฎ
โญโโ โ โ โญโโโฎ โ โ โโโฎ
โ โ โ โ โโฅ โ โ โ โ โ
โฐโโ โ โ โฐโโโฏ โ โ โโโฏ
โฐโโโ โฐโโโโโโโฏ โโโโฏ
โฐโโโโโโโโโโโฏ
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]
---
4. 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 โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
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 owl-archive/references/anti-patterns.md for the full list)
No em-dashes (use periods or commas)
No "not X, but Y" patterns or variants ("Not X. Not Y. Just Z.", "The X? A Y.")
No AI-coded words (robust, seamless, leverage, delve, utilize, streamline, etc.)
No "serves as" / "stands as" / "marks a". Use simple verbs
No filler transitions (Furthermore, Moreover, It's worth noting, Notably)
No gerund fragment litanies or bold-first bullet patterns
No false suspense ("Here's the kicker", "Here's the thing")
No dead metaphors (same metaphor repeated in every section)
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
---
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
> *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.
