@ronaldjdevfs/forge 1.3.0-beta → 1.3.1

package/skills/forge/templates/feature/acl-repository.ts.md

@@ -0,0 +1,36 @@
+```typescript
+// src/features/<domain>/adapters/out/legacy-<system>/<Domain>ACL.ts
+import { injectable, inject } from "tsyringe";
+import type { I<Domain>Repository } from "../../domain/I<Domain>Repository.js";
+import type { <Domain>Entity } from "../../domain/<Domain>Entity.js";
+import { <Domain>Gateway } from "./<Domain>Gateway.js";
+import { <Domain>Translator } from "./<Domain>Translator.js";
+
+@injectable()
+export class <Domain>ACLRepository implements I<Domain>Repository {
+  constructor(
+    @inject(<Domain>Gateway) private readonly gateway: <Domain>Gateway,
+    @inject(<Domain>Translator) private readonly translator: <Domain>Translator,
+  ) {}
+
+  async findById(id: string): Promise<<Domain>Entity | null> {
+    try {
+      const dto = await this.gateway.fetch(id);
+      return dto ? this.translator.toDomain(dto) : null;
+    } catch (error) {
+      if (error.message.includes("404")) return null;
+      throw new Error("<Domain>Repository.fetchFailed");
+    }
+  }
+
+  async save(entity: <Domain>Entity): Promise<<Domain>Entity> {
+    const dto = this.translator.toExternal(entity);
+    const result = await this.gateway.upsert(dto);
+    return this.translator.toDomain(result);
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.gateway.remove(id);
+  }
+}
+```

package/skills/forge/templates/feature/acl-translator.ts.md

@@ -0,0 +1,24 @@
+```typescript
+// src/features/<domain>/adapters/out/legacy-<system>/<Domain>Translator.ts
+import type { <Domain>Entity } from "../../../domain/<Domain>Entity.js";
+import type { External<Domain>DTO } from "./External<Domain>DTO.js";
+
+export class <Domain>Translator {
+  toDomain(dto: External<Domain>DTO): <Domain>Entity {
+    return {
+      id: dto.externalId,
+      // mapear campos del DTO externo al modelo de dominio
+      // name: dto.fullName,
+      // email: dto.emailAddress,
+      // status: dto.isActive ? "active" : "inactive",
+    } as <Domain>Entity;
+  }
+
+  toExternal(entity: <Domain>Entity): External<Domain>DTO {
+    return {
+      externalId: entity.id,
+      // mapear campos del dominio al DTO externo
+    } as External<Domain>DTO;
+  }
+}
+```

package/skills/forge/templates/feature/cqrs-query.ts.md

@@ -0,0 +1,40 @@
+```typescript
+// src/features/<domain>/application/queries/Get<Domain>Query.ts
+import { injectable, inject } from "tsyringe";
+import type { I<Domain>ReadRepository } from "../../adapters/out/read/I<Domain>ReadRepository.js";
+
+export type <Domain>QueryResult = {
+  // DTO plano desnormalizado para lectura
+  id: string;
+  // campos optimizados para consulta
+};
+
+@injectable()
+export class Get<Domain>Query {
+  constructor(
+    @inject(I<Domain>ReadRepository)
+    private readonly readRepo: I<Domain>ReadRepository,
+  ) {}
+
+  async execute(id: string): Promise<<Domain>QueryResult | null> {
+    return this.readRepo.findById(id);
+  }
+}
+
+// Query con filtros
+export class List<Domain>Query {
+  constructor(
+    @inject(I<Domain>ReadRepository)
+    private readonly readRepo: I<Domain>ReadRepository,
+  ) {}
+
+  async execute(filters: {
+    page?: number;
+    limit?: number;
+    sort?: string;
+    filter?: Record<string, string>;
+  }): Promise<{ data: <Domain>QueryResult[]; total: number }> {
+    return this.readRepo.findMany(filters);
+  }
+}
+```

package/skills/forge/templates/feature/outbox-repository.ts.md

