jdi-cli 0.1.0

package/core/skills/kiss/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: kiss
+description: KISS (Keep It Simple, Stupid). The simplest solution that solves the problem wins. Complexity only justified by real measured pain. Each layer/abstraction must pay its own cost. Applies in any language.
+type: skill
+applies_to: |
+  Loaded by doer when designing a new feature/module.
+  Loaded by reviewer at gate 5 to detect over-engineering.
+loaded_by:
+  - jdi-doer-{slug}
+  - jdi-reviewer-{slug}
+runtime_overrides:
+  antigravity:
+    triggers:
+      - "KISS"
+      - "keep simple"
+      - "over-engineering"
+      - "simplicity"
+---
+
+# Skill: KISS
+
+> Simplicity is the best design. Every complexity must pay its own cost.
+
+KISS is not "dumb code". It's **rejecting unjustified complexity**. Every interface, every layer, every abstraction has maintenance cost — only worth it if it solves real pain.
+
+## Rules
+
+### 1. Default is the simplest
+
+Ask before adding:
+- **Function** vs class vs framework?
+- **Variable** vs config vs feature flag?
+- **If/else** vs strategy pattern vs plugin system?
+- **Sync** vs async vs queue vs event bus?
+- **Inline** vs helper vs lib?
+
+Start with the leftmost. Only step up if there is a real requirement.
+
+### 2. Complexity must justify pain
+
+**Allowed:**
+- New pattern if it has 3+ real cases using it
+- Abstraction layer if it has 2+ implementations that exist today
+- Cache if measurement shows hot path
+- Async if there's unacceptable latency synchronous
+- Plugin system if there are confirmed external extenders
+
+**Forbidden:**
+- "Will scale later" without current requirement
+- "Other people might need it" without other people
+- "To make it generic" without 2nd use case
+- "Will look cleaner" trading 5 clear lines for 50 elegant ones
+- Enterprise pattern in small codebase (Repository + UoW + Mediator + CQRS for 10-controller app)
+
+### 3. Cognitive load is a real metric
+
+Code you read 10x and write 1x. Optimize for reading:
+- **Named variables** > composite expression
+- **Early return** > nested if/else
+- **Linear function** > jumps between callbacks
+- **Explicit types** > magical inference in large codebase
+- **Simple procedural code** > fancy OOP for 50 lines
+
+Rule: code that needs a comment explaining "why so complex" is too complex.
+
+### 4. Indicators of over-engineering
+
+Signs the code went over the line:
+
+- Interface with 1 implementation
+- Factory/Builder for something instantiated 1x
+- Generic <T> only used with 1 type
+- Config with a key that never changed
+- Abstraction layer that only encapsulates a call to another layer (pass-through)
+- Inheritance hierarchy > 2 levels
+- File with more setup than logic
+- Test that needs 30 lines of mock to run 5 lines of logic
+
+### 5. Refactor is the opposite direction
+
+Natural tendency: code grows in complexity. Refactoring = REMOVE complexity that no longer pays.
+
+Ask:
+- Does this layer still exist to solve a problem, or did it become tradition?
+- Does this abstraction have 2+ implementations today?
+- If I delete this, what breaks?
+- Can I solve it with 5 lines instead of 50?
+
+## Anti-patterns
+
+| Anti-pattern | Symptom |
+|---|---|
+| Interface + 1 implementation | `IUserService` + `UserService` (only 1) — delete the interface, use the class |
+| Generic `<T>` used with 1 type | `Repository<User>` but never `Repository<Order>` — concretize |
+| Factory for new() | `UserFactory.create()` that only does `return new User()` |
+| Config string that never changed | `MAX_RETRIES: 3` in config + nobody ever changed it — hardcode |
+| Inheritance > 2 levels | `BaseEntity -> AuditableEntity -> SoftDeletableEntity -> User` — flatten via composition |
+| Pass-through layer | `Controller -> Service -> Repository -> DbContext` where Service only calls Repository without logic — delete Service |
+| Enterprise pattern without demand | Mediator/CQRS in small app — replace with direct call |
+| Comment explaining "why so complex" | Code lost the war — refactor |
+| Mock setup > logic test | Test gets fragile; code under test is over-coupled |
+| Unused future-proof params | `(opts?: { future?: boolean })` without caller passing — remove |
+
+## Procedure
+
+### Doer (before writing)
+
+1. Ask: "What is the **simplest** version that meets the current requirement?"
+2. Write that version.
+3. Only step up complexity if you hit real pain.
+4. After writing, ask: "Can I delete any layer/parameter/abstraction without losing functionality?"
+
+### Reviewer (gate 5)
+
+Over-engineering heuristics:
+
+```bash
+# Interfaces with 1 implementation
+grep -RnE '^(public |export )?interface I?[A-Z]\w+' src/ | while read iface; do
+  name=$(echo "$iface" | grep -oE '[A-Z]\w+\b' | head -1)
+  count=$(grep -RnE "class \w+\s*:\s*$name|implements $name" src/ | wc -l)
+  [[ $count -eq 1 ]] && echo "WARN: $iface has only 1 implementation"
+done
+
+# Deep inheritance (> 2 levels)
+# (depends on stack — specific heuristic)
+
+# Very large or nested functions
+grep -cE '^\s{20,}\S' src/**/*  # lines with 20+ spaces = deep nesting
+```
+
+Match -> WARN with suggestion to simplify.
+
+## Inputs
+
+- Diff/content of the file
+- Context: codebase size (over-engineering is relative)
+
+## Outputs
+
+Does NOT produce a file. Modifies judgement.
+
+## Examples
+
+### Example 1: Interface with 1 impl
+
+Wrong:
+```typescript
+interface ILogger { log(msg: string): void }
+class ConsoleLogger implements ILogger { log(msg) { console.log(msg) } }
+const logger: ILogger = new ConsoleLogger()
+```
+
+Right (KISS):
+```typescript
+function log(msg: string) { console.log(msg) }
+// or
+class Logger { static log(msg: string) { console.log(msg) } }
+```
+
+Add interface when 2nd impl arrives, not before.
+
+### Example 2: Pass-through service
+
+Wrong:
+```csharp
+public class UserService {
+  public User GetById(int id) => _repo.GetById(id);  // only calls repo
+}
+```
+
+Right: use `_repo` directly in the controller. Add Service when there is real logic (validation, multi-step, transaction, event).
+
+### Example 3: Hardcodable config
+
+Wrong: `appsettings.json -> "MaxItemsPerPage": 50` that nobody ever changed in 2 years.
+
+Right: `const MAX_ITEMS_PER_PAGE = 50` in the code. Move back to config if some client actually needs to customize.

