@entelligentsia/forgecli 0.21.0 → 1.0.3

package/dist/forge-payload/schemas/config.schema.json

@@ -204,11 +204,6 @@
           }
         }
       }
-    },
-    "mode": {
-      "type": "string",
-      "enum": ["full", "fast"],
-      "description": "Init mode. 'fast' means scaffolding was generated by /forge:init --fast (stubs present, heavy artifacts deferred to first use). 'full' means all artifacts are generated. Absent on pre-0.12 projects — treated as 'full' by all readers. Flipped to 'full' by /forge:regenerate (default) or /forge:materialize --all."
     }
   },
   "additionalProperties": false

package/dist/forge-payload/schemas/enum-catalog.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.51.4",
-  "generated": "2026-05-26",
+  "version": "1.0.2",
+  "generated": "2026-05-28",
   "note": "Authoritative enum catalog. Source: build-enum-catalog.cjs. Regenerate via node forge/tools/build-manifest.cjs.",
   "enums": {
     "task.status": [
@@ -35,34 +35,30 @@
     ]
   },
   "commandNames": [
-    "forge:sprint-intake",
+    "forge:new-sprint",
     "forge:plan",
     "forge:review-plan",
     "forge:implement",
     "forge:review-code",
     "forge:fix-bug",
-    "forge:sprint-plan",
+    "forge:plan-sprint",
     "forge:run-task",
     "forge:run-sprint",
-    "forge:collate",
-    "forge:retrospective",
+    "forge:retro",
     "forge:approve",
     "forge:commit",
-    "forge:enhance",
-    "forge:quiz-agent",
+    "forge:check-agent",
     "forge:validate",
     "forge:init",
     "forge:health",
-    "forge:regenerate",
+    "forge:rebuild",
     "forge:update",
     "forge:add-task",
     "forge:add-pipeline",
-    "forge:calibrate",
-    "forge:materialize",
     "forge:remove",
     "forge:report-bug",
-    "forge:store-query",
-    "forge:store-repair",
+    "forge:search",
+    "forge:repair",
     "forge:config",
     "forge:ask",
     "forge:store-custodian",

package/dist/forge-payload/schemas/structure-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.51.4",
-  "generatedAt": "2026-05-26T04:50:57.503Z",
+  "version": "1.0.2",
+  "generatedAt": "2026-05-28T05:59:32.606Z",
   "generatedByTool": "build-manifest.cjs",
   "namespaces": {
     "personas": {
@@ -48,6 +48,7 @@
         "review_plan.md",
         "run_sprint.md",
         "sprint_retrospective.md",
+        "triage.md",
         "update_implementation.md",
         "update_plan.md",
         "validate_task.md"
@@ -75,20 +76,18 @@
       "prefixed": true,
       "files": [
         "approve.md",
-        "collate.md",
+        "check-agent.md",
         "commit.md",
-        "enhance.md",
         "fix-bug.md",
         "implement.md",
+        "new-sprint.md",
+        "plan-sprint.md",
         "plan.md",
-        "quiz-agent.md",
-        "retrospective.md",
+        "retro.md",
         "review-code.md",
         "review-plan.md",
         "run-sprint.md",
         "run-task.md",
-        "sprint-intake.md",
-        "sprint-plan.md",
         "validate.md"
       ]
     },
@@ -182,6 +181,24 @@
           "paths.engineering"
         ]
       },
