Estándar de proyectos — Jan Polanco Velasco

Filosofía central: todo lo que vive dentro de la carpeta del proyecto tiene una instrucción escrita. El documento que la contiene es

CONSTITUTION.md

, la fuente única de verdad. Un proyecto sano es un proyecto donde un agente (o una persona) puede leer la constitución y operar sin adivinar.

Cómo invocarlo (plantilla de prompt)

@jan-project-standard

Soy:         Jan  |  NO soy Jan → aquí mi nombre y correo
Estado:      proyecto nuevo  |  proyecto existente (ya tiene README y/o CONSTITUTION.md)
Repo:        git@github.com:<usuario>/<repo>.git
Stack:       Python (uv) · ¿paquete o app? · ¿ty? · ¿Archify?
Objetivo:    crear desde cero  |  estandarizar SIN borrar  |  solo auditar  |  añadir X
Restricción: no elimines nada existente; mejora y completa.

• En un proyecto existente: primero leer, luego proponer, luego aplicar. Nunca reemplaces archivos del usuario (README,

  CONSTITUTION.md

  , código) sin revisarlos.
• Si no eres Jan: no uses rutas ni repos fijos; aporta tus datos (ver "Identidad Git").
• Ante la duda, audita (

  --audit

  ) y muestra el informe antes de tocar nada.

Cuándo usar este skill

• Crear un proyecto o repositorio nuevo desde cero.
• Estandarizar un proyecto existente que no sigue el estándar.
• Redactar, poblar o actualizar un

  CONSTITUTION.md

  .
• Configurar

  uv

  + Ruff + pre-commit + Makefile + CI.
• Conectar un proyecto local a un repositorio de GitHub.
• Preparar un README profesional con badges, licencia y estructura.

Cuándo NO usarlo

• Proyectos que ya tienen su propio estándar y el usuario no quiere adoptar este.
• Cambios triviales de una línea en un repo ya estandarizado (no re-scaffold).

Las 10 reglas no negociables

1. CONSTITUTION.md primero. La constitución se crea al inicio y se actualiza en el mismo commit ante cualquier cambio arquitectónico, tecnológico o de proceso.

2. uv

   manda. Gestión de entornos y dependencias solo con

   uv

   . Prohibido

   pip

   y

   requirements.txt

   . Dependencias en

   pyproject.toml

   ;

   uv.lock

   sí se versiona.
3. Python 3.13+ fijado en

   .python-version

   y en

   requires-python

   .
4. src-layout (

   src/<paquete>/

   ) con build backend

   uv_build

   , salvo apps simples (modo

   --app

   ).
5. Calidad automatizada: Ruff (lint + formato), pre-commit y pytest. Nada se sube con

   make check

   en rojo.

   --no-verify

   está prohibido salvo causa documentada.
6. Makefile como interfaz. Todos los comandos del proyecto se exponen en targets (

   make help

   los lista). La paridad local ↔ CI es obligatoria: el CI corre lo mismo.
7. Conventional Commits (

   feat:

   ,

   fix:

   ,

   docs:

   ,

   refactor:

   ,

   style:

   ,

   test:

   ,

   chore:

   ) en un solo idioma claro; descripciones en imperativo.
8. GitHub gobernado: plantilla de Pull Request, plantillas de issue, CI, Dependabot, labels declarativas y rama

   main

   protegida por PRs.
9. README profesional: badges, tabla de contenidos, stack, primeros pasos, estructura, arquitectura (opcional, con Archify), contribución y licencia.
10. Identidad Git automática: la carpeta de proyectos hereda nombre, correo y llave SSH vía

    includeIf

    en

    ~/.gitconfig

    . Perfil A para Jan (

    ~/Desktop/Repositorios/personal/

    ); Perfil B para cualquier otro usuario (macOS o Windows), y solo si lo pide (ver

    references/git-identity.md

    ).

Modo A — Crear un proyecto nuevo

Paso 1 · Ejecutar el scaffolder

uv

python3 <SKILL_DIR>/scripts/new_project.py \
  --name "Nombre del Proyecto" \
  --path ./nombre-del-proyecto \
  --description "Descripción breve del proyecto." \
  --git

La autoría y el owner se deducen solos:

--author

/

--email

salen de

git config user.name

/

user.email

, y

