jdi-cli 0.1.0

package/core/templates/skill.md

@@ -0,0 +1,66 @@
+---
+name: {NAME}
+description: {ONE_LINE_DESCRIPTION}
+type: skill
+applies_to:
+  {WHEN_TO_APPLY}
+loaded_by:
+  {AGENTS_THAT_LOAD}
+runtime_overrides:
+  antigravity:
+    triggers:
+      {DISCOVERY_TRIGGERS}
+---
+
+# Skill: {NAME}
+
+{DETAILED_DESCRIPTION}
+
+## When to apply
+
+{USAGE_CONDITIONS}
+
+## Procedure
+
+### Step 1: {NAME}
+{DESCRIPTION}
+
+### Step 2: {NAME}
+{DESCRIPTION}
+
+### Step 3: {NAME}
+{DESCRIPTION}
+
+## Expected inputs
+
+{WHAT_THE_PARENT_AGENT_PROVIDES}
+
+## Outputs
+
+{WHAT_GOES_BACK_TO_PARENT_AGENT}
+
+Does NOT produce own files. Modifies parent agent's work.
+
+## References
+
+- `references/{X}.md` — {DESCRIPTION}
+- `references/{Y}.md` — {DESCRIPTION}
+
+## Anti-patterns
+
+- {THING_NOT_TO_DO}
+- {THING_NOT_TO_DO}
+
+## Examples
+
+### Example 1: {SCENARIO}
+
+Input:
+```
+{EXAMPLE_INPUT}
+```
+
+Output (in parent agent context):
+```
+{EXAMPLE_OUTPUT}
+```

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "jdi-cli",
+  "version": "0.1.0",
+  "description": "JDI (Just Do It) — lean workflow toolkit for Claude Code, GitHub Copilot, Antigravity, and OpenCode. 10 commands (7 loop + ralph + adopt + meta), 6 core agents + N per-project specialists with file-glob routing. Optional Playwright MCP + Caveman plugin install.",
+  "bin": {
+    "jdi": "bin/jdi.js"
+  },
+  "files": [
+    "bin/jdi.js",
+    "bin/lib",
+    "bin/jdi-build.sh",
+    "bin/jdi-build.ps1",
+    "bin/jdi-install.sh",
+    "bin/jdi-install.ps1",
+    "bin/jdi-update.sh",
+    "bin/jdi-update.ps1",
+    "bin/jdi-uninstall.sh",
+    "bin/jdi-uninstall.ps1",
+    "bin/jdi-doctor.sh",
+    "bin/jdi-doctor.ps1",
+    "bin/jdi-install-playwright.sh",
+    "bin/jdi-install-playwright.ps1",
+    "bin/jdi-install-caveman.sh",
+    "bin/jdi-install-caveman.ps1",
+    "bin/git-hooks",
+    "core",
+    "runtimes",
+    "templates-jdi-folder",
+    "README.md",
+    "ARCHITECTURE.md",
+    "AGENTS.md",
+    "COMMANDS.md",
+    "EXTENSION.md",
+    "CREATE.md",
+    "CREATE-EXAMPLE.md",
+    "PORTABILITY.md",
+    "MEMORY.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/slipalison/jdi-cli.git"
+  },
+  "homepage": "https://github.com/slipalison/jdi-cli#readme",
+  "bugs": {
+    "url": "https://github.com/slipalison/jdi-cli/issues"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "agent",
+    "workflow",
+    "spec-driven-development",
+    "jdi",
+    "opencode",
+    "copilot",
+    "antigravity"
+  ],
+  "author": "JDI contributors",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "node bin/jdi.js build",
+    "doctor": "node bin/jdi.js doctor",
+    "test:local": "npm pack && echo 'Package generated. Test with: npx ./jdi-cli-1.4.0.tgz install <runtime>'"
+  }
+}

package/runtimes/antigravity/agents.md

