@entelligentsia/forgecli 0.11.2 → 0.15.0

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

@@ -0,0 +1,511 @@
+{
+  "version": "0.46.1",
+  "generatedAt": "2026-05-22T02:09:22.016Z",
+  "generatedByTool": "build-manifest.cjs",
+  "namespaces": {
+    "personas": {
+      "logicalKey": "personas",
+      "dir": ".forge/personas",
+      "files": [
+        "architect.md",
+        "bug-fixer.md",
+        "collator.md",
+        "engineer.md",
+        "qa-engineer.md",
+        "supervisor.md"
+      ]
+    },
+    "skills": {
+      "logicalKey": "skills",
+      "dir": ".forge/skills",
+      "files": [
+        "architect-skills.md",
+        "bug-fixer-skills.md",
+        "collator-skills.md",
+        "engineer-skills.md",
+        "generic-skills.md",
+        "qa-engineer-skills.md",
+        "supervisor-skills.md"
+      ]
+    },
+    "workflows": {
+      "logicalKey": "workflows",
+      "dir": ".forge/workflows",
+      "files": [
+        "architect_approve.md",
+        "architect_review_sprint_completion.md",
+        "architect_sprint_intake.md",
+        "architect_sprint_plan.md",
+        "collator_agent.md",
+        "commit_task.md",
+        "fix_bug.md",
+        "implement_plan.md",
+        "migrate_structural.md",
+        "orchestrate_task.md",
+        "plan_task.md",
+        "quiz_agent.md",
+        "review_code.md",
+        "review_plan.md",
+        "run_sprint.md",
+        "sprint_retrospective.md",
+        "update_implementation.md",
+        "update_plan.md",
+        "validate_task.md"
+      ]
+    },
+    "templates": {
+      "logicalKey": "templates",
+      "dir": ".forge/templates",
+      "files": [
+        "CODE_REVIEW_TEMPLATE.md",
+        "COST_REPORT_TEMPLATE.md",
+        "PLAN_REVIEW_TEMPLATE.md",
+        "PLAN_SUMMARY_TEMPLATE.json",
+        "PLAN_TEMPLATE.md",
+        "PROGRESS_TEMPLATE.md",
+        "RETROSPECTIVE_TEMPLATE.md",
+        "SPRINT_MANIFEST_TEMPLATE.md",
+        "SPRINT_REQUIREMENTS_TEMPLATE.md",
+        "TASK_PROMPT_TEMPLATE.md"
+      ]
+    },
+    "commands": {
+      "logicalKey": "commands",
+      "dir": ".claude/commands",
+      "prefixed": true,
+      "files": [
+        "approve.md",
+        "collate.md",
+        "commit.md",
+        "enhance.md",
+        "fix-bug.md",
+        "implement.md",
+        "plan.md",
+        "quiz-agent.md",
+        "retrospective.md",
+        "review-code.md",
+        "review-plan.md",
+        "run-sprint.md",
+        "run-task.md",
+        "sprint-intake.md",
+        "sprint-plan.md",
+        "validate.md"
+      ]
+    },
+    "fragments": {
+      "logicalKey": "fragments",
+      "dir": ".forge/workflows/_fragments",
+      "files": [
+        "context-injection.md",
+        "event-emission-schema.md",
+        "finalize.md",
+        "friction-emit.md",
+        "progress-reporting.md",
+        "store-cli-verbs.md"
+      ]
+    },
+    "schemas": {
+      "logicalKey": "schemas",
+      "dir": ".forge/schemas",
+      "files": [
+        "bug.schema.json",
+        "collation-state.schema.json",
+        "config.schema.json",
+        "event-sidecar.schema.json",
+        "event.schema.json",
+        "feature.schema.json",
+        "progress-entry.schema.json",
+        "project-context.schema.json",
+        "project-overlay.schema.json",
+        "proposal.schema.json",
+        "sprint.schema.json",
+        "structure-versions.schema.json",
+        "task.schema.json"
+      ]
+    }
+  },
+  "edges": {
+    "workflows": {
+      "architect_approve": {
+        "personas": [
+          ".forge/personas/architect.md"
+        ],
+        "skills": [
+          ".forge/skills/architect-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [],
+        "sub_workflows": [],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md"
+        ],
+        "config_fields": [
+          "paths.engineering"
+        ]
+      },
+      "collator_agent": {
+        "personas": [
+          ".forge/personas/collator.md"
+        ],
+        "skills": [
+          ".forge/skills/collator-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [],
+        "sub_workflows": [],
+        "kb_docs": [
+          "{KB_PATH}/MASTER_INDEX.md"
+        ],
+        "config_fields": [
+          "paths.engineering"
+        ]
+      },
+      "commit_task": {
+        "personas": [
+          ".forge/personas/engineer.md"
+        ],
+        "skills": [
+          ".forge/skills/engineer-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [
+          ".forge/templates/PROGRESS_TEMPLATE.md"
+        ],
+        "sub_workflows": [],
+        "kb_docs": [],
+        "config_fields": [
+          "commands.test",
+          "paths.engineering"
+        ]
+      },
+      "fix_bug": {
+        "personas": [
+          ".forge/personas/bug-fixer.md",
+          ".forge/personas/supervisor.md",
+          ".forge/personas/architect.md",
+          ".forge/personas/engineer.md",
+          ".forge/personas/collator.md"
+        ],
+        "skills": [
+          ".forge/skills/bug-fixer-skills.md",
+          ".forge/skills/supervisor-skills.md",
+          ".forge/skills/architect-skills.md",
+          ".forge/skills/engineer-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [
+          ".forge/templates/PROGRESS_TEMPLATE.md"
+        ],
+        "sub_workflows": [
+          ".forge/workflows/plan_task.md",
+          ".forge/workflows/implement_plan.md",
+          ".forge/workflows/review_plan.md",
+          ".forge/workflows/review_code.md",
+          ".forge/workflows/architect_approve.md",
+          ".forge/workflows/commit_task.md"
+        ],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md",
+          "{KB_PATH}/architecture/routing.md"
+        ],
+        "config_fields": [
+          "commands.test",
+          "paths.engineering"
+        ]
+      },
+      "implement_plan": {
+        "personas": [
+          ".forge/personas/engineer.md"
+        ],
+        "skills": [
+          ".forge/skills/engineer-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [
+          ".forge/templates/PROGRESS_TEMPLATE.md"
+        ],
+        "sub_workflows": [
+          ".forge/workflows/review_code.md"
+        ],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md",
+          "{KB_PATH}/architecture/routing.md"
+        ],
+        "config_fields": [
+          "commands.test",
+          "paths.engineering"
+        ]
+      },
+      "orchestrate_task": {
+        "personas": [
+          ".forge/personas/architect.md",
+          ".forge/personas/engineer.md",
+          ".forge/personas/supervisor.md",
+          ".forge/personas/bug-fixer.md",
+          ".forge/personas/collator.md",
+          ".forge/personas/qa-engineer.md"
+        ],
+        "skills": [
+          ".forge/skills/architect-skills.md",
+          ".forge/skills/engineer-skills.md",
+          ".forge/skills/supervisor-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [],
+        "sub_workflows": [
+          ".forge/workflows/plan_task.md",
+          ".forge/workflows/implement_plan.md",
+          ".forge/workflows/review_plan.md",
+          ".forge/workflows/review_code.md",
+          ".forge/workflows/fix_bug.md",
+          ".forge/workflows/architect_approve.md",
+          ".forge/workflows/commit_task.md",
+          ".forge/workflows/validate_task.md"
+        ],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md"
+        ],
+        "config_fields": [
+          "paths.engineering"
+        ]
+      },
+      "plan_task": {
+        "personas": [
+          ".forge/personas/architect.md"
+        ],
+        "skills": [
+          ".forge/skills/architect-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [
+          ".forge/templates/PLAN_TEMPLATE.md",
+          ".forge/templates/TASK_PROMPT_TEMPLATE.md"
+        ],
+        "sub_workflows": [
+          ".forge/workflows/review_plan.md"
+        ],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md"
+        ],
+        "config_fields": [
+          "commands.test",
+          "paths.engineering"
+        ]
+      },
+      "sprint_retrospective": {
+        "personas": [
+          ".forge/personas/architect.md"
+        ],
+        "skills": [
+          ".forge/skills/architect-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [
+          ".forge/templates/RETROSPECTIVE_TEMPLATE.md"
+        ],
+        "sub_workflows": [],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md"
+        ],
+        "config_fields": [
+          "paths.engineering"
+        ]
+      },
+      "review_code": {
+        "personas": [
+          ".forge/personas/supervisor.md"
+        ],
+        "skills": [
+          ".forge/skills/supervisor-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [
+          ".forge/templates/CODE_REVIEW_TEMPLATE.md"
+        ],
+        "sub_workflows": [],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md",
+          "{KB_PATH}/architecture/routing.md"
+        ],
+        "config_fields": [
+          "commands.test",
+          "paths.engineering"
+        ]
+      },
+      "review_plan": {
+        "personas": [
+          ".forge/personas/supervisor.md"
+        ],
+        "skills": [
+          ".forge/skills/supervisor-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [
+          ".forge/templates/PLAN_REVIEW_TEMPLATE.md"
+        ],
+        "sub_workflows": [],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md"
+        ],
+        "config_fields": [
+          "paths.engineering"
+        ]
+      },
+      "architect_review_sprint_completion": {
+        "personas": [
+          ".forge/personas/architect.md"
+        ],
+        "skills": [
+          ".forge/skills/architect-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [],
+        "sub_workflows": [],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md"
+        ],
+        "config_fields": [
+          "paths.engineering"
+        ]
+      },
+      "architect_sprint_intake": {
+        "personas": [
+          ".forge/personas/product-manager.md"
+        ],
+        "skills": [
+          ".forge/skills/architect-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [
+          ".forge/templates/SPRINT_REQUIREMENTS_TEMPLATE.md",
+          ".forge/templates/SPRINT_MANIFEST_TEMPLATE.md"
+        ],
+        "sub_workflows": [],
+        "kb_docs": [
+          "{KB_PATH}/MASTER_INDEX.md",
+          "{KB_PATH}/architecture/stack.md"
+        ],
+        "config_fields": [
+          "project.prefix",
+          "paths.engineering"
+        ]
+      },
+      "architect_sprint_plan": {
+        "personas": [
+          ".forge/personas/architect.md"
+        ],
+        "skills": [
+          ".forge/skills/architect-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [
+          ".forge/templates/SPRINT_MANIFEST_TEMPLATE.md",
+          ".forge/templates/TASK_PROMPT_TEMPLATE.md"
+        ],
+        "sub_workflows": [],
+        "kb_docs": [
+          "{KB_PATH}/MASTER_INDEX.md",
+          "{KB_PATH}/architecture/stack.md"
+        ],
+        "config_fields": [
+          "project.prefix",
+          "paths.engineering"
+        ]
+      },
+      "update_implementation": {
+        "personas": [
+          ".forge/personas/engineer.md"
+        ],
+        "skills": [
+          ".forge/skills/engineer-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [
+          ".forge/templates/PROGRESS_TEMPLATE.md"
+        ],
+        "sub_workflows": [
+          ".forge/workflows/review_code.md"
+        ],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md"
+        ],
+        "config_fields": [
+          "commands.test",
+          "paths.engineering"
+        ]
+      },
+      "update_plan": {
+        "personas": [
+          ".forge/personas/architect.md"
+        ],
+        "skills": [
+          ".forge/skills/architect-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [
+          ".forge/templates/PLAN_TEMPLATE.md"
+        ],
+        "sub_workflows": [
+          ".forge/workflows/review_plan.md"
+        ],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md"
+        ],
+        "config_fields": [
+          "paths.engineering"
+        ]
+      },
+      "validate_task": {
+        "personas": [
+          ".forge/personas/qa-engineer.md"
+        ],
+        "skills": [
+          ".forge/skills/qa-engineer-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [],
+        "sub_workflows": [],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md"
+        ],
+        "config_fields": [
+          "commands.test",
+          "paths.engineering"
+        ]
+      },
+      "quiz_agent": {
+        "personas": [
+          ".forge/personas/qa-engineer.md"
+        ],
+        "skills": [
+          ".forge/skills/qa-engineer-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [],
+        "sub_workflows": [],
+        "kb_docs": [
+          "{KB_PATH}/architecture/stack.md",
+          "{KB_PATH}/MASTER_INDEX.md"
+        ],
+        "config_fields": [
+          "paths.engineering"
+        ]
+      },
+      "migrate_structural": {
+        "personas": [
+          ".forge/personas/engineer.md"
+        ],
+        "skills": [
+          ".forge/skills/engineer-skills.md",
+          ".forge/skills/generic-skills.md"
+        ],
+        "templates": [],
+        "sub_workflows": [],
+        "kb_docs": [],
+        "config_fields": [
+          "paths.engineering"
+        ]
+      }
+    }
+  }
+}

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

