speccrew 0.6.5 → 0.6.8

package/.speccrew/skills/speccrew-knowledge-bizs-init-features/SKILL.md

@@ -8,19 +8,23 @@ tools: Read, Write, Glob, Grep, SearchCodebase, Skill, Bash
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| {source_path} | string | No | Source code directory path (default: project root) |
-| {language} | string | Yes | Target language for generated content (e.g., "zh", "en") |
+| `source_path` | string | No | Source code directory path (default: project root) |
+| `language` | string | Yes | Target language for generated content (e.g., "zh", "en") |
+| `sync_state_bizs_dir` | string | Yes | Absolute path to features and entry-dirs JSON output directory |
+| `configs_dir` | string | Yes | Absolute path to configuration files directory |
+| `ide_skills_dir` | string | Yes | Absolute path to IDE skills directory (e.g., `.qoder/skills`) |
 
 ## Output
 
-- `speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/features-{platform}.json` - Platform-specific feature inventory files
+- `{sync_state_bizs_dir}/features-{platform}.json` - Platform-specific feature inventory files
+- `{sync_state_bizs_dir}/entry-dirs-{platform}.json` - Entry directories configuration files
 
 ## Workflow
 
 ```mermaid
 flowchart TD
     Start([Start]) --> Step1[Step 1: Identify Platforms]
-    Step1 --> Step2[Step 2: Configure Platform Parameters]
+    Step1 --> Step2[Step 2: Identify Entry Directories]
     Step2 --> Step3[Step 3: Execute Inventory Scripts]
     Step3 --> Step4[Step 4: Report Results]
     Step4 --> End([End])
@@ -31,8 +35,8 @@ flowchart TD
 **Detection Process:**
 
 1. **Read Configuration:**
-   - `speccrew-workspace/docs/configs/platform-mapping.json` - Platform type and subtype mappings
-   - `speccrew-workspace/docs/configs/tech-stack-mappings.json` - Tech stack configurations and exclude directories
+   - `{configs_dir}/platform-mapping.json` - Platform type and subtype mappings
+   - `{configs_dir}/tech-stack-mappings.json` - Tech stack configurations and exclude directories
 
 2. Scan `{source_path}` for platform-specific configuration files (e.g., package.json, pubspec.yaml, pom.xml)
 
@@ -52,122 +56,70 @@ flowchart TD
 - Lookup `platform-mapping.json`: `web` + `vue` → `platform_type=web`, `platform_subtype=vue`
 - Lookup `tech-stack-mappings.json`: vue → extensions=[".vue"], exclude_dirs=["components","utils"]
 
-### Step 2: Configure Platform Parameters
+### Step 2: Identify Entry Directories
 
-For each detected platform, configure the following parameters:
+For each platform detected in Step 1, identify business module entry directories.
 
-| Parameter | Description | Example |
-|-----------|-------------|---------|
-| `SourcePath` | Source directory relative to project root | `frontend-web/src/views` |
-| `OutputFileName` | Output file name | `features-web.json` |
-| `PlatformName` | Human-readable platform name | `Web Frontend` |
-| `PlatformType` | Platform category | `web`, `mobile`, `backend`, `desktop` |
-| `PlatformSubtype` | Technology/framework | `vue`, `react`, `flutter`, `spring` |
-| `TechStack` | Technology stack array | `["vue", "typescript"]` |
-| `FileExtensions` | File extensions to scan | `[".vue", ".ts"]` |
-| `ExcludeDirs` | Directories to exclude | `["components", "utils"]` |
+**Option A: Invoke Skill (Recommended)**
 
-### Step 3: Execute Inventory Scripts
+Dispatch Worker with `speccrew-knowledge-bizs-identify-entries` skill:
 
-> **MANDATORY**: You MUST execute the provided scripts via `run_in_terminal`. DO NOT use `read_file`, `search_codebase`, `Glob`, or any other tool to substitute script execution. DO NOT manually scan files and construct JSON output yourself.
+| Parameter | Value |
+|-----------|-------|
+| `platforms` | Platform list from Step 1 (each with platformId, sourcePath, platformType, platformSubtype, techStack) |
+| `workspace_path` | Absolute path to speccrew-workspace |
+| `sync_state_bizs_dir` | `{sync_state_bizs_dir}` |
+| `configs_dir` | `{configs_dir}` |
 
-Execute the inventory script for each platform:
+Worker generates `entry-dirs-{platform_id}.json` files in `{sync_state_bizs_dir}/`.
 
-**Prerequisites:**
-- Node.js 14.0+
+**Option B: Direct Execution**
 
-**Script Location (relative to this skill's directory):**
-- All Platforms: `{skill_path}/scripts/generate-inventory.js`
+If executing directly (without Worker dispatch), follow the same logic as the `speccrew-knowledge-bizs-identify-entries` skill:
+1. Read each platform's directory tree (3 levels deep)
+2. Identify entry directories based on platform type:
+   - **Backend**: Find directories containing `*Controller.*` files, extract business package names
+   - **Frontend**: Find `views/` or `pages/` directories, use first-level subdirectories as modules
+   - **Mobile**: Find `pages/` subdirectories + top-level `pages-*` directories
+3. Apply exclusion rules from `{configs_dir}/tech-stack-mappings.json`
+4. Generate `entry-dirs-{platform_id}.json` files to `{sync_state_bizs_dir}/`
 
-**Example - Web Platform (Vue):**
-```bash
-node "scripts/generate-inventory.js" \
-  --sourcePath "frontend-web/src/views" \
-  --outputFileName "features-web.json" \
-  --platformName "Web Frontend" \
-  --platformType "web" \
-  --platformSubtype "vue" \
-  --techStack "vue,typescript" \
-  --fileExtensions ".vue" \
-  --excludeDirs "components,composables,hooks,utils"
-```
+**Verification**: Confirm each entry-dirs JSON has non-empty `modules` array with business-meaningful names.
 
-**Example - Mobile Platform (UniApp):**
-```bash
-node "scripts/generate-inventory.js" \
-  --sourcePath "frontend-mobile/pages" \
-  --outputFileName "features-mobile.json" \
-  --platformName "Mobile App" \
-  --platformType "mobile" \
-  --platformSubtype "uniapp" \
-  --techStack "uniapp,vue" \
-  --fileExtensions ".vue" \
-  --excludeDirs "components,utils"
-```
+### Step 3: Execute Inventory Scripts
 
-**Example - Backend Platform (Spring Single Module):**
-```bash
-node "scripts/generate-inventory.js" \
-  --sourcePath "backend/src/main/java/com/example/controller" \
-  --outputFileName "features-backend.json" \
-  --platformName "Backend API" \
-  --platformType "backend" \
-  --platformSubtype "spring" \
-  --techStack "spring-boot,java" \
-  --fileExtensions ".java" \
-  --excludeDirs ""
-```
+> **MANDATORY**: You MUST execute the provided scripts via `run_in_terminal`. DO NOT use `read_file`, `search_codebase`, `Glob`, or any other tool to substitute script execution. DO NOT manually scan files and construct JSON output yourself.
 
-**Example - Backend Platform (Spring Multi-Module):**
+Execute the inventory script for each platform using the entry-dirs JSON from Step 2:
 
-> **IMPORTANT for Java/Kotlin backends**: Set `sourcePath` to the Java package root directory (e.g., `yudao-module-system/src/main/java/cn/iocoder/yudao/module/system`), NOT the module root. This ensures the `getModuleName` function extracts business module names (like `dept`, `auth`) instead of Java package segments (like `src`, `cn`).
+**Prerequisites:**
+- Node.js 14.0+
 
-For projects with multiple backend modules (e.g., ruoyi-vue-pro), execute the script once per module:
+**Script Location:**
+- All Platforms: `{ide_skills_dir}/speccrew-knowledge-bizs-init-features/scripts/generate-inventory.js`
 
+**Execution Command:**
 ```bash
