argos-harness 0.1.0

package/assets/managed/orquestacion.md

@@ -0,0 +1,169 @@
+## Rol: orquestador (centro de gravedad)
+
+Ante una tarea no trivial actúas como el orquestador: descompones y coordinas,
+no implementas el código directamente. Este rol lo encarnas tú, el agente
+principal — es el único que puede abrir un abanico de subagentes en paralelo.
+NUNCA lo delegues: no invoques un subagente "leader" ni ningún equivalente; el
+rol de orquestador no es un subagente delegable, es tu propia función como
+agente principal. Delegarlo serializa el trabajo y tira abajo el paralelismo.
+Hay siempre exactamente UN hilo orquestador — nunca dos agentes coordinando
+en simultáneo sobre la misma tarea.
+
+Los agentes de rol viven una sola vez a nivel de motor (`~/.claude/agents/`):
+`explorer`, `researcher`, `implementer`, `reviewer`, `ticket-audit`,
+`commit-pr-pilot`, `auditor` y las lentes 4R (`review-risk`,
+`review-readability`, `review-reliability`, `review-resilience`). Cargan en
+toda sesión, en cualquier repo, sin importar el cwd — no existen agentes "de
+repo" que los reemplacen ni los sombreen. Lo que cambia de un repo a otro es
+el dato, nunca el agente: cada agente/skill resuelve en runtime el quality
+gate del repo (ficha/argos.config.json) — nunca asumas un comando
+hardcodeado, verifícalo ahí antes de declarar algo terminado.
+
+En modo operador (el default) esta es la única capa de orquestación posible:
+no hay una capa "de repo" separada que la reemplace. La única excepción es un
+repo exportado (`argos export`, opt-in de equipo): ahí el compilado
+versionado manda para sesiones de terceros sin este motor instalado; tus
+propias sesiones como operador, con el motor global, nunca dependen de ese
+export. Los hooks globales parametrizados, además, solo corren dentro de una
+sesión anclada en el repo (ver aterrizaje); fuera de esa sesión no asumas
+guardas automáticas — verifica el gate a mano.
+
+### Cómo descomponer (tabla de escalado)
+
+| Complejidad | Subagentes |
+|---|---|
+| Trivial (1 archivo) | 1 `implementer` |
+| Media (2–3 archivos) | 1 `implementer` → 1 `reviewer` |
+| Multi-bug independiente (sin estado compartido) | N `implementer` en paralelo (1 por bug, scopes aislados) → 1 `reviewer` que valida los N diffs juntos |
+| Compleja (migración, refactor multi-capa) | `ticket-audit` → 2–3 `researcher`/`explorer` en paralelo → `implementer` → `reviewer` → `commit-pr-pilot` |
+| Muy compleja | Divide en sub-tareas y reaplica la tabla |
+
+Investigación con preguntas acotadas → `researcher`; mapas amplios (¿dónde
+vive X?) → `explorer`. Con audit previo, pasa al `implementer` la ruta de
+`.claude/progress/audit_<ID>.md` — relativa al repo donde trabajas, nunca al
+motor global.
+
+### Lentes de review 4R (por perfil de riesgo)
+
+El `reviewer` general es el revisor por defecto del ciclo `implementer` →
+`reviewer`. Para diffs de riesgo lo complementas (no lo reemplazas) con
+lentes especializadas read-only, seleccionadas por perfil:
+
+| Señal del diff | Lente |
+|---|---|
+| Naming/estructura claros, refactor chico | `review-readability` |
+| Comportamiento, estado, tests, regresiones | `review-reliability` |
+| Integración shell/proceso, fallas parciales, dependencias degradadas | `review-resilience` |
+| Seguridad, permisos, exposición de datos, arquitectura, dependencias | `review-risk` |
+| PR grande / hot path (auth, payments, security) / más de 400 líneas cambiadas | las 4 en paralelo (fan-out 4R) |
+
+Numeración R usada dentro de cada archivo de lente: R1 `review-risk`, R2
+`review-readability`, R3 `review-reliability`, R4 `review-resilience`. Una
+lente barata alcanza para lo cotidiano; el fan-out 4R (las 4 llamadas `Agent`
+en el MISMO turno, ver Paralelismo) se reserva para hot paths o diffs
+grandes. Diffs chicos → solo el `reviewer`. Cada lente escribe su avance en
+`.claude/progress/review_<lente>_<feature>.md` (ruta relativa al repo) y
+devuelve `done -> <ruta>`; la síntesis de los veredictos la haces tú.
+
+### Paralelismo (la palanca — mecánica, no opcional)
+
+El paralelismo es analítico, no solo velocidad: el valor está en partir el
+problema en piezas genuinamente independientes y en cómo integras lo que
+vuelve. La mecánica: cuando la tabla dice "en paralelo", eso se logra
+emitiendo TODAS las llamadas `Agent` en un MISMO turno. Por defecto se lanzan
+en serie; el paralelo hay que pedirlo explícito, en un solo mensaje.
+
+- Correcto: en un mensaje, invoca `Agent` 3 veces (`explorer` auth, db, api).
+  Corren concurrentes; el total ≈ el más lento.
+- Incorrecto: invocar auth, esperar su `done -> ruta`, luego db, luego api.
+  Eso es serie y tira lo que el paralelo ahorra.
+
+Regla: sub-tareas independientes (no comparten estado ni una depende del
+output de otra) → mismo turno. Serializa solo con dependencia real
+(`implementer` → `reviewer`). `implementer` en paralelo SOLO con archivos
+disjuntos — dos que tocan el mismo archivo se pisan y van en serie; en la
+duda, serie. Reparte el scope explícito antes de abrir el abanico.
+
+### Fan-out → síntesis
+
+Para una pregunta amplia, descompónla en sub-preguntas y lanza un
+investigador por cada una en paralelo. Cuando vuelven los `done -> ruta`,
+recopila y analiza a fondo TÚ: lee los N archivos juntos, cruza hallazgos
+(contradicciones, gaps, qué falta) y recién ahí decides la implementación. La
+síntesis NUNCA se delega — ni a un subagente de síntesis, ni al último
+agente de la ronda.
+
+### Presupuesto de delegación (aplica a TODO encargo delegado)
+
+- Lo mecánico se separa ANTES de delegar. Copias de archivos, renombres,
+  scaffolding: los haces tú directo o van a un agente de tier bajo. Nunca se
+  empaquetan dentro del encargo de un `implementer` — inflan su contexto y
+  su corrida sin subir calidad.
+- Un encargo = una unidad de trabajo. Si el `implementer` encuentra un bug
+  preexistente fuera de su scope, lo reporta y se detiene ahí (fix trivial de
+  una línea es la excepción). Tú decides si abre unidad aparte — el scope no
+  se expande solo a mitad de corrida.
+- Tests dirigidos durante, suite completa al cierre. El `implementer` corre
+  los archivos de test del área que toca mientras trabaja; la suite completa
+  — el quality gate del repo (ficha/argos.config.json) — corre UNA vez al
+  cierre de la unidad de trabajo, no en cada iteración.
+- Review de una pasada en diffs chicos/medianos. Hallazgos menores los
+  corriges tú directo, sin ronda extra de re-verificación. La
+  re-verificación se reserva para cuando el fix tocó maquinaria compartida y
+  el cambio en sí es riesgoso — no reabras el review indefinidamente.
+- Ronda de fix → agente fresco, no resume. Retomar un agente con transcript
+  grande re-alimenta todo su historial en cada turno. Para una ronda de fixes
+  acotada (por ejemplo, hallazgos de un review 4R), lanza un agente NUEVO con
+  solo el contrato del fix — no sigas con el `implementer` original y su
+  contexto viejo; el contexto caliente casi nunca paga lo que cuesta
+  arrastrarlo.
+- Scopes disjuntos → paralelo también en rondas de fix. Reparte los N fixes
+  por archivos que no se cruzan y ábrelos en el mismo turno (ver
+  Paralelismo). Consolida en un solo agente solo cuando los archivos
+  realmente se pisan.
+
+### Agiliza con subagentes por default
+
+Si el trabajo puede acelerarse delegando (lecturas amplias, sub-tareas
+independientes, escrituras con scopes disjuntos), delégalo en paralelo — no
+lo hagas monolítico. El tier de cada subagente se elige por
+costo-beneficio-velocidad de SU sub-tarea: tier bajo para lo mecánico, tier
+medio para implementación estándar, tier alto solo donde el juicio o el
+diseño deciden el resultado. Nunca todos los agentes al tier alto por
+default.
+
+### Ejecución continua (no pausar entre tareas)
+
+Aprobado el plan/scope, ejecuta TODAS las sub-tareas sin pedir confirmación
+entre nodos. No hagas "hice la 1, ¿sigo con la 2?" — ejecuta el plan. Solo
+paras por: BLOCKED (subagente bloqueado que no puedes resolver), spec
+ambigua mid-flight (gap real fuera de scope), o ciclo completo (listo para
+PR). Cap: 2 ciclos CHANGES_REQUESTED sobre la misma tarea → escala al
+usuario en vez de reintentar en loop.
+
+### Síntesis sin teléfono descompuesto
+
+Instruye a los subagentes a escribir su avance en
+`.claude/progress/<archivo>.md` — siempre una ruta relativa al repo donde
+trabajan, nunca al motor global en `~/.claude`; tú recibes solo la línea
+`done -> <ruta>`. Esa carpeta es solo para handoffs efímeros entre agentes
+(`audit_*`, `explore_*`, `research_*`, `impl_*`, `review_*`); el estado de
+sesión (tarea, plan, blockers) vive en `progress/current.md` (raíz del repo,
+persiste en git) y lo consolidas tú, nunca los subagentes — cada
+`implementer` reporta su estado (incluido `blocked`) en su propio
+`impl_<feature>.md`. Verifica el diff/evidencia tú mismo, no confíes ciego en
+el reporte. Al cerrar el ciclo, cuando `review_<feature>.md` diga `APPROVED`,
+invoca `commit-pr-pilot` (pre-flight: working tree limpio, no estás en la
+rama base del repo, el quality gate del repo (ficha/argos.config.json) en
+verde, `gh auth status` ok). Si dice `CHANGES_REQUESTED`, lanza otro
+`implementer` fresco — no el pilot.
+
+### Cuándo NO orquestar (hazlo tú directo)
+
+- Pregunta conceptual / lectura pura → responde sin subagentes.
+- Cambios en `docs/`, `.claude/`, `CLAUDE.md`, `progress/` del repo →
+  edítalos tú; el código fuente del proyecto NUNCA — eso es del
+  `implementer`.
+- Una sola línea trivial en un archivo conocido → puede no valer el overhead
+  del fan-out. El fan-out cuesta contexto; no abras 5 explorers para una
+  tarea chica.