@@ -0,0 +1,36 @@
+```typescript
+// src/features/<domain>/adapters/out/persistence/<Domain>OutboxRepository.ts
+import { injectable } from "tsyringe";
+import type { DomainEvent } from "../../../domain/events/DomainEvent.js";
+
+export type OutboxEntry = {
+  id: string;
+  eventType: string;
+  aggregateId: string;
+  aggregateType: string;
+  payload: Record<string, unknown>;
+  occurredAt: Date;
+  processedAt: Date | null;
+  retryCount: number;
+  lastError: string | null;
+};
+
+@injectable()
+export class <Domain>OutboxRepository {
+  async add(event: DomainEvent): Promise<void> {
+    // Implementar: INSERT en tabla outbox dentro de la transacción actual
+    // const entry: OutboxEntry = {
+    //   id: crypto.randomUUID(),
+    //   eventType: event.constructor.name,
+    //   aggregateId: event.aggregateId,
+    //   aggregateType: "<Domain>",
+    //   payload: JSON.parse(JSON.stringify(event)),
+    //   occurredAt: new Date(),
+    //   processedAt: null,
+    //   retryCount: 0,
+    //   lastError: null,
+    // };
+    // await this.db.outbox.create({ data: entry });
+  }
+}
+```

package/skills/forge/templates/feature/saga-orchestrator.ts.md

@@ -0,0 +1,72 @@
+```typescript
+// src/features/<domain>/adapters/out/saga/SagaOrchestrator.ts
+import { injectable, inject } from "tsyringe";
+import type { SagaInstance, SagaStatus } from "../../domain/SagaInstance.entity.js";
+import type { ISagaRepository } from "../../domain/ISagaRepository.js";
+import type { IEventBus } from "@/platform/events/IEventBus.js";
+import type { ILogger } from "@/platform/logger/ILogger.js";
+
+export interface SagaStep {
+  name: string;
+  execute(ctx: Record<string, unknown>): Promise<void>;
+  compensate(ctx: Record<string, unknown>): Promise<void>;
+}
+
+@injectable()
+export class SagaOrchestrator {
+  constructor(
+    @inject(ISagaRepository) private readonly sagaRepo: ISagaRepository,
+    @inject(IEventBus) private readonly eventBus: IEventBus,
+    @inject(ILogger) private readonly logger: ILogger,
+  ) {}
+
+  async execute(
+    sagaType: string,
+    steps: SagaStep[],
+    initialContext: Record<string, unknown>,
+  ): Promise<string> {
+    const saga = SagaInstance.start(sagaType, initialContext);
+    await this.sagaRepo.save(saga);
+
+    for (const step of steps) {
+      try {
+        this.logger.info(`Saga ${saga.id}: executing step ${step.name}`);
+        await step.execute(saga.context);
+        saga.advance(step.name);
+        await this.sagaRepo.save(saga);
+      } catch (error) {
+        this.logger.error(
+          `Saga ${saga.id}: step ${step.name} failed — ${error.message}`,
+        );
+        await this.compensate(saga, steps);
+        return saga.id;
+      }
+    }
+
+    saga.complete();
+    await this.sagaRepo.save(saga);
+    this.eventBus.publish({ type: "saga.completed", sagaId: saga.id });
+    return saga.id;
+  }
+
+  private async compensate(
+    saga: SagaInstance,
+    steps: SagaStep[],
+  ): Promise<void> {
+    const executed = steps.slice(0, saga.currentStepIndex);
+    for (const step of executed.reverse()) {
+      try {
+        this.logger.info(`Saga ${saga.id}: compensating step ${step.name}`);
+        await step.compensate(saga.context);
+      } catch (err) {
+        this.logger.error(
+          `Saga ${saga.id}: compensation failed for ${step.name} — requiere intervención manual`,
+        );
+        saga.requireManualIntervention(step.name, err.message);
+      }
+    }
+    saga.fail();
+    await this.sagaRepo.save(saga);
+  }
+}
+```

package/skills/forge/templates/platform/outbox-relayer.ts.md

