@qubiit/lmagent 3.0.1 → 3.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/.agents/config/models.yaml +1 -1
  2. package/.agents/config/settings.yaml +9 -1
  3. package/.agents/docs/commands.md +46 -132
  4. package/.agents/docs/customization-guide.md +24 -432
  5. package/.agents/docs/getting-started.md +49 -126
  6. package/.agents/docs/how-to-start.md +20 -232
  7. package/.agents/docs/navigation-index.md +17 -227
  8. package/.agents/docs/usage-guide.md +17 -108
  9. package/.agents/memory/01-project.md +17 -0
  10. package/.agents/memory/02-tech-updates.md +16 -0
  11. package/.agents/memory/03-learnings.md +12 -0
  12. package/.agents/memory/04-active-context.md +14 -0
  13. package/.agents/memory/05-product-state.md +13 -0
  14. package/.agents/rules/02-tech-stack.md +33 -32
  15. package/.agents/rules/03-code-style.md +1 -1
  16. package/.agents/rules/08-agents-ai.md +22 -611
  17. package/.agents/rules/09-automations.md +15 -642
  18. package/.agents/rules/10-git-flow.md +34 -122
  19. package/.agents/scripts/create_skill.js +1 -1
  20. package/.agents/scripts/validate_skills.js +2 -2
  21. package/.agents/templates/backend-node/Dockerfile +1 -1
  22. package/.agents/templates/backend-node/package.json +10 -10
  23. package/.agents/templates/backend-python/Dockerfile +1 -1
  24. package/.agents/templates/backend-python/requirements-dev.txt +5 -6
  25. package/.agents/templates/backend-python/requirements.txt +4 -4
  26. package/.agents/templates/frontend-react/Dockerfile +19 -0
  27. package/.agents/templates/frontend-react/package.json +31 -0
  28. package/.agents/templates/frontend-react/postcss.config.js +6 -0
  29. package/.agents/templates/frontend-react/tailwind.config.js +11 -0
  30. package/.agents/templates/frontend-react/tsconfig.app.json +35 -0
  31. package/.agents/templates/frontend-react/tsconfig.json +11 -0
  32. package/.agents/templates/frontend-react/tsconfig.node.json +24 -0
  33. package/.agents/templates/frontend-react/vite.config.ts +17 -0
  34. package/.agents/workflows/n8n/README.md +3 -0
  35. package/AGENTS.md +3 -2
  36. package/CONTRIBUTING.md +2 -2
  37. package/README.md +1 -1
  38. package/install.js +123 -87
  39. package/package.json +5 -2
