Add project-aware Deploy to xCloud skill for Lovable and Replit agents

[neobuilds]

Summary

Add a project-aware Deploy to xCloud capability to the official agent-skills plugin so an AI running inside Lovable, Replit, or another coding panel can prepare and deploy the current application end to end through the existing xCloud MCP.

The intended request is simply:

Deploy this application to xCloud.

The agent should guide the user through xCloud MCP OAuth when needed, inspect the current project, select the correct native Git or Custom Docker path, create any required deployment files, deploy through MCP, poll the operation, and return a verified HTTPS URL.

Why

The existing skills are strong at operating xCloud resources after an application is deployable:

• xcloud:servers creates Git-deployed sites, including Lovable, Node.js, Laravel, PHP, and WordPress sites.
• xcloud:sites manages Git settings, deployments, logs, status, domains, and site lifecycle.
• xcloud:ssl manages certificates.
• xcloud:wordpress owns WordPress application management after provisioning.
• xcloud:account owns identity/account reads used during connection verification.

What is missing is the project-side orchestration that turns the application currently open in an AI coding panel into an xCloud-compatible deployment.

A useful starting point already exists in Asif2BD/xCloud-Docker-Deploy-Skill. It provides stack detection, native-versus-Docker routing, Dockerfile/Compose generation, GHCR workflows, port normalization, and several application templates. We should credit and reuse that work, then align it with the official plugin, current MCP-first authentication, the .xcloud contract, and Lovable/Replit-specific behavior rather than publishing a competing implementation.

Product experience

1. User installs the official xCloud deployment skill in Lovable/Replit or another compatible agent panel.
2. User asks the agent to deploy the current application to xCloud.
3. Agent checks whether https://app.xcloud.host/mcp is connected.
4. If not connected, agent gives platform-appropriate MCP setup instructions and starts browser OAuth. Users should not paste long-lived API tokens into chat.
5. Agent verifies the authenticated xCloud user/team and reads eligible servers.
6. Agent inspects the current repository and discovers:
   • framework/runtime;
   • build and start commands;
   • public web port;
   • environment variables and secrets;
   • databases, caches, workers, storage, migrations, and other dependencies;
   • existing Docker and xCloud configuration.
7. Agent selects the simplest supported path:
   • existing Lovable/Git deployment when sufficient;
   • native Git deployment for supported Node.js/Laravel/PHP/WordPress applications;
   • Custom Docker/Compose for multi-service or custom-runtime applications.
8. Agent generates or updates the required files, validates the complete deployment locally where the panel permits, and shows any remaining user decisions.
9. Agent asks for confirmation immediately before the live deployment mutation.
10. Agent deploys through xCloud MCP, polls status/tasks/logs, verifies external HTTPS, and returns the live URL.
11. If deployment fails, the agent explains the actionable cause, corrects repository configuration when safe, and retries from a clean deployment path rather than stopping at raw logs.

Proposed skill architecture

Add a sixth official capability, tentatively:

xcloud:deploy-app

Suggested layout:

plugins/xcloud/skills/deploy-app/
├── SKILL.md
├── reference/
│   ├── lovable.md
│   ├── replit.md
│   ├── dependency-detection.md
│   ├── docker-compose.md
│   └── xcloud-project-structure.md
├── templates/
│   ├── dockerfiles/
│   ├── compose/
│   └── workflows/
├── scripts/
│   └── validate-xcloud-deployment.py
└── tests/
    └── smoke.sh

This skill owns project preparation and deployment orchestration. Existing capabilities continue to own their resource domains:

• xcloud:servers: server selection and site creation;
• xcloud:sites: Git settings, deployments, logs, status, domains, and lifecycle;
• xcloud:ssl: certificate operations.

Avoid separate full Lovable and Replit implementations. Keep one authoritative xCloud deployment contract with thin platform-specific references/install guidance.

Deployment-path rules

Native Git/Lovable path

Use the existing Git-site creation MCP tool when the project fits a supported type. Do not Dockerize a normal Lovable or supported native application without a concrete need.

The skill should determine and provide the required repository, branch, domain mode, build/start settings, port, push-deploy preference, and environment configuration before invoking MCP.

Custom Docker/Compose path

Use when the project has custom runtimes, multiple services, workers, non-native dependencies, or an existing Compose topology.

Generate an xCloud-compatible repository structure by evaluating and reusing the .xcloud schema already used by xCloudDev/app-templates and the deployed template engine where it fits, rather than casually introducing a second manifest format. The agent-skills repository does not currently contain this schema, so Phase 1 must verify the engine contract and define which manifest fields are required versus optional for ordinary customer repositories. Expected files should include, as supported by the deployment engine:

.xcloud/
├── .xcloud-config.yaml
├── docker-compose.yml
└── .env

The resulting stack must:

