README

Roadmap — How It Works

Structure

roadmap/
  ROADMAP.md                          # high-level milestones (stakeholder view)
  dashboard.md                        # Dataview queries (local Obsidian only)
  items/
    auth-module/
      auth-module.md                  # work item spec
      assets/                         # screenshots, mockups, diagrams
        login-flow-sketch.png
    drill-builder/
      drill-builder.md
      assets/
        mockup-v1.png
        mockup-v2.png

Each work item is a folder containing a markdown spec and an assets/ subfolder for screenshots, mockups, and diagrams. Simple items may have no assets folder — just the markdown file.

Work Item Template

Every work item uses this frontmatter and structure:

---
status: draft | ready | in-progress | review | done
priority: high | medium | low
milestone: mvp | post-mvp | future
depends: []                         # list of work item folder names, omit if none
tags: [server, auth]
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
# Title
 
## Summary
One-paragraph description of what this work item delivers.
 
## Context
Why this matters. Link to relevant architecture docs.
 
## Requirements
What needs to be true when this is done:
- Requirement 1
- Requirement 2
 
## Details
Extended description — behavior, edge cases, constraints, API surface.
As detailed or as rough as the current iteration allows.
 
## Assets
Inline screenshots and mockups:
![[mockup-v2.png]]
 
## Iteration Notes
Running log of changes as the spec is refined:
**YYYY-MM-DD** — what changed and why
 
## Open Questions
- [ ] Unanswered question
- [ ] Decision not yet made

Status Flow

draft → ready → in-progress → review → done

Status	Meaning
draft	Still iterating — adding screenshots, refining requirements. Not ready for implementation.
ready	Spec is clear enough to hand to an AI agent and say “build this.”
in-progress	Actively being implemented.
review	Built, needs testing or human review.
done	Shipped. Item stays in place as a record.

AI Agent Instructions

When working with roadmap items, follow these rules:

Reading a Work Item

1. Read the frontmatter to understand status, scope, and priority.
2. Read Summary and Requirements for the “what.”
3. Read Details for the “how.”
4. View Assets for visual context (screenshots, mockups, diagrams).
5. Check Open Questions before starting — if any are unresolved and relevant to your task, ask the human instead of guessing.
6. Follow links to architecture docs for constraints and design decisions.

Before Implementing

• Only implement items with status ready or in-progress. Never implement a draft item without asking first.
• Check the depends field — if any dependency is not done, flag it to the human before starting. Do not implement a blocked item without explicit approval.
• If requirements are ambiguous, ask for clarification rather than making assumptions.
• If the work item references assets (screenshots, mockups), review them — they may contain details not captured in text.

During Implementation

• Update the item’s status to in-progress in the frontmatter.
• Update the updated date in the frontmatter.
• If implementation reveals new requirements or edge cases, add them to the work item’s Details or Open Questions section.

After Implementation

• Update the item’s status to review.
• Add an Iteration Notes entry describing what was built.
• If the implementation diverged from the spec, update the spec to match reality.

Creating New Work Items

• Create a folder under items/ with a kebab-case name.
• Use the template above.
• Set status to draft unless the human specifies otherwise.
• Create an assets/ subfolder only if there are assets to include.
• Add a link to the item from ROADMAP.md under the appropriate milestone.

Filing Assets

• Screenshots and mockups go in the item’s assets/ folder.
• Name assets descriptively: login-error-message.png, not screenshot-1.png.
• When iterating on mockups, keep previous versions (e.g., mockup-v1.png, mockup-v2.png) and note in Iteration Notes which is current.

Linting (rangeday check docs)

The CLI lints all work items under items/ and reports issues with file paths and line numbers. AI agents should run this after creating or editing work items and work with the human to resolve any issues.

Frontmatter Rules

• Required fields: status, priority, milestone, created, updated
• status must be one of: draft, ready, in-progress, review, done
• priority must be one of: high, medium, low
• milestone must be one of: mvp, post-mvp, future
• depends must be a list of valid work item folder names if present
• tags must be a list if present (not a string). Use the standard tag vocabulary:

Tag Vocabulary

Tag	Scope
core	Shared Rust core crate (libs/core)
server	Server crate (apps/server)
dashboard	Admin web app (apps/dashboard)
pwa	Shooter-facing PWA (apps/pwa)
marketing	Marketing site (apps/marketing)
ios	iOS app only (apps/ios)
android	Android app only (apps/android)
mobile	Both iOS and Android
proto	Protobuf definitions (proto/)
infra	CI/CD, deployment, observability

Tags can be combined: [mobile, core] means the item touches both mobile apps and the core crate. Use mobile when the work is identical on both platforms; use ios or android when it’s platform-specific.

• tags entries must be from the standard tag vocabulary (see table above)
• created and updated must be valid YYYY-MM-DD dates
• updated must be ≥ created

Structure Rules

• Required sections: Summary, Requirements
• Recommended sections: Context, Details, Open Questions (warning, not error)
• Summary must not be empty
• Requirements must contain at least one list item
• Folder naming: kebab-case, matches the markdown filename (e.g., auth-module/auth-module.md)
• Asset references: any ![[image]] must point to a file that exists in the item’s assets/ folder

Dependency Rules

• Each entry in depends must match an existing work item folder name under items/
• A ready or in-progress item cannot depend on an item still in draft (dependency must be at least ready)
• Circular dependencies are flagged as errors (A depends on B, B depends on A)
• A done dependency is always satisfied

Example Output

$ rangeday check docs

docs/roadmap/items/auth-module/auth-module.md
  ✗ frontmatter: missing required field "updated"
  ✗ structure: "Requirements" section is empty (needs at least one list item)
  ⚠ structure: missing recommended section "Open Questions"

docs/roadmap/items/drill-builder/drill-builder.md
  ✗ frontmatter: "status" has invalid value "wip" (expected: draft | ready | in-progress | review | done)
  ✗ assets: referenced image "mockup-v3.png" not found in assets/

docs/roadmap/items/score-dashboard/score-dashboard.md
  ✗ depends: "score-api" is in status "draft" but this item is "ready" (dependency must be at least "ready")
  ✗ depends: "analytics-engine" does not exist as a work item
  ✗ tags: "frontend" is not a valid tag (expected: core | server | dashboard | pwa | marketing | ios | android | mobile | proto | infra)

3 files, 7 errors, 1 warning

Dataview Dashboard (Local Obsidian Only)

The dashboard.md file contains Dataview queries for dynamic views. These only render in Obsidian — stakeholders viewing the published site use ROADMAP.md instead.

Published Site (Quartz)

The Quartz static site renders every work item as a navigable page. Stakeholders can:

• View ROADMAP.md for the high-level milestone overview
• Click any work item link to see the full spec
• View inline screenshots and mockups
• Follow links to architecture docs for context

Dataview queries do not render on the published site. All other content (markdown, images, wikilinks, callouts) renders fully.