-# Module 1: AI
-node "scripts/generate-inventory.js" \
-  --sourcePath "yudao-module-ai/src/main/java/cn/iocoder/yudao/module/ai" \
-  --outputFileName "features-backend-ai.json" \
-  --platformName "Backend API - AI Module" \
-  --platformType "backend" \
-  --platformSubtype "ai" \
-  --techIdentifier "spring" \
-  --techStack "spring-boot,java" \
-  --fileExtensions ".java" \
-  --excludeDirs ""
-
-# Module 2: System
-node "scripts/generate-inventory.js" \
-  --sourcePath "yudao-module-system/src/main/java/cn/iocoder/yudao/module/system" \
-  --outputFileName "features-backend-system.json" \
-  --platformName "Backend API - System Module" \
-  --platformType "backend" \
-  --platformSubtype "system" \
-  --techIdentifier "spring" \
-  --techStack "spring-boot,java" \
-  --fileExtensions ".java" \
-  --excludeDirs ""
+node "{ide_skills_dir}/speccrew-knowledge-bizs-init-features/scripts/generate-inventory.js" --entryDirsFile "{sync_state_bizs_dir}/entry-dirs-{platform_id}.json" --outputDir "{sync_state_bizs_dir}"
 ```
 
-> **Note**: For multi-module backend projects, prefer per-module execution (above) over scan-all to get proper module-level directory isolation (e.g., `backend-ai/`, `backend-system/`).
-
-**Alternative: Scan All Modules at Once**
-
-If all modules share the same parent directory structure, you can scan from the project root:
+**Parameters:**
+- `--entryDirsFile`: Path to the `entry-dirs-{platform_id}.json` file in `{sync_state_bizs_dir}/`
+- `--outputDir`: Output directory for `features-{platform}.json` (use `{sync_state_bizs_dir}`)
 
+**Example:**
 ```bash
