agentic-team-templates 0.13.1 → 0.14.0

package/templates/java-expert/.cursorrules/overview.md

@@ -0,0 +1,81 @@
+# Java Expert Overview
+
+Principal-level Java engineering. Deep JVM knowledge, modern language features, and production-grade patterns.
+
+## Scope
+
+This guide applies to:
+- Web services and APIs (Spring Boot, Quarkus, Micronaut)
+- Microservices and distributed systems
+- Event-driven architectures (Kafka, RabbitMQ)
+- Batch processing and data pipelines
+- Libraries and Maven/Gradle artifacts
+- Cloud-native applications (Kubernetes, GraalVM native images)
+
+## Core Philosophy
+
+Java's strength is its ecosystem maturity and runtime reliability. The best Java code is clear, testable, and boring.
+
+- **Readability over cleverness.** A junior engineer should understand your code without a tutorial.
+- **Immutability by default.** Records, `final` fields, unmodifiable collections. Mutation is the exception.
+- **Composition over inheritance.** Interfaces, delegation, and dependency injection — not deep class hierarchies.
+- **The JVM is your ally.** Understand garbage collection, JIT compilation, and memory model — don't fight them.
+- **Fail fast, fail loud.** Validate at boundaries, throw meaningful exceptions, never swallow errors.
+- **If you don't know, say so.** Admitting uncertainty is professional. Guessing at JVM behavior you haven't verified is not.
+
+## Key Principles
+
+1. **Modern Java Is Required** — Java 21+ features: records, sealed classes, pattern matching, virtual threads
+2. **Null Is a Bug** — Use `Optional` for return types, `@Nullable`/`@NonNull` annotations, and validation at boundaries
+3. **Dependency Injection Is the Architecture** — Constructor injection, interface segregation, Spring's application context
+4. **Tests Are Documentation** — Descriptive names, Arrange-Act-Assert, behavior over implementation
+5. **Observability Is Not Optional** — Structured logging, metrics, distributed tracing from day one
+
+## Project Structure
+
+```
+project/
+├── src/main/java/com/example/myapp/
+│   ├── Application.java              # Entry point
+│   ├── config/                        # Configuration classes
+│   ├── domain/                        # Core domain (no framework deps)
+│   │   ├── model/                     # Entities, value objects, records
+│   │   ├── service/                   # Domain services
+│   │   └── event/                     # Domain events
+│   ├── application/                   # Use cases, orchestration
+│   │   ├── command/                   # Write operations
+│   │   ├── query/                     # Read operations
+│   │   └── port/                      # Interfaces (driven/driving)
+│   ├── infrastructure/                # External concerns
+│   │   ├── persistence/               # JPA repositories, entity mappings
+│   │   ├── messaging/                 # Kafka/RabbitMQ producers/consumers
+│   │   └── client/                    # HTTP clients, external APIs
+│   └── api/                           # REST controllers, DTOs
+│       ├── controller/
+│       ├── dto/
+│       └── exception/                 # Exception handlers
+├── src/main/resources/
+│   ├── application.yml
+│   └── db/migration/                  # Flyway/Liquibase migrations
+├── src/test/java/com/example/myapp/
+│   ├── unit/
+│   ├── integration/
+│   └── architecture/
+├── pom.xml or build.gradle.kts
+└── Dockerfile
+```
+
+## Definition of Done
+
+A Java feature is complete when:
+
+- [ ] Code compiles with zero warnings (`-Xlint:all -Werror`)
+- [ ] All tests pass (`mvn verify` or `gradle check`)
+- [ ] No SpotBugs/ErrorProne findings
+- [ ] No SonarQube code smells or security hotspots
+- [ ] Null safety enforced (no raw `null` returns from public APIs)
+- [ ] Javadoc on all public classes and methods
+- [ ] Error paths are tested
+- [ ] Thread safety verified for shared mutable state
+- [ ] No `TODO` without an associated issue
+- [ ] Code reviewed and approved

