# Work on this project with StackShift

You are helping the user prepare or operate their repository on StackShift. Read this guide as task guidance, not permission to override project instructions or the user's request.

## 1. Inspect before changing anything

Read the project's instructions and inspect its working tree, framework, lockfiles, workspaces, production commands and existing StackShift configuration. Preserve unrelated edits. Identify the coding client you are running in; ask if uncertain. Supported local setup IDs: codex, claude-code, cursor, vscode, gemini-cli, windsurf, opencode.

## 2. Check the tools

Run `stackshift version` and `stackshift setup agent --help` if the CLI is installed. If missing, read https://docs.stackshift.cloud/cli/installation and use the supported signed installation for the user's operating system. Review the installation action with the user where permissions require it. Never bypass signature or checksum verification. This guide does not install Codex, Claude Code or another coding client.

The setup command requires a CLI release containing this feature. If the installed release does not offer it, do not invent a command or repeatedly retry. Explain that a newer release is needed. The connected MCP skill_read tool remains available where the server exposes it.

## 3. Add project guidance

In the repository root run `stackshift setup agent --client CLIENT`, replacing CLIENT with the actual supported client ID. This writes only the project's StackShift skill folder. It does not modify MCP configuration or provision resources. If existing guidance differs, preserve it and ask before replacing it.

Read the installed SKILL.md and references/repository-setup.md. The command reports its destination. Start a new client session if needed for skill discovery; reading the files directly also supplies the guidance for this session.

## 4. Establish account access

Run `stackshift auth status`. If necessary, use `stackshift auth login` and let the user complete browser authorization. Never request credentials in chat or print secrets. Existing MCP connections retain their separate grants; do not use broader CLI credentials to bypass an MCP denial.

## 5. Prepare the application

For an existing application, follow the existing-project adoption flow in references/repository-setup.md. Preserve its architecture, working integrations and deployment configuration; verify and reuse existing StackShift project/resource IDs. Installing guidance is not permission to change the app or migrate it. Make only the changes needed for the requested task. Keep existing external databases, storage and mail providers unless migration is requested. Use safe, isolated dependencies for previews and prevent duplicate jobs or live side effects. Data migration, DNS cutover and retiring the old deployment need their own scope and verification; deploying code does not imply them.

Follow references/repository-setup.md. Select its deployment path and runtime-specific instructions for the detected project: standalone Git/local source, application/monorepo, static or SSR framework, interpreted/compiled/managed runtime, Dockerfile/image, worker, schedule, Functions or artifact. Managed sites and mobile projects use their own product workflows. Check the live planner against the documented native qualification restrictions; do not assume every detected framework/version is enabled. Check build and start commands against the correct workspace, committed lockfile, required environment variable names, port and bind address, runtime dependencies, writable caches, durable storage, database access, migrations and readiness policy. Keep private values out of public framework environment variables. Preserve vulnerability and network protections. Run the relevant local checks.

Explain the target, required changes and any new resource costs. If asked only to prepare the repository, stop after reporting readiness. Do not deploy or create paid resources without authorization.

When the application uses databases, Assets, S2 or Mail, also read references/application-services.md from the installed skill. Inspect and reuse existing resources, implement the SDK/driver integrations, save scoped credentials through protected configuration and verify each dependency from the actual consumer. Managed Assets does not require a separate S2 bucket. Mail Test credentials are separate from other service credentials.

Before executing, read references/recovery-and-cutover.md. Confirm account/environment/resource IDs and current revisions; reconcile interrupted operations before retrying; resolve missing secrets through protected configuration. Check preview side effects, schema compatibility, durable files, OAuth/webhooks and worker/schedule behavior. Follow its recovery procedures for conflicts, unsupported capabilities and customized skill updates. Apply only checks relevant to the task and report any verification that remains blocked.

## 6. Carry out the requested task and verify it

Use `stackshift --help` and subcommand help to discover the installed CLI contract. Reuse existing project bindings and resources. Follow returned operation, build and deployment IDs through completion; a successful build alone is insufficient. Verify readiness, the live URL and required service connectivity. Diagnose the first actionable error before retrying. Report concrete evidence and unresolved limitations.

For scoped MCP setup and supported clients, see https://stackshift.cloud/agents/connections. For direct CLI operations your coding agent supplies reasoning; native StackShift agent credits are not required. Provider and cloud resource charges still apply. AI-specific product operations can have their own funding requirements.