--owner

de

git config github.user

. Puedes sobreescribirlos con flags si quieres.

--name

--path

.

--repo

--owner

git config github.user

<usuario>

--description

--author

--email

git config user.name

user.email

--python-version

3.13

--app

--minimal

.github

AGENTS.md

.opencode

--archify

--no-types

ty

--no-github

.github/

--no-agents

AGENTS.md

.opencode/

--git

--no-git

main

--sync

uv sync

uv run pre-commit install

--force

--dry-run

--audit

⚠️ Antes de sobrescribir: si la carpeta destino ya tiene archivos (sobre todo un

CONSTITUTION.md

o

README.md

propios), no uses

--force

a ciegas. Investiga, lee lo existente y fusiona en lugar de reemplazar.

Paso 2 · Poblar la constitución

CONSTITUTION.md

<!-- ... -->

• Propósito y no-propósito (una o dos frases cada uno).
• Alcance (qué entra y qué no).
• Stack técnico (confirma o corrige la tabla).
• Decisiones iniciales en el historial (fecha + decisión + motivo).
• Notas y tareas pendientes (roadmap en formato checklist).

Paso 3 · Verificar el entorno

cd nombre-del-proyecto
uv sync
uv run pre-commit install
make check     # lint + formato + pruebas

Paso 4 · Conectar a GitHub

gh repo create <tu-usuario>/<repo> --private --source=. --remote=origin --push
# o, si el repo ya existe:
git remote add origin git@github.com:<tu-usuario>/<repo>.git
git push -u origin main

main

references/github.md

Paso 5 · Diagrama de arquitectura (opcional, Archify)

npx skills add tt-a1i/archify -g
# Luego, en el chat:
#   "Analiza este repositorio y usa Archify para crear un diagrama de arquitectura de
#    runtime. 8–12 componentes, un camino principal, dependencias externas y límites."

docs/arquitectura.json

docs/arquitectura.html

deliver

references/archify.md

Modo B — Mejorar un proyecto existente (no destructivo)

Contrato de no destrucción. El objetivo no es reemplazar, es completar y elevar. Un repo con historia,

README.md

o

CONSTITUTION.md

propios es trabajo del usuario: se lee, respeta y mejora; nunca se borra ni se sobrescribe con

--force

a ciegas.

1. Audita sin tocar nada (captura el contexto del propio repo):
   bash

   python3 <SKILL_DIR>/scripts/new_project.py --path . --audit

   Lee

   pyproject.toml

   ,

   .python-version

   ,

   CONSTITUTION.md

   y el remoto de git, y reporta FALTA / DIFIERE / OK.

   DIFIERE

   puede ser personalización legítima: revísala.
2. Lee

   README.md

   ,

   CONSTITUTION.md

   y la estructura real antes de cambiar nada.
3. Propón un plan (qué se añade, qué se completa) y aplícalo de forma aditiva:
   bash

   python3 <SKILL_DIR>/scripts/new_project.py --path . --name "..." --description "..."

   Sin

   --force

   , el scaffolder omite todo archivo que ya existe (solo crea lo que falta).
4. Fusiona los

   DIFIERE

   a mano: conserva el contenido del usuario y añade lo que falte (no reemplaces secciones; no borres lo propio).
5. Migra solo si el usuario lo pide:

   requirements.txt

   →

   pyproject.toml

   con

   uv add

   ; scripts sueltos →

   src/<paquete>/

   ;

   .ipynb

   →

   .py

   .
6. Registra el cambio en el historial de la constitución y verifica con

   make check

   .

El

--audit

es la herramienta para "capturar más contexto": puedes correrlo las veces que quieras sin efectos secundarios, incluso en repos grandes, y mostrar el informe antes de proponer cambios.

Manifiesto de archivos del estándar

CONSTITUTION.md

README.md

pyproject.toml

uv

uv.lock

.python-version

3.13

.gitignore

.editorconfig

Makefile

help

install

dev

lint

format

test

check

clean

.pre-commit-config.yaml

uv-lock

LICENSE

CONTRIBUTING.md

CODE_OF_CONDUCT.md

AGENTS.md

.opencode/rules/tgrep.md

tgrep

.github/pull_request_template.md

.github/ISSUE_TEMPLATE/

.github/workflows/ci.yml

