argos-harness 0.1.0

package/assets/skills/typescript/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: typescript
+description: TypeScript strict patterns and best practices. Trigger: When writing TypeScript code - types, interfaces, generics.
+---
+
+## Const Types Pattern (REQUIRED)
+
+```typescript
+// ✅ ALWAYS: Create const object first, then extract type
+const STATUS = {
+  ACTIVE: "active",
+  INACTIVE: "inactive",
+  PENDING: "pending",
+} as const;
+
+type Status = (typeof STATUS)[keyof typeof STATUS];
+
+// ❌ NEVER: Direct union types
+type Status = "active" | "inactive" | "pending";
+```
+
+**Why?** Single source of truth, runtime values, autocomplete, easier refactoring.
+
+## Flat Interfaces (REQUIRED)
+
+```typescript
+// ✅ ALWAYS: One level depth, nested objects → dedicated interface
+interface UserAddress {
+  street: string;
+  city: string;
+}
+
+interface User {
+  id: string;
+  name: string;
+  address: UserAddress;  // Reference, not inline
+}
+
+interface Admin extends User {
+  permissions: string[];
+}
+
+// ❌ NEVER: Inline nested objects
+interface User {
+  address: { street: string; city: string };  // NO!
+}
+```
+
+## Never Use `any`
+
+```typescript
+// ✅ Use unknown for truly unknown types
+function parse(input: unknown): User {
+  if (isUser(input)) return input;
+  throw new Error("Invalid input");
+}
+
+// ✅ Use generics for flexible types
+function first<T>(arr: T[]): T | undefined {
+  return arr[0];
+}
+
+// ❌ NEVER
+function parse(input: any): any { }
+```
+
+## No Nested Ternaries (REQUIRED)
+
+```typescript
+// ❌ NEVER: nested ternaries — unreadable, flagged by SonarCloud/ESLint
+const color = state === "available" ? "green" : state === "busy" ? "red" : "yellow";
+
+// ✅ Lookup map keyed by the discriminant — single source of truth, extensible
+const STATE_CONFIG = {
+  available: { color: "green", label: "Disponible" },
+  busy: { color: "red", label: "Ocupado" },
+  lead: { color: "yellow", label: "No reservable aún" },
+} as const;
+
+const { color, label } = STATE_CONFIG[state];
+
+// ✅ When the value is computed (not a direct key), use early returns
+function slotState(available: boolean, hasReasons: boolean) {
+  if (available) return "available";
+  if (hasReasons) return "busy";
+  return "lead";
+}
+
+// ✅ In JSX, prefer independent && blocks over a chained ternary
+{loading && <Loader />}
+{!loading && items.length === 0 && <Empty />}
+{!loading && items.length > 0 && <List />}
+```
+
+**Why?** A nested ternary is a `switch` in disguise — a lookup map or early returns reads top-to-bottom, adds cases without re-nesting, and keeps the config in one place. A single (non-nested) ternary is fine; nesting is the smell.
+
+## Utility Types
+
+```typescript
+Pick<User, "id" | "name">     // Select fields
+Omit<User, "id">              // Exclude fields
+Partial<User>                 // All optional
+Required<User>                // All required
+Readonly<User>                // All readonly
+Record<string, User>          // Object type
+Extract<Union, "a" | "b">     // Extract from union
+Exclude<Union, "a">           // Exclude from union
+NonNullable<T | null>         // Remove null/undefined
+ReturnType<typeof fn>         // Function return type
+Parameters<typeof fn>         // Function params tuple
+```
+
+## Type Guards
+
+```typescript
+function isUser(value: unknown): value is User {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "id" in value &&
+    "name" in value
+  );
+}
+```
+
+## Import Types
+
+```typescript
+import type { User } from "./types";
+import { createUser, type Config } from "./utils";
+```
+
+## Keywords
+typescript, ts, types, interfaces, generics, strict mode, utility types, nested ternary, lookup map, early returns

