Setup Runtime

Rules

• Declared runtime config is wrong until verified. /init guessed; /setup-runtime observes.
• Ask questions in plain text, one line answerable, grouped logically. No checkbox tools.
• Never rm -rf; ask the developer to delete files/dirs.
• Never modify business or test code without presenting a diff and getting confirmation.
• Build, CI, and environment configuration fixes (dependency declarations, build flags, run profiles) may be applied directly, but record them in docs/agents/runtime.md.
• BUILD SUCCESS means success. Plugin/warning noise is not failure.
• The app is "ready" when its logs say so; if the signal isn't obvious, ask. Don't assume a curl endpoint.
• When a fact cannot be observed, ask how, not what (source of secrets, never the value).
• Environment variables are configuration; surface all that influence runtime.
• When in doubt, ask — never assume silently.

Execution

Phase 0: Scope detection

• Auto-detect language, build system, framework, monorepo structure from files.
• If ambiguous (multiple apps, monorepo), ask: "Which part are you working on?"
• Confirm the project type (web app, CLI, library) before proceeding.

Phase 1: Inventory

Read docs/agents/runtime.md (the previous run's output, if it exists) and ask the user for any runtime facts they already know (port, profile, build command, test command). Treat all of them as declared claims to verify, not as facts.

Also read any runtime claims in the project's memory file (CLAUDE.md if it exists, else AGENTS.md) — output from /init or hand-written notes. Read-only: memory files are never written by this skill; their claims are suspect input like any other.

Tailor discovery to project type:

• Web app: Port, profiles/env configs, secrets sources, DB URLs, external service URLs, build prerequisites, health endpoints.
• CLI tool: Required args, env vars, file system access, outbound network calls.
• Library: Build/test commands, test dependencies (DB, docker), publish credentials location.

Output a comparison table. Every declared claim goes in one column; the discovered fact goes in the other. Flag mismatches.

Example (web app):

Claim (previous run / user)	Discovered	Match?
Port: 8080	Port: 8102 (local profile)	❌
Start: ./mvnw spring-boot:run	Start: ./mvnw spring-boot:run -Denv.config=local	❌
Jasypt: needs -D flag	Jasypt password in yaml	❌
Actuator health endpoint	No actuator on classpath	❌

No table if there are no declared claims — just list what was discovered.

Phase 2: Reconcile

Resolve each discrepancy with the developer. Be specific — point to the exact claim that conflicts.

"The previous runtime config says the app runs on port 8080 with no profile flag. I found application-local.yaml with port 8102, and application-dev.yaml with port 8080. Which is correct for local development?"

"The previous runtime config says -Djasypt.encryptor.password is required. I found the password in application-local.yaml — no -D flag needed for local. Confirm?"

For facts not already declared, ask:

• Which config/profile for local dev?
• How do you connect to remote DBs/services (VPN, tunnel, local mock)?
• How are secrets provided? (ask for source only)
• Any wrapper scripts, env tools (direnv), or proxies that affect the app?

Phase 3: Build

1. Detect or ask for the build command.
2. Run it.
3. BUILD SUCCESS → record command and timing.
4. BUILD FAILURE → present error, ask how to proceed.
5. Locked build dirs → ask developer to delete.

Phase 4: Start & Verify

1. Build the start command from reconciled facts (profile, port, env vars).
2. Ask: "Any env vars to set before starting?"
3. Kill any process on target port (after asking).
4. Start. Watch output for the "ready" signal. If unclear, ask what to look for.

"Application started on port 8102 in 13.4 seconds. Ready."

5. Failure: present error, let developer direct. Do not diagnose silently.

Phase 5: Dev Loop Verification

Goal: Verify the inner dev loop (change → test → result) works. A project that builds and starts but can't run tests is not fully set up.

Step 1: Detect the test command

Derive from the build system detected in Phase 0:

If the detection is ambiguous, ask: "What command runs your tests?"

Windows pwsh note: replace ./mvnw with .\mvnw.cmd (or mvn) and ./gradlew with .\gradlew.bat (or gradle).

Step 2: Check for existing tests

1. Look for a test directory (src/test/, tests/, __tests__/, test/, etc.)
2. Verify test sources compile (derive from the build system: ./mvnw test-compile, ./gradlew compileTestJava, go build ./..., tsc --noEmit, python -m py_compile). Skip for interpreted languages with no compile step.
3. If compile fails → diagnose. If the fix requires business or test code changes, present a diff and ask before modifying. Build/CI/environment fixes can be applied directly and must be recorded as a Known Issue or Note.

Step 3: Run the tests

Run the full test suite. Profile/configuration flags that were needed for Phase 3-4 should be reused here.

Three possible outcomes:

A. Tests pass (all green) → Record DEV_READY level. Move on.

B. Tests fail

Diagnose with a timebox (3 attempts or ~10 min, whichever comes first):

1. Is it an infrastructure issue? (classpath, forking, missing system property, logging config, DB connection)
   • Try the simplest fix: add build-system-appropriate flags (e.g. -DforkCount=0 for Maven Surefire, --no-parallel for Gradle, env vars for DB)
   • If fixed → record the required flag in Known Issues
   • If not fixed in 3 attempts → record as Known Issue, mark BOOT_AND_API, stop diagnosing
2. Is it a missing test dependency? (test DB not seeded, Docker not running, external service unreachable)
   • Record as Known Issue
   • If the developer can resolve quickly, wait and re-run
   • Otherwise mark BOOT_AND_API
3. Is it a code bug? (compilation error in test, logic failure)
   • Record as Known Issue
   • Do NOT fix — this is not /setup-runtime's job

C. No tests exist

Do NOT silently skip. This is a finding worth recording.

1. Generate a minimal smoke test that verifies the application can initialize:
   • Web app: context-load / app-factory-instantiates test
   • CLI: argument-parser-help-flag test
   • Library: import-and-instantiate test
   • Script: parse-with-sample-input test
2. Present the smoke test as a diff and ask before creating the file.
3. Run it. If green → record BOOT_AND_TESTABLE with note "No existing tests; smoke test generated at <path>"
4. If the generated test fails → diagnose (2 attempts max), record Known Issue, mark BOOT_AND_API

Step 4: Record test results

Always write findings (see Phase 7). Include:

• Test command used
• Results (X pass / Y fail / Z skipped)
• Any flags needed (e.g. -DforkCount=0)
• Known Issues for any failures

Phase 6: Stop

Kill process, verify port freed.

Phase 7: Record

Always write, even if verification was incomplete. Record what was observed; mark the rest.

One output — docs/agents/runtime.md is the source of truth:

docs/agents/runtime.md — the full record. Create the file if missing; if it exists, overwrite it in place (it is /setup-runtime's own file, not a shared document). First line declares who must read it.

Verification levels

Use one of these levels based on what was observed:

Tag each fact:

• [FULL] — observed this session (build, start, port, test run).
• [PARTIAL] — confirmed by developer but not directly observed.

docs/agents/runtime.md structure:

# Runtime Configuration (last verified: YYYY-MM-DD)

> Agents must read this file before starting the app. Generated by /setup-runtime.

**Verification level**: DEV_READY

### Local run
Profile: dev (port 8080, H2) [FULL]
Start: ./mvnw spring-boot:run -Dspring-boot.run.profiles=dev [FULL]
Secrets: .env.local loaded by IDE plugin [PARTIAL]

### Test
Command: ./mvnw test -Denv.config=local -DforkCount=0 [FULL]
Results: 5 tests, 5 pass, 0 fail [FULL]
Note: requires -DforkCount=0 on Windows (Surefire IsolatedClassLoader issue)

### Prerequisites
- MariaDB at <team-db-host>:3306 (VPN required) [PARTIAL]
- Java 17 [FULL]

### Notes
- `dev` profile uses remote DB — do not use `local` for development
- Always `clean compile` (MapStruct)

### Test Known Issues
- **Logback classpath**: `logging.config=classpath:logback-local.xml` not found in Surefire forked JVM. Workaround: `-DforkCount=0`. Root cause TBD.
- **MapStruct stale files**: `mvn clean` on Windows may leave locked files in `target/generated-sources/`. Workaround: manually delete `target/` before clean build.

If PARTIAL:

| Step    | Status | Detail                                        |
| ------- | ------ | --------------------------------------------- |
| Build   | ✅     | ./mvnw clean compile -Denv.config=local (2m)  |
| Start   | ✅     | Port 8102, 23s startup                        |
| Test    | ❌     | Logback config not found in forked JVM (see Known Issues) |

**To complete**: fix test classpath issue, then re-run /setup-runtime.

When tests fail and cannot be fixed within the timebox, include the failures in the ### Test Known Issues section of docs/agents/runtime.md (see structure above).