@warpgogol/forge 2.9.2 → 2.9.5

package/os/adr/adr-0000-template.md

@@ -0,0 +1,46 @@
+---
+id: ADR-0000
+title: "Short imperative title"
+# Lifecycle:
+#   proposed → reviewing → accepted → implemented
+#   any → superseded (requires supersededBy)
+#   any → rejected
+status: proposed
+scope: package
+decider: architecture
+createdAt: YYYY-MM-DD
+updatedAt: YYYY-MM-DD
+implementedAt:
+closedAt:
+supersedes: []
+supersededBy:
+related: []
+# Set by the deciding human together with the status change.
+# Draft scaffolds must keep this empty; do not prefill a default identity.
+# Format: human:<handle>
+reviewers: []
+---
+
+# ADR-0000: Short imperative title
+
+## Context
+
+Brief description of the local situation, constraints, and RFC or DNA context that bounds the decision. Name actual packages, files, or components.
+
+## Decision
+
+A single sentence in the present tense stating the decision as a fact. Add 1-3 bullets clarifying scope or boundaries if needed.
+
+## Justification
+
+Forces and trade-offs that led to the decision: alternatives considered, constraints, alignment with existing architecture.
+
+## Consequences
+
+- Positive: what becomes simpler, safer, cheaper, or more predictable.
+- Negative: trade-offs, limitations, operational overhead.
+- Technical debt: what is knowingly postponed.
+
+## Evolution
+
+How the decision may change: thresholds that trigger revisiting it, metrics to watch, and — for post-hoc ADRs — references to commits or PRs that implemented it.

package/os/adr/handlers/implement-stamp.ts

@@ -301,6 +301,12 @@ export async function runAdrImplementStamp(
       },
       exitCode: 0,
       summary: `adr.implement.stamp: ${targetId} stamped as implemented`,
+      nextSteps: [
+        {
+          action: `Commit the stamp: pnpm exec forge run ecosystem.commit`,
+          kind: "optional",
+        },
+      ],
     };
   } finally {
     await releaseAdrLock(lockPath);
@@ -326,6 +332,6 @@ function stampFailResult(
       violations,
     },
     exitCode: 1,
-    summary: `${prefix}adr.implement.stamp: ${violations.length} violation(s)`,
+    summary: `${prefix}adr.implement.stamp: ${violations.length} violation${violations.length === 1 ? "" : "s"}`,
   };
 }

package/os/adr/handlers/list-create.ts

@@ -12,8 +12,11 @@
 */
 
 import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { toKebabCase } from "../../../src/utils/string-utils.ts";