package/assets/skills/verify-before-done/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: verify-before-done
+description: Aplica la Iron Law de verificación antes de declarar cualquier tarea lista — exige evidencia fresca del comando que respalda el claim, nunca inferencia. Trigger: antes de decir listo/done/completed/approved, antes de un commit o PR, o cuando un subagente reporta éxito sin que se haya visto el diff.
+---
+
+# Verify Before Done
+
+## La ley de hierro
+
+```
+NINGÚN CLAIM DE COMPLETADO SIN EVIDENCIA DE VERIFICACIÓN FRESCA
+```
+
+Si no corriste el comando de verificación EN ESTE TURNO, no puedes afirmar el claim. "Debería funcionar", "la corrida anterior estaba verde", "se ve bien" NO son evidencia.
+
+## Por qué este skill existe
+
+El bug recurrente es declarar "listo" en base a inferencia:
+
+- "corrí el check hace 2 cambios atrás, debería seguir verde"
+- "el código compila, la UI debería andar"
+- "el adapter está bien, el render debe funcionar"
+
+Inferencia ≠ evidencia. Este skill fuerza el rigor.
+
+## Función de gate
+
+ANTES de afirmar cualquier "listo / done / completed / approved":
+
+1. **IDENTIFY**: ¿qué comando prueba este claim?
+2. **RUN**: ejecuta el comando COMPLETO en este turno (no parcial, no cached).
+3. **READ**: output completo, exit code, contar failures.
+4. **VERIFY**: ¿el output confirma el claim?
+   - NO → declara el estado real con evidencia.
+   - SÍ → afirma el claim CON la evidencia visible.
+5. **ONLY THEN**: haz el claim.
+
+Saltarse cualquier step = mentira, no verificación.
+
+El comando exacto de cada claim (qué es "fast" y qué es "full") no vive en este skill: se resuelve en runtime leyendo `qualityGate.fast` / `qualityGate.full` en el `argos.config.json` del repo, o la ficha (CLAUDE.md delgado) que `argos adopt` escribió con esos hechos ya resueltos en texto literal. Si el repo no tiene config ni ficha, no asumas un comando — pregunta o revisa `package.json` / scripts del repo antes de declarar nada verde.
+
+## Tabla claim → output requerido → no alcanza
+
+| Claim | Output requerido | No alcanza |
+|---|---|---|
+| Quality gate fast verde | Comando fast del repo (resuelto desde `argos.config.json`/ficha) corrido completo en este turno con exit 0 | "corrí antes", "debería estar verde", "lint pasaba ayer" |
+| Quality gate full verde | Comando full del repo (mismo origen) — exit 0 fresco en este turno | "el dev server anda", "build pasó hace rato" |
+| Cero errores nuevos vs baseline | `git stash` → re-run → comparar conteos → `git stash pop` | "lint dijo OK" sin comparar baseline |
+| UI validada (golden path) | Repro step + comportamiento observado en navegador con dev server vivo en este turno | "se ve bien en código", "debería renderizar bien" |
+| Bug arreglado | Reproducir síntoma original y verlo NO ocurrir | "cambié el código, asumí que quedó arreglado", "el diff cubre el caso" |
+| Filtro / feature funciona | Click real + descripción del resultado | "el handler está bien escrito" |
+| Migración estructural completa | Lectura Y escritura van al mismo destino en el flujo afectado, validado en navegador o test | "cambié el service, debería andar" |
+| PR creable | Pre-flight verde (status limpio, no estás en la rama base ni en la rama destino del PR — `branchBase`/`prTarget` de `argos.config.json` —, `gh` auth ok, quality gate verde) EN ESTE TURNO | "el branch tiene commits, podemos crear" |
+| Tests pasan | Suite corrida fresca con exit 0 en este turno + conteo de tests | "no tocamos tests", "deberían seguir verdes" |
+| Type-check limpio | `tsc --noEmit` (o el check equivalente que declare el stack del repo) exit 0 en este turno | "TS no se quejó cuando lo guardé" |
+
+## Señales de alerta (PARA)
+
+- Estás por escribir "listo" / "done" / "perfect" / "should work".
+- Estás por hacer `git commit` sin haber corrido el quality gate fast del repo en este turno.
+- Estás por marcar `APPROVED` un review sin haber leído el diff completo.
+- Estás cansado y quieres cerrar.
+- "Solo por esta vez" — NO. Cero excepciones.
+- Confías en el reporte de un subagente sin verificar el diff tú mismo.
+
+## Prevención de racionalización
+
+| Excusa | Realidad |
+|---|---|
+| "Tengo confianza" | Confianza ≠ evidencia. |
+| "Si compila, anda" | TS con `strict: false` no atrapa undefined runtime. Verifica UI / runtime. |
+| "El check pasó hace 10 min" | Re-corre. Fresca. |
+| "Es trivial, no hace falta" | Trivialidad no exime de verificación. |
+| "El subagente dijo done" | Mira el diff tú mismo. Confía, pero verifica. |
+| "El usuario tiene prisa" | Prisa ≠ excusa. Verificación rápida es más rápida que rollback. |
+| "Mismo argumento con otras palabras = la regla no aplica" | El espíritu de la regla importa más que la letra. |
+
+## Cuándo se invoca este skill
+
+- **`implementer`**: antes de devolver `done -> .claude/progress/impl_<feature>.md`. Antes de pasar al `reviewer`.
+- **`reviewer`**: antes de marcar `APPROVED`.
+- **`commit-pr-pilot`**: antes de `gh pr create`.
+- **Cualquier agent**: antes de decir "listo" al usuario en cualquier respuesta de tarea de código.
+
+## Conexión con el resto del harness
+
+- El CLAUDE.md global menciona el quality gate en su sección de cierre. Este skill añade rigor de "evidencia fresca" + cubre dimensiones UI / bug arreglado que el quality gate no toca por sí solo.
+- El `implementer` referencia este skill en su "Evidence-based completion".
+- El `reviewer` debe citar este skill cuando marca `APPROVED`.
+- El `commit-pr-pilot` lo aplica en su pre-flight antes de tocar `gh`.
+
+## Anti-patrones
+
+- ❌ Mostrar output cacheado de hace 5 mensajes y decir "ya está verde" — evidencia fresca, no cacheada.
+- ❌ Inferir UI desde el código — la UI necesita repro en navegador.
+- ❌ "Confía en mí, anda en mi máquina" — no es claim válido sin evidencia en el chat.
+- ❌ Hacer el claim ANTES del comando ("voy a correr X y debería estar verde").
+- ❌ Marcar `[x]` un step del plan atómico sin haber corrido la verificación que respalda ese step.
+- ❌ Aceptar el reporte de un subagente sin abrir el diff y validar al menos los archivos críticos.
+
+## Cierre
+
+Skill **siempre activa** durante cualquier flow de implementación. No requiere invocación explícita — es principio que aplica a todo claim de "listo".
+
+Al aplicarla, el output al usuario debe incluir:
+
+1. El claim explícito (qué se logró).
+2. El output completo (o referencia al comando corrido) que lo respalda.
+3. Si algún sub-claim NO pudo verificarse (ej. UI sin browser disponible), decirlo EXPLÍCITO — no inferir.
+
+Este skill vive una sola vez en el motor global (`~/.claude/skills/`) y se aplica a cualquier repo. Los checks específicos de un proyecto (comandos que cuentan como evidencia válida, patrones de bug donde la inferencia históricamente falló, áreas críticas con verificación propia) no se editan aquí: viven en la ficha del repo (CLAUDE.md delgado) o en `project.criticalAreas` de su `argos.config.json`, y se leen en runtime al trabajar en ese repo.

