hamsomp3/jan_skills_repository

jan-project-standard

Estandariza proyectos personales y académicos con las convenciones de Jan Polanco Velasco: Python con uv/Astral (3.13+), src-layout, Ruff, pre-commit, Makefile, pytest, CONSTITUTION.md como fuente única de verdad, Conventional Commits, README con badges, li…

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/hamsomp3/jan_skills_repository --skill jan-project-standard

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

Estándar de proyectos — Jan Polanco Velasco

Este skill encapsula cómo se construyen y gobiernan los proyectos de Jan: una forma de trabajar repetible, reproducible y auditable que ya está aplicada en decenas de repositorios personales y académicos.

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)

No hace falta memorizar comandos: describe tu caso en lenguaje natural. Estas son las piezas que conviene incluir:

text
@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.

Reglas de convivencia (obligatorias):

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

  1. `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.

  1. Python 3.13+ fijado en .python-version y en requires-python.
  2. src-layout (src/<paquete>/) con build backend uv_build, salvo apps simples

(modo --app).

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

con make check en rojo. --no-verify está prohibido salvo causa documentada.

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

  1. Conventional Commits (feat:, fix:, docs:, refactor:, style:, test:,

chore:) en un solo idioma claro; descripciones en imperativo.

  1. GitHub gobernado: plantilla de Pull Request, plantillas de issue, CI, Dependabot,

labels declarativas y rama main protegida por PRs.

  1. README profesional: badges, tabla de contenidos, stack, primeros pasos, estructura,

arquitectura (opcional, con Archify), contribución y licencia.

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

El scaffolder copia las plantillas, sustituye variables y deja el proyecto listo. Usa solo la biblioteca estándar de Python (no requiere uv para ejecutarse):

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

Opciones más usadas:

OpciónEfecto
--nameNombre legible del proyecto (obligatorio).
--pathCarpeta destino (por defecto .).
--repoNombre del repo en GitHub (por defecto, slug del nombre).
--ownerCuenta/organización de GitHub (por defecto: git config github.user o <usuario>).
--descriptionDescripción de una línea (va al README, pyproject y constitución).
--author / --emailAutoría (por defecto: git config user.name / user.email).
--python-versionVersión de Python (por defecto 3.13).
--appProyecto de aplicación (sin paquete ni build-system), en vez de src-layout.
--minimalSolo lo esencial: sin .github, sin AGENTS.md/.opencode, sin extras.
--archifyIncluye la sección Arquitectura del proyecto (Archify) en el README y la fila en la constitución.
--no-typesOmite ty (tipado estático) de dependencias, Makefile y docs.
--no-githubNo genera .github/.
--no-agentsNo genera AGENTS.md ni .opencode/.
--git / --no-gitInicializa el repositorio git (rama main). Por defecto: sí.
--syncEjecuta uv sync y uv run pre-commit install al terminar.
--forceSobrescribe archivos existentes.
--dry-runMuestra qué haría sin escribir nada.
--auditSolo audita un proyecto existente (FALTA/DIFIERE/OK) sin escribir nada; infiere el contexto del repo.
⚠️ 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

Abre CONSTITUTION.md y completa, como mínimo, las secciones marcadas con <!-- ... -->:

  • 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

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

Paso 4 · Conectar a GitHub

Crea el repositorio (si no existe) y publica:

bash
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

Luego protege main y verifica que la CI esté en verde. Detalle en `references/github.md`.

Paso 5 · Diagrama de arquitectura (opcional, Archify)

Si el proyecto necesita un mapa de arquitectura en el README (documentación viva), instala la skill Archify y genera el diagrama:

bash
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."

El resultado queda en docs/arquitectura.json (fuente versionada) y docs/arquitectura.html (artefacto interactivo), y se enlaza desde el README. No se edita el HTML a mano: se regenera con deliver. Detalle completo en `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.

  1. Lee README.md, CONSTITUTION.md y la estructura real antes de cambiar nada.
  2. 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).

  1. Fusiona los `DIFIERE` a mano: conserva el contenido del usuario y añade lo que

falte (no reemplaces secciones; no borres lo propio).

  1. Migra solo si el usuario lo pide: requirements.txt → pyproject.toml con uv add;

scripts sueltos → src/<paquete>/; .ipynb → .py.

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