@@ -1,227 +1,17 @@
1
- # LMAgent Framework - Navigation Index
2
-
3
- > **Quick Reference**: Find any resource in the framework instantly.
4
- >
5
- > **Versión**: 3.0 (SPEC+LM) | **Actualizado**: 2026-01
6
-
7
- ---
8
-
9
- ## 🎯 Entry Points (Start Here)
10
-
11
- | Archivo | Propósito | Cuándo Leer |
12
- |---------|-----------|-------------|
13
- | [AGENTS.md](../AGENTS.md) | **Main entry point** - Visual flow, commands, rules | ⭐ SIEMPRE primero |
14
- | [README.md](../README.md) | Overview del proyecto, instalación | Setup inicial |
15
- | [.agent/README.md](../.agent/README.md) | Config para Antigravity | Si usas Antigravity IDE |
16
- | [CLAUDE.md](../CLAUDE.md) | Config para Claude Code | Si usas Claude Code |
17
- | [.cursorrules](../.cursorrules) | Config para Cursor | Si usas Cursor |
18
-
19
- ---
20
-
21
- ## 👥 Personas & Metodologías (21 Total)
22
-
23
- ### Roles de Producto & Gestión
24
-
25
- | Persona | Archivo | Trigger | Especialidad |
26
- |---------|---------|---------|--------------|
27
- | **Orchestrator** | [orchestrator.md](../personas/orchestrator.md) | `/orch` | Meta-routing, coordinación |
28
- | **Product Manager** | [product-manager.md](../personas/product-manager.md) | `/pm` | Requisitos, PRDs, spec.yaml |
29
- | **Scrum Master** | [scrum-master.md](../personas/scrum-master.md) | `/sm` | Agile, procesos, facilitación |
30
- | **Tech Lead** | [tech-lead.md](../personas/tech-lead.md) | `/lead` | Decisiones técnicas, mentoring |
31
-
32
- ### Roles de Ingeniería
33
-
34
- | Persona | Archivo | Trigger | Especialidad |
35
- |---------|---------|---------|--------------|
36
- | **Architect** | [architect.md](../personas/architect.md) | `/arch` | Diseño de sistemas, ADRs |
37
- | **Backend Engineer** | [backend-engineer.md](../personas/backend-engineer.md) | `/dev` | Python, FastAPI, APIs |
38
- | **Frontend Engineer** | [frontend-engineer.md](../personas/frontend-engineer.md) | `/frontend` | React, TypeScript |
39
- | **Mobile Engineer** | [mobile-engineer.md](../personas/mobile-engineer.md) | `/mobile` | React Native |
40
- | **DevOps Engineer** | [devops-engineer.md](../personas/devops-engineer.md) | `/devops` | CI/CD, Docker, K8s |
41
- | **Data Engineer** | [data-engineer.md](../personas/data-engineer.md) | `/dba` | SQL, PostgreSQL, pipelines |
42
-
43
- ### Roles de IA & Automatización
44
-
45
- | Persona | Archivo | Trigger | Especialidad |
46
- |---------|---------|---------|--------------|
47
- | **AI Agent Engineer** | [ai-agent-engineer.md](../personas/ai-agent-engineer.md) | `/ai` | Agentes, RAG, LangChain |
48
- | **Prompt Engineer** | [prompt-engineer.md](../personas/prompt-engineer.md) | `/prompt` | System prompts, CoT |
49
- | **Automation Engineer** | [automation-engineer.md](../personas/automation-engineer.md) | `/auto` | n8n, webhooks |
50
-
51
- ### Roles de Calidad & Seguridad
52
-
53
- | Persona | Archivo | Trigger | Especialidad |
54
- |---------|---------|---------|--------------|
55
- | **QA Engineer** | [qa-engineer.md](../personas/qa-engineer.md) | `/qa` | Testing, E2E |
56
- | **Security Analyst** | [security-analyst.md](../personas/security-analyst.md) | `/sec` | OWASP, compliance |
57
- | **Performance Engineer** | [performance-engineer.md](../personas/performance-engineer.md) | `/perf` | Optimización |
58
-
59
- ### Roles de Documentación & UX
60
-
61
- | Persona | Archivo | Trigger | Especialidad |
62
- |---------|---------|---------|--------------|
63
- | **Technical Writer** | [technical-writer.md](../personas/technical-writer.md) | `/writer` | Documentación |
64
- | **UX/UI Designer** | [ux-ui-designer.md](../personas/ux-ui-designer.md) | `/ux` | Diseño, a11y |
65
-
66
- ### Metodologías
67
-
68
- | Metodología | Archivo | Trigger | Especialidad |
69
- |---------|---------|---------|--------------|
70
- | **BMAD Methodology** | [bmad-methodology](../skills/bmad-methodology/SKILL.md) | `/bmad` | Scale-Adaptive Intelligence, kickoff |
71
- | **SWE-Agent** | [swe-agent](../skills/swe-agent/SKILL.md) | `/swe` | Resolución autónoma de issues |
72
- | **Spec-Driven Dev** | [spec-driven-dev](../skills/spec-driven-dev/SKILL.md) | `/spec-dev` | Pipeline SPECIFY→PLAN→TASKS→IMPL→VERIFY |
73
-
74
- ---
75
-
76
- ## 📋 Workflows (13 Total)
77
-
78
- | Workflow | Archivo | Trigger | Nivel | Uso |
79
- |----------|---------|---------|-------|-----|
80
- | **SPEC DRIVEN** | [spec-driven.md](../workflows/spec-driven.md) | `/spec` | 2-4 | ⭐ Desarrollo completo |
81
- | New Automation | [new-automation.md](../workflows/new-automation.md) | `/new-auto` | 2-3 | Backend + n8n |
82
- | New AI Agent | [new-agent-ia.md](../workflows/new-agent-ia.md) | `/new-agent` | 2-3 | Crear agente IA |
83
- | Bugfix Backend | [bugfix-backend.md](../workflows/bugfix-backend.md) | `/fix` | 1-2 | Arreglar bugs |
84
- | Optimize Performance | [optimize-performance.md](../workflows/optimize-performance.md) | `/perf` | 2-3 | Optimización |
85
- | Resolve GitHub Issue | [resolve-github-issue.md](../workflows/resolve-github-issue.md) | `/issue` | 1-3 | Issues automáticos |
86
- | Security Review | [security-review.md](../workflows/security-review.md) | `/sec-review` | 2-4 | Auditoría |
87
- | Generate PRD | [generate-prd.md](../workflows/generate-prd.md) | `/prd` | 2 | Documentos de producto |
88
- | Ideation | [ideation.md](../workflows/ideation.md) | `/brainstorm` | 1-2 | Ideación |
89
- | New Feature | [new-feature.md](../workflows/new-feature.md) | `/feature` | 2-3 | Features nuevos |
90
- | Testing Strategy | [testing-strategy.md](../workflows/testing-strategy.md) | `/test-plan` | 2 | Estrategia de tests |
91
- | Third Party Integration | [third-party-integration.md](../workflows/third-party-integration.md) | `/integrate` | 2-3 | Integraciones |
92
- | Documentation | [documentation.md](../workflows/documentation.md) | `/docs` | 1-2 | Documentar |
93
-
94
- ---
95
-
96
- ## 📏 Rules (9 Total)
97
-
98
- | Regla | Archivo | Prioridad | Descripción |
99
- |-------|---------|-----------|-------------|
100
- | **Documentation** | [documentation.md](../rules/documentation.md) | ⚠️ CRÍTICA | Documentar cambios siempre |
101
- | Stack | [stack.md](../rules/stack.md) | Alta | Stack tecnológico |
102
- | Workflow | [workflow.md](../rules/workflow.md) | Alta | Flujo de trabajo |
103
- | Code Style | [code-style.md](../rules/code-style.md) | Alta | Guías de estilo |
104
- | Agents IA | [agents-ia.md](../rules/agents-ia.md) | Alta | Reglas para agentes |
105
- | Automations n8n | [automations-n8n.md](../rules/automations-n8n.md) | Media | n8n patterns |
106
- | API Design | [api-design.md](../rules/api-design.md) | Media | Diseño de APIs |
107
- | Security | [security.md](../rules/security.md) | Alta | Seguridad |
108
- | Testing | [testing.md](../rules/testing.md) | Alta | Estrategias de testing |
109
-
110
- ---
111
-
112
- ## ✅ Checklists (5 Niveles)
113
-
114
- | Nivel | Archivo | Tiempo | Confirmación |
115
- |-------|---------|--------|--------------|
116
- | Level 0: Trivial | [level-0-trivial.md](../checklists/level-0-trivial.md) | <5 min | No |
117
- | Level 1: Small | [level-1-small.md](../checklists/level-1-small.md) | 5-30 min | No |
118
- | Level 2: Medium | [level-2-medium.md](../checklists/level-2-medium.md) | 30m-2h | Sí |
119
- | Level 3: Complex | [level-3-complex.md](../checklists/level-3-complex.md) | 2-8h | Sí + Artefactos |
120
- | Level 4: Enterprise | [level-4-enterprise.md](../checklists/level-4-enterprise.md) | 8h+ | Governance |
121
-
122
- ---
123
-
124
- ## 📄 Templates (SPEC DRIVEN)
125
-
126
- | Template | Archivo | Cuándo Usar |
127
- |----------|---------|-------------|
128
- | **PROJECT_KICKOFF.md** | [PROJECT_KICKOFF.md](../templates/PROJECT_KICKOFF.md) | ⭐ **INICIO**: Entry point para proyectos nuevos |
129
- | **spec.yaml** | [spec.yaml](../templates/spec.yaml) | Fase 1: Especificación |
130
- | **plan.yaml** | [plan.yaml](../templates/plan.yaml) | Fase 2: Plan de implementación |
131
- | **tasks.yaml** | [tasks.yaml](../templates/tasks.yaml) | Fase 3: Tasks ejecutables |
132
- | **session.yaml** | [session.yaml](../templates/session.yaml) | Estado persistente del proyecto |
133
- | **checkpoint.yaml** | [checkpoint.yaml](../templates/checkpoint.yaml) | Auto-backups de estado |
134
- | Agent Python | [agent-python/](../templates/agent-python/) | Scaffold para agentes IA |
135
- | Backend Python | [backend-python/](../templates/backend-python/) | Scaffold para backend FastAPI |
136
- | Frontend React | [frontend-react/](../templates/frontend-react/) | Scaffold para frontend React |
137
- | Database | [database/](../templates/database/) | Esquemas de DB |
138
-
139
- **Flujo único**: `PROJECT_KICKOFF.md` → `spec.yaml` → `plan.yaml` → `tasks.yaml` → CODE
140
-
141
- ---
142
-
143
- ## ⚙️ Configuration
144
-
145
- | Config | Archivo | Descripción |
146
- |--------|---------|-------------|
147
- | Settings | [settings.yaml](../config/settings.yaml) | Configuración global |
148
- | Levels | [levels.yaml](../config/levels.yaml) | Sistema de niveles |
149
- | Tools | [tools.yaml](../config/tools.yaml) | Registry de herramientas |
150
- | Tools Extended | [tools-extended.yaml](../config/tools-extended.yaml) | Tools adicionales |
151
- | Commands | [commands.yaml](../config/commands.yaml) | Aliases de comandos |
152
- | Models | [models.yaml](../config/models.yaml) | Configuración de LLMs |
153
-
154
- ---
155
-
156
- ## 🔍 "What to Read When..."
157
-
158
- | Situación | Único Archivo a Leer |
159
- |-----------|---------------------|
160
- | **Proyecto nuevo (desde cero)** | `templates/PROJECT_KICKOFF.md` → completar → el agente hace el resto |
161
- | **Proyecto existente + LMAgent** | `AGENTS.md` (entry point) |
162
- | **Feature nuevo (L2+)** | Ejecutar `/spec [nombre]` |
163
- | **Bug fix rápido** | `workflows/bugfix-backend.md` |
164
- | **No sé qué persona usar** | Usar `/orch` (Orchestrator decide) |
165
-
166
- ### Flujo Único para Proyectos Nuevos
167
-
168
- ```
169
- DESARROLLADOR AGENTE
170
- ──────────── ──────
171
-
172
-
173
- Crear PROJECT_KICKOFF.md
174
- (5-10 minutos)
175
-
176
-
177
- Abrir en IDE ─────────────────────────────▶ Detecta PROJECT_KICKOFF.md
178
-
179
-
180
- Ejecuta /spec workflow
181
-
182
-
183
- spec.yaml (← Aprobación)
184
-
185
-
186
- plan.yaml (← Aprobación)
187
-
188
-
189
- tasks.yaml
190
-
191
-
192
- CÓDIGO + TESTS
193
-
194
-
195
- PROYECTO LISTO ✅
196
- ```
197
-
198
- ---
199
-
200
- ## 🗺️ Relationship Map
201
-
202
- ```
203
- ┌─────────────┐
204
- │ AGENTS.md │ ← Main Entry Point
205
- └──────┬──────┘
206
-
207
- ┌────────────────────┼────────────────────┐
208
- │ │ │
209
- ▼ ▼ ▼
210
- ┌───────────┐ ┌───────────┐ ┌───────────┐
211
- │ personas │ │ workflows │ │ rules │
212
- │ (18) │ │ (13) │ │ (9) │
213
- └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
214
- │ │ │
215
- │ ┌──────┴──────┐ │
216
- │ │ │ │
217
- ▼ ▼ ▼ ▼
218
- ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
219
- │ templates │ │ checklists│ │ config │ │ docs │
220
- │ (8) │ │ (5) │ │ (6) │ │ (4) │
221
- └───────────┘ └───────────┘ └───────────┘ └───────────┘
222
- ```
223
-
224
- ---
225
-
226
- *LMAgent Framework v3.0 (SPEC+LM)*
227
- *Navigation Index - Updated 2026-01*
1
+ # 🗺️ Navigation Index
2
+
3
+ ## 📜 Rules (Governance)
4
+ - [00-master.md](../rules/00-master.md) - **Start Here**
5
+ - [01-workflow.md](../rules/01-workflow.md)
6
+ - [05-testing.md](../rules/05-testing.md)
7
+ - [10-git-flow.md](../rules/10-git-flow.md)
8
+
9
+ ## 📚 Documentation (Manuals)
10
+ - [Getting Started](getting-started.md)
11
+ - [Commands Reference](commands.md)
12
+ - [Usage Guide](usage-guide.md)
13
+ - [Customization](customization-guide.md)
14
+
15
+ ## 🧠 Memory (Context)
16
+ - [Project Identity](../memory/01-project.md)
17
+ - [Active Context](../memory/04-active-context.md)
@@ -1,113 +1,22 @@
1
- # Guía de Uso Completa de LMAgent
1
+ # 📖 LMAgent General Usage Guide
2
2
 