package/assets/skills/webapp-rebuilder/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: webapp-rebuilder
+description: Trigger: rebuild web app, reconstruir app, rebuild from blueprint, redesign rebuild, webapp rebuilder. Phased web app reconstruction from an app-blueprint: preserve every business rule, redesign UX/UI.
+---
+
+# Webapp Rebuilder
+
+## Activation Contract
+
+Activate when the user wants to rebuild an existing web app from its app-blueprint docs (`blueprint/<repo>/`), modernizing stack and redesigning UX/UI while preserving behavior. Requires an existing blueprint; if none exists, run app-blueprint first.
+
+## Hard Rules
+
+- The blueprint is the source of truth for BEHAVIOR: business rules (BR-*), API contracts, capabilities. It is NOT a UI spec — redesigning screens, flows, and navigation is encouraged; losing a capability is forbidden.
+- Any feature or BR intentionally dropped must be an explicit entry in the charter kill-list, approved by the user. Nothing is dropped silently.
+- Maintain `_traceability.md` in the new repo: every BR from the blueprint → status (`implemented@test`, `implemented`, `killed@charter`, `pending`). The rebuild is not done until no `pending` remains.
+- Consume backend endpoints exactly as documented in the blueprint's `api-layer.md`. Never invent or "improve" an endpoint contract — the real services are live.
+- Each BR becomes a test before or with its implementation (BRs are already written as testable statements).
+- Orchestrate, never implement inline: delegate each phase to sub-agents per `~/.claude/skills/app-builder/references/orchestration.md`. Complete phases in order; a phase starts only after the previous gate passes.
+- For ANY UI work, load skills via the ui-skills CLI first (`npx ui-skills start`). UI primitives from shadcn/ui copied into `components/ui/*`, owned and editable. Phase 4 builds structural character in grayscale; color arrives in Phase 5.
+- All artifacts in English. Conventional commits, no AI attribution.
+
+## Decision Gates
+
+| Situation | Action |
+|-----------|--------|
+| No blueprint for the target app | Stop; run app-blueprint first |
+| Blueprint has `_gaps.md` entries touching a phase | Surface them in that phase's charter section; user decides |
+| BR contradicts observed service behavior during Phase 2 | Trust the live service, note the correction back into the blueprint |
+| Scope creep mid-phase | Log as post-MVP in the charter, finish the current gate |
+
+## Execution Steps
+
+1. Read `references/workflow.md` in full before acting.
+2. Phase 0: write the rebuild charter from `assets/charter-template.md`; user approves it explicitly before any code.
+3. Phases 1-6 per the workflow phase table (scaffold → typed API layer → domain/BR tests → UX redesign + UI → visual identity → polish), delegating each to sub-agents with its blueprint slice as spec.
+4. Phase 7: adversarial traceability audit — every BR accounted for in `_traceability.md`; gaps trigger a fix round.
+5. Phase 8: ship docs (README + DEPLOYMENT via ship-docs).
+
+## Output Contract
+
+A working repo for the rebuilt app plus: `docs/rebuild-charter.md`, `_traceability.md` (100% BRs resolved), per-phase Engram/memory records, and ship docs. Final report: capabilities delivered, BRs implemented/killed, redesign decisions taken.
+
+## References
+
+- `references/workflow.md` — phase table with models/skills/gates, blueprint-slice-per-phase mapping, traceability audit rules.
+- `assets/charter-template.md` — rebuild charter template (stack, redesign scope, kill-list).
+- `~/.claude/skills/app-builder/references/orchestration.md` — delegation protocol (shared with app-builder).

