TYPES DOCUMENTATION
TECHNICAL BULLETIN NO. 004
OPTIONS TYPES - COMMAND OPERATION DEFINITION SYSTEM
task-o-matic-options-types-v1All PersonnelMANDATORY COMPLIANCE: Yes
⚠️ CRITICAL SURVIVAL NOTICE
Citizen, ignore these option types and your commands become lost in translation. Parameters misinterpret, validation fails, and your CLI becomes a tower of babel where no one understands each other. This is your command language foundation.
TYPE SYSTEM ARCHITECTURE
The options types system provides specialized interfaces for each command operation. It uses inheritance patterns and composition to create reusable, type-safe command configurations. The architecture supports:
- Command-Specific Options: Tailored interfaces for each operation
- AI Integration: Streaming and provider configuration
- Validation Patterns: Type-safe parameter handling
- Extensibility: Easy to add new command options
- Consistency: Standardized patterns across commands
This design enables clear command contracts while maintaining flexibility for different command requirements.
COMPLETE TYPE DOCUMENTATION
#### Task Management Options
##### ListTasksOptions Interface
export interface ListTasksOptions {
status?: string;
tag?: string;
}Purpose: Options for listing tasks with filtering
Properties:
- status (Optional, string): Filter by task status
- tag (Optional, string): Filter by tag name
Usage Examples:
// List all todo tasks
const todoTasks: ListTasksOptions = {
status: "todo"
};
// List tasks with specific tag
const bugTasks: ListTasksOptions = {
tag: "bug"
};
// Combined filters
const todoBugs: ListTasksOptions = {
status: "todo",
tag: "bug"
};##### ShowTaskOptions Interface
export interface ShowTaskOptions {
id: string;
}Purpose: Options for displaying detailed task information
Properties:
- id (Required, string): Task ID to display
Usage Examples:
// Show specific task
const showTask: ShowTaskOptions = {
id: "task-123"
};##### DocumentTaskOptions Interface
export interface DocumentTaskOptions extends StreamingAIOptions {
taskId: string;
force?: boolean;
}Purpose: Options for generating task documentation
Inherited Properties: From StreamingAIOptions
Specific Properties:
- taskId (Required, string): Task ID to document
- force (Optional, boolean): Regenerate documentation even if exists
Usage Examples:
// Basic documentation generation
const basicDoc: DocumentTaskOptions = {
taskId: "task-123",
aiProvider: "anthropic",
stream: true
};
// Force regeneration
const forceDoc: DocumentTaskOptions = {
taskId: "task-123",
force: true,
aiProvider: "openrouter",
aiModel: "claude-3.5-sonnet"
};##### EnhanceTaskOptions Interface
export interface EnhanceTaskOptions extends StreamingAIOptions {
taskId: string;
all?: boolean;
}Purpose: Options for enhancing tasks with AI
Inherited Properties: From StreamingAIOptions
Specific Properties:
- taskId (Required, string): Specific task ID to enhance
- all (Optional, boolean): Enhance all tasks
Usage Examples:
// Enhance single task
const enhanceSingle: EnhanceTaskOptions = {
taskId: "task-123",
aiProvider: "anthropic",
stream: true
};
// Enhance all tasks
const enhanceAll: EnhanceTaskOptions = {
all: true,
aiProvider: "openrouter",
reasoning: "5000"
};##### SplitTaskOptions Interface
export interface SplitTaskOptions extends StreamingAIOptions {
taskId: string;
all?: boolean;
prompt?: string;
message?: string;
}Purpose: Options for splitting tasks into subtasks
Inherited Properties: From StreamingAIOptions
Specific Properties:
- taskId (Required, string): Specific task ID to split
- all (Optional, boolean): Split all tasks
- prompt (Optional, string): Custom splitting prompt
- message (Optional, string): Alias for prompt
Usage Examples:
// Basic task splitting
const basicSplit: SplitTaskOptions = {
taskId: "task-123",
aiProvider: "anthropic",
stream: true
};
// Split with custom prompt
const customSplit: SplitTaskOptions = {
taskId: "task-123",
prompt: "Split this into user interface and backend components",
aiProvider: "openrouter",
aiModel: "claude-3.5-sonnet"
};
// Split all tasks
const splitAll: SplitTaskOptions = {
all: true,
message: "Break down into implementable subtasks"
};##### PlanTaskOptions Interface
export interface PlanTaskOptions extends StreamingAIOptions {
id: string;
}Purpose: Options for generating implementation plans
Inherited Properties: From StreamingAIOptions
Specific Properties:
- id (Required, string): Task ID to plan
Usage Examples:
// Generate plan for task
const planTask: PlanTaskOptions = {
id: "task-123",
aiProvider: "anthropic",
aiModel: "claude-3.5-sonnet",
stream: true
};##### GetPlanOptions Interface
export interface GetPlanOptions {
id: string;
}Purpose: Options for retrieving existing implementation plan
Properties:
- id (Required, string): Task ID whose plan to retrieve
Usage Examples:
// Get task plan
const getPlan: GetPlanOptions = {
id: "task-123"
};##### UpdateTaskOptions Interface
export interface UpdateTaskOptions {
id: string;
title?: string;
description?: string;
status?: "todo" | "in-progress" | "completed";
effort?: "small" | "medium" | "large";
tags?: string;
}Purpose: Options for updating task properties
Properties:
- id (Required, string): Task ID to update
- title (Optional, string): New task title
- description (Optional, string): New task description
- status (Optional, union): New task status
- effort (Optional, union): New effort estimate
- tags (Optional, string): Comma-separated tag list
Usage Examples:
// Update task status
const updateStatus: UpdateTaskOptions = {
id: "task-123",
status: "in-progress"
};
// Update multiple properties
const updateMultiple: UpdateTaskOptions = {
id: "task-123",
title: "Fix critical authentication bug",
description: "Users cannot login due to token validation error",
status: "in-progress",
effort: "medium",
tags: "bug,critical,security"
};
// Add tags
const addTags: UpdateTaskOptions = {
id: "task-123",
tags: "frontend,react,component"
};##### DeleteTaskOptions Interface
export interface DeleteTaskOptions {
id: string;
force?: boolean;
cascade?: boolean;
}Purpose: Options for deleting tasks
Properties:
- id (Required, string): Task ID to delete
- force (Optional, boolean): Skip confirmation prompts
- cascade (Optional, boolean): Delete subtasks recursively
Usage Examples:
// Delete with confirmation
const deleteTask: DeleteTaskOptions = {
id: "task-123"
};
// Force delete
const forceDelete: DeleteTaskOptions = {
id: "task-123",
force: true
};
// Cascade delete
const cascadeDelete: DeleteTaskOptions = {
id: "task-123",
cascade: true,
force: true
};##### SetTaskStatusOptions Interface
export interface SetTaskStatusOptions {
id: string;
status: "todo" | "in-progress" | "completed";
}Purpose: Options for setting task status
Properties:
- id (Required, string): Task ID to update
- status (Required, union): New status value
Usage Examples:
// Mark task as in progress
const startTask: SetTaskStatusOptions = {
id: "task-123",
status: "in-progress"
};
// Complete task
const completeTask: SetTaskStatusOptions = {
id: "task-123",
status: "completed"
};##### ManageTagsOptions Interface
export interface ManageTagsOptions {
id: string;
tags: string;
}Purpose: Options for managing task tags
Properties:
- id (Required, string): Task ID to modify
- tags (Required, string): Comma-separated tag list
Usage Examples:
// Add tags
const addTags: ManageTagsOptions = {
id: "task-123",
tags: "bug,critical,frontend"
};
// Remove tags (same interface)
const removeTags: ManageTagsOptions = {
id: "task-123",
tags: "bug,critical"
};#### PRD Management Options
##### ParsePrdOptions Interface
export interface ParsePrdOptions extends StreamingAIOptions {
file: string;
prompt?: string;
message?: string;
}Purpose: Options for parsing Product Requirements Documents
Inherited Properties: From StreamingAIOptions
Specific Properties:
- file (Required, string): Path to PRD file
- prompt (Optional, string): Custom parsing prompt
- message (Optional, string): Alias for prompt
Usage Examples:
// Basic PRD parsing
const parsePrd: ParsePrdOptions = {
file: "./docs/PRD.md",
aiProvider: "anthropic",
stream: true
};
// Custom parsing instructions
const customParse: ParsePrdOptions = {
file: "./docs/PRD.md",
prompt: "Focus on technical requirements and user stories",
message: "Extract actionable tasks from this PRD",
aiProvider: "openrouter",
aiModel: "claude-3.5-sonnet"
};##### ReworkPrdOptions Interface
export interface ReworkPrdOptions extends StreamingAIOptions {
file: string;
feedback: string;
output?: string;
prompt?: string;
message?: string;
}Purpose: Options for reworking PRDs based on feedback
Inherited Properties: From StreamingAIOptions
Specific Properties:
- file (Required, string): Path to PRD file
- feedback (Required, string): Feedback for improvements
- output (Optional, string): Output file path
- prompt (Optional, string): Custom rework prompt
- message (Optional, string): Alias for prompt
Usage Examples:
// Basic PRD rework
const reworkPrd: ReworkPrdOptions = {
file: "./docs/PRD.md",
feedback: "Add more technical details and acceptance criteria",
aiProvider: "anthropic",
stream: true
};
// Rework with custom output
const customRework: ReworkPrdOptions = {
file: "./docs/PRD.md",
feedback: "Include security requirements and performance metrics",
output: "./docs/PRD-v2.md",
prompt: "Improve this PRD with specific focus on security",
aiProvider: "openrouter",
aiModel: "claude-3.5-sonnet"
};#### Workflow Options
##### WorkflowStep Type
export type WorkflowStep =
| "initialize"
| "define-prd"
| "question-refine-prd"
| "refine-prd"
| "generate-tasks"
| "split-tasks"
| "complete";Purpose: Defined workflow automation steps
Step Definitions:
- "initialize": Project initialization
- "define-prd": PRD creation/upload
- "question-refine-prd": AI-driven PRD questioning
- "refine-prd": PRD improvement based on feedback
- "generate-tasks": Task creation from PRD
- "split-tasks": Task breakdown into subtasks
- "complete": Workflow completion
Usage Examples:
// Current step tracking
let currentStep: WorkflowStep = "initialize";
// Step progression
function nextStep(current: WorkflowStep): WorkflowStep {
const steps: WorkflowStep[] = [
"initialize",
"define-prd",
"question-refine-prd",
"refine-prd",
"generate-tasks",
"split-tasks",
"complete"
];
const currentIndex = steps.indexOf(current);
return steps[Math.min(currentIndex + 1, steps.length - 1)];
}
// Step-specific handling
function handleStep(step: WorkflowStep): void {
switch (step) {
case "initialize":
console.log("🚀 Initializing project...");
break;
case "define-prd":
console.log("📝 Defining PRD...");
break;
case "question-refine-prd":
console.log("❓ Refining PRD with questions...");
break;
case "refine-prd":
console.log("✏️ Refining PRD...");
break;
case "generate-tasks":
console.log("📋 Generating tasks...");
break;
case "split-tasks":
console.log("🔧 Splitting tasks...");
break;
case "complete":
console.log("✅ Workflow complete!");
break;
}
}##### WorkflowState Interface
export interface WorkflowState {
projectName?: string;
projectDir?: string;
initialized: boolean;
prdFile?: string;
prdContent?: string;
tasks?: Array<{ id: string; title: string; description?: string }>;
currentStep: WorkflowStep;
aiConfig?: {
provider: string;
model: string;
key?: string;
};
}Purpose: Complete workflow execution state
Properties:
- projectName (Optional, string): Project name
- projectDir (Optional, string): Project directory path
- initialized (Required, boolean): Whether project is initialized
- prdFile (Optional, string): Path to PRD file
- prdContent (Optional, string): PRD file content
- tasks (Optional, array): Generated tasks
- currentStep (Required, WorkflowStep): Current workflow step
- aiConfig (Optional, object): AI configuration
Usage Examples:
// Initial workflow state
const initialState: WorkflowState = {
initialized: false,
currentStep: "initialize"
};
// After initialization
const afterInit: WorkflowState = {
projectName: "My Project",
projectDir: "/path/to/my-project",
initialized: true,
currentStep: "define-prd",
aiConfig: {
provider: "anthropic",
model: "claude-3.5-sonnet",
key: "sk-ant-..."
}
};
// After PRD creation
const afterPRD: WorkflowState = {
projectName: "My Project",
projectDir: "/path/to/my-project",
initialized: true,
prdFile: "./docs/PRD.md",
prdContent: "# My Project\n\nThis project builds...",
currentStep: "generate-tasks",
aiConfig: {
provider: "anthropic",
model: "claude-3.5-sonnet"
}
};
// After task generation
const afterTasks: WorkflowState = {
projectName: "My Project",
projectDir: "/path/to/my-project",
initialized: true,
prdFile: "./docs/PRD.md",
prdContent: "# My Project\n\nThis project builds...",
tasks: [
{ id: "task-1", title: "Setup project structure", description: "Create directories and package.json" },
{ id: "task-2", title: "Build authentication", description: "Implement user login system" },
{ id: "task-3", title: "Create dashboard", description: "Build main user interface" }
],
currentStep: "split-tasks"
};##### AIAssistedChoice Interface
export interface AIAssistedChoice<T = any> {
userInput: string;
availableOptions: T[];
context: string;
recommendation?: T;
}Purpose: AI-assisted decision making structure
Properties:
- userInput (Required, string): User's input
- availableOptions (Required, array): Available choices
- context (Required, string): Decision context
- recommendation (Optional, T): AI's recommendation
Usage Examples:
// Frontend selection
const frontendChoice: AIAssistedChoice<string> = {
userInput: "I want to build a web app",
availableOptions: ["next", "react-router", "nuxt", "svelte"],
context: "Frontend framework selection",
recommendation: "next"
};
// Database selection
const databaseChoice: AIAssistedChoice<string> = {
userInput: "I need to store user data",
availableOptions: ["postgres", "mysql", "sqlite"],
context: "Database selection",
recommendation: "postgres"
};
// Complex choice with objects
const configChoice: AIAssistedChoice<{ name: string; description: string }> = {
userInput: "What authentication system?",
availableOptions: [
{ name: "better-auth", description: "Modern auth with multiple providers" },
{ name: "clerk", description: "Headless auth service" },
{ name: "none", description: "No authentication" }
],
context: "Authentication system selection",
recommendation: { name: "better-auth", description: "Modern auth with multiple providers" }
};##### InitConfigChoice Interface
export interface InitConfigChoice {
projectName: string;
aiProvider: string;
aiModel: string;
aiProviderUrl?: string;
frontend?: string;
backend?: string;
database?: string;
auth?: boolean;
reasoning?: string;
}Purpose: Complete project initialization configuration
Properties:
- projectName (Required, string): Project name
- aiProvider (Required, string): AI provider
- aiModel (Required, string): AI model
- aiProviderUrl (Optional, string): Custom AI endpoint
- frontend (Optional, string): Frontend framework
- backend (Optional, string): Backend framework
- database (Optional, string): Database choice
- auth (Optional, boolean): Include authentication
- reasoning (Optional, string): Reasoning token limit
Usage Examples:
// Full-stack web application
const fullStackConfig: InitConfigChoice = {
projectName: "E-commerce Platform",
aiProvider: "anthropic",
aiModel: "claude-3.5-sonnet",
frontend: "next",
backend: "hono",
database: "postgres",
auth: true,
reasoning: "5000"
};
// CLI-only project
const cliConfig: InitConfigChoice = {
projectName: "Task CLI Tool",
aiProvider: "openrouter",
aiModel: "anthropic/claude-3.5-sonnet",
frontend: "cli",
backend: "none",
database: "none",
auth: false
};
// Custom AI provider
const customAIConfig: InitConfigChoice = {
projectName: "AI Assistant",
aiProvider: "custom",
aiModel: "llama-3-70b",
aiProviderUrl: "https://api.custom-ai.com/v1",
frontend: "react-router",
backend: "express",
database: "mysql",
auth: true
};#### Additional Task Options
##### GetNextTaskOptions Interface
export interface GetNextTaskOptions {
status?: "todo" | "in-progress";
tag?: string;
effort?: "small" | "medium" | "large";
priority?: "newest" | "oldest" | "effort";
}Purpose: Options for retrieving next available task
Properties:
- status (Optional, union): Filter by status
- tag (Optional, string): Filter by tag
- effort (Optional, union): Filter by effort level
- priority (Optional, union): Sort order priority
Usage Examples:
// Get next todo task
const nextTodo: GetNextTaskOptions = {
status: "todo"
};
// Get next high-effort task
const nextLarge: GetNextTaskOptions = {
effort: "large",
priority: "oldest"
};
// Get next bug task
const nextBug: GetNextTaskOptions = {
tag: "bug",
status: "todo",
priority: "newest"
};
// Get oldest in-progress task
const resumeWork: GetNextTaskOptions = {
status: "in-progress",
priority: "oldest"
};##### ListSubtasksOptions Interface
export interface ListSubtasksOptions {
id: string;
}Purpose: Options for listing task subtasks
Properties:
- id (Required, string): Parent task ID
Usage Examples:
// List subtasks
const listSubtasks: ListSubtasksOptions = {
id: "task-parent-123"
};##### TaskTreeOptions Interface
export interface TaskTreeOptions {
id?: string;
}Purpose: Options for displaying task hierarchy
Properties:
- id (Optional, string): Root task ID (shows all if omitted)
Usage Examples:
// Show full task tree
const fullTree: TaskTreeOptions = {};
// Show subtree
const subtree: TaskTreeOptions = {
id: "task-parent-123"
};##### DeletePlanOptions Interface
export interface DeletePlanOptions {
id: string;
}Purpose: Options for deleting task implementation plan
Properties:
- id (Required, string): Task ID whose plan to delete
Usage Examples:
// Delete task plan
const deletePlan: DeletePlanOptions = {
id: "task-123"
};#### Base AI Options
##### AIProviderOptions Interface
export interface AIProviderOptions {
aiProvider?: string;
aiModel?: string;
aiKey?: string;
aiProviderUrl?: string;
aiReasoning?: string;
}Purpose: Base AI provider configuration options
Properties:
- aiProvider (Optional, string): AI provider name
- aiModel (Optional, string): AI model name
- aiKey (Optional, string): API authentication key
- aiProviderUrl (Optional, string): Custom endpoint URL
- aiReasoning (Optional, string): Reasoning token limit
Usage Examples:
// OpenAI configuration
const openaiOptions: AIProviderOptions = {
aiProvider: "openai",
aiModel: "gpt-4",
aiKey: "sk-openai-..."
};
// Anthropic with reasoning
const anthropicOptions: AIProviderOptions = {
aiProvider: "anthropic",
aiModel: "claude-3.5-sonnet",
aiKey: "sk-ant-...",
aiReasoning: "5000"
};
// Custom provider
const customOptions: AIProviderOptions = {
aiProvider: "custom",
aiModel: "llama-3-70b",
aiProviderUrl: "https://api.custom-ai.com/v1",
aiKey: "custom-key"
};##### StreamingAIOptions Interface
export interface StreamingAIOptions extends AIProviderOptions {
stream?: boolean;
}Purpose: AI options with streaming support
Inherited Properties: From AIProviderOptions
Specific Properties:
- stream (Optional, boolean): Enable streaming output
Usage Examples:
// Streaming with OpenAI
const streamingOpenAI: StreamingAIOptions = {
aiProvider: "openai",
aiModel: "gpt-4",
stream: true
};
// Non-streaming with Anthropic
const nonStreamingAnthropic: StreamingAIOptions = {
aiProvider: "anthropic",
aiModel: "claude-3.5-sonnet",
stream: false
};FUNCTION DOCUMENTATION
No standalone functions in this module - this is a type definition file.
INTEGRATION PROTOCOLS
#### Command Handler Integration
// commands/tasks/index.ts
import {
ListTasksOptions,
CreateTaskOptions,
UpdateTaskOptions,
DeleteTaskOptions,
EnhanceTaskOptions,
SplitTaskOptions,
PlanTaskOptions,
DocumentTaskOptions
} from '../../types/options';
export class TaskCommandHandlers {
async handleList(options: ListTasksOptions): Promise<void> {
const tasks = await this.taskService.listTasks({
status: options.status,
tag: options.tag
});
this.displayTasks(tasks);
}
async handleCreate(options: CreateTaskOptions): Promise<void> {
const task = await this.taskService.createTask({
title: options.title,
content: options.content,
effort: options.effort as "small" | "medium" | "large",
parentId: options.parentId,
aiEnhance: options.aiEnhance
}, {
aiProvider: options.aiProvider,
aiModel: options.aiModel,
apiKey: options.aiKey,
baseURL: options.aiProviderUrl,
stream: options.stream
});
console.log(`Created task: ${task.id}`);
}
async handleUpdate(options: UpdateTaskOptions): Promise<void> {
const tags = options.tags ? options.tags.split(',').map(t => t.trim()) : undefined;
await this.taskService.updateTask(options.id, {
title: options.title,
description: options.description,
status: options.status,
effort: options.effort,
tags
});
console.log(`Updated task: ${options.id}`);
}
async handleDelete(options: DeleteTaskOptions): Promise<void> {
await this.taskService.deleteTask(options.id, {
force: options.force,
cascade: options.cascade
});
console.log(`Deleted task: ${options.id}`);
}
async handleEnhance(options: EnhanceTaskOptions): Promise<void> {
if (options.all) {
const tasks = await this.taskService.listTasks();
for (const task of tasks) {
await this.enhanceSingleTask(task.id, options);
}
} else {
await this.enhanceSingleTask(options.taskId, options);
}
}
private async enhanceSingleTask(taskId: string, options: EnhanceTaskOptions): Promise<void> {
await this.taskService.enhanceTask(taskId, {
aiProvider: options.aiProvider,
aiModel: options.aiModel,
apiKey: options.aiKey,
baseURL: options.aiProviderUrl,
stream: options.stream
});
}
}#### Service Layer Integration
// services/tasks.ts
import {
CreateTaskOptions,
UpdateTaskOptions,
DeleteTaskOptions,
ListTasksOptions,
GetNextTaskOptions
} from '../types/options';
export class TaskService {
async createTask(options: CreateTaskOptions, aiConfig?: AIProviderOptions): Promise<Task> {
const task: Task = {
id: this.generateTaskId(),
title: options.title,
content: options.content,
effort: options.effort,
parentId: options.parentId,
aiEnhance: options.aiEnhance,
status: "todo",
createdAt: Date.now(),
updatedAt: Date.now()
};
await this.storage.saveTask(task);
if (options.aiEnhance) {
await this.enhanceTask(task.id, aiConfig);
}
return task;
}
async updateTask(id: string, options: Partial<UpdateTaskOptions>): Promise<Task> {
const existingTask = await this.storage.getTask(id);
if (!existingTask) {
throw new Error(`Task ${id} not found`);
}
const updatedTask: Task = {
...existingTask,
...options,
updatedAt: Date.now()
};
// Handle tags conversion
if (options.tags && typeof options.tags === 'string') {
updatedTask.tags = options.tags.split(',').map(t => t.trim()).filter(Boolean);
}
await this.storage.updateTask(id, updatedTask);
return updatedTask;
}
async listTasks(options?: ListTasksOptions): Promise<Task[]> {
const filters = {
status: options?.status,
tag: options?.tag
};
return await this.storage.listTasks(filters);
}
async getNextTask(options?: GetNextTaskOptions): Promise<Task | null> {
const tasks = await this.listTasks({
status: options?.status || "todo",
tag: options?.tag
});
// Filter by effort if specified
let filteredTasks = tasks;
if (options?.effort) {
filteredTasks = tasks.filter(task => task.estimatedEffort === options.effort);
}
// Sort by priority
switch (options?.priority) {
case "newest":
filteredTasks.sort((a, b) => b.createdAt - a.createdAt);
break;
case "oldest":
filteredTasks.sort((a, b) => a.createdAt - b.createdAt);
break;
case "effort":
const effortOrder = { "small": 1, "medium": 2, "large": 3 };
filteredTasks.sort((a, b) =>
(effortOrder[a.estimatedEffort || "medium"] || 2) -
(effortOrder[b.estimatedEffort || "medium"] || 2)
);
break;
default:
filteredTasks.sort((a, b) => a.createdAt - b.createdAt);
}
return filteredTasks[0] || null;
}
}#### CLI Integration
// cli/task-commands.ts
import { Command } from 'commander';
import {
CreateTaskOptions,
UpdateTaskOptions,
DeleteTaskOptions,
ListTasksOptions,
EnhanceTaskOptions,
SplitTaskOptions
} from '../../types/options';
export function createTaskCommands(): Command[] {
return [
new Command('create')
.description('Create a new task')
.requiredOption('-t, --title <title>', 'Task title')
.option('-c, --content <content>', 'Task description')
.option('-e, --effort <effort>', 'Effort estimate (small|medium|large)')
.option('-p, --parent <parentId>', 'Parent task ID')
.option('--ai-enhance', 'Enhance with AI')
.option('--stream', 'Stream AI output')
.option('--ai-provider <provider>', 'AI provider')
.option('--ai-model <model>', 'AI model')
.action(async (options: CreateTaskOptions) => {
await taskCommandHandlers.handleCreate(options);
}),
new Command('update')
.description('Update a task')
.requiredOption('-i, --id <taskId>', 'Task ID')
.option('-t, --title <title>', 'New task title')
.option('-d, --description <description>', 'New task description')
.option('-s, --status <status>', 'New status (todo|in-progress|completed)')
.option('-e, --effort <effort>', 'New effort (small|medium|large)')
.option('--tags <tags>', 'Comma-separated tag list')
.action(async (options: UpdateTaskOptions) => {
await taskCommandHandlers.handleUpdate(options);
}),
new Command('list')
.description('List tasks')
.option('-s, --status <status>', 'Filter by status')
.option('-t, --tag <tag>', 'Filter by tag')
.action(async (options: ListTasksOptions) => {
await taskCommandHandlers.handleList(options);
}),
new Command('delete')
.description('Delete a task')
.requiredOption('-i, --id <taskId>', 'Task ID')
.option('-f, --force', 'Skip confirmation')
.option('--cascade', 'Delete subtasks')
.action(async (options: DeleteTaskOptions) => {
await taskCommandHandlers.handleDelete(options);
})
];
}SURVIVAL SCENARIOS
#### Scenario 1: Complete Task Management Workflow
// Complete task management with all operations
class TaskManagementWorkflow {
private taskService: TaskService;
async executeFullWorkflow(): Promise<void> {
console.log("🚀 Starting task management workflow...");
// Step 1: Create tasks
const createOptions: CreateTaskOptions = {
title: "Build user authentication system",
content: "Implement login, registration, and profile management",
effort: "large",
aiEnhance: true,
aiProvider: "anthropic",
stream: true
};
const authTask = await this.taskService.createTask(createOptions);
console.log(`✅ Created task: ${authTask.id}`);
// Step 2: Create subtasks
const loginTask = await this.taskService.createTask({
title: "Implement login form",
content: "Create login interface with validation",
effort: "medium",
parentId: authTask.id
});
const registerTask = await this.taskService.createTask({
title: "Implement registration form",
content: "Create user registration with email verification",
effort: "medium",
parentId: authTask.id
});
const profileTask = await this.taskService.createTask({
title: "Build profile management",
content: "User profile viewing and editing",
effort: "small",
parentId: authTask.id
});
console.log(`✅ Created ${3} subtasks`);
// Step 3: Update main task status
await this.taskService.updateTask(authTask.id, {
status: "in-progress"
});
console.log(`✅ Updated main task status`);
// Step 4: List current tasks
const currentTasks = await this.taskService.listTasks();
console.log(`📋 Current tasks: ${currentTasks.length}`);
// Step 5: Get next task
const nextTask = await this.taskService.getNextTask({
status: "todo",
priority: "oldest"
});
if (nextTask) {
console.log(`➡️ Next task: ${nextTask.title}`);
// Step 6: Enhance next task
const enhanceOptions: EnhanceTaskOptions = {
taskId: nextTask.id,
aiProvider: "openrouter",
aiModel: "claude-3.5-sonnet",
stream: true
};
await this.taskService.enhanceTask(nextTask.id, enhanceOptions);
console.log(`✅ Enhanced task: ${nextTask.id}`);
}
console.log("🎉 Task management workflow complete!");
}
async handleTaskSplitting(): Promise<void> {
const largeTasks = await this.taskService.listTasks({
status: "todo"
});
const largeTasksFiltered = largeTasks.filter(task =>
task.estimatedEffort === "large" && !task.parentId
);
for (const task of largeTasksFiltered) {
console.log(`🔧 Splitting task: ${task.title}`);
const splitOptions: SplitTaskOptions = {
taskId: task.id,
prompt: "Break this down into implementable subtasks with clear acceptance criteria",
aiProvider: "anthropic",
stream: true
};
await this.taskService.splitTask(task.id, splitOptions);
console.log(`✅ Split task: ${task.id}`);
}
}
}#### Scenario 2: PRD Processing Pipeline
// Complete PRD processing workflow
class PRDProcessingWorkflow {
private taskService: TaskService;
async processPRD(filePath: string): Promise<void> {
console.log(`📄 Processing PRD: ${filePath}`);
// Step 1: Parse PRD
const parseOptions: ParsePrdOptions = {
file: filePath,
aiProvider: "anthropic",
aiModel: "claude-3.5-sonnet",
stream: true
};
const parseResult = await this.prdService.parsePRD(parseOptions);
console.log(`✅ Parsed ${parseResult.tasks.length} tasks from PRD`);
// Step 2: Create tasks from parsed results
const createdTasks = [];
for (const parsedTask of parseResult.tasks) {
const createOptions: CreateTaskOptions = {
title: parsedTask.title,
content: parsedTask.description,
effort: parsedTask.effort,
aiEnhance: true,
aiProvider: "openrouter",
aiModel: "claude-3.5-sonnet"
};
const task = await this.taskService.createTask(createOptions);
createdTasks.push(task);
console.log(`✅ Created task: ${task.id} - ${task.title}`);
}
// Step 3: Set up dependencies
for (let i = 0; i < createdTasks.length; i++) {
const task = createdTasks[i];
const dependencies = parseResult.tasks[i].dependencies || [];
if (dependencies.length > 0) {
// Find dependency task IDs
const dependencyIds = dependencies.map(dep => {
const depTask = createdTasks.find(t => t.title === dep);
return depTask ? depTask.id : undefined;
}).filter(Boolean);
await this.taskService.updateTask(task.id, {
dependencies: dependencyIds
});
console.log(`🔗 Set dependencies for task: ${task.id}`);
}
}
// Step 4: Split large tasks
const largeTasks = createdTasks.filter(task => task.effort === "large");
for (const task of largeTasks) {
console.log(`🔧 Splitting large task: ${task.title}`);
const splitOptions: SplitTaskOptions = {
taskId: task.id,
prompt: "Break this large task into smaller, manageable subtasks",
aiProvider: "anthropic",
stream: true
};
await this.taskService.splitTask(task.id, splitOptions);
console.log(`✅ Split task: ${task.id}`);
}
// Step 5: Generate plans for complex tasks
const complexTasks = createdTasks.filter(task =>
task.effort === "large" || task.dependencies && task.dependencies.length > 2
);
for (const task of complexTasks) {
console.log(`📋 Generating plan for: ${task.title}`);
const planOptions: PlanTaskOptions = {
id: task.id,
aiProvider: "openrouter",
aiModel: "claude-3.5-sonnet",
stream: true
};
await this.taskService.planTask(task.id, planOptions);
console.log(`✅ Generated plan for task: ${task.id}`);
}
console.log("🎉 PRD processing workflow complete!");
}
async reworkPRD(filePath: string, feedback: string): Promise<void> {
console.log(`✏️ Reworking PRD: ${filePath}`);
const reworkOptions: ReworkPrdOptions = {
file: filePath,
feedback: feedback,
output: `${filePath}.reworked.md`,
prompt: "Improve this PRD based on the provided feedback, focusing on clarity, completeness, and actionable requirements",
aiProvider: "anthropic",
aiModel: "claude-3.5-sonnet",
stream: true
};
const result = await this.prdService.reworkPRD(reworkOptions);
console.log(`✅ Reworked PRD saved to: ${result.outputFile}`);
// Step 2: Parse updated PRD and create new tasks
await this.processPRD(result.outputFile);
}
}#### Scenario 3: AI Configuration Management
// AI configuration management across operations
class AIConfigManager {
private configs: Map<string, AIProviderOptions> = new Map();
setConfig(operation: string, config: AIProviderOptions): void {
this.configs.set(operation, config);
console.log(`🔧 Set AI config for ${operation}:`, {
provider: config.aiProvider,
model: config.aiModel,
reasoning: config.aiReasoning
});
}
getConfig(operation: string): AIProviderOptions {
const baseConfig = this.configs.get(operation) || {};
const envConfig = this.loadFromEnvironment();
return {
aiProvider: baseConfig.aiProvider || envConfig.aiProvider,
aiModel: baseConfig.aiModel || envConfig.aiModel,
aiKey: baseConfig.aiKey || envConfig.aiKey,
aiProviderUrl: baseConfig.aiProviderUrl || envConfig.aiProviderUrl,
aiReasoning: baseConfig.aiReasoning || envConfig.aiReasoning
};
}
applyConfigToOptions<T extends AIProviderOptions>(
baseOptions: T,
operation: string
): T & StreamingAIOptions {
const config = this.getConfig(operation);
return {
...baseOptions,
aiProvider: config.aiProvider,
aiModel: config.aiModel,
aiKey: config.aiKey,
aiProviderUrl: config.aiProviderUrl,
aiReasoning: config.aiReasoning,
stream: config.stream || false
};
}
private loadFromEnvironment(): AIProviderOptions {
return {
aiProvider: process.env.AI_PROVIDER,
aiModel: process.env.AI_MODEL,
aiKey: process.env.OPENAI_API_KEY ||
process.env.ANTHROPIC_API_KEY ||
process.env.OPENROUTER_API_KEY,
aiProviderUrl: process.env.CUSTOM_API_URL,
aiReasoning: process.env.AI_REASONING
};
}
// Usage in command handlers
async handleEnhanceCommand(baseOptions: EnhanceTaskOptions): Promise<void> {
const options = this.applyConfigToOptions(baseOptions, 'enhance');
if (options.all) {
const tasks = await this.taskService.listTasks();
for (const task of tasks) {
await this.taskService.enhanceTask(task.id, options);
}
} else {
await this.taskService.enhanceTask(options.taskId, options);
}
}
async handleSplitCommand(baseOptions: SplitTaskOptions): Promise<void> {
const options = this.applyConfigToOptions(baseOptions, 'split');
if (options.all) {
const tasks = await this.taskService.listTasks();
for (const task of tasks) {
await this.taskService.splitTask(task.id, options);
}
} else {
await this.taskService.splitTask(options.taskId, options);
}
}
async handlePlanCommand(baseOptions: PlanTaskOptions): Promise<void> {
const options = this.applyConfigToOptions(baseOptions, 'plan');
await this.taskService.planTask(options.id, options);
}
}TECHNICAL SPECIFICATIONS
#### Interface Design Patterns
- Optional Properties: All non-essential properties marked optional
- Type Safety: Union types for constrained values
- Inheritance: Base interfaces extended for reusability
- Composition: Multiple interface combination
- Consistency: Standardized naming conventions
#### Validation Rules
- Required Fields: Enforced at compile time
- Union Types: Limited to predefined values
- String Constraints: Comma-separated lists for tags
- Boolean Flags: Consistent true/false patterns
- AI Integration: Standardized AI configuration
#### Performance Considerations
- Object Creation: Minimal overhead
- Type Checking: Compile-time validation
- Memory Usage: Efficient property access
- Inheritance: Flat structure for performance
#### Extensibility Guidelines
- New Properties: Add optional properties to interfaces
- New Commands: Create specific option interfaces
- Backward Compatibility: Optional properties don't break existing code
- Type Guards: Add validation for new properties
Remember: Citizen, in the wasteland of command-line interfaces, well-defined option types are your compass. Every interface is a map through the desert of user input, and every type constraint is a wellspring of predictability. Without them, your commands become lost in the sands of ambiguity.