@zhuan-ai/zhuanspec 1.3.0 → 2.1.0

package/README.zh.md

@@ -415,7 +415,7 @@ npm install -g ./distributions/fission-ai-zhuanspec-1.0.0.tgz
 
 1. **升级包**
    ```bash
-   npm install -g @fission-ai/zhuanspec@latest
+   npm install -g @zhuan-ai/zhuanspec@latest
    ```
 2. **刷新代理说明**
    - 在每个项目内运行 `zhuanspec update` 以重新生成 AI 指导并确保最新的斜杠命令处于活动状态。

package/dist/cli/index.js

@@ -227,7 +227,7 @@ skillsCmd
     .option('--json', 'Output as JSON for programmatic use')
     .action(async (options) => {
     try {
-        const skills = discoverSkills();
+        const skills = discoverSkills(process.cwd());
         console.log(formatSkillsList(skills, !!options?.json));
     }
     catch (error) {

package/dist/commands/artifact-workflow.js

@@ -13,6 +13,7 @@ import { createChange, validateChangeName } from '../utils/change-utils.js';
 import { discoverSkills } from '../core/skill-discovery.js';
 import { getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getProposeChangeSkillTemplate, getExploreSkillTemplate, getVerifySkillTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate, getOpsxProposeCommandTemplate, getOpsxExploreCommandTemplate, getOpsxVerifyCommandTemplate } from '../core/templates/skill-templates.js';
 import { FileSystemUtils } from '../utils/file-system.js';
+import { parseTasks, generateExecutionPlan, renderExecutionPlanXml, renderMermaidDiagram, hasDependsAnnotations, } from '../core/task-graph/index.js';
 const DEFAULT_SCHEMA = 'spec-driven';
 /**
  * Checks if color output is disabled via NO_COLOR env or --no-color flag.
@@ -176,7 +177,7 @@ async function instructionsCommand(artifactId, options) {
         let discoveredSkillsJson;
         if (artifactId === 'tasks' || artifactId === 'proposal') {
             try {
-                const skills = await discoverSkills();
+                const skills = discoverSkills(projectRoot);
                 if (skills.length > 0) {
                     discoveredSkillsJson = JSON.stringify(skills.map((s) => ({ name: s.name, description: s.description })), null, 2);
                 }
@@ -408,12 +409,45 @@ async function generateApplyInstructions(projectRoot, changeName, schemaName) {
     // Parse tasks if tracking file exists
     let tasks = [];
     let tracksFileExists = false;
+    let executionPlanXml;
+    let hasDependencies = false;
     if (tracksFile) {
         const tracksPath = path.join(changeDir, tracksFile);
         tracksFileExists = fs.existsSync(tracksPath);
         if (tracksFileExists) {
             const tasksContent = await fs.promises.readFile(tracksPath, 'utf-8');
             tasks = parseTasksFile(tasksContent);
+            // Parse tasks using task-graph module for dependency analysis
+            const parsedTasks = parseTasks(tasksContent);
+            hasDependencies = hasDependsAnnotations(parsedTasks);
+            // Only generate execution plan if:
+            // 1. Tasks have @depends annotations
+            // 2. Not all tasks are complete
+            const allTasksComplete = parsedTasks.length > 0 && parsedTasks.every(t => t.completed);
+            if (hasDependencies && !allTasksComplete) {
+                const executionPlan = generateExecutionPlan(parsedTasks);
+                executionPlanXml = renderExecutionPlanXml(executionPlan);
+                // Generate Mermaid diagram and embed in tasks.md
+                if (executionPlan && !executionPlan.hasCycle) {
+                    const mermaidSection = renderMermaidDiagram(executionPlan, parsedTasks);
+                    if (mermaidSection) {
+                        // Read current tasks.md content
+                        let currentTasksContent = tasksContent;
+                        // Check if tasks.md already has Workflow Diagram section
+                        const workflowDiagramRegex = /## Workflow Diagram[\s\S]*?(?=\n## |$)/;
+                        if (workflowDiagramRegex.test(currentTasksContent)) {
+                            // Replace existing Workflow Diagram section
+                            currentTasksContent = currentTasksContent.replace(workflowDiagramRegex, mermaidSection);
+                        }
+                        else {
+                            // Append to file end
+                            currentTasksContent = currentTasksContent.trimEnd() + '\n\n' + mermaidSection;
+                        }
+                        // Write back to tasks.md
+                        fs.writeFileSync(tracksPath, currentTasksContent, 'utf-8');
+                    }
+                }
+            }
         }
     }
     // Calculate progress
@@ -480,6 +514,8 @@ See the apply command template for detailed code review workflow instructions.`;
         state,
         missingArtifacts: missingArtifacts.length > 0 ? missingArtifacts : undefined,
         instruction,
+        executionPlanXml,
+        hasDependencies,
     };
 }
 async function applyInstructionsCommand(options) {
@@ -506,7 +542,7 @@ async function applyInstructionsCommand(options) {
     }
 }
 function printApplyInstructionsText(instructions) {
-    const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, instruction } = instructions;
+    const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, instruction, executionPlanXml } = instructions;
     console.log(`## Apply: ${changeName}`);
     console.log(`Schema: ${schemaName}`);
     console.log();
@@ -547,6 +583,13 @@ function printApplyInstructionsText(instructions) {
         }
         console.log();
     }
+    // Execution Plan (only if tasks have dependencies and not all complete)
+    if (executionPlanXml) {
+        console.log('### Execution Plan');
+        console.log();
+        console.log(executionPlanXml);
+        console.log();
+    }
     // Instruction
     console.log('### Instruction');
     console.log(instruction);

package/dist/commands/validate.d.ts

@@ -18,6 +18,20 @@ export declare class ValidateCommand {
     private validateByType;
     private printReport;
     private printNextSteps;
+    /**
+     * Validate task dependencies in tasks.md if present.
+     * Returns a report with validation status and execution plan.
+     */
+    private validateTaskDependencies;
+    /**
+     * Print execution plan summary for tasks with dependencies.
+     */
+    private printExecutionPlanSummary;
+    /**
+     * Write Mermaid diagram to tasks.md file.
+     * Replaces existing "## Workflow Diagram" section or appends at end.
+     */
+    private writeMermaidDiagramToTasks;
     private runBulkValidation;
 }
 export {};

package/dist/commands/validate.js

@@ -1,9 +1,12 @@
 import ora from 'ora';
 import path from 'path';
+import chalk from 'chalk';
+import { promises as fs } from 'fs';
 import { Validator } from '../core/validation/validator.js';
 import { isInteractive, resolveNoInteractive } from '../utils/interactive.js';
 import { getActiveChangeIds, getSpecIds } from '../utils/item-discovery.js';
 import { nearestMatches } from '../utils/match.js';
+import { parseTasks, TaskGraph, generateExecutionPlan } from '../core/task-graph/index.js';
 export class ValidateCommand {
     async execute(itemName, options = {}) {
         const interactive = isInteractive(options);
@@ -102,8 +105,19 @@ export class ValidateCommand {
             const changeDir = path.join(process.cwd(), 'zhuanspec', 'changes', id);
             const start = Date.now();
             const report = await validator.validateChangeDeltaSpecs(changeDir);
+            // Validate tasks.md dependencies if present
+            const taskReport = await this.validateTaskDependencies(changeDir);
+            // Merge task dependency issues into report
+            if (taskReport.issues.length > 0) {
+                report.issues.push(...taskReport.issues);
+                report.valid = report.valid && taskReport.valid;
+            }
+            // Write Mermaid diagram to tasks.md if generated
+            if (report.mermaidDiagram) {
+                await this.writeMermaidDiagramToTasks(changeDir, report.mermaidDiagram);
+            }
             const durationMs = Date.now() - start;
-            this.printReport('change', id, report, durationMs, opts.json);
+            this.printReport('change', id, report, durationMs, opts.json, taskReport, { strict: opts.strict });
             // Non-zero exit if invalid (keeps enriched output test semantics)
             process.exitCode = report.valid ? 0 : 1;
             return;
@@ -112,17 +126,41 @@ export class ValidateCommand {
         const start = Date.now();
         const report = await validator.validateSpec(file);
         const durationMs = Date.now() - start;
-        this.printReport('spec', id, report, durationMs, opts.json);
+        this.printReport('spec', id, report, durationMs, opts.json, undefined, { strict: opts.strict });
         process.exitCode = report.valid ? 0 : 1;
     }
-    printReport(type, id, report, durationMs, json) {
+    printReport(type, id, report, durationMs, json, taskReport, opts) {
         if (json) {
-            const out = { items: [{ id, type, valid: report.valid, issues: report.issues, durationMs }], summary: { totals: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 }, byType: { [type]: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 } } }, version: '1.0' };
+            const out = {
+                items: [{ id, type, valid: report.valid, issues: report.issues, durationMs }],
+                summary: { totals: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 }, byType: { [type]: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 } } },
+                version: '1.0'
+            };
+            // Add execution plan to JSON output if available
+            if (taskReport?.hasDependencies && taskReport.executionPlan) {
+                out.executionPlan = taskReport.executionPlan;
+            }
+            // Add strict checks to JSON output if available
+            if (report.strictChecks) {
+                out.strictChecks = report.strictChecks;
+            }
+            // Add mermaid diagram flag to JSON output if generated
+            if (report.mermaidDiagram) {
+                out.workflowDiagramGenerated = true;
+            }
             console.log(JSON.stringify(out, null, 2));
             return;
         }
         if (report.valid) {
             console.log(`${type === 'change' ? 'Change' : 'Specification'} '${id}' is valid`);
+            // Print execution plan summary if available
+            if (taskReport?.hasDependencies && taskReport.executionPlan && !taskReport.executionPlan.hasCycle) {
+                this.printExecutionPlanSummary(taskReport.executionPlan);
+            }
+            // Print Mermaid diagram generated message
+            if (report.mermaidDiagram) {
+                console.log('  Workflow diagram generated');
+            }
         }
         else {
             console.error(`${type === 'change' ? 'Change' : 'Specification'} '${id}' has issues`);
@@ -133,6 +171,21 @@ export class ValidateCommand {
             }
             this.printNextSteps(type);
         }
+        // Print strict mode checks summary if available
+        if (opts?.strict && report.strictChecks && report.strictChecks.length > 0) {
+            console.log('');
+            console.log('Strict Mode Checks:');
+            for (const check of report.strictChecks) {
+                if (check.passed) {
+                    console.log(`  ${chalk.green('✓')} ${check.ruleName}`);
+                }
+                else {
+                    const firstError = check.errors[0] || check.warnings[0] || '';
+                    const errorSuffix = firstError ? ` — ${firstError}` : '';
+                    console.log(`  ${chalk.red('✗')} ${check.ruleName}${errorSuffix}`);
+                }
+            }
+        }
     }
     printNextSteps(type) {
         const bullets = [];
@@ -149,6 +202,109 @@ export class ValidateCommand {
         console.error('Next steps:');
         bullets.forEach(b => console.error(`  ${b}`));
     }
+    /**
+     * Validate task dependencies in tasks.md if present.
+     * Returns a report with validation status and execution plan.
+     */
+    async validateTaskDependencies(changeDir) {
+        const tasksFile = path.join(changeDir, 'tasks.md');
+        // Check if tasks.md exists
+        let content;
+        try {
+            content = await fs.readFile(tasksFile, 'utf-8');
+        }
+        catch {
+            // No tasks.md file - skip dependency validation
+            return { valid: true, hasDependencies: false, issues: [] };
+        }
+        // Parse tasks
+        const tasks = parseTasks(content);
+        if (tasks.length === 0) {
+            return { valid: true, hasDependencies: false, issues: [] };
+        }
+        // Check if any task has @depends annotation
+        const hasDependencies = tasks.some(t => t.depends.length > 0);
+        if (!hasDependencies) {
+            // No dependencies - skip validation, no execution plan output
+            return { valid: true, hasDependencies: false, issues: [] };
+        }
+        // Validate task dependencies
+        const graph = new TaskGraph(tasks);
+        const validation = graph.validate();
+        const issues = [];
+        if (!validation.valid) {
+            for (const error of validation.errors) {
+                issues.push({
+                    level: 'ERROR',
+                    path: 'tasks.md',
+                    message: error,
+                });
+            }
+        }
+        // Generate execution plan
+        const executionPlan = generateExecutionPlan(tasks);
+        // Add cycle-related errors from execution plan
+        if (executionPlan.hasCycle && executionPlan.errors.length > 0) {
+            for (const error of executionPlan.errors) {
+                // Avoid duplicates
+                if (!issues.some(i => i.message === error)) {
+                    issues.push({
+                        level: 'ERROR',
+                        path: 'tasks.md',
+                        message: error,
+                    });
+                }
+            }
+        }
+        return {
+            valid: issues.filter(i => i.level === 'ERROR').length === 0,
+            hasDependencies: true,
+            issues,
+            executionPlan,
+        };
+    }
+    /**
+     * Print execution plan summary for tasks with dependencies.
+     */
+    printExecutionPlanSummary(plan) {
+        const { waves, totalTasks, parallelTasks, serialTasks } = plan;
+        console.log(`  Execution Plan: ${waves.length} waves, ${totalTasks} tasks (${parallelTasks} parallel, ${serialTasks} serial)`);
+        for (const wave of waves) {
+            const taskIds = wave.tasks.map(t => t.id).join(', ');
+            const parallelLabel = wave.parallel ? ' (parallel)' : '';
+            console.log(`  Wave ${wave.wave}: [${taskIds}]${parallelLabel}`);
+        }
+    }
+    /**
+     * Write Mermaid diagram to tasks.md file.
+     * Replaces existing "## Workflow Diagram" section or appends at end.
+     */
+    async writeMermaidDiagramToTasks(changeDir, mermaidDiagram) {
+        const tasksFile = path.join(changeDir, 'tasks.md');
+        let content;
+        try {
+            content = await fs.readFile(tasksFile, 'utf-8');
+        }
+        catch {
+            // tasks.md doesn't exist, nothing to write to
+            return;
+        }
+        // Pattern to match existing "## Workflow Diagram" section
+        const workflowSectionPattern = /^## Workflow Diagram[\s\S]*?(?=^## |\z)/gm;
+        // Check if section exists
+        const hasExistingSection = workflowSectionPattern.test(content);
+        workflowSectionPattern.lastIndex = 0; // Reset regex state
+        let newContent;
+        if (hasExistingSection) {
+            // Replace existing section
+            newContent = content.replace(workflowSectionPattern, mermaidDiagram + '\n\n');
+        }
+        else {
+            // Append at end
+            newContent = content.trimEnd() + '\n\n' + mermaidDiagram + '\n';
+        }
+        await fs.writeFile(tasksFile, newContent, 'utf-8');
+    }
     async runBulkValidation(scope, opts) {
         const spinner = !opts.json && !opts.noInteractive ? ora('Validating...').start() : undefined;
         const [changeIds, specIds] = await Promise.all([

package/dist/core/skill-discovery.d.ts

@@ -13,10 +13,10 @@ export interface DiscoveredSkill {
  * Discover available skills by scanning priority paths.
  * Uses short-circuit strategy: once a non-empty directory is found, stops scanning.
  *
- * @param _projectRoot - Project root path (reserved for future project-level skill scanning)
+ * @param projectRoot - Project root path for scanning project-local skills directory
  * @returns Array of discovered skills
  */
-export declare function discoverSkills(_projectRoot?: string): DiscoveredSkill[];
+export declare function discoverSkills(projectRoot?: string): DiscoveredSkill[];
 /**
  * Format discovered skills for display.
  */

package/dist/core/skill-discovery.js

@@ -73,15 +73,28 @@ function findSkillFiles(dir) {
     }
     return results;
 }
+/**
+ * Build the list of paths to scan for skills.
+ * Project-local skills directory is scanned first if projectRoot is provided.
+ */
+function buildScanPaths(projectRoot) {
+    const paths = [];
+    if (projectRoot) {
+        paths.push(path.join(projectRoot, 'skills'));
+    }
+    paths.push(...SCAN_PRIORITY);
+    return paths;
+}
 /**
  * Discover available skills by scanning priority paths.
  * Uses short-circuit strategy: once a non-empty directory is found, stops scanning.
  *
- * @param _projectRoot - Project root path (reserved for future project-level skill scanning)
+ * @param projectRoot - Project root path for scanning project-local skills directory
  * @returns Array of discovered skills
  */
-export function discoverSkills(_projectRoot) {
-    for (const scanPath of SCAN_PRIORITY) {
+export function discoverSkills(projectRoot) {
+    const scanPaths = buildScanPaths(projectRoot);
+    for (const scanPath of scanPaths) {
         const resolved = resolvePath(scanPath);
         // Check if directory exists
         try {

package/dist/core/task-graph/execution-planner.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Execution Planner
+ *
+ * Generates wave-based execution plans from parsed tasks.
+ * Uses a layer-by-layer approach: each wave contains tasks with in-degree 0.
+ */
+import type { ParsedTask, ExecutionPlan } from './types.js';
+/**
+ * Generates an execution plan from parsed tasks.
+ *
+ * Algorithm: Iteratively peel off nodes with in-degree 0 to form waves.
+ *
+ * @param tasks - Array of parsed tasks
+ * @returns Execution plan with waves
+ */
+export declare function generateExecutionPlan(tasks: ParsedTask[]): ExecutionPlan;
+//# sourceMappingURL=execution-planner.d.ts.map

package/dist/core/task-graph/execution-planner.js

@@ -0,0 +1,119 @@
+/**
+ * Execution Planner
+ *
+ * Generates wave-based execution plans from parsed tasks.
+ * Uses a layer-by-layer approach: each wave contains tasks with in-degree 0.
+ */
+import { TaskGraph } from './task-graph.js';
+/**
+ * Generates an execution plan from parsed tasks.
+ *
+ * Algorithm: Iteratively peel off nodes with in-degree 0 to form waves.
+ *
+ * @param tasks - Array of parsed tasks
+ * @returns Execution plan with waves
+ */
+export function generateExecutionPlan(tasks) {
+    // Filter out already completed tasks
+    const incompleteTasks = tasks.filter(t => !t.completed);
+    // Handle empty case
+    if (incompleteTasks.length === 0) {
+        return {
+            waves: [],
+            totalTasks: 0,
+            parallelTasks: 0,
+            serialTasks: 0,
+            hasCycle: false,
+            errors: [],
+        };
+    }
+    // Create graph and validate
+    const graph = new TaskGraph(incompleteTasks);
+    const validation = graph.validate();
+    // Check for cycles
+    if (validation.errors.some(e => e.includes('Circular dependency'))) {
+        return {
+            waves: [],
+            totalTasks: incompleteTasks.length,
+            parallelTasks: 0,
+            serialTasks: 0,
+            hasCycle: true,
+            errors: validation.errors,
+        };
+    }
+    // Collect non-cycle errors
+    const errors = validation.errors.filter(e => !e.includes('Circular dependency'));
+    // Build waves using modified Kahn's algorithm
+    const waves = [];
+    const completed = new Set();
+    // Track in-degrees locally
+    const inDegree = new Map();
+    const dependents = new Map();
+    // Initialize
+    for (const task of incompleteTasks) {
+        // Only count dependencies that exist in incomplete tasks
+        const validDeps = task.depends.filter(d => incompleteTasks.some(t => t.id === d));
+        inDegree.set(task.id, validDeps.length);
+        dependents.set(task.id, []);
+    }
+    // Build reverse adjacency
+    for (const task of incompleteTasks) {
+        for (const dep of task.depends) {
+            if (dependents.has(dep)) {
+                dependents.get(dep).push(task.id);
+            }
+        }
+    }
+    let waveNumber = 0;
+    let remainingTasks = incompleteTasks.length;
+    while (remainingTasks > 0) {
+        waveNumber++;
+        // Find all tasks with in-degree 0
+        const readyIds = [...inDegree.keys()]
+            .filter(id => !completed.has(id) && inDegree.get(id) === 0)
+            .sort();
+        if (readyIds.length === 0) {
+            // Shouldn't happen if no cycles, but handle gracefully
+            break;
+        }
+        const readyTasks = readyIds
+            .map(id => incompleteTasks.find(t => t.id === id))
+            .filter(Boolean);
+        waves.push({
+            wave: waveNumber,
+            tasks: readyTasks,
+            parallel: readyTasks.length > 1,
+        });
+        // Mark as completed and update in-degrees
+        for (const id of readyIds) {
+            completed.add(id);
+            remainingTasks--;
+            // Decrease in-degree of dependents
+            for (const dep of dependents.get(id) || []) {
+                if (!completed.has(dep)) {
+                    inDegree.set(dep, inDegree.get(dep) - 1);
+                }
+            }
+        }
+    }
+    // Calculate statistics
+    let parallelTasks = 0;
+    let serialTasks = 0;
+    for (const wave of waves) {
+        if (wave.parallel) {
+            parallelTasks += wave.tasks.length;
+        }
+        else {
+            serialTasks += wave.tasks.length;
+        }
+    }
+    return {
+        waves,
+        totalTasks: incompleteTasks.length,
+        parallelTasks,
+        serialTasks,
+        hasCycle: false,
+        errors,
+    };
+}
+//# sourceMappingURL=execution-planner.js.map

package/dist/core/task-graph/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Task Graph Module
+ *
+ * Provides task dependency graph operations for tasks.md processing.
+ */
+export type { ParsedTask, ExecutionWave, ExecutionPlan } from './types.js';
+export { parseTasks } from './task-parser.js';
+export { TaskGraph, type ValidationResult } from './task-graph.js';
+export { generateExecutionPlan } from './execution-planner.js';
+export { renderExecutionPlanXml, hasDependsAnnotations } from './xml-renderer.js';
+export { renderMermaidDiagram } from './mermaid-renderer.js';
+export type { MermaidRenderOptions } from './mermaid-renderer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/task-graph/index.js

@@ -0,0 +1,16 @@
+/**
+ * Task Graph Module
+ *
+ * Provides task dependency graph operations for tasks.md processing.
+ */
+// Parser
+export { parseTasks } from './task-parser.js';
+// Graph
+export { TaskGraph } from './task-graph.js';
+// Execution planner
+export { generateExecutionPlan } from './execution-planner.js';
+// XML Renderer
+export { renderExecutionPlanXml, hasDependsAnnotations } from './xml-renderer.js';
+// Mermaid Renderer
+export { renderMermaidDiagram } from './mermaid-renderer.js';
+//# sourceMappingURL=index.js.map

package/dist/core/task-graph/mermaid-renderer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Mermaid Renderer for Execution Plan
+ *
+ * Renders ExecutionPlan to Mermaid flowchart format for visualization in tasks.md.
+ */
+import type { ExecutionPlan, ParsedTask } from './types.js';
+export interface MermaidRenderOptions {
+    /** Maximum parallelism threshold. Default: 3 */
+    maxParallelism?: number;
+    /** Whether to show @skill annotations in node labels. Default: true */
+    showSkills?: boolean;
+}
+/**
+ * Renders an ExecutionPlan to Mermaid flowchart format.
+ *
+ * @param plan - The execution plan to render
+ * @param tasks - The parsed tasks (used for task details)
+ * @param options - Render options
+ * @returns Complete markdown section with Mermaid diagram
+ */
+export declare function renderMermaidDiagram(plan: ExecutionPlan, tasks: ParsedTask[], options?: MermaidRenderOptions): string;
+//# sourceMappingURL=mermaid-renderer.d.ts.map