mrvn-cli 0.2.5 → 0.2.6

package/README.md

@@ -172,6 +172,19 @@ Feature (PO)          Epic (TL)              Sprint (DM)
 
 When a sprint links to epics, those epics are auto-tagged with `sprint:SP-xxx`. Work items (actions, decisions, questions) are associated with sprints via the same `sprint:SP-xxx` tag convention. The `generate_sprint_progress` report shows linked epics with statuses, tagged work items grouped by status, and done/total completion %.
 
+**Sprint planning** is supported by the `gather_sprint_planning_context` tool, which aggregates all planning-relevant data in a single call:
+
+| Section | Contents |
+|---------|----------|
+| `approvedFeatures` | Approved features sorted by priority, with epic counts by status |
+| `backlog` | Unassigned non-done epics, sorted by parent feature priority, enriched with feature context and effort estimates |
+| `activeSprint` | Current active sprint with linked epic statuses, work item counts, and completion % |
+| `velocityReference` | Last 2 completed sprints with epic count, effort strings, and work item throughput |
+| `blockers` | Open questions, open risk-finding and blocker-report contributions |
+| `summary` | Total backlog size, approved features with no epics, epics at risk, planned sprint count |
+
+When asked to propose a sprint, the DM reasons through priority, capacity, dependencies, and risk to present a structured proposal. The TL focuses on technical readiness, effort balance, and feature coverage. Both personas call this tool automatically before proposing a sprint plan.
+
 This provides **hard enforcement** (epics must link to approved features) combined with **soft guidance** (persona prompts steer each role toward their responsibilities) and **sprint-level tracking** for time-boxed delivery.
 
 ## Configuration
@@ -406,7 +419,7 @@ src/agent/                 → Claude Agent SDK integration, MCP tools
 src/mcp/                   → Standalone MCP stdio server adapter
 src/plugins/               → Plugin system (methodology plugins)
   ├── types.ts             → MarvinPlugin interface
-  ├── common.ts            → Shared registrations + tool factory (meetings, reports, features, epics, sprints)
+  ├── common.ts            → Shared registrations + tool factory (meetings, reports, features, epics, sprints, sprint planning)
   ├── registry.ts          → Plugin resolution
   └── builtin/
       ├── generic-agile.ts → Default methodology

package/dist/index.js

@@ -16204,6 +16204,188 @@ function createSprintTools(store) {
   ];
 }
 