@@ -0,0 +1,74 @@
+# agents.md — JDI workflow (Antigravity)
+
+Este projeto usa **JDI (Just Do It)** como workflow de desenvolvimento. JDI eh um workflow enxuto.
+
+## Loop canonico
+
+```
+/jdi-new "<descricao>"   -> research + PROJECT.md + ROADMAP.md
+/jdi-bootstrap           -> cria specialists per-project
+/jdi-discuss <N>         -> captura decisoes locked
+/jdi-plan <N>            -> decompoe em tasks com waves
+/jdi-do <N>              -> executa via doer specialist
+/jdi-verify <N>          -> gates via reviewer specialist
+/jdi-ship <N>            -> finaliza phase
+```
+
+`/jdi-create [desc]` cria agents/skills no `core/` (so dentro do repo JDI).
+
+## Skills disponiveis
+
+Em `.gemini/antigravity/skills/`. Discovery via triggers.
+
+| Skill | Funcao |
+|---|---|
+| jdi-researcher | Research pre-roadmap (PROJECT.md + ROADMAP.md) |
+| jdi-bootstrap | Cria specialists per-project (doer + reviewer) |
+| jdi-asker | Loop de perguntas pra CONTEXT.md |
+| jdi-planner | Gera PLAN.md com waves |
+| jdi-architect | Meta-skill: cria agents/skills/specialists |
+
+## Specialists per-project
+
+Apos `/jdi-bootstrap`, criados em `.jdi/agents/jdi-doer-{slug}.md` e `.jdi/agents/jdi-reviewer-{slug}.md`.
+
+Pra Antigravity reconhecer, copie pra `.gemini/antigravity/skills/` (ou rode `jdi-install.sh antigravity` apos bootstrap).
+
+## Triggers
+
+Digite `/jdi-discuss N` ou peca em natural — ex: "discutir phase 2", "iniciar phase 1", "executar phase 3", "verificar entrega da phase". Skills tem triggers prefixados `jdi-` pra evitar falsos positivos.
+
+## Memoria — files em `.jdi/`
+
+```
+.jdi/
+  PROJECT.md, ROADMAP.md, DECISIONS.md, STATE.md
+  specialists.md, reviewers.md, registry.md
+  agents/         <- per-project specialists
+  phases/{NN-slug}/{CONTEXT,PLAN,SUMMARY,REVIEW}.md
+```
+
+## Limitacoes Antigravity
+
+- **Sem restricao formal de tools**: cada SKILL.md documenta privilegios via prosa. Confianca via review.
+- **Sem hooks runtime**: pre-commit/post-commit ficam em `.githooks/`. Ativar com `git config core.hooksPath .githooks`.
+- **Discovery por trigger**: prefixo `jdi-` evita falsos positivos.
+- **Subagent spawn limitado**: paralelizacao por default sequential. Use prompts explicitos pra paralelo.
+
+## Convencoes
+
+- Conventional Commits — scope = phase slug
+- Atomic commits — 1 task = 1 commit
+- 80% cobertura minima
+- Code design locked no `/jdi-new`
+
+## Idioma
+
+- Codigo/commits/PRs: ingles
+- Discussao/docs em `.jdi/`: pt-BR
+
+## Prioridade quando conflita
+
+1. Seguranca
+2. Performance
+3. Boas praticas

