pi-new-project/INSTALL.md

INSTALL — pi-new-project

Instalación del paquete/skill new-project en pi, en este ordenador o en cualquier otro.

Repositorios:

• Distribución (para usarlo): https://git.sargatxet.cloud/sargatxet/pi-new-project-dist. Solo contiene lo que pi necesita: package.json, LICENSE, extensions/, skills/ y un README.md mínimo. Se genera con scripts/publicar-dist.sh.
• Desarrollo (para modificarlo): https://git.sargatxet.cloud/sargatxet/pi-new-project.

1. Requisitos

Componente	Versión mínima	Notas
pi	1.3.0	Hace falta soporte de skills y de paquetes (pi install).
bash	4.0	El script usa arrays y ${var//}.
git	cualquiera	Opcional: --git y autor por defecto.
shellcheck	opcional	Para validar el script (shellcheck new-project.sh).

2. Opción A — instalarlo como paquete de pi desde git (recomendado)

pi clona el repositorio de distribución y lo instala directamente:

pi install git:git.sargatxet.cloud/sargatxet/pi-new-project-dist
# equivalente, con la URL completa:
pi install https://git.sargatxet.cloud/sargatxet/pi-new-project-dist

Para fijar una versión concreta, añade una etiqueta (v0.3.0, …) o un commit: pi install git:git.sargatxet.cloud/sargatxet/pi-new-project-dist@<etiqueta-o-commit>. Añade -l (--local) para declararlo solo en el proyecto actual (.pi/settings.json) en lugar de en ~/.pi/agent/settings.json.

Comprueba con pi list y arranca pi: la skill aparecerá como new-project y estará disponible la orden /modelo-proyecto. Para una prueba puntual sin instalarlo: pi -e git:git.sargatxet.cloud/sargatxet/pi-new-project-dist.

Si ya lo tenías instalado desde el repositorio de desarrollo (git:git.sargatxet.cloud/sargatxet/pi-new-project), pi lo considera otro paquete: quítalo antes con pi remove git:git.sargatxet.cloud/sargatxet/pi-new-project para que la skill no se cargue dos veces.

Desde una copia local del repositorio de desarrollo

Si vas a revisarlo o modificarlo:

git clone https://git.sargatxet.cloud/sargatxet/pi-new-project.git
pi install ./pi-new-project

Una instalación local se carga desde ese directorio sin copiarlo: los cambios (o un git pull) se aplican en la siguiente sesión de pi.

3. Opción B — copiar la skill

Copia el directorio de la skill a una de las rutas que pi descubre:

mkdir -p ~/.agents/skills
cp -r pi-new-project/skills/new-project ~/.agents/skills/

o enlázalo para mantenerlo actualizado con el repositorio:

ln -s "$PWD/pi-new-project/skills/new-project" ~/.agents/skills/new-project

Rutas equivalentes: ~/.pi/agent/skills/ y, por proyecto, .agents/skills/.

En estos ejemplos, pi-new-project/ es una copia del repositorio obtenida con git clone https://git.sargatxet.cloud/sargatxet/pi-new-project-dist.git pi-new-project (o del de desarrollo, .../pi-new-project.git; ambos tienen skills/ y extensions/).

La skill sola no incluye la orden /modelo-proyecto ni la herramienta elegir_modelo_proyecto; cópialas también (o la skill usará el plan B, pi --list-models + --modelo):

mkdir -p ~/.pi/agent/extensions
cp pi-new-project/extensions/modelo-proyecto.ts ~/.pi/agent/extensions/

4. Opción C — exportar a otro ordenador sin acceso al repositorio

Si el ordenador destino tiene acceso a https://git.sargatxet.cloud/sargatxet/pi-new-project-dist, basta con la opción A. Si no, copia el directorio (mejor el de distribución, que solo trae lo necesario); no tiene dependencias.

# en el ordenador origen
tar -czf pi-new-project-0.3.0.tar.gz pi-new-project/

# en el ordenador destino
tar -xzf pi-new-project-0.3.0.tar.gz
pi install ./pi-new-project        # o la opción B

5. Verificación

bash -n pi-new-project/skills/new-project/scripts/new-project.sh
pi-new-project/skills/new-project/scripts/new-project.sh --dry-run --nombre Demo /tmp/demo

# prueba real en un directorio temporal
pi-new-project/skills/new-project/scripts/new-project.sh \
  --nombre Demo --descripcion "Proyecto de prueba" --git /tmp/demo
ls -A /tmp/demo

Deben aparecer AGENTS.md, README.md, CHANGELOG.md, TODO.md, INSTALL.md y .gitignore, sin marcadores {{...}} pendientes.

Modelo por defecto:

pi-new-project/skills/new-project/scripts/new-project.sh \
  --nombre Demo --modelo anthropic/claude-sonnet-4-5 /tmp/demo2
cat /tmp/demo2/.pi/settings.json

En pi, dentro de /tmp/demo2, /modelo-proyecto debe mostrar el selector de modelos y actualizar .pi/settings.json.

6. Actualización

pi update --extensions      # instalado desde git: actualiza el clon gestionado por pi

# instalado desde una copia local o copiado (opción B):
cd pi-new-project && git pull

Si se instaló con una etiqueta o un commit fijo (@<ref>), pi update no lo mueve: reinstala con la nueva referencia.

7. Desinstalación

pi remove git:git.sargatxet.cloud/sargatxet/pi-new-project-dist  # paquete desde git
pi remove git:git.sargatxet.cloud/sargatxet/pi-new-project       # instalaciones antiguas
pi remove ./pi-new-project          # paquete desde una copia local
rm -rf ~/.agents/skills/new-project # si se copió o enlazó
rm -f ~/.pi/agent/extensions/modelo-proyecto.ts

La skill no deja estado propio: no hay caché ni configuración que limpiar.

Publicar una versión (mantenedores)

El repositorio de distribución se genera desde el de desarrollo; no se edita a mano. Con los cambios ya commiteados y la versión subida en package.json y CHANGELOG.md:

scripts/publicar-dist.sh --dry-run   # prepara y muestra el contenido sin subir nada
scripts/publicar-dist.sh             # commit + etiqueta vX.Y.Z en pi-new-project-dist

El script toma el contenido de HEAD (no del directorio de trabajo), se niega a publicar si hay cambios sin commitear en lo que se publica o si la etiqueta ya existe, y necesita permiso de escritura en el repositorio de distribución.

8. Resolución de problemas

Síntoma	Causa probable	Solución
La skill no aparece	Ruta no descubierta	Comprueba la ruta con pi list o colócala en ~/.agents/skills/.
no encuentro las plantillas	Falta templates/	Reinstala el paquete completo, no solo el script.
no puedo deducir el nombre	Destino . o /	Pasa --nombre.
No sobreescribe mis ficheros	Protección por defecto	Usa --force tras revisar --dry-run.
El proyecto no arranca con su modelo	Proyecto no confiado: pi ignora .pi/settings.json	Ejecuta /trust en el proyecto.
/modelo-proyecto no existe	Solo se copió la skill	Instala el paquete o copia extensions/modelo-proyecto.ts.
El selector sale vacío	Ningún proveedor con credenciales	/login o configura la API key del proveedor.