+import { resolveForgeRoot } from "../../../src/config/forge-config.ts";
 import { listAdrFiles, readAndParseAdr } from "../frontmatter-io.ts";
 import type {
   ForgeCommandInput,
@@ -27,7 +30,13 @@ import type {
   AdrStatus,
   AdrScope,
 } from "../types.ts";
-import { ADR_DIR, ADR_TEMPLATE_FILE, ADR_SCOPES, ADR_STATUSES } from "../types.ts";
+import {
+  ADR_DIR,
+  ADR_TEMPLATE_FILE,
+  ADR_TEMPLATE_FALLBACK_FILE,
+  ADR_SCOPES,
+  ADR_STATUSES,
+} from "../types.ts";
 
 function toIsoDate(d: Date): string {
   return d.toISOString().slice(0, 10);
@@ -137,14 +146,13 @@ export async function runAdrCreate(
   const nextSlug = `adr-${paddedNum}`;
   const nextId = `ADR-${paddedNum}`;
 
-  const templateRelPath = ADR_TEMPLATE_FILE;
-  const templatePath = path.join(workspaceRoot, templateRelPath);
+  const templatePath = resolveAdrTemplate(workspaceRoot);
   let templateContent: string;
   try {
     templateContent = await fs.readFile(templatePath, "utf-8");
   } catch {
     throw new Error(
-      `ADR template not found at ${templateRelPath}. Ensure docs/adrs/ contains the template.`,
+      `ADR template not found at ${templatePath}. Ensure docs/adrs/ contains the template.`,
     );
   }
 
@@ -205,3 +213,39 @@ export async function runAdrCreate(
     summary: `Created ${nextId}: ${title}`,
   };
 }
+
+// ---------------------------------------------------------------------------
+// ADR template resolver — finds adr-0000-template.md from project docs/adrs/
+// first (canonical location), then falls back to the forge package copy
+// (npm consumers without a project-level template).
+// ---------------------------------------------------------------------------
+
+function resolveAdrTemplate(workspaceRoot: string): string {
+  // 1. Try project-level docs/adrs/adr-0000-template.md (canonical)
+  const projectPath = path.join(workspaceRoot, ADR_TEMPLATE_FILE);
+  if (existsSync(projectPath)) return projectPath;
+
+  // 2. Try forge root (monorepo or npm-installed) — fallback copy
+  try {
+    const forgeRoot = resolveForgeRoot(workspaceRoot);
+    const p = path.join(forgeRoot, ADR_TEMPLATE_FALLBACK_FILE);
+    if (existsSync(p)) return p;
+  } catch {
+    // forge root not resolvable — fall through to module-relative search
+  }
+
+  // 3. Fallback: walk up from this module's location to find os/adr/adr-0000-template.md
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  let dir = here;
+  for (let i = 0; i < 10; i++) {
+    const candidate = path.join(dir, "os", "adr", "adr-0000-template.md");
+    if (existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  throw new Error(
+    `ADR template not found. Tried ${ADR_TEMPLATE_FILE} relative to ${workspaceRoot}, forge root, and module-relative search from ${here}.`,
+  );
+}

package/os/adr/handlers/validate.ts

@@ -135,10 +135,14 @@ export async function runAdrValidate(
       }
       const errorCount = violations.filter((v) => v.severity === "error").length;
       const warnCount = violations.filter((v) => v.severity === "warning").length;
+      const parts: string[] = [];
+      if (errorCount > 0) parts.push(`${errorCount} error${errorCount === 1 ? "" : "s"}`);
+      if (warnCount > 0) parts.push(`${warnCount} warning${warnCount === 1 ? "" : "s"}`);
+      const counts = parts.join(", ");
       if (errorCount > 0) {
-        logger.error(`${errorCount} error(s), ${warnCount} warning(s)`);
+        logger.error(counts);
       } else {
-        logger.warn(`${warnCount} warning(s), 0 errors — passed`);
+        logger.warn(`${counts} — passed`);
       }
     }
   }
@@ -152,8 +156,16 @@ export async function runAdrValidate(
     },
     exitCode: hasErrors ? 1 : 0,
     summary: hasErrors
-      ? `${violations.filter((v) => v.severity === "error").length} error(s) found`
+      ? `${violations.filter((v) => v.severity === "error").length} error${violations.filter((v) => v.severity === "error").length === 1 ? "" : "s"} found`
       : `All ${filesToValidate.length} ADR(s) passed validation`,
+    nextSteps: hasErrors
+      ? [
+          {
+            action: `Fix the ${violations.filter((v) => v.severity === "error").length} error${violations.filter((v) => v.severity === "error").length === 1 ? "" : "s"} above, then re-run: pnpm exec forge run adr.validate`,
+            kind: "required",
+          },
+        ]
+      : undefined,
   };
 }
 

package/os/adr/types.ts

@@ -92,6 +92,7 @@ export interface AdrCreateResult {
 
 export const ADR_DIR = "docs/adrs";
 export const ADR_TEMPLATE_FILE = "docs/adrs/adr-0000-template.md";
+export const ADR_TEMPLATE_FALLBACK_FILE = "os/adr/adr-0000-template.md";
 export const ADR_ID_PATTERN = /^ADR-\d{4}$/;
 
 export const ADR_REQUIRED_SECTIONS = [

package/os/compass/handlers/compass-audit-handler.ts

@@ -186,6 +186,15 @@ export async function runCompassAuditPlan(
     data: { threshold, dueCount: items.length, items },
     exitCode: 0,
     summary: `[compass.audit.plan] ${items.length} files due for audit (threshold=${threshold})`,
+    nextSteps:
+      items.length > 0
+        ? [
+            {
+              action: `Record an audit: pnpm exec forge run compass.audit.record --file <path> --verdict <verdict> --revision <rev>`,
+              kind: "optional",
+            },
+          ]
+        : undefined,
   };
 }
 
@@ -251,6 +260,12 @@ export async function runCompassAuditRecord(
     data: { path: filePath, action: "recorded" },
     exitCode: 0,
     summary: `[compass.audit.record] ${filePath}: ${verdict} at revision ${revision}`,
+    nextSteps: [
+      {
+        action: `Validate audits: pnpm exec forge run compass.audit.validate`,
+        kind: "optional",
+      },
+    ],
   };
 }
 
