sargatxet/pi-new-project-dist
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

release v0.3.0 (origen c00f020)

Browse Source
This commit is contained in:
sargatxet committed 2026-10-18 18:58:51 +02:00
commit 2df23d5b33
13 files changed
+874
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

skills/new-project/SKILL.md
+74
View File
@@ -0,0 +1,74 @@
---
name: new-project
description: Genera la base documental de un proyecto nuevo (AGENTS.md, README.md, CHANGELOG.md, TODO.md, INSTALL.md y .gitignore) a partir de plantillas, y deja que el usuario elija el modelo por defecto del proyecto. Úsala cuando el usuario pida crear un proyecto, repositorio o directorio nuevo, inicializar su documentación o "montar el esqueleto" de un repo.
license: MIT
---
# new-project
Genera el esqueleto documental de un proyecto. Todas las plantillas están en
`templates/` y el andamiaje lo hace `scripts/new-project.sh`.
## Procedimiento
1. **Recoge los datos** que falten antes de ejecutar nada:
- ruta de destino (obligatoria);
- nombre del proyecto (por defecto, el nombre del directorio destino);
- descripción en una frase (obligatoria: se usa en README y AGENTS);
- autor (opcional; por defecto `git config user.name`);
- si hay que inicializar un repositorio git (`--git`).
No inventes la descripción: si el usuario no la da, pregúntala o propón una
y confírmala.
2. **Ejecuta el script** desde este directorio de skill:
```bash
scripts/new-project.sh --nombre "Mi Proyecto" --descripcion "Qué hace" \
--git /ruta/al/proyecto
```
El script no sobreescribe ficheros existentes salvo con `--force` y muestra
un resumen de lo creado. Usa `--dry-run` para revisar antes.
3. **Modelo por defecto del proyecto** (obligatorio): el usuario elige el modelo
de entre los existentes; tú no lo eliges.
- Llama a la herramienta `elegir_modelo_proyecto` con `ruta` = destino del
proyecto. Muestra al usuario el selector con los modelos disponibles y
guarda su elección en `<ruta>/.pi/settings.json` (`defaultProvider` y
`defaultModel`). pi lo usará en todas las sesiones nuevas del proyecto.
- Si la herramienta no existe o no hay interfaz: ejecuta `pi --list-models`,
enséñale la lista al usuario, pregúntale cuál quiere y guárdalo con
`scripts/new-project.sh --modelo proveedor/id <destino>` (solo crea
`.pi/settings.json` si no existe).
- Si el usuario cancela, déjalo sin fijar e indícale que puede hacerlo más
tarde con `/modelo-proyecto`.
4. **Revisa el resultado**: abre `README.md` y `AGENTS.md` del proyecto generado
y completa lo que quede como `PENDIENTE` (objetivos, stack, comandos de
verificación reales). No dejes marcadores de plantilla ni secciones vacías.
5. **Ajusta** `INSTALL.md` con los requisitos y pasos reales del stack elegido.
6. **Commit inicial** si se creó repo git (incluye `.pi/settings.json`):
```bash
git add -A && git commit -m "docs: base documental inicial"
```
7. Informa al usuario de la ruta creada, los ficheros, el modelo elegido, el
commit y de que puede cambiar el modelo en cualquier momento con
`/modelo-proyecto` dentro del proyecto.
## Reglas
- No ejecutes el script sobre un directorio que ya tiene `AGENTS.md` o `README.md`
sin avisar y confirmar (usaría `--force`).
- Las secciones `## Reglas de modelo` (salvo el modelo por defecto, que gestiona
`/modelo-proyecto`) y `## Reglas de funcionamiento` de
`AGENTS.md` se dejan como `PENDIENTE` a propósito: se acuerdan después, por
proyecto. No las rellenes con suposiciones.
- Idioma de los documentos generados: español.
- Rutas relativas siempre desde este directorio de skill.
## Referencia
- `scripts/new-project.sh --help` — todas las opciones.
- `/modelo-proyecto [proveedor/id]` — cambia el modelo por defecto del proyecto
del directorio actual (sin argumento, muestra el selector).
- `templates/` — plantillas con marcadores `{{PROYECTO}}`, `{{DESCRIPCION}}`,
`{{AUTOR}}`, `{{FECHA}}`, `{{FECHA_ISO}}`.
- `references/plantillas.md` — qué contiene cada documento y cuándo tocarlo.
skills/new-project/references/plantillas.md
+43
View File
@@ -0,0 +1,43 @@
# Plantillas de la base documental
Qué genera `new-project.sh` y cuándo hay que tocar cada documento.
| Documento | Para qué sirve | Cuándo actualizarlo |
| --- | --- | --- |
| `AGENTS.md` | Reglas de trabajo para agentes y colaboradores: flujo, commits, verificación y las futuras reglas de modelo y de funcionamiento. | Al cambiar el flujo, las reglas, los comandos de verificación o al fijar las reglas de modelo. |
| `README.md` | Puerta de entrada: qué es el proyecto, estado, instalación rápida, uso y estructura. | Al cambiar el propósito, el uso o la estructura. |
| `INSTALL.md` | Instalación reproducible: requisitos, dependencias, configuración, verificación, arranque, actualización y desinstalación. | Al añadir dependencias, variables de entorno o cambiar pasos de instalación. |
| `CHANGELOG.md` | Historial *Keep a Changelog*: `Añadido` / `Cambiado` / `Corregido` / `Eliminado`. | En cada cambio, sin excepción. |
| `TODO.md` | Tareas en curso, pendientes y hechas, incluida la deuda técnica. | Al abrir o cerrar tareas. |
| `.gitignore` | Exclusiones básicas: secretos, dependencias descargadas, artefactos de build, logs. | Al detectar ficheros que no deben versionarse. |
| `.pi/settings.json` | Modelo por defecto de pi para el proyecto (`defaultProvider`, `defaultModel`). Lo crea `elegir_modelo_proyecto` o `--modelo`. | Solo con `/modelo-proyecto`, a petición del usuario. |
## Marcadores
El script sustituye estos marcadores en todas las plantillas:
| Marcador | Valor |
| --- | --- |
| `{{PROYECTO}}` | `--nombre` o, si falta, el nombre del directorio destino. |
| `{{DESCRIPCION}}` | `--descripcion` o un `PENDIENTE` explícito. |
| `{{AUTOR}}` | `--autor` o `git config user.name`. |
| `{{FECHA}}` y `{{FECHA_ISO}}` | Fecha de ejecución en formato `AAAA-MM-DD`. |
## Secciones reservadas
`AGENTS.md` incluye a propósito dos secciones con `PENDIENTE`:
- `## Reglas de modelo` — explica dónde está el modelo por defecto y cómo
cambiarlo; el criterio de selección por tarea queda `PENDIENTE`.
- `## Reglas de funcionamiento` — estándares, ramas, revisión y automatización.
No se rellenan al generar el proyecto: se acuerdan después, proyecto a proyecto.
## Modelo por defecto
- Al crear el proyecto, el usuario elige el modelo en el selector de la
herramienta `elegir_modelo_proyecto` (alternativa: `--modelo proveedor/id`).
- Se guarda en `<proyecto>/.pi/settings.json`; pi lo aplica en cada sesión nueva
del proyecto si éste es de confianza.
- Se cambia en cualquier momento con `/modelo-proyecto`, que fusiona el valor con
el resto de ajustes del fichero y activa el modelo en la sesión actual.
skills/new-project/scripts/new-project.sh
Executable
+154
View File
@@ -0,0 +1,154 @@
#!/usr/bin/env bash
# Genera la base documental de un proyecto a partir de las plantillas de la skill.
set -euo pipefail
# bash >= 5.2 sustituye '&' del reemplazo por el patrón encontrado; lo desactivamos
# para que los valores con '&' o '\' se inserten literales.
shopt -u patsub_replacement 2>/dev/null || true
SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
TEMPLATES_DIR="$SCRIPT_DIR/../templates"
PROYECTO=""
DESCRIPCION=""
AUTOR=""
DESTINO=""
MODELO=""
INIT_GIT=0
FORCE=0
DRY_RUN=0
FECHA_ISO="$(date +%Y-%m-%d)"
uso() {
cat <<'EOF'
Uso: new-project.sh [opciones] <directorio-destino>
Genera AGENTS.md, README.md, CHANGELOG.md, TODO.md, INSTALL.md y .gitignore.
Opciones:
-n, --nombre NOMBRE Nombre del proyecto (por defecto: nombre del directorio).
-d, --descripcion TEXTO Descripción en una frase (por defecto: PENDIENTE).
-a, --autor NOMBRE Autor (por defecto: git config user.name).
-m, --modelo PROV/ID Modelo por defecto del proyecto; se guarda en
.pi/settings.json (lista: pi --list-models).
En pi es preferible la herramienta
elegir_modelo_proyecto o la orden /modelo-proyecto.
-g, --git Inicializa un repositorio git en el destino.
-f, --force Sobreescribe ficheros que ya existan.
--dry-run Muestra lo que haría sin escribir nada.
-h, --help Muestra esta ayuda.
EOF
}
die() { printf 'error: %s\n' "$*" >&2; exit 1; }
aviso() { printf 'aviso: %s\n' "$*" >&2; }
requiere() { [[ $# -ge 2 && -n "$2" && "$2" != -* ]] || die "$1 necesita un valor"; }
while [[ $# -gt 0 ]]; do
case "$1" in
-n | --nombre) requiere "$@"; PROYECTO="$2"; shift 2 ;;
-d | --descripcion) requiere "$@"; DESCRIPCION="$2"; shift 2 ;;
-a | --autor) requiere "$@"; AUTOR="$2"; shift 2 ;;
-m | --modelo) requiere "$@"; MODELO="$2"; shift 2 ;;
-g | --git) INIT_GIT=1; shift ;;
-f | --force) FORCE=1; shift ;;
--dry-run) DRY_RUN=1; shift ;;
-h | --help) uso; exit 0 ;;
--) shift; break ;;
-*) die "opción desconocida: $1 (usa --help)" ;;
*) break ;;
esac
done
[[ $# -ge 1 ]] || { uso >&2; exit 2; }
DESTINO="$1"
[[ $# -eq 1 ]] || die "solo se admite un directorio destino"
[[ -d "$TEMPLATES_DIR" ]] || die "no encuentro las plantillas en $TEMPLATES_DIR"
if [[ -z "$PROYECTO" ]]; then
PROYECTO="$(basename -- "${DESTINO%/}")"
fi
[[ -n "$PROYECTO" ]] || die "no puedo deducir el nombre del proyecto; usa --nombre"
if [[ -z "$DESCRIPCION" ]]; then
DESCRIPCION="PENDIENTE: describir $PROYECTO en una frase."
aviso "sin --descripcion; se deja un PENDIENTE en README.md y AGENTS.md"
fi
if [[ -z "$AUTOR" ]]; then
AUTOR="$(git config user.name 2>/dev/null || true)"
[[ -n "$AUTOR" ]] || AUTOR="PENDIENTE"
fi
if [[ -n "$MODELO" ]]; then
[[ "$MODELO" =~ ^[^/[:space:]\"]+/[^[:space:]\"]+$ ]] \
|| die "--modelo debe tener la forma proveedor/id (p. ej. anthropic/claude-sonnet-4-5)"
fi
FICHEROS=(AGENTS.md README.md CHANGELOG.md TODO.md INSTALL.md .gitignore)
render() {
local plantilla="$1" salida="$2" contenido
contenido="$(<"$plantilla")"
contenido="${contenido//'{{PROYECTO}}'/$PROYECTO}"
contenido="${contenido//'{{DESCRIPCION}}'/$DESCRIPCION}"
contenido="${contenido//'{{AUTOR}}'/$AUTOR}"
contenido="${contenido//'{{FECHA}}'/$FECHA_ISO}"
contenido="${contenido//'{{FECHA_ISO}}'/$FECHA_ISO}"
printf '%s\n' "$contenido" > "$salida"
}
destino_abs="$(cd -- "$DESTINO" 2>/dev/null && pwd || true)"
[[ -n "$destino_abs" ]] || destino_abs="$DESTINO"
creados=()
omitidos=()
for fichero in "${FICHEROS[@]}"; do
ruta="$DESTINO/$fichero"
if [[ -e "$ruta" && $FORCE -eq 0 ]]; then
omitidos+=("$fichero")
aviso "$fichero ya existe; se omite (usa --force para sobreescribir)"
continue
fi
if [[ $DRY_RUN -eq 1 ]]; then
printf 'dry-run: escribiría %s\n' "$ruta"
else
mkdir -p -- "$DESTINO"
render "$TEMPLATES_DIR/$fichero.tmpl" "$ruta"
fi
creados+=("$fichero")
done
if [[ -n "$MODELO" ]]; then
settings="$DESTINO/.pi/settings.json"
if [[ -e "$settings" && $FORCE -eq 0 ]]; then
omitidos+=(".pi/settings.json")
aviso ".pi/settings.json ya existe; se omite (usa /modelo-proyecto en pi para cambiar el modelo sin perder otros ajustes)"
elif [[ $DRY_RUN -eq 1 ]]; then
printf 'dry-run: escribiría %s (modelo %s)\n' "$settings" "$MODELO"
creados+=(".pi/settings.json")
else
mkdir -p -- "$DESTINO/.pi"
printf '{\n "defaultProvider": "%s",\n "defaultModel": "%s"\n}\n' \
"${MODELO%%/*}" "${MODELO#*/}" > "$settings"
creados+=(".pi/settings.json")
fi
fi
if [[ $INIT_GIT -eq 1 && $DRY_RUN -eq 0 ]]; then
if [[ -d "$DESTINO/.git" ]]; then
aviso "$DESTINO ya es un repositorio git"
else
git -C "$DESTINO" init -q
printf 'git: repositorio inicializado en %s\n' "$destino_abs"
fi
fi
printf '\nproyecto: %s\n' "$PROYECTO"
printf 'destino: %s\n' "$destino_abs"
printf 'modelo: %s\n' "${MODELO:-sin fijar (elígelo con /modelo-proyecto)}"
printf 'creados: %s\n' "${creados[*]:-ninguno}"
[[ ${#omitidos[@]} -eq 0 ]] || printf 'omitidos: %s\n' "${omitidos[*]}"
[[ $DRY_RUN -eq 1 ]] || printf 'siguiente: revisa README.md, INSTALL.md y las secciones PENDIENTE de AGENTS.md\n'
skills/new-project/templates/.gitignore.tmpl
+27
View File
@@ -0,0 +1,27 @@
# Secretos y configuración local
.env
.env.*
!.env.example
# Dependencias descargadas
node_modules/
vendor/
venv/
.venv/
__pycache__/
*.py[cod]
# Artefactos de build
dist/
build/
target/
out/
*.log
logs/
# Sistema operativo y editores
.DS_Store
Thumbs.db
.idea/
.vscode/
*.swp
skills/new-project/templates/AGENTS.md.tmpl
+88
View File
@@ -0,0 +1,88 @@
# AGENTS.md
Guía para agentes y colaboradores que trabajen en **{{PROYECTO}}**.
Léela antes de tocar cualquier fichero y respétala en cada cambio.
## Propósito del proyecto
{{DESCRIPCION}}
## Contenido del repositorio
| Ruta | Descripción |
| --- | --- |
| `AGENTS.md` | Este documento: reglas de trabajo. |
| `README.md` | Visión general y puesta en marcha. |
| `INSTALL.md` | Instalación detallada y dependencias. |
| `CHANGELOG.md` | Historial de cambios (*Keep a Changelog*). |
| `TODO.md` | Tareas pendientes y deuda técnica. |
| `.pi/settings.json` | Ajustes de pi del proyecto: modelo por defecto. |
| _(completar)_ | Añade aquí el código y los recursos del proyecto. |
## Reglas de modelo
### Modelo por defecto
El modelo por defecto del proyecto se guarda en `.pi/settings.json`
(`defaultProvider` y `defaultModel`) y pi lo aplica al iniciar cada sesión nueva
en este directorio (requiere haber confiado en el proyecto: `/trust`).
- Para cambiarlo: `/modelo-proyecto` (muestra los modelos disponibles) o
`/modelo-proyecto proveedor/id`.
- No edites a mano ni cambies ese modelo sin que lo pida el usuario.
- `.pi/settings.json` se versiona; un cambio de modelo se commitea como
cualquier otro cambio.
### Otras reglas
PENDIENTE: definir el contexto y el criterio de selección de modelos por tarea
(coste, VRAM, ventana, velocidad). Se acuerda tarea por tarea; hasta entonces,
no fijar valores aquí.
## Reglas de funcionamiento
PENDIENTE: definir flujo de trabajo, estándares de código, comandos obligatorios,
política de ramas y de revisión, y cualquier automatización propia del proyecto.
## Reglas obligatorias
1. **Todo cambio se documenta y se commitea.** Cada vez que se modifique
cualquier fichero del repositorio:
- Añadir una entrada en `CHANGELOG.md` (fecha, versión y tipo:
`Añadido` / `Cambiado` / `Corregido` / `Eliminado`).
- Actualizar `TODO.md` si el cambio abre, cierra o modifica tareas.
- Actualizar `README.md`, `INSTALL.md` o los documentos que correspondan si
cambia el comportamiento, la instalación o el uso.
- Crear **un commit de git** con mensaje claro en imperativo.
2. **Nunca dejar documentación desfasada.** Si el código y los documentos no
coinciden, el cambio está incompleto.
3. **No commitear** secretos, binarios, artefactos de build, logs ni dependencias
descargadas (`.gitignore` cubre lo básico; amplíalo según el stack).
4. **Idioma: español** para documentación, mensajes de commit y comentarios.
## Verificación antes de commitear
PENDIENTE: sustituir por los comandos reales del stack (formato, tipos, tests,
lint). Ningún commit sin verificación en verde.
```bash
# ejemplo
# make check
```
## Flujo de trabajo
1. Editar los ficheros necesarios.
2. Ejecutar las verificaciones anteriores.
3. Actualizar `CHANGELOG.md`, `TODO.md` y la documentación afectada.
4. `git add -A && git commit -m "tipo(alcance): descripción breve"`.
5. Informar del cambio y del hash del commit.
## Convención de mensajes de commit
`tipo(alcance): resumen` — tipos: `feat`, `fix`, `docs`, `chore`, `refactor`,
`test`, `build`, `perf`.
Ejemplos:
- `docs: documentar instalación y puesta en marcha`
- `feat(api): añadir búsqueda paginada`
skills/new-project/templates/CHANGELOG.md.tmpl
+24
View File
@@ -0,0 +1,24 @@
# Changelog
Todos los cambios relevantes de este proyecto se documentan en este fichero.
El formato sigue [*Keep a Changelog*](https://keepachangelog.com/es-ES/1.1.0/)
y el proyecto usa [Versionado Semántico](https://semver.org/lang/es/).
## [No publicado]
### Añadido
- Base documental inicial del proyecto ({{FECHA}}): `AGENTS.md`, `README.md`,
`INSTALL.md`, `CHANGELOG.md`, `TODO.md` y `.gitignore`.
<!--
Plantilla de entrada:
## [0.1.0] - AAAA-MM-DD
### Añadido
### Cambiado
### Corregido
### Eliminado
-->
skills/new-project/templates/INSTALL.md.tmpl
+79
View File
@@ -0,0 +1,79 @@
# INSTALL — {{PROYECTO}}
Instalación, configuración y puesta en marcha de **{{PROYECTO}}**.
{{DESCRIPCION}}
## 1. Requisitos
PENDIENTE: completar con el stack real.
| Componente | Versión mínima | Notas |
| --- | --- | --- |
| Sistema operativo | PENDIENTE | |
| Lenguaje / runtime | PENDIENTE | |
| Gestor de paquetes | PENDIENTE | |
| Otros | PENDIENTE | |
Comprueba lo instalado:
```bash
# PENDIENTE: comandos de comprobación (p. ej. python3 --version)
```
## 2. Obtener el código
```bash
git clone <url-del-repositorio>
cd {{PROYECTO}}
```
## 3. Dependencias
```bash
# PENDIENTE: instalación de dependencias
```
## 4. Configuración
PENDIENTE: variables de entorno, ficheros de configuración y secretos. Indica
qué ficheros hay que crear y de dónde copiarlos (`.env.example`, etc.).
```bash
# PENDIENTE: cp .env.example .env y editar
```
| Variable | Obligatoria | Descripción |
| --- | --- | --- |
| PENDIENTE | | |
## 5. Verificación de la instalación
```bash
# PENDIENTE: comando de humo que demuestre que funciona
```
## 6. Arranque
```bash
# PENDIENTE: comando de arranque en desarrollo y en producción
```
## 7. Actualización
```bash
git pull
# PENDIENTE: reinstalar dependencias y aplicar migraciones si las hay
```
## 8. Desinstalación
PENDIENTE: qué borrar y qué dejar.
## 9. Resolución de problemas
| Síntoma | Causa probable | Solución |
| --- | --- | --- |
| PENDIENTE | | |
Documento creado el {{FECHA}} por {{AUTOR}}.
skills/new-project/templates/README.md.tmpl
+58
View File
@@ -0,0 +1,58 @@
# {{PROYECTO}}
{{DESCRIPCION}}
## Estado
- Versión: `0.1.0`
- Fecha de creación: {{FECHA}}
- Autor: {{AUTOR}}
- Estado: en desarrollo
## Requisitos
PENDIENTE: lenguajes, versiones y dependencias del sistema. Ver `INSTALL.md`.
## Instalación rápida
```bash
# PENDIENTE: sustituir por los comandos reales
git clone <url-del-repositorio>
cd {{PROYECTO}}
```
Instrucciones completas en [`INSTALL.md`](INSTALL.md).
## Uso
PENDIENTE: ejemplo mínimo de uso o de arranque.
```bash
# PENDIENTE
```
## Estructura
```text
{{PROYECTO}}/
├── AGENTS.md # reglas de trabajo para agentes y colaboradores
├── README.md # este documento
├── INSTALL.md # instalación y dependencias
├── CHANGELOG.md # historial de cambios
├── TODO.md # tareas pendientes
└── .pi/
└── settings.json # modelo por defecto de pi (cambiar con /modelo-proyecto)
```
## Documentación
| Documento | Contenido |
| --- | --- |
| [`AGENTS.md`](AGENTS.md) | Reglas, flujo de trabajo y convenciones. |
| [`INSTALL.md`](INSTALL.md) | Instalación, configuración y desinstalación. |
| [`CHANGELOG.md`](CHANGELOG.md) | Qué cambió y cuándo. |
| [`TODO.md`](TODO.md) | Qué falta y qué está en curso. |
## Licencia
PENDIENTE: indicar licencia del proyecto.
skills/new-project/templates/TODO.md.tmpl
+22
View File
@@ -0,0 +1,22 @@
# TODO — {{PROYECTO}}
Tareas pendientes y deuda técnica. Al cerrar una tarea, muévela a *Hecho* y
anota el cambio en `CHANGELOG.md`.
## En curso
- [ ] _(nada en curso)_
## Pendiente
- [ ] Definir las **reglas de modelo** del proyecto en `AGENTS.md` (criterio por
tarea; el modelo por defecto se cambia con `/modelo-proyecto`).
- [ ] Definir las **reglas de funcionamiento** del proyecto en `AGENTS.md`.
- [ ] Completar los `PENDIENTE` de `README.md` e `INSTALL.md`.
- [ ] Fijar los comandos de verificación reales en `AGENTS.md`.
- [ ] Elegir licencia.
## Hecho
- [x] {{FECHA}} — base documental inicial (`AGENTS.md`, `README.md`, `INSTALL.md`,
`CHANGELOG.md`, `TODO.md`, `.gitignore`).