agentic-team-templates 0.13.2 → 0.14.0

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

@@ -0,0 +1,209 @@
+# Java Concurrency
+
+The Java Memory Model is the law. Every concurrent decision must respect it.
+
+## Virtual Threads (Java 21+)
+
+The default for I/O-bound work. Platform threads for CPU-bound work.
+
+```java
+// Virtual threads for I/O concurrency
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    var futures = tasks.stream()
+        .map(task -> executor.submit(() -> process(task)))
+        .toList();
+
+    var results = futures.stream()
+        .map(f -> {
+            try { return f.get(30, TimeUnit.SECONDS); }
+            catch (TimeoutException e) { throw new ProcessingTimeoutException(e); }
+            catch (ExecutionException e) { throw new ProcessingException(e.getCause()); }
+            catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+                throw new ProcessingException(e);
+            }
+        })
+        .toList();
+}
+```
+
+### Virtual Thread Rules
+
+- Don't pool virtual threads — they're cheap to create
+- Don't use `synchronized` for I/O operations — use `ReentrantLock`
+- Don't pin virtual threads to carrier threads (`synchronized` blocks pin)
+- Don't use `ThreadLocal` for request-scoped data — use `ScopedValue` (preview)
+
+```java
+// Bad: synchronized pins virtual thread to carrier
+synchronized (lock) {
+    database.query(sql); // I/O while pinned — wastes carrier thread
+}
+
+// Good: ReentrantLock doesn't pin
+private final ReentrantLock lock = new ReentrantLock();
+
+lock.lock();
+try {
+    database.query(sql); // Virtual thread can unmount during I/O
+} finally {
+    lock.unlock();
+}
+```
+
+## Structured Concurrency (Preview)
+
+```java
+// All subtasks succeed or all are cancelled — no leaked threads
+try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+    Subtask<User> userTask = scope.fork(() -> userService.findById(userId));
+    Subtask<List<Order>> ordersTask = scope.fork(() -> orderService.findByUser(userId));
+
+    scope.join();           // Wait for all
+    scope.throwIfFailed();  // Propagate first failure
+
+    return new Dashboard(userTask.get(), ordersTask.get());
+}
+```
+
+## CompletableFuture
+
+```java
+// Async pipeline with proper error handling
+public CompletableFuture<OrderResult> processOrderAsync(CreateOrderRequest request) {
+    return validateAsync(request)
+        .thenCompose(this::checkInventoryAsync)
+        .thenCompose(this::createOrderAsync)
+        .thenApply(OrderResult::success)
+        .exceptionally(ex -> {
+            log.error("Order processing failed", ex);
+            return OrderResult.failure(ex.getMessage());
+        });
+}
+
+// Combine independent operations
+public CompletableFuture<Dashboard> loadDashboard(UUID userId) {
+    var userFuture = CompletableFuture.supplyAsync(() -> userService.findById(userId));
+    var ordersFuture = CompletableFuture.supplyAsync(() -> orderService.recent(userId));
+    var statsFuture = CompletableFuture.supplyAsync(() -> statsService.forUser(userId));
+
+    return CompletableFuture.allOf(userFuture, ordersFuture, statsFuture)
+        .thenApply(v -> new Dashboard(
+            userFuture.join(),
+            ordersFuture.join(),
+            statsFuture.join()));
+}
+```
+
+## Thread Safety Patterns
+
+### Immutability (Preferred)
+
+```java
+// Immutable objects are inherently thread-safe
+public record UserSnapshot(UUID id, String name, Instant capturedAt) {}
+
+// Unmodifiable collections
+private final List<String> allowedRoles = List.of("USER", "ADMIN", "MODERATOR");
+```
+
+### Atomic Operations
+
+```java
+private final AtomicLong requestCounter = new AtomicLong();
+private final AtomicReference<Config> currentConfig = new AtomicReference<>(Config.defaults());
+
+public void handleRequest() {
+    requestCounter.incrementAndGet();
+}
+
+public void updateConfig(Config newConfig) {
+    currentConfig.set(newConfig);
+}
+```
+
+### ConcurrentHashMap
+
+```java
+// Thread-safe map with atomic compute operations
+private final ConcurrentHashMap<String, AtomicLong> counters = new ConcurrentHashMap<>();
+
+public void increment(String key) {
+    counters.computeIfAbsent(key, k -> new AtomicLong()).incrementAndGet();
+}
+
+// Never iterate and modify — use compute/merge operations
+counters.merge(key, new AtomicLong(1), (existing, value) -> {
+    existing.incrementAndGet();
+    return existing;
+});
+```
+
+### Bounded Queues
+
+```java
+// Backpressure via bounded queue
+private final BlockingQueue<Event> eventQueue = new LinkedBlockingQueue<>(10_000);
+
+public boolean publish(Event event) {
+    return eventQueue.offer(event); // Returns false if full — handle backpressure
+}
+
+public void consume() {
+    while (!Thread.currentThread().isInterrupted()) {
+        try {
+            Event event = eventQueue.poll(1, TimeUnit.SECONDS);
+            if (event != null) process(event);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            break;
+        }
+    }
+}
+```
+
+## Interrupt Handling
+
+```java
+// Always restore interrupt status
+public void processItems(List<Item> items) {
+    for (var item : items) {
+        if (Thread.currentThread().isInterrupted()) {
+            log.warn("Processing interrupted, {} items remaining", items.size());
+            break;
+        }
+        process(item);
+    }
+}
+
+// In catch blocks
+try {
+    Thread.sleep(Duration.ofSeconds(5));
+} catch (InterruptedException e) {
+    Thread.currentThread().interrupt(); // Restore flag
+    throw new RuntimeException("Operation interrupted", e);
+}
+```
+
+## Anti-Patterns
+
+```java
+// Never: double-checked locking without volatile (pre-Java 5 bug, but still seen)
+// Use: enum singleton, or lazy holder pattern, or just @Singleton
+
+// Never: synchronized on non-final fields
+private Object lock = new Object(); // Can be reassigned!
+synchronized (lock) { } // Different threads may lock different objects
+// Use: private final Object lock = new Object();
+
+// Never: Thread.stop() or Thread.suspend()
+// Use: cooperative interruption via Thread.interrupt()
+
+// Never: busy-wait
+while (!ready) { } // Burns CPU
+// Use: CountDownLatch, Semaphore, or BlockingQueue
+
+// Never: shared mutable state without synchronization
+private int counter; // Multiple threads read/write without coordination
+// Use: AtomicInteger, or synchronize access
+```