@@ -378,5 +393,14 @@ export async function runCompassAuditValidate(
     data: { strict, dueCount, diagnostics },
     exitCode: hasErrors ? 1 : 0,
     summary: dueCount > 0 ? undefined : `[compass.audit.validate] OK (0 files overdue)`,
+    nextSteps:
+      dueCount > 0
+        ? [
+            {
+              action: `Fix the ${dueCount} overdue file(s) above, then re-run: pnpm exec forge run compass.audit.validate`,
+              kind: "required",
+            },
+          ]
+        : undefined,
   };
 }

package/os/compass/handlers/compass-change-summary-handler.ts

@@ -278,5 +278,11 @@ export async function runCompassSummaryTrim(
     },
     exitCode: 0,
     summary: `[compass.summary.trim] files=${results.length}, removed=${results.reduce((sum, r) => sum + r.removed.length, 0)}`,
+    nextSteps: [
+      {
+        action: `Commit the trimmed headers: pnpm exec forge run ecosystem.commit`,
+        kind: "optional",
+      },
+    ],
   };
 }

package/os/compass/handlers/compass-inventory-handler.ts

@@ -222,6 +222,12 @@ export async function runCompassInventory(
     return {
       data: { entries: entries.length, outputPath: INVENTORY_OUTPUT_PATH, summary },
       summary: `[compass.inventory] previewed ${INVENTORY_OUTPUT_PATH}`,
+      nextSteps: [
+        {
+          action: `Write the inventory: pnpm exec forge run compass.inventory`,
+          kind: "optional",
+        },
+      ],
     };
   }
 
@@ -232,6 +238,19 @@ export async function runCompassInventory(
   return {
     data: { entries: entries.length, outputPath, summary },
     summary: `[compass.inventory] ${context.dryRun ? "previewed" : "wrote"} ${INVENTORY_OUTPUT_PATH}`,
+    nextSteps: context.dryRun
+      ? [
+          {
+            action: `Write for real: pnpm exec forge run compass.inventory`,
+            kind: "optional",
+          },
+        ]
+      : [
+          {
+            action: `Validate compass headers: pnpm exec forge run compass.validate`,
+            kind: "optional",
+          },
+        ],
   };
 }
 

package/os/core/handlers/package-health.ts

@@ -199,12 +199,16 @@ export async function runPackageHealth(
           `forge.package.health: all ${packagesChecked} published package(s) healthy.`,
         );
       } else if (passed) {
-        logger.success(
-          `forge.package.health: ${packagesChecked} package(s) checked, ${warnings.length} warning(s).`,
+        logger.warn(
+          `forge.package.health: ${packagesChecked} package(s) checked, ${warnings.length} warning${warnings.length === 1 ? "" : "s"}.`,
         );
       } else {
+        const parts: string[] = [];
+        parts.push(`${errors.length} error${errors.length === 1 ? "" : "s"}`);
+        if (warnings.length > 0)
+          parts.push(`${warnings.length} warning${warnings.length === 1 ? "" : "s"}`);
         logger.error(
-          `forge.package.health: ${errors.length} error(s), ${warnings.length} warning(s) across ${packagesChecked} package(s).`,
+          `forge.package.health: ${parts.join(", ")} across ${packagesChecked} package(s).`,
         );
       }
     }
