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

# 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