+      "triage": {
+        "personas": [
+          ".forge/personas/bug-fixer.md"
+        ],
+        "skills": [
+          ".forge/skills/bug-fixer-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [],
+        "sub_workflows": [],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md"
+        ],
+        "config_fields": [
+          "commands.test",
+          "paths.engineering"
+        ]
+      },
       "fix_bug": {
         "personas": [
           ".forge/personas/bug-fixer.md",

package/dist/forge-payload/tools/artifact.cjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+'use strict';
+
+// Forge tool: artifact
+// Read, write, or list phase artifacts (PLAN.md, PROGRESS.md, *-SUMMARY.json, etc.)
+// for a task, bug, or sprint. Resolves paths from entity store record.
+//
+// Usage:
+//   node artifact.cjs read <entity> <entityId> <artifact>
+//   node artifact.cjs write <entity> <entityId> <artifact> <content|@file>
+//   node artifact.cjs list <entity> <entityId>
+//
+// Exit codes: 0 = success, 1 = usage/validation error, 2 = not found
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { findProjectRoot } = require('./lib/project-root.cjs');
+
+// ── Artifact catalog ─────────────────────────────────────────────────────────
+
+const ARTIFACT_CATALOG = {
+  'plan':                   { filename: 'PLAN.md',                    type: 'md' },
+  'plan-review':            { filename: 'PLAN_REVIEW.md',             type: 'md' },
+  'progress':               { filename: 'PROGRESS.md',                type: 'md' },
+  'code-review':            { filename: 'CODE_REVIEW.md',             type: 'md' },
+  'validation-report':      { filename: 'VALIDATION_REPORT.md',       type: 'md' },
+  'architect-approval':     { filename: 'ARCHITECT_APPROVAL.md',      type: 'md' },
+  'triage':                 { filename: 'TRIAGE.md',                  type: 'md' },
+  'bug-report':             { filename: 'BUG_REPORT.md',              type: 'md' },
+  'index':                  { filename: 'INDEX.md',                   type: 'md' },
+  'task-prompt':            { filename: 'TASK_PROMPT.md',             type: 'md' },
+  'sprint-requirements':    { filename: 'SPRINT_REQUIREMENTS.md',     type: 'md' },
+  'sprint-completion-review': { filename: 'SPRINT_COMPLETION_REVIEW.md', type: 'md' },
+  'cost-report':            { filename: 'COST_REPORT.md',             type: 'md' },
+  'timesheet':              { filename: 'TIMESHEET.md',               type: 'md' },
+  'plan-summary':           { filename: 'PLAN-SUMMARY.json',          type: 'json' },
+  'review-plan-summary':    { filename: 'REVIEW-PLAN-SUMMARY.json',   type: 'json' },
+  'implementation-summary': { filename: 'IMPLEMENTATION-SUMMARY.json', type: 'json' },
+  'review-code-summary':    { filename: 'REVIEW-CODE-SUMMARY.json',   type: 'json' },
+  'review-impl-summary':    { filename: 'REVIEW-IMPL-SUMMARY.json',   type: 'json' },
+  'validation-summary':     { filename: 'VALIDATION-SUMMARY.json',    type: 'json' },
+  'approve-summary':        { filename: 'APPROVE-SUMMARY.json',       type: 'json' },
+  'commit-summary':         { filename: 'COMMIT-SUMMARY.json',        type: 'json' },
+  'triage-summary':         { filename: 'TRIAGE-SUMMARY.json',        type: 'json' },
+  'writeback-summary':      { filename: 'WRITEBACK-SUMMARY.json',     type: 'json' },
+  'collation-summary':      { filename: 'COLLATION-SUMMARY.json',     type: 'json' },
+};
+
+// Per-entity filename overrides. Bug-mode plans and plan-summaries use the
+// BUG_FIX_PLAN prefix to match the long-standing forge convention and the
+// preflight-gate.cjs expectations for review-plan in bug mode. Without this
+// override, plan-fix (routed via plan_task.md post FORGE-BUG-040) writes
+// PLAN.md and review-plan preflight then fails "artifact missing:
+// BUG_FIX_PLAN.md" — see FORGE-BUG-041.
+const ARTIFACT_FILENAME_OVERRIDES = {
+  bug: {
+    'plan':         'BUG_FIX_PLAN.md',
+    'plan-summary': 'BUG-FIX-PLAN-SUMMARY.json',
+  },
+};
+
+function resolveArtifactFilename(entity, artifactName) {
+  const override = ARTIFACT_FILENAME_OVERRIDES[entity];
+  if (override && override[artifactName]) return override[artifactName];
+  return ARTIFACT_CATALOG[artifactName].filename;
+}
+
+const ARTIFACT_NAMES = Object.keys(ARTIFACT_CATALOG).sort();
+
+// ── Summary JSON validation ──────────────────────────────────────────────────
+
+const SUMMARY_REQUIRED = ['objective', 'key_changes', 'verdict', 'written_at'];
+
+function validateSummaryJson(content) {
+  let obj;
+  try {
+    obj = JSON.parse(content);
+  } catch (e) {
+    return `Invalid JSON: ${e.message}`;
+  }
+  const missing = SUMMARY_REQUIRED.filter((f) => !(f in obj));
+  if (missing.length > 0) return `Missing required fields: ${missing.join(', ')}`;
+  if (typeof obj.objective !== 'string') return `"objective" must be a string`;
+  if (!Array.isArray(obj.key_changes)) return `"key_changes" must be an array`;
+  if (typeof obj.verdict !== 'string') return `"verdict" must be a string`;
+  if (typeof obj.written_at !== 'string') return `"written_at" must be a string`;
+  return null;
+}
+
+// ── Entity path resolution ───────────────────────────────────────────────────
+
+/** Read a store record via store-cli and return its `path` field, or null on failure. */
+function readStorePath(entity, entityId, toolDir, projectRoot) {
+  const cliPath = path.join(toolDir, 'store-cli.cjs');
+  try {
+    const result = execFileSync('node', [cliPath, 'read', entity, entityId, '--json'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 10_000,
+    });
+    const record = JSON.parse(result);
+    if (typeof record.path === 'string' && record.path.length > 0) {
+      // Defensive: if the path ends with a file extension, the store record
+      // was written with a filename (e.g. "…/PROGRESS.md") instead of the
+      // directory. Strip the trailing filename to get the entity directory.
+      const p = record.path;
+      if (/\.(md|json)$/i.test(p)) return path.dirname(p);
+      return p;
+    }
+  } catch (_) {
+    // Store unavailable or record not found — fall through.
+  }
+  return null;
+}
+
+/**
+ * Resolve entity directory using the store record's `path` field when available,
+ * falling back to ID-only construction.
+ */
+function resolveEntityDir(entity, entityId, engineeringPath, toolDir, projectRoot) {
+  switch (entity) {
+    case 'bug': {
+      const storePath = readStorePath('bug', entityId, toolDir, projectRoot);
+      if (storePath) return storePath;
+      return path.join(engineeringPath, 'bugs', entityId);
+    }
+    case 'sprint': {
+      const storePath = readStorePath('sprint', entityId, toolDir, projectRoot);
+      if (storePath) return storePath;
+      return path.join(engineeringPath, 'sprints', entityId);
+    }
+    case 'task': {
+      const storePath = readStorePath('task', entityId, toolDir, projectRoot);
+      if (storePath) return storePath;
+      // Fallback: derive from sprint prefix + sprint record path.
+      const match = entityId.match(/^(.+-S\d+)-T\d+$/);
+      if (!match) return null;
+      const sprintId = match[1];
+      const sprintPath = readStorePath('sprint', sprintId, toolDir, projectRoot);
+      if (sprintPath) {
+        return path.join(sprintPath, entityId);
+      }
+      return path.join(engineeringPath, 'sprints', sprintId, entityId);
+    }
+    default:
+      return null;
+  }
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+
+const argv = process.argv.slice(2);
+
+if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+  process.stderr.write([
+    'Usage: node artifact.cjs <subcommand> <entity> <entityId> [artifact] [content|@file]',
+    '',
+    'Subcommands:',
+    '  list <entity> <entityId>                   List existing artifacts',
+    '  read <entity> <entityId> <artifact>         Read artifact content',
+    '  write <entity> <entityId> <artifact> <content|@file>',
+    '                                              Write artifact (content or @/path/to/file)',
+    '',
+    'Entities: task, bug, sprint',
+    `Known artifacts: ${ARTIFACT_NAMES.join(', ')}`,
+    '',
+    'Exit codes: 0=success, 1=usage/validation error, 2=not found',
+  ].join('\n') + '\n');
+  process.exit(1);
+}
+
+const [subcmd, entity, entityId] = argv;
+
+if (!subcmd || !entity || !entityId) {
+  process.stderr.write('Usage: artifact.cjs <list|read|write> <entity> <entityId> [artifact] [content]\n');
+  process.exit(1);
+}
+
+const VALID_ENTITIES = ['task', 'bug', 'sprint'];
+if (!VALID_ENTITIES.includes(entity)) {
+  process.stderr.write(`Unknown entity type: ${entity}. Valid: ${VALID_ENTITIES.join(', ')}\n`);
+  process.exit(1);
+}
+
+const projectRoot = findProjectRoot();
+if (!projectRoot) {
+  process.stderr.write('Cannot find project root (.forge/config.json not found)\n');
+  process.exit(1);
+}
+
+// Read engineering path from config
+let engineeringPath = 'engineering';
+try {
+  const cfg = JSON.parse(fs.readFileSync(path.join(projectRoot, '.forge', 'config.json'), 'utf8'));
+  if (typeof cfg.paths?.engineering === 'string') engineeringPath = cfg.paths.engineering;
+} catch (_) { /* default */ }
+
+const toolDir = __dirname;
+
+const entityDir = resolveEntityDir(entity, entityId, engineeringPath, toolDir, projectRoot);
+if (!entityDir) {
+  process.stderr.write(
+    `Cannot resolve ${entity} directory for "${entityId}". ` +
+    `Expected ID pattern: task=PREFIX-SNN-TNN, bug=PREFIX-BNN[-slug], sprint=PREFIX-SNN.\n`
+  );
+  process.exit(1);
+}
+
+const absDir = path.resolve(projectRoot, entityDir);
+
+// ── list ────────────────────────────────────────────────────────────────────
+
+if (subcmd === 'list') {
+  if (!fs.existsSync(absDir)) {
+    process.stdout.write(`No artifacts found — directory does not exist: ${entityDir}/\n`);
+    process.exit(0);
+  }
+  const files = fs.readdirSync(absDir).filter((f) => f.endsWith('.md') || f.endsWith('.json'));
+  const known = [];
+  const other = [];
+  for (const f of files) {
+    // Recognise the per-entity overrides as well, so e.g. BUG_FIX_PLAN.md
+    // surfaces as the `plan` artifact in bug-mode listings.
+    const overrideEntry = ARTIFACT_FILENAME_OVERRIDES[entity]
+      ? Object.entries(ARTIFACT_FILENAME_OVERRIDES[entity]).find(([, fn]) => fn === f)
+      : undefined;
+    const catalogEntry = overrideEntry
+      || Object.entries(ARTIFACT_CATALOG).find(([, v]) => v.filename === f);
+    if (catalogEntry) {
+      known.push(`  ${catalogEntry[0]} → ${f}`);
+    } else {
+      other.push(`  (unlisted) ${f}`);
+    }
+  }
+  const lines = [`Artifacts in ${entityDir}/:`];
+  if (known.length > 0) lines.push(...known);
+  if (other.length > 0) lines.push(...other);
+  if (known.length === 0 && other.length === 0) lines.push('  (empty)');
+  process.stdout.write(lines.join('\n') + '\n');
+  process.exit(0);
+}
+
+// ── read / write — need artifact name ───────────────────────────────────────
+
+const artifactName = argv[3];
+if (!artifactName) {
+  process.stderr.write(`"artifact" is required for ${subcmd}. Known: ${ARTIFACT_NAMES.join(', ')}\n`);
+  process.exit(1);
+}
+
+const catalogEntry = ARTIFACT_CATALOG[artifactName];
+if (!catalogEntry) {
+  const suggestions = ARTIFACT_NAMES.filter((n) => n.includes(artifactName.toLowerCase()));
+  process.stderr.write(
+    `Unknown artifact "${artifactName}". Known: ${ARTIFACT_NAMES.join(', ')}.` +
+    (suggestions.length > 0 ? ` Did you mean: ${suggestions.join(', ')}?` : '') + '\n'
+  );
+  process.exit(1);
+}
+
+const resolvedFilename = resolveArtifactFilename(entity, artifactName);
+const filePath = path.join(absDir, resolvedFilename);
+
+// ── read ─────────────────────────────────────────────────────────────────────
+
+if (subcmd === 'read') {
+  if (!fs.existsSync(filePath)) {
+    process.stderr.write(`Artifact not found: ${path.join(entityDir, resolvedFilename)}\n`);
+    process.exit(2);
+  }
+  process.stdout.write(fs.readFileSync(filePath, 'utf8'));
+  process.exit(0);
+}
+
+// ── write ─────────────────────────────────────────────────────────────────────
+
+if (subcmd === 'write') {
+  let rawContent = argv[4];
+  if (!rawContent) {
+    process.stderr.write('"content" is required for write. Pass inline or use @/path/to/file for large content.\n');
+    process.exit(1);
+  }
+
+  // @-prefix convention: read content from file when arg starts with @
+  let content;
+  if (rawContent.startsWith('@')) {
+    const contentFile = rawContent.slice(1);
+    if (!fs.existsSync(contentFile)) {
+      process.stderr.write(`@-file not found: ${contentFile}\n`);
+      process.exit(1);
+    }
+    content = fs.readFileSync(contentFile, 'utf8');
+  } else {
+    content = rawContent;
+  }
+
+  if (catalogEntry.type === 'json') {
+    const validationError = validateSummaryJson(content);
+    if (validationError) {
+      process.stderr.write(
+        `Summary validation failed for ${resolvedFilename}: ${validationError}. ` +
+        `Required fields: ${SUMMARY_REQUIRED.join(', ')}.\n`
+      );
+      process.exit(1);
+    }
+  }
+
+  fs.mkdirSync(absDir, { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+  process.stdout.write(
+    `Wrote ${Buffer.byteLength(content, 'utf8')} bytes to ${path.join(entityDir, resolvedFilename)}\n`
+  );
+  process.exit(0);
+}
+
+process.stderr.write(`Unknown subcommand: ${subcmd}. Valid: list, read, write\n`);
+process.exit(1);
+
+} // end if (require.main === module)
+
+module.exports = { ARTIFACT_CATALOG, ARTIFACT_NAMES, validateSummaryJson, resolveEntityDir };

package/dist/forge-payload/tools/banners.cjs

@@ -31,7 +31,7 @@
 //   node banners.cjs --plain forge
 //   node banners.cjs --subtitle "Forging your SDLC"
 //   node banners.cjs --progress 5 12 "Templates"
-//   node banners.cjs --phase 7 12 "Workflows" ember fast
+//   node banners.cjs --phase 7 12 "Workflows" ember
 
 // ─── Plain-mode detection ─────────────────────────────────────────────────────
 // Resolved at call-time so tests can flip env vars dynamically.
@@ -61,14 +61,13 @@ const f = (r, g, b) => `\x1b[38;2;${r};${g};${b}m`;
 // ─── Mode tints ───────────────────────────────────────────────────────────────
 // Mode-aware accent colour for progress bars and subtitles. Used by phaseHeader.
 const MODE_TINTS = {
-  fast: [255, 208, 122],   // lantern yellow
   full: [255, 138, 60],    // ember orange
 };
 
 // ─── Zen blue ─────────────────────────────────────────────────────────────────
 // System-wide horizontal-rule tint. Applied to em-dash separators in
-// phaseHeader, ruleLine, and ensure-ready.cjs --announce framing. Picked to
-// read calm and cool without competing with banner colours.
+// phaseHeader and ruleLine. Picked to read calm and cool without competing
+// with banner colours.
 const ZEN_BLUE = [100, 140, 200];
 
 // ─── Banner registry ───────────────────────────────────────────────────────────

package/dist/forge-payload/tools/build-context-pack.cjs

@@ -196,7 +196,7 @@ function buildContextPack({ archDir, existingPackPath }) {
   if (realLineCount > PACK_LINE_LIMIT) {
     // Keep PACK_LINE_LIMIT - 1 lines so the marker fits within the cap
     const truncated = splitLines.slice(0, PACK_LINE_LIMIT - 1);
-    truncated.push('<!-- TRUNCATED: pack exceeded 400 lines. Architecture KB has grown beyond summary capacity. Run /forge:regenerate after pruning docs. -->');
+    truncated.push('<!-- TRUNCATED: pack exceeded 400 lines. Architecture KB has grown beyond summary capacity. Run /forge:rebuild after pruning docs. -->');
     markdown = truncated.join('\n') + '\n';
   }
 

package/dist/forge-payload/tools/check-structure.cjs

@@ -59,11 +59,16 @@ function checkNamespaces(manifest, projectRoot, options = {}) {
 
   for (const [nsKey, ns] of Object.entries(manifest.namespaces)) {
     const logicalKey = ns.logicalKey || nsKey;
-    let resolvedDir = (resolvedConfigPaths[logicalKey] && typeof resolvedConfigPaths[logicalKey] === 'string')
+    const configHasPath = resolvedConfigPaths[logicalKey] && typeof resolvedConfigPaths[logicalKey] === 'string';
+    let resolvedDir = configHasPath
       ? resolvedConfigPaths[logicalKey]
       : ns.dir;
-    if (ns.prefixed && projectPrefix) {
-      resolvedDir = resolvedDir + '/' + projectPrefix;
+    // When config provides the path, use it verbatim (it already includes any
+    // prefix subdirectory).  Only apply the prefixed append when falling back
+    // to the manifest's base dir.
+    if (ns.prefixed && !configHasPath) {
+      const suffix = projectPrefix || getCommandsSubdir('forge');
+      resolvedDir = resolvedDir + '/' + suffix;
     }
     const absDir = path.join(projectRoot, resolvedDir);
 

package/dist/forge-payload/tools/store-cli.cjs

@@ -558,10 +558,17 @@ function cmdWrite() {
 function cmdRead() {
   const entity = args[1];
   const id = args[2];
-  const asJson = args.includes('--json');
+  const asJson      = args.includes('--json');
+  const noSummaries = args.includes('--no-summaries');
+
+  let fieldsProjection = null;
+  const fieldsIdx = args.indexOf('--fields');
+  if (fieldsIdx !== -1 && args[fieldsIdx + 1] && !args[fieldsIdx + 1].startsWith('--')) {
+    fieldsProjection = args[fieldsIdx + 1].split(',').map((f) => f.trim()).filter(Boolean);
+  }
 
   if (!entity || !id) {
-    console.error('Usage: store-cli.cjs read <entity> <id> [--json]');
+    console.error('Usage: store-cli.cjs read <entity> <id> [--json] [--no-summaries] [--fields <comma-list>]');
     process.exit(1);
   }
 
@@ -590,10 +597,19 @@ function cmdRead() {
     process.exit(1);
   }
 
+  // Apply projection before formatting
+  let projected = record;
+  if (noSummaries) {
+    projected = Object.fromEntries(Object.entries(projected).filter(([k]) => k !== 'summaries'));
+  }
+  if (fieldsProjection) {
+    projected = Object.fromEntries(fieldsProjection.map((f) => [f, projected[f]]).filter(([, v]) => v !== undefined));
+  }
+
   if (asJson) {
-    console.log(JSON.stringify(record));
+    console.log(JSON.stringify(projected));
   } else {
-    console.log(JSON.stringify(record, null, 2));
+    console.log(JSON.stringify(projected, null, 2));
   }
 }
 
@@ -601,7 +617,7 @@ function cmdList() {
   const entity = args[1];
 
   if (!entity) {
-    console.error('Usage: store-cli.cjs list <entity> [key=value ...]');
+    console.error('Usage: store-cli.cjs list <entity> [key=value ...] [--no-summaries] [--fields <comma-list>] [--limit N] [--count]');
     process.exit(1);
   }
 
@@ -610,9 +626,27 @@ function cmdList() {
     process.exit(1);
   }
 
-  // Parse key=value filter pairs from remaining args
+  // Parse projection flags and key=value filter pairs from remaining args
+  const noSummaries = args.includes('--no-summaries');
+  const countOnly   = args.includes('--count');
+
+  let fieldsProjection = null;
+  const fieldsIdx = args.indexOf('--fields');
+  if (fieldsIdx !== -1 && args[fieldsIdx + 1] && !args[fieldsIdx + 1].startsWith('--')) {
+    fieldsProjection = args[fieldsIdx + 1].split(',').map((f) => f.trim()).filter(Boolean);
+  }
+
+  let limitN = null;
+  const limitIdx = args.indexOf('--limit');
+  if (limitIdx !== -1 && args[limitIdx + 1] && !args[limitIdx + 1].startsWith('--')) {
+    const n = parseInt(args[limitIdx + 1], 10);
+    if (!isNaN(n) && n >= 0) limitN = n;
+  }
+
   const filter = {};
   for (let i = 2; i < args.length; i++) {
+    // Skip flag arguments and their value arguments
+    if (args[i].startsWith('--')) { i++; continue; }
     const eqIdx = args[i].indexOf('=');
     if (eqIdx > 0) {
       const key = args[i].slice(0, eqIdx);
@@ -623,7 +657,33 @@ function cmdList() {
     }
   }
 
-  const records = listEntities(entity, Object.keys(filter).length > 0 ? filter : undefined);
+  let records = listEntities(entity, Object.keys(filter).length > 0 ? filter : undefined);
+
+  // --count: emit bare integer and exit (mutually exclusive with other flags)
+  if (countOnly) {
+    console.log(String(records.length));
+    return;
+  }
+
+  // --limit: truncate after filtering
+  if (limitN !== null) {
+    records = records.slice(0, limitN);
+  }
+
+  // Apply projection
+  if (fieldsProjection || noSummaries) {
+    records = records.map((rec) => {
+      let projected = rec;
+      if (noSummaries) {
+        projected = Object.fromEntries(Object.entries(projected).filter(([k]) => k !== 'summaries'));
+      }
+      if (fieldsProjection) {
+        projected = Object.fromEntries(fieldsProjection.map((f) => [f, projected[f]]).filter(([, v]) => v !== undefined));
+      }
+      return projected;
+    });
+  }
+
   console.log(JSON.stringify(records, null, 2));
 }
 

package/dist/forge-payload/tools/substitute-placeholders.cjs

@@ -9,7 +9,7 @@
  * output to the appropriate output directories.
  *
  * Output path mapping (--target claude-code, default):
- *   base-pack/commands/  → <outRoot>/.claude/commands/forge/
+ *   base-pack/commands/  → <outRoot>/.claude/commands/<prefix>/
  *   base-pack/personas/  → <outRoot>/.forge/personas/
  *   base-pack/skills/    → <outRoot>/.forge/skills/
  *   base-pack/workflows/ → <outRoot>/.forge/workflows/