package/runtimes/antigravity/skills/clean-code/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: clean-code
+description: Clean Code. Human-readable code, optimized for reading (read 10x more than written). Names reveal intent, small functions, no redundant comments, explicit error handling, no magic numbers. Applies in any language.
+triggers:
+  - "Clean Code"
+  - "clean code"
+  - "code smells"
+  - "code readability"
+---
+
+# Skill: Clean Code
+
+> Code is read 10x more than written. Optimize for reading.
+
+Not about pretty style. About **making reader understand in 1 pass**, without mentally simulating execution.
+
+## Rules
+
+### 1. Names reveal intent
+
+- **Variable**: what it **is**, not how it's stored (`elapsedSeconds` > `t` > `time`)
+- **Function**: what it **does**, verb + object (`calculateTax(order)`, not `tax(order)`)
+- **Boolean**: yes/no question (`isActive`, `hasPermission`, `canSubmit`)
+- **Class/module**: noun (`OrderRepository`, `EmailValidator`)
+- **Interface**: role/capability (`Repository`, `Cacheable`) — no `I`/`Abstract` prefix if language doesn't require
+
+### Anti-names
+
+| Wrong | Right |
+|---|---|
+| `data`, `info`, `value`, `temp`, `result` | something descriptive of the context |
+| `processData()` | `parseUserPayload()`, `applyDiscount()`, etc |
+| `Manager`, `Helper`, `Util` | name of the real responsibility |
+| `flag`, `status` | `isComplete`, `paymentStatus` |
+| `obj`, `item`, `thing` | actual type |
+| Abbreviations: `usr`, `ctx`, `mgr`, `cfg` | `user`, `context` (exception: well-established domain convention) |
+| Variables with `_2`, `_new`, `_old` | refactor until 1 remains |
+
+### 2. Small functions
+
+- **Size**: ideally < 20 lines. If over 50, almost certainly doing too much.
+- **1 abstraction level**: inside function, all operations at same level. Mixing "open connection" + "calculate tax" = no.
+- **3-4 params max**: more than that signals either missing object or too much responsibility.
+- **1 logical exit**: early return is OK; multiple returns mid-complex-logic is bad.
+
+### 3. Functions do **one** thing
+
+If you describe function as "does X **and** Y", split into two. Function name must be precise.
+
+Exception: orchestrators (controllers, command handlers) coordinate — OK to describe as "validates, saves, notifies" if each step is a call to another function.
+
+### 4. Comments
+
+**Default: DON'T write**.
+
+Well-named code doesn't need to explain **what** it does. If you feel like writing a comment, first attempt: rename function/variable.
+
+### Comments OK when:
+
+- **Why** non-obvious: workaround for specific bug, surprising design decision, external constraint
+- **Critical invariant**: "this array MUST be sorted for binary search to work"
+- **TODO/FIXME marker** with ticket link: `// TODO(#1234): handle UTF-16 surrogate`
+- **Pitfall warning**: "// don't call this in a loop, O(n^2)"
+- **Public API doc**: contract for caller (params, returns, exceptions)
+
+### Comments bad when:
+
+- Explain **what** (code already says)
+- Repeat the function name in English
+- Comment goes stale relative to code
+- "// removed on XX/YY" left in the tree
+- "// hack" without explanation
+- "// not sure why this works" — investigate, don't guess
+
+### 5. Explicit error handling
+
+- **Never silence exception**: `try { ... } catch {}` is **latent bug**
+- **Explicit handling**: structured log + rethrow OR return Result/Either
+- **Errors are part of the contract**: document what can fail
+- **Boundary**: handle error at the boundary (controller, top-level handler), not at every internal call
+- **Validation**: at the entry (boundary), not scattered
+
+### 6. No magic numbers/strings
+
+- Number or string with meaning becomes a **named constant**
+- `if (status === 3)` becomes `if (status === OrderStatus.Shipped)`
+- `setTimeout(fn, 86400000)` becomes `setTimeout(fn, MS_PER_DAY)`
+- Exception: 0, 1, -1, universally clear cases
+
+### 7. Command-Query Separation (CQS)
+
+- **Query**: returns info, does **not** mutate state
+- **Command**: mutates state, does **not** return (or returns void/minimal ack)
+
+`function getUser(id)` that **also** updates last_access violates CQS — caller doesn't expect side-effect. Split.
+
+### 8. Boy Scout Rule
+
+> Leave the campground cleaner than you found it.
+
+Touched a file? Small cleanness improvement is OK in the same commit:
+- Rename obscure variable
+- Split giant function you already had to read
+- Remove stale comment
+- Delete dead code
+
+No heavy unrelated refactor — atomic commit still rules.
+
+### 9. Formatting
+
+- **Auto-format**: linter/formatter on the project (prettier, dotnet format, ruff format, gofmt) — no human decisions
+- **Member order**: consistent convention (publics before privates, or group by feature)
+- **Blank line**: separates logical blocks. Function all glued together is hard to scan.
+- **Consistent indentation**: respect project convention
+
+### 10. Symmetry and consistency
+
+- Functions at same "level" have similar signature
+- `getUserById, getUserByEmail` — consistent param order
+- Exceptions "as is" vs "throws" vs Result — pick **one** style in the project
+- `null` vs `undefined` vs `Option` — pick **one**
+- Consistent naming convention (camelCase, PascalCase, snake_case) following the language
+
+## Classic code smells
+
+| Smell | Symptom |
+|---|---|
+| **Long function** | > 50 lines |
+| **Long parameter list** | > 4 params |
+| **God class** | 1 class does everything |
+| **Feature envy** | method uses more data from **another** class than its own |
+| **Data clump** | same 3-4 params bundled in multiple places -> object |
+| **Primitive obsession** | everything is string/int, no value objects |
+| **Scattered switch statements** | OCP violated |
+| **Shotgun surgery** | simple change touches N files |
+| **Divergent change** | 1 class changes for 5 different reasons (SRP) |
+| **Dead code** | function/parameter/var never used |
+| **Speculative generality** | flexibility without caller (YAGNI) |
+| **Comments compensating bad code** | refactor code, delete comment |
+| **Magic numbers** | 86400, 1024 with no name |
+| **Silenced exceptions** | `catch {}`, `catch (Exception _) { }` |
+| **Long if/else chains** | use polymorphism/strategy |
+| **Inconsistent naming** | `getUser` here, `fetchAccount` there, `loadOrder` over there |
+| **Boolean parameter** | `fn(true)` at caller — nobody knows what `true` means |
+
+## Procedure
+
+### Doer
+
+After writing:
+1. **Name review**: does each variable/function have a name that stands without a comment? Rename if not.
+2. **Size**: any function > 30 lines? Split.
+3. **Magic**: any number/string without obvious meaning? Constant.
+4. **Redundant comments**: any comment that just repeats the code? Delete.
+5. **Error handling**: any silent `catch {}`? Log or rethrow.
+
+### Reviewer (gate 5)
+
+```bash
+# Long functions
+awk '/^(function|def|public |private |protected |async )/ { start=NR; name=$0 }
+     /^}$|^\s{0,2}}\s*$/ { if (NR-start > 50) print FILENAME":"start": function with "(NR-start)" lines: "name }' src/**/*.{ts,cs,py,go,java}
+
+# Magic numbers (typical suspects)
+grep -RnE '\b(86400|3600|1024|65535|1000000)\b' src/
+
+# Silent catch
+grep -RnE 'catch\s*(\([^)]*\))?\s*\{\s*\}' src/
+grep -RnE 'except.*:\s*pass\s*$' src/
+grep -RnE 'catch.*:.*ignore' src/
+
+# TODO without ticket
+grep -RnE 'TODO(?!.*#\d+)|FIXME(?!.*#\d+)' src/
+
+# Suspect boolean params
+grep -RnE 'function \w+\([^)]*: bool|: boolean' src/
+
+# Generic name
+grep -RnE '\b(data|info|value|temp|tmp|result|obj|item|thing)\b\s*[:=]' src/ | head -20
+
+# Dead code (linter catches — confirm)
+
+# Obvious comments
+grep -RnE '^\s*//\s*(get|set|return|increment|decrement|loop|iterate)\b' src/
+```
+
+Relevant match -> WARN or BLOCK depending on severity.
+
+## Inputs
+
+- Diff/content of the file
+- Project convention (linter config, naming convention from PROJECT.md)
+
+## Outputs
+
+Does NOT produce a file. Modifies judgement.
+
+## Examples
+
+### Example 1: bad names
+
+Wrong:
+```python
+def calc(d, t):
+    r = d * t * 0.18
+    return r
+```
+
+Right:
+```python
+VAT_RATE = 0.18
+
+def calculate_vat(amount: Decimal, qty: int) -> Decimal:
+    return amount * qty * VAT_RATE
+```
+
+### Example 2: giant function
+
+Wrong: 1 function of 120 lines validating, saving, sending email, logging.
+
+Right: 4 functions of 20 lines each + 1 orchestrator of 15 lines that coordinates.
+
+### Example 3: silenced exception
+
+Wrong:
+```typescript
+try {
+  await sendNotification(user)
+} catch {}
+```
+
+Latent bug — notification failure disappears.
+
+Right:
+```typescript
+try {
+  await sendNotification(user)
+} catch (err) {
+  logger.error("notification failed", { userId: user.id, err })
+  // intentional: notification is best-effort, doesn't block flow
+}
+```
+
+Comment here justifies the "why" of the no-rethrow.
+
+### Example 4: boolean param
+
+Wrong: `createUser("alice", "alice@x.com", true, false)`
+
+Right: `createUser({ name: "alice", email: "alice@x.com", admin: true, sendWelcome: false })`
+
+Caller becomes self-documented.

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