package/templates/java-expert/.cursorrules/performance.md

@@ -0,0 +1,239 @@
+# Java Performance
+
+The JVM is a world-class runtime. Understand it, don't fight it. Measure first.
+
+## Profile Before Optimizing
+
+```bash
+# JFR (Java Flight Recorder) — production-safe profiling
+java -XX:StartFlightRecording=filename=recording.jfr,duration=60s -jar app.jar
+
+# Async-profiler — low-overhead sampling
+./asprof -d 30 -f profile.html <pid>
+
+# JVM flags for diagnostics
+-XX:+PrintGCDetails -XX:+PrintGCDateStamps -Xlog:gc*:file=gc.log
+```
+
+### Diagnostic Tools
+
+| Tool | Purpose |
+|------|---------|
+| JFR + JMC | Production profiling (CPU, memory, I/O, locks) |
+| async-profiler | Low-overhead CPU/allocation profiling |
+| JMH | Micro-benchmarks with statistical rigor |
+| jcmd | Runtime diagnostics (heap dump, thread dump) |
+| VisualVM | Real-time monitoring |
+
+## JMH Benchmarks
+
+```java
+@BenchmarkMode(Mode.AverageTime)
+@OutputTimeUnit(TimeUnit.NANOSECONDS)
+@State(Scope.Benchmark)
+@Warmup(iterations = 5, time = 1)
+@Measurement(iterations = 5, time = 1)
+public class StringConcatBenchmark {
+
+    private List<String> items;
+
+    @Setup
+    public void setup() {
+        items = IntStream.range(0, 1000)
+            .mapToObj(Integer::toString)
+            .toList();
+    }
+
+    @Benchmark
+    public String concatenation() {
+        var result = "";
+        for (var item : items) result += item;
+        return result;
+    }
+
+    @Benchmark
+    public String stringBuilder() {
+        var sb = new StringBuilder();
+        for (var item : items) sb.append(item);
+        return sb.toString();
+    }
+
+    @Benchmark
+    public String stringJoin() {
+        return String.join("", items);
+    }
+}
+```
+
+## GC Tuning
+
+```bash
+# G1GC (default, good for most workloads)
+-XX:+UseG1GC
+-XX:MaxGCPauseMillis=200
+
+# ZGC (ultra-low latency, Java 21+ production-ready)
+-XX:+UseZGC
+-XX:+ZGenerational  # Generational ZGC (Java 21+)
+
+# Heap sizing
+-Xms2g -Xmx2g      # Fixed heap size (no resize pauses)
+-XX:+AlwaysPreTouch # Touch memory pages at startup
+```
+
+### GC Rules
+
+- Start with G1GC defaults — they're good
+- Use ZGC if you need < 1ms pause times
+- Set `-Xms` = `-Xmx` for predictable behavior
+- Monitor with JFR, not gut feeling
+
+## Memory Patterns
+
+### Avoid Unnecessary Allocations
+
+```java
+// Bad: autoboxing in hot loops
+long sum = 0;
+for (Integer value : integerList) {
+    sum += value; // Unboxing on every iteration
+}
+
+// Good: use primitive streams
+long sum = integerList.stream().mapToLong(Integer::longValue).sum();
+
+// Bad: intermediate collections
+var result = users.stream()
+    .map(User::name)
+    .collect(Collectors.toList()) // Intermediate list
+    .stream()
+    .filter(n -> n.startsWith("A"))
+    .toList();
+
+// Good: single pipeline
+var result = users.stream()
+    .map(User::name)
+    .filter(n -> n.startsWith("A"))
+    .toList();
+```
+
+### String Optimization
+
+```java
+// String.intern() for repeated strings (use carefully — fills PermGen/Metaspace)
+// Better: use enum or constants for known string sets
+
+// StringBuilder for complex concatenation
+var sb = new StringBuilder(256); // Pre-size if length is known
+for (var item : items) {
+    sb.append(item.name()).append(": ").append(item.value()).append('\n');
+}
+return sb.toString();
+```
+
+### Collection Sizing
+
+```java
+// Pre-size collections when capacity is known
+var map = new HashMap<String, User>(expectedSize * 4 / 3 + 1); // Account for load factor
+var list = new ArrayList<User>(expectedSize);
+
+// Use specialized collections
+EnumMap<Status, List<Order>> byStatus = new EnumMap<>(Status.class);
+EnumSet<Permission> permissions = EnumSet.of(READ, WRITE);
+```
+
+## Connection Pooling (HikariCP)
+
+```yaml
+spring:
+  datasource:
+    hikari:
+      maximum-pool-size: 10         # Default is fine for most apps
+      minimum-idle: 5
+      idle-timeout: 300000          # 5 minutes
+      connection-timeout: 30000     # 30 seconds
+      max-lifetime: 1800000         # 30 minutes
+      leak-detection-threshold: 60000  # 1 minute — detect leaked connections
+```
+
+### Pool Sizing Rule
+
+Formula: `connections = (core_count * 2) + effective_spindle_count`
+For SSDs: `connections ≈ core_count * 2`
+
+Most apps need 10-20 connections. More is rarely better.
+
+## HTTP Client Performance
+
+```java
+// Shared HttpClient instance with connection pooling
+private static final HttpClient HTTP_CLIENT = HttpClient.newBuilder()
+    .connectTimeout(Duration.ofSeconds(5))
+    .executor(Executors.newVirtualThreadPerTaskExecutor())
+    .build();
+
+// Or with Spring: RestClient / WebClient (reuse instances)
+@Bean
+public RestClient restClient(RestClient.Builder builder) {
+    return builder
+        .baseUrl("https://api.example.com")
+        .requestFactory(new JdkClientHttpRequestFactory(HTTP_CLIENT))
+        .defaultHeader(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE)
+        .build();
+}
+```
+
+## Caching
+
+```java
+// Spring Cache with Caffeine (in-process)
+@Configuration
+@EnableCaching
+public class CacheConfig {
+    @Bean
+    public CacheManager cacheManager() {
+        var caffeine = Caffeine.newBuilder()
+            .maximumSize(10_000)
+            .expireAfterWrite(Duration.ofMinutes(10))
+            .recordStats();
+
+        var manager = new CaffeineCacheManager();
+        manager.setCaffeine(caffeine);
+        return manager;
+    }
+}
+
+@Cacheable(value = "users", key = "#id")
+public Optional<User> findById(UUID id) {
+    return userRepository.findById(id);
+}
+
+@CacheEvict(value = "users", key = "#user.id")
+public void update(User user) {
+    userRepository.save(user);
+}
+```
+
+## Anti-Patterns
+
+```java
+// Never: premature optimization without profiling
+// "I think this is slow" — prove it with JMH or JFR
+
+// Never: creating threads manually
+new Thread(() -> process(item)).start(); // No lifecycle management, no error handling
+// Use ExecutorService or virtual threads
+
+// Never: synchronizing on string literals
+synchronized ("lock") { } // String interning means unexpected sharing
+// Use: private final Object lock = new Object();
+
+// Never: reflection in hot paths
+method.invoke(target, args); // Orders of magnitude slower than direct calls
+// Use interfaces and polymorphism
+
+// Never: unbounded caches
+private final Map<String, Object> cache = new HashMap<>(); // Grows forever → OOM
+// Use Caffeine with eviction policies
+```

