Wiedii — Setup de Nuevo Repositorio

CLAUDE.md / AGENTS.md por repositorio

Todo repositorio debe tener un CLAUDE.md y/o AGENTS.md en la raíz.

Contenido mínimo

# Project Name — Agent Instructions

## Setup
```bash
mise run setup   # one-command: installs tools + hooks + deps
```

## Stack
- Runtime: Bun
- Framework: [Astro / Next.js / etc.]
- Language: TypeScript

## Commands
- Lint: `bun eslint .`
- Type check: `bun tsc --noEmit`
- Test: `bun test`
- Build: `bun run build`
- Commit: `bun commit` (czg wizard)

## Branch model
Git Flow (next). Never push directly to `main` or `develop`. Always create an MR.

## Commit format
Conventional Commits. Use `bun commit` for the interactive wizard.

## Policies
Seguir [politicas-core](./politicas-core.md) para todas las tareas de desarrollo.

## Architecture graph
If `graphify-out/GRAPH_REPORT.md` exists, read it before answering architecture or codebase questions — it has 71× fewer tokens than grepping files raw.

Convención de nombres

Antes de crear el repo en GitLab, definir:

• Project name (nombre visible): Title Case con espacios — ej. Wiedii Configs, Renovate Runner
• Project path (URL / slug): kebab-case — ej. wiedii-configs, renovate-runner

GitLab pre-rellena el path en kebab-case al escribir el nombre — el path generado automáticamente suele ser correcto. Solo ajustar el Project name a Title Case con espacios si GitLab lo rellenó de otra forma. Ver gitlab-naming para la política completa y excepciones (Homebrew tap).

---

Checklist de nuevo repositorio

Usar este checklist cada vez que se configura o clona un nuevo repositorio:

Setup inicial

• git flow init --preset=classic --defaults
• Primer commit: git commit -m "chore: initial commit" (antes de cualquier otro commit)
• Crear .gitignore (plantilla del stack + globales de SO para Windows/Linux/macOS)
• Crear .gitattributes con configuración de line endings cross-platform
• Ejecutar git add --renormalize . si el repo ya tenía archivos
• Crear .editorconfig
• Crear .taplo.toml con las opciones de formato estándar de Wiedii (copiar de wildcat/wiedii-configs/taplo/taplo.toml o usar la plantilla de linters)
• Crear mise.toml con todas las herramientas binarias (bun, lefthook, taplo, hadolint, shfmt, shellcheck + específicas del stack)
• Crear .taplo.toml en la raíz con las opciones estándar Wiedii (ver linters)

Instalación de herramientas

• mise run setup (mise install instala herramientas + registra hooks via [hooks].postinstall; bun install corre solo si hay package.json)
• Verificar hooks: lefthook run pre-commit (debe pasar en repo limpio)

Renovate (actualizaciones automáticas de dependencias)

• Crear renovate.json en la raíz del repo con el preset compartido:

  {
    "$schema": "https://docs.renovatebot.com/renovate-schema.json",
    "extends": ["local>wildcat/renovate-runner//.gitlab/renovate.json"]
  }

  Sin este archivo el runner de Renovate ignora el repositorio. Ver renovate para overrides y troubleshooting.

Metadatos de package.json

Todo package.json de Wiedii debe incluir estos campos de identificación:

{
  "name": "nombre-del-proyecto",
  "version": "0.1.0",
  "private": true,
  "description": "Una línea en inglés describiendo el propósito del proyecto",
  "keywords": ["palabra-clave-1", "palabra-clave-2"],
  "repository": {
    "type": "git",
    "url": "https://gitlab.wiedii.co/<namespace>/<repo>.git"
  },
  "license": "UNLICENSED",
  "author": "Wiedii Authors"
}

