prueba de proyecto

backlog/mvp-1.md

@@ -0,0 +1,246 @@
+Construye un MVP v1 de un sistema local de seguimiento de proyectos personales.
+
+Objetivo:
+Crear una herramienta CLI que opere sobre archivos Markdown y YAML para ayudar a seguir proyectos personales con foco en continuidad entre sesiones. El sistema combina Kanban liviano, documentación viva, changelog y bitácora técnica por sesiones.
+
+Restricciones obligatorias:
+- usar persistencia en archivos legibles
+- Markdown como formato principal
+- YAML/JSON simple para metadatos
+- sin base de datos
+- sin interfaz web
+- sin dependencias cloud
+- todo debe seguir siendo usable manualmente aunque la CLI no exista
+- una sola sesión activa a la vez en v1
+- LOG.md append-only
+- README.md solo puede modificarse en secciones autogeneradas delimitadas por marcadores AUTOGEN
+
+Stack preferido:
+- Python 3.11+
+- Typer
+- Jinja2
+- PyYAML
+- GitPython opcional
+
+Estructura del repositorio esperada:
+- README.md principal
+- pyproject.toml
+- tracker.yaml
+- paquete tracker/ con cli, services, models, storage, utils y templates
+- carpeta projects/
+- carpeta tests/
+- carpeta examples/
+
+Cada proyecto debe generarse así:
+projects/<slug>/
+  README.md
+  LOG.md
+  CHANGELOG.md
+  TASKS.md
+  sessions/
+  docs/
+  assets/
+  meta/project.yaml
+
+Comandos mínimos a implementar:
+- tracker init-project
+- tracker list
+- tracker show <slug>
+- tracker start <slug>
+- tracker note <text>
+- tracker stop <slug>
+- tracker change <slug>
+- tracker next <slug>
+- tracker review
+
+Comportamiento requerido:
+
+1. init-project
+- crea estructura de carpetas
+- genera README.md, LOG.md, CHANGELOG.md, TASKS.md y meta/project.yaml desde plantillas
+- acepta name, type, tags, repo-path y description
+
+2. list
+- muestra nombre, slug, estado, última sesión y próximo paso si existe
+
+3. show <slug>
+- muestra estado actual, contexto, último resumen, bloqueos, próximos pasos y última actividad
+
+4. start <slug>
+- valida que no exista otra sesión activa
+- registra hora de inicio
+- crea sesión activa en un archivo tipo .active_session.json
+- puede aceptar objective
+- muestra contexto reciente
+
+5. note <text>
+- agrega nota a la sesión activa
+- soporta tipos: work, change, blocker, decision, idea, reference
+
+6. stop <slug>
+- registra fin
+- calcula duración
+- consolida notas
+- genera resumen heurístico
+- sugiere próximos pasos
+- crea archivo detallado en sessions/YYYY-MM-DD_HHMM.md
+- actualiza LOG.md
+- actualiza README.md en bloques AUTOGEN
+- opcionalmente actualiza CHANGELOG.md
+- limpia sesión activa
+
+7. change <slug>
+- añade una entrada manual al CHANGELOG.md
+
+8. next <slug>
+- sugiere próximos pasos por reglas simples, sin IA obligatoria
+
+9. review
+- muestra proyectos activos, últimas sesiones, bloqueos abiertos y proyectos sin actividad reciente
+
+Modelo mínimo:
+
+Proyecto:
+- id
+- name
+- slug
+- description
+- type
+- status
+- tags
+- root_path
+- repo_path
+- created_at
+- updated_at
+- last_session_at
+
+Sesión:
+- id
+- project_slug
+- started_at
+- ended_at
+- duration_minutes
+- objective
+- summary
+- work_done
+- changes
+- decisions
+- blockers
+- next_steps
+- references
+- raw_notes
+
+Cambio:
+- date
+- type
+- title
+- impact
+- references
+
+Valores sugeridos de type:
+- code
+- homelab
+- automation
+- agent
+- research
+- misc
+
+Valores sugeridos de status:
+- inbox
+- next
+- active
+- blocked
+- waiting
+- done
+- archived
+
+README.md del proyecto debe incluir:
+- nombre
+- descripción
+- objetivo
+- estado actual
+- contexto actual
+- stack / herramientas
+- arquitectura breve
+- decisiones técnicas
+- riesgos / bloqueos
+- próximos pasos
+- últimas sesiones
+
+Usa bloques delimitados, por ejemplo:
+<!-- AUTOGEN:STATUS_START -->
+...
+<!-- AUTOGEN:STATUS_END -->
+
+LOG.md debe ser append-only y usar entradas como:
+## 2026-03-23 10:00–11:20
+**Objetivo**
+...
+**Trabajo realizado**
+- ...
+**Cambios relevantes**
+- ...
+**Bloqueos**
+- ...
+**Decisiones**
+- ...
+**Próximos pasos**
+- ...
+**Resumen**
+...
+
+CHANGELOG.md debe registrar solo cambios relevantes:
+- code
+- infra
+- config
+- docs
+- automation
+- decision
+
+TASKS.md debe tener secciones:
+- Inbox
+- Próximo
+- En curso
+- Bloqueado
+- En espera
+- Hecho
+
+Heurísticas mínimas:
+- si hay bloqueos abiertos, priorizar destrabar
+- si hubo cambios sin validación, sugerir validar
+- si hubo trabajo parcial, sugerir cerrar el hilo abierto
+- si no hubo avances, sugerir redefinir objetivo
+- si hubo commits recientes no documentados, sugerir registrarlos
+
+Integración Git:
+- opcional
+- leer commits recientes si repo_path existe
+- no hacer commit, push ni cambios de ramas
+
+Requisitos de calidad:
+- código modular
+- mensajes de error claros
+- paths multiplataforma
+- UTF-8
+- tests básicos del flujo principal
+
+Entregables:
+- estructura completa del repositorio
+- CLI funcional
+- plantillas base
+- README principal
+- ejemplos de uso
+- tests básicos
+- proyecto demo
+
+Prioriza claridad, mantenibilidad y bajo acoplamiento.
+
+Además:
+- implementa primero la estructura y los comandos base
+- evita sobreingeniería
+- usa funciones pequeñas y testeables
+- separa claramente CLI, lógica de dominio y persistencia
+- no escondas datos importantes en formatos opacos
+- añade ejemplos de salida de comandos
+- incluye un proyecto demo ya generado
+- incluye tests del flujo init-project → start → note → stop → show