-node "scripts/generate-inventory.js" \
-  --sourcePath "." \
-  --outputFileName "features-backend-all.json" \
-  --platformName "Backend API - All Modules" \
-  --platformType "backend" \
-  --platformSubtype "spring" \
-  --techStack "spring-boot,java" \
-  --fileExtensions ".java" \
-  --excludeDirs "test,target,.git"
+# Execute for each platform's entry-dirs file
+node "d:/project/.qoder/skills/speccrew-knowledge-bizs-init-features/scripts/generate-inventory.js" --entryDirsFile "d:/project/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/entry-dirs-backend-system.json" --outputDir "d:/project/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs"
 ```
 
+**Script Parameters**:
+- `--entryDirsFile`: (Required) Path to the `entry-dirs-{platform_id}.json` file in `{sync_state_bizs_dir}/`
+- `--outputDir`: (Required) Output directory for `features-{platform}.json` (use `{sync_state_bizs_dir}`)
+- `--techIdentifier`: (Optional) Technology identifier for tech-stack lookup (auto-detected from platform mapping if omitted)
+- `--fileExtensions`: (Optional) Comma-separated list of file extensions to include
+- `--excludeDirs`: (Optional) Additional directories to exclude
+
 **Output: `features-{platform}.json` Structure:**
 ```json
 {
@@ -175,7 +127,10 @@ node "scripts/generate-inventory.js" \
   "platformType": "web",
   "sourcePath": "frontend-web/src/views",
   "techStack": ["vue", "typescript"],
-  "modules": ["system", "trade", "infra"],
+  "modules": [
+    { "name": "chat", "featureCount": 12 },
+    { "name": "image", "featureCount": 8 }
+  ],
   "totalFiles": 25,
   "analyzedCount": 0,
   "pendingCount": 25,
@@ -196,12 +151,10 @@ node "scripts/generate-inventory.js" \
 ```
 
 **Module Detection Rule:**
-- The `module` field is automatically extracted from each file's relative directory path
-- It uses the **first non-excluded directory level** as the module name
-- Example: `system/user/index.vue` → module = `system`
-- Example: `components/Table.vue` (excluded dir) → skipped by ExcludeDirs
-- Files at root level (no subdirectory) → module = `_root`
-- The top-level `modules` array lists all unique module names found
+- When using `--entryDirsFile` mode (recommended), the `module` field for each feature is determined by matching the file's path against the entry directories defined in the entry-dirs JSON
+- Each file is assigned to the module whose `entryDirs` path matches the file's relative directory
+- The top-level `modules` array lists all modules with their feature counts
+- Files not matching any entry directory → module = `_root`
 
 **sourcePath Format:**
 - In both full-scan mode and entry-dirs mode, `sourcePath` is always a **project-root-relative path**
@@ -225,23 +178,23 @@ Feature Inventory Generated
 
 Platform Inventory Files:
 - Web Frontend:
-  - Inventory File: speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/features-web.json
+  - Inventory File: {sync_state_bizs_dir}/features-web.json
   - Total Features: [N]
   - Status: Generated ✓
 - Mobile App:
-  - Inventory File: speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/features-mobile.json
+  - Inventory File: {sync_state_bizs_dir}/features-mobile.json
   - Total Features: [N]
   - Status: Generated ✓
 - Backend API:
-  - Inventory File: speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/features-api.json
+  - Inventory File: {sync_state_bizs_dir}/features-api.json
   - Total Features: [N]
   - Status: Generated ✓
 
 Final Output:
 - Platform Files:
-  - speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/features-web.json
-  - speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/features-mobile.json
-  - speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/features-api.json
+  - {sync_state_bizs_dir}/features-web.json
+  - {sync_state_bizs_dir}/features-mobile.json
+  - {sync_state_bizs_dir}/features-api.json
 ```
 
 ## Checklist
@@ -251,6 +204,12 @@ Final Output:
 - [ ] Each platform has correct `platformName`, `platformType`, `techStack` configuration
 - [ ] Source directories located for all platforms
 
+### Entry Directory Identification
+- [ ] Entry-dirs JSON files generated for all platforms
+- [ ] Each platform has non-empty modules array
+- [ ] Module names are business-meaningful (not technical terms like `config`, `util`, `controller`)
+- [ ] Entry directory paths are correct and accessible
+
 ### Inventory Generation
 - [ ] **Inventory scripts executed**: Node.js script generated `features-{platform}.json` files
 - [ ] **Inventory files valid**: JSON structure correct, all features listed
@@ -258,7 +217,9 @@ Final Output:
 - [ ] **File paths correct**: All `sourcePath` and `documentPath` values are accurate (sourcePath MUST be project-root-relative path)
 
 ### Output Generation
-- [ ] All platform inventory files generated in `sync-state` directory
+- [ ] All platform inventory files generated in `{sync_state_bizs_dir}` directory
 - [ ] Output path verified
 - [ ] Results reported
 
+> **MANDATORY**: Use the provided absolute paths directly. DO NOT construct or derive paths yourself. DO NOT manually create JSON files.
+

package/.speccrew/skills/speccrew-knowledge-bizs-init-features/scripts/generate-inventory.js

@@ -5,7 +5,7 @@
  * Scans source directory for page files and generates a flat feature list with analysis status tracking.
  * All configuration is passed via parameters - the script does not infer anything.
  *
- * Usage: node generate-inventory.js --sourcePath <path> --outputFileName <name> --platformName <name> --platformType <type> --techStack <json> --fileExtensions <json> [--platformSubtype <subtype>] [--techIdentifier <identifier>] [--analysisMethod <method>] [--excludeDirs <json>] [--includeDataObjects <true|false>]
+ * Usage: node generate-inventory.js --sourcePath <path> --outputFileName <name> --platformName <name> --platformType <type> --techStack <json> --fileExtensions <json> [--platformSubtype <subtype>] [--techIdentifier <identifier>] [--analysisMethod <method>] [--excludeDirs <json>] [--includeDataObjects <true|false>] [--outputDir <dir>]
  *     Array parameters (--techStack, --fileExtensions, --excludeDirs) accept both JSON format and comma-separated format.
  *
  * Whitelist Mode (using --entryDirsFile):
@@ -20,6 +20,11 @@
  *   The suffixes are read from tech-stack-mappings.json (exclude_file_suffixes field).
  *   Use --includeDataObjects true to include them.
  *
+ * Output Directory (--outputDir):
+ *   By default, the script uses findProjectRoot() to locate the project root and outputs to:
+ *   <projectRoot>/speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/
+ *   Use --outputDir to explicitly specify the output directory, bypassing findProjectRoot().
+ *
  * Example (full scan mode):
  *   node generate-inventory.js \
  *     --sourcePath "src/views" \
@@ -639,8 +644,14 @@ function main() {
         
     console.log(`Platform config: type=${platformType}, subtype=${platformSubtype}, framework=${framework}`);
     
-    // Set output directory
-    const outputDir = path.join(projectRoot, 'speccrew-workspace', 'knowledges', 'base', 'sync-state', 'knowledge-bizs');
+    // Set output directory (prefer --outputDir parameter, fallback to findProjectRoot)
+    let outputDir;
+    if (params.outputDir) {
+      outputDir = path.resolve(params.outputDir);
+      console.log(`Using outputDir from parameter: ${outputDir}`);
+    } else {
+      outputDir = path.join(projectRoot, 'speccrew-workspace', 'knowledges', 'base', 'sync-state', 'knowledge-bizs');
+    }
     
     // Generate features from entry dirs
     const success = generateFromEntryDirs(entryDirsData, platformConfig, projectRoot, outputDir);
@@ -735,13 +746,19 @@ function main() {
 
   // Validate required parameters
   if (!sourcePath || !outputFileName || !platformName || !platformType || !techStackStr || !fileExtensionsStr) {
-    console.error('Usage: node generate-inventory.js --sourcePath <path> --outputFileName <name> --platformName <name> --platformType <type> --techStack <json> --fileExtensions <json> [--platformSubtype <subtype>] [--techIdentifier <identifier>] [--analysisMethod <method>] [--excludeDirs <json>] [--includeDataObjects <true|false>]');
+    console.error('Usage: node generate-inventory.js --sourcePath <path> --outputFileName <name> --platformName <name> --platformType <type> --techStack <json> --fileExtensions <json> [--platformSubtype <subtype>] [--techIdentifier <identifier>] [--analysisMethod <method>] [--excludeDirs <json>] [--includeDataObjects <true|false>] [--outputDir <dir>]');
     console.error('Example: node generate-inventory.js --sourcePath "src/views" --outputFileName "features-web.json" --platformName "Web Frontend" --platformType "web" --platformSubtype "vue" --techStack "vue,typescript" --fileExtensions ".vue,.ts" --analysisMethod "ui-based" --excludeDirs "components,composables,hooks,utils"');
     process.exit(1);
   }
 
-  // Find sync-state directory
-  const syncStateDir = path.join(projectRoot, 'speccrew-workspace', 'knowledges', 'base', 'sync-state', 'knowledge-bizs');
+  // Find sync-state directory (prefer --outputDir parameter, fallback to findProjectRoot)
+  let syncStateDir;
+  if (params.outputDir) {
+    syncStateDir = path.resolve(params.outputDir);
+    console.log(`Using outputDir from parameter: ${syncStateDir}`);
+  } else {
+    syncStateDir = path.join(projectRoot, 'speccrew-workspace', 'knowledges', 'base', 'sync-state', 'knowledge-bizs');
+  }
   const outputPath = path.join(syncStateDir, outputFileName);
 
   // Calculate relative source path from project root

package/.speccrew/skills/speccrew-pm-knowledge-detector/SKILL.md

@@ -29,7 +29,9 @@ Detect business knowledge base availability and completeness status. Scans the s
 
 | Variable | Type | Description | Required |
 |----------|------|-------------|----------|
-| `workspace_path` | string | Path to speccrew workspace (e.g., `speccrew-workspace`) | **Yes** |
+| `workspace_path` | string | Absolute path to speccrew workspace (e.g., `speccrew-workspace`) | **Yes** |
+| `sync_state_bizs_dir` | string | Absolute path to `knowledges/base/sync-state/knowledge-bizs/` directory | **Yes** |
+| `configs_dir` | string | Absolute path to `docs/configs/` directory | **Yes** |
 
 ## Output JSON
 
@@ -72,7 +74,7 @@ flowchart TD
 
 Check if the system overview file exists:
 
-1. Construct path: `{workspace_path}/knowledges/bizs/system-overview.md`
+1. Path: `{workspace_path}/knowledges/bizs/system-overview.md`
 2. Attempt to read the file
 3. Set `has_system_overview` = true if exists, false otherwise
 4. Set `system_overview_path` = path if exists, null otherwise
@@ -83,7 +85,7 @@ Check if the system overview file exists:
 
 Scan the sync-state directory for feature inventory files:
 
-1. Construct path: `{workspace_path}/knowledges/base/sync-state/knowledge-bizs/`
+1. Use provided path: `{sync_state_bizs_dir}/`
 2. Glob pattern: `features-*.json`
 3. Collect all matching files into `features_files` array
 4. Set `has_features` = true if any files found
@@ -94,7 +96,7 @@ Scan the sync-state directory for feature inventory files:
 
 Scan for entry directory configuration files:
 
-1. Use same sync-state path
+1. Use provided path: `{sync_state_bizs_dir}/`
 2. Glob pattern: `entry-dirs-*.json`
 3. Collect all matching files into `entry_dirs_files` array
 4. Set `has_entry_dirs` = true if any files found
@@ -137,6 +139,8 @@ Return the complete JSON output.
 3. **Graceful handling**: Return empty arrays if directories don't exist
 4. **Path format**: All returned paths should be relative to workspace_path
 
+> **MANDATORY**: Use the provided absolute paths directly. DO NOT construct or derive paths yourself.
+
 ## Task Completion Report
 
 When the task is complete, report:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speccrew",
-  "version": "0.6.5",
+  "version": "0.6.8",
   "description": "Spec-Driven Development toolkit for AI-powered IDEs",
   "author": "charlesmu99",
   "repository": {

package/workspace-template/scripts/path-utils.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * Path utility functions for speccrew workspace.
+ * All functions expect absolute paths as input.
+ */
+
+/**
+ * Get the sync-state bizs directory path.
+ * @param {string} workspacePath - Absolute path to speccrew-workspace
+ * @returns {string} Absolute path to knowledges/base/sync-state/knowledge-bizs/
+ */
+function getSyncStateBizsDir(workspacePath) {
+  return path.join(workspacePath, 'knowledges', 'base', 'sync-state', 'knowledge-bizs');
+}
+
+/**
+ * Get the sync-state techs directory path.
+ * @param {string} workspacePath - Absolute path to speccrew-workspace
+ * @returns {string} Absolute path to knowledges/base/sync-state/knowledge-techs/
+ */
+function getSyncStateTechsDir(workspacePath) {
+  return path.join(workspacePath, 'knowledges', 'base', 'sync-state', 'knowledge-techs');
+}
+
+/**
+ * Get the features JSON file path for a platform.
+ * @param {string} syncStateBizsDir - Absolute path to sync-state/knowledge-bizs/
+ * @param {string} platformId - Platform identifier (e.g., 'backend-spring')
+ * @returns {string} Absolute path to features-{platformId}.json
+ */
+function getFeaturesFilePath(syncStateBizsDir, platformId) {
+  return path.join(syncStateBizsDir, `features-${platformId}.json`);
+}
+
+/**
+ * Get the entry-dirs JSON file path for a platform.
+ * @param {string} syncStateBizsDir - Absolute path to sync-state/knowledge-bizs/
+ * @param {string} platformId - Platform identifier
+ * @returns {string} Absolute path to entry-dirs-{platformId}.json
+ */
+function getEntryDirsFilePath(syncStateBizsDir, platformId) {
+  return path.join(syncStateBizsDir, `entry-dirs-${platformId}.json`);
+}
+
+/**
+ * Get the feature document path in bizs knowledge base.
+ * @param {string} workspacePath - Absolute path to speccrew-workspace
+ * @param {string} platformId - Platform identifier
+ * @param {string} moduleName - Business module name
+ * @param {string} fileName - Document file name (without extension)
+ * @returns {string} Absolute path to the feature document
+ */
+function getFeatureDocPath(workspacePath, platformId, moduleName, fileName) {
+  return path.join(workspacePath, 'knowledges', 'bizs', platformId, moduleName, `${fileName}.md`);
+}
+
+/**
+ * Get the graph knowledge file path.
+ * @param {string} workspacePath - Absolute path to speccrew-workspace
+ * @param {string} platformId - Platform identifier
+ * @param {string} moduleName - Business module name
+ * @param {string} fileName - Graph file name (e.g., 'knowledge-graph.json')
+ * @returns {string} Absolute path to the graph file
+ */
+function getGraphFilePath(workspacePath, platformId, moduleName, fileName) {
+  return path.join(workspacePath, 'knowledges', 'bizs', platformId, moduleName, fileName);
+}
+
+/**
+ * Generate a standardized marker file name for dispatch tracking.
+ * Format: {module}-{subpath}-{fileName}.{type}.json
+ * @param {string} moduleName - Business module name
+ * @param {string} subpath - Sub-path within module (use '-' separator, empty string if none)
+ * @param {string} fileName - Source file name (without extension)
+ * @param {string} [type='done'] - Marker type ('done', 'error', 'skip')
+ * @returns {string} Marker file name
+ */
+function getMarkerFileName(moduleName, subpath, fileName, type = 'done') {
+  const subpathPart = subpath ? `-${subpath.replace(/[\/\\]/g, '-')}` : '';
+  return `${moduleName}${subpathPart}-${fileName}.${type}.json`;
+}
+
+/**
+ * Get the completed markers directory path.
+ * @param {string} syncStateBizsDir - Absolute path to sync-state/knowledge-bizs/
+ * @returns {string} Absolute path to completed/ directory
+ */
+function getCompletedDir(syncStateBizsDir) {
+  return path.join(syncStateBizsDir, 'completed');
+}
+
+/**
+ * Get the iterations directory path.
+ * @param {string} workspacePath - Absolute path to speccrew-workspace
+ * @returns {string} Absolute path to iterations/
+ */
+function getIterationsDir(workspacePath) {
+  return path.join(workspacePath, 'iterations');
+}
+
+/**
+ * Get the configs directory path.
+ * @param {string} workspacePath - Absolute path to speccrew-workspace
+ * @returns {string} Absolute path to docs/configs/
+ */
+function getConfigsDir(workspacePath) {
+  return path.join(workspacePath, 'docs', 'configs');
+}
+
+/**
+ * Get the update-progress.js script path.
+ * @param {string} workspacePath - Absolute path to speccrew-workspace
+ * @returns {string} Absolute path to scripts/update-progress.js
+ */
+function getUpdateProgressScript(workspacePath) {
+  return path.join(workspacePath, 'scripts', 'update-progress.js');
+}
+
+module.exports = {
+  getSyncStateBizsDir,
+  getSyncStateTechsDir,
+  getFeaturesFilePath,
+  getEntryDirsFilePath,
+  getFeatureDocPath,
+  getGraphFilePath,
+  getMarkerFileName,
+  getCompletedDir,
+  getIterationsDir,
+  getConfigsDir,
+  getUpdateProgressScript
+};