3
- Esta guía detalla cómo sacar el máximo provecho al framework LMAgent en tu día a día.
3
+ ## 1. Filosofía
4
+ LMAgent convierte tu IDE en una agencia de desarrollo de software completa. No hablas con un "chatbot", hablas con **Ingenieros Especialistas**.
4
5
 
5
- ## Flujo de Trabajo Mental
6
+ ## 2. Flujo de Trabajo (The Loop)
7
+ Todo trabajo sigue este ciclo:
6
8
 
7
- Cuando le pidas algo al agente, sigue este patrón mental para obtener los mejores resultados:
9
+ 1. **Activación**: Usas un Trigger (`/dev`, `/pm`) o el Agente detecta la tarea.
10
+ 2. **Contexto**: El Agente lee `AGENTS.md` y `active_context.md`.
11
+ 3. **Planificación**: El Agente propone un plan (si es complejo).
12
+ 4. **Ejecución**: El Agente usa herramientas (`read_file`, `run_command`).
13
+ 5. **Memoria**: Al terminar, el Agente actualiza `.agents/memory/`.
8
14
 
9
- 1. **¿QUIÉN debe hacerlo?** → Selecciona la Persona (`/dev`, `/pm`, `/arch`)
10
- 2. **¿QUÉ tan complejo es?** Define el Nivel (0-4)
11
- 3. **¿CÓMO debe hacerlo?** Selecciona un Workflow o Regla
15
+ ## 3. Mejores Prácticas
16
+ - **Sé explícito**: "Actúa como `/front` y crea el componente X".
17
+ - **Usa la Memoria**: Si algo cambia en el negocio, actualiza `05-product-state.md`.
18
+ - **Validación**: Siempre pide al agente que verifique su trabajo (`/test`).
12
19
 
