@cristiancorreau/forge 2.9.13 → 2.10.0

package/assets/adapters/opencode/commands/session-start.md

@@ -1,62 +1,11 @@
 ---
 name: session-start
-description: Inicializa una sesión de trabajo detectando el estado del repo y enrutando según el escenario.
+description: Inicializa una sesión de trabajo siguiendo el skill central de forge.
 ---
 
-Inicializa la sesión de trabajo: detecta el estado del repo, identifica el escenario y actúa según corresponda.
+Inicializa la sesión de trabajo siguiendo el skill central `core/skills/session-start/SKILL.md`.
 
-## Paso 1 — Leer estado del repo
-
-Ejecutar los siguientes comandos y guardar sus resultados:
-
-- `git branch --show-current` → rama actual
-- `git status --short` → cambios sin commitear
-- `git log --oneline -5` → commits recientes
-- `gh pr list --author @me --state open --json number,title,headRefName 2>/dev/null` → PRs abiertos (saltar si gh no está disponible)
-- `git branch --sort=-committerdate --format='%(refname:short)' | grep -v 'HEAD' | head -8` → ramas recientes
-
-## Paso 2 — Leer configuración del proyecto
-
-- Si existe `project.yaml` en el directorio actual, leerlo para obtener: `project.mode`, `project.name`, `stack.*`, `agents.active`
-- Si existe `AGENTS.md`, leerlo para obtener contexto del proyecto
-- Si ninguno existe, continuar con defaults: mode=startup
-
-## Paso 3 — Evaluar escenario y actuar
-
-### Escenario A — Ya en una rama de feature (no es main/master/develop)
-
-- Mostrar los últimos 5 commits de esta rama para contexto
-- Mostrar archivos con cambios sin commitear si los hay
-- Reportar: "Continuando sesión en [branch]. Contexto: [mensaje del último commit]."
-- Preguntar: "¿Qué trabajamos hoy?"
-
-### Escenario B — En main/master con PRs abiertos o ramas recientes de feature
-
-- Listar los PRs abiertos del Paso 1 como menú numerado
-- Listar las ramas recientes que no sean main/master/develop del Paso 1
-- Preguntar: "¿Continuás uno de estos o arrancamos algo nuevo?"
-- Si el usuario elige continuar uno existente: hacer checkout de esa rama
-- Si el usuario quiere algo nuevo: pasar al flujo del Escenario C
-
-### Escenario C — En main/master sin trabajo previo identificado
-
-- Esperar el primer mensaje del usuario describiendo qué quiere trabajar
-- Antes de cualquier edición de código, proponer un nombre de rama siguiendo la convención:
-  - `feature/<tema-corto>-$(date +%Y-%m-%d)` para features
-  - `fix/<tema-corto>-$(date +%Y-%m-%d)` para correcciones
-  - `chore/<tema-corto>-$(date +%Y-%m-%d)` para tareas técnicas
-  - `docs/<tema-corto>-$(date +%Y-%m-%d)` para documentación
-- Crear la rama: `git checkout -b <nombre-propuesto>`
-- Confirmar: "Branch creada: [nombre]. Listo para trabajar."
-
-## Paso 4 — Recordatorio de reglas de sesión
-
-Una vez determinado el escenario, enunciar estas reglas una sola vez:
-
-"Reglas de sesión: (1) No editar código en main. (2) Conventional Commits. (3) Spec antes de implementar si el proyecto es standard/enterprise. (4) Implementar en serie — OpenCode no soporta subagentes paralelos. (5) Cerrar con /session-close."
-
-## Comportamiento adaptativo
-
-- Si `gh` no está disponible: omitir los pasos que lo requieren y agregar nota "gh no disponible — revisar PRs en GitHub.com manualmente"
-- Si `project.yaml` no existe: continuar con defaults, no interrumpir el flujo
-- Si la rama actual no sigue la convención de nombres: mencionarlo pero no bloquear
+Ejecuta sus 4 pasos en orden: (1) leer estado del repo, (2) leer `project.yaml`
+(en OpenCode, leer también `AGENTS.md` para contexto), (3) evaluar el escenario
+A/B/C y enrutar, (4) enunciar las reglas de sesión una sola vez. Recordá la regla
+extra de OpenCode: implementar en serie — OpenCode no soporta subagentes paralelos.

