Workspace agentico multiplataforma

Especificación mínima para que distintos agentes (Cursor, Claude Code, Gemini, Codex/ChatGPT, otros) compartan contexto estable, reglas, skills, workflows y notas por plataforma, sin formatos propietarios pesados.

Estructura principal

| Ruta | Rol | |------|-----| | AGENTS.md | Entrypoint universal: orden de carga y prioridades | | .agent/rules/ | Restricciones (un archivo = un tema); incluye stable-* y level-* tras init | | .agent/skills/ | Conocimiento reutilizable (modular por carpeta, p. ej. skills/nextjs/routing.md) | | .agent/detect-manifest.json | Última detección de stack (generado por el CLI) | | registry/ | Fingerprints de tecnologías, arquetipos y resolución de skills | | catalog/ | Markdown neutro y plantillas copiadas o renderizadas por init / sync | | knowledge/ | Packs JSON curados por stack y major (fuente para skills generadas) | | .agent/workflows/ | Secuencias operativas | | .agent/context/ | Contexto estable del proyecto | | .agent/memory/ | Estado mutable (tarea actual, incidencias, notas) | | .agent/platform/ | Adaptaciones y matices por herramienta | | examples/ | Prompts y salidas de ejemplo | | docs/agents-contract.md | Contrato global del workspace |

Tres niveles de conocimiento

1. Stable (universal): reglas transversales (stable-*.md desde catalog/rules/stable/ en init).
2. Stack: skills del catálogo + skills generadas desde knowledge/ + plantillas (catalog/templates/skills/).
3. Project: .agent/context/ y .agent/memory/ (no los sobrescribe el CLI salvo bloques marcados en stack.md).

Ver orden de carga en AGENTS.md.

Contexto frente a memoria

• context/: verdad de larga vida (stack, ADR, negocio). Cambiar con el mismo rigor que el código.
• memory/: corto plazo y coordinación; puede editarse en paralelo entre sesiones. Hasta contar con locking o logs append-only (fases futuras), conviene ser explícito en el PR sobre quién actualiza qué.

Cómo probar manualmente (checklist)

En cada herramienta, abre el repo y pide al agente que siga el orden de carga de AGENTS.md para una tarea pequeña de prueba (por ejemplo, validar que el script de estructura pasa).

• [ ] Cursor: reglas en .cursor/rules/ deben remitir a AGENTS.md; adjunta @AGENTS.md y una skill si hace falta.
• [ ] Claude Code: lee AGENTS.md + .agent/platform/claude.md; opcionalmente enlaza un archivo de .claude/skills/ si existe.
• [ ] Gemini: lee AGENTS.md + .agent/platform/gemini.md + GEMINI.md si está presente.
• [ ] ChatGPT / Codex: pega el contenido de AGENTS.md y solo los fragmentos necesarios de .agent/; ver .agent/platform/codex.md.

Validación local

./scripts/validate-structure.sh

CLI acc-agent-workspace

Tras npm install y compilación:

npm run build
npx acc-agent-workspace install -y
npx acc-agent-workspace install --dry-run
npx acc-agent-workspace init --dry-run
npx acc-agent-workspace init --level strict
npx acc-agent-workspace sync --dry-run
npx acc-agent-workspace sync --full
npx acc-agent-workspace doctor

También puedes usar node dist/cli.js … o el script npm npm run acc-agent-workspace -- install.

Equivalente a npx autoskills

| autoskills | acc-agent-workspace | |------------|---------------------| | npx autoskills | npx acc-agent-workspace install | | npx autoskills -y | npx acc-agent-workspace install -y | | npx autoskills --dry-run | npx acc-agent-workspace install --dry-run | | Skills en IDE (~/.cursor/skills) | Workspace portable en .agent/skills/ + AGENTS.md | | skills-lock.json | .agent/agent-skills-lock.json (SHA-256) |

Diferencia principal: el catálogo es propio y multi-IDE (no descarga skills de terceros salvo referencias opt-in con --with-upstream).

• install: flujo recomendado (como autoskills): escanea, muestra stack/skills, materializa .agent/, adapters por IDE detectado, lock de integridad. Flags: -y, --dry-run, --with-upstream, --force.
• init: primera materialización: skills estáticas del catálogo, reglas stable-*, level-*, bloque automático en context/stack.md, manifiesto con resolvedVersions y knowledgePacks, skills generadas desde packs cuando aplique. Opción --emit-adapters cursor,claude,gemini o all para punteros ligeros por plataforma.
• sync: vuelve a detectar stack y versiones, regenera manifiesto, bloque de stack y skills generadas (generated-best-practices.md). Con --full también recopía el catálogo como init. --dry-run solo muestra el resumen.
• doctor: coherencia del manifiesto, archivos esperados, aviso de drift si la major del proyecto supera el knowledge pack disponible, comprobación de marcas generatedBy y verificación de .agent/agent-skills-lock.json.

Cuando el paquete esté publicado en npm:

npx acc-agent-workspace@latest init
npx acc-agent-workspace@latest sync
npx acc-agent-workspace@latest doctor

Publicar en npm

1. Comprueba el nombre (si acc-agent-workspace ya existe, usa un scope, p. ej. @tu-org/acc-agent-workspace, y cambia el campo name en package.json; para scopes añade "publishConfig": { "access": "public" }).
2. Metadatos opcionales: añade en package.json los campos repository, bugs y homepage con la URL real de tu repo para que la ficha en npmjs.com enlace bien.
3. Compilar y probar: npm run build && npm test.
4. Inicio de sesión: npm login (usuario, contraseña, OTP si tienes 2FA).
5. Publicar: desde la raíz del repo, npm publish (el script prepack ejecuta npm run build y el tarball incluirá dist/, registry/, catalog/, knowledge/, README.md y LICENSE).
6. Verificación: en otro directorio, npx acc-agent-workspace@<version> doctor --cwd . o npx acc-agent-workspace init --dry-run.

Las versiones nuevas suben el campo version en package.json y vuelves a ejecutar npm publish.

Roadmap (resumen)

• Fase 1 (actual): estructura portable, contrato, validación bash y CLI init / sync / doctor con registry, knowledge packs y catálogo modular.
• Fase 2: acc-agent-workspace load (concatenación selectiva / compilador de prompt) y optimización de tokens.
• Fase 3: memoria avanzada, orquestación multi-agente, MCP, adaptadores dinámicos por plataforma.

Métricas sugeridas (manuales al inicio)

• Tiempo hasta el primer PR útil de una persona nueva usando solo AGENTS.md + .agent/.
• Prompts repetidos evitados (encuesta breve semanal).
• Consistencia: checklist de arquitectura en PR (¿se tocó solo lo necesario? ¿tests?).
• Compatibilidad: tabla modelo ↔ notas en .agent/platform/ actualizada cuando cambie el comportamiento de un cliente.