---
name: configure-spinnery
description: Inspect a repository and create or repair the smallest valid spinnery.yml for a Spinnery service. Use when connecting a repository to Spinnery, resolving setup_required or invalid service readiness, declaring a Compose preview, wiring cross-service inputs and outputs, or validating a proposed Spinnery setup PR.
---

# Configure Spinnery

Use the public setup guide as the schema source of truth:
https://spinnery.dev/docs/service-setup. If it is unavailable, read the bundled
offline fallback at `references/manifest.md` before editing.

## Workflow

1. Inspect the working tree before editing. Preserve unrelated changes.
2. Read repository evidence: Compose files and resolved services, Dockerfiles, package manifests and scripts, lockfiles, tracked `.env.development` and env example files, and any existing `spinnery.yml`. Use only variable names from `.env.development`; treat every value in it as sensitive. Example, sample, and template files may supply clearly safe placeholder or development defaults, but never copy ambiguous or credential-like values. Never read untracked `.env` files, production environment files, credential files, private keys, or secret stores.
3. Keep runtime facts in Compose and Dockerfiles. Write `version: 1` and add only the smallest Spinnery contract the evidence supports. Do not introduce version 2; the CLI accepts it only so existing legacy manifests can migrate. Do not invent commands, ports, service names, framework conventions, development bypasses, or fallback behavior.
4. For cross-repo wiring, declare the consumer need under `inputs`, map it under `environment`, and expose provider values under `outputs`. Never add cross-repo `depends_on` references.
5. Configure the repository's documented normal development mode. Trace checked-in feature flags, local switches, fallbacks, and conditional validation before deciding a credential is required. When evidence proves a safe development mode disables an external integration, set that mode and do not require the unused production credential. A referenced variable is not automatically required. Mark a secret `required: false` only when the service boots and its normal development workflow works without that integration.
6. Never write secret values. Do not copy credentials from local config, shell output, or secret stores into the manifest or response.
7. Run `spin validate` from the repository root. Use `spin validate <manifest-or-repo-path> --json` when explicit or machine-readable output helps. The command requires Docker Compose v2 and checks the manifest, selected Compose file, resolved preview service names, strict boolean fields, and declared `input.*` references. If Docker Compose or the command is unavailable, report validation as blocked and run the manual checks in the public guide or bundled fallback; do not claim success.
8. Manually confirm that preview ports match the running applications, required inputs have same-name outputs from selected sibling services or explicit project bindings, required secrets are needed by the normal development workflow, no secret values entered the diff, and optional commands come from repository evidence.
9. Show the validation result and final diff. Explain any evidence that remains ambiguous.

Do not commit, push, or open a pull request unless the user explicitly requests it. If requested, include only the intended setup changes and report the validation result with the commit or PR.