.github/workflows/labels.yml

.github/labels.yml

.github/labels.yml

.github/dependabot.yml

uv

src/<paquete>/

tests/

docs/

docs/arquitectura.{json,html}

references/archify.md

Variables de las plantillas

assets/templates/

{{PROJECT_NAME}}

Mi Proyecto

{{PROJECT_SLUG}}

mi-proyecto

{{PACKAGE_NAME}}

mi_proyecto

{{DESCRIPTION}}

{{OWNER}}

{{REPO}}

{{REPO_URL}}

{{SSH_URL}}

{{AUTHOR}}

{{AUTHOR_EMAIL}}

{{PYTHON_VERSION}}

3.13

{{YEAR}}

{{DATE}}

{{#if PACKAGE}}…{{/if}}

{{#if TYPES}}…{{/if}}

ty

{{#if GITHUB}}…{{/if}}

{{#if AGENTS}}…{{/if}}

Documentación de apoyo

references/constitution.md

CONSTITUTION.md

references/python-stack.md

uv

pyproject.toml

.editorconfig

.gitignore

references/github.md

references/agent-context.md

AGENTS.md

.opencode/rules/

references/git-identity.md

includeIf

references/archify.md

references/slidev.md

Identidad Git automática (

includeIf

)

gh auth

references/git-identity.md

Perfil A — Ejemplo (configuración del autor de la skill)

Es solo un ejemplo real de un perfil funcionando. Cualquier otro usuario sigue el Perfil B con sus propios datos.

~/Desktop/Repositorios/personal/

# ~/.gitconfig
[includeIf "gitdir:~/Desktop/Repositorios/personal/"]
    path = ~/.gitconfig-personal

# ~/.gitconfig-personal
[user]
    name = Jan Polanco V.
    email = hamsomp3@gmail.com
[core]
    sshCommand = ssh -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes

git@github.com:<tu-usuario>/<repo>.git

Perfil B — Cualquier otro usuario (alumno, compañero)

includeIf

python3 <SKILL_DIR>/scripts/setup_git_identity.py \
  --name "Pedro Pérez" --email pedro@example.com \
  --key ~/.ssh/id_ed25519 --dir ~/Repos/personal --platform mac
# Windows: --key C:/Users/pedro/.ssh/id_ed25519 --dir C:/Users/pedro/Repos --platform windows

~/.gitconfig

--print

includeIf

gitdir/i:

/

IdentitiesOnly

references/git-identity.md

⚙️ Nunca se commitea: es configuración local de la máquina. Vive en la constitución solo como nota (no como archivo del repo), y solo se aplica si el usuario lo pide.

Flujo diario (commit + push)

git status                       # 1. ver cambios
make check                       # 2. lint + formato + (tipos) + pruebas
git add -A                       # 3. agregar
git commit -m "tipo: mensaje"    # 4. commitear (los hooks se ejecutan solos)
git push                         # 5. subir

Checklist de verificación

• CONSTITUTION.md

  existe y está poblado (propósito, stack, estructura, flujo, decisiones).

• uv sync

  funciona y

  uv.lock

  está versionado.

• make check

  pasa en verde (lint + formato + pruebas).

• uv run pre-commit run --all-files

  pasa (hooks instalados).

• README.md

  tiene badges, TOC, descripción, stack, primeros pasos y licencia.

• LICENSE

  presente (MIT por defecto).

• .github/

  con PR template, issue templates, CI, Dependabot y labels (si aplica).

• AGENTS.md

  (y

  .opencode/rules/tgrep.md

  ) describen el proyecto para agentes (si aplica).
• Identidad Git automática configurada si el usuario lo pidió (perfil A para Jan / perfil B para otros).
• Diagrama de arquitectura con Archify en

  docs/

  y enlazado desde el README (si aplica).
• Sin secretos, datos personales ni artefactos pesados versionados.
• El historial de decisiones de la constitución registra los cambios significativos.

Directiva de mantenimiento

Cada vez que se realicen cambios significativos (nuevas funcionalidades, cambios arquitectónicos, adición de clases/módulos o ajustes de tecnologías), se debe actualizar

CONSTITUTION.md

en el mismo commit para mantener la verdad central del proyecto. El checklist de la plantilla de Pull Request lo verifica explícitamente.