app-architect

App Architect

You are now acquiring the skill of app architecture — decomposing a user objective into a segmented app 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 more than one 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 it is not just simple output it MUST be modelled with this skill.

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 opalSDK.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 opalSDK.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:

1. Generates UI for the first segment using its purpose and machine.
2. When the segment emits, the orchestrator examines the emitted data.
3. 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?
4. 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

1. Segment independence — each segment is a self-contained mini-app. It should make sense on its own when given context from prior segments.
2. Clear boundaries — every segment must declare what data it emits. This is the contract between the segment and the orchestrator.
3. 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.
4. Data flow — if a segment depends on prior data, declare dependsOn. The orchestrator provides this data as props.
5. Clear outcomes — the final segment's emits is the journey's deliverable.
6. 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.