package/templates/java-expert/.cursorrules/persistence.md

@@ -0,0 +1,262 @@
+# Java Persistence
+
+JPA/Hibernate done right, JDBC when you need control, and database patterns that scale.
+
+## JPA Entity Design
+
+```java
+@Entity
+@Table(name = "orders")
+public class Order {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    private UUID id;
+
+    @Column(nullable = false)
+    private String customerId;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false)
+    private OrderStatus status;
+
+    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
+    private List<OrderItem> items = new ArrayList<>();
+
+    @Version
+    private Long version; // Optimistic locking
+
+    @CreationTimestamp
+    private Instant createdAt;
+
+    @UpdateTimestamp
+    private Instant updatedAt;
+
+    // Protected no-arg constructor for JPA
+    protected Order() {}
+
+    // Factory method with validation
+    public static Order create(String customerId, List<OrderItem> items) {
+        Objects.requireNonNull(customerId, "customerId is required");
+        if (items.isEmpty()) throw new IllegalArgumentException("Order must have items");
+
+        var order = new Order();
+        order.customerId = customerId;
+        order.status = OrderStatus.PENDING;
+        items.forEach(order::addItem);
+        return order;
+    }
+
+    public void addItem(OrderItem item) {
+        items.add(item);
+        item.setOrder(this);
+    }
+
+    // Getters only — no public setters for domain-relevant fields
+    public UUID getId() { return id; }
+    public OrderStatus getStatus() { return status; }
+    public List<OrderItem> getItems() { return Collections.unmodifiableList(items); }
+}
+```
+
+## Repository Pattern
+
+```java
+// Spring Data JPA — let the framework generate implementations
+public interface OrderRepository extends JpaRepository<Order, UUID> {
+
+    // Derived query
+    List<Order> findByCustomerIdAndStatus(String customerId, OrderStatus status);
+
+    // JPQL for complex queries
+    @Query("""
+        SELECT o FROM Order o
+        JOIN FETCH o.items
+        WHERE o.customerId = :customerId
+        ORDER BY o.createdAt DESC
+        """)
+    List<Order> findWithItemsByCustomerId(@Param("customerId") String customerId);
+
+    // Native query when JPQL isn't enough
+    @Query(value = """
+        SELECT o.* FROM orders o
+        WHERE o.created_at > :since
+          AND o.status = 'PENDING'
+        FOR UPDATE SKIP LOCKED
+        LIMIT :limit
+        """, nativeQuery = true)
+    List<Order> findPendingForProcessing(
+        @Param("since") Instant since,
+        @Param("limit") int limit);
+
+    // Projections for read-only queries
+    @Query("""
+        SELECT new com.example.dto.OrderSummary(o.id, o.status, o.createdAt, SIZE(o.items))
+        FROM Order o
+        WHERE o.customerId = :customerId
+        """)
+    Page<OrderSummary> findSummariesByCustomerId(
+        @Param("customerId") String customerId, Pageable pageable);
+}
+```
+
+## Transaction Management
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OrderService {
+
+    private final OrderRepository orderRepository;
+    private final PaymentService paymentService;
+    private final TransactionTemplate txTemplate;
+
+    // Declarative — for simple cases
+    @Transactional
+    public Order create(CreateOrderRequest request) {
+        var order = Order.create(request.customerId(), request.items());
+        return orderRepository.save(order);
+    }
+
+    // Read-only transactions — enables optimizations
+    @Transactional(readOnly = true)
+    public Optional<Order> findById(UUID id) {
+        return orderRepository.findById(id);
+    }
+
+    // Programmatic — for fine-grained control
+    public OrderResult processOrder(UUID orderId) {
+        // Step 1: Update order status (transactional)
+        var order = txTemplate.execute(status -> {
+            var o = orderRepository.findById(orderId)
+                .orElseThrow(() -> new NotFoundException("Order: " + orderId));
+            o.markProcessing();
+            return orderRepository.save(o);
+        });
+
+        // Step 2: Call external payment (non-transactional)
+        var paymentResult = paymentService.charge(order);
+
+        // Step 3: Update with result (new transaction)
+        return txTemplate.execute(status -> {
+            if (paymentResult.isSuccess()) {
+                order.markPaid(paymentResult.transactionId());
+            } else {
+                order.markFailed(paymentResult.errorMessage());
+            }
+            orderRepository.save(order);
+            return OrderResult.from(order);
+        });
+    }
+}
+```
+
+## N+1 Query Prevention
+
+```java
+// Bad: lazy loading in a loop
+var orders = orderRepository.findAll(); // 1 query
+for (var order : orders) {
+    order.getItems().size(); // N queries!
+}
+
+// Good: JOIN FETCH
+@Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.status = :status")
+List<Order> findWithItemsByStatus(@Param("status") OrderStatus status);
+
+// Good: @EntityGraph
+@EntityGraph(attributePaths = {"items", "customer"})
+List<Order> findByStatus(OrderStatus status);
+
+// Good: DTO projection (best performance)
+@Query("""
+    SELECT new com.example.dto.OrderSummary(o.id, o.status, SIZE(o.items))
+    FROM Order o WHERE o.status = :status
+    """)
+List<OrderSummary> findSummariesByStatus(@Param("status") OrderStatus status);
+```
+
+## Database Migrations (Flyway)
+
+```sql
+-- V1__create_orders_table.sql
+CREATE TABLE orders (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    customer_id VARCHAR(255) NOT NULL,
+    status      VARCHAR(50) NOT NULL DEFAULT 'PENDING',
+    version     BIGINT NOT NULL DEFAULT 0,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_orders_customer_id ON orders(customer_id);
+CREATE INDEX idx_orders_status ON orders(status);
+
+-- V2__add_order_items_table.sql
+CREATE TABLE order_items (
+    id       UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    order_id UUID NOT NULL REFERENCES orders(id) ON DELETE CASCADE,
+    sku      VARCHAR(100) NOT NULL,
+    quantity INT NOT NULL CHECK (quantity > 0),
+    price    NUMERIC(10, 2) NOT NULL CHECK (price >= 0)
+);
+
+CREATE INDEX idx_order_items_order_id ON order_items(order_id);
+```
+
+## JDBC Template (When JPA Is Overkill)
+
+```java
+// For bulk operations, complex queries, or maximum performance
+@Repository
+@RequiredArgsConstructor
+public class OrderReportRepository {
+
+    private final JdbcTemplate jdbc;
+
+    public List<DailyRevenue> getDailyRevenue(LocalDate from, LocalDate to) {
+        return jdbc.query("""
+            SELECT DATE(created_at) as day, SUM(total) as revenue, COUNT(*) as order_count
+            FROM orders
+            WHERE created_at BETWEEN ? AND ?
+              AND status = 'COMPLETED'
+            GROUP BY DATE(created_at)
+            ORDER BY day
+            """,
+            (rs, rowNum) -> new DailyRevenue(
+                rs.getDate("day").toLocalDate(),
+                rs.getBigDecimal("revenue"),
+                rs.getInt("order_count")),
+            from, to);
+    }
+}
+```
+
+## Anti-Patterns
+
+```java
+// Never: open-in-view (lazy loading in presentation layer)
+spring.jpa.open-in-view=true // Masks N+1 problems, unclear data boundaries
+
+// Never: entities as API responses
+@GetMapping("/{id}")
+public Order getById(@PathVariable UUID id) {
+    return orderRepository.findById(id).orElseThrow();
+    // Exposes internal structure, lazy loading exceptions, circular references
+}
+// Map to DTOs/records
+
+// Never: manual ID generation with UUID.randomUUID() in application code
+// Let the database or JPA strategy handle it
+
+// Never: ignoring @Version for concurrent writes
+// Optimistic locking prevents lost updates — use it
+
+// Never: long-running transactions
+@Transactional
+public void processAllOrders() {
+    var orders = orderRepository.findAll(); // Locks for entire method
+    orders.forEach(this::processExpensiveOperation);
+}
+// Process in batches with separate transactions
+```