mrvn-cli 0.3.7 → 0.4.0

package/README.md

@@ -109,24 +109,26 @@ Each persona has a tuned system prompt that shapes how Claude approaches your pr
 Marvin enforces a structured product development workflow:
 
 1. **Product Owner** defines features (`F-xxx`) as `draft`, then approves them when requirements are clear
-2. **Tech Lead** breaks approved features into implementation epics (`E-xxx`) — the system **enforces** that epics can only be created against approved features
+2. **Tech Lead** breaks approved features into implementation epics (`E-xxx`) — the system **enforces** that epics can only be created against approved features. An epic can link to **one or more features** (e.g. a cross-cutting epic spanning auth and profiles)
 3. **Delivery Manager** creates sprints (`SP-xxx`) with goals and date boundaries, assigns epics to sprints, and tracks progress
 
 ```
-Feature (PO)          Epic (TL)              Sprint (DM)
-┌──────────┐    ┌──────────────┐    ┌──────────────────────┐
-│ F-001    │───▶│ E-001        │───▶│ SP-001               │
-│ approved │    │ linked: F-001│    │ linkedEpics: [E-001]  │
-└──────────┘    ├──────────────┤    │ goal: "Deliver auth"  │
-                │ E-002        │    │ 2026-03-01..03-14     │
-                │ linked: F-001│    └──────────────────────┘
-                └──────────────┘             │
-                                    ┌────────┴─────────────┐
-                                    │ A-001 (sprint:SP-001) │
-                                    │ D-003 (sprint:SP-001) │
-                                    └──────────────────────┘
+Feature (PO)          Epic (TL)                       Sprint (DM)
+┌──────────┐    ┌────────────────────────┐    ┌──────────────────────┐
+│ F-001    │───▶│ E-001                  │───▶│ SP-001               │
+│ approved │    │ linked: [F-001]        │    │ linkedEpics: [E-001]  │
+└──────────┘    ├────────────────────────┤    │ goal: "Deliver auth"  │
+                │ E-002                  │    │ 2026-03-01..03-14     │
+┌──────────┐───▶│ linked: [F-001, F-002] │    └──────────────────────┘
+│ F-002    │    └────────────────────────┘             │
+│ approved │                                  ┌────────┴─────────────┐
+└──────────┘                                  │ A-001 (sprint:SP-001) │
+                                              │ D-003 (sprint:SP-001) │
+                                              └──────────────────────┘
 ```
 
+Epics store `linkedFeature` as an array (e.g. `["F-001", "F-002"]`). Legacy files with a single string value are normalized to an array on read for backwards compatibility. Multi-linked epics appear in progress reports under each linked feature, and feature tags (`feature:F-xxx`) are generated for all linked features.
+
 **Sprints** are time-boxed iterations with:
 - `goal` — what the sprint aims to deliver
 - `startDate` / `endDate` — sprint boundaries (ISO dates)

package/dist/index.js