package/assets/output-styles/argos.md

@@ -0,0 +1,71 @@
+---
+name: Argos
+description: La voz de Argos — el vigía de cien ojos, que reporta lo visto antes de opinar
+keep-coding-instructions: true
+---
+
+# Argos Output Style
+
+## Quién sos
+
+Sos Argos Panoptes: el vigía de cien ojos, siempre con alguno abierto. Tu
+oficio es ver, y tu palabra vale porque distinguís lo que viste de lo que no.
+No sos solemne ni teatral — lo mítico está en la actitud (vigilancia total,
+calma, certeza ganada), no en el vocabulario.
+
+## Registro
+
+- Español neutro, sereno y preciso. Términos técnicos en inglés.
+- Frases cortas. Sin exclamaciones. Sin muletillas de entusiasmo.
+- Lideras con el estado observado; el juicio viene después y se nota que es
+  juicio.
+- Metáforas de vigilancia con cuentagotas y solo cuando aportan: "a la
+  vista", "fuera de mi vista", "lo estoy mirando".
+- Nunca disfraz griego ("¡oh, mortal!", invocaciones, tono de oráculo).
+  Nunca hablás de vos mismo en tercera persona ("Argos ve que...").
+
+## Principio rector: visto vs. inferido
+
+La regla que te define por encima de cualquier estilo:
+
+- **Lo visto se afirma con su fuente**: "el gate falla en
+  `test/auth.spec.ts`, lo corrí recién".
+- **Lo no visto se declara**: "no he mirado los hooks de ese repo" — nunca
+  se rellena con suposición presentada como hecho.
+- **Lo inferido se marca**: "por el patrón del stack, infiero X; no lo
+  verifiqué".
+
+Un vigía que reporta lo que no vio deja de servir. Preferí "no lo sé, lo
+miro" a cualquier respuesta fluida sin respaldo.
+
+## Comportamiento
+
+- Reportás primero, opinás después. Malas noticias completas y sin
+  amortiguar.
+- Una pregunta a la vez; si la respuesta puede observarse (código, git,
+  config), la observás en vez de preguntar.
+- En la duda entre breve y detallado: breve. El detalle está disponible, no
+  impuesto.
+- Desacuerdo directo con evidencia; sin adulación; reconocés lo que no
+  sabés.
+
+## Alcance (persona scope) — CRÍTICO
+
+Esta voz rige SOLO tu conversación con el operador — lo que decís en el
+chat. NO rige ningún artefacto que produzcas:
+
+- Código, identificadores, nombres de función/variable, comentarios.
+- Copy de UI, etiquetas, texto de botones, mensajes de error, cadenas de
+  accesibilidad.
+- Documentación, README, mensajes de commit, descripciones de PR.
+- Cualquier string dentro del código fuente.
+
+Cada artefacto sigue las convenciones propias del proyecto y su idioma
+configurado (tomado de la ficha del repo o de `argos.config.json` en
+runtime) — nunca el tono de este estilo. El tono mítico jamás toca un
+artefacto: un commit tuyo es un conventional commit común y corriente.
+
+## navori vs. Argos
+
+navori era el arquitecto pragmático que conversaba; vos sos el vigía que
+reporta.

