@dv.nghiem/flowdeck 0.1.0

package/src/skills/java-patterns/SKILL.md

@@ -0,0 +1,479 @@
+---
+name: java-patterns
+description: Modern Java (17+) patterns covering records, sealed classes, Stream API, CompletableFuture, Spring Boot, JPA, and testing. Activate when writing or reviewing Java code.
+origin: FlowDeck
+---
+
+# Java Patterns Skill
+
+Modern Java for production applications. Focuses on Java 17+ features and Spring Boot conventions.
+
+## When to Activate
+
+Activate when:
+- Writing new Java services or libraries
+- Reviewing Java code for correctness and modern idiom
+- Designing API layers, service classes, or data access
+- Troubleshooting Spring Boot configuration or JPA queries
+- Setting up testing infrastructure
+
+## Modern Java Features (17+)
+
+### Records — Immutable Data Carriers
+
+Records eliminate boilerplate for data classes. Use them for DTOs, value objects, and command/query objects.
+
+```java
+// Compiler generates constructor, getters, equals, hashCode, toString
+public record Point(double x, double y) {}
+
+// Custom constructor for validation
+public record EmailAddress(String value) {
+    public EmailAddress {
+        Objects.requireNonNull(value);
+        if (!value.contains("@")) {
+            throw new IllegalArgumentException("invalid email: " + value);
+        }
+        value = value.toLowerCase();
+    }
+}
+
+// Records can implement interfaces
+public record PageRequest(int page, int size) implements Serializable {
+    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; }
+}
+```
+
+### Sealed Classes — Closed Hierarchies
+
+Use sealed classes to model a fixed set of variants. The compiler enforces exhaustive pattern matching.
+
+```java
+public sealed interface PaymentResult
+    permits PaymentResult.Success, PaymentResult.Declined, PaymentResult.Error {
+
+    record Success(String transactionId, BigDecimal amount) implements PaymentResult {}
+    record Declined(String reason) implements PaymentResult {}
+    record Error(Throwable cause) implements PaymentResult {}
+}
+
+// Pattern matching ensures all cases are handled
+String message = switch (result) {
+    case PaymentResult.Success s  -> "Charged " + s.amount();
+    case PaymentResult.Declined d -> "Declined: " + d.reason();
+    case PaymentResult.Error e    -> "Error: " + e.cause().getMessage();
+};
+```
+
+### Pattern Matching instanceof
+
+```java
+// ❌ Old style — verbose cast
+if (obj instanceof String) {
+    String s = (String) obj;
+    System.out.println(s.length());
+}
+
+// ✅ Pattern variable — binding in same expression
+if (obj instanceof String s) {
+    System.out.println(s.length());
+}
+
+// Combining with guards
+if (obj instanceof String s && s.length() > 5) {
+    System.out.println("long string: " + s);
+}
+```
+
+### Text Blocks
+
+```java
+// ✅ Multiline strings without escaping
+String json = """
+        {
+          "name": "Alice",
+          "age": 30
+        }
+        """;
+
+String query = """
+        SELECT u.id, u.email
+          FROM users u
+         WHERE u.active = true
+           AND u.created_at > :since
+        """;
+```
+
+## Optional — Use at API Boundaries
+
+Optional communicates "might be absent" in a return type. Never use it as a field type or parameter.
+
+```java
+// ✅ Return type — caller must handle absence
+public Optional<User> findByEmail(String email) {
+    return userRepository.findByEmail(email);
+}
+
+// ✅ Chained operations
+String displayName = findByEmail(email)
+    .map(User::displayName)
+    .orElse("Anonymous");
+
+// ✅ Throw if absent with meaningful message
+User user = findByEmail(email)
+    .orElseThrow(() -> new UserNotFoundException(email));
+
+// ✅ Execute only if present
+findByEmail(email).ifPresent(user -> auditLog.record(user.id()));
+
+// ❌ Never null-check Optional itself
+Optional<User> opt = findByEmail(email);
+if (opt != null && opt.isPresent()) { ... }  // wrong
+
+// ❌ Never use as a field type
+class Service {
+    private Optional<Cache> cache;  // wrong — use @Nullable or just null
+}
+```
+
+## Stream API
+
+### Core Operations
+
+```java
+List<String> activeEmails = users.stream()
+    .filter(User::isActive)
+    .sorted(Comparator.comparing(User::lastName))
+    .map(User::email)
+    .toList();  // Java 16+ unmodifiable list
+
+// Collectors
+Map<Department, List<Employee>> byDept = employees.stream()
+    .collect(Collectors.groupingBy(Employee::department));
+
+Map<Boolean, List<User>> partitioned = users.stream()
+    .collect(Collectors.partitioningBy(User::isAdmin));
+
+// Reduce
+BigDecimal total = cart.items().stream()
+    .map(Item::price)
+    .reduce(BigDecimal.ZERO, BigDecimal::add);
+```
+
+### flatMap — Flattening Nested Collections
+
+```java
+// One user has many orders, each order has many items
+List<Item> allItems = users.stream()
+    .flatMap(u -> u.orders().stream())
+    .flatMap(o -> o.items().stream())
+    .toList();
+```
+
+### Parallel Streams — When NOT to Use
+
+```java
+// ✅ Parallel for CPU-bound work on large, independent datasets
+long count = IntStream.range(0, 10_000_000)
+    .parallel()
+    .filter(n -> isPrime(n))
+    .count();
+
+// ❌ Parallel with shared mutable state — data race
+List<Integer> result = new ArrayList<>();
+IntStream.range(0, 1000).parallel()
+    .forEach(result::add);  // non-thread-safe!
+
+// ❌ Parallel for I/O-bound work — blocks common ForkJoinPool
+Stream.of(urls).parallel()
+    .map(this::fetch)  // ties up ForkJoin threads on I/O
+    .toList();
+
+// Rule: parallel only when dataset is large, work is CPU-bound,
+// and no shared mutable state exists. Benchmark first.
+```
+
+## CompletableFuture — Async Composition
+
+```java
+// Chain transformations
+CompletableFuture<String> result = CompletableFuture
+    .supplyAsync(() -> fetchUser(userId))        // background thread
+    .thenApply(User::email)                      // same thread
+    .thenApplyAsync(this::sendWelcome, executor); // different thread
+
+// Compose dependent futures (flatMap equivalent)
+CompletableFuture<Order> order = CompletableFuture
+    .supplyAsync(() -> findUser(id))
+    .thenCompose(user -> placeOrder(user, items));  // avoids nested futures
+
+// Recover from failure
+CompletableFuture<User> withFallback = fetchUser(id)
+    .exceptionally(ex -> {
+        log.warn("fetch failed, using guest", ex);
+        return User.guest();
+    });
+
+// Wait for multiple independent futures
+CompletableFuture<Void> all = CompletableFuture.allOf(
+    sendEmail(user), updateCache(user), auditLog(user)
+);
+all.join();  // blocks — use only at the top of the call stack
+
+// Timeout
+CompletableFuture<User> withTimeout = fetchUser(id)
+    .orTimeout(2, TimeUnit.SECONDS)
+    .exceptionally(ex -> User.guest());
+```
+
+## Spring Boot Patterns
+
+### Dependency Injection — Constructor Injection Only
+
+```java
+// ✅ Constructor injection — dependencies are explicit and final
+@Service
+public class OrderService {
+    private final OrderRepository orders;
+    private final PaymentGateway payments;
+    private final EventPublisher events;
+
+    public OrderService(
+        OrderRepository orders,
+        PaymentGateway payments,
+        EventPublisher events
+    ) {
+        this.orders = orders;
+        this.payments = payments;
+        this.events = events;
+    }
+}
+
+// ❌ Field injection — hides dependencies, breaks tests
+@Service
+public class OrderService {
+    @Autowired private OrderRepository orders;  // bad
+}
+```
+
+### @ConfigurationProperties — Typed Config
+
+```java
+@ConfigurationProperties(prefix = "payment")
+public record PaymentConfig(
+    String apiKey,
+    URI baseUrl,
+    Duration timeout,
+    int maxRetries
+) {}
+
+// application.yml
+// payment:
+//   api-key: sk_live_...
+//   base-url: https://api.stripe.com
+//   timeout: 5s
+//   max-retries: 3
+```
+
+### Layered Stereotypes
+
+```java
+@Repository   // data access — wraps DataAccessException
+@Service      // business logic
+@Component    // general-purpose bean
+@RestController  // HTTP endpoints (combines @Controller + @ResponseBody)
+```
+
+## JPA and Hibernate
+
+### N+1 Problem
+
+```java
+// ❌ N+1: one query for orders, then one query per order for items
+List<Order> orders = orderRepo.findAll();
+orders.forEach(o -> System.out.println(o.getItems().size()));
+
+// ✅ Fetch join: single query
+@Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.userId = :userId")
+List<Order> findWithItems(@Param("userId") Long userId);
+
+// ✅ Or use @EntityGraph for reuse
+@EntityGraph(attributePaths = {"items", "items.product"})
+List<Order> findByUserId(Long userId);
+```
+
+### Fetch Strategy
+
+```java
+// Default for @OneToMany is LAZY — keep it that way
+@OneToMany(mappedBy = "order", fetch = FetchType.LAZY)
+private List<OrderItem> items;
+
+// EAGER causes joins on every query, even when items aren't needed
+// Only use EAGER for @ManyToOne / @OneToOne where the association is always needed
+```
+
+### Transaction Boundaries
+
+```java
+// @Transactional on service methods, not repository methods
+@Service
+public class TransferService {
+    @Transactional
+    public void transfer(Long fromId, Long toId, BigDecimal amount) {
+        Account from = accounts.findById(fromId).orElseThrow();
+        Account to   = accounts.findById(toId).orElseThrow();
+        from.debit(amount);
+        to.credit(amount);
+        // both saves happen in the same transaction
+    }
+}
+```
+
+## Testing
+
+### JUnit 5 with Mockito
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+
+    @Mock OrderRepository orders;
+    @Mock PaymentGateway payments;
+    @InjectMocks OrderService service;
+
+    @Test
+    void placeOrder_chargesPaymentAndSavesOrder() {
+        var user = aUser().build();
+        var items = List.of(anItem().withPrice(BigDecimal.TEN).build());
+        when(payments.charge(any(), any())).thenReturn(chargeSuccess());
+
+        var result = service.placeOrder(user, items);
+
+        assertThat(result.status()).isEqualTo(OrderStatus.CONFIRMED);
+        verify(orders).save(argThat(o -> o.total().equals(BigDecimal.TEN)));
+    }
+}
+```
+
+### Spring Boot Test Slices
+
+```java
+// Unit test — no Spring context
+@ExtendWith(MockitoExtension.class)
+class UserServiceTest { ... }
+
+// Web layer only — no full context
+@WebMvcTest(UserController.class)
+class UserControllerTest {
+    @Autowired MockMvc mvc;
+    @MockBean UserService service;
+
+    @Test
+    void getUser_returns200() throws Exception {
+        when(service.findById(1L)).thenReturn(Optional.of(aUser().build()));
+        mvc.perform(get("/users/1"))
+           .andExpect(status().isOk())
+           .andExpect(jsonPath("$.email").value("alice@example.com"));
+    }
+}
+
+// Full integration test
+@SpringBootTest(webEnvironment = RANDOM_PORT)
+@Transactional  // rolls back each test
+class OrderIntegrationTest { ... }
+```
+
+## Build Configuration
+
+### Maven
+
+```xml
+<properties>
+    <java.version>21</java.version>
+    <spring-boot.version>3.3.0</spring-boot.version>
+</properties>
+
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-compiler-plugin</artifactId>
+    <configuration>
+        <release>${java.version}</release>
+        <compilerArgs><arg>-parameters</arg></compilerArgs>
+    </configuration>
+</plugin>
+```
+
+### Gradle (Kotlin DSL)
+
+```kotlin
+java {
+    toolchain { languageVersion = JavaLanguageVersion.of(21) }
+}
+
+tasks.withType<JavaCompile> {
+    options.compilerArgs.add("-parameters")
+}
+```
+
+## Common Pitfalls
+
+### Checked Exceptions in New Code
+
+```java
+// ❌ Checked exceptions force callers to handle or declare them
+public List<User> loadUsers() throws IOException, ParseException { ... }
+
+// ✅ Wrap in unchecked and carry the cause
+public List<User> loadUsers() {
+    try {
+        return parser.parse(Files.readString(path));
+    } catch (IOException | ParseException e) {
+        throw new UserLoadException("failed to load users from " + path, e);
+    }
+}
+```
+
+### String Concatenation in Loops
+
+```java
+// ❌ Creates a new String object every iteration — O(n²) allocations
+String result = "";
+for (String s : list) {
+    result += s + ", ";
+}
+
+// ✅ StringBuilder is O(n)
+var sb = new StringBuilder();
+for (String s : list) {
+    sb.append(s).append(", ");
+}
+String result = sb.toString();
+
+// ✅ Or use String.join / Collectors.joining
+String result = String.join(", ", list);
+```
+
+### Autoboxing Overhead
+
+```java
+// ❌ Unnecessary boxing in tight loops
+Long sum = 0L;
+for (long i = 0; i < 1_000_000; i++) {
+    sum += i;  // unboxes sum, adds, boxes result each iteration
+}
+
+// ✅ Use primitives
+long sum = 0L;
+for (long i = 0; i < 1_000_000; i++) {
+    sum += i;
+}
+
+// ✅ LongStream avoids boxing entirely
+long sum = LongStream.range(0, 1_000_000).sum();
+```

package/src/skills/multi-repo/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: multi-repo
+description: Coordinate changes across multiple repositories in a microservice architecture. Manages cross-repo dependencies, API contract evolution, and ordered rollouts.
+origin: FlowDeck
+---
+
+# Multi-Repo Skill
+
+Provides the patterns and vocabulary for planning, sequencing, and executing changes that span more than one repository in a microservice system.
+
+## When to Activate
+
+Activate when:
+- A feature or fix requires changes in two or more repositories
+- An API contract in one service must change and consumers exist in other repos
+- A shared library version bump ripples downstream
+- You need to verify no two services are making incompatible concurrent changes
+
+Do not activate for single-repo changes, even if the repo is part of a larger microservice system.
+
+## Architecture Patterns
+
+### Service Mesh
+
+Services communicate through well-defined contracts (REST, gRPC, event schemas). No direct database sharing between services. Each service owns its data store.
+
+Key implication: contract changes are the primary coordination surface. A service can change its internals freely; it cannot change its contract without coordinating consumers.
+
+### API Contracts
+
+Every `upstream-api` service maintains a contract — the stable interface it promises to consumers. Contracts define:
+- Endpoint paths and HTTP methods (or gRPC service definitions)
+- Request and response schemas (fields, types, nullability)
+- Error response shapes
+- Authentication requirements
+- Rate limits and SLAs (where relevant)
+
+Contracts are the input to `@architect` when designing cross-repo changes.
+
+### Event-Driven Changes
+
+For services that communicate via message queues or event streams:
+- The event schema plays the same role as an API contract
+- Producers must publish the new schema before consumers update their handlers
+- Both old and new schema versions must be supported during the transition window
+- Treat schema changes with the same breaking/non-breaking classification used for REST APIs
+
+## Microservice Role Vocabulary
+
+| Role | Meaning |
+|------|---------|
+| `upstream-api` | Provides an API consumed by other services |
+| `downstream-consumer` | Calls one or more upstream APIs |
+| `shared-lib` | Imported as a package dependency by other services |
+| `gateway` | Routes external traffic to internal services |
+| `worker` | Processes background jobs; no inbound HTTP API |
+
+## Config Schema
+
+The multi-repo registry lives at `.planning/config.json` in the root repository.
+
+```json
+{
+  "sub_repos": [
+    {
+      "name": "user-service",
+      "path": "../user-service",
+      "role": "upstream-api",
+      "tech_stack": "node+typescript",
+      "owner_team": "platform"
+    },
+    {
+      "name": "order-service",
+      "path": "../order-service",
+      "role": "downstream-consumer",
+      "tech_stack": "node+typescript",
+      "owner_team": "commerce"
+    },
+    {
+      "name": "shared-types",
+      "path": "../shared-types",
+      "role": "shared-lib",
+      "tech_stack": "node+typescript",
+      "owner_team": "platform"
+    },
+    {
+      "name": "api-gateway",
+      "path": "../api-gateway",
+      "role": "gateway",
+      "tech_stack": "nginx+lua",
+      "owner_team": "infra"
+    }
+  ]
+}
+```
+
+**Field definitions:**
+- `name` — unique identifier used in dependency graph and change plans
+- `path` — relative path from the root repo's parent directory (the directory containing `.planning/`)
+- `role` — service role from the vocabulary above; determines dependency ordering
+- `tech_stack` — technology used; informs which tools and commands to run
+- `owner_team` — team responsible; flagged in conflict reports and escalations
+
+## Cross-Repo Workflow
+
+### When to Use Feature Branches vs Trunk Per Repo
+
+**Feature branches per repo:**
+- Use when the change spans multiple repos and involves breaking API changes
+- Each repo gets its own branch (e.g., `feature/refresh-token-support`)
+- Branch per repo enables coordinated review before any deploy
+- Merge in dependency order: upstream merged and released before downstream merges
+
+**Trunk-based per repo:**
+- Use when the change is non-breaking (additive field, new optional endpoint)
+- Changes can be merged independently to each repo's main branch
+- Downstream consumers update on their own schedule
+- Safe because the old contract remains valid during transition
+
+Decision rule: if any change in the set is breaking for any consumer, use feature branches. If all changes are non-breaking, trunk-based is fine.
+
+## Contract-First Development Pattern
+
+For any cross-repo change involving an API:
+
+1. **Write the new contract first** — `@architect` produces the updated interface definition before any code is written
+2. **Review the contract in isolation** — confirm all affected teams agree before implementation starts
+3. **Implement upstream against the new contract** — `@coder` in the upstream repo
+4. **Implement downstream against the new contract** — `@coder` in each consumer repo, independently
+5. **Integration test** — verify upstream and downstream work together against the contract
+
+This pattern allows Wave 3 parallelism (upstream and downstream `@coder` agents can work simultaneously from the same contract) even across repos.
+
+## Breaking vs Non-Breaking API Changes
+
+### Non-Breaking (safe to deploy independently):
+- Adding a new optional field to a response object
+- Adding a new endpoint (existing endpoints unchanged)
+- Adding an optional request parameter
+- Relaxing a validation rule (e.g., allowing a longer string)
+- Adding a new event type to a message stream
+
+### Breaking (requires coordinated rollout):
+- Removing a field from a response object
+- Renaming an existing field
+- Changing a field's type (e.g., string → number)
+- Making an optional field required
+- Removing or renaming an endpoint
+- Changing the authentication scheme
+- Modifying an existing event schema in an incompatible way
+
+When a breaking change is unavoidable, use versioned paths (`/v2/endpoint`) to maintain the old contract alongside the new one during the transition window. Retire the old version only after all consumers have migrated.
+
+## Rollout Sequencing
+
+Changes deploy in dependency order. The general sequence:
+
+```
+1. shared-lib  →  publish new version (semver bump)
+2. upstream-api  →  canary → stage → prod
+3. downstream-consumers  →  canary → stage → prod (after upstream is in prod)
+4. gateway  →  route config update after all services are live in prod
+```
+
+**Canary phase:** 5% of traffic, monitor error rate and latency for 15 minutes before proceeding.
+**Stage phase:** full deploy to staging environment, run integration tests.
+**Prod phase:** full production deploy after stage passes.
+
+For breaking changes, complete the full canary → stage → prod cycle for the upstream before starting the canary phase for any downstream consumer. Mixed versions in prod during a breaking change window will cause errors.
+
+## Conflict Detection Rules
+
+Two concurrent changes conflict when:
+- Both change the same endpoint's response shape in incompatible ways
+- Both require incompatible versions of the same shared-lib
+- Both claim the same gateway route prefix
+- Both migrate the same database table in incompatible directions
+
+Conflicts must be resolved before any CHANGE PLAN is executed. The `@multi-repo-coordinator` surfaces conflicts with resolution options; the relevant `owner_team` decides.
+
+## Independence Check Before Executing
+
+Before running `/multi-repo`:
+- [ ] `.planning/config.json` has a `sub_repos` array with at least two entries
+- [ ] All `path` values resolve to actual directories on disk
+- [ ] Each repo has its own `.git` directory (they are separate repos, not subtrees)
+- [ ] You have read access to all repos in the registry