spec-gen-cli 1.2.5 → 1.2.6

package/README.md

@@ -476,6 +476,7 @@ Priority: CLI flags > environment variables > config file > provider defaults.
 | `spec-gen view` | Launch interactive graph & spec viewer in the browser | No |
 | `spec-gen mcp` | Start MCP server (stdio, for Cline / Claude Code) | No |
 | `spec-gen doctor` | Check environment and configuration for common issues | No |
+| `spec-gen refresh-stories` | Re-annotate story files with stale risk context | No |
 
 ### Global Options
 
@@ -830,6 +831,8 @@ All tools run on **pure static analysis** -- no LLM quota consumed.
 | `check_spec_drift` | Detect code changes not reflected in OpenSpec specs. Compares git-changed files against spec coverage maps. Issues: gap / stale / uncovered / orphaned-spec / adr-gap. | Yes (generate) |
 | `search_specs` | Semantic search over OpenSpec specifications to find requirements, design notes, and architecture decisions by meaning. Returns linked source files for graph highlighting. Use this when asked "which spec covers X?" or "where should we implement Z?". Requires a spec index built with `spec-gen analyze` or `--reindex-specs`. | Yes (generate) |
 | `list_spec_domains` | List all OpenSpec domains available in this project. Use this to discover what domains exist before doing a targeted `search_specs` call. | Yes (generate) |
+| `generate_change_proposal` | Given a story/task description, chains `orient` + `search_specs` + `analyze_impact` to produce a structured change proposal at `openspec/changes/{slug}/proposal.md` with affected domains, risk scores, and insertion points. | Yes |
+| `annotate_story` | Reads a story/task markdown file, runs structural analysis, and patches a `## Risk Context` section in-place with domains, risk scores, blocking refactors, and insertion points. | Yes |
 
 ### Parameters
 
@@ -1005,6 +1008,21 @@ domain     string   Filter by domain name (e.g. "auth", "analyzer")
 section    string   Filter by section type: "requirements" | "purpose" | "design" | "architecture" | "entities"
 ```
 
+**`generate_change_proposal`**
+```
+directory     string   Absolute path to the project directory
+description   string   Natural-language description of the change (story, intent, or spec delta)
+slug          string   URL-safe identifier for the proposal (e.g. "add-payment-retry")
+storyContent  string   Optional full story markdown to embed in the proposal
+```
+
+**`annotate_story`**
+```
+directory      string   Absolute path to the project directory
+storyFilePath  string   Path to the story file (relative to project root or absolute)
+description    string   Natural-language summary of the story for structural analysis
+```
+
 ### Typical workflow
 
 **Scenario A -- Initial exploration**
@@ -1045,6 +1063,17 @@ section    string   Filter by section type: "requirements" | "purpose" | "design
 3. check_spec_drift({ directory })                    # verify after implementation
 ```
 
+**Scenario E -- Agentic workflow (risk-gated implementation)**
+```
+1. generate_change_proposal({ directory, description, slug })  # proposal.md with risk + domains
+2. annotate_story({ directory, storyFilePath, description })   # patch story with risk_context
+3. orient({ directory, task: "..." })                          # scope functions + insertion points
+4. analyze_impact({ directory, symbol: "topFunction" })        # confirm risk before coding
+5. check_spec_drift({ directory })                             # verify after implementation
+```
+
+See [docs/agentic-workflows/](docs/agentic-workflows/) for full integration patterns with BMAD, Mistral Vibe, spec-kit, and Claude Code.
+
 ## Interactive Graph Viewer
 
 `spec-gen view` launches a local React app that visualises your codebase analysis and lets you explore spec requirements side-by-side with the dependency graph.