package/assets/skills/webapp-rebuilder/assets/charter-template.md

@@ -0,0 +1,46 @@
+# Rebuild Charter: {app name}
+
+**Source blueprint:** `blueprint/{repo}/` (generated {date}, {N} business rules)
+**Target:** {new repo/workspace path}
+**Status:** draft | approved ({date})
+
+## Goal
+
+One paragraph: what this rebuild delivers and why now.
+
+## Target Stack
+
+| Layer | Legacy | Rebuild | Why |
+|-------|--------|---------|-----|
+| Framework | | | |
+| Routing | | | |
+| State | | | |
+| Data fetching | | | |
+| UI system | | | |
+| Auth | | | |
+
+## Backend Strategy
+
+Which services are consumed as-is (per api-layer.md contracts) and which, if any, change. Default: all as-is.
+
+## Capability Map
+
+One line per blueprint module: what the user can do. This is the redesign raw material — screens may be resliced, capabilities may not.
+
+| Module | Capabilities | Redesign scope |
+|--------|--------------|----------------|
+
+## Redesign Decisions
+
+Flows being rethought, each with the pain point motivating it. Flows rebuilt as-is need no entry.
+
+## Kill-List
+
+Every feature/BR intentionally NOT rebuilt. User-approved, one reason each. This list is the only legitimate destination for dropped behavior.
+
+| Item | Blueprint ref | Reason | Approved |
+|------|--------------|--------|----------|
+
+## Out of Scope / Post-MVP
+
+## Open Questions