package/templates/java-expert/.cursorrules/error-handling.md

@@ -0,0 +1,205 @@
+# Java Error Handling
+
+Exceptions for exceptional conditions. Validation at boundaries. Never swallow errors.
+
+## Exception Hierarchy
+
+```java
+// Application exception base — unchecked
+public abstract class ApplicationException extends RuntimeException {
+    private final String errorCode;
+
+    protected ApplicationException(String errorCode, String message) {
+        super(message);
+        this.errorCode = errorCode;
+    }
+
+    protected ApplicationException(String errorCode, String message, Throwable cause) {
+        super(message, cause);
+        this.errorCode = errorCode;
+    }
+
+    public String getErrorCode() { return errorCode; }
+}
+
+// Specific exceptions
+public class NotFoundException extends ApplicationException {
+    public NotFoundException(String entity, Object id) {
+        super("NOT_FOUND", "%s with id '%s' not found".formatted(entity, id));
+    }
+}
+
+public class ConflictException extends ApplicationException {
+    public ConflictException(String message) {
+        super("CONFLICT", message);
+    }
+}
+
+public class ValidationException extends ApplicationException {
+    private final Map<String, String> fieldErrors;
+
+    public ValidationException(Map<String, String> fieldErrors) {
+        super("VALIDATION_FAILED", "Validation failed");
+        this.fieldErrors = Map.copyOf(fieldErrors);
+    }
+
+    public Map<String, String> getFieldErrors() { return fieldErrors; }
+}
+```
+
+## Checked vs Unchecked
+
+```java
+// Checked exceptions: recoverable conditions at system boundaries
+// - IOException: file not found, network error — caller can retry or use fallback
+// - SQLException: database error — caller can retry with backoff
+
+// Unchecked exceptions: programming errors and business rule violations
+// - IllegalArgumentException: bad input
+// - NullPointerException: null where not expected
+// - NotFoundException: domain-level "not found"
+// - ValidationException: business rule violation
+
+// Rule: if the caller CAN and SHOULD handle it → checked
+//        if it's a bug or unrecoverable → unchecked
+```
+
+## Validation
+
+```java
+// Jakarta Bean Validation on DTOs
+public record CreateUserRequest(
+    @NotBlank(message = "Name is required")
+    @Size(min = 2, max = 200, message = "Name must be 2-200 characters")
+    String name,
+
+    @NotBlank(message = "Email is required")
+    @Email(message = "Invalid email format")
+    String email,
+
+    @NotNull(message = "Role is required")
+    UserRole role
+) {}
+
+// Custom validator
+@Constraint(validatedBy = UniqueEmailValidator.class)
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface UniqueEmail {
+    String message() default "Email already registered";
+    Class<?>[] groups() default {};
+    Class<? extends Payload>[] payload() default {};
+}
+
+public class UniqueEmailValidator implements ConstraintValidator<UniqueEmail, String> {
+    private final UserRepository userRepository;
+
+    @Override
+    public boolean isValid(String email, ConstraintValidatorContext context) {
+        return email == null || !userRepository.existsByEmail(email);
+    }
+}
+```
+
+## Guard Clauses
+
+```java
+public class OrderService {
+
+    public Order create(String customerId, List<OrderItem> items) {
+        // Fail fast with meaningful messages
+        Objects.requireNonNull(customerId, "customerId must not be null");
+        if (customerId.isBlank()) {
+            throw new IllegalArgumentException("customerId must not be blank");
+        }
+        if (items == null || items.isEmpty()) {
+            throw new IllegalArgumentException("Order must have at least one item");
+        }
+        if (items.size() > MAX_ITEMS) {
+            throw new ValidationException(Map.of(
+                "items", "Maximum %d items allowed".formatted(MAX_ITEMS)));
+        }
+
+        // Business logic follows clean preconditions
+        return Order.create(customerId, items);
+    }
+}
+```
+
+## Result Pattern (Alternative to Exceptions)
+
+```java
+// For operations where failure is expected, not exceptional
+public sealed interface Result<T> permits Result.Success, Result.Failure {
+
+    record Success<T>(T value) implements Result<T> {}
+    record Failure<T>(String code, String message) implements Result<T> {}
+
+    static <T> Result<T> success(T value) { return new Success<>(value); }
+    static <T> Result<T> failure(String code, String message) { return new Failure<>(code, message); }
+
+    default <U> U match(Function<T, U> onSuccess, BiFunction<String, String, U> onFailure) {
+        return switch (this) {
+            case Success<T> s -> onSuccess.apply(s.value());
+            case Failure<T> f -> onFailure.apply(f.code(), f.message());
+        };
+    }
+}
+
+// Usage
+public Result<User> register(RegisterRequest request) {
+    if (userRepository.existsByEmail(request.email())) {
+        return Result.failure("CONFLICT", "Email already registered");
+    }
+    var user = User.create(request.name(), request.email());
+    userRepository.save(user);
+    return Result.success(user);
+}
+```
+
+## Logging Exceptions
+
+```java
+// Log with context, not just the exception
+try {
+    return paymentService.charge(orderId, amount);
+} catch (PaymentException ex) {
+    log.error("Payment failed for order {} amount {}: {}",
+        orderId, amount, ex.getMessage(), ex);
+    throw new OrderProcessingException("Payment failed for order " + orderId, ex);
+}
+
+// Rules:
+// - Log at the point of handling, not at every rethrow
+// - Include business context (IDs, amounts, actions)
+// - Use structured logging parameters, not string concatenation
+// - Include the exception as the LAST parameter (for stack trace)
+// - Don't log AND throw at the same level (choose one)
+```
+
+## Anti-Patterns
+
+```java
+// Never: catching Exception or Throwable broadly
+try { doWork(); }
+catch (Exception e) { log.error("Error", e); }
+// Catches InterruptedException, NPE, and everything else — too broad
+
+// Never: empty catch blocks
+try { connection.close(); }
+catch (Exception e) { /* ignore */ }
+// At minimum: log.debug("Error closing connection", e);
+
+// Never: using exceptions for control flow
+try { return Integer.parseInt(input); }
+catch (NumberFormatException e) { return defaultValue; }
+// Use: input.matches("\\d+") or a tryParse utility
+
+// Never: wrapping without adding context
+catch (SQLException e) { throw new RuntimeException(e); }
+// Add context: throw new PersistenceException("Failed to save order " + orderId, e);
+
+// Never: losing the original exception
+catch (Exception e) { throw new RuntimeException("Something failed"); }
+// Always chain: throw new RuntimeException("Something failed", e);
+```

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