package/core/skills/solid/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: solid
+description: SOLID. Robert C. Martin's 5 OO design principles - SRP, OCP, LSP, ISP, DIP. Applicable in any language with types/classes/interfaces (C#, Java, TS, Python, Go, Rust, Kotlin, Swift, etc). Direct summary + anti-patterns + detection heuristics.
+type: skill
+applies_to: |
+  Loaded by doer when designing classes/modules/interfaces.
+  Loaded by reviewer at gate 5 to detect structural violations.
+loaded_by:
+  - jdi-doer-{slug}
+  - jdi-reviewer-{slug}
+runtime_overrides:
+  antigravity:
+    triggers:
+      - "SOLID"
+      - "SOLID principles"
+      - "SRP OCP LSP ISP DIP"
+      - "OO design"
+---
+
+# Skill: SOLID
+
+5 design principles — **S**ingle Responsibility, **O**pen/Closed, **L**iskov Substitution, **I**nterface Segregation, **D**ependency Inversion.
+
+Applicable in any language with classes or interfaces. In FP/procedural, principles map to modules and functions (SRP: 1 function 1 responsibility; ISP: minimal parameters; DIP: dependency injection via parameter).
+
+## S - Single Responsibility Principle (SRP)
+
+> A class/module must have **1 reason to change**.
+
+**1 reason = 1 stakeholder or 1 axis of change**, not "1 action".
+
+`UserService` that does auth + persistence + sends email violates — there are 3 reasons to change (security team changes auth, DBA changes persistence, marketing changes email).
+
+### Violation symptoms
+- Class with generic name (`Manager`, `Helper`, `Service`, `Util`)
+- Methods without thematic coherence
+- Multiple imports of unrelated libraries (DB + email + crypto in the same class)
+- Diff of one class affects separate domains in different sprints
+
+### Fix
+Extract responsibilities into separate classes:
+- `UserAuthenticator` (auth)
+- `UserRepository` (persistence)
+- `UserNotifier` (email)
+
+Compose in a coordinator if needed, but each piece has 1 reason.
+
+## O - Open/Closed Principle (OCP)
+
+> Open for **extension**, closed for **modification**.
+
+Adding new behavior shouldn't require editing tested code. Use polymorphism, strategy, plugins, or config — not infinite if/else.
+
+### Violation symptoms
+- `switch (type)` that grows with every new feature
+- `if (provider === "x") ... else if ... else if ...`
+- Each new feature edits N existing classes instead of adding 1 new one
+
+### Fix
+- **Strategy pattern**: each case becomes an impl of an interface
+- **Polymorphism**: subclass override instead of external switch
+- **Registry**: `registry.register("x", handler)` — new feature just adds
+- **Visitor**: for closed type hierarchies
+
+### When to ignore
+OCP is aspirational, not absolute. Apply at points of **known** variation (payment strategies are multiple), don't speculate (KISS + YAGNI).
+
+## L - Liskov Substitution Principle (LSP)
+
+> Subtype must be **substitutable** for the supertype without breaking behavior.
+
+If `Bird` has method `fly()`, `Penguin extends Bird` violates LSP — penguin doesn't fly. Caller receiving `Bird` breaks when it receives `Penguin`.
+
+### Violation symptoms
+- Subclass that **throws exception** on inherited method ("not supported")
+- Subclass that **strengthens precondition** (`base accepts >= 0`, sub accepts `> 0`)
+- Subclass that **weakens postcondition** (base guarantees "sorted", sub doesn't guarantee)
+- Caller needs `if (instanceof Subtype)` to handle a special case
+
+### Fix
+- Rethink hierarchy: `Penguin` isn't a flying `Bird`, it's a `Bird` that walks. Create `FlyingBird : Bird` and `Penguin : Bird` without fly.
+- Composition over inheritance: prefer composed interfaces over deep hierarchies.
+- Refactor to capabilities: `Flyable`, `Swimmable`, `Walkable` (overlap with ISP).
+
+## I - Interface Segregation Principle (ISP)
+
+> Clients should not be forced to depend on interfaces they **do not use**.
+
+Big interfaces ("fat interfaces") force impls to stub meaningless methods (throwing NotImplemented), and callers to import broad dependencies.
+
+### Violation symptoms
+- Interface with 15 methods, each caller uses 2-3
+- Impl with several methods throwing `throw new NotImplementedException()`
+- Huge test mock to use 1 method of the interface
+
+### Fix
+Split into smaller, cohesive interfaces:
+```
+IFileReader { read() }
+IFileWriter { write() }
+// callers pick the subset they need
+```
+
+In FP/Go, same principle: minimal parameters, structural typing doesn't force implementing everything.
+
+## D - Dependency Inversion Principle (DIP)
+
+> High-level modules **do not** depend on low-level. Both depend on **abstractions**.
+
+Business logic doesn't care about "PostgreSQL", "AWS S3", "SendGrid". It cares about abstractions (`UserRepository`, `BlobStorage`, `EmailSender`). Concrete implementations live in outer layers.
+
+### Violation symptoms
+- Domain class imports `pg`, `aws-sdk`, `sendgrid`, `axios`
+- Business logic testable only with real infra (DB up, S3 mocked, etc)
+- Swapping provider requires rewriting business logic
+
+### Fix
+- **Dependency injection** (constructor / property / parameter)
+- Define interfaces in the domain module; impls live in infra/adapter layer (overlap with Hexagonal/Clean Architecture)
+- Composition root injects the right impl
+
+### DIP != IoC container
+DIP is a principle. IoC container is **one** tool. You can apply DIP with manual constructor, simple factory, or parameter injection — no framework.
+
+## Summary of the 5
+
+| Letter | Focus | Key question |
+|---|---|---|
+| **S** | Unit cohesion | How many reasons to change this class/module? (>1 = violates) |
+| **O** | Stability against extension | Does adding a new feature edit tested code or add new code? |
+| **L** | Inheritance contract | Does replacing parent with child break any caller? |
+| **I** | Interface size | Does every impl/caller use all methods? |
+| **D** | Direction of dependency | Does domain import infra or does infra import domain? |
+
+## General anti-patterns
+
+| Anti-pattern | Principle violated |
+|---|---|
+| `God class` with 30+ heterogeneous methods | SRP |
+| `switch (kind)` in N callers, grows with each feature | OCP |
+| Subclass with `throw NotSupportedException()` | LSP |
+| `IRepository` with 20 generic methods | ISP |
+| Domain service importing concrete ORM | DIP |
+| Inheritance > 3 levels | LSP + SRP (usually) |
+| Constructor with 8+ parameters | SRP (too many responsibilities) |
+| Util class with 50 unrelated functions | SRP |
+
+## Procedure
+
+### Doer
+
+Before creating class/module/interface:
+- **SRP**: describe in 1 sentence. If you need "and", split.
+- **ISP**: list expected callers. Does each one need **all** methods? If not, split.
+- **DIP**: what does this depend on? Concretions (DB, HTTP, FS) -> inject as abstraction.
+
+Before subclassing:
+- **LSP**: does substitution by parent work in all callers? If not, wrong hierarchy.
+
+Before adding `if/switch` at a growing point:
+- **OCP**: is strategy/registry worth it?
+
+### Reviewer (gate 5)
+
+```bash
+# SRP — very large classes
+find src/ -name '*.cs' -o -name '*.ts' -o -name '*.py' | while read f; do
+  loc=$(wc -l < "$f")
+  [[ $loc -gt 400 ]] && echo "WARN SRP: $f has $loc lines, possible god class"
+done
+
+# OCP — big switches on hot paths
+grep -RnE 'switch\s*\(' src/ | head
+# (manually: evaluate if it grows with each feature)
+
+# LSP — NotImplemented in subclass
+grep -RnE 'NotImplemented|UnsupportedOperation|throw new.*not (implemented|supported)' src/
+
+# ISP — giant interfaces
+grep -RnA50 '^(public |export )?interface' src/ | grep -cE '^\s+\w+\s*\(' | sort -rn
+# count > 10 methods -> WARN
+
+# DIP — domain module importing concretions
+grep -RnE 'from.*pg|from.*aws-sdk|using Npgsql|using AWSSDK' src/domain/ src/core/
+```
+
+Relevant match -> WARN with principle cited.
+
+## Inputs
+
+- Diff/content of the file
+- Project structure (to detect domain vs infra)
+
+## Outputs
+
+Does NOT produce a file. Modifies judgement.
+
+## Examples
+
+### Example 1: SRP violated
+
+Wrong:
+```csharp
+public class OrderService {
+  public Order Create(...) { /* validate + save + email + log + audit */ }
+}
+```
+
+5 reasons to change.
+
+Right:
+```csharp
+public class OrderValidator { }
+public class OrderRepository { }
+public class OrderNotifier { }
+public class OrderService {
+  public Order Create(...) {
+    _validator.Validate(...)
+    var order = _repo.Save(...)
+    _notifier.Notify(order)
+    return order;
+  }
+}
+```
+
+### Example 2: OCP violated
+
+Wrong:
+```typescript
+function calcDiscount(type: string, amount: number) {
+  if (type === "vip") return amount * 0.2
+  else if (type === "newcomer") return amount * 0.1
+  else if (type === "blackfriday") return amount * 0.5
+  return 0
+}
+```
+
+Each new type edits this function.
+
+Right:
+```typescript
+const strategies: Record<string, (amount: number) => number> = {
+  vip: a => a * 0.2,
+  newcomer: a => a * 0.1,
+  blackfriday: a => a * 0.5,
+}
+function calcDiscount(type: string, amount: number) {
+  return strategies[type]?.(amount) ?? 0
+}
+```
+
+New type: register in `strategies`, don't touch `calcDiscount`.
+
+### Example 3: DIP violated
+
+Wrong:
+```python
+# domain/order.py
+import psycopg2
+class OrderService:
+  def get(self, id):
+    conn = psycopg2.connect(...)
+    ...
+```
+
+Domain coupled to Postgres.
+
+Right:
+```python
+# domain/order.py
+class OrderService:
+  def __init__(self, repo: OrderRepository):  # abstraction
+    self._repo = repo
+  def get(self, id): return self._repo.get(id)
+
+# infra/postgres_order_repo.py
+class PostgresOrderRepository(OrderRepository):
+  def get(self, id): ...  # concrete impl
+```
+
+Domain doesn't know Postgres exists.

package/core/skills/yagni/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: yagni
+description: YAGNI (You Aren't Gonna Need It). Build only what the current requirement asks for. Generalize after the 3rd real case, never before. Code not written is code with no bug, no maintenance cost, no pending test. Applies in any language.
+type: skill
+applies_to: |
+  Loaded by doer when planning implementation.
+  Loaded by reviewer at gate 5 to detect speculative code.
+loaded_by:
+  - jdi-doer-{slug}
+  - jdi-reviewer-{slug}
+runtime_overrides:
+  antigravity:
+    triggers:
+      - "YAGNI"
+      - "speculative code"
+      - "future-proof"
+      - "premature abstraction"
+---
+
+# Skill: YAGNI
+
+> You aren't gonna need it.
+
+YAGNI is discipline against **speculative code**: features, abstractions, parameters, hooks, layers, configs that exist "in case it's needed". In 90% of cases, never needed — and when needed, the requirement is different from what you imagined.
+
+## Rules
+
+### 1. Build only what the current requirement asks
+
+Ask of every new line of code:
+- **Does this functionality have a requirement today?**
+- **Who is the caller that needs this NOW?**
+
+If there's no real caller, don't write it. Dead code is **net negative**: latent bug, maintenance cost, distraction in review, hinders refactor.
+
+### 2. Generalize after the 3rd real case
+
+Sandi Metz: "Duplication is far cheaper than the wrong abstraction."
+
+- 1 case: implement specific
+- 2 cases: copy or minimally parameterize
+- 3 cases: now extract real pattern (one you **saw** happen, not imagined)
+
+Generalizing earlier couples callers to the wrong interface. Refactoring later to the right interface is cheap; breaking callers to swap a wrong generic interface is expensive.
+
+### 3. Costs of speculative code
+
+Every "in case it's needed" line costs:
+
+- **Maintenance**: someone will touch it when refactoring the neighborhood
+- **Confusion**: reader thinks "this is being used, must be important"
+- **Tests**: untested code becomes a bomb; tested, wasted time
+- **Coupling**: callers will couple to the speculative interface, making it hard to remove
+- **Scope creep**: simple feature becomes complex feature
+- **Bug surface**: a line that doesn't exist has no bug
+
+### 4. What YAGNI is NOT
+
+YAGNI is not an excuse to:
+- **Hardcoded everywhere**: some extension points are real requirements (i18n, logging, auth)
+- **Cut real requirement**: if ticket asks for X, deliver X complete, not half
+- **Skip security/error handling**: these are universal requirements, not speculative
+- **Raw illegible code**: clarity is a requirement, not speculation
+- **Skip tests**: coverage is a contract
+
+### 5. Symptoms of violation
+
+Code smells of broken YAGNI if:
+
+- Optional parameters never passed (`fn(a, b, opts?: {...})` with opts always `undefined`)
+- Hooks/events without subscribers
+- Plugin system without plugins
+- Config "in case we want to change" that nobody ever changed
+- Interface with 1 impl (overlap with KISS)
+- Generic `<T>` used with only 1 type
+- "Future-proof" architecture written to scale 100x before validating current requirement
+- Branches in code for scenarios nobody can describe
+
+### 6. How to remove
+
+After discovering speculative code:
+1. Confirm nobody calls (`grep` callers)
+2. Delete. Yes, delete directly. Git keeps history.
+3. Don't leave "// removed on XX/YY" — more trash.
+4. If you find out later you need it, add it when you need it (safe bet: later you know the real requirement, not imagined).
+
+## Anti-patterns
+
+| Anti-pattern | Why it violates |
+|---|---|
+| Optional parameter never used | Adds surface area without benefit |
+| "Generic" function used by 1 caller | Generalized too early |
+| Plugin/extension point without extenders | Dead code carries maintenance |
+| "Configurable" config nobody changes | False flexibility — becomes hardcode later |
+| Try/catch for impossible exception | Indicates fear, not requirement |
+| Defensive validation for value coming from a safe type | TypeScript/C#/Python types already guarantee |
+| `for/while` instead of direct return for "future looping" | Invents speculative repetition |
+| Layer "to make it generic" without 2nd impl | Speculation with pass-through cost |
+| Comment "TODO: extend to X later" without ticket | Message to nobody |
+| Abstraction with 1 concrete implementation | Generic abstraction without second case |
+| `enum` with 1 value "will grow" | Add value when it appears |
+
+## Procedure
+
+### Doer (before/during implementation)
+
+Before adding:
+
+1. **Is there a current requirement?** (ticket, conversation, explicit business rule) Otherwise, don't add.
+2. **Who calls this today?** If nobody, don't add.
+3. **When will I use that flexibility?** If "don't know", don't add.
+
+After writing, ask:
+- Is there a parameter/config/branch that could disappear without losing requirement?
+
+### Reviewer (gate 5)
+
+Heuristics:
+
+```bash
+# Optional parameters never passed
+# (depends on stack — examples)
+grep -RnE 'function \w+\([^)]*opts\?:' src/  # TS
+grep -RnE '\([^)]*=\s*null\)' src/            # optional default null
+
+# "TODO: extend" code
+grep -RnE 'TODO.*(extend|future|reserved|placeholder|in case)' src/
+
+# Try/catch without clear reason
+grep -RnA3 'try\s*{' src/ | grep -B1 'catch.*:.*ignore'
+
+# Declared and unused variables
+# (linter already catches — confirm in review)
+
+# Plugin/extension points
+grep -RnE 'register|registerPlugin|EventEmitter|hook(' src/
+# Cross-check: are there actually callers?
+```
+
+3+ matches without real caller -> WARN.
+
+## Inputs
+
+- File diff (focus on additions)
+- List of callers if any
+
+## Outputs
+
+Does NOT produce a file. Modifies judgement — doer avoids writing, reviewer marks WARN.
+
+## Examples
+
+### Example 1: Speculative optional param
+
+Wrong:
+```python
+def send_email(to: str, subject: str, body: str,
+               cc: list[str] = None,
+               bcc: list[str] = None,
+               attachments: list[Path] = None,
+               priority: str = "normal",
+               retry_count: int = 3,
+               on_failure: Callable = None):
+    ...
+```
+
+Current requirement is to send simple email (`to, subject, body`). The other 5 params are speculative.
+
+Right:
+```python
+def send_email(to: str, subject: str, body: str):
+    ...
+```
+
+Add `cc`, `bcc` etc **when** real requirement arrives, not before.
+
+### Example 2: Plugin system without plugins
+
+Wrong:
+```typescript
+class PaymentProcessor {
+  private plugins: Plugin[] = []
+  registerPlugin(p: Plugin) { this.plugins.push(p) }
+  process(...) {
+    this.plugins.forEach(p => p.beforeProcess())
+    // logic
+    this.plugins.forEach(p => p.afterProcess())
+  }
+}
+```
+
+Has 0 plugins registered. Whole plugin system is dead code.
+
+Right:
+```typescript
+class PaymentProcessor {
+  process(...) { /* logic */ }
+}
+```
+
+When the 1st real plugin appears, then yes. Not before.
+
+### Example 3: Unused config string
+
+Wrong: `config.json -> "DEFAULT_LANGUAGE": "pt-BR"` but nobody reads it. Code uses `"pt-BR"` directly.
+
+Right: delete the config. Add it when the multi-language feature is actually implemented.