jdi-cli 0.1.0

package/runtimes/antigravity/skills/yagni/SKILL.md

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

package/runtimes/claude/CLAUDE.md

@@ -0,0 +1,91 @@
+# JDI — Instrucoes Claude Code
+
+Este projeto usa o JDI (Just Do It) como workflow de desenvolvimento. JDI eh um workflow enxuto: 6 comandos no loop principal, 5 agents core + 2 per-project specialists.
+
+## Loop canonico
+
+```
+/jdi-new "<descricao>"   -> research + PROJECT.md + ROADMAP.md
+/jdi-bootstrap           -> cria specialists per-project (doer + reviewer)
+/jdi-discuss <N>         -> captura decisoes locked da phase
+/jdi-plan <N>            -> decompoe em tasks com waves
+/jdi-do <N>              -> executa via doer specialist
+/jdi-verify <N>          -> gates de qualidade via reviewer specialist
+/jdi-ship <N>            -> finaliza phase + avanca pra proxima
+```
+
+`/jdi-create [desc]` gera novos agents/skills genericos no `core/` (rodado dentro do repo JDI, nao de projetos consumindo).
+
+## Agents core (em `.claude/agents/`)
+
+Genericos, shipped pelo JDI:
+
+| Agent | Modelo | Funcao |
+|---|---|---|
+| `jdi-researcher` | Opus | Research pre-roadmap. Le ideia, pergunta, gera PROJECT.md + ROADMAP.md |
+| `jdi-bootstrap` | Sonnet | Dispara architect modo specialist pra gerar per-project doer + reviewer |
+| `jdi-asker` | Sonnet | Loop adaptativo de perguntas pra capturar decisoes locked (CONTEXT.md) |
+| `jdi-planner` | Opus | Decompoe phase em tasks, agrupa em waves de paralelismo (PLAN.md) |
+| `jdi-architect` | Opus | Meta-agent. 2 modos: cria agents/skills genericos no core/ OU cria specialists per-project |
+
+## Specialists per-project (em `.jdi/agents/`)
+
+Gerados pelo `/jdi-bootstrap` baseado em PROJECT.md:
+
+| Agent | Funcao |
+|---|---|
+| `jdi-doer-{slug}` | Executor que ja conhece stack/code-design/conventions do projeto. Sem descoberta, ja sabe |
+| `jdi-reviewer-{slug}` | Roda gates de qualidade definidos pra stack: build, tests, coverage, lint, security |
+
+Routing em `.jdi/specialists.md` e `.jdi/reviewers.md`.
+
+## Memoria — files em `.jdi/`
+
+```
+.jdi/
+  PROJECT.md          <- visao + stack + code-design locked
+  ROADMAP.md          <- phases + status
+  DECISIONS.md        <- D-XX append-only (decisoes locked)
+  STATE.md            <- current_phase + next_step
+  specialists.md      <- routing pro doer
+  reviewers.md        <- routing pro reviewer
+  registry.md         <- audit trail dos specialists criados
+  agents/             <- per-project specialists
+    jdi-doer-{slug}.md
+    jdi-reviewer-{slug}.md
+  phases/{NN-slug}/
+    CONTEXT.md        <- output do asker
+    PLAN.md           <- output do planner
+    SUMMARY.md        <- output do doer
+    REVIEW.md         <- output do reviewer
+```
+
+## Convencoes
+
+- Conventional Commits — scope = phase slug, ex: `feat(01-setup-api): ...`
+- Atomic commits — 1 task = 1 commit
+- 80% cobertura minima (overridable via PROJECT.md)
+- Code design locked uma vez no `/jdi-new`, nunca muda
+- D-XX referenciado em commit message quando aplicavel
+
+## Idioma
+
+- Codigo, commits, PRs: ingles
+- Discussao, docs em `.jdi/`: pt-BR
+- i18n no frontend: nunca string hardcoded em pt-BR no JSX
+
+## Prioridade quando conflita
+
+1. Seguranca
+2. Performance
+3. Boas praticas
+
+## Hooks (opcional)
+
+`.githooks/pre-commit` e `post-commit` shipped. Pra ativar:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+Windows: hooks rodam via Git Bash (vem com Git for Windows). Sem ele, hooks sao silenciosamente ignorados.