Wiedii — Crear un proyecto desde cero (checklist y consideraciones)

🎯 Guía para crear un proyecto/repositorio real desde cero: el paso a paso y qué tener en cuenta. Distinta del onboarding de práctica con el sandbox — para eso ver guia-nuevo-dev y repo-sandbox.

Instrucciones para agentes — `AGENTS.md` como fuente única

Todo repositorio debe tener instrucciones para agentes en la raíz. Para no duplicar la misma configuración en cada herramienta de IA, se centraliza en un único archivo escrito a mano, AGENTS.md (estándar abierto que varias herramientas leen), y cada herramienta autorizada apunta a él en vez de repetir contenido. Esto reemplaza el patrón antiguo de un archivo propio "todo en uno".

Regla 1 — `AGENTS.md` es la única fuente, y solo contexto del proyecto

AGENTS.md contiene solo lo específico del proyecto: qué hace el servicio, su dominio, comandos locales, particularidades y gotchas. No duplicar las convenciones de empresa (commits, branching, testing, seguridad, stacks…): ya las cargan solos los skills del plugin wiedii-dev, y repetirlas en cada repo genera deriva. Si una regla aplica a todos los repos, va en un skill (vía vault + /sync-skills), no en AGENTS.md.

Regla 2 — punteros solo a herramientas autorizadas

Cada herramienta de IA autorizada apunta a AGENTS.md; la whitelist vive en conducta-ia (no se duplica aquí). Nunca crear config de herramientas fuera de la whitelist (.cursorrules, .windsurfrules, .github/copilot-instructions.md, etc.): el .gitignore ya las ignora a propósito y audit-project FALLA si quedan trackeadas. Ignorarlas no las autoriza.

Regla 3 — `CODEMASTER.md` y monolitos "todo en uno" están deprecados

El archivo propio que centralizaba todo (CODEMASTER.md y similares, de antes de skills/plugins) queda deprecado: ningún tool lo lee de forma nativa y duplica lo que hoy dan los skills. Migración: mover lo específico del proyecto a AGENTS.md, dejar los punteros, y borrar CODEMASTER.md.

Regla 4 — los archivos "community-health" de GitHub no son canónicos

Los documentos canónicos de un repo Wiedii son README.md, CONTRIBUTING.md, AGENTS.md y CLAUDE.md (más los punteros de herramientas autorizadas). Los repos son internos/privados (license: UNLICENSED), así que los community-health files de GitHub — pensados para proyectos open-source públicos — no aplican al modelo de Wiedii:

CODE_OF_CONDUCT.md
SECURITY.md
.github/ISSUE_TEMPLATE/ y .github/PULL_REQUEST_TEMPLATE.md
.github/FUNDING.yml
CODEOWNERS (las aprobaciones se cubren con la política operativa + branch protection — ver branch-protection)

No son obligatorios y, si aparecen (arrastrados de una plantilla o autogenerados), se tratan igual que CODEMASTER.md: no canónicos → considerar eliminar. La regla general es "documento no canónico en Wiedii → WARN 'considerar eliminar'" (no un FAIL duro): /audit-project y /review-pr lo marcan como aviso cuando lo encuentran trackeado, para que el equipo decida. La única plantilla de MR que sí usamos es la de GitLab: .gitlab/merge_request_templates/default.md.

Regla 5 — configs muertas del tooling de commits (post-`wietoo`)

