Jules

Jules Skill — Autonomous Coding Agent & EPIC Orchestrator

⚡ SWAL Agent System — Updated 2026-07-20 Repos: ONLY iberi22/*

⚡ Quick Reference

# 🎯 Assign task to Jules (CLI)
jules new --repo iberi22/<REPO> "task description"
jules new --repo iberi22/<REPO> --parallel 3 "task"

# 🎯 Assign via GitHub issue (label = trigger)
gh issue create --repo iberi22/<REPO> --title "..." --body "$(cat body.md)" --label jules

# 📋 List sessions
jules remote list --session
jules remote list --repo

# 📥 Pull completed session
jules remote pull --session <ID>
jules teleport <SESSION_ID>

# 🔍 Check PRs from Jules
gh pr list --repo iberi22/xavier --state all --json number,title,body --jq '.[] | select(.body | test("created automatically by Jules")) | "#\(.number) \(.title)"'

1. Authentication

# Check if logged in
jules remote list --repo

# Login (one-time, opens browser)
jules login

2. How Jules Works

Jules monitorea issues de GitHub con el label jules. Flujo típico:

1. Creas issue + label jules
2. Jules responde en 1-5 min: "Jules is on it" + enlace a Google Tasks
3. Jules trabaja (segundos a minutos)
4. Jules abre PRs como Draft con body "Fixes #N" + enlace Google Tasks

⚠️ Importante:

• @jules-ai mention = NO trigger
• Issue assignment = NO trigger
• jules label = ONLY trigger
• Jules usa iberi22 como author de PRs (mismo que humano)
• Para distinguir PRs de Jules: branch termina en 20 dígitos (Google Task ID) o body contiene "created automatically by Jules"

3. CLI Session Management

# List ALL sessions (PRIMARY monitor command)
jules remote list --session

# List connected repos
jules remote list --repo

# Create new session
jules new --repo iberi22/<REPO> "implement feature X"
jules new --repo iberi22/<REPO> --parallel 3 "write unit tests"

# Pull session result (view what Jules did)
jules remote pull --session <ID>

# Pull AND apply patch to local repo
jules remote pull --session <ID> --apply

# Teleport (clone repo + checkout + apply patch)
jules teleport <SESSION_ID>

Session Status Values

4. Asignar Tareas via GitHub Issues

Template de Issue (OBLIGATORIO — Jules NO pregunta, solo ejecuta)

Cada issue DEBE incluir esta estructura. Si falta "Web Research Required", Jules produce soluciones subóptimas:

> Wave context: [Ola/Número de sprint]

## Web Research Required (Jules MUST search the web FIRST)

**MANDATORY**: Before implementing any code, search for current approaches (2025-2026).
1. **[Current Best Practice]** - search: "specific query 2025 2026"
2. **[Architecture/Design]** - search: "design pattern query"

## Exact Technical Context
- **File**: `path/to/file.rs` (N lines)
- **Function**: `function_name` at line ~XXX

> CRITICAL: gotchas, excluded crates, feature flags

## Problem
[1-3 sentences]

## Acceptance Criteria
- [ ] Specific change with exact code
- [ ] `cargo check --workspace` passes
- [ ] Tests pass

## Files to Modify
| File | Change |
|------|--------|
| `src/path.rs` | What changes |

**NEVER create `.patch` / `.py` / `part1.rs` loose files in repo root.**

## Verification
```bash
git pull origin main --rebase && cargo check --workspace

Dependencies and Merge Order

• Depends on: [issue N]
• Can run in parallel with: [issue P]

### Trigger / Re-trigger

```bash
# Trigger
gh issue edit <N> --repo iberi22/<REPO> --add-label jules

# Re-trigger (si Jules falló o no respondió)
gh issue edit <N> --remove-label jules
sleep 5
gh issue edit <N> --add-label jules

5. Anti-Conflict Protocol

THE #1 RULE: If two issues touch the same file, they CANNOT run in parallel.

File Ownership Map

Antes de crear issues, mapear qué archivos tocará cada issue:

# Declaración de conflictos (usar antes de taggear)
$fileOwnership = @{
  "src/auth2/mod.rs"                   = @(774, 775, 776)  # CONFLICT — sequential only
  "tests/integration/auth_test.rs"     = @(777)             # SAFE
  "panel-ui/vite.config.ts"            = @(773)             # SAFE
}

Wave Tagging Rules

Rebase Before PR (mandatory for Jules)

Agregar a la Verification section de cada issue:

git pull origin main --rebase
cargo check --workspace

One-file-per-PR principle

• ✅ 1-2 files: low risk
• ⚠️ 3-5 files: medium — verify ownership map
• ❌ 6+ files: split into smaller issues

6. EPIC & Sub-issues Organization

Crear EPIC

gh issue create --title "Ola N — Feature Completion to 100%" \
  --body "## EPIC: Ola N\n\nSprint description." \
  --label epic

Crear Sub-issues (vinculados al EPIC)

gh issue create --parent EPIC_NUMBER \
  --title "[Ola N.X] Short description" \
  --body "$(cat body.md)" \
  --label jules

Monitoring EPIC Progress

# Ver todos los sub-issues abiertos
for num in 773 774 775 776 777 778 779 780 781 782; do
  gh issue view "$num" --json number,state,title --jq '"#\(.number) [\(.state)] \(.title)"'
done

7. Batch Merge Workflow (for Jules PRs)

Detectar PRs de Jules

# PRs con body que dice "created automatically by Jules"
gh pr list --repo iberi22/xavier --state all --json number,title,body,headRefName,isDraft \
  --jq '.[] | select(.body | test("created automatically by Jules|Jules for task")) | "#\(.number) [\(.state)] \(.title) draft=\(.isDraft)"'

# PRs con branch que termina en 20 dígitos (Google Task ID)
gh pr list --repo iberi22/xavier --state all --json number,headRefName,title \
  --jq '.[] | select(.headRefName | test("\\d{20}$")) | "#\(.number) \(.title) [\(.headRefName)]"'

Merge Order

1. PRs de FUNDACIÓN (crates compartidos, types, schemas)
2. PRs de INFRAESTRUCTURA CORE (PluginHost, DB, FTS5)
3. PRs de PLUGINS/PARSERS (binarios standalone)
4. PRs de HERRAMIENTAS (MCP, tools, CLI)
5. PRs de ESTABILIZACIÓN (tests, fixes, lint)

Mergear PRs de Jules (workflow completo)

# 1. Verificar estado
gh pr view <N> --repo iberi22/xavier --json state,isDraft,mergeable,additions,deletions

# 2. Marcar como ready (Jules siempre crea Draft)
gh pr ready <N> --repo iberi22/xavier

# 3. Mergear con squash
gh pr merge <N> --repo iberi22/xavier --squash --delete-branch

# 4. Cerrar issue asociado
gh issue close <N_issue> --repo iberi22/xavier --comment "✅ Delivered in main via PR #N"

Resolver Conflictos entre PRs Paralelos

Cuando Jules trabaja en N issues simultáneamente:

• Cada PR se crea desde main en su momento
• Al mergear PR #1, los PRs #2..#N quedan con conflictos
• NO re-triggerear a Jules para resolver conflictos — resolverlos manualmente es más rápido

# 1. Clonar la branch del PR
git fetch origin pull/<N>/head:pr-<N>
git checkout pr-<N>

# 2. Hacer merge trial
git merge origin/main --no-commit --no-ff

# 3. Ver conflictos
git diff --name-only --diff-filter=U

# 4. Resolver o abortar
git merge --abort  # si es muy complejo

Detectar PRs Obsoletos (Superseded)

Si dos PRs tocan la misma feature:

# Identificar cuál es el más completo / reciente
gh pr diff <old> --name-only
gh pr diff <new> --name-only

# Si el nuevo cubre el mismo scope + mejoras:
gh pr comment <old> --body "❌ Superseded por #<new> (merged). Cerrando."
gh pr close <old>

8. Autonomous Orchestrator Pattern (Auto-Merge + Wave Advance)

Para sprints continuos, combinar Jules con un script orquestador que corre cada 20 min:

Jules ──abre PRs Draft──► GitHub ──poll cada 20 min──► Orchestrator (no_agent script)
                                                            │
                                            ┌───────────────┼───────────────┐
                                            ▼               ▼               ▼
                                       Convert Ready    Merge Squash   Close Issue
                                            │               │               │
                                            └───────────────┴───────────────┘
                                                          │
                                                    Wave complete?
                                                          │
                                                    ┌─────┴─────┐
                                                    ▼           ▼
                                                  Sí           No
                                                    │           │
                                          Tag next wave     (wait 20 min)
                                          + assign Jules
                                                    │
                                                    ▼
                                              ──► Jules starts next wave

El orquestador:

1. Detecta current wave (lock file o GitHub states)
2. Tags issues para Jules si no tienen label (agrega jules, ola5, wave-N + assign)
3. Mergea Draft PRs: gh pr ready N → gh pr merge N --squash --delete-branch
4. Cierra issues con comentario
5. Avanza wave: si todos los issues están cerrados, taggea siguiente wave
6. Reporta solo en cambios (watchdog silent pattern)

# Crear el cronjob
hermes cronjob create \
  --script ~/.hermes/scripts/ola5-epic-orchestrator.py \
  --no-agent \
  --deliver origin \
  --schedule "every 20 min"

Pitfalls del orquestador

• Labels must exist before adding. Create jules, ola5, wave-N first.
• gh returns UPPERCASE states. Always .upper() in comparisons.
• Shell escaping. Use gh(args=[...]) for args with spaces/quotes.
• Comment bodies. Use temp file + --body-file for multi-line markdown.
• Dynamic PR→issue matching. PR body dice "Fixes #N" — check body, not just title.

9. Quality Scorecard & Post-Merge Checklist

Evaluar PR de Jules

Post-Merge Checklist

# 1. Compila?
cargo check --workspace

# 2. Tests pasan?
cargo test --workspace 2>&1 | tail -10

# 3. Clippy limpio?
cargo clippy --all-targets -- -D warnings 2>&1 | tail -10

# 4. Funcionalidad eliminada? Jules puede borrar métodos usados
grep -rn "fn find_by_lang\|fn clear_by_file\|fn contains_call" code-graph/src/

Errores Comunes de Jules

10. Verificación de Merge (Protocolo Obligatorio)

NUNCA asumir que un PR de Jules está mergeado. Siempre verificar:

gh pr view <N> --repo iberi22/xavier --json state,mergeable,isDraft

# state = "MERGED" → mergeado ✅
# state = "OPEN" + isDraft = true → Draft, no mergear
# state = "OPEN" + isDraft = false → ready, check mergeable

# Verificar commits en main
git log --oneline main | head -5

Lección aprendida (Julio 2026): Confundir "commits en la branch" con "PR mergeado a main" engaña al usuario. Siempre verificar con gh pr view antes de reportar.

11. Troubleshooting

Session stuck ("Awaiting User F")

1. Revisar: jules remote pull --session <ID>
2. Extraer trabajo parcial del output
3. Eliminar sesión desde app.jules.ai
4. Relanzar con mejor contexto

Jules no responde al issue

gh issue edit <N> --remove-label jules
sleep 5
gh issue edit <N> --add-label jules

Jules falló con error

• Revisar comentarios del issue
• Ajustar descripción (más específica)
• Forzar re-trigger o crear issue nuevo

PR con 0 adiciones

Jules puede abrir PRs con 0 additions/0 deletions (empty commit):

gh pr view <N> --json additions,deletions
# Si ambos son 0 → no-op. Cerrar y re-trigger con issue más específico.

12. Jules + Gestalt Swarm — Combined Workflow

Jules = async coding (refactors, features, PRs).
Gestalt Swarm = fast parallel CLI (scans, analysis, bulk ops).

User → Swarm (fast analysis) → Jules (implement fixes) → PR → Merge

When to Use Each

13. Proyectos SWAL Activos

⚠️ Jules ONLY works in iberi22/* repos.

Last updated: 2026-07-20 Jules = Google's autonomous AI coding agent Gestalt Swarm = SWAL's parallel execution bridge Anti-Conflict Protocol v1 + Wave Orchestration v4