13
- ---
14
-
15
- ## 1. Trabajando con Personas
16
-
17
- Las personas no son solo "prompts"; son contextos completos con instrucciones específicas.
18
-
19
- ### Cómo activarlas
20
- Simplemente menciónalas en el chat o usa su trigger:
21
-
22
- > "Actúa como **/product-manager** para analizar este requerimiento."
23
- > "Hola **/arch**, necesito diseñar un nuevo microservicio."
24
-
25
- ### Cuándo cambiar de persona
26
- Es común cambiar de persona durante una tarea compleja:
27
-
28
- 1. **Inicio**: `/pm` analiza el pedido y crea User Stories.
29
- 2. **Diseño**: `/arch` revisa las stories y define la estructura de DB y API.
30
- 3. **Desarrollo**: `/dev` toma el diseño e implementa el código.
31
- 4. **Revisión**: `/qa` escribe los tests para validar el código.
32
- 5. **Prompting**: `/prompt` ajusta el system prompt del agente creado.
33
- 6. **Cierre**: `/tech-writer` actualiza la documentación.
34
-
35
- ---
36
-
37
- ## 2. El Sistema de Niveles (The Thinking Process)
38
-
39
- El error #1 de los agentes es "correr a escribir código" sin entender el problema. Los niveles fuerzan un momento de planificación.
40
-
41
- ### Tipos de Niveles
42
-
43
- | Nivel | Cuándo usarlo | Comportamiento del Agente |
44
- |-------|---------------|---------------------------|
45
- | **L0 (Trivial)** | Typos, logs, fixes obvios de 1 línea | Ejecuta directo. Sin preámbulos. |
46
- | **L1 (Small)** | Funciones pequeñas, tweaks de UI | Piensa brevemente, confirma, ejecuta. |
47
- | **L2 (Medium)** | Features completos, endpoints nuevos | **STOP & PLAN**. Crea `implementation_plan.md`. Pide OK. |
48
- | **L3 (Complex)** | Refactors grandes, integraciones | Plan extenso. Verifica impactos. Pide revisión de `/arch`. |
49
- | **L4 (Enterprise)** | Migraciones, cambios críticos de seguridad | Plan paranoico. Plan de rollback. Múltiples confirmaciones. |
50
-
51
- ### Cómo usarlos
52
- Dile al agente explícitamente o deja que él clasifique:
53
- > "Esto es una tarea **Level 2**. Haz un plan primero."
54
-
55
- ---
56
-
57
- ## 3. Workflows: Autopistas al Éxito
58
-
59
- Los workflows son "recetas" paso a paso para tareas comunes. Garantizan consistencia.
60
-
61
- ### Workflows más usados
62
-
63
- - **/new-feature**: Para crear algo nuevo de punta a punta.
64
- - **/fix**: Para debugging sistemático (no adivinar).
65
- - **/refactor**: Para mejorar código sin romper nada.
66
- - **/test**: Para generar estrategias de testing.
67
-
68
- ### Cómo invocarlos
69
- > "Usa el workflow **/fix** para arreglar este error en producción."
70
-
71
- ---
72
-
73
- ## 4. Reglas y Documentación Continua
74
-
75
- LMAgent tiene una "memoria muscular" basada en reglas.
76
-
77
- ### Reglas Globales (`.agent/rules/`)
78
- Aplican a todos los proyectos. Ej: "Siempre usar English para nombres de variables".
79
-
80
- ### Reglas de Proyecto (`.agent/rules/project.md`)
81
- Específicas de ESTE proyecto. Ej: "Los endpoints deben empezar con `/api/v1`".
82
-
83
- ### La Regla de Oro: Documentación Continua
84
- Si el agente o tú descubren algo nuevo (un truco, un bug recurrente, una decisión de diseño), **DEBEN** escribirlo en una nueva regla o actualizar la documentación.
85
-
86
- > "Agente, aprendimos que la librería X falla con Y. Crea una regla en `rules/tech-stack.md` para evitar esto en el futuro."
87
-
88
- ---
89
-
90
- ## 5. Artefactos (Tu Memoria Externa)
91
-
92
- El agente usa archivos Markdown para mantener el contexto entre sesiones.
93
-
94
- - **`task.md`**: El estado actual. Qué hicimos, qué falta.
95
- - **`implementation_plan.md`**: El plan detallado (para L2+).
96
- - **`tech_spec.md`**: Especificaciones técnicas complejas.
97
- - **`walkthrough.md`**: Guía visual de lo que se construyó (al final).
98
-
99
- **Tip**: Si el agente "olvida" algo, dile que lea los artefactos:
100
- > "Lee `task.md` y dime qué sigue."
101
-
102
- ---
103
-
104
- ## FAQ
105
-
106
- **Q: El agente se queda atascado en un bucle.**
107
- A: Dile "STOP". Pídele que revise sus últimos pasos, identifique el error y proponga un enfoque alternativo. Cambia a L2 para forzar planificación.
108
-
109
- **Q: El agente ignora mis reglas.**
110
- A: Recuérdaselo explícitamente: "Revisa `rules/code-style.md` antes de escribir código". Asegúrate que la regla sea clara y esté en la carpeta correcta.
111
-
112
- **Q: ¿Puedo crear mis propias personas?**
113
- A: ¡Sí! Crea un archivo `.md` en `.agent/personas/` siguiendo el formato de los existentes.
20
+ ## 4. Solución de Problemas
21
+ - **El agente alucina**: Dile "Lee AGENTS.md de nuevo".
22
+ - **El agente ignora reglas**: Verifica que `.agents/rules` estén instaladas en tu carpeta de IDE (`.cursor/rules`, etc.).
@@ -0,0 +1,17 @@
1
+ # 🧠 Project Identity & Core Goals
2
+ > **Update Frequency:** Start of project & Major Pivots.
3
+
4
+ ## 🎯 Mission
5
+ [Define the core purpose of this project in 1 sentence]
6
+
7
+ ## 📦 Core Value Proposition
8
+ - [Value 1]
9
+ - [Value 2]
10
+
11
+ ## 👥 Key Stakeholders / Users
12
+ - **Primary:** [User Persona A]
13
+ - **Secondary:** [User Persona B]
14
+
15
+ ## 🌟 Definition of Success
16
+ 1. [Goal 1]
17
+ 2. [Goal 2]
@@ -0,0 +1,16 @@
1
+ # 💻 Tech Stack & Updates
2
+ > **Update Frequency:** Whenever a new library/tool is added or removed.
3
+
4
+ ## 🛠️ Stack Overview
5
+ | Layer | Technology | Decision Why? |
6
+ |:---|:---|:---|
7
+ | **Frontend** | [React / Vue / Etc] | |
8
+ | **Backend** | [Node / Python / Go] | |
9
+ | **Database** | [Postgres / Mongo] | |
10
+ | **Infra** | [AWS / Vercel] | |
11
+
12
+ ## 📦 Key Dependencies
13
+ - `dependency-1`: [Version] - [Reason]
14
+
15
+ ## 🔄 Architecture Decisions (ADR)
16
+ - **[Date]**: We chose X because Y.
@@ -0,0 +1,12 @@
1
+ # 🧠 System Learnings & Patterns
2
+ > **Update Frequency:** Continuous (After solving tricky bugs or finding good patterns).
3
+
4
+ ## 🐛 Known Bugs / Gotchas
5
+ - [Bug ID]: Description of the issue and how to avoid it.
6
+
7
+ ## 💡 Best Practices Discovered
8
+ - **Pattern A**: When doing X, always use Y because Z.
9
+ - **Optimization**: To improve performance on [Component], do [Action].
10
+
11
+ ## 🚫 Anti-Patterns (What NOT to do)
12
+ - Don't do [Action] because it breaks [Component].
@@ -0,0 +1,14 @@
1
+ # ⚡ Active Context (Current Sprint/Task)
2
+ > **Update Frequency:** DAILY. Read this before starting work.
3
+
4
+ ## 📍 Current Focus
5
+ - **Epic/Feature:** [Name]
6
+ - **Status:** [Planning / In-Progress / Review]
7
+
8
+ ## 🚧 Active Tasks
9
+ 1. [Task A]
10
+ 2. [Task B]
11
+
12
+ ## 📝 Recent Context / Notes
13
+ - [Date]: We decided to change the API response format for [Endpoint].
14
+ - [Date]: User reported bug in [Feature], prioritizing fix.
@@ -0,0 +1,13 @@
1
+ # 📊 Product State & Roadmap
2
+ > **Update Frequency:** Weekly / Per Sprint.
3
+
4
+ ## 🚀 Roadmap
5
+ - [ ] **Phase 1 (MVP)**: [Description]
6
+ - [ ] **Phase 2**: [Description]
7
+
8
+ ## ✅ Completed Features
9
+ - [Feature A] - [Date]
10
+ - [Feature B] - [Date]
11
+
12
+ ## 🧪 Experiments / Features in Testing
13
+ - [Feature C] is currently behind `feature-flag-x`.
@@ -30,14 +30,14 @@ Este documento define el stack tecnológico base y las buenas prácticas para pr
30
30
  | Lenguaje | Versión | Uso |
