jdi-cli 0.1.0

package/runtimes/opencode/skills/solid/SKILL.md

@@ -0,0 +1,267 @@
+---
+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.
+---
+
+# 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/runtimes/opencode/skills/yagni/SKILL.md

@@ -0,0 +1,193 @@
+---
+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.
+---
+
+# 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.

package/templates-jdi-folder/config.json

@@ -0,0 +1,18 @@
+{
+  "$schema_version": "1.1",
+  "context_window": 200000,
+  "thresholds": {
+    "warn_pct": 60,
+    "critical_pct": 70
+  },
+  "budgets": {
+    "max_context_chars": 6000,
+    "max_plan_chars": 12000,
+    "max_summary_chars": 8192
+  },
+  "compaction": {
+    "keep_phases": 2,
+    "archive_after": 5
+  },
+  "coverage_min": 80
+}

package/templates-jdi-folder/registry.md

@@ -0,0 +1,31 @@
+# JDI — Registry
+
+Audit trail de tudo que o `jdi-architect` cria. Append-only.
+
+2 fontes:
+- `/jdi-create` (modo create) — agent/skill generico em `core/`
+- `/jdi-bootstrap` (modo specialist) — doer + reviewer per-project em `.jdi/agents/`
+
+Cada entrada documenta: o que, por que, quando, como invocar.
+
+## Format
+
+```markdown
+## R-{N} ({date ISO})
+**Tipo:** {agent | skill | composite | specialist}
+**Nome ou slug:** {jdi-{nome}} ou {todo-app}
+**Criado por:** /jdi-create | /jdi-bootstrap | manual
+**Por que:** {razao em 1-2 linhas}
+**Substitui:** {agent/skill anterior, se refactor}
+**Files:**
+- {path 1}
+- {path 2}
+**Integration:**
+- {arquivo atualizado}
+- {arquivo atualizado}
+**Removido em:** {data + razao, se foi removido depois}
+```
+
+## Entries
+
+<!-- Append abaixo. Mais recente no fim. -->

package/templates-jdi-folder/reviewers.md

@@ -0,0 +1,33 @@
+# Reviewers
+
+Per-project reviewer specialists. `/jdi-verify <N>` le esse arquivo.
+
+Veredicto: APPROVED / APPROVED_WITH_WARNINGS / BLOCKED. BLOCKED bloqueia o `/jdi-ship`.
+
+## Format
+
+```markdown
+| Agent | Trigger | Bloqueia ship? |
+|---|---|---|
+| jdi-reviewer-{slug} | /jdi-verify | sim, se BLOCKED |
+```
+
+Reviewers ficam em `.jdi/agents/jdi-reviewer-{slug}.md` (per-project).
+
+## Como sao criados
+
+Junto com o doer, via `/jdi-bootstrap` -> `jdi-architect` modo specialist. Template base em `core/templates/reviewer-specialist.md`.
+
+Gates default (cada reviewer customiza):
+- Build
+- Tests
+- Coverage (threshold do PROJECT.md, default 80%)
+- Lint/Format
+- Security/Perf rules da stack
+- Plan consistency
+
+## Entries
+
+| Agent | Trigger | Bloqueia ship? |
+|---|---|---|
+<!-- Append abaixo via /jdi-bootstrap -->

package/templates-jdi-folder/skills-registry.md

@@ -0,0 +1,32 @@
+# Skills Registry
+
+Skills disponiveis pros agents JDI carregarem on-demand.
+
+Skill = procedimento reusavel. Sem decision loop proprio. Carregado inline pelo agent pai.
+
+## Format
+
+```markdown
+| Skill | Path | Quando aplicar | Loaded by |
+|---|---|---|---|
+| {nome} | core/skills/{nome}/ | {trigger} | {lista de agents} |
+```
+
+## Como agents carregam
+
+Cada agent tem uma secao `<skills_to_load>` no prompt:
+
+```markdown
+<skills_to_load>
+- {skill-nome}: aplica quando {condicao}
+- {outra-skill}: aplica quando {condicao}
+</skills_to_load>
+```
+
+Agent le essa secao, carrega skill via Read no path correspondente, segue o procedure.
+
+## Entries
+
+| Skill | Path | Quando aplicar | Loaded by |
+|---|---|---|---|
+<!-- Append abaixo via /jdi-create -->

package/templates-jdi-folder/specialists.md

@@ -0,0 +1,39 @@
+# Specialists
+
+Per-project doer specialists. Cada projeto tem 1 doer (ou mais, se multi-stack).
+
+`/jdi-do <N>` le esse arquivo. Match -> spawn specialist registrado.
+
+## Format
+
+```markdown
+| Stack | Agent | Trigger |
+|---|---|---|
+| {stack} | jdi-doer-{slug} | {quando aplicar} |
+```
+
+Specialists ficam em `.jdi/agents/jdi-doer-{slug}.md` (per-project, NAO no `core/`).
+
+## Como sao criados
+
+`/jdi-bootstrap` invoca o `jdi-architect` em modo specialist:
+
+1. Le `.jdi/PROJECT.md`
+2. 6 perguntas focadas (test framework, build/test commands, coverage min, lint, conventions)
+3. Substitui placeholders em `core/templates/doer-specialist.md`
+4. Write em `.jdi/agents/jdi-doer-{slug}.md`
+5. Append linha aqui
+
+## Multi-stack (futuro)
+
+Projeto com backend + frontend pode ter 2 doers:
+- `jdi-doer-{slug}-backend` (ex: .NET)
+- `jdi-doer-{slug}-frontend` (ex: React)
+
+`/jdi-do <N>` decide qual chamar baseado em `files_modified` do PLAN.md. Hoje `/jdi-bootstrap` cria 1 doer agregado — multi-doer eh feature pendente.
+
+## Entries
+
+| Stack | Agent | Trigger |
+|---|---|---|
+<!-- Append abaixo via /jdi-bootstrap -->