@@ -22,6 +22,99 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 
+// ── Persona parser — two variants: base-pack (no frontmatter) and meta (YAML frontmatter) ──
+//
+// Base-pack personas: first line is a markdown heading, e.g. "# Architect" or
+// "# Architect — subtitle". The rest is the body. id and role are derived from
+// the filename. summary is the first sentence of the first non-heading line.
+// responsibilities and outputs are derived from section headers in the body.
+// file_ref is derived from the file path.
+//
+// Meta personas: YAML frontmatter block (--- ... ---) containing all required
+// fields. The body is ignored.
+
+function parsePersona(content, filePath) {
+  if (content.startsWith('---')) {
+    // Meta format — parse frontmatter then ignore body
+    const fm = parseFrontmatter(content, filePath);
+    // Re-validate required fields for meta personas
+    for (const field of REQUIRED_PERSONA_FIELDS) {
+      if (!(field in fm)) {
+        throw new Error(`${filePath}: frontmatter missing required field '${field}'`);
+      }
+    }
+    return fm;
+  }
+
+  // Base-pack format — no frontmatter, derive fields from content
+  const lines = content.split(/\r?\n/);
+  const fileName = path.basename(filePath, '.md'); // e.g. "architect"
+
+  // Derive id and role from filename (e.g. "meta-architect.md" → "architect", "architect.md" → "architect")
+  const id = fileName.replace(/^meta-/, '').replace(/-skills$/, '');
+  const role = id;
+
+  // Extract summary: first non-heading, non-empty line
+  let summary = '';
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('{{')) {
+      // Grab first sentence (up to first period + space or first line break)
+      const sentenceEnd = trimmed.search(/\.\s/);
+      summary = sentenceEnd >= 0 ? trimmed.slice(0, sentenceEnd + 1) : trimmed;
+      break;
+    }
+  }
+
+  // Derive responsibilities and outputs from section headers
+  const responsibilities = [];
+  const outputs = [];
+  for (const line of lines) {
+    if (/^##\s+(What I Produce|Outputs?)/i.test(line)) {
+      // Collect bullet points under this header until next ## or end
+      let i = lines.indexOf(line) + 1;
+      while (i < lines.length && !lines[i].startsWith('##')) {
+        const m = lines[i].match(/^[-*]\s+(.+)/);
+        if (m) outputs.push(m[1].trim());
+        i++;
+      }
+    }
+    if (/^##\s+(Capabilities?)/i.test(line)) {
+      let i = lines.indexOf(line) + 1;
+      while (i < lines.length && !lines[i].startsWith('##')) {
+        const m = lines[i].match(/^[-*]\s+(.+)/);
+        if (m) responsibilities.push(m[1].trim());
+        i++;
+      }
+    }
+  }
+
+  // file_ref: base-pack personas become .forge/personas/<id>.md
+  const file_ref = `.forge/personas/${id}.md`;
+
+  return { id, role, summary, responsibilities, outputs, file_ref };
+}
+
+// ── Skill parser — base-pack skills (with frontmatter, no file_ref) and meta skills (with file_ref) ──
+
+function parseSkill(content, filePath) {
+  const fm = parseFrontmatter(content, filePath);
+
+  // Skills must have: id, applies_to, summary, capabilities
+  for (const field of ['id', 'applies_to', 'summary', 'capabilities']) {
+    if (!(field in fm)) {
+      throw new Error(`${filePath}: frontmatter missing required field '${field}'`);
+    }
+  }
+
+  // file_ref is present in meta skills; derive it for base-pack skills from the path
+  if (!fm.file_ref) {
+    fm.file_ref = `.forge/skills/${path.basename(filePath)}`;
+  }
+
+  return fm;
+}
+
 // ── YAML frontmatter parser ──────────────────────────────────────────────────
 // Narrow-scope parser: handles scalars, folded scalars (`>`), block lists
 // (`- item`) under a key, and inline flow lists (`[a, b]`). Anything else
