Lintel on GitHub Copilot. Generated from
skills/generate-app/SKILL.md; edit the canonical file, then runli-copilot init.
- Resource root:
../../..from this skill's base directory (the Lintel source withbin/,lib/,skills/). Write plans, state and evidence into the working repository's.claude/tree, never into the resource root.- Skill-relative paths: this skill's own
scripts/,references/anddata/folders (and a<base>that the workflow defines as its own directory) mean../../../skills/generate-app/in the Lintel source, not this generated folder.${LINTEL_SKILLS_DIR:-skills}means the skills root,../../../skills. Abin/li-runstep runs in the working repository, so use$LINTEL_SKILLS_DIR/generate-app/there.- Shell steps: run Bash snippets with Bash (Git for Windows'
bash.exeon Windows, neverSystem32\bash.exe). Save a snippet to a temporary.shfile and runbash "<resource root>/bin/li-run" <file>; it preparesLINTEL_SOURCE_ROOT,LINTEL_REPO_ROOTand the profile context.- Tools: Read=
view, Write=create, Edit=edit, Bash=bash/powershell, Grep=grep, Glob=glob, AskUserQuestion=ask_user, TodoWrite=the plan checklist, Task or a named role=taskwith that custom agent, WebFetch=web_fetch.- Other Lintel workflows are native skills: invoke
/li-<name>rather than reading their files. Named roles such asCodeReviewerare custom agents.
You are the generate-app skill for full-app scaffolds, preserving the design-director versus rendering-engine separation.
What this skill does
Reads frontend-design-spec.json (from /li-frontend-design orchestrator output) → generates a working repo skeleton the operator can npm install && npm run dev. Spans single-page-app territory beyond what generate-web's single-file or nextjs-scaffold variants cover.
Why separate from generate-web (M-2 resolution): generate-web targets pitch-artifacts (single-file landing + Next.js scaffold). generate-app targets production-grade app skeletons (multi-route, state, API stubs, deploy-config). Same rendering-engine family, different scope.
L-001-discipline: skill body is the contract (what scaffolds get generated). Agent at invocation produces actual file-content. Don't pre-bake "the best React structure" — let agent decide based on stack + brief.
Use the shared direct design contract for validation and renderer arguments. Respect existing project technology; no library, framework migration, dependency installation or deployment is implicit.
When to use
- "Customer wants a full Next.js app POC, not just a landing page"
- Vite-React production-grade starter with motion + shader wired up
- SvelteKit multi-route app skeleton
- Engagement-deliverable that operator will commit to a customer repo
When NOT to use
- Single-file landing page → use
/li-generate-web --variant single-file - Next.js scaffold (basic 1-3 route) → use
/li-generate-web --variant nextjs-scaffold - Pure backend (no frontend) → not in this skill's scope
- Operator already has a repo + just needs design integration → use
/li-frontend-designsolo + manual integration
Inputs
- Required
--from-frontend-design <run-dir>— frontend-design output dir (must containfrontend-design-spec.json) - Required
--stack <next-app|vite-react|svelte-kit>— framework choice - Optional
--brief <path>— additional content brief beyond what frontend-design captured - Optional
--routes <comma-list>— explicit route list (default: home + about + contact) - Optional
--with-api-stubs— generate api/ folder with placeholder routes - Optional
--with-auth-stubs— placeholder auth (next-auth / clerk-stub / lucia-stub) - Required
--out <path>— explicitly owned repository-relative application output directory - Optional
--customer-share— triggers compliance-gate - Optional
--review— explicitly request the shared post-generation review; this does not add a second reviewer or waive required review when omitted
Workflow
Step 1 — Parse + validate
from_frontend_design="${FROM_FRONTEND_DESIGN:-}"
stack="${STACK:-}"
brief="${BRIEF:-}"
routes="${ROUTES:-home,about,contact}"
out_dir="${OUT:?select an owned repository-relative output directory}"
[ -z "$from_frontend_design" ] && { echo "Required: --from-frontend-design <dir>"; exit 2; }
[ -f "$from_frontend_design/frontend-design-spec.json" ] || { echo "frontend-design-spec.json not found"; exit 2; }
[ -z "$stack" ] && { echo "Required: --stack <next-app|vite-react|svelte-kit>"; exit 2; }
Reject unknown, duplicate or conflicting options before output. Validate the selected design and project manifests before scaffolding; do not create directories merely because two required strings are nonempty. Follow owned source and output selection. Missing or unwritable output fails visibly; no current-directory, personal-home or neighboring-run fallback is permitted. Preserve original source/manifest bytes and require explicit replacement authorization before touching existing output.
Step 2 — Schema-version handshake (M-1 + M-5)
Call design_contract.load_design using the external prepared P05 context and
explicit P07 configuration. Consume renderer_args rather than reimplementing
variant/stack mapping. Legacy readable inputs need explicit resolution; missing
policy/assets and profile drift block, without rebinding.
The shared reader enforces the existing schema_version: 1 and
source: frontend-design handshake as well as the complete bound design.
Step 2b — Stack-guidance pass (ADR-0015 — retrieval before rendering)
case "$stack" in
next-app) dna_stack=nextjs ;;
vite-react) dna_stack=react ;;
svelte-kit) dna_stack=svelte ;;
*) echo "Unsupported stack '$stack'; preserve the project technology" >&2; exit 2 ;;
esac
python3 "${LINTEL_SKILLS_DIR:-skills}/design-dna/scripts/search.py" "<routes/features keywords>" --stack "$dna_stack"
Apply the returned Do/Don't/Severity rules while scaffolding. python3 absent → Read
design-dna/data/stacks/$dna_stack.csv (same root) directly.
Step 3 — Stack-specific scaffold
For --stack next-app:
- Use an already available
create-next-apptemplate or an explicitly selected owned template, including an actual verified configured template path. Record which source was used. A missing selected template/dependency is a reported boundary, not an automatic download, home scan, tool fallback or reason to replace a project. A different scaffold needs explicit selection. - Generate dir structure:
This is a library-enabled example, not a required dependency tree. For no-motion or CSS-only output omit Lenis/GSAP providers, motion modules and dependencies; for no-shader omit the canvas/GPU module. Use only libraries actually selected with project-compatible source/version/license evidence.app/ ├── layout.tsx — wires up LenisProvider + fonts + global CSS ├── page.tsx — home route, applies visual_thesis ├── about/page.tsx ├── contact/page.tsx └── globals.css — typography + layout_grammar tokens components/ ├── ui/ — shadcn primitives (init via skill body) ├── motion/ — GSAP-tied components └── hero/ — uses shader-snippets if shader != null lib/ ├── motion.ts — Lenis init + GSAP setup └── typography.ts — variable-axes utilities public/ └── (operator-licensed fonts dropped here if Pangram etc) package.json — gsap + lenis + (paper-shaders if applicable) + shadcn + (Aceternity reference) next.config.js tsconfig.json tailwind.config.ts — fontFamily with stacks from typography.json
For --stack vite-react:
- Use Vite + React-TS template
- Similar structure adapted to Vite paradigm
- React-Router for multi-route
- Apply same typography + motion + shader integration
For --stack svelte-kit:
- Use SvelteKit + TypeScript template
- Similar structure, Svelte syntax for components
- SvelteKit routes-based file routing
Step 4 — Apply design-spec to generated files
For each file generated, apply transforms from frontend-design-spec.json:
- layout.tsx / +layout.svelte: apply the selected authorized font-loading
strategy and font-family classes. If
interaction_signature.scroll_smoothingis true, integrate the actual bound motion runtime in a framework-compatible way.LenisProvideris only an example when Lenis was explicitly selected; do not introduce it for a different runtime or native scrolling. - page.tsx / +page.svelte: apply
visual_thesisto hero copy + structure - tailwind.config: map
typography.size_scale.scale+typography.line_heights+layout_grammar.max_widthto Tailwind tokens - Motion: none means no animation imports; CSS-only uses CSS, not a JS library added for media queries. Library mode implements only selected effects with cleanup and reduced-motion handling.
- Shader: emit a GPU component only for an active non-
noneshader decision;shader: nullandvisual_thesis: noneproduce no shader dependency.
Step 5 — Generate package.json
Retain the project's manifest/lockfile and package manager. For a new authorized
scaffold, select exact compatible framework/tool releases from their official
sources; record version/license and rationale in the shared binding. Write only
the dependencies the chosen design needs, plus the selected framework/build tools.
No guessed latest, stale version ranges or universal GSAP/Lenis/Tailwind bundle.
Use actual framework scripts and preserve the lockfile. Run installation only
inside the separately authorized scope after a manifest change or missing-tool
failure; never silently skip the failed build and claim smoke-test success.
Step 6 — Operator-instructions emit
GENERATE-APP COMPLETE
══════════════════════════════════════════════════════════════════
Stack: <next-app | vite-react | svelte-kit>
Output dir: $out_dir
Files generated:
- $route_count routes
- $component_count components
- typography + motion + (shader) wired up
Next steps:
cd $out_dir
npm install
npm run dev
open http://localhost:3000
Operator-licensed items (per frontend-design-spec.json):
- Pangram font? See: $out_dir/public/README-fonts.md
- Any selected runtime/editor/asset terms? See the source-bound dependency notes.
Step 7 — Required checks and one review owner
Run the existing mechanical validator on actual produced HTML using the verified profile; source JSX is not rendered HTML. Retain its errors and warnings, then run the declared build smoke-test. A failure remains a failure.
Follow review ownership and reuse.
In an enclosing frontend-design run, return artifact paths, current input identity
and observed checks to that owner for its Step 7 review. For standalone use,
the current app workflow owns the same frontend-design-review handoff.
--review requests that review, not an extra DesignSystemAuditor pass after
WebExperienceCritic. Reuse only applicable current P05/QA and independent evidence.
Resolve actual voice.gates_active separately from compliance hooks when the
brief/profile requires voice review. No configured voice gate is different from
an unavailable required one; missing mandatory observations keep delivery blocked.
An otherwise valid generated artifact can be handed to its owner for outstanding
review without regenerating it or treating the unperformed review as passed.
Voice tier behavior
voice: mixed. Default internal. --customer-share triggers compliance-gate + voice-gate.
Reusable patterns
Follow the reusable pattern consumer contract.
Before scaffolding, verify-lock the lock handed over by the design step against the current
context, then check the spec's pattern_context with validate_visual against it (never a
stored report). Loading through design_contract with --pattern-lock does both. A stale context,
mismatched setting or unusable selection blocks instead of being corrected here. Apply the
projected values; generate-app still makes no design decisions. When the runtime reports no
patterns, scaffolding is unchanged.
Status protocol
- DONE — app output and all applicable required build, inspection and review controls are verified
- DONE_WITH_CONCERNS — required controls are satisfied; advisory concerns remain explicit
- BLOCKED — invalid design, failed build, or any required failed/unverified control; hand valid produced output to the selected owner for an outstanding review
- NEEDS_CONTEXT — stack-choice missing or frontend-design-spec absent
Pause-points
- Schema-version handshake fail: BLOCKED hard
- Build smoke-test fail: surface diagnostic + offer retry
- Customer-share + voice-gate fail: BLOCKED for operator-review
Integration
Reads:
<from-frontend-design>/frontend-design-spec.json(mandatory)- Explicitly selected owned or verified configured template source for the selected stack
- The exact selected pattern/lock references carried by the bound design
- The unchanged verified P07 profile reference and its actual voice requirements; do not read a personal profile YAML directly
Writes:
<out_dir>/— full repo skeleton- Audit-log:
.claude/runtime/audit/generate-app-runs.jsonl
Calls into:
/li-frontend-design-reviewthrough the single selected owner; the retained WebExperienceCritic/DesignSystemAuditor methods are not two default passes- the active pack's actual voice requirements (
resolve_pack_field voice.gates_active; none by default, independent of compliance hooks) /li-compliance-gate(if customer-share)
Boundary with frontend- family (L-002):*
generate-app is the rendering-engine — produces files. frontend-design is the design-director — produces spec. generate-app does NOT make design-decisions; it READS them from spec + scaffolds accordingly. Same role as generate-web but larger-scope output.
| Concern | generate-web | generate-app |
|---|---|---|
| Output | single .html OR Next.js scaffold (basic) | Full vite/next/svelte project skeleton |
| Use case | Pitch artifact, landing page | Production-grade app POC |
| Routes | 1-3 | Multi (configurable) |
| Build-system | Embedded or npm-init | Full package.json + npm-build |
| API stubs | No | Optional via --with-api-stubs |
| Auth stubs | No | Optional via --with-auth-stubs |
Anti-patterns
- Making design-decisions in generate-app — wrong layer. Read them from frontend-design-spec.json.
- Letting an unpinned install choose design dependencies — retain project versions/lockfile and record exact sourced choices before an authorized change.
- Generating without schema-version handshake — M-1 + M-5 violation.
- Skipping prefers-reduced-motion handling — accessibility-fail. Mandatory.
- Inventing routes not in
--routesflag — operator decides scope.
Failure recovery
- Schema-version handshake fail: BLOCKED + diagnostic
- Dependency/build failure: retain the exact diagnostic and unverified artifact outcome; skipping a smoke test does not make the requested app runnable.
- Output missing/unwritable: BLOCKED with the actual error and selected path; retain partial owned output and never retry at an unselected destination
- Stack-template missing or cli scaffold tool unavailable: BLOCKED with install-instruction
Recommended next steps after invocation
cd $out_dir && npm install && npm run dev— operator validates locally/li-frontend-design-review $out_dir— Phase A2 6-dimension audit (if not already auto-run)- Operator commits to customer-repo if customer-share
- Pair with
/li-compliance-gatefor final ship-gate