---
name: kb-journeys
description: Author and publish user/customer/product journeys as living markdown with generated HTML views and standalone UI mocks. Journeys are hierarchical (journey → phase → sub-journey → step) with entry/exit conditions, interfaces, and readiness assessments. The skill ships authoring commands (ideate, discuss, review, refine) shared with kb-roadmap's contract, a neutral HTML template whose tokens are set by the adopter's `.kb-config/artifacts.yaml`, and a mock-extraction pipeline that renders every embedded UI mock as a linkable standalone page. Triggered by `/kb journeys` and journey-authoring phrases.
version: 1.0.0
triggers:
  - "/kb journeys"
  - "/kb journey"
  - "user journey"
  - "customer journey"
  - "product journey"
  - "operator journey"
  - "journey map"
  - "user flow"
  - "customer flow"
  - "experience map"
  - "onboarding flow"
  - "sub-journey"
  - "journey phase"
  - "journey mock"
tools: []
requires:
  - kb-management
author: agentic-kb contributors
homepage: https://github.com/wlfghdr/agentic-kb
license: Apache-2.0
---

# Skill: KB Journeys

Journeys describe how a persona moves through a product, service, or process — as a **hierarchy** (journey → phase → sub-journey → step) with explicit entry conditions, exit conditions, cross-journey interfaces, and readiness assessments per visible step. They are a first-class product-management KB artifact, separate from roadmaps (plan↔delivery) and topics (positions), but tightly coupled to both as the product-behavior reference layer.

This skill turns markdown journey specs into:

1. A **browsable HTML set** (one HTML per journey + an index) that respects the adopter's brand tokens.
2. An automatic **standalone-mock index** — every embedded UI or terminal mock is also rendered as its own page and back-linked.
3. A four-command authoring arc shared with `kb-roadmap`: `ideate`, `discuss`, `review`, `refine`.

## When to invoke

Invoke whenever the user:

- Types `/kb journeys` (optionally followed by `new`, `render`, `extract-mocks`, `audit`, `ideate`, `discuss`, `review`, `refine`).
- Describes a user flow, a phase map, an onboarding path, an incident response path, or any multi-step persona-centric narrative.
- Asks *"how does a user / customer / operator move through X?"*.

## Why journeys matter in the operating model

Journeys are the cleanest shared answer to: **what is the thing supposed to do for whom, through which path, at what level of readiness?**

That makes them the bridge between:

- **joint roadmap intent** — what leadership/product says should move
- **workstream detail reality** — what engineering is actually building, learning, changing, and proving

Roadmap items should move journey readiness. Delivery updates should be explainable in journey terms. Scope changes should be visible as changes in journey shape, step priority, or readiness movement, not only as ticket churn.

## Core rules (always apply)

1. **Markdown is the source of truth.** HTML is generated; never hand-edit the HTML.
2. **Every journey is self-contained.** Readable without loading any other journey, but with explicit `## Interfaces` to adjacent journeys.
3. **Every visible step has a stable id** (`J<journey>.<phase>-S<step>`, e.g. `J1.1-S3`). Ids do not change once assigned — they are link targets across the KB.
4. **Every visible step carries a readiness chip** — green / amber / red, with a one-line rationale. Journeys without readiness are draft only.
5. **Every embedded mock is extractable** — wrap in the mock envelope so the extractor can lift it out into a standalone page.
6. **Zero vendor strings.** Brand colors, fonts, logos come from the adopter's `.kb-config/artifacts.yaml`. The skill's template ships with neutral tokens.
7. **Dual output always.** Every `render` run emits the per-journey HTMLs + the mocks index in the same pass. They never drift.
8. **Journeys are ground truth for the roadmap.** When a scope in `kb-roadmap` declares `journey-refs` pointing here, every roadmap item is cross-checked against its cited step(s). Journey steps are the definition of what the product must do; roadmap items exist to move step readiness forward. A journey is **never** silently updated from roadmap findings — drift findings trigger `/kb journeys review <step>`, which is a deliberate authoring pass.
9. **Journeys must work both top-down and bottom-up.** Top-down: strategy or roadmap intent can introduce or re-prioritize a journey or step. Bottom-up: engineering discoveries, demo feedback, prototype learning, and customer signal can force a journey refinement, split, merge, or readiness downgrade.
10. **Daily work should feed journeys with intent, not noise.** Not every ticket touches a journey, but every meaningful product behavior change should be able to point to the step it advances, challenges, or invalidates.
11. **Log every run** to `.kb-log/YYYY-MM-DD.log`.
12. **Setup decides ownership.** `/kb setup` proposes the owning layer from the user's role, audience, sources, and desired outputs. The conservative default is to co-locate journeys with the roadmap scope they ground. Cross-layer journey inheritance is allowed by the layer graph but treated as a later enhancement unless the user explicitly configures it.
13. **Journey text stays value-oriented.** Step titles describe what the persona can do, learn, decide, or recover from; implementation mechanics belong in step detail, interfaces, or readiness notes.