ArchivoPropósito
CONSTITUTION.mdFuente única de verdad: propósito, stack, estructura, convenciones, flujo y decisiones.
README.mdPuerta de entrada pública: badges, TOC, descripción, stack, primeros pasos, estructura, contribución, licencia.
pyproject.tomlMetadatos, dependencias (uv), configuración de Ruff y pytest.
uv.lockLockfile determinista (versionado).
.python-versionVersión de Python fijada (3.13).
.gitignoreIgnora venvs, cachés, secretos, artefactos pesados y datos.
.editorconfigConvenciones de estilo entre editores.
MakefileInterfaz de comandos (help, install, dev, lint, format, test, check, clean).
.pre-commit-config.yamlHigiene de archivos + Ruff + uv-lock antes de cada commit.
LICENSEMIT por defecto.
CONTRIBUTING.mdEntorno, ramas, estándares, commits y proceso de PR.
CODE_OF_CONDUCT.mdContributor Covenant 2.1 (proyectos con colaboración).
AGENTS.mdContexto para agentes LLM (stack, flujo, reglas, tgrep).
.opencode/rules/tgrep.mdRegla de búsqueda con tgrep para agentes en OpenCode.
.github/pull_request_template.mdPlantilla de PR (Conventional Commits + checklist).
.github/ISSUE_TEMPLATE/Formularios de bug, funcionalidad e investigación (spike).
.github/workflows/ci.ymlCI: pre-commit + pruebas.
.github/workflows/labels.ymlSincroniza labels desde .github/labels.yml.
.github/labels.ymlFuente única de las etiquetas del repositorio.
.github/dependabot.ymlActualización automática de dependencias (uv y Actions).
src/<paquete>/Código del paquete (src-layout).
tests/Pruebas con pytest (patrón AAA).
docs/Documentación, ADRs, spikes e investigación.
docs/arquitectura.{json,html}Diagrama interactivo de arquitectura (Archify); el JSON es la fuente. Ver `references/archify.md`.

Variables de las plantillas

Las plantillas bajo assets/templates/ usan marcadores que el scaffolder sustituye. Si editas a mano, reemplázalos todos:

MarcadorSignificado
{{PROJECT_NAME}}Nombre legible (Mi Proyecto).
{{PROJECT_SLUG}}Identificador kebab-case (mi-proyecto), usado como carpeta y repo.
{{PACKAGE_NAME}}Identificador snakecase (`miproyecto`), usado como paquete Python.
{{DESCRIPTION}}Descripción de una línea.
{{OWNER}} / {{REPO}}Cuenta y nombre del repositorio.
{{REPO_URL}} / {{SSH_URL}}URLs HTTPS y SSH del repositorio.
{{AUTHOR}} / {{AUTHOR_EMAIL}}Autoría.
{{PYTHON_VERSION}}Versión de Python (3.13).
{{YEAR}} / {{DATE}}Año y fecha ISO.

Bloques condicionales (se eliminan si la bandera es falsa): {{#if PACKAGE}}…{{/if}} (src-layout), {{#if TYPES}}…{{/if}} (ty), {{#if GITHUB}}…{{/if}}, {{#if AGENTS}}…{{/if}}.


Documentación de apoyo

Carga estos archivos solo cuando los necesites (divulgación progresiva):

ReferenciaContenido
`references/constitution.md`Anatomía completa del CONSTITUTION.md sección por sección, con ejemplos.
`references/python-stack.md`uv, pyproject.toml, Ruff, Makefile, pre-commit, .editorconfig, .gitignore.
`references/github.md`Creación del repo, remotos SSH, badges, plantillas, CI, Dependabot, labels, ramas.
`references/agent-context.md`AGENTS.md, .opencode/rules/ y tgrep.
`references/git-identity.md`Identidad Git automática (includeIf): perfil Jan y perfil propio para macOS/Windows.
`references/archify.md`Diagramas de arquitectura interactivos con Archify (instalación, tipos, validate/deliver, README).
`references/slidev.md`Presentaciones con Slidev (proyectos de curso): monolito, hub, reglas de sintaxis, export.

Identidad Git automática (includeIf)

Configura Git para que todo repositorio bajo una carpeta use automáticamente un nombre, un correo y una llave SSH. Es una de las piezas más útiles del estándar: elimina flags y gh auth por proyecto. Hay dos perfiles y el agente debe decidir cuál aplica (detalle en `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.

Carpeta canónica de ejemplo ~/Desktop/Repositorios/personal/:

ini
# ~/.gitconfig
[includeIf "gitdir:~/Desktop/Repositorios/personal/"]
    path = ~/.gitconfig-personal
ini
# ~/.gitconfig-personal
[user]
    name = Jan Polanco V.
    email = hamsomp3@gmail.com
[core]
    sshCommand = ssh -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes

Efecto: todo repo bajo esa carpeta usa el nombre, correo y llave del ejemplo. Preferir remotos SSH (git@github.com:<tu-usuario>/<repo>.git); HTTPS puede resolver con un token de otra cuenta.

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

Si el usuario pide identidad automática y no comparte el perfil de ejemplo, pregúntale primero su nombre, correo, llave SSH y carpeta de proyectos, y luego configura includeIf en su carpeta y su sistema operativo (macOS o Windows). Script listo:

bash
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

El script respalda ~/.gitconfig, es idempotente y tiene un modo --print que solo muestra los bloques sin escribir nada. Pasos manuales y gotchas (orden de includeIf, gitdir/i:, rutas con / en Windows, IdentitiesOnly) en `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)

bash
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

Antes de dar por terminado un proyecto o un cambio:

  • [ ] 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.