31
31
  |----------|---------|-----|
32
32
  | Python | 3.14+ | Backends, agentes IA, scripts |
33
- | TypeScript | 6.0+ | Backends Node, frontends |
33
+ | TypeScript | 5.9+ | Backends Node, frontends |
34
34
  | JavaScript | ES2026+ | Scripts, n8n custom nodes |
35
35
 
36
36
  ### Frameworks Backend
37
37
 
38
38
  #### Python (Preferido para APIs y Agentes)
39
39
  ```
40
- FastAPI - Framework web async
40
+ FastAPI (0.128+) - Framework web async
41
41
  SQLModel - ORM + validación (combina SQLAlchemy + Pydantic)
42
42
  Pydantic - Validación de datos
43
43
  Pydantic-Settings - Configuración via env vars
@@ -46,7 +46,7 @@ Uvicorn - Servidor ASGI
46
46
 
47
47
  #### NodeJS/TypeScript (Cuando sea necesario)
48
48
  ```
49
- NestJS - Framework estructurado (preferido)
49
+ NestJS (v11+) - Framework estructurado (preferido)
50
50
  Express - Framework minimalista
51
51
  Prisma - ORM para TypeScript
52
52
  ```
@@ -54,8 +54,8 @@ Prisma - ORM para TypeScript
54
54
  ### Base de Datos
55
55
  | Componente | Tecnología | Uso |
56
56
  |------------|------------|-----|
57
- | Principal | PostgreSQL 18+ | Datos relacionales |
58
- | Cache | Redis 8+ | Cache, sesiones, colas |
57
+ | Principal | PostgreSQL 17+ | Datos relacionales |
58
+ | Cache | Redis 7.4+ | Cache, sesiones, colas |
59
59
  | Colas | Redis Streams | Mensajería async |
60
60
  | Búsqueda | PostgreSQL FTS | Búsqueda de texto |
61
61
 
@@ -247,56 +247,57 @@ DEBUG=true
247
247
  ### Python - requirements.txt base
248
248
  ```
