Imported from NezerkC/mk-40-mvp1.2 (AGENTS.md). Install upstream with npx skills add NezerkC/mk-40-mvp1.2. Copyright stays with the author.

🧠 J.A.R.V.I.S. MARK-40 — Agent Instructions

Propósito: Instrucciones para agentes IA que trabajen en este proyecto. Prioridad sobre: configuraciones globales de agente. Primera regla: leer MAINTENANCE_GUIDE.md completo antes de cualquier cambio.

📋 Ficha del Proyecto

🚦 Detección de Tipo de Cambio

Antes de empezar CUALQUIER trabajo, identificar el tipo:

🔍 Cómo detectar automáticamente

# Pseudocódigo para determinar el tipo:
if change_adds_new_capability():
    type = "feature"
elif change_fixes_bug_or_crash():
    type = "fix"
elif change_restructures_without_new_behavior():
    type = "refactor"
elif change_is_only_docs():
    type = "docs"
elif change_is_deps_or_ci():
    type = "chore"
elif change_is_security():
    type = "security"

Regla de oro: cuando tengas dudas entre feature y refactor, es feature. Si toca archivos de UI, actions, services, providers, o engine → probablemente es feature.

📐 Release Flow

Versionado Semver

v<MAJOR>.<MINOR>.<PATCH>

MAJOR: breaking changes (cambia API de tools, providers, o config)
MINOR: nuevas features (backward-compatible)
PATCH: bug fixes (backward-compatible)

Cuándo crear un release

1. Se completó un hito del changelog
2. Los cambios están en main
3. Todos los tests pasan en CI
4. El changelog se actualizó con lo nuevo

Cómo crear un release tag

git tag -a v<version> -m "v<version>: <descripción breve>"
git push origin v<version>

Tags siempre anotados (-a), nunca ligeros.

🧱 SDD (Spec-Driven Development)

SDD es obligatorio para cambios marcados como FEATURE, REFACTOR (recomendado), y SECURITY.

Flujo completo:

/sdd-new <nombre-del-cambio>    → Explora y crea proposal
/sdd-ff <nombre>                 → Fast-forward: spec → design → tasks
/sdd-continue [nombre]           → Ejecuta la siguiente fase disponible
/sdd-verify [nombre]             → Valida contra specs
/sdd-archive [nombre]            → Cierra el cambio

Para cambios triviales (1 archivo, typo, bugfix simple de <10 líneas) SDD no es necesario.

🧱 Capas del Sistema

┌──────────────────────────────────────────────────┐
│                    TOOLS                          │  ← Bridge LLM ↔ Sistema
│  tools/declarations.py      (schemas para LLM)    │
│  tools/chat_tools/*.py      (BaseTool impls)      │
│  tools/registry.py          (auto-descubrimiento) │
├──────────────────┬───────────────────────────────┤
│    ACTIONS       │          SERVICES              │
│   (directas)     │      (dominio complejo)        │
├──────────────────┴───────────────────────────────┤
│  actions/*.py              services/*/             │
│  · browser_control.py      · email/gmail_client   │
│  · file_controller.py      · git/git_client       │
│  · screen_processor.py     · skills/manager.py    │
│  · web_search.py           · mcp/integration.py   │
│  · weather_report.py       · database/             │
│  · etc.                    · docker/, media/ etc.  │
└──────────────────────────────────────────────────┘

Reglas estrictas

1. tools/ NO tiene lógica de negocio — solo parsea args y llama actions/services
2. actions/ NO llama services/ directamente desde tools — la tool es el bridge
3. services/ NO importa tools/ — es al revés, las tools importan services
4. Si una action necesita estado persistente → convertir a service
5. Si un service tiene 1 función y no necesita auth → puede ser action

✅ Checklist Pre-acción para el Agente

• ¿Leíste MAINTENANCE_GUIDE.md?
• ¿Identificaste el tipo de cambio?
• Si es FEATURE: ¿ejecutaste SDD primero (/sdd-new)?
• ¿Estás en la rama correcta?
• ¿Corriste python -m pytest tests/ -v --tb=short?
• Si cambiaste tools: ¿actualizaste tools/declarations.py?
• Si agregaste service: ¿tiene is_available() y is_configured()?
• Commit message: ¿sigue conventional commits?

🔗 Archivos Críticos (NO modificar sin permiso)