@@ -1385,6 +1414,10 @@ for (const [key, req] of Object.entries(requirements)) {
 | [examples/openspec-analysis/](examples/openspec-analysis/) | Static analysis output from `spec-gen analyze` |
 | [examples/openspec-cli/](examples/openspec-cli/) | Specifications generated with `spec-gen generate` |
 | [examples/drift-demo/](examples/drift-demo/) | Sample project configured for drift detection |
+| [examples/bmad/](examples/bmad/) | BMAD Method integration — agents, tasks, templates for brownfield codebases |
+| [examples/mistral-vibe/](examples/mistral-vibe/) | Mistral Vibe skills for analyze, generate, plan-refactor, implement-story |
+| [examples/spec-kit/](examples/spec-kit/) | spec-kit extension with `before_implement` / `after_implement` hooks |
+| [examples/gsd/](examples/gsd/) | Get-Shit-Done Claude Code commands for orient + drift |
 
 ## Development
 
@@ -1392,11 +1425,11 @@ for (const [key, req] of Object.entries(requirements)) {
 npm install          # Install dependencies
 npm run dev          # Development mode (watch)
 npm run build        # Build
-npm run test:run     # Run tests (2059 unit tests)
+npm run test:run     # Run tests (2200+ unit tests)
 npm run typecheck    # Type check
 ```
 
-2050+ unit tests covering static analysis, call graph (including Swift), refactor analysis, spec mapping, drift detection, LLM enhancement, ADR generation, MCP handlers, cross-file edge synthesis, and the full CLI.
+2200+ unit tests covering static analysis, call graph (including Swift), refactor analysis, spec mapping, drift detection, LLM enhancement, ADR generation, MCP handlers, change proposals, cross-file edge synthesis, and the full CLI.
 
 ## Links
 
@@ -1406,5 +1439,6 @@ npm run typecheck    # Type check
 - [OpenSpec Integration](docs/OPENSPEC-INTEGRATION.md) - How spec-gen integrates with OpenSpec
 - [OpenSpec Format](docs/OPENSPEC-FORMAT.md) - Spec format reference
 - [Philosophy](docs/PHILOSOPHY.md) - "Archaeology over Creativity"
+- [Agentic Workflows](docs/agentic-workflows/) - Integration patterns for BMAD, Mistral Vibe, spec-kit, GSD
 - [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions
 - [AGENTS.md](AGENTS.md) - LLM system prompt for direct prompting

package/dist/cli/commands/mcp.d.ts

@@ -67,6 +67,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -111,6 +114,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -152,6 +158,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -196,6 +205,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -251,6 +263,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -304,6 +319,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -351,6 +369,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -414,6 +435,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -461,6 +485,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -508,6 +535,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -559,6 +589,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -606,6 +639,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -650,6 +686,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -697,6 +736,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -747,6 +789,9 @@ export declare const TOOL_DEFINITIONS: ({
             fanOutThreshold?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -800,6 +845,9 @@ export declare const TOOL_DEFINITIONS: ({
             fanOutThreshold?: undefined;
             description?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -853,6 +901,68 @@ export declare const TOOL_DEFINITIONS: ({
             fanOutThreshold?: undefined;
             description?: undefined;
             language?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            directory: {
+                type: string;
+                description: string;
+            };
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            language: {
+                type: string;
+                description: string;
+            };
+            domain: {
+                type: string;
+                description: string;
+            };
+            section: {
+                type: string;
+                description: string;
+            };
+            task?: undefined;
+            force?: undefined;
+            filePattern?: undefined;
+            functionName?: undefined;
+            direction?: undefined;
+            maxDepth?: undefined;
+            format?: undefined;
+            entryFunction?: undefined;
+            targetFunction?: undefined;
+            maxPaths?: undefined;
+            orphansOnly?: undefined;
+            base?: undefined;
+            files?: undefined;
+            domains?: undefined;
+            failOn?: undefined;
+            maxFiles?: undefined;
+            symbol?: undefined;
+            depth?: undefined;
+            sortBy?: undefined;
+            minFanIn?: undefined;
+            filePath?: undefined;
+            fanOutThreshold?: undefined;
+            description?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -897,6 +1007,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -944,6 +1057,9 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };
@@ -992,6 +1108,112 @@ export declare const TOOL_DEFINITIONS: ({
             language?: undefined;
             query?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            directory: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            slug: {
+                type: string;
+                description: string;
+            };
+            storyContent: {
+                type: string;
+                description: string;
+            };
+            task?: undefined;
+            limit?: undefined;
+            force?: undefined;
+            filePattern?: undefined;
+            functionName?: undefined;
+            direction?: undefined;
+            maxDepth?: undefined;
+            format?: undefined;
+            entryFunction?: undefined;
+            targetFunction?: undefined;
+            maxPaths?: undefined;
+            domain?: undefined;
+            orphansOnly?: undefined;
+            base?: undefined;
+            files?: undefined;
+            domains?: undefined;
+            failOn?: undefined;
+            maxFiles?: undefined;
+            symbol?: undefined;
+            depth?: undefined;
+            sortBy?: undefined;
+            minFanIn?: undefined;
+            filePath?: undefined;
+            fanOutThreshold?: undefined;
+            language?: undefined;
+            query?: undefined;
+            section?: undefined;
+            storyFilePath?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            directory: {
+                type: string;
+                description: string;
+            };
+            storyFilePath: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            task?: undefined;
+            limit?: undefined;
+            force?: undefined;
+            filePattern?: undefined;
+            functionName?: undefined;
+            direction?: undefined;
+            maxDepth?: undefined;
+            format?: undefined;
+            entryFunction?: undefined;
+            targetFunction?: undefined;
+            maxPaths?: undefined;
+            domain?: undefined;
+            orphansOnly?: undefined;
+            base?: undefined;
+            files?: undefined;
+            domains?: undefined;
+            failOn?: undefined;
+            maxFiles?: undefined;
+            symbol?: undefined;
+            depth?: undefined;
+            sortBy?: undefined;
+            minFanIn?: undefined;
+            filePath?: undefined;
+            fanOutThreshold?: undefined;
+            language?: undefined;
+            query?: undefined;
+            section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
         };
         required: string[];
     };
@@ -1036,6 +1258,9 @@ export declare const TOOL_DEFINITIONS: ({
             description?: undefined;
             language?: undefined;
             section?: undefined;
+            slug?: undefined;
+            storyContent?: undefined;
+            storyFilePath?: undefined;
         };
         required: string[];
     };

package/dist/cli/commands/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAEhG,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,kCAAkC,EAClC,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,gBAAgB,EAChB,4BAA4B,EAC5B,iBAAiB,EAGlB,MAAM,8CAA8C,CAAC;AAEtD,OAAO,EACL,qBAAqB,EACrB,6BAA6B,EAC7B,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,EAG1B,MAAM,8CAA8C,CAAC;AAGtD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,CAAC;AAG/C,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,kCAAkC,EAClC,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,4BAA4B,EAC5B,iBAAiB,EACjB,qBAAqB,EACrB,6BAA6B,EAC7B,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,GAC1B,CAAC;AAMF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAsoB5B,CAAC;AAmLF,eAAO,MAAM,UAAU,SAK0C,CAAC"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAEhG,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,kCAAkC,EAClC,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,gBAAgB,EAChB,4BAA4B,EAC5B,iBAAiB,EAIlB,MAAM,8CAA8C,CAAC;AAGtD,OAAO,EACL,qBAAqB,EACrB,6BAA6B,EAC7B,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,EAG1B,MAAM,8CAA8C,CAAC;AAGtD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,CAAC;AAG/C,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,kCAAkC,EAClC,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,4BAA4B,EAC5B,iBAAiB,EACjB,qBAAqB,EACrB,6BAA6B,EAC7B,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,GAC1B,CAAC;AAMF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAovB5B,CAAC;AA+LF,eAAO,MAAM,UAAU,SAK0C,CAAC"}

package/dist/cli/commands/mcp.js

@@ -23,8 +23,9 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { sanitizeMcpError, validateDirectory } from '../../core/services/mcp-handlers/utils.js';
 import { DEFAULT_DRIFT_MAX_FILES } from '../../constants.js';
 import { handleGetCallGraph, handleGetSubgraph, handleAnalyzeImpact, handleGetLowRiskRefactorCandidates, handleGetLeafFunctions, handleGetCriticalHubs, handleGetGodFunctions, handleGetFileDependencies, handleTraceExecutionPath, } from '../../core/services/mcp-handlers/graph.js';
-import { handleSearchCode, handleSuggestInsertionPoints, handleSearchSpecs, handleListSpecDomains, handleGetSpec, } from '../../core/services/mcp-handlers/semantic.js';
+import { handleSearchCode, handleSuggestInsertionPoints, handleSearchSpecs, handleListSpecDomains, handleGetSpec, handleUnifiedSearch, } from '../../core/services/mcp-handlers/semantic.js';
 import { handleOrient } from '../../core/services/mcp-handlers/orient.js';
+import { handleGenerateChangeProposal, handleAnnotateStory } from '../../core/services/mcp-handlers/change.js';
 import { handleAnalyzeCodebase, handleGetArchitectureOverview, handleGetRefactorReport, handleGetDuplicateReport, handleGetSignatures, handleGetMapping, handleCheckSpecDrift, handleGetFunctionSkeleton, handleGetFunctionBody, handleGetDecisions, } from '../../core/services/mcp-handlers/analysis.js';
 // Re-export utilities for tests
 export { sanitizeMcpError, validateDirectory };
@@ -569,6 +570,45 @@ export const TOOL_DEFINITIONS = [
             required: ['directory', 'query'],
         },
     },
+    {
+        name: 'search_unified',
+        description: 'USE THIS WHEN: you want to find where something is implemented AND what the spec says about it ' +
+            'in a single call. Searches both code functions and spec requirements simultaneously, then ' +
+            'cross-boosts results that are linked through mapping.json — so a function that implements a ' +
+            'matching requirement ranks higher than one found by code search alone. ' +
+            'Returns results with type "code", "spec", or "both" and a mappingBoost score. ' +
+            'Requires "spec-gen analyze --embed" and a prior "spec-gen generate" run.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: {
+                    type: 'string',
+                    description: 'Absolute path to the project directory',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Natural language query, e.g. "validate user authentication"',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of results to return (default: 10)',
+                },
+                language: {
+                    type: 'string',
+                    description: 'Filter code results by language (e.g. "TypeScript")',
+                },
+                domain: {
+                    type: 'string',
+                    description: 'Filter spec results by domain name',
+                },
+                section: {
+                    type: 'string',
+                    description: 'Filter spec results by section type: "requirements", "purpose", etc.',
+                },
+            },
+            required: ['directory', 'query'],
+        },
+    },
     {
         name: 'get_spec',
         description: 'Return the full content of a spec domain\'s specification file (spec.md) and the ' +
@@ -632,6 +672,69 @@ export const TOOL_DEFINITIONS = [
             required: ['directory', 'filePath'],
         },
     },
+    {
+        name: 'generate_change_proposal',
+        description: 'USE THIS WHEN: you have a BMAD story, a feature description, or a spec delta request, ' +
+            'and want to create a structured OpenSpec change proposal before writing any code. ' +
+            'Combines orient + search_specs + analyze_impact to produce a pre-filled ' +
+            'openspec/changes/{slug}/proposal.md — no LLM required. ' +
+            'Output includes affected domains, touched requirements, risk scores, and insertion points. ' +
+            'Run analyze_codebase first; spec index optional (degrades gracefully).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: {
+                    type: 'string',
+                    description: 'Absolute path to the project directory',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Intent of the change — story title + primary AC, or a free-form feature description. ' +
+                        'e.g. "add retry logic to payment processing — must retry up to 3 times on timeout"',
+                },
+                slug: {
+                    type: 'string',
+                    description: 'Change identifier used as the directory name, e.g. "add-payment-retry". ' +
+                        'Will be lowercased and hyphenated automatically.',
+                },
+                storyContent: {
+                    type: 'string',
+                    description: 'Optional: full BMAD story content (markdown). If provided, it is embedded verbatim ' +
+                        'in the proposal for traceability.',
+                },
+            },
+            required: ['directory', 'description', 'slug'],
+        },
+    },
+    {
+        name: 'annotate_story',
+        description: 'USE THIS WHEN: you have a BMAD story file and want to auto-populate its risk_context ' +
+            'section with structural analysis from the codebase. ' +
+            'Reads the story file, runs orient + analyze_impact, writes the risk_context block ' +
+            'directly into the file (replaces existing section or inserts it). ' +
+            'Run by the Architect Agent after writing stories — eliminates manual copy-paste of ' +
+            'generate_change_proposal output. Run analyze_codebase first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: {
+                    type: 'string',
+                    description: 'Absolute path to the project directory',
+                },
+                storyFilePath: {
+                    type: 'string',
+                    description: 'Path to the BMAD story markdown file — relative to the project directory ' +
+                        'or absolute. e.g. ".bmad-method/stories/001-add-payment-retry.md"',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Story intent for structural analysis — use story title + primary AC. ' +
+                        'e.g. "add payment retry — must retry up to 3 times on timeout"',
+                },
+            },
+            required: ['directory', 'storyFilePath', 'description'],
+        },
+    },
     {
         name: 'get_decisions',
         description: 'List or search Architecture Decision Records (ADRs) stored in openspec/decisions/. ' +
@@ -758,6 +861,10 @@ async function startMcpServer(options = {}) {
                 const { directory, query, limit = 10, domain, section } = args;
                 result = await handleSearchSpecs(directory, query, limit, domain, section);
             }
+            else if (name === 'search_unified') {
+                const { directory, query, limit = 10, language, domain, section } = args;
+                result = await handleUnifiedSearch(directory, query, limit, language, domain, section);
+            }
             else if (name === 'list_spec_domains') {
                 const { directory } = args;
                 result = await handleListSpecDomains(directory);
@@ -774,6 +881,14 @@ async function startMcpServer(options = {}) {
                 const { directory, filePath, direction = 'both' } = args;
                 result = await handleGetFileDependencies(directory, filePath, direction);
             }
+            else if (name === 'generate_change_proposal') {
+                const { directory, description, slug, storyContent } = args;
+                result = await handleGenerateChangeProposal(directory, description, slug, storyContent);
+            }
+            else if (name === 'annotate_story') {
+                const { directory, storyFilePath, description } = args;
+                result = await handleAnnotateStory(directory, storyFilePath, description);
+            }
             else if (name === 'get_decisions') {
                 const { directory, query } = args;
                 result = await handleGetDecisions(directory, query);