@@ -15000,6 +15000,17 @@ function createSessionTools(store) {
 import * as http2 from "http";
 import { tool as tool20 } from "@anthropic-ai/claude-agent-sdk";
 
+// src/plugins/builtin/tools/epic-utils.ts
+function normalizeLinkedFeatures(value) {
+  if (value === void 0 || value === null) return [];
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value.filter((v) => typeof v === "string");
+  return [];
+}
+function generateFeatureTags(features) {
+  return features.map((id) => `feature:${id}`);
+}
+
 // src/reports/gar/collector.ts
 function collectGarMetrics(store) {
   const allActions = store.list({ type: "action" });
@@ -15472,7 +15483,7 @@ function getDiagramData(store) {
           id: fm.id,
           title: fm.title,
           status: fm.status,
-          linkedFeature: fm.linkedFeature
+          linkedFeature: normalizeLinkedFeatures(fm.linkedFeature)
         });
         break;
       case "feature":
@@ -16263,8 +16274,8 @@ function buildArtifactFlowchart(data) {
   lines.push("  classDef default fill:#1e293b,stroke:#475569,color:#e2e8f0");
   const nodeIds = /* @__PURE__ */ new Set();
   for (const epic of data.epics) {
-    if (epic.linkedFeature) {
-      const feature = data.features.find((f) => f.id === epic.linkedFeature);
+    for (const featureId of epic.linkedFeature) {
+      const feature = data.features.find((f) => f.id === featureId);
       if (feature) {
         const fNode = feature.id.replace(/-/g, "_");
         const eNode = epic.id.replace(/-/g, "_");
@@ -17079,7 +17090,7 @@ function createReportTools(store) {
             id: epicDoc.frontmatter.id,
             title: epicDoc.frontmatter.title,
             status: epicDoc.frontmatter.status,
-            linkedFeature: epicDoc.frontmatter.linkedFeature,
+            linkedFeature: normalizeLinkedFeatures(epicDoc.frontmatter.linkedFeature),
             targetDate: epicDoc.frontmatter.targetDate,
             estimatedEffort: epicDoc.frontmatter.estimatedEffort,
             workItems: {
@@ -17206,7 +17217,7 @@ function createReportTools(store) {
         const epicDocs = store.list({ type: "epic" });
         const features = featureDocs.filter((f) => !args.feature || f.frontmatter.id === args.feature).map((f) => {
           const linkedEpics = epicDocs.filter(
-            (e) => e.frontmatter.linkedFeature === f.frontmatter.id
+            (e) => normalizeLinkedFeatures(e.frontmatter.linkedFeature).includes(f.frontmatter.id)
           );
           const byStatus = {};
           for (const e of linkedEpics) {
@@ -17410,14 +17421,14 @@ function createEpicTools(store) {
         let docs = store.list({ type: "epic", status: args.status });
         if (args.linkedFeature) {
           docs = docs.filter(
-            (d) => d.frontmatter.linkedFeature === args.linkedFeature
+            (d) => normalizeLinkedFeatures(d.frontmatter.linkedFeature).includes(args.linkedFeature)
           );
         }
         const summary = docs.map((d) => ({
           id: d.frontmatter.id,
           title: d.frontmatter.title,
           status: d.frontmatter.status,
-          linkedFeature: d.frontmatter.linkedFeature,
+          linkedFeature: normalizeLinkedFeatures(d.frontmatter.linkedFeature),
           owner: d.frontmatter.owner,
           targetDate: d.frontmatter.targetDate,
           estimatedEffort: d.frontmatter.estimatedEffort,
@@ -17458,11 +17469,11 @@ function createEpicTools(store) {
     ),
     tool10(
       "create_epic",
-      "Create a new epic linked to an approved feature. The linked feature must exist and be approved.",
+      "Create a new epic linked to one or more approved features. All linked features must exist and be approved.",
       {
         title: external_exports.string().describe("Epic title"),
         content: external_exports.string().describe("Epic description and scope"),
-        linkedFeature: external_exports.string().describe("Feature ID to link this epic to (e.g. 'F-001')"),
+        linkedFeature: external_exports.union([external_exports.string(), external_exports.array(external_exports.string())]).describe("Feature ID(s) to link this epic to (e.g. 'F-001' or ['F-001', 'F-002'])"),
         status: external_exports.enum(["planned", "in-progress", "done"]).optional().describe("Epic status (default: 'planned')"),
         owner: external_exports.string().optional().describe("Epic owner"),
         targetDate: external_exports.string().optional().describe("Target completion date (ISO format)"),
@@ -17470,45 +17481,48 @@ function createEpicTools(store) {
         tags: external_exports.array(external_exports.string()).optional().describe("Additional tags")
       },
       async (args) => {
-        const feature = store.get(args.linkedFeature);
-        if (!feature) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `Feature ${args.linkedFeature} not found`
-              }
-            ],
-            isError: true
-          };
-        }
-        if (feature.frontmatter.type !== "feature") {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `${args.linkedFeature} is a ${feature.frontmatter.type}, not a feature`
-              }
-            ],
-            isError: true
-          };
-        }
-        if (feature.frontmatter.status !== "approved") {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `Feature ${args.linkedFeature} has status '${feature.frontmatter.status}'. Only approved features can have epics. Ask the Product Owner to approve it first.`
-              }
-            ],
-            isError: true
-          };
+        const linkedFeatures = normalizeLinkedFeatures(args.linkedFeature);
+        for (const featureId of linkedFeatures) {
+          const feature = store.get(featureId);
+          if (!feature) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Feature ${featureId} not found`
+                }
+              ],
+              isError: true
+            };
+          }
+          if (feature.frontmatter.type !== "feature") {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `${featureId} is a ${feature.frontmatter.type}, not a feature`
+                }
+              ],
+              isError: true
+            };
+          }
+          if (feature.frontmatter.status !== "approved") {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Feature ${featureId} has status '${feature.frontmatter.status}'. Only approved features can have epics. Ask the Product Owner to approve it first.`
+                }
+              ],
+              isError: true
+            };
+          }
         }
         const frontmatter = {
           title: args.title,
           status: args.status ?? "planned",
-          linkedFeature: args.linkedFeature,
-          tags: [`feature:${args.linkedFeature}`, ...args.tags ?? []]
+          linkedFeature: linkedFeatures,
+          tags: [...generateFeatureTags(linkedFeatures), ...args.tags ?? []]
         };
         if (args.owner) frontmatter.owner = args.owner;
         if (args.targetDate) frontmatter.targetDate = args.targetDate;
@@ -17518,7 +17532,7 @@ function createEpicTools(store) {
           content: [
             {
               type: "text",
-              text: `Created epic ${doc.frontmatter.id}: ${doc.frontmatter.title} (linked to ${args.linkedFeature})`
+              text: `Created epic ${doc.frontmatter.id}: ${doc.frontmatter.title} (linked to ${linkedFeatures.join(", ")})`
             }
           ]
         };
@@ -17526,7 +17540,7 @@ function createEpicTools(store) {
     ),
     tool10(
       "update_epic",
-      "Update an existing epic. The linked feature cannot be changed.",
+      "Update an existing epic, including its linked features.",
       {
         id: external_exports.string().describe("Epic ID to update"),
         title: external_exports.string().optional().describe("New title"),
@@ -17535,10 +17549,49 @@ function createEpicTools(store) {
         owner: external_exports.string().optional().describe("New owner"),
         targetDate: external_exports.string().optional().describe("New target date"),
         estimatedEffort: external_exports.string().optional().describe("New estimated effort"),
+        linkedFeature: external_exports.union([external_exports.string(), external_exports.array(external_exports.string())]).optional().describe("New linked feature ID(s)"),
         tags: external_exports.array(external_exports.string()).optional().describe("Replace tags (e.g. remove 'risk', add 'risk-mitigated')")
       },
       async (args) => {
-        const { id, content, ...updates } = args;
+        const { id, content, linkedFeature: rawLinkedFeature, tags: userTags, ...updates } = args;
+        if (rawLinkedFeature !== void 0) {
+          const linkedFeatures = normalizeLinkedFeatures(rawLinkedFeature);
+          for (const featureId of linkedFeatures) {
+            const feature = store.get(featureId);
+            if (!feature) {
+              return {
+                content: [
+                  { type: "text", text: `Feature ${featureId} not found` }
+                ],
+                isError: true
+              };
+            }
+            if (feature.frontmatter.type !== "feature") {
+              return {
+                content: [
+                  { type: "text", text: `${featureId} is a ${feature.frontmatter.type}, not a feature` }
+                ],
+                isError: true
+              };
+            }
+            if (feature.frontmatter.status !== "approved") {
+              return {
+                content: [
+                  { type: "text", text: `Feature ${featureId} has status '${feature.frontmatter.status}'. Only approved features can have epics. Ask the Product Owner to approve it first.` }
+                ],
+                isError: true
+              };
+            }
+          }
+          updates.linkedFeature = linkedFeatures;
+          const existingDoc = store.get(id);
+          const existingTags = existingDoc?.frontmatter.tags ?? [];
+          const nonFeatureTags = existingTags.filter((t) => !t.startsWith("feature:"));
+          const baseTags = userTags ?? nonFeatureTags;
+          updates.tags = [...generateFeatureTags(linkedFeatures), ...baseTags];
+        } else if (userTags !== void 0) {
+          updates.tags = userTags;
+        }
         const doc = store.update(id, updates, content);
         return {
           content: [
@@ -17873,7 +17926,9 @@ function createSprintPlanningTools(store) {
         const questions = store.list({ type: "question", status: "open" });
         const contributions = store.list({ type: "contribution" });
         const approvedFeatures = features.filter((f) => f.frontmatter.status === "approved").sort((a, b) => priorityRank(a.frontmatter.priority) - priorityRank(b.frontmatter.priority)).map((f) => {
-          const linkedEpics = epics.filter((e) => e.frontmatter.linkedFeature === f.frontmatter.id);
+          const linkedEpics = epics.filter(
+            (e) => normalizeLinkedFeatures(e.frontmatter.linkedFeature).includes(f.frontmatter.id)
+          );
           const epicsByStatus = {};
           for (const e of linkedEpics) {
             epicsByStatus[e.frontmatter.status] = (epicsByStatus[e.frontmatter.status] ?? 0) + 1;
@@ -17898,22 +17953,25 @@ function createSprintPlanningTools(store) {
         );
         if (args.focusFeature) {
           backlogEpics = backlogEpics.filter(
-            (e) => e.frontmatter.linkedFeature === args.focusFeature
+            (e) => normalizeLinkedFeatures(e.frontmatter.linkedFeature).includes(args.focusFeature)
           );
         }
         const backlog = backlogEpics.sort((a, b) => {
-          const fa = featureMap.get(a.frontmatter.linkedFeature);
-          const fb = featureMap.get(b.frontmatter.linkedFeature);
-          return priorityRank(fa?.frontmatter.priority) - priorityRank(fb?.frontmatter.priority);
+          const aFeatures = normalizeLinkedFeatures(a.frontmatter.linkedFeature);
+          const bFeatures = normalizeLinkedFeatures(b.frontmatter.linkedFeature);
+          const aRank = Math.min(...aFeatures.map((id) => priorityRank(featureMap.get(id)?.frontmatter.priority)), 99);
+          const bRank = Math.min(...bFeatures.map((id) => priorityRank(featureMap.get(id)?.frontmatter.priority)), 99);
+          return aRank - bRank;
         }).map((e) => {
-          const parent = featureMap.get(e.frontmatter.linkedFeature);
+          const linkedFeatures = normalizeLinkedFeatures(e.frontmatter.linkedFeature);
+          const parents = linkedFeatures.map((id) => featureMap.get(id)).filter(Boolean);
           return {
             id: e.frontmatter.id,
             title: e.frontmatter.title,
             status: e.frontmatter.status,
-            linkedFeature: e.frontmatter.linkedFeature,
-            featureTitle: parent?.frontmatter.title ?? null,
-            featurePriority: parent?.frontmatter.priority ?? null,
+            linkedFeature: linkedFeatures,
+            featureTitle: parents.map((p) => p.frontmatter.title).join(", ") || null,
+            featurePriority: parents.map((p) => p.frontmatter.priority).join(", ") || null,
             estimatedEffort: e.frontmatter.estimatedEffort ?? null,
             targetDate: e.frontmatter.targetDate ?? null
           };
@@ -17994,8 +18052,8 @@ function createSprintPlanningTools(store) {
         const epicsAtRisk = epics.filter((e) => {
           if (e.frontmatter.status === "done") return false;
           if (e.frontmatter.targetDate && e.frontmatter.targetDate < now) return true;
-          const parent = featureMap.get(e.frontmatter.linkedFeature);
-          if (parent?.frontmatter.status === "deferred") return true;
+          const linkedIds = normalizeLinkedFeatures(e.frontmatter.linkedFeature);
+          if (linkedIds.some((id) => featureMap.get(id)?.frontmatter.status === "deferred")) return true;
           return false;
         }).map((e) => ({
           id: e.frontmatter.id,
@@ -23650,7 +23708,7 @@ function createProgram() {
   const program = new Command();
   program.name("marvin").description(
     "AI-powered product development assistant with Product Owner, Delivery Manager, and Technical Lead personas"
-  ).version("0.3.7");
+  ).version("0.4.0");
   program.command("init").description("Initialize a new Marvin project in the current directory").action(async () => {
     await initCommand();
   });