Inicializar issues y proyecto para un repo
Configura las convenciones que asumen las otras habilidades issue-*. Todo lo que se escribe aquí va a GitHub (etiquetas, un proyecto, un enlace al repo): indica lo que vas a crear y obtén la aprobación del usuario primero. No se hace push a git.
Requisitos previos: gh auth status muestra los ámbitos repo y project (si no, gh auth refresh -s project); jq está instalado.
1. Inspeccionar (solo lectura)
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner); OWNER=${REPO%%/*}
gh label list --repo "$REPO" --limit 100
gh project list --owner "$OWNER"
2. Etiquetas
Crea las etiquetas estándar a continuación (nombre|descripción|color). Añade las etiquetas componente propias del repo (por defecto backend, frontend; elimina o añade según corresponda). Deja las etiquetas predeterminadas de GitHub (enhancement, documentation, ...) intactas a menos que se te pida otro.
while IFS='|' read -r n d c; do
gh label create "$n" --repo "$REPO" --description "$d" --color "$c" --force
done <<'EOF'
bug|Something isn't working|d73a4a
feature|New user-facing capability|a2eeef
tech-debt|Tracked technical debt|fbca04
epic|Multi-issue effort|5319e7
backend|Backend / services|0e8a16
frontend|Frontend / web app|1d76db
performance|Performance|fef2c0
security|Security|d93f0b
testing|Tests / CI / E2E|c5def5
privacy|Privacy / GDPR|bfdadc
ai|Addressable by an AI agent without human intervention|7057ff
needs-context|AI-addressable once a quick check or decision is answered (also carries ai)|fbca04
needs-human|Needs a device, store/legal/owner decision, external access or a roadmap choice|d93f0b
wontfix|This will not be worked on|ffffff
EOF
gh label list --repo "$REPO" # create es silencioso en caso de éxito: verificar
3. Tablero
A. Copiar un tablero de referencia (campos y vistas, no elementos):
gh project copy <número-fuente> --source-owner <propietario> --target-owner "$OWNER" --title "<Nombre del repo>"
B. Desde cero:
gh project create --owner "$OWNER" --title "<Nombre del repo>" --format json -q '.number' # anotar como $N
for f in Reach Impact "Confidence (%)" "Effort (days)" RICE; do
gh project field-create "$N" --owner "$OWNER" --name "$f" --data-type NUMBER
done
Un tablero nuevo ya tiene un campo Status con Todo, In Progress, Done; eso es suficiente
(se puede añadir una opción Defer en la interfaz del tablero).
Luego vincularlo y verificar:
gh project link "$N" --owner "$OWNER" --repo "$REPO"
# luego seguir "Resolver IDs primero" en issue-project-fields: debe encontrar el tablero y todos los campos
4. Documentarlo en el repo
Añade esta sección a las instrucciones del agente del repo (AGENTS.md, CLAUDE.md o ambos), completando los espacios <...> (repo, URL del tablero y las etiquetas de componente que creaste en el paso 2; si las habilidades provienen de un plugin, menciónalo y nómbralo). Haz commit en una rama, no en la rama predeterminada.
## Seguimiento del trabajo (GitHub Issues)
El backlog vive en **GitHub Issues** (`<propietario/repo>`), seguido en el proyecto **<título del tablero>** (<URL del tablero>). El issue es la fuente de verdad para el contexto *y* el estado; refiérete al trabajo por número de issue (`#123`) y etiquetas. Habilidades del flujo de trabajo: `issue-search`, `issue-file`, `issue-start`, `issue-pr-refs`, `issue-close-out`, `issue-project-fields`, `issue-score`, `issue-link`, `issue-plan-doc`, `issue-file-found`, `issue-audit-scores`, `issue-project-init` (<de dónde vienen>).
### Etiquetas
| Grupo | Etiquetas | Regla |
|---|---|---|
| Tipo | `bug`, `feature`, `tech-debt`, `epic` | Exactamente una por issue |
| Componente | <ej. `backend`, `frontend`> | Las que correspondan |
| Tema | `performance`, `security`, `testing`, `privacy` | Opcional |
| Enrutamiento de agente | `ai`, `needs-context`, `needs-human` | Opcional. `ai` = un agente puede hacerlo sin supervisión; `needs-context` = un agente puede una vez que se responda una pregunta rápida (también lleva `ai`); `needs-human` = necesita un dispositivo, acceso externo o una decisión del propietario |
### Campos del proyecto
| Campo | Valores | Notas |
|---|---|---|
| Status | Todo / In Progress / Done | Solo lo establece el agente orquestador |
| Reach | 1–5 | A cuántos usuarios afecta |
| Impact | 0.5–3 | Magnitud del efecto |
| Confidence (%) | porcentaje entero, ej. `70` | |
| Effort (days) | número | |
| RICE | `(Reach × Impact × Confidence) / Effort` | También se escribe en el cuerpo como `**Score:** RICE x = (R × I × C%) / Ed` para que el issue se lea de forma independiente |
### Cuerpo del issue y flujo de trabajo
**El cuerpo del issue** lleva el registro completo: Descripción, Estado Actual, Qué Necesita Hacerse, Por Qué Es Importante, Archivos Relacionados, estimación. Vincula trabajo relacionado con `#n`; expresa el orden con "bloqueado por" (texto del cuerpo y la API de dependencias, ver `issue-link`). El trabajo grande es un `epic` cuyo plan vive en el cuerpo del issue y cuyas partes son sub-issues.
- **Antes de empezar:** buscar primero (`issue-search`); reutilizar o extender en lugar de reportar duplicados.
- **Mientras se trabaja:** establecer el elemento como In Progress y asignarlo (`issue-start`); los nombres de rama llevan el número de issue (`feat/123-short-desc`). Los bugs y la deuda técnica comienzan con una prueba que falla. Registrar hallazgos no relacionados como nuevos issues en lugar de ampliar el alcance (`issue-file-found`).
- **Al finalizar:** cada PR referencia sus issues (`Closes #n` por issue, `Part of #n` para el epic; `issue-pr-refs`); después de fusionar, establecer Status = Done y actualizar los issues relacionados (`issue-close-out`).
- `gh` necesita el ámbito `project` (`gh auth refresh -s project`). Solo el agente orquestador cambia el estado del issue/proyecto; los subagentes delegados no crean, editan ni cierran issues.
5. Opcional: sembrar un epic
issue-file (tipo epic) → issue-plan-doc → por cada parte issue-file + issue-link + issue-project-fields + issue-score.
Problemas conocidos
gh label create,gh project copy|link|item-editson silenciosos en caso de éxito: siempre verificar.- Un tablero copiado comienza vacío;
item-addes idempotente. - Las llamadas REST de sub-issues y dependencias toman el ID numérico de base de datos del issue (ver
issue-link). - Confidence es un porcentaje entero (
70); los IDs difieren por tablero, por lo que siempre redescubrirlos (issue-project-fields).