249
249
  # Framework
250
- fastapi>=0.109.0
251
- uvicorn[standard]>=0.27.0
250
+ fastapi>=0.128.0
251
+ uvicorn[standard]>=0.34.0
252
252
 
253
253
  # Database
254
- sqlmodel>=0.0.14
255
- asyncpg>=0.29.0
256
- sqlalchemy[asyncio]>=2.0.0
254
+ sqlmodel>=0.0.24
255
+ asyncpg>=0.30.0
256
+ sqlalchemy[asyncio]>=2.0.36
257
257
 
258
258
  # Validation
259
- pydantic>=2.5.0
260
- pydantic-settings>=2.1.0
259
+ pydantic>=2.10.0
260
+ pydantic-settings>=2.7.0
261
261
 
262
262
  # Redis
263
- redis>=5.0.0
263
+ redis>=5.2.0
264
264
 
265
265
  # HTTP Client
266
- httpx>=0.26.0
266
+ httpx>=0.28.0
267
267
 
268
268
  # Security
269
269
  python-jose[cryptography]>=3.3.0
270
270
  passlib[bcrypt]>=1.7.4
271
271
 
272
272
  # Logging
273
- structlog>=24.1.0
273
+ structlog>=24.4.0
274
274
 
275
275
  # Dev
276
- pytest>=8.0.0
277
- pytest-asyncio>=0.23.0
278
- pytest-cov>=4.1.0
279
- ruff>=0.2.0
276
+ pytest>=9.0.0
277
+ pytest-asyncio>=0.25.0
278
+ pytest-cov>=6.0.0
279
+ ruff>=0.9.0
280
+
280
281
  ```
281
282
 
282
283
  ### Node - package.json base
283
284
  ```json
