Agent Skills: Aether Slice Development

Aether Slice Development

Build slices for the Aether distributed runtime using JBCT patterns.

When to Use This Skill

Activate when:

• Creating or modifying @Slice interfaces
• Working with Aether resources (@Sql, @PgSql, @Http, @Notify, streams, pub-sub, pg-notifications)
• Writing routes.toml, configuring aether.toml
• Schema migrations (schema/ directory)
• Setting up Forge for local development
• Writing k6 load tests
• Deploying and scaling slices
• Inter-slice invocation patterns
• Error modeling with sealed Cause types mapped to HTTP status codes

Delegation Model

This skill understands Aether-specific patterns. For Java code generation and review, delegate to specialized agents:

• Implementation: Use jbct-coder subagent — it knows JBCT patterns (Result/Option/Promise, factory naming, structural patterns). Provide Aether context (resource qualifiers, slice contract) in the prompt.
• Review: Use jbct-reviewer subagent — checks JBCT compliance. Supplement with Aether-specific checks (routes.toml consistency, error mapping completeness, resource wiring).
• Formatting & Linting: Use jbct CLI tool:

  jbct check src/main/java     # Format + lint (41 rules)
  jbct format src/main/java    # Format only
  jbct lint src/main/java      # Lint only
  

Quick Reference

Core Contract

• Slice Interface & Factory — @Slice, factory methods, single vs multi-method
• Error Modeling — sealed Cause types, HTTP status mapping
• Inter-Slice Invocation — dependency declaration, proxy wiring
• Step Composition — Slice → Step → Leaf with transitive provisioning

Resources

• Database: @Sql & @PgSql — generic SQL, type-safe PostgreSQL persistence
• HTTP Client: @Http — outbound HTTP with custom qualifiers
• Notifications: @Notify — email/SMS sending
• Pub-Sub Messaging — Publisher/Subscriber with custom qualifiers
• Streaming — partitioned, ordered, replayable streams
• PG LISTEN/NOTIFY — real-time database change notifications
• Configuration — config provisioning, secrets, dynamic updates
• Custom Qualifiers — defining your own @ResourceQualifier annotations

Deployment & Testing

• HTTP Routing: routes.toml — route mapping, error codes
• Schema Migrations — Flyway-style, multi-datasource
• Forge & Local Development — run-forge.sh, PostgreSQL, dashboard
• k6 Load Testing — steady-state, ramp-up, spike patterns
• Deployment & Scaling — blueprint, CLI, strategies
• Configuration Reference — full aether.toml reference

Important Notes

• @Codec is NOT needed on slice types. The slice processor generates serialization codecs automatically.
• All slice methods must return Promise<T>.
• Pub-Sub, Streaming, PG LISTEN/NOTIFY, and most scheduled tasks use @ResourceQualifier custom annotations — no shortcut annotations (exception: @Heartbeat is the built-in shortcut for the heartbeat scheduled task).
• Built-in shortcut annotations: @Sql (database), @PgSql (PostgreSQL persistence; also usable on a @Query interface TYPE), @Http (HTTP client), @Notify (notifications), @Jooq (jOOQ connector), @Heartbeat (heartbeat scheduled task, method-level).

Self-Validation Checkpoint

Before considering a slice complete:

Slice Contract

• [ ] Interface annotated with @Slice
• [ ] Factory method: lowercase-first name matching interface
• [ ] All methods return Promise<T>
• [ ] Request/Response records nested in interface
• [ ] Error types as sealed Cause hierarchy

Routing

• [ ] routes.toml exists with prefix, routes, and error mapping
• [ ] All public methods have routes
• [ ] All error types have HTTP status mappings
• [ ] default error status defined (typically 500)

Resources

• [ ] All resource qualifiers have matching aether.toml config sections
• [ ] Secrets use ${secrets:path} (not hardcoded)
• [ ] Database connections pooled (default config sufficient)

Schema

• [ ] Migration files in schema/ if using @Sql or @PgSql
• [ ] Sequential version numbers (V001__, V002__)
• [ ] Idempotent where possible (CREATE IF NOT EXISTS)

Testing

• [ ] Unit tests for validation, happy path, failure cases
• [ ] jbct check passes (format + 41 lint rules)
• [ ] Forge smoke test with curl
• [ ] k6 steady-state test at expected load

JBCT Compliance

Delegate to jbct-reviewer for thorough check, or run:

jbct lint src/main/java