melman-mode

melman-mode

Workflow de desarrollo agentico con soporte para OpenCode y Claude Code. Un único agente primario (melman) cubre investigación, brainstorming, spec, planning, ejecución paralela y reportes — coordinado a través de Linear, GitHub y Slack.

---

Install

Requisitos previos

• OpenCode o Claude Code instalado
• Node.js con npx disponible
• GitHub CLI (gh) — winget install GitHub.cli → gh auth login
• Cuentas activas en Linear, GitHub y Slack

Desde npm

npm install -g melman-mode

Instala para OpenCode y Claude Code simultáneamente. OpenCode queda en ~/.config/opencode/, Claude Code en ~/.claude/.

context-mode se instala automáticamente como dependencia declarada — no requiere pasos adicionales ni permisos de administrador.

Desde el repo (contribuidores / dev)

git clone https://github.com/donlucaso/flow420
cd flow420
npm run setup            # OpenCode
npm run setup:claude     # Claude Code
npm run setup:both       # OpenCode + Claude Code

---

Variables de entorno

Hay dos formas de setearlas en Windows. Las dos son permanentes (persisten al reiniciar).

Opción A — UI (recomendado, sin terminal)

1. Win + R → escribir sysdm.cpl → Enter
2. Pestaña Advanced → botón Environment Variables...
3. En la sección User variables → clic New...
4. Ingresar el nombre (ej. LINEAR_API_KEY) y el valor
5. Repetir para cada variable → OK → OK
6. Cerrar y reabrir cualquier terminal / OpenCode para que tome efecto

Opción B — PowerShell (una línea por variable)

