argos-harness 0.1.0

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

@@ -0,0 +1,197 @@
+## Standalone Components (REQUIRED)
+
+Components are standalone by default. Do NOT set `standalone: true`.
+
+```typescript
+@Component({
+  selector: 'app-user',
+  imports: [CommonModule],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `...`
+})
+export class UserComponent {}
+```
+
+---
+
+## Input/Output Functions (REQUIRED)
+
+```typescript
+// ✅ ALWAYS: Function-based
+readonly user = input.required<User>();
+readonly disabled = input(false);
+readonly selected = output<User>();
+readonly checked = model(false);  // Two-way binding
+
+// ❌ NEVER: Decorators
+@Input() user: User;
+@Output() selected = new EventEmitter<User>();
+```
+
+---
+
+## Signals for State (REQUIRED)
+
+```typescript
+readonly count = signal(0);
+readonly doubled = computed(() => this.count() * 2);
+
+// Update
+this.count.set(5);
+this.count.update(prev => prev + 1);
+
+// Side effects
+effect(() => localStorage.setItem('count', this.count().toString()));
+```
+
+---
+
+## NO Lifecycle Hooks (REQUIRED)
+
+Signals replace lifecycle hooks. Do NOT use `ngOnInit`, `ngOnChanges`, `ngOnDestroy`.
+
+```typescript
+// ❌ NEVER: Lifecycle hooks
+ngOnInit() {
+  this.loadUser();
+}
+
+ngOnChanges(changes: SimpleChanges) {
+  if (changes['userId']) {
+    this.loadUser();
+  }
+}
+
+// ✅ ALWAYS: Signals + effect
+readonly userId = input.required<string>();
+readonly user = signal<User | null>(null);
+
+private userEffect = effect(() => {
+  // Runs automatically when userId() changes
+  this.loadUser(this.userId());
+});
+
+// ✅ For derived data, use computed
+readonly displayName = computed(() => this.user()?.name ?? 'Guest');
+```
+
+### When to Use What
+
+| Need | Use |
+|------|-----|
+| React to input changes | `effect()` watching the input signal |
+| Derived/computed state | `computed()` |
+| Side effects (API calls, localStorage) | `effect()` |
+| Cleanup on destroy | `DestroyRef` + `inject()` |
+
+```typescript
+// Cleanup example
+private readonly destroyRef = inject(DestroyRef);
+
+constructor() {
+  const subscription = someObservable$.subscribe();
+  this.destroyRef.onDestroy(() => subscription.unsubscribe());
+}
+```
+
+---
+
+## inject() Over Constructor (REQUIRED)
+
+```typescript
+// ✅ ALWAYS
+private readonly http = inject(HttpClient);
+
+// ❌ NEVER
+constructor(private http: HttpClient) {}
+```
+
+---
+
+## Native Control Flow (REQUIRED)
+
+```html
+@if (loading()) {
+  <spinner />
+} @else {
+  @for (item of items(); track item.id) {
+    <item-card [data]="item" />
+  } @empty {
+    <p>No items</p>
+  }
+}
+
+@switch (status()) {
+  @case ('active') { <span>Active</span> }
+  @default { <span>Unknown</span> }
+}
+```
+
+---
+
+## RxJS - Only When Needed
+
+Signals are the default. Use RxJS ONLY for complex async operations.
+
+| Use Signals | Use RxJS |
+|-------------|----------|
+| Component state | Combining multiple streams |
+| Derived values | Debounce/throttle |
+| Simple async (single API call) | Race conditions |
+| Input/Output | WebSockets, real-time |
+| | Complex error retry logic |
+
+```typescript
+// ✅ Simple API call - use signals
+readonly user = signal<User | null>(null);
+readonly loading = signal(false);
+
+async loadUser(id: string) {
+  this.loading.set(true);
+  this.user.set(await firstValueFrom(this.http.get<User>(`/api/users/${id}`)));
+  this.loading.set(false);
+}
+
+// ✅ Complex stream - use RxJS
+readonly searchResults$ = this.searchTerm$.pipe(
+  debounceTime(300),
+  distinctUntilChanged(),
+  switchMap(term => this.http.get<Results>(`/api/search?q=${term}`))
+);
+
+// Convert to signal when needed in template
+readonly searchResults = toSignal(this.searchResults$, { initialValue: [] });
+```
+
+---
+
+## Zoneless Angular (REQUIRED)
+
+Angular is zoneless. Use `provideZonelessChangeDetection()`.
+
+```typescript
+bootstrapApplication(AppComponent, {
+  providers: [provideZonelessChangeDetection()]
+});
+```
+
+Remove ZoneJS:
+```bash
+npm uninstall zone.js
+```
+
+Remove from `angular.json` polyfills: `zone.js` and `zone.js/testing`.
+
+### Zoneless Requirements
+- Use `OnPush` change detection
+- Use signals for state (auto-notifies Angular)
+- Use `AsyncPipe` for observables
+- Use `markForCheck()` when needed
+
+---
+
+## Resources
+
+- https://angular.dev/guide/signals
+- https://angular.dev/guide/templates/control-flow
+- https://angular.dev/guide/zoneless

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

