/app-design-thinking

name: app-design-thinking
description: Design the app mechanism and build pipeline for the produced app — the app-phase analog of [[schema-design]]. Use this skill whenever the knowledge phases are complete (or nearly so), when the user mentions building the app / runtime / UX / production / deploy, when the app-type definition section of PLAN.md needs its runtime + pipeline rows settled, or when [[ralph-loop]] advances out of packaging into the app phases. The shape of the produced app gets decided here; downstream phases follow.
metadata:
  triggers:
    - design the app
    - app design thinking
    - app mechanism
    - build pipeline
    - how should the app work
    - design the app phases
    - what kind of app
    - app shape

app-design-thinking

The knowledge phases produced byte-identical knowledge inventories at `<project>/.claude/skills/` and `<project>/.agents/skills/`. Now the question is: **what app do we build with them, and how do we build it?** That's the third and fourth links of the app-type definition cascade — app mechanism and build pipeline. This skill teaches how to settle those decisions from the knowledge already extracted.

[[schema-design]] is this skill's twin in the knowledge phases — same methodology, different links in the cascade. Both teach taste, neither prescribes.

What this skill is NOT

• **It's not picking from a closed menu of app archetypes.** The 5 reference apps are examples for pattern-matching, not a catalog. Every John project should invent its own runtime + pipeline shape; templates may ship common shapes as starting points, but users always override. If the project's runtime doesn't resemble any of the 5, that's normal — invent it.
• It's not one-shot. Runtime and pipeline iterate as the produced skills reveal what the app naturally wants to be.
• It's not an alternative to the user's intent. They own the project's *what*; this skill teaches you how to translate it into *how*.

The third decision — app mechanism

The runtime is how the produced app works for end-users. Pin it down by asking:

• **Who's the end-user?** (a teacher? a compliance officer? a player? a researcher?) Their context determines the runtime shape.
• **What's their input?** (a document upload? a chat? a click? nothing — they just browse?) The input shape constrains the runtime architecture.
• **What's their output?** (a verdict? a slide deck? an interactive widget? a downloadable file?) The output shape determines what the runtime must produce.
• **Is there an LLM at runtime, or only at build time?** (a static slide deck has no runtime LLM; a chat-based study companion calls a workerLLM on every user turn.) See `references/runtime-vs-buildtime-llm.md`.
• **Is the runtime stateful?** (does it remember the user across sessions? track progress? store uploads?) If end-users wait on expensive generation — upload → job → download — [[job-runtime]] supplies the runtime pattern.

Sketch the runtime in PLAN.md's app-type definition section. Like schema-design's schema sketch, mark it "may evolve."

The fourth decision — build pipeline

The build pipeline is the phases that turn the packaged skills (and any other input) into the runtime. Derive it backward from the runtime: what does the runtime need, and what phases produce each piece?

Common pipeline patterns (see `references/app-phase-design.md`):

• **Scaffold** — set up the app's basic structure (framework choice, project layout, dependencies).
• **Wire core mechanics** — implement the app's central loop (rule application, game logic, slide rendering).
• **Seed content from skills** — pull knowledge entries from the active provider's project skill tree into the app's data layer; the Claude and Codex trees should be byte-identical.
• **Wire runtime LLM** (if applicable) — provider abstraction, system prompts, error handling.
• **Wire the job runtime** (if end-users wait on long generation) — task registry, bounded worker pool, progress + cancellation endpoints; see [[job-runtime]].
• **Polish** — UX details, error states, edge cases.
• **Deploy** — Docker, hosting, smoke test.

Not every project needs every phase. Use the rubric in [[phase-design]] to decide; this list is a starting point, not a checklist.

Deployment posture — standalone by default

Vanilla John designs produced apps to **run standalone**: launch locally or on any host the user owns, configuration through `.env`, no assumptions about an external auth/billing/telemetry platform being present. If the project is destined for a hosted multi-tenant platform, a template supplies those integration patterns — don't invent platform coupling in a vanilla project.

The reverse direction — runtime informs schema

Sometimes app-design-thinking reveals that the produced knowledge isn't quite shaped right for the runtime you want. (E.g., "this rule-shaped schema doesn't carry the severity field the runtime needs to color-code violations.") When that happens, [[plan-md-evolution]] takes over: append to PLAN.md's Log, surface the gap as an Open Decision, decide whether to extend the schema and re-emit affected entries, OR adapt the runtime to what the schema gives. Cascade iteration is normal; the cascade is not a one-way pipe.

**The cost tradeoff.** If the schema is already locked (you've extracted hundreds of entries against it), extending and re-emitting is expensive. Before deciding, ask the user three questions:

1. How many entries already exist? (more entries → re-emission cost grows) 2. Is the missing field mandatory at runtime, or optional? (optional → can adapt runtime cheaper) 3. Can the runtime compute the field from existing fields? (e.g., derive severity from a `category` and a fixed mapping)

If re-emission is expensive AND the runtime can adapt, adapting often wins. If re-emission is cheap OR the field is mandatory, extending the schema is right. Capture the decision in PLAN.md so future-you knows why the cascade looks the way it