@zhuan-ai/zhuanspec 1.3.0 → 2.0.0

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, 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.
@@ -408,12 +409,25 @@ 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);
+            }
         }
     }
     // Calculate progress
@@ -480,6 +494,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 +522,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 +563,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,15 @@ 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;
     private runBulkValidation;
 }
 export {};

package/dist/commands/validate.js

@@ -1,9 +1,11 @@
 import ora from 'ora';
 import path from 'path';
+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 +104,15 @@ 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;
+            }
             const durationMs = Date.now() - start;
-            this.printReport('change', id, report, durationMs, opts.json);
+            this.printReport('change', id, report, durationMs, opts.json, taskReport);
             // Non-zero exit if invalid (keeps enriched output test semantics)
             process.exitCode = report.valid ? 0 : 1;
             return;
@@ -115,14 +124,26 @@ export class ValidateCommand {
         this.printReport('spec', id, report, durationMs, opts.json);
         process.exitCode = report.valid ? 0 : 1;
     }
-    printReport(type, id, report, durationMs, json) {
+    printReport(type, id, report, durationMs, json, taskReport) {
         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;
+            }
             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);
+            }
         }
         else {
             console.error(`${type === 'change' ? 'Change' : 'Specification'} '${id}' has issues`);
@@ -149,6 +170,79 @@ 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}`);
+        }
+    }
     async runBulkValidation(scope, opts) {
         const spinner = !opts.json && !opts.noInteractive ? ora('Validating...').start() : undefined;
         const [changeIds, specIds] = await Promise.all([

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,11 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,14 @@
+/**
+ * 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';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,74 @@
+/**
+ * Task Graph
+ *
+ * Builds a DAG from parsed tasks and provides graph operations.
+ * Uses Kahn's algorithm for topological sorting.
+ */
+import type { ParsedTask } from './types.js';
+/**
+ * Validation result for the task graph
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Represents a task dependency graph.
+ * Provides methods for querying build order, ready tasks, and completion status.
+ */
+export declare class TaskGraph {
+    private tasks;
+    private inDegree;
+    private dependents;
+    private dependencies;
+    private completedTasks;
+    constructor(tasks: ParsedTask[]);
+    /**
+     * Validates the task graph.
+     *
+     * Checks:
+     * - All depends references exist
+     * - No self-dependencies
+     * - No circular dependencies
+     */
+    validate(): ValidationResult;
+    /**
+     * Performs topological sort using Kahn's algorithm.
+     * Returns tasks in execution order.
+     */
+    topologicalSort(): ParsedTask[];
+    /**
+     * Detects circular dependencies in the graph.
+     * Returns an array of cycle paths.
+     */
+    detectCycles(): string[][];
+    /**
+     * Gets tasks that are ready to execute (in-degree 0 and not completed).
+     */
+    getReady(): ParsedTask[];
+    /**
+     * Marks a task as completed and updates graph state.
+     */
+    markCompleted(taskId: string): void;
+    /**
+     * Gets the direct dependencies of a task (tasks it depends on).
+     */
+    getDependencies(taskId: string): ParsedTask[];
+    /**
+     * Gets the direct dependents of a task (tasks that depend on it).
+     */
+    getDependents(taskId: string): ParsedTask[];
+    /**
+     * Gets a task by ID.
+     */
+    getTask(taskId: string): ParsedTask | undefined;
+    /**
+     * Gets all tasks in the graph.
+     */
+    getAllTasks(): ParsedTask[];
+    /**
+     * Checks if all tasks are completed.
+     */
+    isComplete(): boolean;
+}
+//# sourceMappingURL=task-graph.d.ts.map

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

@@ -0,0 +1,219 @@
+/**
+ * Task Graph
+ *
+ * Builds a DAG from parsed tasks and provides graph operations.
+ * Uses Kahn's algorithm for topological sorting.
+ */
+/**
+ * Represents a task dependency graph.
+ * Provides methods for querying build order, ready tasks, and completion status.
+ */
+export class TaskGraph {
+    tasks;
+    inDegree;
+    dependents; // task -> tasks that depend on it
+    dependencies; // task -> tasks it depends on
+    completedTasks;
+    constructor(tasks) {
+        this.tasks = new Map(tasks.map(t => [t.id, t]));
+        this.inDegree = new Map();
+        this.dependents = new Map();
+        this.dependencies = new Map();
+        this.completedTasks = new Set();
+        // Initialize data structures
+        for (const task of tasks) {
+            this.inDegree.set(task.id, 0);
+            this.dependents.set(task.id, []);
+            this.dependencies.set(task.id, []);
+            // Mark already completed tasks
+            if (task.completed) {
+                this.completedTasks.add(task.id);
+            }
+        }
+        // Build graph edges
+        for (const task of tasks) {
+            // Filter depends to only include existing tasks
+            const validDepends = task.depends.filter(dep => this.tasks.has(dep));
+            this.dependencies.set(task.id, validDepends);
+            this.inDegree.set(task.id, validDepends.length);
+            for (const dep of validDepends) {
+                this.dependents.get(dep).push(task.id);
+            }
+        }
+    }
+    /**
+     * Validates the task graph.
+     *
+     * Checks:
+     * - All depends references exist
+     * - No self-dependencies
+     * - No circular dependencies
+     */
+    validate() {
+        const errors = [];
+        // Check for missing dependencies and self-dependencies
+        for (const task of this.tasks.values()) {
+            for (const dep of task.depends) {
+                if (!this.tasks.has(dep)) {
+                    errors.push(`Task ${task.id}: depends on non-existent task "${dep}"`);
+                }
+                if (dep === task.id) {
+                    errors.push(`Task ${task.id}: self-dependency not allowed`);
+                }
+            }
+            // Check for duplicate dependencies (warning, not error)
+            const uniqueDeps = new Set(task.depends);
+            if (uniqueDeps.size < task.depends.length) {
+                const duplicates = task.depends.filter((d, i) => task.depends.indexOf(d) !== i);
+                errors.push(`Task ${task.id}: duplicate dependencies detected: ${[...new Set(duplicates)].join(', ')}`);
+            }
+        }
+        // Check for cycles
+        const cycles = this.detectCycles();
+        if (cycles.length > 0) {
+            for (const cycle of cycles) {
+                errors.push(`Circular dependency detected: ${cycle.join(' → ')}`);
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+        };
+    }
+    /**
+     * Performs topological sort using Kahn's algorithm.
+     * Returns tasks in execution order.
+     */
+    topologicalSort() {
+        // Create a copy of in-degrees for this operation
+        const inDegree = new Map();
+        for (const [id, degree] of this.inDegree) {
+            inDegree.set(id, degree);
+        }
+        // Start with roots (in-degree 0), sorted for determinism
+        const queue = [...this.tasks.keys()]
+            .filter(id => inDegree.get(id) === 0)
+            .sort();
+        const result = [];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            result.push(this.tasks.get(current));
+            // Collect newly ready tasks, then sort before adding
+            const newlyReady = [];
+            for (const dep of this.dependents.get(current)) {
+                const newDegree = inDegree.get(dep) - 1;
+                inDegree.set(dep, newDegree);
+                if (newDegree === 0) {
+                    newlyReady.push(dep);
+                }
+            }
+            queue.push(...newlyReady.sort());
+        }
+        return result;
+    }
+    /**
+     * Detects circular dependencies in the graph.
+     * Returns an array of cycle paths.
+     */
+    detectCycles() {
+        const cycles = [];
+        const visited = new Set();
+        const recStack = new Set();
+        const path = [];
+        const dfs = (taskId) => {
+            visited.add(taskId);
+            recStack.add(taskId);
+            path.push(taskId);
+            const deps = this.dependencies.get(taskId) || [];
+            for (const dep of deps) {
+                if (!visited.has(dep)) {
+                    if (dfs(dep)) {
+                        return true;
+                    }
+                }
+                else if (recStack.has(dep)) {
+                    // Found a cycle - extract the cycle path
+                    const cycleStart = path.indexOf(dep);
+                    const cyclePath = [...path.slice(cycleStart), dep];
+                    cycles.push(cyclePath);
+                    return true;
+                }
+            }
+            path.pop();
+            recStack.delete(taskId);
+            return false;
+        };
+        for (const taskId of this.tasks.keys()) {
+            if (!visited.has(taskId)) {
+                dfs(taskId);
+            }
+        }
+        return cycles;
+    }
+    /**
+     * Gets tasks that are ready to execute (in-degree 0 and not completed).
+     */
+    getReady() {
+        const ready = [];
+        for (const task of this.tasks.values()) {
+            if (this.completedTasks.has(task.id)) {
+                continue; // Already completed
+            }
+            // Check if all dependencies are completed
+            const deps = this.dependencies.get(task.id) || [];
+            const allDepsCompleted = deps.every(dep => this.completedTasks.has(dep));
+            if (allDepsCompleted) {
+                ready.push(task);
+            }
+        }
+        // Sort for deterministic ordering
+        return ready.sort((a, b) => a.id.localeCompare(b.id));
+    }
+    /**
+     * Marks a task as completed and updates graph state.
+     */
+    markCompleted(taskId) {
+        if (!this.tasks.has(taskId)) {
+            throw new Error(`Task "${taskId}" not found in graph`);
+        }
+        this.completedTasks.add(taskId);
+    }
+    /**
+     * Gets the direct dependencies of a task (tasks it depends on).
+     */
+    getDependencies(taskId) {
+        const deps = this.dependencies.get(taskId) || [];
+        return deps.map(id => this.tasks.get(id)).filter(Boolean);
+    }
+    /**
+     * Gets the direct dependents of a task (tasks that depend on it).
+     */
+    getDependents(taskId) {
+        const deps = this.dependents.get(taskId) || [];
+        return deps.map(id => this.tasks.get(id)).filter(Boolean);
+    }
+    /**
+     * Gets a task by ID.
+     */
+    getTask(taskId) {
+        return this.tasks.get(taskId);
+    }
+    /**
+     * Gets all tasks in the graph.
+     */
+    getAllTasks() {
+        return Array.from(this.tasks.values());
+    }
+    /**
+     * Checks if all tasks are completed.
+     */
+    isComplete() {
+        for (const task of this.tasks.values()) {
+            if (!this.completedTasks.has(task.id)) {
+                return false;
+            }
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=task-graph.js.map

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

@@ -0,0 +1,14 @@
+/**
+ * Task Parser
+ *
+ * Parses tasks.md content into structured ParsedTask array.
+ */
+import type { ParsedTask } from './types.js';
+/**
+ * Parse tasks.md content into an array of ParsedTask objects.
+ *
+ * @param content - The raw content of tasks.md
+ * @returns Array of parsed tasks
+ */
+export declare function parseTasks(content: string): ParsedTask[];
+//# sourceMappingURL=task-parser.d.ts.map

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

@@ -0,0 +1,111 @@
+/**
+ * Task Parser
+ *
+ * Parses tasks.md content into structured ParsedTask array.
+ */
+// Regex patterns for parsing
+// Group header: ## N. Group Name
+const GROUP_HEADER_REGEX = /^##\s+(\d+)\.\s+(.+)$/;
+// Task line: - [ ] N.M description @skill:name1,name2 @depends:id1,id2
+// or: - [x] N.M description ...
+const TASK_LINE_REGEX = /^-\s+\[([ xX])\]\s+(\d+\.\d+)\s+(.*)$/;
+// Annotations (can be inside or outside HTML comments)
+const SKILL_REGEX = /@skill:([^\s@]+)/g;
+const DEPENDS_REGEX = /@depends:([^\s@]+)/g;
+// HTML comment pattern to extract content
+const HTML_COMMENT_REGEX = /<!--\s*(.*?)\s*-->/g;
+/**
+ * Extract annotations from text (handles both plain text and HTML comments)
+ */
+function extractAnnotations(text) {
+    const skills = [];
+    const depends = [];
+    // Collect all text to search (including content inside HTML comments)
+    let searchText = text;
+    // Extract content from HTML comments and add to search text
+    let match;
+    while ((match = HTML_COMMENT_REGEX.exec(text)) !== null) {
+        searchText += ' ' + match[1];
+    }
+    // Reset lastIndex for subsequent regex operations
+    HTML_COMMENT_REGEX.lastIndex = 0;
+    // Extract skills
+    let skillMatch;
+    while ((skillMatch = SKILL_REGEX.exec(searchText)) !== null) {
+        const skillList = skillMatch[1].split(',').filter(s => s.trim());
+        skills.push(...skillList);
+    }
+    SKILL_REGEX.lastIndex = 0;
+    // Extract depends
+    let dependsMatch;
+    while ((dependsMatch = DEPENDS_REGEX.exec(searchText)) !== null) {
+        const dependsList = dependsMatch[1].split(',').filter(d => d.trim());
+        depends.push(...dependsList);
+    }
+    DEPENDS_REGEX.lastIndex = 0;
+    return {
+        skills: [...new Set(skills)], // dedupe
+        depends: [...new Set(depends)], // dedupe
+    };
+}
+/**
+ * Clean description by removing annotations
+ */
+function cleanDescription(text) {
+    let cleaned = text
+        // Remove HTML comments with annotations
+        .replace(/<!--\s*@(?:skill|depends):[^\s]*(?:\s+@(?:skill|depends):[^\s]*)?\s*-->/g, '')
+        // Remove plain annotations
+        .replace(/@skill:[^\s@]+/g, '')
+        .replace(/@depends:[^\s@]+/g, '')
+        .trim();
+    return cleaned;
+}
+/**
+ * Parse tasks.md content into an array of ParsedTask objects.
+ *
+ * @param content - The raw content of tasks.md
+ * @returns Array of parsed tasks
+ */
+export function parseTasks(content) {
+    if (!content || !content.trim()) {
+        return [];
+    }
+    const lines = content.split('\n');
+    const tasks = [];
+    let currentGroup = '';
+    let currentGroupName = '';
+    for (const line of lines) {
+        // Check for group header
+        const groupMatch = line.match(GROUP_HEADER_REGEX);
+        if (groupMatch) {
+            currentGroup = groupMatch[1];
+            currentGroupName = groupMatch[2].trim();
+            continue;
+        }
+        // Check for task line
+        const taskMatch = line.match(TASK_LINE_REGEX);
+        if (taskMatch) {
+            const checkboxState = taskMatch[1];
+            const taskId = taskMatch[2];
+            const rest = taskMatch[3];
+            // Extract annotations
+            const { skills, depends } = extractAnnotations(rest);
+            // Clean description
+            const description = cleanDescription(rest);
+            // Parse group from task ID if not already set
+            const taskGroup = taskId.split('.')[0];
+            tasks.push({
+                id: taskId,
+                group: currentGroup || taskGroup,
+                groupName: currentGroupName,
+                description,
+                skills,
+                depends,
+                completed: checkboxState.toLowerCase() === 'x',
+            });
+        }
+    }
+    return tasks;
+}
+//# sourceMappingURL=task-parser.js.map

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

@@ -0,0 +1,53 @@
+/**
+ * Task Graph Types
+ *
+ * Type definitions for task dependency graph module.
+ */
+/**
+ * Represents a parsed task from tasks.md
+ */
+export interface ParsedTask {
+    /** Task ID, e.g., "1.1", "2.3" */
+    id: string;
+    /** Group number, e.g., "1", "2" */
+    group: string;
+    /** Group name */
+    groupName: string;
+    /** Task description text */
+    description: string;
+    /** Skills required, e.g., ["java-dao-standards"] */
+    skills: string[];
+    /** Task IDs this task depends on, e.g., ["1.1", "2.1"] */
+    depends: string[];
+    /** Whether the task is completed (checkbox state [x] vs [ ]) */
+    completed: boolean;
+}
+/**
+ * Represents a wave of tasks that can be executed together
+ */
+export interface ExecutionWave {
+    /** Wave number (starting from 1) */
+    wave: number;
+    /** Tasks in this wave */
+    tasks: ParsedTask[];
+    /** Whether tasks can run in parallel (tasks.length > 1) */
+    parallel: boolean;
+}
+/**
+ * Represents the complete execution plan
+ */
+export interface ExecutionPlan {
+    /** Waves of tasks to execute */
+    waves: ExecutionWave[];
+    /** Total number of tasks */
+    totalTasks: number;
+    /** Number of tasks that can be executed in parallel (tasks in multi-task waves) */
+    parallelTasks: number;
+    /** Number of tasks that must be executed serially (tasks in single-task waves) */
+    serialTasks: number;
+    /** Whether there is a cycle in the dependency graph */
+    hasCycle: boolean;
+    /** Validation errors */
+    errors: string[];
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,7 @@
+/**
+ * Task Graph Types
+ *
+ * Type definitions for task dependency graph module.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,21 @@
+/**
+ * XML Renderer for Execution Plan
+ *
+ * Renders ExecutionPlan to XML format for injection into apply instructions.
+ */
+import type { ExecutionPlan, ParsedTask } from './types.js';
+/**
+ * Renders an ExecutionPlan to XML format.
+ *
+ * @param plan - The execution plan to render
+ * @returns XML string representation of the plan
+ */
+export declare function renderExecutionPlanXml(plan: ExecutionPlan): string;
+/**
+ * Checks if any task in the parsed tasks has @depends annotation.
+ *
+ * @param tasks - Array of parsed tasks
+ * @returns True if at least one task has dependencies
+ */
+export declare function hasDependsAnnotations(tasks: ParsedTask[]): boolean;
+//# sourceMappingURL=xml-renderer.d.ts.map

package/dist/core/task-graph/xml-renderer.js

@@ -0,0 +1,81 @@
+/**
+ * XML Renderer for Execution Plan
+ *
+ * Renders ExecutionPlan to XML format for injection into apply instructions.
+ */
+/**
+ * Escapes special XML characters in a string.
+ */
+function escapeXml(str) {
+    return str
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/**
+ * Renders a single task to XML format.
+ */
+function renderTaskXml(task, indent) {
+    const skillsAttr = task.skills.length > 0 ? ` skills="${escapeXml(task.skills.join(','))}"` : '';
+    const lines = [];
+    lines.push(`${indent}<task id="${escapeXml(task.id)}"${skillsAttr}>`);
+    lines.push(`${indent}  <description>${escapeXml(task.description)}</description>`);
+    lines.push(`${indent}  <depends>${task.depends.length > 0 ? escapeXml(task.depends.join(',')) : ''}</depends>`);
+    lines.push(`${indent}</task>`);
+    return lines.join('\n');
+}
+/**
+ * Renders an ExecutionPlan to XML format.
+ *
+ * @param plan - The execution plan to render
+ * @returns XML string representation of the plan
+ */
+export function renderExecutionPlanXml(plan) {
+    const lines = [];
+    // Handle error cases
+    if (plan.hasCycle) {
+        lines.push(`<execution_plan error="cycle_detected">`);
+        lines.push('  <errors>');
+        for (const error of plan.errors) {
+            lines.push(`    <error>${escapeXml(error)}</error>`);
+        }
+        lines.push('  </errors>');
+        lines.push('</execution_plan>');
+        return lines.join('\n');
+    }
+    // Handle empty plan (all tasks complete or no tasks)
+    if (plan.waves.length === 0) {
+        return ''; // Return empty string - no execution plan needed
+    }
+    // Render full plan
+    lines.push(`<execution_plan total_tasks="${plan.totalTasks}" parallel_tasks="${plan.parallelTasks}" serial_tasks="${plan.serialTasks}">`);
+    // Render each wave
+    for (const wave of plan.waves) {
+        lines.push(`  <wave number="${wave.wave}" parallel="${wave.parallel}">`);
+        for (const task of wave.tasks) {
+            lines.push(renderTaskXml(task, '    '));
+        }
+        lines.push('  </wave>');
+    }
+    // Add orchestration strategy
+    lines.push('');
+    lines.push('  <orchestration_strategy>');
+    lines.push('    每个 wave 内的任务通过独立 subagent 并行执行。');
+    lines.push('    Wave 之间严格串行，前一 wave 全部完成后才启动下一 wave。');
+    lines.push('    每个 subagent 仅加载其 task 关联的 @skill，实现上下文隔离。');
+    lines.push('  </orchestration_strategy>');
+    lines.push('</execution_plan>');
+    return lines.join('\n');
+}
+/**
+ * Checks if any task in the parsed tasks has @depends annotation.
+ *
+ * @param tasks - Array of parsed tasks
+ * @returns True if at least one task has dependencies
+ */
+export function hasDependsAnnotations(tasks) {
+    return tasks.some(task => task.depends.length > 0);
+}
+//# sourceMappingURL=xml-renderer.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",

package/schemas/spec-driven/templates/tasks.md

@@ -10,16 +10,28 @@
      - 避免过度匹配：简单的代码修改（如增删枚举值、修改常量）只需通用编码规范 skill
      - 避免关键词匹配：不要仅因文件名或路径包含某些词就匹配相关 skill
   
+  @depends 标注指南：
+  1. 分析任务间的依赖关系，识别哪些任务必须在其他任务完成后才能开始
+  2. 使用 @depends:taskId 标注依赖，支持多依赖 @depends:taskId1,taskId2
+  3. 无 @depends 标注的任务默认无依赖，可与其他无依赖任务并行执行
+  4. 依赖可以跨任务组（如 2.1 依赖 1.2）
+  5. 不允许循环依赖
+  6. 标注原则：
+     - 仅标注直接依赖：如 A→B→C，C 只需标注 @depends:B，无需标注 A
+     - 数据依赖：后续任务使用前序任务创建的表/接口/类时，必须标注依赖
+     - 独立任务：无数据或逻辑依赖的任务不要添加 @depends，以最大化并行度
+
   示例：
-  - [ ] 1.1 新增 AssBusinessDataEnum 枚举值 ASSEMBLY_MACHINE_FLAG → @skill:kf-backend-coding-standards
-  - [ ] 1.2 定义 SCF 接口 IAssQueryService → @skill:java-scf-rpc-usage-skill
-  - [ ] 1.3 创建数据库表 ass_order → @skill:java-db-schema-standards
+  - [ ] 1.1 新增 AssBusinessDataEnum 枚举值 ASSEMBLY_MACHINE_FLAG @skill:kf-backend-coding-standards
+  - [ ] 1.2 创建数据库表 ass_order @skill:java-db-schema-standards
+  - [ ] 1.3 编写 DAO 层代码 @skill:java-dao-standards @depends:1.2
+  - [ ] 1.4 定义 SCF 接口 IAssQueryService @skill:java-scf-rpc-usage-skill @depends:1.3
 -->
 
 - [ ] 1.1 <!-- 任务描述 --> <!-- @skill:real-skill-name -->
-- [ ] 1.2 <!-- 任务描述 -->
+- [ ] 1.2 <!-- 任务描述 --> <!-- @skill:real-skill-name @depends:1.1 -->
 
 ## 2. <!-- 任务组名称 -->
 
 - [ ] 2.1 <!-- 任务描述 -->
-- [ ] 2.2 <!-- 任务描述 -->
+- [ ] 2.2 <!-- 任务描述 --> <!-- @depends:1.2,2.1 -->