Tras migrar a wietoo (validación de commits nativa, sin Node), los archivos de configuración del tooling viejo quedan muertos y deben eliminarse: commitlint.config.{js,cjs,mjs} y su compañero changelog.config.js (más las devDependencies @commitlint/*, cz-git, czg y el script "commit": "czg" de package.json). Ver wietoo-cli. Si alguno sigue trackeado en un repo ya migrado → WARN "considerar eliminar" en /audit-project / /review-pr (mismo trato que CODEMASTER.md): es peso muerto, ningún hook los invoca ya. La config viva y opcional de commits es wietoo.toml (solo si el repo define scopes propios), no un commitlint.config.

package.json / node_modules / bun.lock en repos que NO son JS/TS. Muchos repos (Go, Python, Terraform, solo-docs) arrastraban un package.json cuyo único propósito era sostener czg/commitlint. Post-wietoo eso es peso muerto (tiempo de bun install, superficie de Renovate, tamaño del repo). Regla para /audit-project / /review-pr → WARN "considerar eliminar el package.json/node_modules/bun.lock" solo si todas estas son ciertas (criterios): dependencies vacío o inexistente; scripts sin nada más que un alias de commits ("commit": "czg" y similares); ningún .js/.ts que el repo realmente ejecute; ningún job de CI que use bun install/bun run salvo el tooling de commits. Si alguna es falsa (código JS/TS real, deps de runtime, scripts propios como los bun run scripts/*.ts) → el repo sí es JS/TS: mantener package.json y solo quitar las 4 devDependencies de commits. ⚠️ [[bun|bun]] en mise.toml NO se quita aunque el repo deje de ser JS/TS: el hook renovate-validate de wiedii-configs usa bunx para validar renovate.json en cualquier stack.

Contenido mínimo de `AGENTS.md`

# Project Name — Agent Instructions

## Setup
```bash
mise trust && mise run setup   # fresh clone: trust first — mise won't run tasks from an untrusted config
```

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

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

## Conventions
Company-wide conventions (commits, branching, testing, security, stack policies) come from the `wiedii-dev` skills — do **not** restate them here. Source: [[politicas-core]].

## Code Discovery Protocol
Use codebase-memory-mcp tools first for code exploration: search_graph, trace_path, get_code_snippet, query_graph, get_architecture, search_code. If the project isn't indexed yet, run index_repository first.

Punteros desde las herramientas autorizadas

CLAUDE.md no repite el contenido: importa AGENTS.md y añade solo lo propio de Claude Code (bloque [[engram|Engram]], instrucciones que inyecta [[codebase-memory-mcp]]):

# Project Name — Claude Code

@AGENTS.md

## Memory (Engram)
<!-- bloque Engram obligatorio — ver abajo -->

Actualizado 2026-07-15: Claude Code y Cowork son las únicas herramientas de IA autorizadas (ver [[politicas-core]] regla #2) — ambas usan el puntero CLAUDE.md de arriba. Codex, Antigravity CLI y el IDE Kiro quedaron fuera de la lista blanca; si un repo conserva sus punteros (.kiro/steering/, el context file de Antigravity, etc.), retirarlos.

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).

Servidores LSP (`.lsp.json`)

Cada repo nuevo debe tener un .lsp.json en la raíz, podado según el stack detectado (Go → gopls; TypeScript/Bun → vtsls; Python → basedpyright-langserver; PHP queda fuera — corre en el dev container, ver [[stack-tecnologico]]).

Por qué a nivel de repo y no basta con el del plugin. El plugin wiedii-dev ya declara su propio .lsp.json baseline, y según la documentación de plugins de Claude Code eso debería activarse automáticamente en cualquier repo que instale el plugin — pero se observó empíricamente que no ocurre de forma confiable en repos consumidores (squadlinx-frontend: el vtsls del plugin nunca arrancó, corrió el LSP por defecto de Claude Code en su lugar; causa raíz sin confirmar). Por eso se scaffoldea un .lsp.json a nivel de repo — la ubicación documentada que sí funciona de forma confiable — y es en todo caso necesario para el tuning específico del repo que un baseline genérico de plugin nunca puede saber (ver [[stack-tecnologico]] para el caso de los build tags de Go).

Generación. Se genera con un script bundleado en la skill repo-setup (scripts/scaffold-lsp-json.ts), que detecta el stack (go.mod/package.json/pyproject.toml) y emite el JSON podado. Sin stack reconocido → no se crea el archivo (no es un hallazgo, mismo trato que las secciones por-lenguaje de .editorconfig).

Riesgo aceptado. Claude Code no documenta qué pasa cuando un .lsp.json de repo y uno de plugin declaran la misma extensión (solo se sabe que "el primer servidor registrado gana, los demás no arrancan") — riesgo conocido, no bloqueante, sin resolver aquí.

Checklist de nuevo repositorio

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

Setup inicial

Instalación de herramientas

mise trust && mise run setup (en un clon nuevo mise trust va antes — mise no corre tareas de un config no confiable; 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

wietoo declarado en mise.toml (parte del setup estándar — ver [[wietoo-cli#Cómo se activa wietoo en un proyecto nuevo]])
lefthook.yaml con el remote de [[wiedii-configs]] incluyendo lefthook/base.yaml (activa el hook commit-msg con wietoo)
(Opcional) Crear wietoo.toml con wietoo init si el proyecto necesita scopes propios — ver [[wietoo-cli#Personalizar los scopes del proyecto (wietoo.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|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

README.md

Crear README.md en la raíz: descripción del proyecto, setup (mise run setup), uso y comandos clave
- En inglés y español (regla #9 de [[politicas-core]])
- Referenciar CONTRIBUTING.md desde el README

CONTRIBUTING.md

Crear CONTRIBUTING.md (inglés, canónico) 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
Crear CONTRIBUTING.es.md como archivo independiente (traducción al español) con navegación recíproca (enlace de ida y vuelta en el encabezado). No es un único archivo combinado: son dos archivos, CONTRIBUTING.md (EN) + CONTRIBUTING.es.md (ES). Ver [[contributing]] y [[documentacion-bilingue]] (inglés canónico + español en archivo aparte, con marcador anti-drift ).

Instrucciones para agentes

AGENTS.md creado como fuente única — solo contexto del proyecto (setup, stack, comandos, gotchas); sin duplicar convenciones de empresa (las dan los skills)
Punteros desde herramientas autorizadas: CLAUDE.md (@AGENTS.md + bloque [[engram|Engram]]) — y ninguna config de herramientas no autorizadas (incl. Codex, Antigravity CLI, Kiro — desautorizados 2026-07-15)
Sin CODEMASTER.md ni monolitos "todo en uno" (deprecados → migrar a AGENTS.md y borrar)
CONTRIBUTING.md referenciado desde README.md y CLAUDE.md
mise run setup documentado como comando único de setup

Knowledge graph (codebase-memory-mcp)

codebase-memory-mcp acelera el trabajo de agentes IA: extracción determinista vía tree-sitter (sin LLM, sin costo de tokens) y consulta estructural/semántica sobre un grafo SQLite por repositorio. El servidor MCP es global (una instalación por máquina); los índices viven fuera del repo (~/.cache/codebase-memory-mcp/) — no hay artefacto que gitignorear ni invocación de skill que recordar.

Confirmar que el servidor ya está registrado globalmente (claude mcp list → codebase-memory); si no, instalarlo una vez por máquina (ver [[02-herramientas/codebase-memory-mcp]])
index_repository (mode full) — indexar el repo la primera vez, tras mise run setup
Confirmar que Claude usa el grafo primero (search_graph/trace_path/get_architecture) en vez de grep por cada archivo — ver el "Code Discovery Protocol" en la plantilla de CLAUDE.md de arriba

Reemplaza a [[graphify]] (decisión 2026-07-15) — ver [[02-herramientas/codebase-memory-mcp#Reemplazo de graphify: mecanismo y costo]] para el detalle de la migración.

Herramientas de Claude Code (artefactos locales)

Las herramientas de IA que Claude Code usa generan artefactos locales que nunca deben commitearse — son regenerables y no aportan valor al historial de Git.

Herramienta	Carpeta generada	Qué contiene
[[graphify]]	`graphify-out/`	Knowledge graph del codebase (`.md` + índices)
[[playwright-mcp	Playwright MCP]]	`.playwright-mcp/`
Claude Code settings	`.claude/`	Configuración local del agente, permisos, hooks

Ver [[cross-platform#6. Project-specific]] para el bloque canónico de artefactos de herramientas IA (fuente única). Agregarlo al final del .gitignore:

### Project-specific — AI tool artifacts (regenerables, never commit) ###
.claude/
graphify-out/
.playwright-mcp/
.context7/

Verificar que .claude/, graphify-out/, .playwright-mcp/ y .context7/ están en .gitignore

Ver [[playwright-mcp]] para documentación completa del MCP y casos de uso de testing visual. Ver [[graphify]] para el knowledge graph.

Verificar que todo funciona

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

Instrucciones para agentes — AGENTS.md como fuente única​

Regla 1 — AGENTS.md es la única fuente, y solo contexto del proyecto​

Regla 2 — punteros solo a herramientas autorizadas​

Regla 3 — CODEMASTER.md y monolitos "todo en uno" están deprecados​

Regla 4 — los archivos "community-health" de GitHub no son canónicos​

Regla 5 — configs muertas del tooling de commits (post-wietoo)​

Contenido mínimo de AGENTS.md​

Punteros desde las herramientas autorizadas​

Convención de nombres​

Servidores LSP (.lsp.json)​

Checklist de nuevo repositorio​

Setup inicial​

Instalación de herramientas​

Renovate (actualizaciones automáticas de dependencias)​

Metadatos de package.json​

Herramientas de commit​

Linters (por stack)​

CI/CD (GitLab)​

Configuración del repositorio (GitLab CE)​

README.md​

CONTRIBUTING.md​

Instrucciones para agentes​

Knowledge graph (codebase-memory-mcp)​

Herramientas de Claude Code (artefactos locales)​

Verificar que todo funciona​