5.1 KiB
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// 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
- tracker start
- tracker note
- tracker stop
- tracker change
- tracker next
- tracker review
Comportamiento requerido:
- 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
- list
- muestra nombre, slug, estado, última sesión y próximo paso si existe
- show
- muestra estado actual, contexto, último resumen, bloqueos, próximos pasos y última actividad
- start
- 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
- note
- agrega nota a la sesión activa
- soporta tipos: work, change, blocker, decision, idea, reference
- stop
- 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
- change
- añade una entrada manual al CHANGELOG.md
- next
- sugiere próximos pasos por reglas simples, sin IA obligatoria
- 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:
...
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