repo_Claude/README.md

# Claude Code — Skills, Agents & Tools

Sistema de automatizacion para desarrollo de software usando Claude Code. Incluye skills (comandos invocables), agentes especializados, y herramientas Go para orquestar trabajo paralelo.

## Estructura del repo

```
repo_Claude/
├── bin/                          # Binarios compilados
│   └── parallel-executor         # Orquestador de ejecucion paralela
├── utils/
│   └── parallel-executor/        # Codigo fuente Go del orquestador
│       ├── core/                 # Funciones puras (parser, planner)
│       └── shell/                # I/O (worktrees, executor, logger)
├── dev/
│   └── issues/                   # Sistema local de issues
└── install.sh                    # Instalador
```

---

## Skills

Skills son comandos invocables desde Claude Code con `/nombre`. Viven en `~/.claude/skills/`.

### Configuracion y setup

| Skill | Descripcion | Uso |
|-------|-------------|-----|
| `/primer` | Genera CLAUDE.md personalizado analizando el repo | `/primer` |
| `/init-jupyter` | Inicializa proyecto Jupyter + MCP (bash script idempotente) | `/init-jupyter [ruta]` |
| `/init-go-module` | Crea modulo Go funcional con bindings Python (CGO + ctypes) | `/init-go-module nombre` |
| `/init-frontend` | Crea proyecto React/Vite o Wails desktop | `/init-frontend nombre [--wails]` |
| `/nochanges` | Modo read-only para explorar sin modificar | `/nochanges` |
| `/create-skill` | Crea un skill nuevo | `/create-skill nombre` |
| `/create-agent` | Crea un agente especializado | `/create-agent` |

### Git

| Skill | Descripcion | Uso |
|-------|-------------|-----|
| `/git-branch` | Crea ramas `issue/*` o `quick/*` desde master | `/git-branch issue 0013 slug` |
| `/git-push` | Commits atomicos por tipo, merge --no-ff, push, limpieza | `/git-push` |
| `/git-recovery` | Recupera repo de estados inconsistentes | `/git-recovery [--aggressive]` |

### Workspace (Gitea + SQLite)

| Skill | Descripcion | Uso |
|-------|-------------|-----|
| `/create-repo` | Crea workspace en Gitea con rollback | `/create-repo` |
| `/import-repo` | Importa repo existente a Gitea (mirror) | `/import-repo` |
| `/sync-repos` | Sincroniza workspaces locales con Gitea | `/sync-repos [--dry-run]` |
| `/list-repos` | Lista workspaces desde SQLite | `/list-repos [--filter x]` |
| `/cleanup-worktrees` | Limpia worktrees post-merge | `/cleanup-worktrees [--all]` |

### Issues

| Skill | Descripcion | Uso |
|-------|-------------|-----|
| `/create-issue` | Crea issue con template, sub-issues si es grande | `/create-issue` |
| `/fix-issue` | E2E: lee issue, branch, implementa, tests, merge | `/fix-issue 0013` |
| `/auto-fix` | Igual que fix-issue pero sin confirmacion | `/auto-fix 0013` |
| `/auto-create` | Igual que create-issue sin confirmacion | `/auto-create` |
| `/quick-issue` | Issue minimal desde texto (para TUI) | `/quick-issue --text "..."` |
| `/issues-status` | Dashboard con filtros por workspace/estado/tag | `/issues-status` |

### Ejecucion paralela

| Skill | Descripcion | Uso |
|-------|-------------|-----|
| `/sort-issues` | Analiza dependencias, topological sort | `/sort-issues` |
| `/parallel-issues` | Genera plan de ejecucion paralela | `/parallel-issues` |
| `/execute-parallel` | Crea worktrees y ejecuta issues en paralelo | `/execute-parallel [--dry-run]` |

---

## Agentes

Agentes especializados que Claude Code puede invocar automaticamente. Cada uno tiene su propio modelo, herramientas y MCP servers. Viven en `~/.claude/agents/`.

### Librerias de desarrollo

| Agente | Modelo | Descripcion | Ubicacion |
|--------|--------|-------------|-----------|
| **backend-lib** | sonnet | Gestiona DevFactory — libreria Go funcional con Result[T], Option[T], HTTP, DB, finance | `~/.local_agentes/backend` |
| **frontend-lib** | sonnet | Gestiona Frontend_Library — 50+ componentes React/TS, temas OKLCH, shadcn/ui, charts, DSP | `~/.local_agentes/frontend` |

### Build y deploy