@@ -0,0 +1,141 @@
+---
+name: dry
+description: DRY (Don't Repeat Yourself). 1 source of truth per piece of knowledge. Detects real duplication (same decision in 2+ places) and separates from apparent duplication (same code, different reasons). Applies in any language.
+triggers:
+  - "DRY"
+  - "code duplication"
+  - "Don't Repeat Yourself"
+  - "duplicate refactor"
+---
+
+# Skill: DRY
+
+> Every piece of knowledge has **one** authoritative, unambiguous representation in the system.
+
+DRY is not about copying code. It's about **duplicated knowledge** — business rule, formula, format, decision, present in 2+ places and that change **together** when the requirement changes.
+
+## Rules
+
+### 1. Knowledge duplication != code coincidence
+
+**Knowledge duplication (violates DRY):**
+- Tax calculation in 2 places
+- CPF validation in 3 services
+- Date format schema scattered across the app
+- Same timeout constant in 4 files
+
+When the rule changes, you change in N places — miss one, system becomes inconsistent.
+
+**Code coincidence (does NOT violate DRY):**
+- 2 functions with 5 identical lines but different domains
+- Framework boilerplate repeated (every controller has `[Authorize]`)
+- Similar iteration loop in 2 unrelated contexts
+
+Forcing abstraction here couples things that shouldn't be coupled.
+
+### 2. Rule of 3
+
+- 1 occurrence: leave it
+- 2 occurrences: pay attention, but don't abstract yet
+- 3 occurrences: abstract (probably real knowledge duplication)
+
+Skipping this rule produces **premature abstraction** — worse than duplication because callers are already coupled to the wrong interface.
+
+### 3. Types of DRY
+
+**Code DRY:** reusable functions/classes for repeated logic
+**Data DRY:** 1 source schema (generates DTO + validator + DB + docs)
+**Process DRY:** 1 build script that serves dev + CI + prod
+**Documentation DRY:** docs generated from code, not written in parallel
+
+### 4. Single Source of Truth (SSoT)
+
+For each piece of knowledge, identify:
+- **Where the truth lives** (DB schema, env config, business rule)
+- **Who derives from it** (DTOs, types, docs, UI)
+- **Derivation tool** (codegen, schema migration, type inference)
+
+Never: manually edit both the source and the derived.
+
+### 5. When NOT to apply DRY
+
+- **Premature abstraction**: 2 similar callers but with diverging future evolutions -> leave duplicated
+- **Cross-boundary**: duplicating across microservices > coupling via shared lib
+- **Test setup**: readable redundant tests > shared magical helpers
+- **Wrong abstraction**: better duplicate than extract wrong (Sandi Metz: "duplication is far cheaper than the wrong abstraction")
+
+## Anti-patterns
+
+| Anti-pattern | Why it violates |
+|---|---|
+| Copy-paste without extraction after 3rd occurrence | Duplicated knowledge, each caller silently diverges |
+| Utility helper with 15 unrelated functions | "DRY" became ball of mud — bundles unrelated things |
+| Abstraction after 2nd duplication with extension hooks "just in case" | Premature abstraction + YAGNI violated together |
+| Same constant hardcoded in 4 files | Single source of truth absent — extract to config |
+| Validation logic duplicated client + server | Code OK, but should share schema (Zod, Pydantic, JSON Schema) |
+| Comment explaining what code does | Doc duplicates code, will go out of sync |
+
+## Procedure
+
+### Doer (before writing)
+
+1. Is there an identical rule/calculation/constant elsewhere in the codebase? If so, refer/import. Don't duplicate.
+2. Going to create the 2nd occurrence? OK, but mentally mark it.
+3. Going to create the 3rd? Stop. Refactor first into abstraction, then use.
+
+### Reviewer (gate 5)
+
+Per-language specific greps (examples):
+
+```bash
+# Duplicated magic constants
+grep -RnE '\b86400\b|\b3600\b|\b1024\b' src/
+
+# Same string in 3+ places
+sort src/ | uniq -c | sort -rn | head -20  # coarse heuristic
+
+# Duplicated email/CPF/etc validation
+grep -RnE 'regex.*@|EmailRegex|CpfValidator|cpf_pattern' src/
+
+# Hardcoded URLs/endpoints
+grep -RnE 'https?://[a-z0-9.-]+\.[a-z]{2,}' src/ --include='*.ts' --include='*.cs' --include='*.py'
+```
+
+3+ matches of the same pattern in different files -> WARN.
+
+## Inputs
+
+- Diff or content of the modified file
+- Context: project stack for adapted greps
+
+## Outputs
+
+Does NOT produce a file. Modifies judgement:
+- Doer chooses to reuse/extract
+- Reviewer marks WARN with pointer to refactor
+
+## Examples
+
+### Example 1: 3 services calculating tax
+
+Wrong:
+```
+service A: total * 0.18
+service B: amount * 0.18
+service C: value * 0.18
+```
+
+Right: extract `TaxCalculator.applyVat(amount)` or `const VAT_RATE = 0.18` in shared config.
+
+Reviewer marks WARN: "tax 0.18 hardcoded in 3 services. Extract to `config/tax.{ts,cs,py}`."
+
+### Example 2: Code coincidence (does NOT violate DRY)
+
+```
+function findUser(id) { return db.query(...) }
+function findOrder(id) { return db.query(...) }
+```
+
+Same structure, different domains. **Don't** extract `findEntity(id, table)` — will force abstraction that will diverge (user has soft-delete, order has cache, etc).
+
+Reviewer ignores — code coincidence is OK.