ln-032-vps-project-runtime

name	ln-032-vps-project-runtime
description	Use when creating or verifying one project runtime on a prepared VPS, including god-session, provider credentials, and local dispatcher setup.
license	MIT
allowed-tools	Bash, Read, mcp__hex-ssh__remote-ssh, mcp__hex-ssh__ssh-read-lines, mcp__hex-ssh__ssh-write-chunk, mcp__hex-ssh__ssh-edit-block

Paths: File paths (shared/, ../ln-030-vps-bootstrap/references/) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

ln-032-vps-project-runtime

Type: L3 Worker Category: 0XX Shared / Infrastructure

Creates or verifies one project environment on a prepared VPS and installs the local operator dispatcher in the target project repo.

MANDATORY READ

MANDATORY READ: Load shared/references/worker_runtime_contract.md, shared/references/coordinator_summary_contract.md, and shared/references/vps_runtime_contract.md MANDATORY READ: Load ../ln-030-vps-bootstrap/references/scope_layers.md, ../ln-030-vps-bootstrap/references/project_repo_bootstrap.md, ../ln-030-vps-bootstrap/references/god_session_install.md, ../ln-030-vps-bootstrap/references/provider_credentials.md, and ../ln-030-vps-bootstrap/references/operator_dispatcher_install.md

---

Input / Output

Direction	Content
Input	mode, project/VPS variables, provider variables, local ${TARGET_REPO_PATH}, optional dry_run, optional runId, optional summaryArtifactPath
Output	vps-project-runtime summary with status, changes, warnings, blockers, verification, and artifact paths

If summaryArtifactPath is provided, write the same summary JSON there. If not provided, return the summary inline and write it to the standalone run-scoped path. Generate a standalone run_id when runId is absent.

Modes

Mode	Behavior
bootstrap	Create or reconcile one project runtime
verify_only	Inspect expected project runtime without mutation

Workflow

Phase 1: Preflight

Verify unique project inputs:

• ${PROJECT_NAME}
• ${SERVICE_PREFIX}
• ${PROJECT_DIR}
• ${REPO_URL}
• ${REPO_REF}
• ${RELAY_HOOK_PORT}
• ${TARGET_REPO_PATH}

Block on collisions for existing unrelated ${PROJECT_NAME}, ${SERVICE_PREFIX}, tmux socket, or relay port.

Phase 2: Project Repo And State

Use project_repo_bootstrap.md.

Responsibilities:

• create or verify ${PROJECT_DIR}
• clone or update ${REPO_URL} at ${REPO_REF}
• create /etc/${PROJECT_NAME} and /var/lib/${PROJECT_NAME}
• render project .claude/ files
• preserve arbitrary non-git files

Phase 3: God-Session And Scheduler

Use god_session_install.md.

Responsibilities:

• sandbox script
• ${SERVICE_PREFIX}-god@.service
• tmux socket and target naming
• dispatch service/timer templates
• statusLine support
• project-scoped hooks except hex-relay product deployment

Phase 4: Provider Credentials

Use provider_credentials.md.

Responsibilities:

• GitHub App key path and ${SERVICE_PREFIX}-mint-gh-token
• GitLab git/API credential wiring
• optional Codex notify hook only when requested

Never invent or print real provider secrets.

Phase 5: Local Operator Dispatcher

Use operator_dispatcher_install.md.

Responsibilities:

• copy dispatcher.md.template to ${TARGET_REPO_PATH}/.claude/commands/dispatcher.md
• seed missing .env.local VPS_* keys
• verify .env.local is git-ignored

Phase 6: Summary

Write a vps-project-runtime summary artifact with project runtime changes, local dispatcher changes, warnings, blockers, and verification evidence.

Critical Rules

• Requires a prepared or reconciled shared host runtime.
• Does not install shared Node/Claude/Codex runtime.
• Does not deploy or rebuild agents/hex-relay/.
• dry_run=true and verify_only do not mutate remote or local state.
• Local dispatcher setup is project-specific and stays with this worker.

Definition of Done

• Project variables validated and collision checks completed.
• ${PROJECT_DIR} clone exists at ${REPO_REF} without overwriting unrelated files.
• /etc/${PROJECT_NAME} and /var/lib/${PROJECT_NAME} exist with expected ownership and modes.
• Project .claude/ settings and instructions are rendered.
• ${SERVICE_PREFIX}-god@.service and scheduler templates installed or verified.
• Provider credentials are configured or explicitly gated N/A:.
• Local dispatcher command and .env.local VPS_* keys installed or planned.
• dry_run=true / verify_only performed no mutation.
• Structured vps-project-runtime summary artifact written.

---

Version: 1.0.0 Last Updated: 2026-05-05