package/assets/skills/webapp-rebuilder/references/workflow.md

@@ -0,0 +1,47 @@
+# webapp-rebuilder workflow
+
+Goal: rebuild a web app from its blueprint with a modern stack and redesigned UX, losing zero behavior. The blueprint gives you what app-builder's Phase 0 has to invent — so Phase 0 here is about DECISIONS, not discovery.
+
+Inputs: `blueprint/<repo>/` (README, module docs, api-layer.md, ui-shell.md or route table, state doc, `_inventory.json`). Target: a new repo (or workspace app) chosen in the charter.
+
+## Phase table
+
+Model tiers: cheap for mechanical, top tier only where judgment or taste decides. Load listed skills before starting the phase. `ui:*` skills come from the ui-skills CLI.
+
+| # | Phase | Input from blueprint | Output | Gate | Model | Skills |
+|---|-------|----------------------|--------|------|-------|--------|
+| 0 | Rebuild charter | README + module index + gotchas/edge-case sections | `docs/rebuild-charter.md` from the template: target stack, backend strategy, UX redesign scope, kill-list, capability map | User approves explicitly | fable | cognitive-doc-design |
+| 1 | Scaffold | charter only | Repo scaffolded (default: Vite + React 19 + TS strict + Tailwind 4 + shadcn/ui + TanStack Router/Query, unless charter overrides), CI-ready, boots | App boots, typecheck clean | haiku | ponytail |
+| 2 | Typed API layer | `api-layer.md` (every consumed endpoint) + auth/interceptor rules | Typed client: one function per endpoint with zod schemas for payload/response, auth token flow, error mapping | Contract smoke test against real services (or recorded fixtures) passes | sonnet | typescript, zod-4, ponytail |
+| 3 | Domain + BR tests | Business Rules sections of every module doc | Pure domain logic; each applicable BR encoded as a unit test (BR id in test name) | All BR tests pass; `_traceability.md` updated | sonnet | typescript, pytest-style discipline via strict TDD |
+| 4 | UX redesign + UI | Screens/routes + capabilities per module doc — treat as a CAPABILITY inventory, not a screen spec | New information architecture: regrouped flows, reduced tap-count, modern navigation; core screens with structural character in grayscale; owned `components/ui/*` | User walks all flows; every blueprint capability reachable; screens have grayscale personality | sonnet | ui:impeccable (PRIMARY), ui:bolder, react-19, tailwind-4 |
+| 4.5 | UX refinement | usage of Phase 4 build | Density audit, flow chaining, empty states, error copy | User confirms flows FEEL right | sonnet | ui:impeccable, ui:relevant, ponytail |
+| 5 | Visual identity | brand inputs from user | Color tokens + real typography pairing + signature element | User confirms distinctive, not generic | fable | frontend-design, ui:typeset, ui:colorize |
+| 6 | Polish | — | Micro-interactions, motion, a11y pass | Verified in browser | fable | ui:motion, verify |
+| 7 | Traceability audit | full blueprint + `_traceability.md` | Adversarial audit: every BR → implemented@test / implemented / killed@charter. Gaps → fix round → re-audit once; leftovers reported, never dropped | Zero `pending` BRs | inherit session model | — |
+| 8 | Ship docs | real repo | README.md + DEPLOYMENT.md | Fresh clone boots from README | sonnet | ship-docs, cognitive-doc-design |
+
+## Phase 0 — charter specifics
+
+Read the blueprint README and module index; do NOT re-read source code of the legacy app. Produce the charter with:
+
+- **Capability map**: one line per module — what the user can DO (derived from routes + BRs), independent of how old screens sliced it. This is the redesign's raw material.
+- **Kill-list candidates**: mine the blueprint's gotchas/edge-cases/dead-config sections for legacy quirks, disabled features, and dead flows; propose each as keep/kill with a one-line reason. The user decides every entry.
+- **Backend strategy**: default is consuming the existing services per `api-layer.md` unchanged. Migrating a service is out of scope unless the user asks.
+- **Redesign scope**: which flows get rethought (with the pain point motivating it) vs rebuilt as-is.
+
+One batched question round with the user, then the document. Target ≤2 iterations.
+
+## Traceability rules
+
+- `_traceability.md` lives at the new repo root: a table per module — BR id, one-line rule, status, evidence (test file or charter kill-list ref).
+- Seed it in Phase 0 with every BR at `pending` (script the extraction: `rg '\*\*BR-\d+' blueprint/<repo>/*.md`).
+- Phases 3 and 4 update statuses as they land; Phase 7 verifies claims adversarially (spot-check: open the cited test, run it).
+- A BR that applies only to killed features gets `killed@charter` with the kill-list entry as evidence.
+- UI-behavior BRs (guards, visibility rules, redirects) count as implemented only with a route/component test or an explicit Phase 7 manual verification note.
+
+## Redesign guardrails
+
+- Redesign changes HOW a capability is reached, never WHETHER it exists.
+- When collapsing N legacy screens into one flow, list the absorbed routes in the module's traceability section so the audit can match them.
+- Blueprint side effects (emails, notifications, socket events) triggered by user actions must survive the redesign — the trigger may move, the effect may not.