@@ -0,0 +1,80 @@
+```typescript
+// src/platform/scheduler/OutboxRelayer.ts
+import { injectable, inject } from "tsyringe";
+import type { IEventBus } from "@/platform/events/IEventBus.js";
+import type { ILogger } from "@/platform/logger/ILogger.js";
+
+type OutboxEntry = {
+  id: string;
+  eventType: string;
+  payload: Record<string, unknown>;
+  retryCount: number;
+};
+
+@injectable()
+export class OutboxRelayer {
+  private readonly POLL_INTERVAL_MS = 1000;
+  private readonly MAX_RETRIES = 10;
+  private readonly BATCH_SIZE = 50;
+  private running = false;
+
+  constructor(
+    @inject(IEventBus) private readonly eventBus: IEventBus,
+    @inject(ILogger) private readonly logger: ILogger,
+  ) {}
+
+  async start(): Promise<void> {
+    this.running = true;
+    this.logger.info("OutboxRelayer started");
+    while (this.running) {
+      await this.processBatch();
+      await this.sleep(this.POLL_INTERVAL_MS);
+    }
+  }
+
+  stop(): void {
+    this.running = false;
+    this.logger.info("OutboxRelayer stopped");
+  }
+
+  private async processBatch(): Promise<void> {
+    const batch = await this.fetchUnprocessed();
+    for (const entry of batch) {
+      try {
+        await this.eventBus.publish(entry.payload);
+        await this.markProcessed(entry.id);
+      } catch (error) {
+        this.logger.error(`Outbox ${entry.id}: publish failed — ${error.message}`);
+        await this.incrementRetry(entry.id, error.message);
+        if (entry.retryCount >= this.MAX_RETRIES) {
+          await this.sendToDLQ(entry);
+        }
+      }
+    }
+  }
+
+  private async fetchUnprocessed(): Promise<OutboxEntry[]> {
+    // SELECT * FROM outbox WHERE processed_at IS NULL
+    //   AND retry_count < $1 ORDER BY occurred_at ASC LIMIT $2
+    return [];
+  }
+
+  private async markProcessed(id: string): Promise<void> {
+    // UPDATE outbox SET processed_at = NOW() WHERE id = $1
+  }
+
+  private async incrementRetry(id: string, error: string): Promise<void> {
+    // UPDATE outbox SET retry_count = retry_count + 1, last_error = $1 WHERE id = $2
+  }
+
+  private async sendToDLQ(entry: OutboxEntry): Promise<void> {
+    this.logger.error(`Outbox ${entry.id}: moved to DLQ after ${this.MAX_RETRIES} retries`);
+    // INSERT INTO outbox_dlq SELECT * FROM outbox WHERE id = $1
+    // DELETE FROM outbox WHERE id = $1
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+```

package/skills/forge/tests/core.test.mjs