@@ -0,0 +1,115 @@
+## When to Use What
+
+| Use Case | Recommendation |
+|----------|----------------|
+| New apps with signals | Signal Forms (experimental) |
+| Production apps | Reactive Forms |
+| Simple forms | Template-driven |
+
+---
+
+## Signal Forms (v21+, experimental)
+
+```typescript
+import { form, FormField, required, email } from '@angular/forms/signals';
+
+@Component({
+  imports: [FormField],
+  template: `
+    <form>
+      <input [formField]="emailField" type="email" />
+      <input [formField]="passwordField" type="password" />
+      <button (click)="submit()">Login</button>
+    </form>
+  `
+})
+export class LoginComponent {
+  readonly loginForm = form({
+    email: ['', [required, email]],
+    password: ['', required]
+  });
+  
+  readonly emailField = this.loginForm.controls.email;
+  readonly passwordField = this.loginForm.controls.password;
+  
+  submit() {
+    if (this.loginForm.valid()) {
+      const values = this.loginForm.value();
+    }
+  }
+}
+```
+
+### Signal Forms Benefits
+- Automatic two-way binding
+- Type-safe field access
+- Schema-based validation
+- Built on signals
+
+---
+
+## Reactive Forms (production)
+
+```typescript
+import { FormBuilder, Validators, ReactiveFormsModule } from '@angular/forms';
+
+@Component({
+  imports: [ReactiveFormsModule],
+  template: `
+    <form [formGroup]="form" (ngSubmit)="submit()">
+      <input formControlName="email" type="email" />
+      <input formControlName="password" type="password" />
+      <button type="submit" [disabled]="form.invalid">Login</button>
+    </form>
+  `
+})
+export class LoginComponent {
+  private readonly fb = inject(FormBuilder);
+
+  form = this.fb.nonNullable.group({
+    email: ['', [Validators.required, Validators.email]],
+    password: ['', [Validators.required, Validators.minLength(8)]],
+  });
+  
+  submit() {
+    if (this.form.valid) {
+      const { email, password } = this.form.getRawValue();
+    }
+  }
+}
+```
+
+### Key Points
+- ALWAYS use `fb.nonNullable.group()` for type safety
+- Use `getRawValue()` to get typed values
+- Reactive Forms are synchronous (easier to test)
+
+---
+
+## Nested Forms & FormArray
+
+```typescript
+form = this.fb.nonNullable.group({
+  name: [''],
+  address: this.fb.group({
+    street: [''],
+    city: [''],
+  }),
+  phones: this.fb.array([this.fb.control('')]),
+});
+
+get phones() {
+  return this.form.get('phones') as FormArray;
+}
+
+addPhone() {
+  this.phones.push(this.fb.control(''));
+}
+```
+
+---
+
+## Resources
+
+- https://angular.dev/guide/forms/signals/overview
+- https://angular.dev/guide/forms/reactive-forms

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

