WELCOME TO THE CREW

Give your first
gremlin a job.

ShipGremlins is an early alpha for developers who want persistent AI product managers exploring and improving their web applications.

The current automated stack is GitHub Actions, Vercel, Linear, and Claude Code. Start with an isolated test environment and a small mandate.

1. Install from source

You need Node.js 22.12 or newer and Git. Clone the public repository and check your environment:

git clone https://github.com/AgentBurgundy/shipgremlins.git
cd shipgremlins
npm ci
npm run setup -- --check

The check reports missing tools, project configuration, and secret names. It does not print your credential values or dispatch agents.

2. Initialize your configuration

Create a separate configuration directory. Replace the example repository names with your own:

npm run setup -- init --dir .run/my-gremlins \
  --hub-repo your-name/your-hub \
  --project my-app --repo your-name/my-app

The initializer preserves existing files and refuses conflicting configuration. Set SHIPGREMLINS_HOME to your configuration directory when running commands. Project setup is resumable; fill in the placeholders before enabling a schedule.

3. Connect your tools

Install a scoped GitHub App on your hub and target repositories.
Configure Vercel project and preview access, and isolate your test data.
Connect Linear and map each PM area to its project.
Provide the Claude Code credential required by the current runtime.
Register a runner with the configured label, then run the project doctor.

Read the repository's complete setup guide for commands, secret names, Docker options, and migration details.

4. Require evidence before promotion

A healthy check must match the current code revision. The controller holds ordinary work when integration health is unknown, pending, or failed. A bounded recovery lane can repair that branch.

Promotion needs trusted, revision-specific browser evidence and a passing check of the assembled candidate. A candidate branch may be prepared before verification; the staging PR stays blocked until the gate passes. Existing prose-only “verified” comments no longer authorize promotion.

Follow the verification workflow when upgrading an existing installation.

5. Keep Done honest

Implementation, QA, and staging are intermediate milestones. Use the tickets audit to inspect production inclusion; reconciliation requires a reviewed manifest and an explicit apply option. Uncertain historical mappings remain blocked.

npm run hub -- tickets audit --project my-app
npm run hub -- tickets reconcile --project my-app \
  --manifest release-manifest.json

The second command previews changes by default. Read the Linear lifecycle contract before applying a reconciliation. Also check native Linear branch automations so integration merges do not close tickets early.

Know the alpha boundaries

GitLab/Railway adapters, a full control dashboard, provider-neutral AI runtimes, and automated fixture cleanup are planned. CSV and PNG upload fixtures are available through the fixture command. The existing GCP runner path still needs live certification. The current release has focused automated tests; it is not a guarantee that every application or provider configuration has been certified.

Start with one PM, review its evidence, and expand once the workflow earns your trust. Follow the implementation roadmap or report an issue.

Give your firstgremlin a job.