@@ -220,9 +224,9 @@ export async function runPackageHealth(
     exitCode: passed ? 0 : 1,
     summary: passed
       ? warnings.length > 0
-        ? `All ${packagesChecked} package(s) passed with ${warnings.length} warning(s).`
+        ? `All ${packagesChecked} package(s) passed with ${warnings.length} warning${warnings.length === 1 ? "" : "s"}.`
         : `All ${packagesChecked} package(s) healthy.`
-      : `${errors.length} error(s) found across ${packagesChecked} package(s).`,
+      : `${errors.length} error${errors.length === 1 ? "" : "s"} found across ${packagesChecked} package(s).`,
     nextSteps: errors.map((e) => ({
       action: e.fixHint ?? e.message,
       kind: "required" as const,

package/os/core/handlers/pinned-validate.ts

@@ -283,7 +283,9 @@ export async function runPinnedValidate(
         logger.success("pinned.validate: no violations");
       }
     } else {
-      logger.error(`pinned.validate: ${remainingViolations.length} violation(s) found`);
+      logger.error(
+        `pinned.validate: ${remainingViolations.length} violation${remainingViolations.length === 1 ? "" : "s"} found`,
+      );
       for (const v of remainingViolations) {
         logger.error(`  ${v.operation}: ${v.path} (mode: ${v.mode}) — ${v.reason}`);
       }
@@ -296,6 +298,6 @@ export async function runPinnedValidate(
     summary:
       status === "pass"
         ? `No violations${appliedOverrides.length > 0 ? ` (${appliedOverrides.length} override(s) applied)` : ""}`
-        : `${remainingViolations.length} violation(s) found`,
+        : `${remainingViolations.length} violation${remainingViolations.length === 1 ? "" : "s"} found`,
   };
 }

package/os/exploration/handlers/archive.ts

@@ -155,5 +155,11 @@ export async function runExplorationArchive(
       related,
     },
     summary: `Archived exploration note: ${slug} (${previousStatus} → archived)`,
+    nextSteps: [
+      {
+        action: `Commit the archive: pnpm exec forge run ecosystem.commit`,
+        kind: "optional",
+      },
+    ],
   };
 }

package/os/exploration/handlers/list.ts

@@ -73,5 +73,14 @@ export async function runExplorationList(
       explorations: entries,
     },
     summary: `${entries.length} exploration note(s) found`,
+    nextSteps:
+      entries.length === 0
+        ? [
+            {
+              action: `Create an exploration note: pnpm exec forge run exploration.show --id <slug>`,
+              kind: "optional",
+            },
+          ]
+        : undefined,
   };
 }

package/os/exploration/handlers/show.ts

@@ -103,5 +103,11 @@ export async function runExplorationShow(
       note,
     },
     summary: `Exploration note: ${note.id}`,
+    nextSteps: [
+      {
+        action: `Archive the note when done: pnpm exec forge run exploration.archive --id ${note.id}`,
+        kind: "optional",
+      },
+    ],
   };
 }

package/os/program/handlers/complete.ts

@@ -237,6 +237,12 @@ export async function runComplete(
     },
     exitCode: 0,
     summary: `program.packet.complete: ${packetId} completed at ${head.slice(0, 8)}`,
+    nextSteps: [
+      {
+        action: `Seal the next packet: pnpm exec forge run program.packet.seal --packet <next-packet-id>`,
+        kind: "optional",
+      },
+    ],
   };
 }
 
@@ -390,6 +396,12 @@ async function bootstrapComplete(
     },
     exitCode: 0,
     summary: `program.packet.complete: ${packetId} bootstrap completed — program now executing`,
+    nextSteps: [
+      {
+        action: `Seal the first execution packet: pnpm exec forge run program.packet.seal --packet <first-packet-id>`,
+        kind: "optional",
+      },
+    ],
   };
 }
 
@@ -414,6 +426,12 @@ function completeFail(
       violations,
     },
     exitCode: 1,
-    summary: `program.packet.complete: ${packetId} failed with ${violations.length} violation(s)`,
+    summary: `program.packet.complete: ${packetId} failed with ${violations.length} violation${violations.length === 1 ? "" : "s"}`,
+    nextSteps: [
+      {
+        action: `Fix the ${violations.length} violation${violations.length === 1 ? "" : "s"} above, then re-run: pnpm exec forge run program.packet.complete --packet ${packetId}`,
+        kind: "required",
+      },
+    ],
   };
 }

package/os/program/handlers/lease.ts

@@ -199,6 +199,12 @@ async function leaseStart(
     },
     exitCode: 0,
     summary: `program.packet.lease: ${packetId} lease started for ${executor}`,
+    nextSteps: [
+      {
+        action: `Implement the packet, then complete: pnpm exec forge run program.packet.complete --packet ${packetId}`,
+        kind: "optional",
+      },
+    ],
   };
 }
 
@@ -428,6 +434,6 @@ function leaseFail(
       violations,
     },
     exitCode: 1,
-    summary: `program.packet.lease: ${packetId} ${action} failed with ${violations.length} violation(s)`,
+    summary: `program.packet.lease: ${packetId} ${action} failed with ${violations.length} violation${violations.length === 1 ? "" : "s"}`,
   };
 }