@@ -0,0 +1,124 @@
+## NgOptimizedImage (REQUIRED for images)
+
+```typescript
+import { NgOptimizedImage } from '@angular/common';
+
+@Component({
+  imports: [NgOptimizedImage],
+  template: `
+    <!-- LCP image: add priority -->
+    <img ngSrc="hero.jpg" width="800" height="400" priority>
+    
+    <!-- Regular: lazy loaded by default -->
+    <img ngSrc="thumb.jpg" width="200" height="200">
+    
+    <!-- Fill mode (parent needs position: relative) -->
+    <img ngSrc="bg.jpg" fill>
+    
+    <!-- With placeholder -->
+    <img ngSrc="photo.jpg" width="400" height="300" placeholder>
+  `
+})
+```
+
+### Rules
+- ALWAYS set `width` and `height` (or `fill`)
+- Add `priority` to LCP (Largest Contentful Paint) image
+- Use `ngSrc` not `src`
+- Parent of `fill` image must have `position: relative/fixed/absolute`
+
+---
+
+## @defer - Lazy Components
+
+```html
+@defer (on viewport) {
+  <heavy-component />
+} @placeholder {
+  <p>Placeholder shown immediately</p>
+} @loading (minimum 200ms) {
+  <spinner />
+} @error {
+  <p>Failed to load</p>
+}
+```
+
+### Triggers
+
+| Trigger | When to Use |
+|---------|-------------|
+| `on viewport` | Below the fold content |
+| `on interaction` | Load on click/focus/hover |
+| `on idle` | Load when browser is idle |
+| `on timer(500ms)` | Load after delay |
+| `when condition` | Load when expression is true |
+
+```html
+<!-- Multiple triggers -->
+@defer (on viewport; on interaction) {
+  <comments />
+}
+
+<!-- Conditional -->
+@defer (when showComments()) {
+  <comments />
+}
+```
+
+---
+
+## Lazy Routes
+
+```typescript
+// Single component
+{
+  path: 'admin',
+  loadComponent: () => import('./features/admin/admin').then(c => c.AdminComponent)
+}
+
+// Feature with child routes
+{
+  path: 'users',
+  loadChildren: () => import('./features/users/routes').then(m => m.USERS_ROUTES)
+}
+```
+
+---
+
+## SSR & Hydration
+
+```typescript
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideClientHydration()
+  ]
+});
+```
+
+| Scenario | Use |
+|----------|-----|
+| SEO critical (blog, e-commerce) | SSR |
+| Dashboard/Admin | CSR |
+| Static marketing site | SSG/Prerender |
+
+---
+
+## Slow Computations
+
+| Solution | When |
+|----------|------|
+| Optimize algorithm | First choice always |
+| Pure pipes | Cache single result |
+| Memoization | Cache multiple results |
+| `computed()` | Derived signal state |
+
+**NEVER** trigger reflows/repaints in lifecycle hooks (`ngOnInit`, `ngAfterViewInit`).
+
+---
+
+## Resources
+
+- https://angular.dev/guide/image-optimization
+- https://angular.dev/guide/defer
+- https://angular.dev/best-practices/runtime-performance
+- https://angular.dev/guide/ssr