| Agente | Modelo | Descripcion |
|--------|--------|-------------|
| **build-wails** | sonnet | Apps desktop Wails v2 (Go + React). Cross-compile Linux/Windows/macOS. Integra ambas librerias |
| **docker** | sonnet | Dockerfiles multi-stage, docker-compose, push a registries, deploy via SSH |

### Datos e infraestructura

| Agente | Modelo | Descripcion |
|--------|--------|-------------|
| **db-reader** | sonnet | Bases de datos SQLite y DuckDB. Consultas, imports CSV/Parquet/JSON, analisis OLAP |
| **gitea** | sonnet | Gestion de Gitea: repos, issues, PRs, branches, archivos. MCP integrado |

### Automatizacion

| Agente | Modelo | Descripcion |
|--------|--------|-------------|
| **navegator** | sonnet | Automatizacion web con Go + Chrome DevTools Protocol (chromedp). Perfiles de navegacion |

---

## Parallel Executor

Binario Go en `utils/parallel-executor/` que orquesta la ejecucion paralela de issues usando git worktrees.

### Arquitectura

Sigue el patron **pure core / impure shell** de DevFactory:

```
utils/parallel-executor/
├── core/                 # Funciones puras, 0 side effects
│   ├── parser.go         # Parsea PARALLEL_EXECUTION_ORDER.md
│   ├── planner.go        # Topological sort (Kahn), deteccion de ciclos
│   ├── parser_test.go
│   └── planner_test.go
├── shell/                # Operaciones I/O con Result[T]
│   ├── worktree.go       # CRUD de git worktrees
│   ├── executor.go       # Invoca `claude -p` en cada worktree
│   └── logger.go         # Logs por sesion e issue
├── main.go               # CLI
├── go.mod + go.work      # DevFactory como dependencia
└── Makefile
```

### Uso

```bash
# Compilar
cd utils/parallel-executor && make build

# Analizar issues y generar plan
./bin/parallel-executor --sort

# Ver que haria sin ejecutar
./bin/parallel-executor --dry-run

# Ejecutar todo
./bin/parallel-executor

# Solo un grupo
./bin/parallel-executor --group 1

# Sin paralelismo
./bin/parallel-executor --sequential

# Solo limpiar worktrees
./bin/parallel-executor --cleanup
```

### Flujo de ejecucion

1. Lee (o genera) `PARALLEL_EXECUTION_ORDER.md`
2. Agrupa issues por dependencias (topological sort)
3. Por cada grupo, crea worktrees en `worktrees/issue-NNNN/`
4. Ejecuta `claude -p` en paralelo dentro de cada worktree
5. Mergea branches exitosas a master (`--no-ff`)
6. Limpia worktrees automaticamente
7. Escribe logs en `logs/`

---

## Stack tecnologico

### Backend (Go)

- **Go 1.22+** con generics
- **DevFactory** (`~/.local_agentes/backend`): Result[T], Option[T], MapSlice, FilterSlice, Reduce, Pipe, Curry
- Patron **pure core / impure shell**: funciones puras en `core/`, I/O wrapeado en Result[T] en `shell/`
- **DuckDB** para analytics, **SQLite** para metadata
- **Bubble Tea** para TUIs

### Frontend (React)

- **React 19** + TypeScript strict + **Vite** + **Tailwind CSS 4** (OKLCH)
- **Frontend_Library** (`~/.local_agentes/frontend`): shadcn/ui, Phosphor Icons, 50+ componentes
- **pnpm** exclusivamente, link via `pnpm add @anthropic/frontend-lib@link:...`
- Vite dedupe obligatorio para `react`, `react-dom`
- **Storybook 10** para documentacion de componentes

### Desktop

- **Wails v2** (Go backend + React frontend)
- Cross-compile: Linux AMD64/ARM64, Windows AMD64
- DevFactory via `go.work`, Frontend_Library via `pnpm link`

### Infraestructura

- **Gitea** self-hosted para repositorios
- **Docker** multi-stage builds
- **Trunk-based development**: ramas `issue/*` y `quick/*`, merge rapido a master

---

## Convenciones

- **Inmutabilidad**: no mutar datos, crear copias nuevas
- **Result[T]** para errores, no `(T, error)` — permite encadenamiento monadico
- **Commits atomicos**: agrupados por tipo (feat, fix, refactor, docs, chore, test)
- **Issues**: formato 3-4 digitos, estado en markdown, sub-issues con sufijo letra
- **Skills con bash scripts**: idempotentes, detectan estado existente, colores en output