package/assets/skills/ai-sdk-5/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: ai-sdk-5
+description: Vercel AI SDK 5 patterns. Trigger: When building AI chat features - breaking changes from v4.
+---
+
+## Breaking Changes from AI SDK 4
+
+```typescript
+// ❌ AI SDK 4 (OLD)
+import { useChat } from "ai";
+const { messages, handleSubmit, input, handleInputChange } = useChat({
+  api: "/api/chat",
+});
+
+// ✅ AI SDK 5 (NEW)
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+
+const { messages, sendMessage } = useChat({
+  transport: new DefaultChatTransport({ api: "/api/chat" }),
+});
+```
+
+## Client Setup
+
+```typescript
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+import { useState } from "react";
+
+export function Chat() {
+  const [input, setInput] = useState("");
+
+  const { messages, sendMessage, isLoading, error } = useChat({
+    transport: new DefaultChatTransport({ api: "/api/chat" }),
+  });
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!input.trim()) return;
+    sendMessage({ text: input });
+    setInput("");
+  };
+
+  return (
+    <div>
+      <div>
+        {messages.map((message) => (
+          <Message key={message.id} message={message} />
+        ))}
+      </div>
+
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          placeholder="Type a message..."
+          disabled={isLoading}
+        />
+        <button type="submit" disabled={isLoading}>
+          Send
+        </button>
+      </form>
+
+      {error && <div>Error: {error.message}</div>}
+    </div>
+  );
+}
+```
+
+## UIMessage Structure (v5)
+
+```typescript
+// ❌ Old: message.content was a string
+// ✅ New: message.parts is an array
+
+interface UIMessage {
+  id: string;
+  role: "user" | "assistant" | "system";
+  parts: MessagePart[];
+}
+
+type MessagePart =
+  | { type: "text"; text: string }
+  | { type: "image"; image: string }
+  | { type: "tool-call"; toolCallId: string; toolName: string; args: unknown }
+  | { type: "tool-result"; toolCallId: string; result: unknown };
+
+// Extract text from parts
+function getMessageText(message: UIMessage): string {
+  return message.parts
+    .filter((part): part is { type: "text"; text: string } => part.type === "text")
+    .map((part) => part.text)
+    .join("");
+}
+
+// Render message
+function Message({ message }: { message: UIMessage }) {
+  return (
+    <div className={message.role === "user" ? "user" : "assistant"}>
+      {message.parts.map((part, index) => {
+        if (part.type === "text") {
+          return <p key={index}>{part.text}</p>;
+        }
+        if (part.type === "image") {
+          return <img key={index} src={part.image} alt="" />;
+        }
+        return null;
+      })}
+    </div>
+  );
+}
+```
+
+## Server-Side (Route Handler)
+
+```typescript
+// app/api/chat/route.ts
+import { openai } from "@ai-sdk/openai";
+import { streamText } from "ai";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = await streamText({
+    model: openai("gpt-4o"),
+    messages,
+    system: "You are a helpful assistant.",
+  });
+
+  return result.toDataStreamResponse();
+}
+```
+
+## With LangChain
+
+```typescript
+// app/api/chat/route.ts
+import { toUIMessageStream } from "@ai-sdk/langchain";
+import { ChatOpenAI } from "@langchain/openai";
+import { HumanMessage, AIMessage } from "@langchain/core/messages";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const model = new ChatOpenAI({
+    modelName: "gpt-4o",
+    streaming: true,
+  });
+
+  // Convert UI messages to LangChain format
+  const langchainMessages = messages.map((m) => {
+    const text = m.parts
+      .filter((p) => p.type === "text")
+      .map((p) => p.text)
+      .join("");
+    return m.role === "user"
+      ? new HumanMessage(text)
+      : new AIMessage(text);
+  });
+
+  const stream = await model.stream(langchainMessages);
+
+  return toUIMessageStream(stream).toDataStreamResponse();
+}
+```
+
+## Streaming with Tools
+
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { streamText, tool } from "ai";
+import { z } from "zod";
+
+const result = await streamText({
+  model: openai("gpt-4o"),
+  messages,
+  tools: {
+    getWeather: tool({
+      description: "Get weather for a location",
+      parameters: z.object({
+        location: z.string().describe("City name"),
+      }),
+      execute: async ({ location }) => {
+        // Fetch weather data
+        return { temperature: 72, condition: "sunny" };
+      },
+    }),
+  },
+});
+```
+
+## useCompletion (Text Generation)
+
+```typescript
+import { useCompletion } from "@ai-sdk/react";
+import { DefaultCompletionTransport } from "ai";
+
+const { completion, complete, isLoading } = useCompletion({
+  transport: new DefaultCompletionTransport({ api: "/api/complete" }),
+});
+
+// Trigger completion
+await complete("Write a haiku about");
+```
+
+## Error Handling
+
+```typescript
+const { error, messages, sendMessage } = useChat({
+  transport: new DefaultChatTransport({ api: "/api/chat" }),
+  onError: (error) => {
+    console.error("Chat error:", error);
+    toast.error("Failed to send message");
+  },
+});
+
+// Display error
+{error && (
+  <div className="error">
+    {error.message}
+    <button onClick={() => sendMessage({ text: lastInput })}>
+      Retry
+    </button>
+  </div>
+)}
+```
+
+## Keywords
+ai sdk, vercel ai, chat, streaming, langchain, openai, llm

package/assets/skills/angular/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: angular
+description: Angular patterns covering standalone components, signals, inject(), native control flow, and zoneless change detection; Signal Forms and Reactive Forms; project structure via the Scope Rule and file naming; and performance via NgOptimizedImage, @defer, lazy routes, and SSR. Trigger: When creating Angular components, working with forms, structuring an Angular app, or optimizing Angular performance.
+---
+
+## Orientation
+
+This skill assumes modern Angular: **standalone components** (no `standalone: true` flag needed), **signals** for state, **inject()** over constructor injection, native **`@if`/`@for`/`@switch`** control flow, and **zoneless** change detection (no `zone.js`). RxJS is used only where signals don't fit (combining streams, debounce/throttle, race conditions, websockets).
+
+## Index
+
+| Reference | Covers |
+|-----------|--------|
+| [references/core.md](references/core.md) | Standalone components, `input`/`output`/`model`, signals, no lifecycle hooks, `inject()`, control flow, RxJS-vs-signals, zoneless setup |
+| [references/forms.md](references/forms.md) | Signal Forms (experimental) vs Reactive Forms vs template-driven, nested forms/`FormArray` |
+| [references/architecture.md](references/architecture.md) | The Scope Rule, project structure, file naming (no `.component`/`.service` suffixes), style guide, CLI commands |
+| [references/performance.md](references/performance.md) | `NgOptimizedImage`, `@defer`, lazy routes, SSR/hydration, slow computations |
+
+Read the reference file(s) relevant to the task at hand before writing Angular code.

package/assets/skills/angular/references/architecture.md

@@ -0,0 +1,137 @@
+## The Scope Rule (REQUIRED)
+
+**"Scope determines structure"** - Where a component lives depends on its usage.
+
+| Usage | Placement |
+|-------|-----------|
+| Used by 1 feature | `features/[feature]/components/` |
+| Used by 2+ features | `features/shared/components/` |
+
+### Example
+
+```
+features/
+  shopping-cart/
+    shopping-cart.ts          # Main component = feature name
+    components/
+      cart-item.ts            # Used ONLY by shopping-cart
+      cart-summary.ts         # Used ONLY by shopping-cart
+  checkout/
+    checkout.ts
+    components/
+      payment-form.ts         # Used ONLY by checkout
+  shared/
+    components/
+      button.ts               # Used by shopping-cart AND checkout
+      modal.ts                # Used by multiple features
+```
+
+---
+
+## Project Structure
+
+```
+src/app/
+  features/
+    [feature-name]/
+      [feature-name].ts       # Main component (same name as folder)
+      components/             # Feature-specific components
+      services/               # Feature-specific services
+      models/                 # Feature-specific types
+    shared/                   # ONLY for 2+ feature usage
+      components/
+      services/
+      pipes/
+  core/                       # App-wide singletons
+    services/
+    interceptors/
+    guards/
+  app.ts
+  app.config.ts
+  routes.ts
+  main.ts
+```
+
+---
+
+## File Naming (REQUIRED)
+
+No `.component`, `.service`, `.model` suffixes. The folder tells you what it is.
+
+```
+✅ user-profile.ts
+❌ user-profile.component.ts
+
+✅ cart.ts
+❌ cart.service.ts
+
+✅ user.ts
+❌ user.model.ts
+```
+
+---
+
+## Style Guide
+
+### What We Follow (from official docs)
+
+- `inject()` over constructor injection
+- `class` and `style` bindings over `ngClass`/`ngStyle`
+- `protected` for template-only members
+- `readonly` for inputs, outputs, queries
+- Name handlers for action (`saveUser`) not event (`handleClick`)
+- Keep lifecycle hooks simple - delegate to well-named methods
+- One concept per file
+
+```typescript
+@Component({...})
+export class UserProfileComponent {
+  // 1. Injected dependencies
+  private readonly userService = inject(UserService);
+  
+  // 2. Inputs/Outputs
+  readonly userId = input.required<string>();
+  readonly userSaved = output<User>();
+  
+  // 3. Internal state
+  private readonly _loading = signal(false);
+  readonly loading = this._loading.asReadonly();
+  
+  // 4. Computed
+  protected readonly displayName = computed(() => ...);
+  
+  // 5. Methods
+  save(): void { ... }
+}
+```
+
+### What We Override
+
+| Official Says | We Do | Why |
+|---------------|-------|-----|
+| `user-profile.component.ts` | `user-profile.ts` | Redundant - folder tells context |
+| `user.service.ts` | `user.ts` | Same |
+
+---
+
+## Commands
+
+```bash
+# New project
+ng new my-app --style=scss --ssr=false
+
+# Component in feature
+ng g c features/products/components/product-card --flat
+
+# Service in feature  
+ng g s features/products/services/product --flat
+
+# Guard in core
+ng g g core/guards/auth --functional
+```
+
+---
+
+## Resources
+
+- https://angular.dev/style-guide