package/assets/skills/apollo-client/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: apollo-client
+description: GraphQL con Apollo Client — hooks, fetchPolicy, normalización de caché y actualización tras mutaciones. Trigger: al escribir queries/mutations, configurar la caché o los links.
+---
+
+# Apollo Client — el patrón canónico
+
+Lecturas declarativas con hooks, caché **normalizada por id**, y la UI se mantiene en sync actualizando la caché tras cada mutación. Los concerns de red/auth viven en los links, no en los componentes.
+
+## Cuándo usar este skill
+
+Al escribir una query/mutation, configurar `InMemoryCache`/`typePolicies`, o la cadena de `links`.
+
+## Hooks y aislamiento
+
+`useQuery` (lectura al montar), `useLazyQuery` (bajo demanda, retorna `execute`), `useMutation` (retorna `[mutate, { data, loading, error }]`). Aísla los hooks en una capa (hook + adapter): el componente recibe un **modelo de dominio**, no el shape crudo de GraphQL.
+
+```ts
+export function useReport(id: string) {
+  const { data, loading, error } = useGetReportQuery({ variables: { id }, fetchPolicy: 'cache-first' });
+  return { report: data?.report ? adaptReport(data.report) : null, loading, error };
+}
+```
+
+## fetchPolicy según el dato
+
+- `cache-first` (default) — catálogos/detalles ya traídos por una lista.
+- `cache-and-network` — feeds que cambian seguido (render instantáneo + refresh).
+- `network-only` — sesión/bootstrap, datos críticos.
+- Evita `no-cache` salvo PII estricta que no deba tocar disco.
+
+## Normalización de caché
+
+```ts
+const cache = new InMemoryCache({ typePolicies: { Report: { keyFields: ['id'] } } });
+```
+
+Con `keyFields`, Apollo identifica entidades por id y deduplica/actualiza solo. Sin normalización, las listas y detalles se desincronizan.
+
+## Reglas duras
+
+1. **Tras una mutation, actualiza la caché:** `update(cache, { data })` (`cache.modify`/`evict`/`writeQuery`) o `refetchQueries`. Nunca dejes la UI desincronizada.
+2. **`optimisticResponse`** para UI instantánea (resultado temporal con `__typename` + id ficticio); `update` reconcilia al llegar la respuesta real.
+3. **No over-fetch:** pide solo los campos que el componente usa; apóyate en **fragments con colocation** (el fragmento junto al componente que lo consume). Regenera tipos (codegen) tras editar `.graphql`.
+4. **Maneja `loading` y `error` siempre.** Separa error de red (banner genérico, resuelto en un `errorLink`) de error de negocio (`graphQLErrors`, copy según `extensions.code`).
+5. **Paginación** con `fetchMore` + `updateQuery`, o `relayStylePagination`/merge en `typePolicies`.
+6. Red/auth/upload en la cadena de **links** (auth → error → upload), no en cada componente.
+
+```ts
+const [createReport] = useCreateReportMutation({
+  optimisticResponse: { createReport: { __typename: 'Report', id: 'temp', ...fields } },
+  update(cache) { cache.evict({ fieldName: 'reports' }); }, // invalida la lista
+});
+```
+
+## Antes de declarar listo
+
+- Hooks aislados en capa (hook + adapter); el componente ve el modelo de dominio.
+- Caché normalizada por `keyFields`; mutaciones actualizan/invalidan la caché.
+- `fetchPolicy` elegido por tipo de dato; `loading`/`error` manejados.
+- El quality gate del repo (`qualityGate.fast` en `argos.config.json`) en verde.

package/assets/skills/app-blueprint/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: app-blueprint
+description: Generate reconstruction-grade docs of an app — business rules, endpoints, routes, screens, contracts. Trigger: app blueprint, appblueprint, reverse-spec, mapear app, map app for reconstruction.
+---
+
+## Activation Contract
+
+Activate on `/app-blueprint <target>` or requests to map/document an app well enough to rebuild it without losing logic or features. Targets: `<repo-dir>` (one repo), `all` (every repo in the workspace root minus user exclusions), `system` (cross-repo synthesis from existing blueprints).
+
+## Hard Rules
+
+- Output goes to `<workspace-root>/blueprint/<repo>/`. All docs in English.
+- Phase 0 inventory is mandatory and script-only (`rg`/`fd`, zero agent reading). `_inventory.json` is the coverage contract for the whole run.
+- Module agents write their doc file directly to disk and return ONE summary line. Never pipe doc content through the orchestrator context.
+- Business rules are numbered, testable statements with `file:line` refs. No prose-only rules.
+- Partition modules by business domain, never by folder.
+- The run is not done until the audit maps every inventory item (route, endpoint, model, page, slice, job) to a doc section, or lists it in `_gaps.md`.
+
+## Decision Gates
+
+| Target | Action |
+|--------|--------|
+| Single repo | Phases 0-2 on that repo per `references/workflow.md` |
+| `all` | Phases 0-2 per repo, one repo at a time |
+| `system` | Read existing blueprints only (no source code), cross-check contracts, write `SYSTEM.md` |
+| Frontend stack detected | Module docs use frontend sections of the template |
+| Backend stack detected | Module docs use backend sections of the template |
+
+## Execution Steps
+
+1. Read `references/workflow.md` in full before acting.
+2. Phase 0: detect stack, run the inventory command cookbook, write `_inventory.json`.
+3. Phase 1: partition into 6-12 domain modules; spawn all module agents in parallel (Agent tool, single message, `model: sonnet`), each pointed at `assets/module-template.md`.
+4. Phase 2: audit coverage against `_inventory.json`; spawn gap agents for unmapped items; write the repo `README.md`.
+5. `system` mode: cross-check consumed vs exposed endpoints across blueprints; write `SYSTEM.md`.
+
+## Output Contract
+
+Per repo: `blueprint/<repo>/{README.md, _inventory.json, <module>.md...}` plus `_gaps.md` if items remain unresolved. System mode: `blueprint/SYSTEM.md`. Final report to user: files written, coverage count (mapped/total), gaps.
+
+## References
+
+- `references/workflow.md` — phase details, inventory command cookbook, agent prompt templates, audit rules.
+- `assets/module-template.md` — module doc template (frontend/backend sections).
+- `assets/system-template.md` — SYSTEM.md skeleton with contract table.

