build
Build, test, and run the service locally. This is the local development loop — no platform deployment happens here.
SKILL.mdskills/build/SKILL.md
GitHubUser Input
You MUST consider the user input before proceeding (if not empty).
Purpose
This command is the local development loop. It compiles, tests, and runs
the service locally so you can iterate quickly. No Docker images are built,
no containers are pushed, no platform deployments happen. When the service
works locally and you're ready to ship, hand off to /akka:deploy.
Outline
Compile: Use the
akka_maven_compileMCP tool to compile the project. If compilation fails, the tool returns extracted[ERROR]lines — read them, report to the user, and fix the code before proceeding.Test: Use the
akka_maven_testMCP tool to run all tests. If tests fail:- The tool returns test failure details and
[ERROR]lines - Report which tests failed and why
- Suggest fixes based on the failure messages
- Stop and hand off to
/akka:implementfor fixes
- The tool returns test failure details and
Start local environment: Use the
akka_local_startMCP tool to start the local development environment in the background. Tell the user that the local runtime is starting — it provides gRPC proxying, service discovery, trace collection and the local console onlocalhost:9889(this is not the service port). This is idempotent — if already running, tell the user it is already active and report its status.Run the service: Use
akka_local_run_serviceto start the service locally. This tool compiles first (catching errors immediately), then runsmvn exec:javain the background. Tell the user the service is launching against the local runtime.- Pass the
environmentparameter to set additional environment variables (e.g.{"LOG_LEVEL": "DEBUG", "DB_HOST": "localhost"}). These are merged with the current environment — useful for config overrides, debug flags, or connecting to external services during local development.
- Pass the
Verify: Use
akka_local_statusto confirm the service registered. Useakka_local_logswithsource: "service"to check for runtime errors. The service serves its HTTP endpoints on its own port, typicallylocalhost:9000— confirm the actual port fromakka_local_statusor the service logs rather than assuming it. Test endpoints there, not on 9889. Tell the user the service endpoint URL and whether it started successfully.Report: Summarize local build results:
- Compilation: pass/fail
- Tests: N passed, M failed
- Local service: running/failed (with endpoint URLs on the service port, typically
localhost:9000) - Next step: inspect with
/akka:inspect, iterate with/akka:implement, or ship with/akka:deploy
Error Handling
When any step fails:
- Read the error carefully —
akka_local_run_servicereturns Maven[ERROR]lines when compilation fails. Don't guess — read the actual error. - Tell the user what failed and the specific error message before attempting a fix.
- Fix the code based on the error, then retry from the failed step (not from the beginning).
- Check service logs — use
akka_local_logswithsource: "service"to read Maven/application output if the service crashes after starting. - Don't retry blindly — if the same error persists after one fix attempt, stop and ask the user for guidance.
Common Maven errors and what to do:
cannot find symbol— wrong import or missing class. Check the constitution for correct annotations and imports.package does not exist— missing dependency in pom.xml or wrong package name.port already in use— another service is running. Useakka_local_stopthen restart.
If akka_local_start reports a port conflict, ask the user whether to:
- Stop the process using that port, or
- Use a different port (pass the
portparameter toakka_local_start)
Key Rules
- This is LOCAL ONLY — do not build Docker images or deploy to the platform
- Always compile before testing
- Always test before running locally
- The local environment (akka_local_start) provides gRPC proxying and service discovery
- Report failures clearly with actionable fixes
- If the user explicitly asks to deploy, hand off to
/akka:deploy
Done When
-
akka_maven_compilereturned success — no[ERROR]lines remain unaddressed. -
akka_maven_testcompleted and every reported failure was either fixed or explicitly handed off to/akka:implement. -
akka_local_startreports the local runtime active onlocalhost:9889(idempotent — already-running is fine). - The service was launched via
akka_local_run_service; anyenvironmentoverrides requested by the user were passed through. -
akka_local_statusconfirms the service registered, andakka_local_logs(source: "service") shows no unhandled startup errors. - The report summarizes compilation (pass/fail), tests (N passed, M failed), local service status with endpoint URL on the service port (typically
localhost:9000, not the 9889 runtime port), and the next-step recommendation (/akka:inspectto inspect,/akka:implementto iterate, or/akka:deployto ship). - NO Docker image was built and NO platform deploy was attempted — this stayed strictly local.