@@ -125,6 +125,9 @@ describe("profile.mjs", () => {
 });
 
 describe("graph.mjs", () => {
+  before(() => scaffoldProject({}));
+  after(() => cleanup());
+
   it("builds an empty graph for an empty project", async () => {
     const { buildGraph } = await import("../scripts/graph.mjs");
     const graph = buildGraph(process.cwd());
@@ -138,6 +141,9 @@ describe("graph.mjs", () => {
 });
 
 describe("armorer.mjs", () => {
+  before(() => scaffoldProject({}));
+  after(() => cleanup());
+
   it("builds a healthy report for an empty project", async () => {
     const { buildOwnershipReport } = await import("../scripts/armorer.mjs");
     const report = buildOwnershipReport(process.cwd());
@@ -180,6 +186,9 @@ describe("forge-config.mjs", () => {
 });
 
 describe("chain.mjs", () => {
+  before(() => scaffoldProject({}));
+  after(() => cleanup());
+
   it("builds an empty dependency graph for empty project", async () => {
     const { buildDependencyGraph } = await import("../scripts/chain.mjs");
     const graph = buildDependencyGraph();
@@ -318,10 +327,13 @@ describe("detect.mjs — inline ignores", () => {
   });
 });
 
-describe("forgeSentinel.mjs", () => {
-  it("runSentinelCheck returns empty for no files", async () => {
-    const { runSentinelCheck } = await import("../scripts/forgeSentinel-lib.mjs");
-    const result = await runSentinelCheck([], {});
+describe("posttool.mjs", () => {
+  before(() => scaffoldProject({}));
+  after(() => cleanup());
+
+  it("postToolCheck returns empty for no files", async () => {
+    const { postToolCheck } = await import("../scripts/posttool.mjs");
+    const result = await postToolCheck([], {});
     assert.equal(result.total, 0);
     assert.ok(result.summary);
   });
@@ -401,3 +413,275 @@ describe("assay.mjs", () => {
     assert.ok(opinion.includes("R1") || opinion.includes("R8") || opinion.includes("acoplamiento") || opinion.includes("importan"));
   });
 });
+
+describe("transactional-outbox pattern", () => {
+  it("outbox entry tracks lifecycle states", () => {
+    const entry = { id: "1", eventType: "OrderPlaced", processedAt: null, retryCount: 0, lastError: null };
+    assert.equal(entry.processedAt, null);
+    assert.equal(entry.retryCount, 0);
+
+    entry.processedAt = new Date();
+    entry.retryCount = 2;
+    entry.lastError = "timeout";
+    assert.ok(entry.processedAt instanceof Date);
+    assert.equal(entry.retryCount, 2);
+  });
+
+  it("retry policy respects max retries and backoff", () => {
+    const maxRetries = 3;
+    const baseDelay = 100;
+    let attempts = 0;
+
+    async function executeWithRetry(fn) {
+      for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+          return await fn();
+        } catch (error) {
+          if (attempt === maxRetries) throw error;
+          // exponential backoff: baseDelay * 2^(attempt-1)
+          const delay = baseDelay * Math.pow(2, attempt - 1);
+          // not actually waiting in test
+          void delay;
+        }
+      }
+    }
+
+    assert.rejects(async () => {
+      await executeWithRetry(() => Promise.reject(new Error("fail")));
+    }, /fail/);
+  });
+
+  it("outbox relayer moves event to DLQ after exceeding retries", () => {
+    const MAX_RETRIES = 10;
+    const entry = { id: "bad-event", retryCount: 9 };
+    assert.ok(entry.retryCount < MAX_RETRIES);
+
+    entry.retryCount++;
+    assert.equal(entry.retryCount, 10);
+
+    const shouldGoToDLQ = entry.retryCount >= MAX_RETRIES;
+    assert.ok(shouldGoToDLQ);
+  });
+
+  it("outbox entry requires event_id, aggregate_id, and payload", () => {
+    const validEntry = {
+      id: crypto.randomUUID(),
+      eventType: "OrderPlaced",
+      aggregateId: "order-123",
+      aggregateType: "Order",
+      payload: { total: 100 },
+      occurredAt: new Date(),
+      processedAt: null,
+      retryCount: 0,
+      lastError: null,
+    };
+    assert.ok(validEntry.id);
+    assert.ok(validEntry.aggregateId);
+    assert.ok(validEntry.payload);
+    assert.equal(validEntry.eventType, "OrderPlaced");
+  });
+
+  it("processed outbox entries are no longer picked up by relayer", () => {
+    const unprocessed = { processedAt: null };
+    const processed = { processedAt: new Date() };
+
+    const isPending = (entry) => entry.processedAt === null;
+    assert.ok(isPending(unprocessed));
+    assert.ok(!isPending(processed));
+  });
+});
+
+describe("idempotency pattern", () => {
+  it("idempotency key must be a valid UUID", () => {
+    function isValidUUID(key) {
+      return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(key);
+    }
+
+    assert.ok(isValidUUID("550e8400-e29b-41d4-a716-446655440000"));
+    assert.ok(!isValidUUID("not-a-uuid"));
+    assert.ok(!isValidUUID(""));
+  });
+
+  it("same idempotency key returns cached response", async () => {
+    const cache = new Map();
+
+    async function handleRequest(key, handler) {
+      if (cache.has(key)) return cache.get(key);
+      const result = await handler();
+      cache.set(key, result);
+      return result;
+    }
+
+    let callCount = 0;
+    async function processPayment() {
+      callCount++;
+      return { status: "success", transactionId: "txn-1" };
+    }
+
+    const key = "550e8400-e29b-41d4-a716-446655440000";
+    const result1 = await handleRequest(key, processPayment);
+    const result2 = await handleRequest(key, processPayment);
+
+    assert.equal(result1.status, "success");
+    assert.equal(result2.status, "success");
+    assert.equal(callCount, 1); // solo se ejecutó una vez
+  });
+
+  it("different idempotency keys create separate resources", async () => {
+    const store = new Map();
+
+    async function createResource(key, data) {
+      if (store.has(key)) return store.get(key);
+      const resource = { id: crypto.randomUUID(), ...data };
+      store.set(key, resource);
+      return resource;
+    }
+
+    const r1 = await createResource("key-1", { name: "A" });
+    const r2 = await createResource("key-2", { name: "B" });
+
+    assert.notEqual(r1.id, r2.id);
+  });
+
+  it("idempotency key has TTL and expires", () => {
+    const entry = { key: "test", createdAt: new Date() };
+    const TTL_MS = 24 * 60 * 60 * 1000; // 24 horas
+
+    function isExpired(entry) {
+      return Date.now() - entry.createdAt.getTime() > TTL_MS;
+    }
+
+    assert.ok(!isExpired(entry)); // creado ahora, no ha expirado
+
+    const oldEntry = { key: "old", createdAt: new Date(Date.now() - TTL_MS - 1) };
+    assert.ok(isExpired(oldEntry));
+  });
+
+  it("only POST, PATCH, PUT need idempotency keys", () => {
+    const methods = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+    const needsKey = (method) => ["POST", "PATCH", "PUT"].includes(method);
+
+    assert.ok(!needsKey("GET"));
+    assert.ok(needsKey("POST"));
+    assert.ok(needsKey("PUT"));
+    assert.ok(needsKey("PATCH"));
+    assert.ok(!needsKey("DELETE"));
+  });
+});
+
+describe("anti-corruption-layer pattern", () => {
+  it("translator maps external DTO to domain entity", () => {
+    class CustomerTranslator {
+      toDomain(dto) {
+        return {
+          id: dto.customerId,
+          name: `${dto.firstName} ${dto.lastName}`,
+          email: dto.emailAddress,
+          status: dto.active ? "active" : "inactive",
+        };
+      }
+    }
+
+    const externalDTO = {
+      customerId: "ext-123",
+      firstName: "John",
+      lastName: "Doe",
+      emailAddress: "john@example.com",
+      active: true,
+    };
+
+    const translator = new CustomerTranslator();
+    const entity = translator.toDomain(externalDTO);
+
+    assert.equal(entity.id, "ext-123");
+    assert.equal(entity.name, "John Doe");
+    assert.equal(entity.email, "john@example.com");
+    assert.equal(entity.status, "active");
+  });
+
+  it("translator maps domain entity back to external DTO", () => {
+    class CustomerTranslator {
+      toExternal(entity) {
+        return {
+          customerId: entity.id,
+          firstName: entity.name.split(" ")[0],
+          lastName: entity.name.split(" ").slice(1).join(" "),
+          emailAddress: entity.email,
+          active: entity.status === "active",
+        };
+      }
+    }
+
+    const entity = {
+      id: "dom-456",
+      name: "Jane Smith",
+      email: "jane@example.com",
+      status: "active",
+    };
+
+    const translator = new CustomerTranslator();
+    const dto = translator.toExternal(entity);
+
+    assert.equal(dto.customerId, "dom-456");
+    assert.equal(dto.firstName, "Jane");
+    assert.equal(dto.lastName, "Smith");
+    assert.equal(dto.active, true);
+  });
+
+  it("translator handles null/missing values gracefully", () => {
+    class CustomerTranslator {
+      toDomain(dto) {
+        return {
+          id: dto.customerId ?? "unknown",
+          name: dto.firstName ? `${dto.firstName} ${dto.lastName ?? ""}`.trim() : "Unknown",
+          email: dto.emailAddress ?? "",
+          status: dto.active === true ? "active" : "inactive",
+        };
+      }
+    }
+
+    const emptyDTO = { customerId: null, firstName: null, lastName: null, emailAddress: null, active: null };
+    const translator = new CustomerTranslator();
+    const entity = translator.toDomain(emptyDTO);
+
+    assert.equal(entity.id, "unknown");
+    assert.equal(entity.name, "Unknown");
+    assert.equal(entity.status, "inactive");
+  });
+
+  it("gateway enforces timeout and returns null on 404", () => {
+    async function fetchCustomer(id) {
+      const response = { status: 404, ok: false, statusText: "Not Found" };
+      if (response.status === 404) return null;
+      if (!response.ok) throw new Error(response.statusText);
+      return { id };
+    }
+
+    assert.doesNotReject(async () => {
+      const result = await fetchCustomer("nonexistent");
+      assert.equal(result, null);
+    });
+  });
+
+  it("ACL delegates to translator and gateway in correct order", async () => {
+    let order = [];
+
+    const gateway = {
+      async fetch(id) { order.push("gateway"); return { customerId: id, firstName: "A", lastName: "B", emailAddress: "a@b.com", active: true }; },
+    };
+
+    const translator = {
+      toDomain(dto) { order.push("translator"); return { id: dto.customerId, name: `${dto.firstName} ${dto.lastName}`, email: dto.emailAddress, status: "active" }; },
+    };
+
+    async function findById(id) {
+      const dto = await gateway.fetch(id);
+      return dto ? translator.toDomain(dto) : null;
+    }
+
+    const result = await findById("123");
+    assert.deepEqual(order, ["gateway", "translator"]);
+    assert.equal(result.id, "123");
+    assert.equal(result.name, "A B");
+  });
+});

package/src/cli.js

@@ -86,16 +86,20 @@ function ensureDependencies(configDir) {
 }
 
 const COMMANDS = [
-  { name: "forge-forge", desc: "Forge — inicializar proyecto arquitectónicamente" },
-  { name: "forge-cast", desc: "Cast — crear un nuevo feature hexagonal desde cero" },
-  { name: "forge-inspect", desc: "Inspect — inspeccionar la conformidad arquitectónica" },
-  { name: "forge-relocate", desc: "Relocate — migrar feature legacy a la nueva estructura" },
-  { name: "forge-reforge", desc: "Reforge — refactorizar la arquitectura de un feature" },
-  { name: "forge-quench", desc: "Quench — verificar reglas arquitectónicas del proyecto" },
-  { name: "forge-temper", desc: "Temper — endurecer la arquitectura (DI, seguridad)" },
-  { name: "forge-chain", desc: "Chain — analizar cadena de dependencias entre features" },
-  { name: "forge-inscribe", desc: "Inscribe — generar y mantener ARCHITECTURE.md" },
-  { name: "forge-smelt", desc: "Smelt — extraer código reutilizable a shared/" },
+  { name: "forge-forge", desc: "Forge — inicializar proyecto arquitectónicamente", flags: "" },
+  { name: "forge-cast", desc: "Cast — crear un nuevo feature hexagonal desde cero", flags: "" },
+  { name: "forge-inspect", desc: "Inspect — inspeccionar la conformidad arquitectónica", flags: "--json | --diff | --full | --summary | --severity=<nivel> | --force" },
+  { name: "forge-assay", desc: "Assay — ensayo arquitectónico multi-persona", flags: "--persona=<id> | --json | --save | history" },
+  { name: "forge-graph", desc: "Graph — construir el grafo arquitectónico del proyecto", flags: "--json" },
+  { name: "forge-armorer", desc: "Armorer — reporte de ownership, huérfanos y duplicados", flags: "" },
+  { name: "forge-bootstrap", desc: "Bootstrap — inicializar platform, shared e infra layers", flags: "" },
+  { name: "forge-relocate", desc: "Relocate — migrar feature legacy a la nueva estructura", flags: "" },
+  { name: "forge-reforge", desc: "Reforge — refactorizar la arquitectura de un feature", flags: "--cycles" },
+  { name: "forge-quench", desc: "Quench — verificar reglas arquitectónicas del proyecto", flags: "--fix | --show-ignores | --severity=<nivel> | --json" },
+  { name: "forge-temper", desc: "Temper — endurecer la arquitectura (DI, seguridad)", flags: "" },
+  { name: "forge-chain", desc: "Chain — analizar cadena de dependencias entre features", flags: "--json" },
+  { name: "forge-inscribe", desc: "Inscribe — generar y mantener ARCHITECTURE.md", flags: "--output=<path>" },
+  { name: "forge-smelt", desc: "Smelt — extraer código reutilizable a shared/", flags: "" },
 ];
 
 function generateCommands(configDir) {
@@ -103,7 +107,8 @@ function generateCommands(configDir) {
   mkdirSync(cmdsDir, { recursive: true });
   for (const cmd of COMMANDS) {
     const sub = cmd.name.replace("forge-", "");
-    const content = [
+    const hasFlags = cmd.flags && cmd.flags.length > 0;
+    const lines = [
       "---",
       `description: ${cmd.desc}`,
       "agent: build",
@@ -111,8 +116,16 @@ function generateCommands(configDir) {
       "",
       `Ejecuta el subcomando ${sub} de Forge con los argumentos: $ARGUMENTS`,
       "",
-    ].join("\n");
-    writeFileSync(join(cmdsDir, `${cmd.name}.md`), content);
+    ];
+    if (hasFlags) {
+      lines.push(
+        `Flags disponibles: ${cmd.flags}`,
+        "",
+        `Si $ARGUMENTS está vacío, pregunta al usuario qué flags quiere usar con la tool question (checkboxes múltiples). Si no selecciona ninguna, ejecuta sin flags.`,
+        "",
+      );
+    }
+    writeFileSync(join(cmdsDir, `${cmd.name}.md`), lines.join("\n"));
   }
 }