agentic-team-templates 0.13.1 → 0.14.0

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

@@ -0,0 +1,301 @@
+# Java Tooling and Build Systems
+
+Maven or Gradle. Static analysis. CI/CD. Docker. The full production pipeline.
+
+## Build Tools
+
+### Maven
+
+```xml
+<!-- pom.xml essentials -->
+<properties>
+    <java.version>21</java.version>
+    <maven.compiler.source>${java.version}</maven.compiler.source>
+    <maven.compiler.target>${java.version}</maven.compiler.target>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+</properties>
+
+<!-- Dependency management in parent POM -->
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-dependencies</artifactId>
+            <version>${spring-boot.version}</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+
+<!-- Essential plugins -->
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <configuration>
+                <compilerArgs>
+                    <arg>-Xlint:all</arg>
+                    <arg>-Werror</arg>
+                </compilerArgs>
+            </configuration>
+        </plugin>
+        <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <configuration>
+                <argLine>-XX:+EnableDynamicAgentLoading</argLine>
+            </configuration>
+        </plugin>
+    </plugins>
+</build>
+```
+
+### Gradle (Kotlin DSL)
+
+```kotlin
+// build.gradle.kts
+plugins {
+    java
+    id("org.springframework.boot") version "3.4.0"
+    id("io.spring.dependency-management") version "1.1.6"
+}
+
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(21)
+    }
+}
+
+tasks.withType<JavaCompile> {
+    options.compilerArgs.addAll(listOf("-Xlint:all", "-Werror"))
+}
+
+dependencies {
+    implementation("org.springframework.boot:spring-boot-starter-web")
+    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
+    implementation("org.springframework.boot:spring-boot-starter-validation")
+    implementation("org.springframework.boot:spring-boot-starter-actuator")
+
+    runtimeOnly("org.postgresql:postgresql")
+    runtimeOnly("org.flywaydb:flyway-database-postgresql")
+
+    compileOnly("org.projectlombok:lombok")
+    annotationProcessor("org.projectlombok:lombok")
+
+    testImplementation("org.springframework.boot:spring-boot-starter-test")
+    testImplementation("org.testcontainers:postgresql")
+    testImplementation("org.testcontainers:junit-jupiter")
+}
+
+tasks.test {
+    useJUnitPlatform()
+    jvmArgs("-XX:+EnableDynamicAgentLoading")
+}
+```
+
+## Essential Commands
+
+```bash
+# Maven
+mvn clean verify                     # Full build + tests
+mvn test                             # Unit tests only
+mvn verify -Pintegration-tests       # Integration tests
+mvn dependency:tree                  # Dependency analysis
+mvn versions:display-dependency-updates  # Check for updates
+mvn spotbugs:check                   # Static analysis
+
+# Gradle
+./gradlew clean build                # Full build + tests
+./gradlew test                       # Unit tests
+./gradlew integrationTest            # Integration tests
+./gradlew dependencies               # Dependency tree
+./gradlew dependencyUpdates          # Check for updates
+```
+
+## Static Analysis
+
+### SpotBugs + ErrorProne
+
+```xml
+<!-- SpotBugs -->
+<plugin>
+    <groupId>com.github.spotbugs</groupId>
+    <artifactId>spotbugs-maven-plugin</artifactId>
+    <configuration>
+        <effort>Max</effort>
+        <threshold>Low</threshold>
+        <failOnError>true</failOnError>
+    </configuration>
+</plugin>
+
+<!-- ErrorProne (compile-time bug detection) -->
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-compiler-plugin</artifactId>
+    <configuration>
+        <annotationProcessorPaths>
+            <path>
+                <groupId>com.google.errorprone</groupId>
+                <artifactId>error_prone_core</artifactId>
+                <version>${errorprone.version}</version>
+            </path>
+        </annotationProcessorPaths>
+        <compilerArgs>
+            <arg>-XDcompilePolicy=simple</arg>
+            <arg>-Xplugin:ErrorProne</arg>
+        </compilerArgs>
+    </configuration>
+</plugin>
+```
+
+### Checkstyle
+
+```xml
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-checkstyle-plugin</artifactId>
+    <configuration>
+        <configLocation>google_checks.xml</configLocation>
+        <failsOnError>true</failsOnError>
+    </configuration>
+</plugin>
+```
+
+## Docker
+
+```dockerfile
+# Multi-stage build
+FROM eclipse-temurin:21-jdk-alpine AS build
+WORKDIR /app
+COPY pom.xml .
+COPY src ./src
+RUN --mount=type=cache,target=/root/.m2 \
+    mvn package -DskipTests -q
+
+FROM eclipse-temurin:21-jre-alpine
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+USER appuser
+WORKDIR /app
+COPY --from=build /app/target/*.jar app.jar
+EXPOSE 8080
+
+# JVM tuning for containers
+ENV JAVA_OPTS="-XX:+UseContainerSupport \
+    -XX:MaxRAMPercentage=75.0 \
+    -XX:+UseZGC \
+    -XX:+ZGenerational"
+
+ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]
+```
+
+## CI/CD (GitHub Actions)
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: testdb
+        ports:
+          - 5432:5432
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+          cache: maven
+
+      - name: Build and test
+        run: mvn clean verify -B
+        env:
+          SPRING_DATASOURCE_URL: jdbc:postgresql://localhost:5432/testdb
+          SPRING_DATASOURCE_USERNAME: postgres
+          SPRING_DATASOURCE_PASSWORD: test
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+```
+
+## Logging (SLF4J + Logback)
+
+```java
+// Always use SLF4J facade
+private static final Logger log = LoggerFactory.getLogger(OrderService.class);
+// Or with Lombok: @Slf4j on the class
+
+// Structured logging with parameters — never string concatenation
+log.info("Order created orderId={} customerId={} itemCount={}",
+    order.getId(), order.getCustomerId(), order.getItems().size());
+
+// MDC for request-scoped context
+MDC.put("requestId", requestId);
+MDC.put("userId", userId);
+try {
+    // All log statements in this scope include requestId and userId
+    processOrder(order);
+} finally {
+    MDC.clear();
+}
+```
+
+```xml
+<!-- logback-spring.xml for JSON output in production -->
+<configuration>
+    <springProfile name="prod">
+        <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+            <encoder class="net.logstash.logback.encoder.LogstashEncoder" />
+        </appender>
+    </springProfile>
+
+    <springProfile name="local">
+        <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+            <encoder>
+                <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
+            </encoder>
+        </appender>
+    </springProfile>
+
+    <root level="INFO">
+        <appender-ref ref="STDOUT" />
+    </root>
+</configuration>
+```
+
+## Anti-Patterns
+
+```java
+// Never: System.out.println for logging
+System.out.println("Order created: " + order.getId());
+// Use SLF4J logger
+
+// Never: hardcoded versions scattered across modules
+// Use dependencyManagement (Maven) or platform (Gradle)
+
+// Never: fat JAR without layer optimization
+// Use Spring Boot layered JARs for Docker cache efficiency
+
+// Never: running as root in Docker containers
+USER root // Security risk
+// Use: non-root user (adduser)
+
+// Never: skipping static analysis in CI
+// SpotBugs, ErrorProne, and Checkstyle catch real bugs
+```

package/templates/java-expert/CLAUDE.md

@@ -0,0 +1,325 @@
+# Java Expert Development Guide
+
+Principal-level guidelines for Java engineering. Deep JVM knowledge, modern language features, and production-grade patterns.
+
+---
+
+## Overview
+
+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
+│   ├── config/
+│   ├── domain/
+│   │   ├── model/
+│   │   ├── service/
+│   │   └── event/
+│   ├── application/
+│   │   ├── command/
+│   │   ├── query/
+│   │   └── port/
+│   ├── infrastructure/
+│   │   ├── persistence/
+│   │   ├── messaging/
+│   │   └── client/
+│   └── api/
+│       ├── controller/
+│       ├── dto/
+│       └── exception/
+├── src/main/resources/
+│   ├── application.yml
+│   └── db/migration/
+├── src/test/java/
+├── pom.xml or build.gradle.kts
+└── Dockerfile
+```
+
+---
+
+## Modern Java
+
+### Records
+
+```java
+public record CreateUserRequest(@NotBlank String name, @Email String email) {}
+public record Money(BigDecimal amount, Currency currency) {
+    public Money {
+        if (amount.compareTo(BigDecimal.ZERO) < 0)
+            throw new IllegalArgumentException("Amount cannot be negative");
+    }
+}
+```
+
+### Sealed Classes
+
+```java
+public sealed interface PaymentResult
+    permits PaymentSuccess, PaymentFailure, PaymentPending {}
+
+public String describe(PaymentResult result) {
+    return switch (result) {
+        case PaymentSuccess s -> "Paid: " + s.transactionId();
+        case PaymentFailure f -> "Failed: " + f.message();
+        case PaymentPending p -> "Pending: " + p.referenceId();
+    };
+}
+```
+
+### Virtual Threads (Java 21+)
+
+```java
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    var futures = tasks.stream()
+        .map(task -> executor.submit(() -> process(task)))
+        .toList();
+}
+// Don't pool them. Don't use synchronized for I/O. Use ReentrantLock instead.
+```
+
+---
+
+## Spring Boot
+
+### Service Layer
+
+```java
+@Service
+@RequiredArgsConstructor
+@Transactional(readOnly = true)
+public class OrderService {
+    private final OrderRepository orderRepository;
+    private final ApplicationEventPublisher eventPublisher;
+
+    @Transactional
+    public OrderResponse create(CreateOrderRequest request) {
+        var order = Order.create(request);
+        orderRepository.save(order);
+        eventPublisher.publishEvent(new OrderCreatedEvent(order.getId()));
+        return OrderResponse.from(order);
+    }
+}
+```
+
+### Exception Handling
+
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    @ExceptionHandler(NotFoundException.class)
+    public ProblemDetail handleNotFound(NotFoundException ex) {
+        return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
+    }
+}
+```
+
+### Configuration
+
+```java
+@Validated
+@ConfigurationProperties(prefix = "app.orders")
+public record OrderProperties(
+    @NotNull Duration processingTimeout,
+    @Min(1) int maxItemsPerOrder
+) {}
+```
+
+---
+
+## Concurrency
+
+### Rules
+
+- Don't start threads you can't stop
+- Prefer virtual threads for I/O, platform threads for CPU
+- Use `ReentrantLock` over `synchronized` with virtual threads
+- Always restore interrupt status in catch blocks
+- Immutable objects are inherently thread-safe
+
+### CompletableFuture
+
+```java
+var userFuture = CompletableFuture.supplyAsync(() -> userService.findById(userId));
+var ordersFuture = CompletableFuture.supplyAsync(() -> orderService.recent(userId));
+CompletableFuture.allOf(userFuture, ordersFuture)
+    .thenApply(v -> new Dashboard(userFuture.join(), ordersFuture.join()));
+```
+
+---
+
+## Persistence
+
+### JPA Best Practices
+
+- Factory methods on entities, protected no-arg constructors for JPA
+- `@Version` for optimistic locking
+- JOIN FETCH or `@EntityGraph` to prevent N+1 queries
+- DTO projections for read-only queries
+- `spring.jpa.open-in-view=false` — always
+
+### Transactions
+
+```java
+@Transactional(readOnly = true) // On the class for reads
+public Optional<Order> findById(UUID id) { ... }
+
+@Transactional // Override for writes
+public Order create(CreateOrderRequest request) { ... }
+```
+
+### Migrations
+
+Flyway or Liquibase. Every schema change is a versioned migration. No Hibernate auto-DDL in production.
+
+---
+
+## Error Handling
+
+### Two Approaches
+
+1. **Exceptions** — Infrastructure failures, programming errors
+2. **Result types** — Expected business failures (validation, conflicts)
+
+### Guard Clauses
+
+```java
+Objects.requireNonNull(customerId, "customerId must not be null");
+if (items.isEmpty()) throw new IllegalArgumentException("Order must have items");
+```
+
+### Logging
+
+```java
+log.error("Payment failed orderId={} amount={}: {}", orderId, amount, ex.getMessage(), ex);
+// Parameters for structured logging. Exception as last arg for stack trace.
+```
+
+---
+
+## Testing
+
+### Framework Stack
+
+| Tool | Purpose |
+|------|---------|
+| JUnit 5 | Test framework |
+| AssertJ | Fluent assertions |
+| Mockito | Mocking |
+| Testcontainers | Real databases/services |
+| WireMock | HTTP API mocking |
+| ArchUnit | Architecture tests |
+
+### Test Structure
+
+```java
+@Test
+void create_withValidRequest_savesAndReturnsOrder() {
+    // Arrange
+    var request = new CreateOrderRequest("customer-1", List.of(item));
+    when(inventory.check("SKU-001", 2)).thenReturn(true);
+    // Act
+    var result = sut.create(request);
+    // Assert
+    assertThat(result.customerId()).isEqualTo("customer-1");
+}
+```
+
+### Integration Tests
+
+```java
+@SpringBootTest(webEnvironment = RANDOM_PORT)
+@Testcontainers
+class OrderControllerIT {
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");
+}
+```
+
+---
+
+## Performance
+
+### Profile First
+
+```bash
+java -XX:StartFlightRecording=filename=recording.jfr,duration=60s -jar app.jar
+```
+
+### Key Patterns
+
+- Pre-size collections when capacity is known
+- Use primitive streams to avoid autoboxing
+- `StringBuilder` for complex string concatenation
+- HikariCP pool sizing: `core_count * 2` connections
+- Caffeine for in-process caching with eviction
+- ZGC for ultra-low-latency requirements
+
+---
+
+## Tooling
+
+### Essential Stack
+
+| Tool | Purpose |
+|------|---------|
+| Maven/Gradle | Build system |
+| SpotBugs | Bug detection |
+| ErrorProne | Compile-time bug detection |
+| Checkstyle | Code style enforcement |
+| JFR + JMC | Production profiling |
+| JMH | Micro-benchmarks |
+| SLF4J + Logback | Logging |
+
+### CI Essentials
+
+```bash
+mvn clean verify -B         # Full build with tests
+mvn spotbugs:check           # Static analysis
+mvn checkstyle:check         # Code style
+```
+
+---
+
+## 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/javascript-expert/.cursorrules/overview.md

@@ -1,6 +1,8 @@
-# JavaScript Expert
+# JavaScript & TypeScript Expert
 
-Guidelines for principal-level JavaScript engineering across all runtimes, frameworks, and paradigms.
+Guidelines for principal-level JavaScript and TypeScript engineering across all runtimes, frameworks, and paradigms.
+
+**This template covers both JavaScript and TypeScript.** TypeScript is the default — all code is written in strict TypeScript. The advanced type system is covered in `typescript-deep-dive.md`.
 
 ## Scope
 
@@ -8,7 +10,7 @@ This ruleset applies to:
 - Node.js services, CLIs, and tooling
 - React, Vue, Angular, Svelte, and other UI frameworks
 - Vanilla JavaScript and Web APIs
-- TypeScript (strict mode, always)
+- TypeScript (strict mode, always — see `typescript-deep-dive.md` for advanced patterns)
 - Build tools, bundlers, and transpilers
 - Testing at every level (unit, integration, E2E, performance)