feat: paquete pi-new-project con la skill new-project
This commit is contained in:
sargatxet committed
commit
b35bc7a607
14 files changed
+716
No files matched your search
@@ -0,0 +1,27 @@
|
|||||||
|
# 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]
|
||||||
|
|
||||||
|
### Pendiente
|
||||||
|
|
||||||
|
- Fijar las reglas de modelo y de funcionamiento que la skill escribirá en el
|
||||||
|
`AGENTS.md` de cada proyecto generado (hoy quedan como `PENDIENTE`).
|
||||||
|
|
||||||
|
## [0.1.0] - 2026-10-18
|
||||||
|
|
||||||
|
### Añadido
|
||||||
|
|
||||||
|
- Paquete pi `pi-new-project` con la skill `new-project`.
|
||||||
|
- `scripts/new-project.sh`: andamiaje en bash con `--nombre`, `--descripcion`,
|
||||||
|
`--autor`, `--git`, `--force` y `--dry-run`.
|
||||||
|
- Plantillas de `AGENTS.md`, `README.md`, `CHANGELOG.md`, `TODO.md`, `INSTALL.md`
|
||||||
|
y `.gitignore`, con marcadores `{{PROYECTO}}`, `{{DESCRIPCION}}`, `{{AUTOR}}`
|
||||||
|
y `{{FECHA}}`.
|
||||||
|
- `AGENTS.md` generado con las secciones reservadas `## Reglas de modelo` y
|
||||||
|
`## Reglas de funcionamiento`.
|
||||||
|
- Documentación de instalación, exportación a otro ordenador y verificación.
|
||||||
+102
@@ -0,0 +1,102 @@
|
|||||||
|
# INSTALL — pi-new-project
|
||||||
|
|
||||||
|
Instalación del paquete/skill `new-project` en pi, en este ordenador o en
|
||||||
|
cualquier otro.
|
||||||
|
|
||||||
|
## 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 (recomendado)
|
||||||
|
|
||||||
|
Desde el directorio que contiene `pi-new-project/`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pi install ./pi-new-project
|
||||||
|
```
|
||||||
|
|
||||||
|
O desde git/npm cuando se publique:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pi install git:github.com/<usuario>/pi-new-project@v0.1.0
|
||||||
|
```
|
||||||
|
|
||||||
|
Comprueba con `pi list` y arranca pi: la skill aparecerá como `new-project`.
|
||||||
|
Para una prueba puntual sin instalarlo: `pi -e ./pi-new-project`.
|
||||||
|
|
||||||
|
## 3. Opción B — copiar la skill
|
||||||
|
|
||||||
|
Copia el directorio de la skill a una de las rutas que pi descubre:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p ~/.agents/skills
|
||||||
|
cp -r pi-new-project/skills/new-project ~/.agents/skills/
|
||||||
|
```
|
||||||
|
|
||||||
|
o enlázalo para mantenerlo actualizado con el repositorio:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ln -s "$PWD/pi-new-project/skills/new-project" ~/.agents/skills/new-project
|
||||||
|
```
|
||||||
|
|
||||||
|
Rutas equivalentes: `~/.pi/agent/skills/` y, por proyecto, `.agents/skills/`.
|
||||||
|
|
||||||
|
## 4. Opción C — exportar a otro ordenador
|
||||||
|
|
||||||
|
No hay más que copiar el directorio; no tiene dependencias.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# en el ordenador origen
|
||||||
|
tar -czf pi-new-project-0.1.0.tar.gz pi-new-project/
|
||||||
|
|
||||||
|
# en el ordenador destino
|
||||||
|
tar -xzf pi-new-project-0.1.0.tar.gz
|
||||||
|
pi install ./pi-new-project # o la opción B
|
||||||
|
```
|
||||||
|
|
||||||
|
Alternativa sin `tar`: publicar el repositorio y usar `pi install <url-de-git>`.
|
||||||
|
|
||||||
|
## 5. Verificación
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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.
|
||||||
|
|
||||||
|
## 6. Actualización
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git pull
|
||||||
|
pi update --extensions # si se instaló como paquete
|
||||||
|
```
|
||||||
|
|
||||||
|
## 7. Desinstalación
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pi remove ./pi-new-project # si se instaló como paquete
|
||||||
|
rm -rf ~/.agents/skills/new-project # si se copió o enlazó
|
||||||
|
```
|
||||||
|
|
||||||
|
La skill no deja estado propio: no hay caché ni configuración que limpiar.
|
||||||
|
|
||||||
|
## 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`. |
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
# pi-new-project
|
||||||
|
|
||||||
|
Paquete de [pi](https://pi.dev) que genera la base documental de un proyecto
|
||||||
|
nuevo: `AGENTS.md`, `README.md`, `CHANGELOG.md`, `TODO.md`, `INSTALL.md` y
|
||||||
|
`.gitignore`, listos para versionar y con las secciones de reglas reservadas
|
||||||
|
para acordarlas después.
|
||||||
|
|
||||||
|
## Contenido
|
||||||
|
|
||||||
|
```text
|
||||||
|
pi-new-project/
|
||||||
|
├── package.json # manifiesto de paquete pi
|
||||||
|
├── README.md # este documento
|
||||||
|
├── INSTALL.md # instalación en otro ordenador
|
||||||
|
├── CHANGELOG.md
|
||||||
|
├── TODO.md
|
||||||
|
└── skills/
|
||||||
|
└── new-project/
|
||||||
|
├── SKILL.md # instrucciones para el agente
|
||||||
|
├── scripts/new-project.sh # andamiaje (bash, sin dependencias)
|
||||||
|
├── templates/ # plantillas con {{MARCADORES}}
|
||||||
|
└── references/plantillas.md # qué es cada documento
|
||||||
|
```
|
||||||
|
|
||||||
|
## Uso
|
||||||
|
|
||||||
|
En una sesión de pi, pide crear un proyecto nuevo; la skill `new-project` se
|
||||||
|
activa sola. También puedes forzarla:
|
||||||
|
|
||||||
|
```text
|
||||||
|
/skill:new-project crea el proyecto "gestor-gastos" en ~/src/gestor-gastos
|
||||||
|
```
|
||||||
|
|
||||||
|
O ejecutar el script directamente:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
skills/new-project/scripts/new-project.sh --help
|
||||||
|
skills/new-project/scripts/new-project.sh \
|
||||||
|
--nombre "Gestor de gastos" \
|
||||||
|
--descripcion "API para registrar y consultar gastos personales" \
|
||||||
|
--git ~/src/gestor-gastos
|
||||||
|
```
|
||||||
|
|
||||||
|
El script nunca sobreescribe ficheros existentes salvo con `--force`, y admite
|
||||||
|
`--dry-run` para revisar antes.
|
||||||
|
|
||||||
|
## Instalación
|
||||||
|
|
||||||
|
Ver [`INSTALL.md`](INSTALL.md). Resumen: copia (o enlaza) el directorio en
|
||||||
|
`~/.pi/agent/skills/` o instálalo como paquete con `pi install ./pi-new-project`.
|
||||||
|
|
||||||
|
## Requisitos
|
||||||
|
|
||||||
|
- `bash` 4+ y `git` (opcional, solo para `--git` y el autor por defecto).
|
||||||
|
- No usa Python, Node ni dependencias externas: es `bash` con biblioteca estándar.
|
||||||
@@ -0,0 +1,24 @@
|
|||||||
|
# TODO — pi-new-project
|
||||||
|
|
||||||
|
## En curso
|
||||||
|
|
||||||
|
- [ ] _(nada en curso)_
|
||||||
|
|
||||||
|
## Pendiente
|
||||||
|
|
||||||
|
- [ ] Definir las **reglas de modelo** (modelo, contexto, criterio de selección)
|
||||||
|
y volcarlas en `templates/AGENTS.md.tmpl`.
|
||||||
|
- [ ] Definir las **reglas de funcionamiento** comunes y volcarlas en
|
||||||
|
`templates/AGENTS.md.tmpl`.
|
||||||
|
- [ ] Decidir si las reglas se configuran por parámetros del script
|
||||||
|
(p. ej. `--modelo`, `--contexto`, `--stack`) o ficheros de perfil.
|
||||||
|
- [ ] Detectar y completar el stack automáticamente (¿`--stack python|node|rust`?)
|
||||||
|
para prellenar `INSTALL.md` y los comandos de verificación.
|
||||||
|
- [ ] Valorar soporte multiidioma (`--lang es|en`) en plantillas y script.
|
||||||
|
- [ ] Publicar el paquete (git o npm) para instalarlo con `pi install <url>`.
|
||||||
|
- [ ] Prueba automática del script (golden test de los ficheros generados).
|
||||||
|
|
||||||
|
## Hecho
|
||||||
|
|
||||||
|
- [x] 2026-10-18 — estructura del paquete, skill, script y plantillas.
|
||||||
|
- [x] 2026-10-18 — `INSTALL.md` con exportación a otro ordenador.
|
||||||
@@ -0,0 +1,14 @@
|
|||||||
|
{
|
||||||
|
"name": "pi-new-project",
|
||||||
|
"version": "0.1.0",
|
||||||
|
"private": true,
|
||||||
|
"description": "Paquete de pi con la skill new-project: genera la base documental de un proyecto (AGENTS.md, README, CHANGELOG, TODO, INSTALL).",
|
||||||
|
"keywords": [
|
||||||
|
"pi-package"
|
||||||
|
],
|
||||||
|
"pi": {
|
||||||
|
"skills": [
|
||||||
|
"./skills"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,57 @@
|
|||||||
|
---
|
||||||
|
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. Ú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. **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.
|
||||||
|
4. **Ajusta** `INSTALL.md` con los requisitos y pasos reales del stack elegido.
|
||||||
|
5. **Commit inicial** si se creó repo git:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add -A && git commit -m "docs: base documental inicial"
|
||||||
|
```
|
||||||
|
6. Informa al usuario de la ruta creada, los ficheros y del commit.
|
||||||
|
|
||||||
|
## 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` 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.
|
||||||
|
- `templates/` — plantillas con marcadores `{{PROYECTO}}`, `{{DESCRIPCION}}`,
|
||||||
|
`{{AUTOR}}`, `{{FECHA}}`, `{{FECHA_ISO}}`.
|
||||||
|
- `references/plantillas.md` — qué contiene cada documento y cuándo tocarlo.
|
||||||
@@ -0,0 +1,32 @@
|
|||||||
|
# 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. |
|
||||||
|
|
||||||
|
## 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` — modelo de pi, contexto y criterio de selección.
|
||||||
|
- `## 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.
|
||||||
Executable
+125
@@ -0,0 +1,125 @@
|
|||||||
|
#!/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=""
|
||||||
|
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).
|
||||||
|
-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; }
|
||||||
|
|
||||||
|
while [[ $# -gt 0 ]]; do
|
||||||
|
case "$1" in
|
||||||
|
-n | --nombre) PROYECTO="${2:-}"; shift 2 ;;
|
||||||
|
-d | --descripcion) DESCRIPCION="${2:-}"; shift 2 ;;
|
||||||
|
-a | --autor) AUTOR="${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
|
||||||
|
|
||||||
|
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 [[ $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 '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'
|
||||||
@@ -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
|
||||||
@@ -0,0 +1,73 @@
|
|||||||
|
# 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. |
|
||||||
|
| _(completar)_ | Añade aquí el código y los recursos del proyecto. |
|
||||||
|
|
||||||
|
## Reglas de modelo
|
||||||
|
|
||||||
|
PENDIENTE: definir qué modelo de pi se usa en este proyecto, con qué contexto y
|
||||||
|
con qué criterio de selección (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`
|
||||||
@@ -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
|
||||||
|
-->
|
||||||
@@ -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}}.
|
||||||
@@ -0,0 +1,56 @@
|
|||||||
|
# {{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
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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.
|
||||||
@@ -0,0 +1,21 @@
|
|||||||
|
# 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`.
|
||||||
|
- [ ] 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`).
|
||||||
Reference in new issue
Block a user