+// src/plugins/builtin/tools/sprint-planning.ts
+import { tool as tool13 } from "@anthropic-ai/claude-agent-sdk";
+var PRIORITY_ORDER = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3
+};
+function priorityRank(p) {
+  return PRIORITY_ORDER[p ?? ""] ?? 99;
+}
+function createSprintPlanningTools(store) {
+  return [
+    tool13(
+      "gather_sprint_planning_context",
+      "Aggregate all planning-relevant data for proposing the next sprint: approved features, backlog epics, active sprint, velocity reference, blockers, and summary stats",
+      {
+        focusFeature: external_exports.string().optional().describe("Filter backlog to epics of a specific feature ID (e.g. 'F-001')"),
+        sprintDurationDays: external_exports.number().optional().describe("Expected sprint duration in days \u2014 passed through for capacity reasoning")
+      },
+      async (args) => {
+        const features = store.list({ type: "feature" });
+        const epics = store.list({ type: "epic" });
+        const sprints = store.list({ type: "sprint" });
+        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 epicsByStatus = {};
+          for (const e of linkedEpics) {
+            epicsByStatus[e.frontmatter.status] = (epicsByStatus[e.frontmatter.status] ?? 0) + 1;
+          }
+          return {
+            id: f.frontmatter.id,
+            title: f.frontmatter.title,
+            priority: f.frontmatter.priority,
+            owner: f.frontmatter.owner,
+            epicCount: linkedEpics.length,
+            epicsByStatus
+          };
+        });
+        const assignedEpicIds = /* @__PURE__ */ new Set();
+        for (const sp of sprints) {
+          const linked = sp.frontmatter.linkedEpics ?? [];
+          for (const id of linked) assignedEpicIds.add(id);
+        }
+        const featureMap = new Map(features.map((f) => [f.frontmatter.id, f]));
+        let backlogEpics = epics.filter(
+          (e) => !assignedEpicIds.has(e.frontmatter.id) && e.frontmatter.status !== "done"
+        );
+        if (args.focusFeature) {
+          backlogEpics = backlogEpics.filter(
+            (e) => e.frontmatter.linkedFeature === 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);
+        }).map((e) => {
+          const parent = featureMap.get(e.frontmatter.linkedFeature);
+          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,
+            estimatedEffort: e.frontmatter.estimatedEffort ?? null,
+            targetDate: e.frontmatter.targetDate ?? null
+          };
+        });
+        const activeSprintDoc = sprints.find((s) => s.frontmatter.status === "active") ?? null;
+        let activeSprint = null;
+        if (activeSprintDoc) {
+          const linkedEpicIds = activeSprintDoc.frontmatter.linkedEpics ?? [];
+          const linkedEpics = linkedEpicIds.map((epicId) => {
+            const epic = store.get(epicId);
+            return epic ? { id: epicId, title: epic.frontmatter.title, status: epic.frontmatter.status } : { id: epicId, title: "(not found)", status: "unknown" };
+          });
+          const allDocs = store.list();
+          const sprintTag = `sprint:${activeSprintDoc.frontmatter.id}`;
+          const workItems = allDocs.filter(
+            (d) => d.frontmatter.type !== "sprint" && d.frontmatter.type !== "epic" && d.frontmatter.tags?.includes(sprintTag)
+          );
+          const doneCount = workItems.filter(
+            (d) => d.frontmatter.status === "done" || d.frontmatter.status === "resolved" || d.frontmatter.status === "closed"
+          ).length;
+          const completionPct = workItems.length > 0 ? Math.round(doneCount / workItems.length * 100) : 0;
+          activeSprint = {
+            id: activeSprintDoc.frontmatter.id,
+            title: activeSprintDoc.frontmatter.title,
+            goal: activeSprintDoc.frontmatter.goal,
+            startDate: activeSprintDoc.frontmatter.startDate,
+            endDate: activeSprintDoc.frontmatter.endDate,
+            linkedEpics,
+            workItems: { total: workItems.length, done: doneCount, completionPct }
+          };
+        }
+        const completedSprints = sprints.filter((s) => s.frontmatter.status === "completed").sort((a, b) => {
+          const da = a.frontmatter.endDate ?? "";
+          const db = b.frontmatter.endDate ?? "";
+          return da < db ? 1 : da > db ? -1 : 0;
+        }).slice(0, 2);
+        const velocityReference = completedSprints.map((sp) => {
+          const linkedEpicIds = sp.frontmatter.linkedEpics ?? [];
+          const efforts = [];
+          for (const epicId of linkedEpicIds) {
+            const epic = store.get(epicId);
+            if (epic?.frontmatter.estimatedEffort) {
+              efforts.push(String(epic.frontmatter.estimatedEffort));
+            }
+          }
+          const allDocs = store.list();
+          const sprintTag = `sprint:${sp.frontmatter.id}`;
+          const workItems = allDocs.filter(
+            (d) => d.frontmatter.type !== "sprint" && d.frontmatter.type !== "epic" && d.frontmatter.tags?.includes(sprintTag)
+          );
+          return {
+            id: sp.frontmatter.id,
+            title: sp.frontmatter.title,
+            startDate: sp.frontmatter.startDate,
+            endDate: sp.frontmatter.endDate,
+            epicCount: linkedEpicIds.length,
+            efforts,
+            workItemCount: workItems.length
+          };
+        });
+        const openBlockerContributions = contributions.filter(
+          (c) => c.frontmatter.status === "open" && (c.frontmatter.contributionType === "risk-finding" || c.frontmatter.contributionType === "blocker-report")
+        );
+        const blockers = {
+          openQuestions: questions.map((q) => ({
+            id: q.frontmatter.id,
+            title: q.frontmatter.title
+          })),
+          openRiskAndBlockerContributions: openBlockerContributions.map((c) => ({
+            id: c.frontmatter.id,
+            title: c.frontmatter.title,
+            contributionType: c.frontmatter.contributionType
+          }))
+        };
+        const totalBacklogEfforts = backlog.filter((e) => e.estimatedEffort !== null).map((e) => String(e.estimatedEffort));
+        const approvedFeaturesWithNoEpics = approvedFeatures.filter((f) => f.epicCount === 0).map((f) => ({ id: f.id, title: f.title }));
+        const now = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+        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;
+          return false;
+        }).map((e) => ({
+          id: e.frontmatter.id,
+          title: e.frontmatter.title,
+          reason: e.frontmatter.targetDate && e.frontmatter.targetDate < now ? "past-target-date" : "deferred-feature"
+        }));
+        const plannedSprintCount = sprints.filter((s) => s.frontmatter.status === "planned").length;
+        const summary = {
+          totalBacklogEpics: backlog.length,
+          totalBacklogEfforts,
+          approvedFeaturesWithNoEpics,
+          epicsAtRisk,
+          plannedSprintCount
+        };
+        const result = {
+          approvedFeatures,
+          backlog,
+          activeSprint,
+          velocityReference,
+          blockers,
+          summary,
+          ...args.sprintDurationDays !== void 0 ? { sprintDurationDays: args.sprintDurationDays } : {}
+        };
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      },
+      { annotations: { readOnly: true } }
+    )
+  ];
+}
+
 // src/plugins/common.ts
 var COMMON_REGISTRATIONS = [
   { type: "meeting", dirName: "meetings", idPrefix: "M" },
@@ -16220,7 +16402,8 @@ function createCommonTools(store) {
     ...createFeatureTools(store),
     ...createEpicTools(store),
     ...createContributionTools(store),
-    ...createSprintTools(store)
+    ...createSprintTools(store),
+    ...createSprintPlanningTools(store)
   ];
 }
 