package/assets/skills/app-blueprint/assets/module-template.md

@@ -0,0 +1,48 @@
+# Module: {name}
+
+**Repo:** {repo} · **Kind:** {frontend|backend} · **Purpose:** one sentence.
+
+## Screens & Routes (frontend) / Endpoints (backend)
+
+Frontend:
+
+| Route | Screen/Page | Guard | Purpose |
+|-------|-------------|-------|---------|
+
+Backend:
+
+| Method | Path | Auth | Request | Response | Errors |
+|--------|------|------|---------|----------|--------|
+
+## Business Rules
+
+Numbered, testable, with source refs. Capture validations, conditionals, permission checks, status transitions, limits, and defaults.
+
+- **BR-1:** A session cannot be booked when the coach has no connected calendar. (`src/services/x.js:42`)
+- **BR-2:** ...
+
+## Data
+
+Frontend: state used (slices/stores), key entities and their shapes as consumed.
+Backend: models/schemas with fields, types, constraints, indexes, relations.
+
+## API Calls Consumed (frontend) / Dependencies (backend)
+
+Frontend:
+
+| Method | URL | Trigger (screen/action) | Payload | Response used for |
+|--------|-----|-------------------------|---------|-------------------|
+
+Backend: services/DBs/queues this module calls, with purpose.
+
+## Side Effects
+
+Emails, notifications, jobs enqueued, events emitted, external API writes — with trigger condition and source ref.
+
+## Edge Cases & Gotchas
+
+Non-obvious behavior a rebuilder would miss: race handling, retries, timezone logic, legacy quirks, feature flags.
+
+## Files Covered
+
+Every assigned file, one per line. Required — the audit uses this list.

package/assets/skills/app-blueprint/assets/system-template.md

@@ -0,0 +1,38 @@
+# SYSTEM — {workspace name}
+
+**Purpose:** one paragraph — what the whole system does for whom.
+
+## Repo Map
+
+| Repo | Kind | Role | Blueprint |
+|------|------|------|-----------|
+
+## Cross-Service Flows
+
+Trace the 3-6 core user journeys end to end. For each: numbered steps naming screen → endpoint → service → side effects.
+
+### Flow: {e.g. Coachee books a session}
+
+1. ...
+
+## Contract Table
+
+Every HTTP call consumed vs the endpoint that exposes it.
+
+| Consumer | Method | Path | Exposed by | Status |
+|----------|--------|------|------------|--------|
+| bonum-webapp | POST | /sessions | services--sessions | OK / MISSING / ORPHAN |
+
+MISSING = consumed but no documented service exposes it. ORPHAN = exposed but no documented consumer (may be an unmapped client).
+
+## Auth Model
+
+Identity provider, token flow, how each service validates, role/permission model.
+
+## Shared Integrations & Infra
+
+External services (calendar, streaming, email...), who uses them, env vars per repo.
+
+## Gaps
+
+Unresolved items from per-repo `_gaps.md` files plus MISSING/ORPHAN contracts, each with a one-line reason.