Guidance for autonomous coding agents working in this repository.
- Project:
ocp(OpenCode Configuration Profiles CLI) - Stack: Java 25, Micronaut 4.x, Picocli, Gradle Kotlin DSL, JUnit 5
- Packaging: single-module Gradle application
- Main class:
com.github.alvarosanchez.ocp.command.OcpCommand - Source root package:
com.github.alvarosanchez.ocp - Behavior contract:
SPEC.mdis the product truth source
- Cursor rules: no
.cursorrulesand no.cursor/rules/**found - Copilot rules: no
.github/copilot-instructions.mdfound - If these files are added later, treat them as higher-priority agent instructions
Run from repo root: /Users/alvaro/Dev/alvarosanchez/ocp.
- Build:
./gradlew build - Full verification:
./gradlew check - JVM tests:
./gradlew test - Native binary compile:
./gradlew nativeCompile - Native tests:
./gradlew nativeTest - Show CLI help through Gradle app plugin:
./gradlew run --args="help"
- One class:
./gradlew test --tests com.github.alvarosanchez.ocp.service.ProfileServiceTest
- One method:
./gradlew test --tests com.github.alvarosanchez.ocp.service.ProfileServiceTest.getAllProfilesReturnsSortedUniqueNames
- Pattern selection:
./gradlew test --tests "*ProfileCommandTest*"
- List tasks:
./gradlew tasks --all - Compile only (quick type-check proxy):
./gradlew compileJava - Clean outputs:
./gradlew clean
- No dedicated lint task is configured in
build.gradle.kts - No Spotless / PMD / Gradle Checkstyle plugin is configured
- IntelliJ Checkstyle plugin config exists at
.idea/checkstyle-idea.xml - Practical quality baseline for agents:
./gradlew check
- Production Java:
src/main/java/com/github/alvarosanchez/ocp/** - Tests:
src/test/java/com/github/alvarosanchez/ocp/** - Resources:
src/main/resources/** - Build config:
build.gradle.kts,settings.gradle.kts,gradle/libs.versions.toml - Product spec and acceptance criteria:
SPEC.md
command/: Picocli commands, argument handling, exit-code orchestration, user messagesservice/: domain logic and orchestration across repositories/profilesgit/: externalgitprocess execution wrappersconfig/: serde models for registry/repository metadata filesmodel/: immutable read models for command rendering
Rule of thumb: keep command classes thin; move business logic to services.
- 4-space indentation, braces on same line
- Prefer straightforward loops/conditionals over clever abstractions
- Keep methods readable; extract helpers for repeated logic
- Avoid wildcard imports
- Standard ordering in this repo is mixed; preserve local file ordering style
- Use explicit imports; static imports are common in tests for assertions
- Avoid introducing unused imports and large import churn
- Prefer
recordfor DTO/config projections (config/,model/, and local helper records) - Normalize immutable collections with
List.copyOf/Set.copyOf/List.of - Use
finalclasses for core services and utility types when extension is not intended - Default to package-private constructors/methods unless API must be public
- Types/records/enums:
PascalCase - Methods/fields/locals:
camelCase - Constants:
UPPER_SNAKE_CASE - Tests: descriptive
camelCasemethod names - Command names and messages should align with
SPEC.mdCLI terminology
- Public classes and public methods generally include Javadoc
- Preserve this standard when adding new public API surface
- Keep Javadoc concise and behavior-focused (params, return, failure mode)
- Never swallow exceptions silently
- Wrap I/O failures with context (
UncheckedIOExceptionorIllegalStateException) - Include operation and path/URI in exception messages where possible
- For
InterruptedException, always restore interrupt status withThread.currentThread().interrupt() - Commands catch domain/runtime exceptions, print to
stderr, and return non-zero
- Success/info output uses
stdout - Errors use
stderr - Expected exit codes:
0: success1: runtime/validation failure2: command usage error
- Root/group commands should print usage/help when no subcommand is provided
- Stateless services/clients use
@Singleton - Prefer constructor injection (including package-private constructors)
- Keep constructors dependency-only and avoid side effects
- JUnit 5 platform (
useJUnitPlatform()) @TempDiris standard for filesystem isolation- Use explicit setup/teardown for system properties in tests
- Validate both behavior and CLI contract (exit code + stdout/stderr content)
- Keep tests deterministic and independent
- Use private helper methods inside each test class for fixtures
- Default registry file:
~/.config/ocp/config.json - Default repository storage root:
~/.config/ocp - Default OpenCode config target:
~/.config/opencode - Common system property overrides:
ocp.config.dirocp.cache.dir(legacy storage override)ocp.opencode.config.dirocp.working.dir
- Read nearby classes in the same package and related tests first
- Check
SPEC.mdacceptance criteria for user-visible behavior changes - Keep changes minimal, cohesive, and scoped to the request
- Before making any file edits, create and switch to a dedicated working branch (for example
git checkout -b agent/<topic>); never start work onmasterormain. - Never create test repositories, fixture directories, or nested git repositories inside the project working tree; use
@TempDiror system temporary directories outside the checkout instead unless the user explicitly requests an in-repo fixture.
- Minimum verification:
./gradlew test - If startup/native-sensitive behavior changed:
./gradlew nativeTest - If wiring/build behavior changed:
./gradlew build - If CLI or other user-visible behavior changed, update
SPEC.mdand the affected user-facing documentation in the same change set (site docs undersite/src/content/docs/**, plusREADME.mdwhen landing-page messaging or quickstart guidance changes). - Ask the user if they want to create a PR with the "gh" CLI. If granted permission, create it.
- Do not merge the PR until GitHub Copilot has posted its review on that PR.
- Address every Copilot review comment, and confirm there are no unresolved Copilot comments.
- If Copilot review is still pending or missing, keep waiting and polling; do not merge yet.
- After Copilot comments are resolved, monitor CI checks and merge only when required checks pass.
- If CI fails, investigate failures and fix them before merging.
Do:
- Keep architecture boundaries intact (
commandthin,servicerich) - Add or update tests for behavior changes
- Preserve transactionality and rollback behavior in profile switch flows
- Keep user-facing error messages actionable and context-rich
Don't:
- Add unrelated refactors in bugfix changes
- Introduce silent failure paths or empty catches
- Add dependencies without clear need
- Change documented behavior without updating
SPEC.md - Hardcode dependencies in the build script (use the version catalog instead)
- Commit or push unless explicitly requested by the user