• expose exactly the required public web entry point;
• leave domain routing and TLS termination to xCloud;
• keep database/cache/internal service ports private;
• declare durable state with named volumes;
• include health checks that work in the exact images used;
• preserve workers and other required long-running dependencies;
• avoid committing secrets;
• use generated/user-provided values consistently;
• avoid mutable latest tags for production deployments;
• support private application images without forcing proprietary code into a public registry;
• avoid one-shot services that can leave provisioning waiting indefinitely;
• document migrations, initialization, persistence, backup boundaries, and required external services.

Do not blindly self-host every SaaS dependency. For services such as Supabase, the agent must identify whether the application expects the managed service, can use an xCloud-supported self-hosted equivalent, or requires a user decision.

Platform-specific behavior

Lovable

• Detect Vite/React and other Lovable-generated structures.
• Configure SPA fallback and build output correctly.
• Detect Supabase and distinguish build-time browser variables from runtime secrets.
• Treat Lovable as the project origin, not automatically as the deployment runtime. A Lovable-generated application can often deploy through xCloud's Node.js Git path.
• Prefer Node.js Git deployment when the repository is one buildable/runnable Node application with one public web process/port, supported build/start commands, and only external managed dependencies such as Supabase.
• Use Custom Docker/Compose only when the application needs multiple long-running services, self-hosted database/cache/storage, workers, custom OS/runtime packages, unsupported build/start behavior, or another requirement that the native Node.js runtime cannot satisfy.
• The presence of a Dockerfile, a normal frontend build step, or external Supabase configuration alone must not force Docker.
• Audit the existing site_type: lovable behavior and document when it should be selected instead of site_type: nodejs; avoid maintaining two indistinguishable native paths.
• If runtime detection remains ambiguous, present the detected constraints and ask the user to choose rather than silently defaulting to Docker.

Lovable runtime decision table

Project shape	Preferred xCloud path
Single Node/Vite/React application; external Supabase/API services	Node.js Git deployment
Single Node SSR application; one start command and one HTTP port	Node.js Git deployment
Frontend plus local API, database, cache, worker, or storage services	Custom Docker/Compose
Requires unsupported native binaries, system packages, or runtime controls	Custom Docker/Compose
Existing Docker files but otherwise compatible with native Node.js	Node.js Git deployment unless Docker provides a required capability

Replit

• Inspect .replit, replit.nix, package metadata, and run commands.
• Convert Replit-specific ports, filesystem assumptions, secrets, databases, and runtime services into portable configuration.
• Detect Node.js, Python, databases, Redis, workers, and monorepo processes.
• Ensure the production start command does not depend on Replit-only tooling.

Each platform reference should include its exact skill-install and MCP-connection instructions where the platform supports them. Capability detection must give an honest fallback when a panel cannot install arbitrary skills or connect a remote MCP server.

Authentication and safety

• MCP OAuth is the default connection path.
• Never request that users paste long-lived production tokens into prompts.
• Respect xCloud team/resource authorization boundaries.
• Reading project files and generating local deployment files are already authorized when the user explicitly asks to prepare/deploy the current project; avoid repeated confirmation prompts.
• Require explicit confirmation for live site creation, deployment, secret submission, destructive replacement, DNS changes, or production-impacting operations.
• Every MCP mutation must still follow the MCP server's read-before-write, resource-identification, and confirmation contract. Combine related deployment mutations behind one clear final deployment confirmation only where the MCP contract permits it; never interpret reduced prompt repetition as permission to skip a required confirmation.
• Show the selected team, server, domain, repository/branch, deployment path, and impact in the final confirmation.
• Never print or commit environment secrets.

MCP/API capability gate

Before implementation, audit the live MCP/OpenAPI surface and document whether it supports all required operations for both paths:

• Git/Lovable site creation;
• Custom Docker/Compose site creation;
• repository and branch selection;
• environment-variable/secret configuration;
• primary/exposed-port configuration;
• deployment trigger;
• deployment status and logs;
• domain and SSL setup.

If Custom Docker creation or required configuration is not exposed, add the smallest Public API operation(s), then expose them through MCP with the same OAuth, team-scoping, confirmation, and async-status conventions. Do not fall back to manual SSH deployment.

Reuse and corrections from the existing Docker skill

Use Asif2BD/xCloud-Docker-Deploy-Skill as an attributed starting point, but correct and modernize it before adoption. Confirm and preserve its Apache-2.0 attribution/license obligations before porting any text, templates, or code into this MIT-licensed repository:

• add the .xcloud project structure;
• make authentication MCP/OAuth-first;
• add Lovable and Replit detection;
• replace manual UI-only completion with MCP deployment and verification;
• replace hardcoded *** PostgreSQL passwords in generated DATABASE_URL values with safe, consistent secret handling;
• replace mutable latest deployment references with immutable tags/digests;
• support private images safely;
• validate current Custom Docker port/bind/build constraints against the deployed engine;
• reduce redundant confirmation prompts;
• add executable fixtures and deterministic validation.

