@krr2020/taskflow-core 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -0,0 +1,179 @@
+# @krr2020/taskflow-core
+
+Core task management framework for AI-assisted development workflows. This package provides the foundational commands, state management, and configuration handling used by the Taskflow MCP Server and CLI.
+
+## 📦 Installation
+
+```bash
+npm install @krr2020/taskflow-core
+```
+
+## 🏗️ Architecture
+
+The core package provides a complete task management system with:
+
+### Commands Layer
+13 command classes that handle all workflow operations:
+
+**Initialization & Setup**
+- `InitCommand` - Initialize Taskflow in a project
+
+**Status & Navigation**
+- `StatusCommand` - View project, feature, or story status
+- `NextCommand` - Find next available task
+
+**PRD & Task Generation**
+- `PrdCreateCommand` - Create PRD template
+- `PrdGenerateArchCommand` - Generate coding standards and architecture rules from PRD
+- `TasksGenerateCommand` - Generate task breakdown from PRD
+
+**Task Workflow**
+- `StartCommand` - Start a task (SETUP phase)
+- `CheckCommand` - Validate and advance task status
+- `CommitCommand` - Commit changes and complete task
+- `ResumeCommand` - Resume blocked/on-hold tasks
+- `SkipCommand` - Mark task as blocked
+
+**Retrospective System**
+- `RetroAddCommand` - Add error pattern to retrospective
+- `RetroListCommand` - List retrospective entries
+
+### Library Modules
+
+**Core Types & Validation**
+- `types.ts` - TypeScript types and Zod schemas for all data structures
+- `errors.ts` - Custom error classes (FileNotFoundError, InvalidFileFormatError, etc.)
+
+**Data & Configuration**
+- `config-loader.ts` - Load and validate taskflow.config.json
+- `config-paths.ts` - Path helpers and configuration constants
+- `data-access.ts` - JSON file operations for tasks, features, and project index
+
+**Workflow Support**
+- `git.ts` - Git operations (branch switching, commit, push)
+- `validation.ts` - Run configured validation commands
+- `retrospective.ts` - Error pattern tracking and matching
+- `output.ts` - Terminal output formatting utilities
+
+### CLI Interface
+
+The package includes a CLI via `bin/taskflow.js` using Commander.js:
+
+```bash
+# Initialize project
+taskflow init [project-name]
+
+# Status and navigation
+taskflow status [id]
+taskflow next
+
+# PRD workflow
+taskflow prd create <feature-name>
+taskflow prd generate-arch <prd-file>
+taskflow tasks generate <prd-file>
+
+# Task workflow
+taskflow start <task-id>
+taskflow check
+taskflow commit <message>
+taskflow resume [status]
+taskflow skip <reason>
+
+# Retrospective
+taskflow retro add
+taskflow retro list [category]
+```
+
+## 📊 Task Status Flow
+
+Tasks progress through a state machine:
+
+```
+not-started → setup → implementing → verifying → validating → committing → completed
+```
+
+Other states: `blocked`, `on-hold`
+
+## 🔧 Programmatic Usage
+
+```typescript
+import {
+  StartCommand,
+  CheckCommand,
+  CommitCommand,
+  type CommandContext
+} from '@krr2020/taskflow-core';
+
+const context: CommandContext = {
+  projectRoot: process.cwd()
+};
+
+// Start a task
+const startCmd = new StartCommand(context);
+const result = await startCmd.execute('1.1.0');
+
+console.log(result.output);     // Human-readable output
+console.log(result.nextSteps);  // Next action guidance
+console.log(result.aiGuidance); // AI-specific instructions
+```
+
+## 📁 Data Structure
+
+### Project Hierarchy
+```
+project-index.json         # Top-level project and features index
+tasks/
+  └── F1/                  # Feature directory
+      └── F1.json          # Feature file with stories
+      └── S1.1/            # Story directory
+          └── T1.1.0.json  # Individual task files
+```
+
+### Configuration
+
+`taskflow.config.json`:
+```json
+{
+  "project": {
+    "name": "my-project",
+    "root": "."
+  },
+  "branching": {
+    "strategy": "per-story",
+    "base": "main",
+    "prefix": "story/"
+  },
+  "validation": {
+    "commands": {
+      "format": "echo 'running format'",
+      "test": "echo 'running tests'",
+      "build": "echo 'building project'"
+    }
+  }
+}
+```
+
+## 🧪 Testing
+
+```bash
+# Run tests
+pnpm test
+
+# Watch mode
+pnpm test --watch
+
+# Coverage
+pnpm test --coverage
+```
+
+## 📚 Integration
+
+Most users should use this package via:
+- **[@krr2020/taskflow-mcp-server](https://www.npmjs.com/package/@krr2020/taskflow-mcp-server)** - MCP Server for Claude Desktop
+- **CLI** - Direct command-line usage via `npx @krr2020/taskflow-core`
+
+See the main [Taskflow documentation](../../README.md) for complete usage examples.
+
+## 📄 License
+
+MIT

package/bin/taskflow.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+/**
+ * TaskFlow CLI Executable
+ *
+ * This is the entry point for the taskflow command-line tool.
+ */
+
+import { runCLI } from "../dist/cli/index.js";
+
+// Run the CLI
+runCLI().catch((error) => {
+	console.error("Fatal error:", error);
+	process.exit(1);
+});

package/dist/cli/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * TaskFlow CLI - Command-line interface
+ */
+export declare function runCLI(): Promise<void>;

package/dist/cli/index.js

@@ -0,0 +1,352 @@
+/**
+ * TaskFlow CLI - Command-line interface
+ */
+import process from "node:process";
+import { Command } from "commander";
+// Import commands
+import { InitCommand } from "../commands/init.js";
+import { PrdCreateCommand } from "../commands/prd/create.js";
+import { PrdGenerateArchCommand } from "../commands/prd/generate-arch.js";
+import { RetroAddCommand } from "../commands/retro/add.js";
+import { RetroListCommand } from "../commands/retro/list.js";
+import { TasksGenerateCommand } from "../commands/tasks/generate.js";
+import { UpgradeCommand } from "../commands/upgrade.js";
+import { CheckCommand } from "../commands/workflow/check.js";
+import { CommitCommand } from "../commands/workflow/commit.js";
+import { DoCommand } from "../commands/workflow/do.js";
+import { NextCommand } from "../commands/workflow/next.js";
+import { ResumeCommand } from "../commands/workflow/resume.js";
+import { SkipCommand } from "../commands/workflow/skip.js";
+import { StartCommand } from "../commands/workflow/start.js";
+import { StatusCommand } from "../commands/workflow/status.js";
+// Import errors
+import { formatError, TaskflowError } from "../lib/errors.js";
+import { consoleOutput, formatFailure, formatSuccess, printLine, } from "../lib/output.js";
+export async function runCLI() {
+    const program = new Command();
+    program
+        .name("taskflow")
+        .description("AI-first task management and workflow system")
+        .version("1.0.0");
+    // Create command context
+    const context = {
+        projectRoot: process.cwd(),
+    };
+    // ========================================
+    // INIT COMMAND
+    // ========================================
+    program
+        .command("init")
+        .description("Initialize taskflow in the current project")
+        .argument("[project-name]", "Project name (defaults to directory name)")
+        .action(async (projectName) => {
+        try {
+            const cmd = new InitCommand(context);
+            const result = await cmd.execute(projectName);
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    // ========================================
+    // UPGRADE COMMAND
+    // ========================================
+    program
+        .command("upgrade")
+        .description("Upgrade .taskflow reference files to latest version")
+        .option("--force", "Force upgrade even if already up to date")
+        .option("--auto", "Skip prompts for user-generated files")
+        .option("--diff", "Show diff summary without upgrading")
+        .action(async (options) => {
+        try {
+            const cmd = new UpgradeCommand(context);
+            const result = await cmd.execute(options);
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    // ========================================
+    // STATUS COMMAND
+    // ========================================
+    program
+        .command("status")
+        .description("Show project, feature, or story status")
+        .argument("[id]", "Feature ID (N) or Story ID (N.M)")
+        .action(async (id) => {
+        try {
+            const cmd = new StatusCommand(context);
+            const result = await cmd.execute(id);
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    // ========================================
+    // NEXT COMMAND
+    // ========================================
+    program
+        .command("next")
+        .description("Find the next available task")
+        .action(async () => {
+        try {
+            const cmd = new NextCommand(context);
+            const result = await cmd.execute();
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    // ========================================
+    // START COMMAND
+    // ========================================
+    program
+        .command("start")
+        .description("Start working on a task")
+        .argument("<task-id>", "Task ID (e.g., 1.1.0)")
+        .action(async (taskId) => {
+        try {
+            const cmd = new StartCommand(context);
+            const result = await cmd.execute(taskId);
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    // ========================================
+    // CHECK COMMAND
+    // ========================================
+    program
+        .command("check")
+        .description("Validate current task and advance to next status")
+        .action(async () => {
+        try {
+            const cmd = new CheckCommand(context);
+            const result = await cmd.execute();
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    // ========================================
+    // COMMIT COMMAND
+    // ========================================
+    program
+        .command("commit")
+        .description("Commit changes and complete the task")
+        .argument("<message>", 'Bullet points describing changes (e.g., "- Added X\\n- Fixed Y")')
+        .action(async (message) => {
+        try {
+            const cmd = new CommitCommand(context);
+            const result = await cmd.execute(message);
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    // ========================================
+    // DO COMMAND
+    // ========================================
+    program
+        .command("do")
+        .description("Execute the next step of the current task")
+        .action(async () => {
+        try {
+            const cmd = new DoCommand(context);
+            const result = await cmd.execute();
+            if (!result.success) {
+                consoleOutput(formatFailure(result));
+                process.exit(1);
+            }
+            else {
+                // Don't modify output for 'do' command as it has custom formatting
+                printLine(result.output);
+                if (result.nextSteps) {
+                    printLine("\nNEXT STEPS:");
+                    printLine(result.nextSteps);
+                }
+            }
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    // ========================================
+    // RESUME COMMAND
+    // ========================================
+    program
+        .command("resume")
+        .description("Resume a blocked or on-hold task")
+        .argument("[status]", "Status to resume to (setup, implementing, verifying, validating)")
+        .action(async (status) => {
+        try {
+            const cmd = new ResumeCommand(context);
+            const result = await cmd.execute(status);
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    // ========================================
+    // SKIP COMMAND
+    // ========================================
+    program
+        .command("skip")
+        .description("Mark current task as blocked")
+        .argument("<reason>", "Reason for blocking the task")
+        .action(async (reason) => {
+        try {
+            const cmd = new SkipCommand(context);
+            const result = await cmd.execute(reason);
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    // ========================================
+    // PRD COMMANDS
+    // ========================================
+    const prdCommand = program
+        .command("prd")
+        .description("PRD (Product Requirements Document) commands");
+    prdCommand
+        .command("create")
+        .description("Create a new PRD")
+        .argument("<feature-name>", "Name of the feature")
+        .action(async (featureName) => {
+        try {
+            const cmd = new PrdCreateCommand(context);
+            const result = await cmd.execute(featureName);
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    prdCommand
+        .command("generate-arch")
+        .description("Generate CODING-STANDARDS.md and ARCHITECTURE-RULES.md from PRD")
+        .argument("<prd-file>", "PRD filename")
+        .action(async (prdFile) => {
+        try {
+            const cmd = new PrdGenerateArchCommand(context);
+            const result = await cmd.execute(prdFile);
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    // ========================================
+    // TASKS COMMANDS
+    // ========================================
+    const tasksCommand = program
+        .command("tasks")
+        .description("Task generation commands");
+    tasksCommand
+        .command("generate")
+        .description("Generate task breakdown from PRD")
+        .argument("<prd-file>", "PRD filename")
+        .action(async (prdFile) => {
+        try {
+            const cmd = new TasksGenerateCommand(context);
+            const result = await cmd.execute(prdFile);
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    // ========================================
+    // RETRO COMMANDS
+    // ========================================
+    const retroCommand = program
+        .command("retro")
+        .description("Retrospective commands");
+    retroCommand
+        .command("add")
+        .description("Add a retrospective entry for a known error pattern")
+        .argument("<category>", "Error category")
+        .argument("<pattern>", "Error pattern to match")
+        .argument("<solution>", "Solution to the error")
+        .argument("[criticality]", "Criticality level (low, medium, high) - defaults to medium")
+        .action(async (category, pattern, solution, criticality) => {
+        try {
+            const cmd = new RetroAddCommand(context);
+            const result = await cmd.execute(category, pattern, solution, criticality || "medium");
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    retroCommand
+        .command("list")
+        .description("List all retrospective entries")
+        .argument("[category]", "Filter by category")
+        .action(async (category) => {
+        try {
+            const cmd = new RetroListCommand(context);
+            const result = await cmd.execute(category);
+            console.log(formatSuccess(result));
+            process.exit(0);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    // Parse command line arguments
+    await program.parseAsync(process.argv);
+}
+/**
+ * Handle errors with proper formatting
+ */
+function handleError(error) {
+    // Check if it's a failed CommandResult
+    if (typeof error === "object" &&
+        error !== null &&
+        "success" in error &&
+        error.success === false) {
+        console.error(formatFailure(error));
+        process.exit(1);
+    }
+    if (error instanceof TaskflowError) {
+        // Custom TaskFlow errors
+        console.error(formatError(error));
+        process.exit(1);
+    }
+    if (error instanceof Error) {
+        // Generic errors
+        console.error(formatError(error));
+        console.error("\nStack trace:");
+        console.error(error.stack);
+        process.exit(1);
+    }
+    // Unknown error type
+    console.error("An unknown error occurred:");
+    console.error(error);
+    process.exit(1);
+}

package/dist/commands/base.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Base command infrastructure for AI-first command design
+ * Every command returns structured guidance for AI agents
+ */
+export interface CommandContext {
+    projectRoot: string;
+}
+export interface CommandResult {
+    success: boolean;
+    output: string;
+    nextSteps: string;
+    aiGuidance?: string;
+    contextFiles?: string[];
+    warnings?: string[];
+    errors?: string[];
+}
+export declare abstract class BaseCommand {
+    protected context: CommandContext;
+    constructor(context: CommandContext);
+    abstract execute(...args: unknown[]): Promise<CommandResult>;
+    /**
+     * Format command result for terminal output
+     * Returns formatted string with sections: OUTPUT, CONTEXT FILES, NEXT STEPS, AI GUIDANCE, WARNINGS
+     */
+    protected formatOutput(result: CommandResult): string;
+    /**
+     * Create a successful command result
+     */
+    protected success(output: string, nextSteps: string, options?: {
+        aiGuidance?: string;
+        contextFiles?: string[];
+        warnings?: string[];
+    }): CommandResult;
+    /**
+     * Create a failed command result
+     */
+    protected failure(output: string, errors: string[], nextSteps: string, options?: {
+        aiGuidance?: string;
+        warnings?: string[];
+    }): CommandResult;
+}

package/dist/commands/base.js

@@ -0,0 +1,86 @@
+/**
+ * Base command infrastructure for AI-first command design
+ * Every command returns structured guidance for AI agents
+ */
+export class BaseCommand {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    /**
+     * Format command result for terminal output
+     * Returns formatted string with sections: OUTPUT, CONTEXT FILES, NEXT STEPS, AI GUIDANCE, WARNINGS
+     */
+    formatOutput(result) {
+        const sections = [];
+        const separator = "─".repeat(60);
+        // OUTPUT section
+        sections.push("OUTPUT:");
+        sections.push(separator);
+        sections.push(result.output);
+        sections.push("");
+        // CONTEXT FILES section (if any)
+        if (result.contextFiles && result.contextFiles.length > 0) {
+            sections.push("CONTEXT FILES (Read these before proceeding):");
+            sections.push(separator);
+            for (const [index, file] of result.contextFiles.entries()) {
+                sections.push(`${index + 1}. ${file}`);
+            }
+            sections.push("");
+        }
+        // NEXT STEPS section
+        sections.push("NEXT STEPS:");
+        sections.push(separator);
+        sections.push(result.nextSteps);
+        sections.push("");
+        // AI GUIDANCE section (if any)
+        if (result.aiGuidance) {
+            sections.push("AI GUIDANCE:");
+            sections.push(separator);
+            sections.push(result.aiGuidance);
+            sections.push("");
+        }
+        // WARNINGS section (if any)
+        if (result.warnings && result.warnings.length > 0) {
+            sections.push("WARNINGS:");
+            sections.push(separator);
+            for (const warning of result.warnings) {
+                sections.push(`⚠ ${warning}`);
+            }
+            sections.push("");
+        }
+        // ERRORS section (if any)
+        if (result.errors && result.errors.length > 0) {
+            sections.push("ERRORS:");
+            sections.push(separator);
+            for (const error of result.errors) {
+                sections.push(`✗ ${error}`);
+            }
+            sections.push("");
+        }
+        return sections.join("\n");
+    }
+    /**
+     * Create a successful command result
+     */
+    success(output, nextSteps, options) {
+        return {
+            success: true,
+            output,
+            nextSteps,
+            ...options,
+        };
+    }
+    /**
+     * Create a failed command result
+     */
+    failure(output, errors, nextSteps, options) {
+        return {
+            success: false,
+            output,
+            nextSteps,
+            errors,
+            ...options,
+        };
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Init command - Initialize taskflow in a project
+ */
+import { BaseCommand, type CommandResult } from "./base.js";
+export declare class InitCommand extends BaseCommand {
+    execute(projectName?: string): Promise<CommandResult>;
+}