Campo	Valor	Notas
name	kebab-case	Sin scope para repos internos; @wiedii-registry/nombre solo para paquetes publicados en el registro privado
version	SemVer exacto	0.1.0 para proyectos nuevos, 1.0.0 al salir a producción
private	true siempre	Evita publicación accidental en npm
description	Una línea, en inglés	Aparece en GitLab, herramientas de búsqueda y agentes
keywords	Array de strings	Facilita búsqueda y clasificación
repository.url	URL completa de GitLab	Formato: https://gitlab.wiedii.co/<namespace>/<repo>.git
license	"UNLICENSED" siempre	Propietario — todos los derechos reservados a Wiedii
author	"Wiedii Authors"	Identifica el proyecto como propiedad de Wiedii

"UNLICENSED" es el estándar npm para software propietario: significa que nadie tiene permiso de usar, copiar ni distribuir el código sin autorización explícita de Wiedii. No confundir con "PROPRIETARY" (no reconocido por npm) ni dejar el campo vacío.

• Verificar que package.json incluye todos los campos de metadatos antes del primer commit

Herramientas de commit

• Agregar commitlint.config.js con la config de czg (ESM — el proyecto usa "type": "module")
• Agregar devDependencies: czg, @commitlint/cli, @commitlint/config-conventional, cz-git (versiones pinneadas — ver politicas-core)
• Agregar a scripts de package.json: "commit": "bun --bun git-czg" (sin "prepare" — lefthook se instala via [hooks].postinstall en mise.toml)

Linters (por stack)

• JS/TS: ESLint flat config (eslint.config.mjs) + Prettier + tsconfig.json en strict
• Python: ruff + mypy en mise.toml
• Go: golangci-lint en mise.toml
• CSS: Stylelint

CI/CD (GitLab)

• Crear un request en Squadlinx al equipo de Infra solicitando la configuración del pipeline para el proyecto (ver ci-arquitectura)
• Confirmar que GitLab → Settings → CI/CD → General pipelines apunta al repo de infra
• Verificar que los escáneres de seguridad están activos en el pipeline (ver security-scanners)

Configuración del repositorio (GitLab CE)

• Branch protection en main y develop (requerir MR + 1 aprobación + status checks)
• GitLab → Settings → Merge requests: solo merge commits, squash/rebase desactivados
• renovate.json existe en la raíz con "extends": ["local>wildcat/renovate-runner//.gitlab/renovate.json"] (ver renovate)
• .gitlab/merge_request_templates/default.md creado

CONTRIBUTING.md

• Crear CONTRIBUTING.md en la raíz usando la plantilla tpl-contributing
  • Sustituir PROJECT_NAME y <namespace> con los valores del proyecto
  • Ajustar la sección de hooks según el stack (JS, Python, Go)
  • Verificar que la sección Definition of Done refleja los requisitos reales del proyecto
  • Ver contributing para la política completa

Instrucciones para agentes

• CLAUDE.md / AGENTS.md creado con comandos de setup, info del stack y referencia a políticas
• CONTRIBUTING.md referenciado desde README.md y CLAUDE.md
• mise run setup documentado como comando único de setup

Knowledge graph (graphify)

El knowledge graph acelera el trabajo de agentes IA: 71× menos tokens por consulta en proyectos grandes. Se construye una vez, persiste entre sesiones y no se commitea (derivado regenerable).

• graphify . — construye el grafo del proyecto (ejecutar tras mise run setup, primera vez ~1-5 min según tamaño)
• graphify claude install — inyecta instrucciones en CLAUDE.md y activa el hook PreToolUse en settings.json para que Claude navegue por el grafo en lugar de hacer grep por cada archivo
• Verificar que graphify-out/ está en .gitignore (no commitear los outputs)
• Para repos con cambios frecuentes: graphify hook install — rebuild automático tras cada commit y branch switch

Prerequisito: graphify instalado globalmente con uv tool install graphifyy. Ver 02-herramientas/graphify para detalles y troubleshooting.

# Flujo completo en un repo recién clonado
mise run setup
graphify .                 # construye el grafo (primera vez)
graphify claude install    # configura Claude Code para usar el grafo

Verificar que todo funciona

• Clone limpio → mise run setup → bun commit → push → MR → CI verde
• git config --global merge.ff retorna false
• Todos los hooks de pre-commit corren sin errores