@imolko/ultra-agent

Metodología ultra como paquete versionado: skills canónicos, registro ADR A/T/P, extensiones de pi y CLI (install/update/status/ship).

Packages

Package details

extensionskill

Install @imolko/ultra-agent from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@imolko/ultra-agent
Package
@imolko/ultra-agent
Version
0.1.1
Published
Oct 5, 2026
Downloads
408/mo · 408/wk
Author
yohanyflores
License
MIT
Types
extension, skill
Size
803.8 KB
Dependencies
6 dependencies · 1 peer
Pi manifest JSON
{
  "skills": [
    "./skills"
  ],
  "extensions": [
    "./pi/extensions"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@imolko/ultra-agent

La metodología ultra como paquete versionado: el conjunto canónico de skills, el registro de ADRs A/T/P, las extensiones de pi y un CLI para instalarla, actualizarla y mantenerla sin deriva.

@imolko/ultra-agent es la fuente única de la metodología (A-052). Los repositorios consumidores la instalan y la leen desde aquí, en lugar de duplicar skills, ADRs o guardrails.

Requisitos

  • Node.js ≥ 20.
  • pi coding agent (peer dependency) para usar los skills y las extensiones.

Instalación

# instala la metodología en el repositorio actual
npx @imolko/ultra-agent install

O como dependencia de desarrollo:

npm install --save-dev @imolko/ultra-agent

install materializa en el consumidor:

  • un espejo de solo lectura de los ADRs A/T/P (+ ADR-0000 y el gate de consistencia),
  • el pointer hub docs/agents/repo-config.md con los punteros del repo (adr_dir, domain_dir, issue_language, tracker_cli, ship_cmd),
  • el bloque ## Agent skills que ancla AGENTS.md / CLAUDE.md al hub,
  • el manifiesto docs/agents/manifest.json (versión instalada + hashes) que permite detectar deriva.

CLI

El binario es ultra-agent.

Comando Qué hace
ultra-agent install [--dest <dir>] Materializa el espejo A/T/P + gate, el pointer hub y el manifiesto.
ultra-agent update [--dest <dir>] [--reset] Reconcilia el espejo y falla ante deriva; --reset respalda y restaura.
ultra-agent status [--dest <dir>] Reporta la versión instalada y si hay deriva.
ultra-agent init-lint [--dest <dir>] Escribe el andamiaje de lint del consumidor (eslint.config.mjs + .pi/qa-guardrail.json) sin sobrescribir lo existente.
ultra-agent ship <flags> Dispara el pipeline ship sobre un spec y sus issues hijos (A-039).
ultra-agent version Imprime la versión del paquete.
ultra-agent help Muestra la ayuda.

--dest <dir> apunta a otro directorio (por defecto, el directorio actual).

Qué incluye

Skills canónicos

19 skills que el agente descubre por la description de cada SKILL.md (A-034):

code-review, codebase-design, configure-repo, diagnose-bug, domain-modeling, grill-me, i-have-an-idea, implement, research, ship, spike, tdd, to-specs, to-tasks, triage, ultra-generator, wayfinder, workflow, writing-for-agents.

Registro de ADRs

Decisiones de arquitectura en tres tiers, más el meta-ADR de proceso:

  • A — fundacional: decisiones agnósticas al lenguaje.
  • T — TypeScript: ecosistema TypeScript/Zod/Node.js.
  • P — Python: ecosistema Python.
  • ADR-0000: proceso y formato de los ADRs.

El espejo se copia como solo lectura: el tier de proyecto y los READMEs de dominio del consumidor nunca se tocan.

Extensiones de pi

  • handoff — genera un documento de traspaso de contexto, renombra la sesión y arranca una sesión nueva sembrada con el handoff.
  • qa-guardrail — el bucle de linting del agente pi (A-045, A-049): lintea solo el delta de cada edición y corta tras N fallos consecutivos.

Versionado y canales

La versión se deriva de los tipos de Conventional Commits (A-033): feat → minor, fix → patch, breaking → major.

  • develop publica el canal beta.
  • main publica el canal latest (estable).

La publicación usa Trusted Publishing (OIDC) en runners alojados, con fallback automático por staging (token de mínimo privilegio + aprobación 2FA) en runners propios (T-025). Las etiquetas git se reconcilian desde el gitHead del registry.

Desarrollo

npm install
npm test             # vitest
npm run typecheck    # tsc --noEmit
npm run gate         # gate de consistencia del registro ADR
npm run build        # compila a dist-node/ y copia assets

Enlaces

Licencia

MIT © Imolko