[System.Environment]::SetEnvironmentVariable("LINEAR_API_KEY", "lin_api_...", "User")
[System.Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_...", "User")
[System.Environment]::SetEnvironmentVariable("SLACK_WEBHOOK_URL", "https://hooks.slack.com/services/...", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-...", "User")
[System.Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", "sk-...", "User")
[System.Environment]::SetEnvironmentVariable("EXA_API_KEY", "...", "User")

Cerrar y reabrir la terminal después — SetEnvironmentVariable con "User" no afecta la sesión actual.

Para verificar: [System.Environment]::GetEnvironmentVariable("LINEAR_API_KEY", "User")

Variables requeridas — modelo de IA

Variable	Plataforma	Dónde obtenerla
ANTHROPIC_API_KEY	Claude Code	console.anthropic.com → API Keys
DEEPSEEK_API_KEY	OpenCode (modelo principal)	platform.deepseek.com → API Keys

Solo necesitás la key de la plataforma que uses. Ambas son opcionales si ya configuraste el acceso de otra forma.

Variables opcionales — integraciones de servicio

Sin estas variables, melman funciona en modo local: se comporta como un asistente de código puro sin gestión de estado externo.

Variable	Servicio	Dónde obtenerla
LINEAR_API_KEY	Linear (issues, estados, HITL)	linear.app → Settings → Account → Security & Access → API keys
GITHUB_TOKEN	GitHub (PRs, repos)	github.com → Settings → Developer settings → Personal access tokens → Scopes: repo, pull_requests, issues
SLACK_WEBHOOK_URL	Slack (notificaciones de una vía)	api.slack.com/apps → Create App → Incoming Webhooks → Add to Workspace → copiar URL
EXA_API_KEY	Web search (subagente researcher)	dashboard.exa.ai → API Keys

Variables opcionales — HITL inbound (Slack lee respuestas)

Necesarias solo para el flujo HITL bidireccional (melman envía pregunta y lee la respuesta automáticamente).

Variable	Servicio	Dónde obtenerla
SLACK_BOT_TOKEN	Slack Bot API (chat.postMessage + conversations.replies)	api.slack.com/apps → OAuth & Permissions → Bot Token (xoxb-...) · Scopes: chat:write, conversations:history, conversations:replies
SLACK_CHANNEL_ID	Canal de HITL	Slack → clic derecho en el canal → Copy link → el código al final (C0XXXXXXXXX)

Sin SLACK_BOT_TOKEN: melman detecta la decisión bloqueante, la registra como comentario en Linear, y mueve el issue a Waiting for Input manualmente.

Variables opcionales — otros modelos

Variable	Cuándo usar
OPENAI_API_KEY	Si usás GPT en algún workflow
AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY + AWS_REGION	executor-infra con AWS
DIGITALOCEAN_TOKEN	executor-infra con DigitalOcean

Configuración por proyecto — .env.local

Para proyectos que usan sus propias keys (workspace de Linear distinto, canal de Slack diferente), creá un archivo .env.local en la raíz del proyecto:

# .env.local — gitignored, no commitear
LINEAR_API_KEY=lin_api_...
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
SLACK_BOT_TOKEN=xoxb-...
SLACK_CHANNEL_ID=C0XXXXXXXXX

session-init.sh lo carga automáticamente al inicio de cada sesión (tiene prioridad sobre las variables del sistema).

Seguridad: el archivo se parsea línea a línea (KEY=value) — nunca se ejecuta con source. Solo se aceptan nombres de variable válidos ([A-Za-z_][A-Za-z0-9_]*). Alternativa más explícita: usar /login para guardar credenciales en .opencode/melman/credentials.local.json (gitignored automáticamente).

---

Cómo funciona — las tres capas

git/GitHub  → source of truth del código y specs  (inmutable, distribuido)
Linear      → source of truth del estado del trabajo (mutable, reconstruible)
Session     → contexto efímero, reconstruible desde las dos capas anteriores

Podés cerrar OpenCode, cambiar de PC, o que el contexto se compacte — no perdés nada. Cualquier sesión nueva reconstruye el estado completo con /blockers + el spec en git.

---

Agentes

Agente	Modo	Rol
melman	primary	Orquestador completo — todos los comandos
researcher	subagent	Deep research técnico
executor-backend/frontend/database/cache/infra	subagent	Implementación por dominio, en paralelo
qa	subagent	Tests, coverage, revisión de PRs
fastapi-reviewer / react-reviewer / database-reviewer	subagent	Review especializado, despachado por qa

---

Flujo de una feature

melman (una sola sesión)
│
├── /deep-research   → investiga el contexto técnico (opcional)
├── /brainstorm      → Q&A iterativo, diseño, spec aprobado
├── /spec            → escribe doc → git + Linear Epic + Slack
├── /blockers        → orientarse (estado actual de Linear)
├── /plan            → sub-issues por dominio + milestone
└── /execute         → executors en paralelo → QA → Slack "mergear?"

Brainstorm + Spec: Melman hace preguntas, propone enfoques, escribe docs/specs/YYYY-MM-DD-*.md, commitea, crea Linear Epic + Document, notifica Slack.

Plan: Lee el spec, muestra milestones disponibles, crea sub-issues por dominio en estado Todo.

Execute: Lee stack.json, despacha executors en paralelo (branch + TDD + PR por sub-issue), luego QA. Al terminar: Slack "PRs listos — mergear a staging?" (el merge siempre lo hacés vos).

Bugfix

/blockers  →  ve el bug en Todo
/execute   →  executor crea bugfix/vec-XX-..., fix + test + PR → QA

Hotfix (prod roto)

Executor → branch hotfix/vec-XX-... DESDE PROD → fix mínimo → QA fast-track
Usuario humano → mergea a prod manualmente
Executor → backport PR → dev (obligatorio)

---

Comandos

Todos corren en melman.

Comando	Descripción
/brainstorm	Q&A iterativo → diseño → spec aprobado
/spec	Formaliza spec → git + Linear + Slack
/deep-research <tema>	Investiga un tema técnico (despacha researcher)
/meeting	Triage de notas crudas → Linear Backlog
/blockers	Issues bloqueados en Linear
/plan	Descompone spec en sub-issues por dominio
/execute	Despacha executors en paralelo, loop QA
/status	Micro-recap del Epic activo
/report [daily|weekly|monthly]	Reporte → Slack
/visual	Servidor de mockups para brainstorming visual
/set-stack [key=value]	Configura .opencode/stack.json del proyecto
/cost-report [daily|weekly]	Breakdown de tokens y costo por comando
/login [linear|slack|github]	Configura credenciales por proyecto
/rules [list|add|remove]	Gestiona reglas de comportamiento por capa

---

Verificar que funciona

1. Plugin arrancó — al abrir OpenCode deberías ver:

📊 Linear: N bloqueados · M en progreso · K en review

Si no aparece → revisá las env vars.

2. Linear MCP:

¿Cuáles son los últimos 3 issues de Linear?

3. GitHub MCP:

¿Cuál es mi usuario de GitHub?

4. Slack webhook:

curl -X POST -H 'Content-type: application/json' --data '{\"text\":\"test\"}' $env:SLACK_WEBHOOK_URL

5. Smoke test read-only:

/status

/blockers

Si algo falla:

• MCP no disponible → verificar env var y reiniciar OpenCode
• No encuentra issues → verificar que LINEAR_API_KEY tiene acceso al workspace correcto
• No crea PRs → verificar que GITHUB_TOKEN tiene scopes repo y pull_requests
• Slack no recibe → probar el curl manualmente con la URL completa

---

Traceabilidad

Spec file:   docs/specs/YYYY-MM-DD-scope-feature-design.md
Epic Issue:  feat(scope): description                         → VEC-46
Branch:      feature/vec-46-scope-description
PR title:    feat(scope): description [VEC-46]

El VEC-XX en branch y PR title activa la integración Linear GitHub automáticamente.

---

Publish

El workflow de CI/CD publica automáticamente en npm cuando cambia la versión en package.json en master.

Publicar una nueva versión

# 1. Bumpeá la versión en package.json (ej: 0.1.4 → 0.1.5)
# 2. Commiteá y pusheá a master
git commit -am "chore: bump version to 0.1.5"
git push
# GitHub Actions hace el build y npm publish automáticamente

Mantenimiento del NPM_TOKEN (manual — cada 30 días)

npm no ofrece tokens read+write sin expiración en el plan free — expiran a los 30 días.

Cuándo: GitHub enviará un email cuando el secret esté por vencer, o cuando falle el workflow con 401 Unauthorized.

Cómo renovar:

1. npmjs.com → avatar → Access Tokens → Generate New Token → tipo Granular Access Token
2. Packages and scopes → Read and write · Organizations → No access · Expiration → 30 days
3. github.com/donlucaso/flow420/settings/secrets/actions → NPM_TOKEN → Update → pegar el nuevo token

Agendar un recordatorio mensual o revisar el workflow en GitHub Actions si un push a master no dispara una publicación esperada.

---

Documentación

Doc	Contenido
Overview	Arquitectura, data flow, model routing, benchmarks
Todo / Backlog	Estado del backlog P0–P4
Plugin architecture	Stack auto-detection, OS awareness, worktrees
QA & testing	Pre-PR controls, verification steps, test speed directive
Architecture decision	Decisión de mantener Linear + Slack + GitHub
Rules & credentials	Sistema de rules por capa y credentials.local.json
Linear	Issues, labels, milestones, cycles, templates
GitHub	Branching, PR workflow, CI/CD
Slack	Setup Incoming Webhook, eventos, formato de mensajes
Agents	Jerarquía de agentes, permisos, matriz MCP
Plugin hooks	Diseño del plugin TypeScript y hooks
Feature flow	Flujo de feature detallado
Bugfix flow	Flujo de bugfix
Hotfix flow	Hotfix para producción
Prompt tests	Tests de prompts para validación de agentes
v3 tests	Tests de arquitectura v3

Archive: v2 design · v3 architecture (rejected) · implementation plan · research