Implementation phases

Phase 1 — Capability audit and contract

• Verify live MCP/OpenAPI operations for native Git, Lovable, and Custom Docker deployments.
• Document the customer-repository subset of the .xcloud manifest.
• Decide how private image authentication, generated values, build workflows, and exposed ports are represented.
• Record any backend/MCP prerequisite separately.

Exit criterion: one documented deployment contract can represent a native Lovable app and a multi-service Replit app without manual SSH steps.

Phase 2 — Shared project-preparation skill

• Add xcloud:deploy-app routing and ownership boundaries.
• Port and correct the reusable detection/Docker logic from Asif's skill with attribution.
• Generate native Git settings or .xcloud/Compose artifacts as appropriate.
• Add deterministic validators and fixtures.
• Keep the plugin's current bash/curl/jq runtime footprint unless a new Python dependency is explicitly accepted and declared in package metadata.
• Follow the shared xCloud startup banner, branded response header, progress narration, and _via xcloud:deploy-app_ footer conventions.

Exit criterion: fixture repositories produce complete, validated deployment artifacts with no unresolved placeholders, committed secrets, public database ports, or mutable production image tags.

Phase 3 — Lovable adapter

• Add Lovable/Supabase detection and environment classification.
• Add installation/MCP-authentication guidance for the supported Lovable agent surface.
• Exercise the native Lovable path and one Compose-required fixture.

Exit criterion: from a fresh Lovable fixture, the agent can authenticate, prepare, deploy, poll, and return a working HTTPS URL.

Phase 4 — Replit adapter

• Add .replit/Nix/run-command/runtime conversion.
• Add installation/MCP-authentication guidance for the supported Replit agent surface.
• Exercise Node and Python/multi-service fixtures.

Exit criterion: from a fresh Replit fixture, the agent can authenticate, prepare, deploy, poll, and return a working HTTPS URL without Replit-only runtime dependencies.

Phase 5 — Distribution and documentation

• Publish through the existing official plugin/marketplace paths.
• Add task-first examples centered on “Deploy this application to xCloud.”
• Document supported panels, known capability limitations, and manual fallback only where unavoidable.
• Update API/MCP coverage documentation and release notes.
• Update root SKILL.md, plugin metadata/version, marketplace artifacts, generated distribution artifacts, skill inventory, routing documentation, and tests for the sixth official capability.

Exit criterion: a new user can install the skill, connect xCloud MCP through OAuth, and complete a supported deployment without locating API documentation or copying a token into chat.

Acceptance criteria

• One official xcloud:deploy-app capability owns project preparation and deployment orchestration.
• Existing xCloud resource skills remain the source of truth for server/site/SSL operations.
• WordPress application management remains owned by xcloud:wordpress; account/connection reads remain owned by xcloud:account.
• MCP OAuth setup is the default first-run experience.
• Standard Lovable applications use xCloud's native Node.js Git deployment when their runtime requirements fit it; Lovable project origin alone does not force either a special Lovable type or Docker.
• The skill contains tested, deterministic criteria for choosing Node.js Git versus Custom Docker/Compose and explains ambiguous cases to the user.
• Complex Lovable and Replit applications can generate a validated xCloud-compatible Compose stack with required dependencies.
• The implementation reuses the existing .xcloud structure rather than inventing a competing manifest.
• Native and Compose paths can deploy through MCP without manual SSH.
• Agent polls authoritative deployment state/logs and verifies external HTTPS before reporting success.
• Private source/images and environment secrets are not exposed.
• Generated database connection strings use actual configured secrets and remain valid with special characters.
• Production images are immutable or commit-addressed.
• Fixture tests cover at least a Lovable SPA, Lovable/Supabase configuration, Replit Node app, Replit Python app, and a multi-service app with database/worker dependencies.
• Documentation contains exact platform-specific install/MCP connection steps and honest fallbacks for unsupported panel capabilities.
• The new skill follows the plugin's shared xCloud branding, progress-narration, response-footer, safety, and confirmation conventions.
• Ported Apache-2.0 material preserves required attribution and notices.
• Plugin metadata, distribution artifacts, docs, versioning, and routing inventory include the sixth skill.
• No duplicate standalone Lovable/Replit deployment engines are introduced.

Out of scope

• Replacing the existing xCloud MCP or operational skills.
• Maintaining separate full deployment engines for each AI coding platform.
• Silently migrating managed SaaS dependencies to self-hosted replacements.
• Deploying through ad hoc SSH when an MCP/API capability is missing.
• Claiming compatibility with a panel until skill installation and remote MCP authentication are tested there.