284
285
  {
285
286
  "dependencies": {
286
- "@nestjs/common": "^10.0.0",
287
- "@nestjs/core": "^10.0.0",
288
- "@nestjs/platform-express": "^10.0.0",
289
- "@prisma/client": "^5.0.0",
290
- "ioredis": "^5.3.0",
291
- "class-validator": "^0.14.0",
287
+ "@nestjs/common": "^11.0.0",
288
+ "@nestjs/core": "^11.0.0",
289
+ "@nestjs/platform-express": "^11.0.0",
290
+ "@prisma/client": "^6.0.0",
291
+ "ioredis": "^5.4.0",
292
+ "class-validator": "^0.14.1",
292
293
  "class-transformer": "^0.5.1"
293
294
  },
294
295
  "devDependencies": {
295
- "@types/node": "^20.0.0",
296
- "typescript": "^5.0.0",
297
- "jest": "^29.0.0",
298
- "eslint": "^8.0.0",
299
- "prettier": "^3.0.0"
296
+ "@types/node": "^22.0.0",
297
+ "typescript": "^5.7.0",
298
+ "jest": "^29.7.0",
299
+ "eslint": "^9.0.0",
300
+ "prettier": "^3.4.0"
300
301
  }
301
302
  }
302
303
  ```
@@ -308,14 +309,14 @@ ruff>=0.2.0
308
309
  ### Dockerfile Python (multi-stage)
309
310
  ```dockerfile
310
311
  # Build stage
311
- FROM python:3.11-slim as builder
312
+ FROM python:3.14-slim as builder
312
313
 
313
314
  WORKDIR /app
314
315
  COPY requirements.txt .
315
316
  RUN pip install --no-cache-dir --user -r requirements.txt
316
317
 
317
318
  # Production stage
318
- FROM python:3.11-slim
319
+ FROM python:3.14-slim
319
320
 
320
321
  WORKDIR /app
321
322
  COPY --from=builder /root/.local /root/.local
@@ -35,7 +35,7 @@ mypy app/
35
35
  ### Configuración (pyproject.toml)
36
36
  ```toml
37
37
  [tool.ruff]
38
- target-version = "py311"
38
+ target-version = "py312"
39
39
  line-length = 88
40
40
  select = [
41
41
  "E", # pycodestyle errors