@@ -0,0 +1,216 @@
+# Modern Java Language Features
+
+Java 21+ features used deliberately. Every feature exists to make code clearer — not to show off.
+
+## Records
+
+```java
+// Immutable data carriers — the default for DTOs, value objects, events
+public record CreateUserRequest(
+    @NotBlank String name,
+    @Email String email
+) {}
+
+public record Money(BigDecimal amount, Currency currency) {
+    // Compact constructor for validation
+    public Money {
+        if (amount.compareTo(BigDecimal.ZERO) < 0) {
+            throw new IllegalArgumentException("Amount cannot be negative");
+        }
+        Objects.requireNonNull(currency, "Currency is required");
+    }
+}
+
+public record PageRequest(int page, int size) {
+    public PageRequest {
+        if (page < 0) throw new IllegalArgumentException("Page must be >= 0");
+        if (size < 1 || size > 100) throw new IllegalArgumentException("Size must be 1-100");
+    }
+
+    public int offset() {
+        return page * size;
+    }
+}
+```
+
+### When NOT to Use Records
+
+- JPA entities (need mutable state, no-arg constructor)
+- Spring beans (need proxying, lifecycle management)
+- Classes with complex behavior beyond data carrying
+
+## Sealed Classes
+
+```java
+// Exhaustive type hierarchies — the compiler enforces completeness
+public sealed interface PaymentResult permits PaymentSuccess, PaymentFailure, PaymentPending {
+}
+
+public record PaymentSuccess(String transactionId, Instant processedAt) implements PaymentResult {}
+public record PaymentFailure(String errorCode, String message) implements PaymentResult {}
+public record PaymentPending(String referenceId, Duration estimatedWait) implements PaymentResult {}
+
+// Exhaustive switch — compiler warns if a case is missing
+public String describeResult(PaymentResult result) {
+    return switch (result) {
+        case PaymentSuccess s -> "Paid: " + s.transactionId();
+        case PaymentFailure f -> "Failed: " + f.message();
+        case PaymentPending p -> "Pending: " + p.referenceId();
+    };
+}
+```
+
+## Pattern Matching
+
+```java
+// instanceof pattern matching — no more casting
+public String format(Object value) {
+    return switch (value) {
+        case Integer i when i < 0 -> "negative: " + i;
+        case Integer i -> "integer: " + i;
+        case String s when s.isEmpty() -> "empty string";
+        case String s -> "string: " + s;
+        case null -> "null";
+        default -> "unknown: " + value.getClass().getSimpleName();
+    };
+}
+
+// Record patterns (Java 21+)
+public double calculateArea(Shape shape) {
+    return switch (shape) {
+        case Circle(double radius) -> Math.PI * radius * radius;
+        case Rectangle(double w, double h) -> w * h;
+        case Triangle(double base, double height) -> 0.5 * base * height;
+    };
+}
+```
+
+## Text Blocks
+
+```java
+// Multi-line strings with proper indentation
+String query = """
+        SELECT u.id, u.name, u.email
+        FROM users u
+        WHERE u.active = true
+          AND u.created_at > :since
+        ORDER BY u.name
+        """;
+
+String json = """
+        {
+            "name": "%s",
+            "email": "%s"
+        }
+        """.formatted(name, email);
+```
+
+## Optional
+
+```java
+// Return type for "might not exist" — never for fields or parameters
+public Optional<User> findByEmail(String email) {
+    return Optional.ofNullable(userRepository.findByEmail(email));
+}
+
+// Good: chain operations
+public String getUserDisplayName(String email) {
+    return findByEmail(email)
+        .map(User::displayName)
+        .orElse("Unknown User");
+}
+
+// Good: throw with context
+public User getByEmail(String email) {
+    return findByEmail(email)
+        .orElseThrow(() -> new NotFoundException("User not found: " + email));
+}
+
+// Bad: Optional.get() without check — defeats the purpose
+user.get().getName(); // NoSuchElementException risk
+
+// Bad: Optional as method parameter
+public void process(Optional<String> name) { } // Use @Nullable instead
+
+// Bad: Optional as field
+private Optional<String> middleName; // Use @Nullable instead
+```
+
+## Collections
+
+```java
+// Immutable collections — the default
+var users = List.of("Alice", "Bob", "Charlie");
+var scores = Map.of("Alice", 95, "Bob", 87);
+var uniqueNames = Set.of("Alice", "Bob");
+
+// List.copyOf, Set.copyOf, Map.copyOf for defensive copies
+public List<User> getUsers() {
+    return List.copyOf(mutableUserList); // Defensive copy
+}
+
+// Collectors and Stream API
+var activeUsersByDepartment = users.stream()
+    .filter(User::isActive)
+    .collect(Collectors.groupingBy(
+        User::department,
+        Collectors.toUnmodifiableList()));
+
+// toList() shorthand (Java 16+)
+var names = users.stream()
+    .map(User::name)
+    .toList(); // Returns unmodifiable list
+```
+
+## Virtual Threads (Java 21+)
+
+```java
+// Virtual threads for I/O-bound concurrency — massive scalability
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    List<Future<Response>> futures = urls.stream()
+        .map(url -> executor.submit(() -> httpClient.send(url)))
+        .toList();
+
+    List<Response> responses = futures.stream()
+        .map(f -> {
+            try { return f.get(); }
+            catch (Exception e) { throw new RuntimeException(e); }
+        })
+        .toList();
+}
+
+// Spring Boot 3.2+: enable virtual threads
+// spring.threads.virtual.enabled=true
+
+// Rules for virtual threads:
+// - Don't pool them (they're cheap to create)
+// - Don't use synchronized blocks for I/O (use ReentrantLock)
+// - Don't use ThreadLocal for request-scoped data (use ScopedValue)
+// - Perfect for: HTTP handlers, database queries, external API calls
+// - Not for: CPU-bound computation (use platform threads / ForkJoinPool)
+```
+
+## Anti-Patterns
+
+```java
+// Never: raw types
+List list = new ArrayList(); // What's in it?
+// Use: List<User> users = new ArrayList<>();
+
+// Never: checked exceptions for control flow
+try { return Integer.parseInt(input); }
+catch (NumberFormatException e) { return -1; }
+// Use validation before parsing
+
+// Never: mutable public fields
+public class Config {
+    public String url; // Anyone can change this
+}
+// Use: records, or private fields with getters
+
+// Never: null as a valid business value
+public User findUser(String id) {
+    return null; // Caller forgets null check → NPE
+}
+// Use: Optional<User> or throw NotFoundException
+```