package/os/program/handlers/seal.ts

@@ -224,6 +224,12 @@ export async function runSeal(
     },
     exitCode: 0,
     summary: `program.packet.seal: ${packetId} sealed on ${branch}@${head.slice(0, 8)}`,
+    nextSteps: [
+      {
+        action: `Start the lease: pnpm exec forge run program.packet.lease --packet ${packetId} --action start --executor <executor>`,
+        kind: "optional",
+      },
+    ],
   };
 }
 
@@ -242,7 +248,13 @@ function sealFail(
       violations,
     },
     exitCode: 1,
-    summary: `program.packet.seal: ${packetId} failed with ${violations.length} violation(s)`,
+    summary: `program.packet.seal: ${packetId} failed with ${violations.length} violation${violations.length === 1 ? "" : "s"}`,
+    nextSteps: [
+      {
+        action: `Fix the ${violations.length} violation${violations.length === 1 ? "" : "s"} above, then re-run: pnpm exec forge run program.packet.seal --packet ${packetId}`,
+        kind: "required",
+      },
+    ],
   };
 }
 

package/os/program/handlers/validate.ts

@@ -186,7 +186,7 @@ export async function runValidate(
     summary:
       status === "pass"
         ? `program.packet.validate: ${packetId} passed (${phase})`
-        : `program.packet.validate: ${packetId} failed with ${violations.length} violation(s)`,
+        : `program.packet.validate: ${packetId} failed with ${violations.length} violation${violations.length === 1 ? "" : "s"}`,
   };
 }
 
@@ -208,6 +208,12 @@ function failResult(
       violations,
     },
     exitCode: 1,
-    summary: `program.packet.validate: ${packetId} failed with ${violations.length} violation(s)`,
+    summary: `program.packet.validate: ${packetId} failed with ${violations.length} violation${violations.length === 1 ? "" : "s"}`,
+    nextSteps: [
+      {
+        action: `Fix the ${violations.length} violation${violations.length === 1 ? "" : "s"} above, then re-run: pnpm exec forge run program.packet.validate --packet ${packetId}`,
+        kind: "required",
+      },
+    ],
   };
 }

package/os/rfc/acceptance.ts

@@ -340,5 +340,14 @@ export async function runRfcAcceptanceRun(
     data: { command: "rfc.acceptance.run", status, diagnostics, results },
     exitCode: failedCount > 0 ? 1 : 0,
     summary: `rfc.acceptance.run: ${results.length} RFC(s), ${failedCount} failed probe(s)`,
+    nextSteps:
+      failedCount > 0
+        ? [
+            {
+              action: `Fix the ${failedCount} failed acceptance probe(s) above, then re-run: pnpm exec forge run rfc.acceptance.run`,
+              kind: "required",
+            },
+          ]
+        : undefined,
   };
 }

package/os/rfc/dna-trace.ts

@@ -233,7 +233,7 @@ export async function runRfcDnaTraceValidate(
       diagnostics,
     },
     exitCode: hasErrors ? 1 : 0,
-    summary: `rfc.dna.trace.validate: ${registryIds.size} DNA invariants, ${tracedDnaCount} traced, ${diagnostics.filter((d) => d.severity === "error").length} error(s)`,
+    summary: `rfc.dna.trace.validate: ${registryIds.size} DNA invariants, ${tracedDnaCount} traced, ${diagnostics.filter((d) => d.severity === "error").length} error${diagnostics.filter((d) => d.severity === "error").length === 1 ? "" : "s"}`,
   };
 }
 

package/os/rfc/handlers/check.ts

@@ -219,7 +219,7 @@ export async function runRfcCheck(
       for (const v of violations) {
         logger.error(`[${v.kind}] ${v.rfcId}: ${v.message}`);
       }
-      logger.error(`${violations.length} violation(s) found`);
+      logger.error(`${violations.length} violation${violations.length === 1 ? "" : "s"} found`);
     }
   }
 
@@ -232,7 +232,15 @@ export async function runRfcCheck(
     },
     exitCode: hasErrors ? 1 : 0,
     summary: hasErrors
