guid.foo / storied
A 5e storytelling engine with an LLM DM
Star
Fork 0
Watch
storied plans
2 folders · 4 files
completed
rejected
0000-roadmap.md
0012-the-archivist.md
0013-the-aside.md
README.md
README.md

Plans #

This directory holds our designs, plans, and decisions. If you want to know why Storied is the way it is, read these files in order.

How it works #

A plan starts as NNNN-slug.md in this directory. While it is here, it is active, and we edit it freely as we build and learn.

  • plans/*.md is what we are working on or about to start.
  • plans/completed/ is where a plan goes when the work ships. It moves unchanged. From that moment it is a record of what we decided and why.
  • plans/rejected/ is where a plan goes when we bail on it. It gets a short note at the top saying why. Rejected plans are some of the most useful files in a repo, so we keep every one.

Numbers never get reused, and a plan keeps its number when it moves. That way "see 0003" always means the same thing.

How we work together #

  • Design first. We talk an idea through before any code exists. The plan gets written, Chris signs off, then we build. After the plan is written, we add it to the roadmap in 0000-roadmap.md under its own number. The roadmap is keyed by plan number and listed in build order; a plan number is the order the plan was written, not a phase ordinal, so a plan written ahead of its phase does not renumber anything.
  • Small pieces. We build in phases, and every phase ends with something you can actually run. We do not spend months on foundations with nothing to show for it.
  • Stub the future lightly. A phase we have not started yet gets a paragraph, not a spec. We write the real plan when we are about to build it, using what we learned from the phases before it.
  • Pick tools at the last minute. No plan names a library, crate, or dependency until the phase that needs it is being designed. Picking early means guessing, and then bending the design around the guess.
  • Chris steers the experience. How the game feels at the terminal is the whole point, so UX decisions get made together, in small steps, not delivered in bulk at the end.
  • No time estimates. This is a side project, and nobody here is any good at guessing dates anyway. Plans say what and why, never how long.

How to write one #

Write plans like you are explaining an idea to a friend, not presenting at an architecture review. Short, plain, and fun to read. If a plan starts to sound like an RFC, rewrite it.