@@ -16293,7 +16476,12 @@ var genericAgilePlugin = {
 - **list_sprints** / **get_sprint**: View sprints to understand iteration scope and delivery dates.
 - **update_sprint**: Assign epics to sprints by updating linkedEpics when breaking features into work.
 - Tag technical actions and decisions with \`sprint:SP-xxx\` to associate them with a sprint.
-- Use **generate_sprint_progress** to track technical work completion within an iteration.`,
+- Use **generate_sprint_progress** to track technical work completion within an iteration.
+
+**Sprint Planning:**
+- When asked to plan or propose a sprint, ALWAYS call **gather_sprint_planning_context** first.
+- Focus on: technical readiness of each epic, open technical questions or spikes, effort balance across the sprint, and feature coverage.
+- Present a structured sprint proposal with technical rationale for each selected epic, known technical risks, and any prerequisite work that should be completed first.`,
     "delivery-manager": `You track delivery across features and epics, manage schedules, and report on progress.
 
 **Report Tools:**
@@ -16341,7 +16529,13 @@ var genericAgilePlugin = {
 - Assign epics to sprints via linkedEpics.
 - Tag work items (actions, decisions, questions) with \`sprint:SP-xxx\` for sprint scoping.
 - Track delivery dates and flag at-risk sprints.
-- Register past/completed sprints for historical tracking.`,
+- Register past/completed sprints for historical tracking.
+
+**Sprint Planning:**
+- When asked to plan or propose a sprint, ALWAYS call **gather_sprint_planning_context** first. It aggregates approved features, backlog epics, active sprint status, velocity from recent sprints, blockers, and summary stats in one call.
+- Reason through: priority (critical/high features first), capacity (compare backlog effort to velocity reference), dependencies and blockers, balance across features, and risk.
+- Present a structured sprint proposal: title, goal, suggested dates, selected epics with rationale for each, excluded epics with reason, and identified risks.
+- After user confirmation, use **create_sprint** with the agreed epics to persist the sprint.`,
     "*": `You have access to feature, epic, sprint, and meeting tools for project coordination:
 
 **Features** (F-xxx): Product capabilities defined by the Product Owner. Features progress through draft \u2192 approved \u2192 done.
@@ -16364,10 +16558,10 @@ var genericAgilePlugin = {
 };
 
 // src/plugins/builtin/tools/use-cases.ts
-import { tool as tool13 } from "@anthropic-ai/claude-agent-sdk";
+import { tool as tool14 } from "@anthropic-ai/claude-agent-sdk";
 function createUseCaseTools(store) {
   return [
-    tool13(
+    tool14(
       "list_use_cases",
       "List all extension use cases, optionally filtered by status or extension type",
       {
@@ -16397,7 +16591,7 @@ function createUseCaseTools(store) {
       },
       { annotations: { readOnly: true } }
     ),
-    tool13(
+    tool14(
       "get_use_case",
       "Get the full content of a specific use case by ID",
       { id: external_exports.string().describe("Use case ID (e.g. 'UC-001')") },
@@ -16424,7 +16618,7 @@ function createUseCaseTools(store) {
       },
       { annotations: { readOnly: true } }
     ),
-    tool13(
+    tool14(
       "create_use_case",
       "Create a new extension use case definition (Phase 1: Assess Extension Use Case)",
       {
@@ -16458,7 +16652,7 @@ function createUseCaseTools(store) {
         };
       }
     ),
-    tool13(
+    tool14(
       "update_use_case",
       "Update an existing extension use case",
       {
@@ -16488,10 +16682,10 @@ function createUseCaseTools(store) {
 }
 
 // src/plugins/builtin/tools/tech-assessments.ts
-import { tool as tool14 } from "@anthropic-ai/claude-agent-sdk";
+import { tool as tool15 } from "@anthropic-ai/claude-agent-sdk";
 function createTechAssessmentTools(store) {
   return [
-    tool14(
+    tool15(
       "list_tech_assessments",
       "List all technology assessments, optionally filtered by status",
       {
@@ -16522,7 +16716,7 @@ function createTechAssessmentTools(store) {
       },
       { annotations: { readOnly: true } }
     ),
-    tool14(
+    tool15(
       "get_tech_assessment",
       "Get the full content of a specific technology assessment by ID",
       { id: external_exports.string().describe("Tech assessment ID (e.g. 'TA-001')") },
@@ -16549,7 +16743,7 @@ function createTechAssessmentTools(store) {
       },
       { annotations: { readOnly: true } }
     ),
-    tool14(
+    tool15(
       "create_tech_assessment",
       "Create a new technology assessment linked to an assessed/approved use case (Phase 2: Assess Extension Technology)",
       {
@@ -16620,7 +16814,7 @@ function createTechAssessmentTools(store) {
         };
       }
     ),
-    tool14(
+    tool15(
       "update_tech_assessment",
       "Update an existing technology assessment. The linked use case cannot be changed.",
       {
@@ -16650,10 +16844,10 @@ function createTechAssessmentTools(store) {
 }
 
 // src/plugins/builtin/tools/extension-designs.ts
-import { tool as tool15 } from "@anthropic-ai/claude-agent-sdk";
+import { tool as tool16 } from "@anthropic-ai/claude-agent-sdk";
 function createExtensionDesignTools(store) {
   return [
-    tool15(
+    tool16(
       "list_extension_designs",
       "List all extension designs, optionally filtered by status",
       {
@@ -16683,7 +16877,7 @@ function createExtensionDesignTools(store) {
       },
       { annotations: { readOnly: true } }
     ),
-    tool15(
+    tool16(
       "get_extension_design",
       "Get the full content of a specific extension design by ID",
       { id: external_exports.string().describe("Extension design ID (e.g. 'XD-001')") },
@@ -16710,7 +16904,7 @@ function createExtensionDesignTools(store) {
       },
       { annotations: { readOnly: true } }
     ),
-    tool15(
+    tool16(
       "create_extension_design",
       "Create a new extension design linked to a recommended tech assessment (Phase 3: Define Extension Target Solution)",
       {
@@ -16778,7 +16972,7 @@ function createExtensionDesignTools(store) {
         };
       }
     ),
-    tool15(
+    tool16(
       "update_extension_design",
       "Update an existing extension design. The linked tech assessment cannot be changed.",
       {
@@ -16807,10 +17001,10 @@ function createExtensionDesignTools(store) {
 }
 
 // src/plugins/builtin/tools/aem-reports.ts
-import { tool as tool16 } from "@anthropic-ai/claude-agent-sdk";
+import { tool as tool17 } from "@anthropic-ai/claude-agent-sdk";
 function createAemReportTools(store) {
   return [
-    tool16(
+    tool17(
       "generate_extension_portfolio",
       "Generate a portfolio view of all use cases with their linked tech assessments and extension designs",
       {},
@@ -16862,7 +17056,7 @@ function createAemReportTools(store) {
       },
       { annotations: { readOnly: true } }
     ),
-    tool16(
+    tool17(
       "generate_tech_readiness",
       "Generate a BTP technology readiness report showing service coverage and gaps across assessments",
       {},
@@ -16914,7 +17108,7 @@ function createAemReportTools(store) {
       },
       { annotations: { readOnly: true } }
     ),
-    tool16(
+    tool17(
       "generate_phase_status",
       "Generate a phase progress report showing artifact counts and readiness per AEM phase",
       {},
@@ -16976,11 +17170,11 @@ function createAemReportTools(store) {
 import * as fs6 from "fs";
 import * as path6 from "path";
 import * as YAML4 from "yaml";
-import { tool as tool17 } from "@anthropic-ai/claude-agent-sdk";
+import { tool as tool18 } from "@anthropic-ai/claude-agent-sdk";
 var PHASES = ["assess-use-case", "assess-technology", "define-solution"];
 function createAemPhaseTools(store, marvinDir) {
   return [
-    tool17(
+    tool18(
       "get_current_phase",
       "Get the current AEM phase from project configuration",
       {},
@@ -17001,7 +17195,7 @@ function createAemPhaseTools(store, marvinDir) {
       },
       { annotations: { readOnly: true } }
     ),
-    tool17(
+    tool18(
       "advance_phase",
       "Advance to the next AEM phase. Performs soft gate checks and warns if artifacts are incomplete, but does not block.",
       {
@@ -17776,7 +17970,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/skills/action-tools.ts
-import { tool as tool18 } from "@anthropic-ai/claude-agent-sdk";
+import { tool as tool19 } from "@anthropic-ai/claude-agent-sdk";
 
 // src/skills/action-runner.ts
 import { query as query3 } from "@anthropic-ai/claude-agent-sdk";
@@ -17842,7 +18036,7 @@ function createSkillActionTools(skills, context) {
     if (!skill.actions) continue;
     for (const action of skill.actions) {
       tools.push(
-        tool18(
+        tool19(
           `${skill.id}__${action.id}`,
           action.description,
           {
@@ -17934,10 +18128,10 @@ ${lines.join("\n\n")}`;
 }
 
 // src/mcp/persona-tools.ts
-import { tool as tool19 } from "@anthropic-ai/claude-agent-sdk";
+import { tool as tool20 } from "@anthropic-ai/claude-agent-sdk";
 function createPersonaTools(ctx, marvinDir) {
   return [
-    tool19(
+    tool20(
       "set_persona",
       "Set the active persona for this session. Returns full guidance for the selected persona including behavioral rules, allowed document types, and scope. Call this before working to ensure persona-appropriate behavior.",
       {
@@ -17967,7 +18161,7 @@ ${summaries}`
         };
       }
     ),
-    tool19(
+    tool20(
       "get_persona_guidance",
       "Get guidance for a persona without changing the active persona. If no persona is specified, lists all available personas with summaries.",
       {
@@ -20502,7 +20696,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.2.5");
+  ).version("0.2.6");
   program.command("init").description("Initialize a new Marvin project in the current directory").action(async () => {
     await initCommand();
   });