## Hierarchy

```
Journey (tier N)
└── Phase (ordered)
    └── Sub-Journey (optional; a Phase may be a Sub-Journey directly)
        └── Step (Sn; has id, title, actor, artifact, readiness)
            └── Mock (0..N; extracted into standalone page)
```

Numbering reflects tier: `1.x` = tier 1, `2` = tier 2, etc. Sub-journeys within a phase get dotted suffixes (`1.4.2`). Steps use `-S<n>`.

## Directory contract (adopter's KB)

```
my-kb/
├── _kb-journeys/                        # configurable via journeys.output-dir
│   ├── <journey-slug>.md                # source of truth
│   ├── <tiered-journey>/                # if the journey has sub-journey files
│   │   ├── README.md
│   │   ├── <sub-journey-slug>.md
│   │   └── ...
│   ├── overview.md                      # master journey map (cross-journey)
│   ├── html/                            # generated; do not hand-edit
│   │   ├── index.html
│   │   ├── shared.css                   # emitted from .kb-config/artifacts.yaml tokens
│   │   ├── <journey-slug>.html
│   │   └── mocks/
│   │       ├── index.html
│   │       └── <journey>-<step>-<mock-slug>.html
│   └── scripts/
│       └── (optional adopter overrides)
└── .kb-log/YYYY-MM-DD.log
```

## Journey markdown contract

Every journey file opens with a metadata block and required sections. See `references/structure.md` for the full template.

```markdown
# <tier>.<phase> — <Journey Title>

> **Sub-Journey**: <one-line path summary>
> **Tier**: <tier label>
> **Target duration**: <duration>
> **Version**: <n.n> | **Last updated**: YYYY-MM-DD

## Entry Conditions
- ...

## Exit Conditions
- ...

## Interfaces
| Direction | Sub-Journey | What |
|-----------|-------------|------|
| OUT → | <slug> | ... |

## Flow

### Step 1: <title> · `J<tier>.<phase>-S1` · `[ACTOR]`
<description>

#### Readiness
<span class="status-chip feasible">green</span> — <one-liner>

#### Mock (optional)
<!-- mock-begin: <mock-slug> -->
<div class="mockup-block" data-mock="<mock-slug>">
  ... mock HTML ...
</div>
<!-- mock-end: <mock-slug> -->
```

## Commands

Full reference: `references/command-reference.md`.

Concurrency contract: [`docs/concurrency.md`](../../../../docs/concurrency.md) governs shared-layer promote collisions, diverged backlinks, topic merges, and append-only logs. Journey flows that read or write shared KB artifacts must honor the same `/kb sync` and `/kb audit` reconciliation rules.

| Command | Purpose |
|---|---|
| `/kb journeys` | Scan state; surface next action (unrendered journey, stale mock, missing readiness) |
| `/kb journeys new [slug]` | Scaffold a new journey markdown from the template |
| `/kb journeys render [--journey slug]` | Generate HTML set + mock index |
| `/kb journeys extract-mocks` | Refresh standalone mock pages only |
| `/kb journeys audit` | Validate structure, ids, readiness coverage, mock envelopes |
| `/kb journeys ideate \| discuss \| review \| refine [journey]` | Authoring arc — same stance contract as `kb-roadmap` authoring-commands |

## Configuration

Adopter config in `.kb-config/layers.yaml`:

```yaml
journeys:
  output-dir: _kb-journeys
  source-dir: _kb-journeys           # where the .md files live (can be same as output-dir)
  html-subdir: html
  mocks-subdir: html/mocks
  tiers:
    - { key: t1, label: "Individual", color-token: accent-1 }
    - { key: t2, label: "Team",       color-token: accent-2 }
    - { key: t3, label: "Enterprise", color-token: accent-3 }
  readiness-levels:
    - { key: feasible, label: "Green",  chip-class: "feasible" }
    - { key: partial,  label: "Amber",  chip-class: "partial" }
    - { key: blocked,  label: "Red",    chip-class: "blocked" }
  mock-envelope:
    begin-marker: "<!-- mock-begin: "
    end-marker:   "<!-- mock-end: "
    container-selector: ".mockup-block"
  include-terminal-anim: false        # opt-in: embeds shared-terminal-anim.js when mocks use terminal blocks
```

Styling in `.kb-config/artifacts.yaml`:

```yaml
journeys-template:
  base: kb-journeys/templates/journey.html
  tokens: <path to brand tokens CSS>    # reuses the adopter's existing brand tokens
  logo:
    light: <path>
    dark: <path>
  themes: [light, dark, auto]
```

The journey template reads the same tokens block as `kb-roadmap` (`--fg`, `--bg`, `--accent`, `--border`, tier color tokens). Adopters with a brand tokens file already configured for roadmaps get journey styling for free.

## References (load on demand)

- `references/structure.md` — full markdown contract: metadata block, required sections, step id scheme, readiness chips, mock envelope
- `references/authoring.md` — `ideate`/`discuss`/`review`/`refine` stance rules for journeys (shared contract with kb-roadmap, with journey-specific deltas)
- `references/artifact-contract.md` — HTML output shape, shared.css emission, mock index contract
- `references/mocks.md` — mock envelope, extraction, standalone-page layout
- `references/folder-layout.md` — `_kb-journeys/` layout
- `references/config-schema.md` — full `.kb-config/layers.yaml` `journeys:` block
- `references/command-reference.md` — subcommand details
- `references/audit.md` — `/kb journeys audit` rule set, output contract, and offered corrections

## Templates

- `templates/journey.md.hbs` — single-journey markdown template
- `templates/journey-overview.md.hbs` — cross-journey overview template
- `templates/journey.html.hbs` — per-journey HTML template (neutral tokens; brand tokens merged from adopter's config)
- `templates/mock-standalone.html.hbs` — standalone mock page template
- `templates/shared.css.hbs` — base CSS; adopter's brand tokens block is inlined at render time

## Scripts

- `scripts/render_journeys.py` — markdown → HTML set (neutral baseline; brand tokens merged from `.kb-config/artifacts.yaml`)
- `scripts/extract_mocks.py` — standalone-mock extraction pipeline

## Status

Stable setup-proposed skill (`v1.0.0`). Setup offers it when the user's role, goals, sources, or desired outputs imply product-management journey work. Activate by declaring `journeys:` in `.kb-config/layers.yaml` + `journeys-template:` in `.kb-config/artifacts.yaml` for the confirmed owning layer.

The shipped helper scripts cover artifact rendering and standalone-mock extraction, including no-extra-dependency fallback paths when `python-markdown` or `beautifulsoup4` are absent. Authoring and audit flows use the same explicit command and confirmation gates documented in this skill.

## Changelog

| Date | What changed | Source |
|------|-------------|--------|
| 2026-05-24 | Added a concurrency-contract pointer so journey adopters can find the shared-layer `/kb sync` and `/kb audit` reconciliation rules from the skill spec. Closes #124 | `/kb sync` contract reconciliation |
| 2026-05-24 | Added `references/audit.md` to the reference list so the advertised `/kb journeys audit` command points at its canonical J-rule contract | Issue #125 |
| 2026-05-15 | Promoted the journeys skill contract to stable `v1.0.0`, removed draft-status frontmatter, and clarified helper coverage without presenting authoring/audit as unfinished | Release-readiness audit |
| 2026-05-08 | Bumped to v0.2.0, removed the stale `overview.html.hbs` template claim, and clarified current helper-script coverage plus optional dependency fallbacks | Integration pass |
| 2026-04-30 | Promoted journey work into the product-management surface: setup-derived ownership, broader journey/flow triggers, and value-oriented step-title rules | Product-management surface integration |
| 2026-04-22 | Removed internal-repo reference from extract_mocks.py description | Vendor-neutrality review |