package/assets/core/hooks/hooks-registry.yaml

@@ -1,48 +1,35 @@
 # Forge v2 — Hooks registry
 # Define qué hooks se instalan según mode y stack del proyecto.
+# Solo se referencian hooks JavaScript puro (.js) o shell scripts (.sh):
+# sin dependencias de Python. Cada entrada debe tener un archivo real en core/hooks/.
 
 universal:
   # Se instalan en TODOS los proyectos
-  - hook: pre-edit-check.py
+  - hook: pre-edit-check.js
     event: PreToolUse
     matcher: "Edit|Write"
-    description: "Branch guard, debug detection, secret detection"
+    description: >-
+      Branch guard, debug detection, secret detection y spec gate (issue #28):
+      al editar código en una rama feature exige una spec APPROVED en
+      docs/specs/. Backward-compatible: advierte por defecto y solo bloquea con
+      mode=enterprise + rules.require_spec_before_implementation. Ver
+      docs/spec-gate-flow.md.
   - hook: post-turn-check.sh
     event: Stop
     description: "Typecheck/lint sobre archivos modificados"
+  - hook: session-start.sh
+    event: SessionStart
+    description: "Carga project.yaml + estado al iniciar la sesión"
 
 standard:
   # mode: standard + enterprise
-  - hook: pre-bash-check.py
+  - hook: pre-bash-check.js
     event: PreToolUse
     matcher: "Bash"
     description: "Bloquea comandos destructivos en producción"
 
-enterprise:
-  # mode: enterprise solamente (además de standard)
-  - hook: audit-log-append.py
-    event: PostToolUse
-    description: "Audit log inmutable para SOC2/compliance"
-
-stack:
-  # Por stack (además de los universales)
-  supabase:
-    - hook: check-destructive-sql.py
-      event: PreToolUse
-      matcher: "Bash"
-      description: "Detecta SQL destructivo contra Supabase"
-  prisma:
-    - hook: prisma-safety.py
-      event: PreToolUse
-      matcher: "Bash"
-      description: "Bloquea migrate reset en producción"
-  nextjs-admin:
-    - hook: prisma-safety.py
-      event: PreToolUse
-      matcher: "Bash"
-      description: "Bloquea prisma migrate reset/fresh en producción (aplica si el profile usa Prisma como ORM)"
-  laravel:
-    - hook: composer-check.py
-      event: PreToolUse
-      matcher: "Bash"
-      description: "Verifica que composer install/update no instale paquetes de dev en producción; advierte sobre artisan migrate:fresh/reset"
+# NOTA (issue #23): los hooks de enterprise y por stack (audit-log-append,
+# check-destructive-sql, prisma-safety, composer-check) aún no están
+# implementados como .js/.sh, por lo que se omiten del registry hasta que
+# exista una spec SDD aprobada y su implementación en core/hooks/.
+# No agregar referencias a hooks .py: la CLI corre 100% en Node.js.

package/assets/core/hooks/pre-edit-check.js

@@ -6,11 +6,57 @@
 'use strict';
 
 const { execSync } = require('child_process');
+const fs = require('fs');
 const path = require('path');
 
 const DEBUG = !['', '0', 'false', 'False'].includes(process.env.DEBUG || '');
 const dbg = msg => DEBUG && process.stdout.write(`[forge-hook-debug] ${msg}\n`);
 
+// ---------------------------------------------------------------------------
+// project.yaml — minimal loader (no YAML dependency, mirrors pre-bash-check.js)
+// Only needs `mode` and `rules.require_spec_before_implementation`, both of
+// which are flat or one-level-nested scalars.
+// ---------------------------------------------------------------------------
+function findRepoRoot(start) {
+  let dir = start;
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'project.yaml'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return start;
+}
+
+function loadProjectYaml() {
+  try {
+    let dir = process.cwd();
+    for (let i = 0; i < 8; i++) {
+      const candidate = path.join(dir, 'project.yaml');
+      if (fs.existsSync(candidate)) {
+        return { text: fs.readFileSync(candidate, 'utf8'), root: dir };
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch (e) { dbg(`project.yaml load error: ${e}`); }
+  return { text: '', root: findRepoRoot(process.cwd()) };
+}
+
+// Match either a top-level `mode: enterprise` or a nested `project.mode`.
+function isEnterpriseMode(text) {
+  return /^\s*mode\s*:\s*["']?enterprise["']?/m.test(text || '');
+}
+
+// The hard gate is opt-in: only escalates to a block when the project
+// explicitly enables `rules.require_spec_before_implementation`.
+function specGateRequired(text) {
+  return /require_spec_before_implementation\s*:\s*(true|yes|on)\b/i.test(text || '');
+}
+
 // ---------------------------------------------------------------------------
 // File classification
 // ---------------------------------------------------------------------------
@@ -100,6 +146,49 @@ function detectSecrets(content) {
   return found;
 }
 
+// ---------------------------------------------------------------------------
+// Spec gate (issue #28) — require an APPROVED spec in docs/specs/ before code
+// edits on a feature branch. BACKWARD-COMPATIBLE: warns by default, escalates
+// to a hard block ONLY when mode=enterprise AND require_spec_before_implementation.
+// ---------------------------------------------------------------------------
+const PROTECTED_BRANCHES = new Set(['main', 'master', 'develop']);
+
+// A spec file counts as APPROVED when a status/estado header line names APPROVED
+// on its own (not the template's "DRAFT | REVIEW | APPROVED | IMPLEMENTED" menu).
+function specIsApproved(content) {
+  const lines = content.split('\n');
+  for (const line of lines) {
+    if (!/^\s*>?\s*(estado|status)\s*:/i.test(line)) continue;
+    const value = line.replace(/^\s*>?\s*(estado|status)\s*:/i, '').trim();
+    if (/\bAPPROVED\b/i.test(value) && !value.includes('|')) return true;
+  }
+  return false;
+}
+
+// Returns true when docs/specs/ holds at least one APPROVED spec.
+function hasApprovedSpec(repoRoot) {
+  const specsDir = path.join(repoRoot, 'docs', 'specs');
+  let entries;
+  try { entries = fs.readdirSync(specsDir); } catch { return false; }
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue;
+    if (name === '_template.md' || name === 'README.md') continue;
+    try {
+      if (specIsApproved(fs.readFileSync(path.join(specsDir, name), 'utf8'))) return true;
+    } catch { /* ignore unreadable spec */ }
+  }
+  return false;
+}
+
+const SPEC_GATE_MSG =
+  `forge: no se encontró una spec APPROVED en docs/specs/.\n\n` +
+  `  El flujo spec-first (SDD) exige una spec aprobada antes de editar código.\n\n` +
+  `  Para crearla:\n` +
+  `    1. cp docs/specs/_template.md docs/specs/<id>-<slug>.md\n` +
+  `    2. completá Contexto, Decisión y Criterios de aceptación\n` +
+  `    3. pasá el encabezado a "Estado: APPROVED" tras la revisión\n\n` +
+  `  Detalle del gate: docs/spec-gate-flow.md\n`;
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -136,6 +225,25 @@ process.stdin.on('end', () => {
       );
       process.exit(2);
     }
+
+    // 1b. Spec gate — require an APPROVED spec on feature branches.
+    if (!PROTECTED_BRANCHES.has(branch) && branch) {
+      const { text, root } = loadProjectYaml();
+      if (!hasApprovedSpec(root)) {
+        const block = isEnterpriseMode(text) && specGateRequired(text);
+        dbg(`spec gate: no APPROVED spec — ${block ? 'BLOCK (enterprise)' : 'WARN'}`);
+        if (block) {
+          process.stdout.write(SPEC_GATE_MSG);
+          process.exit(2);
+        }
+        warnings.push(
+          `Spec gate: no hay una spec APPROVED en docs/specs/.\n` +
+          `    El flujo spec-first lo recomienda antes de editar código.\n` +
+          `    (Solo advertencia; se vuelve bloqueante con mode=enterprise +\n` +
+          `     rules.require_spec_before_implementation. Ver docs/spec-gate-flow.md)`
+        );
+      }
+    }
   }
 
   // 2. Debug and secret detection on new content

package/assets/core/schemas/project.schema.json

@@ -160,6 +160,11 @@
           "type": ["array", "null"],
           "items": { "type": "string" }
         },
+        "specialized": {
+          "description": "Agentes Tier 3 (de dominio) propios del proyecto, que viven en .claude/agents/ y no provienen de forge",
+          "type": ["array", "null"],
+          "items": { "type": "string" }
+        },
         "profiles": {
           "description": "Profiles stack-específicos (Tier 2) que reemplazan agentes genéricos",
           "type": ["array", "null"],

package/assets/core/skills/README.md

@@ -3,6 +3,8 @@
 ## Mapa de skills y dependencias
 
 ```
+session-start  →  (sesión de trabajo)  →  session-close
+                        │
 new-feature ──────────────────────────────────────────────────┐
 │                                                              │
 ├── spec              (Fase 1 — verificar/crear spec)          │
@@ -26,6 +28,8 @@ wiki-lint   → health check + auto-reparación
 
 | Skill | Categoría | Requiere herramienta externa | Invocado por |
 |-------|-----------|------------------------------|--------------|
+| `session-start` | Sesión | No (`gh` opcional) | Usuario directo |
+| `session-close` | Sesión | No (`gh` opcional) | Usuario directo |
 | `spec` | Core | No | new-feature, orchestrator |
 | `phase-kickoff` | Core | No | orchestrator, new-feature |
 | `security-audit` | Universal | No | new-feature, security-auditor |
@@ -40,6 +44,11 @@ wiki-lint   → health check + auto-reparación
 
 ## Categorías
 
+### Sesión — bookend del flujo de trabajo
+Generan los slash commands `/session-start` y `/session-close`. Abren y cierran el ciclo SDD:
+- **`session-start`**: detecta el estado del repo y enruta según el escenario (rama activa, main con PRs, main limpio)
+- **`session-close`**: pipeline de 8 pasos (commit → changeset → GitHub Projects → daily note → RELEASE-NOTES → cierre → sync → PR)
+
 ### Core — siempre presentes
 - **`spec`**: redactar specs siguiendo la plantilla obligatoria
 - **`phase-kickoff`**: protocolo para iniciar un sprint o fase nueva

package/assets/core/skills/session-close/SKILL.md

@@ -0,0 +1,137 @@
+# Skill: session-close
+
+Cierra la sesión de trabajo con un pipeline de 8 pasos: commit, changeset,
+GitHub Projects, daily note, release notes, commit de cierre, sync y PR. Es el
+último paso del flujo de trabajo SDD.
+
+Triggers: /session-close, "cerrar sesión", "terminar sesión", "cerrar el día"
+
+---
+
+## Cuándo usar este skill
+
+- Al terminar de trabajar en una rama de feature
+- Para dejar la rama lista para PR (commit, daily note, sync con main)
+- Para registrar progreso y cerrar issues trabajados en la sesión
+
+No usar para iniciar la sesión — para eso está `session-start`.
+
+---
+
+## Paso 1 — Verificar estado
+
+Ejecutar `git status --short` y `git diff --stat HEAD 2>/dev/null`. Reportar qué hay pendiente.
+
+## Paso 2 — Commitear cambios pendientes
+
+Si hay cambios sin commitear:
+
+- Preguntar al usuario: "¿Qué describe este commit? (usa Conventional Commits: feat/fix/chore/docs/refactor/test)"
+- Commitear con: `git add -A && git commit -m "<type>(<scope>): <descripción>"`
+- Incluir siempre en el cuerpo del commit el `Co-Authored-By` del runtime activo
+
+Si no hay nada que commitear: indicar "Nada pendiente de commitear." y continuar.
+
+## Paso 3 — Changeset (condicional)
+
+Si el commit del Paso 2 fue de tipo `feat:` o `fix:` Y `package.json` contiene `"@changesets/cli"`:
+
+- Ejecutar `npx changeset` para generar el changeset
+
+En cualquier otro caso, omitir este paso sin mencionarlo.
+
+## Paso 4 — GitHub Projects (condicional)
+
+Leer `project.yaml`. Si tiene una sección `github.project` con `number`, `owner` y `repo`:
+
+- Preguntar: "¿Qué issues trabajaste en esta sesión? (números separados por coma, o Enter para saltar)"
+- Si el usuario provee números: ejecutar `gh issue close <N> --comment "Completado en esta sesión"` para cada uno
+- Mover los issues a Done en el proyecto si es posible con gh CLI
+
+Si `project.yaml` no tiene sección `github.project`: indicar "GitHub Projects no configurado en project.yaml." y continuar.
+
+## Paso 5 — Daily note
+
+Crear el directorio `docs/daily-notes/` si no existe.
+
+Determinar:
+- `FECHA`: resultado de `date +%Y-%m-%d`
+- `TEMA`: derivado del nombre de la rama actual, eliminando el prefijo de tipo y el sufijo de fecha (ej: `feature/billing-webpay-2026-05-16` → `billing-webpay`)
+
+Crear el archivo `docs/daily-notes/FECHA-TEMA.md` con este contenido:
+
+```
+# Session FECHA — TEMA
+
+## Completado
+[listar qué se implementó o cambió en esta sesión]
+
+## Archivos modificados
+[output de: git diff --name-only HEAD~1..HEAD 2>/dev/null || git diff --name-only HEAD 2>/dev/null]
+
+## Commits
+[output de: git log --oneline HEAD~3..HEAD]
+
+## Decisiones tomadas
+[preguntar al usuario: "¿Alguna decisión de diseño o arquitectura que vale registrar?"]
+
+## Blockers para próxima sesión
+[preguntar al usuario: "¿Quedó algo bloqueado o incompleto?"]
+```
+
+Completar las secciones "Archivos modificados" y "Commits" con los outputs reales. Completar "Completado", "Decisiones tomadas" y "Blockers" con las respuestas del usuario.
+
+## Paso 6 — RELEASE-NOTES.md
+
+Agregar al final de `RELEASE-NOTES.md` (crear si no existe):
+
+```
+## FECHA — TEMA
+[resumen en una línea de qué cambió]
+```
+
+Usar el resumen de la daily note para redactar la línea.
+
+## Paso 7 — Commit de cierre
+
+Commitear los archivos generados:
+
+```
+git add docs/daily-notes/ RELEASE-NOTES.md && git commit -m "docs(progress): session close FECHA — TEMA"
+```
+
+## Paso 8 — Sync y PR
+
+Ejecutar:
+
+```
+git fetch origin main
+git log HEAD..origin/main --oneline
+```
+
+- Si main tiene commits nuevos: ejecutar `git rebase origin/main` y luego `git push --force-with-lease origin <rama-actual>`
+- Si main no tiene cambios nuevos: ejecutar `git push -u origin <rama-actual>`
+
+Luego crear el PR:
+
+```
+gh pr create --title "<resumen de cambios>" --body "<resumen de sesión tomado de la daily note>"
+```
+
+Si `gh` no está disponible: hacer solo el push y recordar al usuario "Crea el PR manualmente en GitHub."
+
+## Al finalizar el pipeline
+
+Confirmar con: "Sesión cerrada. PR creado: [URL]" o, si gh no estuvo disponible: "Sesión cerrada. Push hecho a [branch] — crea el PR en GitHub."
+
+---
+
+## Relación con otros skills
+
+`session-close` cierra el ciclo que abre `session-start`. El Paso 8 (sync + PR)
+es equivalente al deploy de `local2prod` cuando el proyecto publica desde main;
+si ya usaste `local2prod` en la sesión, podés saltear el push y solo abrir el PR.
+
+```
+session-start  →  new-feature  →  session-close (commit → … → sync → PR)
+```

package/assets/core/skills/session-start/SKILL.md

@@ -0,0 +1,86 @@
+# Skill: session-start
+
+Inicializa una sesión de trabajo: detecta el estado del repo, identifica el
+escenario y enruta según corresponda. Es el primer paso del flujo de trabajo
+SDD, antes de cualquier edición de código.
+
+Triggers: /session-start, "iniciar sesión", "arrancar sesión", "empezar a trabajar"
+
+---
+
+## Cuándo usar este skill
+
+- Al abrir el editor/agente y comenzar a trabajar en el repo
+- Para retomar una rama de feature en progreso
+- Para decidir si continuar un PR abierto o arrancar algo nuevo
+
+No usar para cerrar la sesión — para eso está `session-close`.
+
+---
+
+## Paso 1 — Leer estado del repo
+
+Ejecutar los siguientes comandos y guardar sus resultados:
+
+- `git branch --show-current` → rama actual
+- `git status --short` → cambios sin commitear
+- `git log --oneline -5` → commits recientes
+- `gh pr list --author @me --state open --json number,title,headRefName 2>/dev/null` → PRs abiertos (saltar si gh no está disponible)
+- `git branch --sort=-committerdate --format='%(refname:short)' | grep -v 'HEAD' | head -8` → ramas recientes
+
+## Paso 2 — Leer configuración del proyecto
+
+- Si existe `project.yaml` en el directorio actual, leerlo para obtener: `project.mode`, `project.name`, `stack.*`, `agents.active`
+- Si existe `wiki/index.md`, leerlo para obtener contexto del proyecto
+- Si ninguno existe, continuar con defaults: mode=startup, sin checks de compliance
+
+## Paso 3 — Evaluar escenario y actuar
+
+### Escenario A — Ya en una rama de feature (no es main/master/develop)
+
+- Mostrar los últimos 5 commits de esta rama para contexto
+- Mostrar archivos con cambios sin commitear si los hay
+- Reportar: "Continuando sesión en [branch]. Contexto: [mensaje del último commit]."
+- Preguntar: "¿Qué trabajamos hoy?"
+
+### Escenario B — En main/master con PRs abiertos o ramas recientes de feature
+
+- Listar los PRs abiertos del Paso 1 como menú numerado
+- Listar las ramas recientes que no sean main/master/develop del Paso 1
+- Preguntar: "¿Continuás uno de estos o arrancamos algo nuevo?"
+- Si el usuario elige continuar uno existente: hacer checkout de esa rama
+- Si el usuario quiere algo nuevo: pasar al flujo del Escenario C
+
+### Escenario C — En main/master sin trabajo previo identificado
+
+- Esperar el primer mensaje del usuario describiendo qué quiere trabajar
+- Antes de cualquier edición de código, proponer un nombre de rama siguiendo la convención:
+  - `feature/<tema-corto>-$(date +%Y-%m-%d)` para features
+  - `fix/<tema-corto>-$(date +%Y-%m-%d)` para correcciones
+  - `chore/<tema-corto>-$(date +%Y-%m-%d)` para tareas técnicas
+  - `docs/<tema-corto>-$(date +%Y-%m-%d)` para documentación
+- Crear la rama: `git checkout -b <nombre-propuesto>`
+- Confirmar: "Branch creada: [nombre]. Listo para trabajar."
+
+## Paso 4 — Recordatorio de reglas de sesión
+
+Una vez determinado el escenario, enunciar estas reglas una sola vez:
+
+"Reglas de sesión: (1) No editar código en main. (2) Conventional Commits. (3) Spec antes de implementar si el proyecto es standard/enterprise. (4) Cerrar con /session-close."
+
+## Comportamiento adaptativo
+
+- Si `gh` no está disponible: omitir los pasos que lo requieren y agregar nota "gh no disponible — revisar PRs en GitHub.com manualmente"
+- Si `project.yaml` no existe: continuar con defaults, no interrumpir el flujo
+- Si la rama actual no sigue la convención de nombres: mencionarlo pero no bloquear
+
+---
+
+## Relación con otros skills
+
+`session-start` abre el ciclo de trabajo; `session-close` lo cierra. Entre ambos,
+`new-feature` orquesta la implementación (spec → seguridad → migración → deploy).
+
+```
+session-start  →  new-feature (spec, security-audit, db-migrate, …)  →  session-close
+```

package/assets/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "forge",
-  "version": "2.0.1",
+  "version": "2.10.0",
   "description": "Agentic development framework for Claude Code",
   "license": "Apache-2.0",
   "repository": "https://github.com/cristiancorreau/forge",

package/dist/cli.js

@@ -10,6 +10,7 @@ import { skills } from './commands/skills.js';
 import { aitmplSearch } from './commands/aitmpl-search.js';
 import { scaffold } from './commands/scaffold.js';
 import { teardown } from './commands/teardown.js';
+import { sessionStart, sessionClose } from './commands/session.js';
 import { VERSION } from './version.js';
 const HELP = `forge v${VERSION} — Agentic development framework
 
@@ -19,7 +20,7 @@ Setup
   init           Initialize forge in a project (wizard + post-install dashboard)
   generate       Generate runtime config files from project.yaml
   migrate        Migrate project.yaml from the v1 schema to v2 (--dry-run, --backup)
-  scaffold       Scaffold a new Tier 2 profile (profiles/<stack>/agents/<engineer>.md)
+  scaffold       Scaffold a new agent: Tier 2 profile, or Tier 3 domain agent (--tier 3)
   teardown       Cleanly uninstall forge from a project (manifest-driven)
 
 Inspect
@@ -29,6 +30,10 @@ Inspect
   skills         List available forge skills grouped by category
   aitmpl-search  Search the curated offline catalog (frameworks, MCP servers, profiles)
 
+Workflow
+  session-start  Open a work session (prints the /session-start skill steps)
+  session-close  Close a work session (prints the /session-close skill steps)
+
 Knowledge
   wiki           Manage the project knowledge base (status | ingest | query | lint)
 
@@ -81,6 +86,12 @@ switch (cmd) {
     case 'teardown':
         exitCode = await teardown(rest);
         break;
+    case 'session-start':
+        exitCode = await sessionStart(rest);
+        break;
+    case 'session-close':
+        exitCode = await sessionClose(rest);
+        break;
     case '-v':
     case '--version':
         console.log(VERSION);

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,IAAI,GAAG,UAAU,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiC7B,CAAC;AAEF,MAAM,CAAC,EAAE,AAAD,EAAG,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;AAExC,IAAI,QAAQ,GAAG,CAAC,CAAC;AAEjB,QAAQ,GAAG,EAAE,CAAC;IACZ,KAAK,MAAM;QACT,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM;IACR,KAAK,OAAO;QACV,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,MAAM;IACR,KAAK,UAAU;QACb,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM;IACR,KAAK,UAAU;QACb,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM;IACR,KAAK,QAAQ;QACX,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM;IACR,KAAK,SAAS;QACZ,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM;IACR,KAAK,MAAM;QACT,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM;IACR,KAAK,QAAQ;QACX,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM;IACR,KAAK,eAAe;QAClB,QAAQ,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM;IACR,KAAK,UAAU;QACb,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM;IACR,KAAK,UAAU;QACb,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM;IACR,KAAK,IAAI,CAAC;IACV,KAAK,WAAW;QACd,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrB,MAAM;IACR,KAAK,SAAS,CAAC;IACf,KAAK,IAAI,CAAC;IACV,KAAK,QAAQ;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3B,MAAM;IACR;QACE,OAAO,CAAC,KAAK,CAAC,oBAAoB,GAAG,iCAAiC,CAAC,CAAC;QACxE,QAAQ,GAAG,CAAC,CAAC;AACjB,CAAC;AAED,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/commands/audit.ts"],"names":[],"mappings":"AA0NA,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA4J3D"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/commands/audit.ts"],"names":[],"mappings":"AA0NA,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuK3D"}

package/dist/commands/audit.js

@@ -263,6 +263,17 @@ export async function audit(args) {
                     issues.push(...agentIssues);
                 }
             }
+            // Tier 3: cada agente declarado en agents.specialized debe tener su archivo.
+            const specialized = config?.agents?.specialized ?? [];
+            for (const name of specialized) {
+                const file = join(agentsDir, `${name}.md`);
+                if (existsSync(file)) {
+                    issues.push({ level: 'ok', check: 'specialized', message: `Tier 3 '${name}' declarado y presente en .claude/agents/` });
+                }
+                else {
+                    issues.push({ level: 'error', check: 'specialized', message: `Tier 3 '${name}' en agents.specialized pero falta .claude/agents/${name}.md` });
+                }
+            }
         }
         // Check hooks
         const hooksDir = join(root, '.claude', 'hooks');