journey-architect - SKILL.md Agent Skill

name: Journey Architect description: Decompose a user objective into a segmented journey. Each segment is a multi-view mini-app. Segments are separated by LLM decision points where the orchestrator decides what comes next.

Journey Architect

You are now acquiring the skill of journey architecture — decomposing a user objective into a segmented journey where multiple mini-apps are orchestrated by an LLM.

What You're Building

A journey spec — a JSON document that describes the segments of a journey. Each segment is a self-contained multi-view mini-app generated by the UI skill. Between segments, the orchestrator (an LLM) examines the user's accumulated data and decides what happens next.

When to Use This Skill

Use this skill when the objective implies more than one screen or interaction step. Signals:

The user needs to browse, select, then act
There's a decision funnel (list → detail → commit)
Information gathering happens across multiple stages
The outcome requires user input at different points

Examples: comparing laptops before buying, planning a dinner menu with shopping list, triaging support tickets by priority.

If the objective is a single display ("show me a weather card"), this skill is overkill. Use the UI generator directly.

The Segment Model

A journey is a sequence of segments separated by LLM decision points:

[segment-1: A → B → C] → emit → LLM → [segment-2: D] → emit → LLM → [segment-3: E → F] → emit → done

Segment — a multi-view mini-app with internal navigation (navigateTo). The user moves between views within a segment without leaving the app.
Boundary — the point where a segment's final view calls ark.emit(), sending collected data back to the orchestrator.
LLM decision point — the orchestrator examines the emitted data and decides: generate the next segment, re-plan, or end the journey.
Context — data that accumulates across segments (each segment's emit payload is merged into the journey context).

Within a segment, views are connected by an XState machine (states, transitions, context). Between segments, the LLM orchestrator decides the next step. You plan both levels.

Your Process

1. Start From the Outcome

What does "done" look like?

"Compare laptops" → outcome: user has chosen a laptop with rationale
"Plan a dinner party" → outcome: user has a menu, guest list, and shopping list
"Triage support tickets" → outcome: tickets are prioritized with assignments

The outcome defines the final state. Work backward from there.

2. Decompose Into States

Each state should have a clear purpose (why is the user here?) and a clear data dependency (what does this state need from prior states to render?). If a screen serves two purposes, split it.

3. Name Transitions After User Intent

Name transitions after what the user wants (BOOK_VIEWING, CHOOSE_ITEM), not what the UI does (CLICK_BUTTON, SUBMIT_FORM).

4. Define the Outcome Report

Final states declare what the journey produces — the data and summary that gets surfaced to the user (or the EA).

Output Format

Save the journey spec as journey.json. The file describes segments and the overall journey:

{
  "objective": "The original user objective",
  "outcome": "What 'done' looks like in one sentence",
  "segments": [
    {
      "id": "gather_requirements",
      "purpose": "Understand the user's needs and constraints",
      "emits": "requirements object (team size, budget, priorities)",
      "machine": { /* XState v5 config for this segment's internal views */ }
    },
    {
      "id": "review_options",
      "purpose": "Present options and let the user compare and choose",
      "dependsOn": ["gather_requirements"],
      "emits": "chosen option with rationale",
      "machine": { /* XState v5 config */ }
    }
  ]
}

Each segment has:

id — unique identifier
purpose — what this segment accomplishes (guides UI generation)
emits — what data leaves via ark.emit at the boundary
dependsOn — which prior segments' data this segment needs
machine — XState v5 config for the segment's internal views

Within-segment view metadata

Each state in a segment's machine config should include extra fields to guide UI generation (XState ignores unknown properties):

meta.purpose — why this view exists (guide for the UI skill)
meta.displays — what the view shows (consumed by the UI skill)
meta.dataNeeded — which context fields this view requires to render

How the orchestrator uses this plan

The plan is an initial best-guess. The orchestrator uses it as follows:

Generates UI for the first segment using its purpose and machine.
When the segment emits, the orchestrator examines the emitted data.
It looks at the planned next segment's dependsOn — does the data satisfy it? Should it proceed, adapt the plan, or insert a new segment?
For the chosen segment, the orchestrator generates UI using the segment's purpose and accumulated context.

The plan gives the overall shape. The LLM at decision points can deviate. Describe segments well enough that the orchestrator can make informed decisions about whether to follow, adapt, or re-plan.

Quality Criteria

Segment independence — each segment is a self-contained mini-app. It should make sense on its own when given context from prior segments.
Clear boundaries — every segment must declare what data it emits. This is the contract between the segment and the orchestrator.
Minimal segments — 2-4 segments is typical. If you have more than 5, look for segments that can be merged. Within a segment, 2-5 views is typical.
Data flow — if a segment depends on prior data, declare dependsOn. The orchestrator provides this data as props.
Clear outcomes — the final segment's emits is the journey's deliverable.
User intent naming — transitions named after what the user wants (BOOK_VIEWING, CHOOSE_ITEM), not what the UI does (CLICK_BUTTON).

Anti-Patterns

The Mega Segment — one segment that does everything. Split it at LLM decision points.
Gratuitous segments — splitting into segments where the LLM has nothing to decide. If no reasoning is needed between two screens, they belong in the same segment.
Context Bloat — carrying data that no future segment needs.
Implicit boundaries — segments that don't declare what they emit.

Output

Save the spec as journey.json. The machine block must be a valid XState v5 machine configuration — states, transitions, context, and final states as defined by the XState API.

Call system_objective_fulfilled with a summary of the journey's states and expected outcome.