From 11e057b09e526b5e79d8428bcc91031f4c6da57c Mon Sep 17 00:00:00 2001 From: Aaron Wood Date: Sat, 11 Apr 2026 16:23:20 -0400 Subject: [PATCH] docs: add handbook and changelog design spec --- .../2026-04-11-handbook-changelog-design.md | 169 ++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-11-handbook-changelog-design.md diff --git a/docs/superpowers/specs/2026-04-11-handbook-changelog-design.md b/docs/superpowers/specs/2026-04-11-handbook-changelog-design.md new file mode 100644 index 0000000..bf065db --- /dev/null +++ b/docs/superpowers/specs/2026-04-11-handbook-changelog-design.md @@ -0,0 +1,169 @@ +# Handbook & Changelog — Design Spec + +Last updated: 2026-04-11 + +--- + +## Goal + +Two reference documents and two maintenance skills: + +1. **`CHANGELOG.md`** — version history at the repo root; updated every time a feature ships or a bug is fixed +2. **`docs/HANDBOOK.md`** — single-file project reference for all collaborators; two sections: product overview (RPG-first) and technical guide (developer-first) +3. **`update-changelog` skill** — helps write new changelog entries in the right format when features change +4. **`update-handbook` skill** — helps update the handbook when features are added, changed, or removed + +--- + +## CHANGELOG.md + +### Location + +Repo root: `CHANGELOG.md` + +### Format + +[Keep a Changelog](https://keepachangelog.com) format with [Semantic Versioning](https://semver.org). + +```markdown +# Changelog + +All notable changes to Darkwatch will be documented here. +Format: [Keep a Changelog](https://keepachangelog.com) +Versioning: [Semantic Versioning](https://semver.org) + +## [Unreleased] + +## [0.1.0] - 2026-04-11 +### Added +- ...features... +``` + +### Versioning convention + +- **Patch** (0.1.x): bug fixes, minor UI polish, no new features +- **Minor** (0.x.0): new features or meaningful enhancements +- **Major** (x.0.0): breaking changes or significant redesigns (rare) + +### Initial v0.1.0 entry + +Groups all currently shipped features under `### Added`: + +- Auth — email/password, JWT httpOnly cookies, register/login/logout +- Campaign management — CRUD, real-time sync via Socket.IO, invite links, DM/player roles +- Character system — stats, gear, talents, HP, XP, currency, auto-calculated AC and attacks +- Talent effects — stat bonuses, AC, attack/damage, gear slots, HP scaling +- Character creation wizard — 4-step modal (name/class/ancestry → stat rolling → background/alignment/deity → review) +- Spellcasting — 34 Tier 1–2 spells, 1d20 cast checks, exhaustion, Wizard mishap table, Priest penance, rest recovery +- 3D dice rolling — predetermined outcomes, character-colored dice, delayed roll log, advantage/disadvantage +- Torch timer — 60-min countdown, synced across clients +- Luck tokens +- DiceBear avatars with style picker +- Per-character color picker +- Atmosphere panel — fog, fire, rain, embers; DM-only, synced via socket +- Initiative tracker — team-based Shadowdark initiative (rolling phase, active phase), enemy HP tracking (DM-only), add/remove enemies mid-combat, DB-persisted +- Compact DM character cards — 3-up grid, HP/AC/luck/torch/modifiers +- Mobile layout — full-screen sheet, long-press adv/dis, roll log drawer +- Medieval visual theme — Cinzel + Alegreya, parchment, gold, color schemes +- MariaDB migration — replaced SQLite with MariaDB 11 in Docker + +--- + +## docs/HANDBOOK.md + +### Location + +`docs/HANDBOOK.md` — a single file with a top-level table of contents linking to both parts. + +### Structure + +``` +# Darkwatch Handbook + +## Table of Contents +- [Part 1: Product Overview](#part-1-product-overview) +- [Part 2: Technical Guide](#part-2-technical-guide) + +--- + +# Part 1: Product Overview + +## What is Darkwatch? +## Who is it for? +## How a session works +## Features + ### Characters + ### Dice Rolling + ### Spellcasting + ### Torch Timer & Luck Tokens + ### Atmosphere Effects + ### Initiative Tracker + ### DM Tools +## What's Coming Next +## Known Limitations + +--- + +# Part 2: Technical Guide + +## Stack +## Running Locally +## Repo Structure +## Key Patterns + ### Socket events + ### CSS Modules & variables + ### Database migrations + ### Auth & roles +## Development Workflow + ### Brainstorm → Spec → Plan → Implement + ### Specs and plans: docs/superpowers/ +## Roadmap +``` + +### Part 1 tone + +Written for someone who plays or runs TTRPGs. Explains what Darkwatch does and why, without assuming any coding knowledge. Feature descriptions focus on what the DM or player experiences, not how it's implemented. + +### Part 2 tone + +Written for a developer joining the project. Assumes familiarity with Node/React but not with this specific codebase. Covers how to get running locally, where things live, and how we work (the spec/plan/implement loop). + +--- + +## Maintenance Skills + +Both skills are project-local markdown files stored in `.claude/skills/` at the repo root. + +### `update-changelog` skill + +**Trigger:** Invoked after a feature ships, bug is fixed, or feature is removed. + +**Behavior:** +1. Read `CHANGELOG.md` to find the current version +2. Read recent git commits and/or `docs/ROADMAP.md` for context on what changed +3. Determine the appropriate version bump (patch/minor) based on the nature of the change +4. Write a new versioned entry above the previous one, using the correct section headers (`Added`, `Changed`, `Fixed`, `Removed`, `Security`) +5. Commit `CHANGELOG.md` + +**Invocation:** Via the `Skill` tool as a project-local skill. Exact storage path (`.claude/skills/` or similar) to be confirmed during implementation based on Claude Code's project-local skill conventions. + +### `update-handbook` skill + +**Trigger:** Invoked after a feature is added, changed, or removed. + +**Behavior:** +1. Read `docs/HANDBOOK.md` +2. Identify which sections are affected (Part 1 features, Part 2 patterns, etc.) +3. Update those sections to reflect the current state +4. Commit `docs/HANDBOOK.md` + +**Scope:** The skill updates prose and feature lists. It does not manage screenshots (those are manual). + +--- + +## Out of Scope + +- Screenshots in the handbook (added manually, not by the skill) +- A separate marketing site (separate project, separate spec) +- GitHub wiki or any external hosting for these docs +- Automated changelog generation from git commits (we write entries intentionally, not mechanically)