# Tzolk'in

> Gestor de proyectos agent-native + memoria persistente para agentes de código (Claude Code).
> Un tablero 2D —fase del ciclo de vida (SDLC) × estado kanban— operado por una CLI barata en
> tokens, con MCP y dashboard web sobre el mismo núcleo. Los datos viven en PostgreSQL del usuario.

Filosofía: **Lee en Markdown · Actúa por acciones · Persiste en SQL.** El estado solo cambia por
comandos tipados (no se corrompe). Cada acción escribe un evento → memoria reconstruible entre sesiones.

## Instalación (para un agente) — conectarse al hosted

Requisitos: Node >= 20, macOS/Linux. NO necesitas base de datos local.

1. Instalar el paquete desde npm (trae la CLI + la skill + los slash commands /tzolk-*):
   npm i -g tzolk        # o: npx tzolk <comando>

2. Apuntar a la instancia hosted y vincular el agente (OAuth, sin pegar tokens):
   export PM_WEB_URL=https://tzolk.angelsalinas.dev
   tzolk login          # abre el navegador, el humano autoriza; token en ~/.config/agent-pm/token
   tzolk whoami         # confirma la conexión

   Con PM_WEB_URL + token, el CLI manda todas las acciones a la API hosted (Authorization: Bearer).

Self-host (opcional): corre tu propio PostgreSQL (DATABASE_URL) + `tzolk web`; el MCP alterna es
el binario `tzolk-mcp` (env DATABASE_URL + AGENT_PM_AGENT=claude). Detalles en el repo.

## Modelo de datos

- Fase (SDLC) = un kanban propio: Requerimientos · Diseño · Desarrollo · Testing · Deploy.
- Estado (kanban) = backlog · todo · in_progress · blocked · review · done.
- Una tarea vive en la celda (fase, estado). `done` significa distinto por fase → trazabilidad.
- `type` = core | feature | bug | redesign | concept | chore.
- `area` = etiqueta transversal (web, api, back, front, bd, …).
- `release` = atributo opcional (v1, v2, …). Tareas con assignee obligatorio, priority, estimate, due, subtareas, ref T-N.

## CLI (superficie principal — preferir sobre MCP por costo de tokens)

Lectura (panorama -> detalle):
  tzolk projects
  tzolk board <proj> [--release|--area|--stage]
  tzolk task <proj> <T-N>
  tzolk area <proj> <area>
  tzolk progress <proj> [--since N]
  tzolk memory <proj> [--limit N]
  tzolk notes <proj> [--kind context|decision|journal|architecture]

Escritura (1 comando = 1 acción):
  tzolk new-project <nombre> [--desc] [--color] [--icon]
  tzolk new-task <proj> <título> --stage <fase> --assignee <quién> [--type --area --status --priority --estimate --due --body]
  tzolk move <proj> <T-N> [--status <col>] [--stage <fase>]
  tzolk edit <proj> <T-N> [--title --body --assignee --priority --area --estimate --due]
  tzolk subtask add|check <proj> <T-N> ...
  tzolk note <proj> <título> --body <md> [--kind] [--task]

Flags globales: --json (salida lean para parsear), --actor <nombre>, --agent <id>.
Ayuda: `tzolk help` (manifiesto) y `tzolk <comando> --help`.

## Enlaces

- Sitio: index.html
- Guía de instalación: install.html