project-runtime

Manages Next.js dev server lifecycle, logs, and readiness checks for generated AppLoop projects.

6|Updated Jul 12, 2026
One-click install
npx skills add https://github.com/josoroma/AppLoop --skill project-runtime-josoroma
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: project-runtime
Source: https://github.com/josoroma/AppLoop/tree/main/.hermes/skills/project-runtime
Command: npx skills add https://github.com/josoroma/AppLoop --skill project-runtime-josoroma

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Generated Next.js projects need their dev servers started, restarted, and validated after code changes, but port conflicts, stale processes, missing dependencies, and template drift make runtime management error-prone. This Skill provides the operational rules for safely controlling a generated project's runtime inside its workspace. ## Core Features & Use Cases - Runtime Lifecycle Control: Start, restart, and stop dev servers from the workspace path, reserving ports against both project records and existing runtime rows to avoid unique-index conflicts. - Log Inspection and Readiness Checks: Classify bounded log output into dependency, compile, port, or application errors, and emit preview-ready events only after the default route responds successfully. - Template Synchronization: Propagate template changes into generated projects and reverse-sync user customizations back to templates with typecheck and audit validation. - Use Case: After an AI edit changes a generated app's CSS, restart the dev server, confirm the new stylesheet hash is served, and only then mark the preview as ready. ## Quick Start Start the generated project's dev server from its workspace path, verify the port is listening and the default route returns HTTP 200, then report the preview as ready.

Frequently Asked Questions about project-runtime

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I restart a Next.js dev server after code changes?▼

Restart only when files affecting runtime behavior changed or the process is unhealthy. Kill the existing process, then start the dev server from the workspace path using the project's recorded package manager, and confirm the port listens before reporting readiness.

How do I find which port a Next.js dev server is running on?▼

Start the project on a free port and Next.js reports the existing port and PID if already running. For stuck servers, use lsof to find the PID holding project files, then check its listening port and verify with curl against the template body classname.

Why does my Next.js dev server listen on a port but not respond?▼

A compilation error such as a missing module can leave Next.js hung in a retry loop with the port bound but no requests served. Check the runtime log, fix the compile error, force-kill the process, and verify with curl.

Why are Tailwind CSS changes not showing in the Next.js preview?▼

Tailwind v4 with Next.js may cache compiled CSS and miss file changes. Commit workspace changes to git first, kill the dev server, delete the .next directory, restart, and confirm the served CSS hash changed.

What causes a missing package.json error in a generated project workspace?▼

The workspace path may point to a partially created directory, or project creation copied transient folders like node_modules or .next from the template. Repair by recopying from the matching template while excluding transient folders, then reinstall dependencies.