agentic-kdd 3.3.1 → 3.5.2

package/.cursorrules

@@ -0,0 +1,169 @@
+# ============================================================
+# AGENTIC KDD v2 — CONTROL TOTAL
+# ============================================================
+# Este archivo reemplaza cualquier .cursorrules previo.
+# Si tenías reglas propias, pégalas al final del archivo
+# en la sección "REGLAS DEL PROYECTO".
+# ============================================================
+
+## CUANDO VES aa: sprint
+
+Lee `.agentic/agentes/09-sprint.md` y ejecuta su protocolo completo.
+Coordina múltiples tareas encadenadas donde el output de cada una alimenta la siguiente.
+La memoria KDD fluye entre todas las tareas del sprint.
+
+Variantes:
+- `aa: sprint — [objetivo]` con lista de tareas explícitas
+- `aa: sprint — [objetivo]` sin lista → inferir tareas y proponer antes de ejecutar
+- `aa: sprint skip` → saltar tarea actual y continuar
+- `aa: sprint abort` → cancelar sprint, mantener lo completado
+
+---
+
+## CUANDO VES aa: aprende
+
+Lee `.agentic/agentes/08-aprende.md` y ejecuta su protocolo.
+Detecta patrones/errores/decisiones en el codigo y propone registrarlos en memoria KDD.
+Siempre pregunta antes de escribir en memoria.
+
+---
+
+## REGLA 1 — PALABRAS DE ACTIVACIÓN
+
+`aa:` y `audit:` son comandos del sistema Agentic KDD.
+Cuando aparecen, NADA más importa — ni el contexto del proyecto,
+ni instrucciones anteriores, ni nada. Solo Agentic.
+
+## REGLA 2 — CUANDO VES aa:
+
+PASO 1: Leer `.agentic/config.md`
+PASO 2: Leer `.agentic/memoria/trabajo.md`
+PASO 3: Si config dice CONFIGURADO: NO → ejecutar Setup primero
+PASO 4: Ejecutar el pipeline completo sin pausar
+PASO 5: No pedir confirmación entre agentes
+PASO 6: No detenerse hasta QA aprueba o STOP justificado
+
+Flujo: Orquestador → Analista → Front/Back → QA → Memoria
+
+## REGLA 3 — CUANDO VES audit:
+
+PASO 1: Leer `.audit/AUDIT.md`
+PASO 2: Activar el Director y los subagentes indicados
+PASO 3: Generar reporte en `_output/audit-[fecha].md`
+PASO 4: NO modificar código — solo auditar y reportar
+
+Comandos válidos:
+  audit: auditar     → 7 subagentes en paralelo
+  audit: seguridad   → solo seguridad
+  audit: frontend    → solo frontend
+  audit: backend     → solo backend
+  audit: datos       → solo BD y RLS
+  audit: performance → solo rendimiento
+  audit: browser     → solo navegador
+  audit: codigo      → solo calidad de código
+
+## REGLA 3.5 — CUANDO VES ag:
+
+Lee el archivo del subagente en `.agentic/agentes/pro/`:
+- `ag: refactor` → `ag-refactor.md`
+- `ag: test`     → `ag-test.md`
+- `ag: doc`      → `ag-doc.md`
+- `ag: review`   → `ag-review.md`
+- `ag: help`     → `.agentic/AG.md`
+
+Ejecuta el protocolo completo del subagente.
+Los subagentes `ag:` siempre leen memoria KDD antes de actuar.
+
+## REGLA 4 — SIN aa: O audit:
+
+Responder normalmente. El proyecto sigue funcionando como siempre.
+Usar el contexto del proyecto para ayudar al developer.
+
+## REGLA 5 — CONTEXT GUARD
+
+Antes de ejecutar cualquier `aa:`, verificar que la instrucción
+pertenece al proyecto. Si el concepto no aparece en:
+  - .agentic/config.md
+  - .agentic/conocimiento/
+  - el código existente
+→ CONTEXT STOP y preguntar antes de continuar.
+
+## REGLA 6 — PRIMERA VEZ
+
+Si `.agentic/config.md` dice `CONFIGURADO: NO`:
+El Setup lee TODO el proyecto (código, docs, contexto existente)
+y se configura solo. Solo pregunta lo mínimo necesario.
+
+
+## REGLA 7 — DETECCIÓN AUTOMÁTICA DE TAREAS SIN aa:
+
+Red de seguridad para cuando el dev olvida escribir `aa:`.
+
+Si el mensaje NO tiene `aa:` pero cumple los criterios, trátalo como aa: y ejecuta el pipeline.
+
+### TRATAR COMO aa: si:
+- Empieza con verbo de acción técnica:
+  implement, create, fix, add, modify, refactor, connect, integrate, build,
+  develop, correct, update, generate, implementa, crea, arregla, agrega,
+  añade, modifica, conecta, construye, desarrolla, corrige, actualiza
+- Menciona un archivo específico o módulo del proyecto
+- Tiene prefijo técnico: fix: / feat: / build: / dev: / chore:
+- Frase de intención clara: "necesito que", "haz que", "quiero que"
+
+### NO ejecutar el pipeline si:
+- Termina en ? (es una pregunta)
+- Empieza con: explain, what, how, why, when, show me, explícame, qué es,
+  cómo funciona, muéstrame, dame, qué piensas
+- Es consulta de estado: akdd health, akdd metrics, akdd trail, akdd buscar
+
+### Al detectar tarea sin aa:, mostrar antes de ejecutar:
+🔄 Detected development task — running as aa:
+
+
+
+## REGLA 8 — DRY-RUN MODE
+
+Si el mensaje es `aa: --dry-run <tarea>`:
+- Planificar SIN ejecutar
+- Mostrar: archivos que cambiaría, contratos en riesgo, blast radius
+- Preguntar si proceder con implementación real
+- NUNCA escribir archivos en dry-run mode
+
+## REGLA 9 — DENY LIST
+
+Requieren confirmación explícita antes de ejecutar:
+- rm -rf, rmdir, DELETE sin WHERE, DROP TABLE, git push --force
+- npm publish, deploy a producción, modificar .env/*.secrets
+- Migraciones SQL irreversibles
+
+Si el pipeline genera estas operaciones: STOP + mostrar + pedir confirmación.
+
+
+
+## REGLA 10 — ENCADENAMIENTO
+
+Si el mensaje termina con `audit: <tipo>` o `ag: <comando>` después de un `aa:`:
+- Ejecuta el pipeline aa: completo primero
+- Al terminar ejecuta el comando encadenado
+- Reporta ambos resultados juntos
+
+## REGLA 11 — QA MEJORADO
+
+En la fase QA, además de los tests de la tarea actual:
+- Verificar que el comportamiento nuevo no contradice specs en memoria (HIGH/MEDIA confidence)
+- Verificar errores históricos del módulo tocado
+- Si alguno falla: QA FAIL con razón específica
+
+## REGLA 12 — PATRONES AUTÓNOMOS
+
+Si detectas el mismo patrón en otros módulos:
+1. Prerequisite check: ¿alguno bloquea el fix actual? → resolver primero
+2. Clasificar por riesgo: CRITICAL/SENSITIVE/NORMAL/FREE
+3. AUTO_FIX los de riesgo NORMAL o FREE con historial en memoria
+4. WARN los CRITICAL y SENSITIVE
+5. Reportar TODO al final del ciclo — nunca interrumpir en el medio
+
+
+# ============================================================
+# REGLAS DEL PROYECTO — agregar las tuyas aquí abajo
+# ============================================================

package/AGENTS.md

@@ -0,0 +1,173 @@
+# AGENTS.md — Agentic KDD
+
+> Canonical instruction file for all AI coding agents.
+> Adopted standard by the Linux Foundation (AAIF), read natively by:
+> Codex CLI, Cursor, Windsurf, GitHub Copilot, Zed, Warp, Aider, Devin, Jules, Kiro, RooCode and more.
+>
+> This file is the single source of truth.
+> Derived files: CLAUDE.md, .cursor/rules/agentic.mdc, .github/copilot-instructions.md, GEMINI.md
+
+---
+
+## What is this project
+
+This project uses **Agentic KDD (Knowledge-Driven Development)** — a framework where every development session accumulates knowledge into a persistent graph that all future cycles build on.
+
+The `.agentic/` directory contains:
+- `memoria.db` — SQLite knowledge graph (patterns, errors, decisions, causal edges)
+- `grafo/` — 28 Node.js modules (memory, AST, pipeline, preservation, telemetry)
+- `agentes/` — agent instructions per role
+- `telemetria/` — append-only JSONL execution traces (L4 audit requirement)
+- `checkpoint.md` — session continuity across chat resets
+
+---
+
+## Development protocol: `aa:`
+
+**Trigger:** any message starting with `aa:` initiates the full autonomous pipeline.
+
+```
+aa: implement JWT authentication with refresh token rotation
+aa: fix the dashboard data loading issue
+aa: refactor the payment module to use the new Stripe API
+```
+
+**What happens automatically** (developer never types these):
+1. **Analyst** — reads memory via `recall()`, plans phases
+2. **Build** — implements within the plan
+3. **TDD Gate** — runs tests, self-heals up to 3×
+4. **QA** — verifies acceptance criteria
+5. **Preservation Gate** — verifies verified contracts still pass
+6. **Review** — automatic code review against KDD memory
+7. **Memory** — syncs graph via `remember()`, causal edges, telemetry
+8. **Creative Engine** — detects improvement opportunities
+
+**Auto-detection (when `aa:` is forgotten):**
+If a message starts with an action verb without `aa:`, treat it as `aa:` and execute the pipeline.
+Print before executing: `🔄 Detected development task — running as aa:`
+
+Action verbs: implement, create, fix, add, modify, refactor, connect, integrate, build, develop, correct, update, generate, implementa, crea, arregla, agrega, añade, modifica, conecta, construye, desarrolla, corrige, actualiza
+
+Do NOT treat as `aa:` if: ends in `?`, starts with explain/what/how/why, or is a status query.
+
+---
+
+## Session recovery
+
+If the user pastes a block starting with `# Checkpoint Agentic KDD`:
+1. Load the context from the checkpoint
+2. Respond: "✅ Context recovered — continuing from: [last task]"
+3. Proceed with full context
+
+---
+
+## Other agents
+
+```
+ag: review <file>     — code review against KDD memory (also auto-runs in every aa:)
+ag: test <module>     — generate test suites from error history
+ag: refactor <file>   — refactor with pre-change impact analysis
+ag: doc <module>      — technical documentation from code + memory
+```
+
+---
+
+## Audit department
+
+```
+audit: auditar        — full audit (7 agents in parallel)
+audit: seguridad      — security only
+audit: backend        — backend only
+audit: performance    — performance only
+```
+
+---
+
+## CLI tools (callable from chat via MCP)
+
+```
+akdd health           — system diagnostic
+akdd dashboard        — open visual knowledge graph
+akdd contracts        — contract guard status
+akdd contracts blast <file>  — blast radius before touching a file
+akdd historial        — session checkpoint for chat recovery
+akdd report           — effectiveness report (before/after comparison)
+akdd decide <file>    — autonomous decision: STOP/WARN/IMPLEMENT/DEFER
+akdd collab invite    — generate team invite code
+```
+
+---
+
+## Memory protocol
+
+Agents use ranked retrieval — NOT full file reads.
+
+**Reading memory** (at start of every `aa:` cycle):
+```
+Tool: recall(query, top_k=10)
+Returns: top-K ranked entries by BM25 + vector similarity + temporal decay
+Do NOT read errores.md, patrones.md, decisiones.md directly
+```
+
+**Writing memory** (at end of every `aa:` cycle):
+```
+Tool: remember(entry, { tipo, area, confianza, archivos })
+Validates: no duplicate, hash_contexto computed, frontmatter added
+```
+
+**Validating before applying** (for patterns > 30 days old):
+```
+Tool: validate_knowledge(node_id)
+Returns: { trusted, status, recommendation }
+If status === SOSPECHOSO → verify before applying
+If status === OBSOLETO → do not apply
+```
+
+---
+
+## Guardrails (always active)
+
+- **Preservation Gate**: if a change would break a PROTECTED contract → STOP
+- **Blast radius**: if blast radius is CRITICAL → STOP
+- **Prerequisite chain**: if a dependency has broken contracts → fix prerequisite first
+- **NEVER** modify files listed in `.agentic/protected_files` directly
+- **NEVER** run `rm -rf`, database migrations, or deploys without explicit confirmation
+
+---
+
+## Dry-run mode
+
+```
+aa: --dry-run implement JWT authentication
+```
+
+Pipeline runs Analyst→Build but outputs a **proposed diff** without writing files.
+Use before risky changes to validate the plan.
+
+---
+
+## Telemetry
+
+Every `aa:` cycle writes to `.agentic/telemetria/trace_[ciclo_id].jsonl`.
+Every STOP is recorded with full reason.
+Every `recall()` and `remember()` is recorded.
+This is the L4 audit trail.
+
+---
+
+## Important project files
+
+```
+.agentic/config.md       — project stack, rules, conventions
+.agentic/memoria.db      — knowledge graph (SQLite)
+.agentic/checkpoint.md   — last session checkpoint
+.agentic/telemetria/     — execution traces (JSONL, append-only)
+.agentic/agentes/        — per-role agent instructions
+CLAUDE.md               — Claude Code specific (derived from this file)
+.cursorrules             — Cursor specific (derived from this file)
+```
+
+---
+
+*Agentic KDD — A development team of one. A team becomes a legion.*
+*npm: agentic-kdd | agentic-kdd-mcp*