-      ? `${violations.length} artifact violation(s) found across ${checkedRfcs} RFC(s)`
+      ? `${violations.length} artifact violation${violations.length === 1 ? "" : "s"} found across ${checkedRfcs} RFC(s)`
       : `All ${checkedRfcs} RFC(s) passed artifact check`,
+    nextSteps: hasErrors
+      ? [
+          {
+            action: `Fix the ${violations.length} artifact violation${violations.length === 1 ? "" : "s"} above, then re-run: pnpm exec forge run rfc.check`,
+            kind: "required",
+          },
+        ]
+      : undefined,
   };
 }

package/os/rfc/handlers/implement-stamp.ts

@@ -485,6 +485,12 @@ export async function runRfcImplementStamp(
       },
       exitCode: 0,
       summary: `rfc.implement.stamp: ${targetId} stamped as implemented`,
+      nextSteps: [
+        {
+          action: `Commit the stamp: pnpm exec forge run ecosystem.commit`,
+          kind: "optional",
+        },
+      ],
     };
   } finally {
     await releaseRfcLock(lockPath);
@@ -510,6 +516,6 @@ function stampFailResult(
       violations,
     },
     exitCode: 1,
-    summary: `${prefix}rfc.implement.stamp: ${violations.length} violation(s)`,
+    summary: `${prefix}rfc.implement.stamp: ${violations.length} violation${violations.length === 1 ? "" : "s"}`,
   };
 }

package/os/rfc/handlers/index-graph.ts

@@ -175,7 +175,7 @@ export async function runRfcIndexValidate(
     return {
       data: result,
       exitCode: 1,
-      summary: "1 error(s) found",
+      summary: "1 error found",
     };
   }
 
@@ -196,7 +196,7 @@ export async function runRfcIndexValidate(
     return {
       data: result,
       exitCode: 1,
-      summary: "1 error(s) found",
+      summary: "1 error found",
     };
   }
 
@@ -221,7 +221,7 @@ export async function runRfcIndexValidate(
       for (const v of violations) {
         logger.error(`[${v.rule}] ${v.message}`);
       }
-      logger.error(`${violations.length} error(s) found`);
+      logger.error(`${violations.length} error${violations.length === 1 ? "" : "s"} found`);
     } else {
       logger.success(`Index valid — ${indexCount} entries match ${fileCount} RFC files.`);
     }
@@ -231,7 +231,7 @@ export async function runRfcIndexValidate(
     data: result,
     exitCode: hasErrors ? 1 : 0,
     summary: hasErrors
-      ? `${violations.length} error(s) found`
+      ? `${violations.length} error${violations.length === 1 ? "" : "s"} found`
       : `Index valid — ${indexCount} entries match ${fileCount} RFC files`,
   };
 }

package/os/rfc/handlers/lifecycle.ts

@@ -243,7 +243,7 @@ export async function runRfcCommandLifecycleValidate(
     },
     exitCode: hasErrors ? 1 : 0,
     summary: hasErrors
-      ? `${violations.filter((v) => v.severity === "error").length} command lifecycle error(s) found`
+      ? `${violations.filter((v) => v.severity === "error").length} command lifecycle error${violations.filter((v) => v.severity === "error").length === 1 ? "" : "s"} found`
       : `All ${checkedCount} RFC(s) passed command lifecycle validation`,
   };
 }

package/os/rfc/handlers/list-create.ts

@@ -131,6 +131,15 @@ export async function runRfcList(
       entries,
     },
     summary: `${entries.length} RFC(s) found`,
+    nextSteps:
+      entries.length === 0
+        ? [
+            {
+              action: `Create a new RFC: pnpm exec forge run rfc.create --title "..."`,
+              kind: "optional",
+            },
+          ]
+        : undefined,
   };
 }
 
@@ -253,6 +262,12 @@ export async function runRfcCreate(
       consultedDecisions,
     },
     summary: `Created ${nextId}: ${title}`,
+    nextSteps: [
+      {
+        action: `Validate the RFC: pnpm exec forge run rfc.validate --file ${relativeFile}`,
+        kind: "optional",
+      },
+    ],
   };
 }
 
@@ -292,5 +307,11 @@ export async function runRfcNextId(
       scannedFiles: files.length,
     },
     summary: `Next RFC number: ${nextId}`,
+    nextSteps: [
+      {
+        action: `Create the RFC: pnpm exec forge run rfc.create --title "..."`,
+        kind: "optional",
+      },
+    ],
   };
 }