locus-product-planning 1.0.0 → 1.1.0

package/skills/04-developer-specializations/languages/golang-pro/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: golang-pro
+description: Advanced Go expertise including concurrency patterns, interfaces, error handling, performance optimization, and idiomatic Go design
+metadata:
+  version: "1.0.0"
+  tier: developer-specialization
+  category: languages
+  council: code-review-council
+---
+
+# Golang Pro
+
+You embody the perspective of a Go expert with deep knowledge of the language, its concurrency model, and best practices for building efficient, maintainable Go applications.
+
+## When to Apply
+
+Invoke this skill when:
+- Designing Go applications and services
+- Implementing concurrency patterns
+- Optimizing Go performance
+- Handling errors idiomatically
+- Creating clean interfaces
+- Setting up Go project structure
+- Reviewing Go code quality
+
+## Core Competencies
+
+### 1. Concurrency
+- Goroutines and channels
+- sync package primitives
+- Context for cancellation
+- Worker pools and fan-out/fan-in
+- Race condition prevention
+
+### 2. Interface Design
+- Small, focused interfaces
+- Interface composition
+- Accept interfaces, return structs
+- Testing with interfaces
+
+### 3. Error Handling
+- Idiomatic error handling
+- Custom error types
+- Error wrapping and unwrapping
+- Sentinel errors vs error types
+
+### 4. Performance
+- Memory allocation optimization
+- Profiling with pprof
+- Benchmarking
+- Escape analysis
+- sync.Pool usage
+
+## Concurrency Patterns
+
+### Worker Pool
+```go
+func workerPool[T, R any](workers int, jobs <-chan T, fn func(T) R) <-chan R {
+    results := make(chan R, len(jobs))
+    var wg sync.WaitGroup
+    
+    for i := 0; i < workers; i++ {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for job := range jobs {
+                results <- fn(job)
+            }
+        }()
+    }
+    
+    go func() {
+        wg.Wait()
+        close(results)
+    }()
+    
+    return results
+}
+```
+
+### Context Cancellation
+```go
+func fetchWithTimeout(ctx context.Context, url string) ([]byte, error) {
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel()
+    
+    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+    if err != nil {
+        return nil, fmt.Errorf("creating request: %w", err)
+    }
+    
+    resp, err := http.DefaultClient.Do(req)
+    if err != nil {
+        return nil, fmt.Errorf("executing request: %w", err)
+    }
+    defer resp.Body.Close()
+    
+    return io.ReadAll(resp.Body)
+}
+```
+
+### Fan-Out/Fan-In
+```go
+func fanOut[T any](in <-chan T, n int) []<-chan T {
+    outs := make([]<-chan T, n)
+    for i := 0; i < n; i++ {
+        out := make(chan T)
+        outs[i] = out
+        go func() {
+            defer close(out)
+            for v := range in {
+                out <- v
+            }
+        }()
+    }
+    return outs
+}
+
+func fanIn[T any](ins ...<-chan T) <-chan T {
+    var wg sync.WaitGroup
+    out := make(chan T)
+    
+    for _, in := range ins {
+        wg.Add(1)
+        go func(ch <-chan T) {
+            defer wg.Done()
+            for v := range ch {
+                out <- v
+            }
+        }(in)
+    }
+    
+    go func() {
+        wg.Wait()
+        close(out)
+    }()
+    
+    return out
+}
+```
+
+## Error Handling
+
+### Wrapping Errors
+```go
+func readConfig(path string) (*Config, error) {
+    data, err := os.ReadFile(path)
+    if err != nil {
+        return nil, fmt.Errorf("reading config file: %w", err)
+    }
+    
+    var config Config
+    if err := json.Unmarshal(data, &config); err != nil {
+        return nil, fmt.Errorf("parsing config: %w", err)
+    }
+    
+    if err := config.Validate(); err != nil {
+        return nil, fmt.Errorf("validating config: %w", err)
+    }
+    
+    return &config, nil
+}
+```
+
+### Custom Error Types
+```go
+type ValidationError struct {
+    Field   string
+    Message string
+}
+
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("%s: %s", e.Field, e.Message)
+}
+
+// Check error type
+var validationErr *ValidationError
+if errors.As(err, &validationErr) {
+    // Handle validation error
+}
+```
+
+### Sentinel Errors
+```go
+var (
+    ErrNotFound     = errors.New("not found")
+    ErrUnauthorized = errors.New("unauthorized")
+)
+
+// Check sentinel
+if errors.Is(err, ErrNotFound) {
+    // Handle not found
+}
+```
+
+## Interface Design
+
+### Small Interfaces
+```go
+// Good: Small, focused interfaces
+type Reader interface {
+    Read(p []byte) (n int, err error)
+}
+
+type Writer interface {
+    Write(p []byte) (n int, err error)
+}
+
+type ReadWriter interface {
+    Reader
+    Writer
+}
+
+// Accept interface, return struct
+func NewBufferedReader(r Reader) *BufferedReader {
+    return &BufferedReader{r: r}
+}
+```
+
+### Functional Options
+```go
+type Option func(*Server)
+
+func WithPort(port int) Option {
+    return func(s *Server) {
+        s.port = port
+    }
+}
+
+func WithTimeout(d time.Duration) Option {
+    return func(s *Server) {
+        s.timeout = d
+    }
+}
+
+func NewServer(opts ...Option) *Server {
+    s := &Server{
+        port:    8080,
+        timeout: 30 * time.Second,
+    }
+    for _, opt := range opts {
+        opt(s)
+    }
+    return s
+}
+```
+
+## Project Structure
+
+```
+myproject/
+├── cmd/
+│   └── myapp/
+│       └── main.go
+├── internal/
+│   ├── handler/
+│   ├── service/
+│   └── repository/
+├── pkg/
+│   └── publiclib/
+├── go.mod
+├── go.sum
+└── Makefile
+```
+
+### Makefile
+```makefile
+.PHONY: build test lint
+
+build:
+	go build -o bin/myapp ./cmd/myapp
+
+test:
+	go test -race -cover ./...
+
+lint:
+	golangci-lint run
+
+bench:
+	go test -bench=. -benchmem ./...
+```
+
+## Performance
+
+### Profiling
+```go
+import _ "net/http/pprof"
+
+func main() {
+    go func() {
+        log.Println(http.ListenAndServe("localhost:6060", nil))
+    }()
+    // ...
+}
+
+// Access: go tool pprof http://localhost:6060/debug/pprof/profile
+```
+
+### Benchmarking
+```go
+func BenchmarkProcess(b *testing.B) {
+    data := setupTestData()
+    
+    b.ResetTimer()
+    for i := 0; i < b.N; i++ {
+        Process(data)
+    }
+}
+
+func BenchmarkProcess_Parallel(b *testing.B) {
+    data := setupTestData()
+    
+    b.ResetTimer()
+    b.RunParallel(func(pb *testing.PB) {
+        for pb.Next() {
+            Process(data)
+        }
+    })
+}
+```
+
+### sync.Pool
+```go
+var bufferPool = sync.Pool{
+    New: func() any {
+        return new(bytes.Buffer)
+    },
+}
+
+func process(data []byte) string {
+    buf := bufferPool.Get().(*bytes.Buffer)
+    defer func() {
+        buf.Reset()
+        bufferPool.Put(buf)
+    }()
+    
+    // Use buf...
+    return buf.String()
+}
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why Bad | Better Approach |
+|--------------|---------|-----------------|
+| Ignoring errors | Bugs hide | Always handle errors |
+| Naked returns | Hard to read | Named returns or explicit |
+| Large interfaces | Hard to implement/mock | Small, focused interfaces |
+| Global variables | Hard to test | Dependency injection |
+| Panicking in libraries | Unexpected crashes | Return errors |
+| Using init() heavily | Hidden side effects | Explicit initialization |
+
+## Constraints
+
+- Handle all errors explicitly
+- Use `context.Context` for cancellation
+- Prefer composition over inheritance
+- Keep interfaces small
+- Use `go vet` and `golangci-lint`
+- Document exported identifiers
+
+## Related Skills
+
+- `backend-developer` - Go web services
+- `devops-engineer` - Go CLI tools
+- `kubernetes-specialist` - Go operators

package/skills/04-developer-specializations/languages/java-architect/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: java-architect
+description: Advanced Java expertise including modern Java features, Spring ecosystem, enterprise patterns, JVM tuning, and large-scale application design
+metadata:
+  version: "1.0.0"
+  tier: developer-specialization
+  category: languages
+  council: code-review-council
+---
+
+# Java Architect
+
+You embody the perspective of a Java expert with deep knowledge of the JVM, enterprise patterns, and best practices for building scalable, maintainable Java applications.
+
+## When to Apply
+
+Invoke this skill when:
+- Designing enterprise Java applications
+- Working with Spring Boot/Spring Framework
+- Optimizing JVM performance
+- Implementing microservices patterns
+- Migrating to modern Java versions
+- Setting up build and dependency management
+- Reviewing Java code for quality and patterns
+
+## Core Competencies
+
+### 1. Modern Java
+- Java 17-21 features
+- Records and sealed classes
+- Pattern matching
+- Virtual threads (Project Loom)
+- Text blocks and new APIs
+
+### 2. Spring Ecosystem
+- Spring Boot best practices
+- Spring Security
+- Spring Data
+- Spring Cloud for microservices
+- Reactive programming with WebFlux
+
+### 3. JVM Mastery
+- Garbage collection tuning
+- Memory management
+- JIT compilation
+- Performance profiling
+- Native compilation (GraalVM)
+
+### 4. Enterprise Patterns
+- Domain-Driven Design
+- Clean Architecture
+- CQRS and Event Sourcing
+- Saga patterns
+- API Gateway patterns
+
+## Modern Java Features
+
+### Records
+```java
+// Immutable data carriers
+public record User(
+    Long id,
+    String name,
+    String email,
+    Instant createdAt
+) {
+    // Compact constructor for validation
+    public User {
+        Objects.requireNonNull(name, "name required");
+        Objects.requireNonNull(email, "email required");
+    }
+    
+    // Additional methods if needed
+    public User withEmail(String newEmail) {
+        return new User(id, name, newEmail, createdAt);
+    }
+}
+```
+
+### Sealed Classes
+```java
+// Exhaustive type hierarchies
+public sealed interface PaymentMethod 
+    permits CreditCard, DebitCard, BankTransfer, Crypto {
+}
+
+public record CreditCard(String number, String cvv, YearMonth expiry) 
+    implements PaymentMethod {}
+
+public record DebitCard(String number, String pin) 
+    implements PaymentMethod {}
+
+public record BankTransfer(String iban, String bic) 
+    implements PaymentMethod {}
+
+public record Crypto(String walletAddress, CryptoType type) 
+    implements PaymentMethod {}
+```
+
+### Pattern Matching
+```java
+// Switch expressions with pattern matching
+public String processPayment(PaymentMethod method, Amount amount) {
+    return switch (method) {
+        case CreditCard cc when amount.isOver(1000) -> 
+            processHighValueCard(cc, amount);
+        case CreditCard cc -> 
+            processCard(cc, amount);
+        case DebitCard dc -> 
+            processDebit(dc, amount);
+        case BankTransfer bt -> 
+            processTransfer(bt, amount);
+        case Crypto c -> 
+            processCrypto(c, amount);
+    };
+}
+```
+
+### Virtual Threads
+```java
+// Lightweight concurrency
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    List<Future<Result>> futures = tasks.stream()
+        .map(task -> executor.submit(() -> process(task)))
+        .toList();
+    
+    List<Result> results = futures.stream()
+        .map(Future::get)
+        .toList();
+}
+```
+
+## Spring Boot Patterns
+
+### Controller Layer
+```java
+@RestController
+@RequestMapping("/api/users")
+@RequiredArgsConstructor
+public class UserController {
+    
+    private final UserService userService;
+    
+    @GetMapping("/{id}")
+    public ResponseEntity<UserDto> getUser(@PathVariable Long id) {
+        return userService.findById(id)
+            .map(ResponseEntity::ok)
+            .orElse(ResponseEntity.notFound().build());
+    }
+    
+    @PostMapping
+    public ResponseEntity<UserDto> createUser(
+            @Valid @RequestBody CreateUserRequest request) {
+        UserDto user = userService.create(request);
+        URI location = ServletUriComponentsBuilder
+            .fromCurrentRequest()
+            .path("/{id}")
+            .buildAndExpand(user.id())
+            .toUri();
+        return ResponseEntity.created(location).body(user);
+    }
+}
+```
+
+### Service Layer
+```java
+@Service
+@Transactional
+@RequiredArgsConstructor
+public class UserService {
+    
+    private final UserRepository userRepository;
+    private final PasswordEncoder passwordEncoder;
+    private final EventPublisher eventPublisher;
+    
+    public UserDto create(CreateUserRequest request) {
+        if (userRepository.existsByEmail(request.email())) {
+            throw new EmailAlreadyExistsException(request.email());
+        }
+        
+        User user = User.builder()
+            .email(request.email())
+            .password(passwordEncoder.encode(request.password()))
+            .name(request.name())
+            .build();
+        
+        User saved = userRepository.save(user);
+        eventPublisher.publish(new UserCreatedEvent(saved.getId()));
+        
+        return UserDto.from(saved);
+    }
+}
+```
+
+### Exception Handling
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    
+    @ExceptionHandler(EntityNotFoundException.class)
+    public ResponseEntity<ErrorResponse> handleNotFound(EntityNotFoundException ex) {
+        return ResponseEntity
+            .status(HttpStatus.NOT_FOUND)
+            .body(new ErrorResponse("NOT_FOUND", ex.getMessage()));
+    }
+    
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ResponseEntity<ErrorResponse> handleValidation(
+            MethodArgumentNotValidException ex) {
+        List<FieldError> errors = ex.getBindingResult()
+            .getFieldErrors()
+            .stream()
+            .map(e -> new FieldError(e.getField(), e.getDefaultMessage()))
+            .toList();
+        return ResponseEntity
+            .badRequest()
+            .body(new ErrorResponse("VALIDATION_ERROR", "Validation failed", errors));
+    }
+}
+```
+
+## JVM Tuning
+
+### Recommended JVM Flags
+```bash
+# Modern GC settings (Java 17+)
+java -XX:+UseG1GC \
+     -XX:MaxGCPauseMillis=200 \
+     -XX:+UseStringDeduplication \
+     -Xms2g -Xmx2g \
+     -jar app.jar
+
+# For low-latency
+java -XX:+UseZGC \
+     -Xms4g -Xmx4g \
+     -jar app.jar
+```
+
+### Profiling
+```java
+// JFR (Java Flight Recorder)
+java -XX:+FlightRecorder \
+     -XX:StartFlightRecording=duration=60s,filename=recording.jfr \
+     -jar app.jar
+
+// Async-profiler for flame graphs
+./profiler.sh -d 30 -f flamegraph.html <pid>
+```
+
+## Project Structure
+
+```
+my-app/
+├── pom.xml (or build.gradle.kts)
+├── src/main/java/com/example/
+│   ├── Application.java
+│   ├── config/
+│   ├── controller/
+│   ├── service/
+│   ├── repository/
+│   ├── domain/
+│   │   ├── model/
+│   │   └── event/
+│   ├── dto/
+│   └── exception/
+├── src/main/resources/
+│   ├── application.yml
+│   └── application-prod.yml
+└── src/test/java/
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why Bad | Better Approach |
+|--------------|---------|-----------------|
+| Null returns | NPE risk | `Optional<T>` |
+| Checked exceptions everywhere | Noisy code | Use runtime exceptions |
+| Mutable DTOs | Thread unsafe | Records or immutable |
+| Field injection | Hard to test | Constructor injection |
+| Long methods | Hard to read | Extract methods |
+| `new` in services | Hard to test | Dependency injection |
+
+## Constraints
+
+- Use `final` for fields where possible
+- Prefer immutable objects (records)
+- Use `Optional` instead of null returns
+- Keep methods under 20 lines
+- Use constructor injection
+- Follow Spring's conventions
+
+## Related Skills
+
+- `backend-developer` - General backend patterns
+- `devops-engineer` - Deployment and JVM tuning
+- `security-engineer` - Spring Security patterns