@@ -123,30 +216,44 @@ function listMarkdown(dir) {
     .map((f) => path.join(dir, f));
 }
 
-function loadEntries(dir, requiredFields) {
+function loadPersonas(dir) {
   const entries = {};
   for (const filePath of listMarkdown(dir)) {
     const content = fs.readFileSync(filePath, 'utf8');
-    let fm;
     try {
-      fm = parseFrontmatter(content, filePath);
+      const persona = parsePersona(content, filePath);
+      entries[persona.id] = persona;
     } catch (err) {
-      // Re-throw with original path-bearing message intact.
       throw err;
     }
-    for (const field of requiredFields) {
-      if (!(field in fm)) {
-        throw new Error(`${filePath}: frontmatter missing required field '${field}'`);
-      }
+  }
+  return entries;
+}
+
+function loadSkills(dir) {
+  const entries = {};
+  for (const filePath of listMarkdown(dir)) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    try {
+      const skill = parseSkill(content, filePath);
+      entries[skill.id] = skill;
+    } catch (err) {
+      throw err;
     }
-    entries[fm.id] = fm;
   }
   return entries;
 }
 
 function buildPack({ personaDir, skillDir }) {
-  const personas = loadEntries(personaDir, REQUIRED_PERSONA_FIELDS);
-  const skills = loadEntries(skillDir, REQUIRED_SKILL_FIELDS);
+  const personas = loadPersonas(personaDir);
+  const skills = loadSkills(skillDir);
+
+  const personaCount = Object.keys(personas).length;
+  const skillCount = Object.keys(skills).length;
+  if (personaCount === 0 && skillCount === 0) {
+    throw new Error('no personas or skills found; refusing to write empty pack');
+  }
+
   return {
     version: 1,
     built_at: new Date().toISOString(),
@@ -220,6 +327,8 @@ if (require.main === module) {
 
 module.exports = {
   parseFrontmatter,
+  parsePersona,
+  parseSkill,
   buildPack,
   computeSourceHash,
   writePack,