package/assets/skills/winston-logging/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: winston-logging
+description: Logging con winston — Logger.error/warn/info/debug, niveles correctos, mensajes accionables con contexto, nada de console.log. Trigger: al agregar logs o auditar las traces de un bug.
+---
+
+# Winston Logging — patterns del repo
+
+El `Logger` del repo (winston, típicamente en `infrastructure/`) reemplaza por completo a `console`. Escribe a consola y archivo en dev, solo consola en prod.
+
+## Cuándo usar este skill
+
+Al agregar logs a un controller, job o servicio, elegir el nivel correcto, auditar traces de un bug, o limpiar `console.log` heredados.
+
+## El patrón
+
+```ts
+import Logger from '../../infrastructure/core/Logger';
+
+try {
+  const created = await Resource.create(dto);
+  Logger.info(`[resource:create] ${created._id} owner ${dto.owner}`);
+} catch (err) {
+  Logger.error(`Failed to create Resource`, err);
+  throw err; // re-throw → middleware global lo mapea a InternalError
+}
+```
+
+Con `format.errors({ stack: true })` (config típica), pasar un `Error` loguea el stack solo. Prefija con `[<scope>:<verb>]` (`[job:sendReminder]`, `[email:welcome]`) para que sea grep-friendly.
+
+Si tu framework ya centraliza el error async (`asyncHandler` en Express, exception filters en Nest, error middleware global), NO dupliques try/catch en cada handler. Agrégalo solo para loguear contexto extra, mapear un error específico (ej. `MongoServerError` 11000 → `BadRequestError`), o hacer cleanup antes del re-throw.
+
+## Gotchas que muerden
+
+- **`Logger.debug` no se imprime en prod** cuando `logLevel = isDev ? 'debug' : 'info'`. Perfecto para diagnóstico que no quieres exponer; inútil si esperabas verlo en prod.
+- **`JSON.stringify(req)` revienta**: los Request son enormes y tienen circular refs. Loguea solo lo que necesitas.
+
+## Reglas duras
+
+1. `Logger` siempre, nunca `console.log/error/warn`. Borra los `console.log` temporales antes del commit.
+2. Nivel correcto: `error` (capturado/crítico), `warn` (recuperable pero notable), `info` (evento de dominio: job, login, email), `debug` (solo dev).
+3. Mensajes accionables: incluye IDs y contexto, no solo "Error"/"Failed".
+4. No spammees — un `info` por request es ruido; resérvalo para eventos.
+5. Re-lanza (`throw err`) tras el `Logger.error` cuando el flujo lo necesita; el caller debe enterarse del fallo.
+6. Nunca loguees secrets (tokens, passwords) ni `JSON.stringify(req)` completo. Nada de `catch (e) {}` tragador.
+
+## Tabla rápida
+
+| Situación | Nivel |
+|---|---|
+| Error capturado o evento crítico | `Logger.error(err)` |
+| Recuperable pero notable | `Logger.warn(msg)` |
+| Evento de dominio (job, login, email) | `Logger.info(msg)` |
+| Diagnóstico de desarrollo | `Logger.debug(msg)` |
+
+## Antes de declarar listo
+
+- No quedó ningún `console.log` nuevo; los temporales se borraron.
+- Cada log usa el nivel correcto y lleva IDs/contexto accionable.
+- Los errores capturados re-lanzan cuando el flujo lo necesita.
+- No se loguean secrets ni `JSON.stringify(req)` completo.
+- El quality gate del repo (`qualityGate.fast` en `argos.config.json`) en verde.

