livt - Living Text

Collaborate on board. Make it living in text.

Outcome

Collaborative outcomes evolve alongside the product as living text.

Opportunities

• Stale Discovery: Discovery-phase artifacts are not persisted after synchronous collaboration sessions
• Discovery-Development Gap: Persisted discovery artifacts are not leveraged in the development process

Solutions

• Provide a CLI tool that captures collaborative outcomes as text files (YAML, Markdown)
• Track consistency across artifacts via ID-based references with automated checks
• Treat Formulation artifacts (Gherkin scenarios) as generated output, not the source of truth — the master lives in Discovery artifacts

Getting Started

Installation

go install github.com/boykush/livt@latest

Quick Start

1. Create the required directories:

mkdir -p stories discoveries/usm discoveries/example-mappings

2. Create your first story in stories/my-first-story.md:

---
name: My first story
---

As a user
I want to do something
So that I get value

3. Build and serve:

livt serve

4. Open http://localhost:3000 in your browser to view the board.

Stories

Stories are Markdown files with YAML frontmatter, stored in the stories/ directory.

Format

---
name: Story display name
---

Story body in Markdown.

The name field in frontmatter is required. The story key is derived from the filename (without .md).

Example

stories/confirm-story-map.md:

---
name: Confirm story map
---

As a team member
I want to view the story map as a board
So that I can visually confirm the discovery outcomes maintained in text

This story has key confirm-story-map, which is used to reference it from story maps and example mappings.

Story Maps

Story maps are YAML files stored in discoveries/usm/. They define the structure of a User Story Map with activities, steps, stories, and release slices.

Format

name: Map Name

activities:
  - key: activity-key
    name: Activity Name
    steps:
      - key: step-key
        name: Step Name
        stories:
          - key: story-key
            name: Story Card Name
          - name: Lightweight Story Card

releases:
  - name: Release Name
    stories:
      - story-key

Releases

• Each release defines a horizontal divider on the board
• Stories listed in a release appear above its divider
• A release without name defaults to “Release N” based on position
• Stories not in any release appear below all dividers
• Story cards without key appear as plain cards and are not included in releases
• A story cannot belong to multiple releases

Example

discoveries/usm/collaborative-discovery.yaml:

name: Collaborative Discovery

activities:
  - key: story-mapping
    name: Story Mapping
    steps:
      - key: discover-stories
        name: Discover stories
        stories:
          - key: confirm-story-context
            name: Confirm story context
          - key: confirm-story-map
            name: Confirm story map
          - name: Draft session outcomes
      - key: slice-releases
        name: Slice into releases
        stories:
          - key: split-release-scope
            name: Split release scope

  - key: discovery
    name: Discovery
    steps:
      - key: discover-rules
        name: Discover rules
        stories:
          - key: confirm-discovery-outcomes
            name: Confirm discovery outcomes

releases:
  - name: Walking Skeleton
    stories:
      - confirm-story-context
      - confirm-story-map
      - confirm-discovery-outcomes
  - stories:
      - split-release-scope

Example Mappings

Example mappings are YAML files stored in discoveries/example-mappings/. They capture the rules, examples, and questions discovered during an Example Mapping session for a story.

Format

story: story-key

rules:
  - id: R-01
    name: Rule description
    examples:
      - id: EX-01
        name: Example description

questions:
  - id: Q-01
    text: Question text

• story is optional (links to the corresponding story detail page)
• IDs must be unique within their rule or question list

Visual Layout

The board renders cards in the Example Mapping format:

• Yellow card: Story (top)
• Blue cards: Rules (row below story)
• Green cards: Examples (stacked under their rule)
• Red cards: Questions (separate column)

Example

discoveries/example-mappings/confirm-discovery-outcomes.yaml:

rules:
  - id: R-01
    name: An example mapping can be rendered as a sticky view with only a story reference
    examples:
      - id: EX-01
        name: A YAML with only a story reference displays a single yellow Story card

  - id: R-02
    name: Cards are laid out following the Example Mapping format
    examples:
      - id: EX-01
        name: Rules are displayed as blue cards in a row below the Story card
      - id: EX-02
        name: Examples are displayed as green cards stacked under their Rule
      - id: EX-03
        name: Questions are displayed as red cards in a separate column

questions: []

Commands

livt serve

Build artifacts and start a local server.

livt serve [flags]

livt build

Build static HTML from artifacts without starting a server.

livt build [flags]

livt version

Print the version of livt.

livt version

File Structure

Input

project-root/
  stories/
    {story-key}.md                        # Story files
  discoveries/
    usm/
      {map-name}.yaml                     # Story map files
    example-mappings/
      {story-key}.yaml                    # Example mapping files

• Story keys are derived from filenames (without extension)
• Example mapping filenames must match story keys to link them

Output

livt build generates the following structure:

dist/
  index.html                              # Story list
  story/
    {story-key}.html                      # Story detail pages
  mapping/
    {story-key}.html                      # Example mapping boards
  story-map/
    {map-name}.html                       # Story map boards