package/assets/skills/work-unit-commits/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: work-unit-commits
+description: Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.
+---
+
+## When to Use
+
+Load this skill when deciding what belongs in each commit or PR.
+
+Use it for:
+
+- Splitting a feature into reviewable work.
+- Preparing commits before opening a PR.
+- Turning a large change into chained or stacked PRs.
+- Keeping reviewer cognitive load healthy.
+- Applying SDD tasks without accidentally producing a PR above 400 changed lines.
+
+## Critical Rules
+
+| Rule | Requirement |
+|------|-------------|
+| Commit by work unit | A commit represents a deliverable behavior, fix, migration, or docs unit. |
+| Do not commit by file type | Avoid `models`, then `services`, then `tests` if none works alone. |
+| Keep tests with code | Tests belong in the same commit as the behavior they verify. |
+| Keep docs with the user-visible change | Docs belong with the feature or workflow they explain. |
+| Tell a story | A reviewer should understand why each commit exists from its diff and message. |
+| Future PR-ready | Each commit should be a candidate chained PR when the change grows. |
+| SDD workload guard | If SDD tasks forecast a >400-line change, group commits into chained PR slices before implementation. |
+
+## Work Unit Checklist
+
+Before committing, confirm:
+
+- [ ] The commit has one clear purpose.
+- [ ] The repo still makes sense after applying only this commit.
+- [ ] Tests or docs for this unit are included when relevant.
+- [ ] Rollback is reasonable without reverting unrelated work.
+- [ ] The commit message explains the outcome, not the file list.
+
+## Split Examples
+
+| Weak split | Better work-unit split |
+|------------|------------------------|
+| `add models` | `feat(auth): add token validation domain model and tests` |
+| `add services` | `feat(auth): wire token validation into login flow` |
+| `add tests` | Tests included with each behavior commit |
+| `update docs` | Docs included with the user-facing change they explain |
+
+## PR Relationship
+
+Use work-unit commits as the foundation for chained PRs:
+
+1. Build the smallest independent work unit.
+2. Include verification for that unit.
+3. Commit it with a Conventional Commit message.
+4. If the PR approaches 400 changed lines, promote commits or groups of commits into chained PRs.
+
+## SDD Relationship
+
+When `sdd-tasks` produces a Review Workload Forecast:
+
+- Low risk: keep work-unit commits inside one PR.
+- Medium risk: commit by work unit and monitor changed lines before PR creation.
+- High risk: follow SDD `delivery_strategy` — ask on `ask-on-risk`, auto-slice on `auto-chain`, require `size:exception` on over-budget `single-pr`, or record accepted `size:exception` on `exception-ok`.
+
+Each SDD work unit should map cleanly to a commit or PR with:
+
+- clear start state,
+- clear finished state,
+- verification in the same unit,
+- rollback that does not remove unrelated work.
+
+## Commands
+
+```bash
+# Review the story before committing
+git diff --stat
+git diff --cached --stat
+
+# Check recent commit style
+git log --oneline -5
+```
+
+_Adapted from a skill originally authored by gentleman-programming._