task-o-matic 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (159) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +552 -0
  3. package/dist/cli/bin.d.ts +3 -0
  4. package/dist/cli/bin.d.ts.map +1 -0
  5. package/dist/cli/bin.js +8 -0
  6. package/dist/cli/display/common.d.ts +5 -0
  7. package/dist/cli/display/common.d.ts.map +1 -0
  8. package/dist/cli/display/common.js +44 -0
  9. package/dist/cli/display/plan.d.ts +11 -0
  10. package/dist/cli/display/plan.d.ts.map +1 -0
  11. package/dist/cli/display/plan.js +42 -0
  12. package/dist/cli/display/progress.d.ts +11 -0
  13. package/dist/cli/display/progress.d.ts.map +1 -0
  14. package/dist/cli/display/progress.js +47 -0
  15. package/dist/cli/display/task.d.ts +18 -0
  16. package/dist/cli/display/task.d.ts.map +1 -0
  17. package/dist/cli/display/task.js +250 -0
  18. package/dist/commands/config.d.ts +3 -0
  19. package/dist/commands/config.d.ts.map +1 -0
  20. package/dist/commands/config.js +61 -0
  21. package/dist/commands/init.d.ts +4 -0
  22. package/dist/commands/init.d.ts.map +1 -0
  23. package/dist/commands/init.js +197 -0
  24. package/dist/commands/prd.d.ts +4 -0
  25. package/dist/commands/prd.d.ts.map +1 -0
  26. package/dist/commands/prd.js +131 -0
  27. package/dist/commands/prompt.d.ts +3 -0
  28. package/dist/commands/prompt.d.ts.map +1 -0
  29. package/dist/commands/prompt.js +192 -0
  30. package/dist/commands/tasks.d.ts +3 -0
  31. package/dist/commands/tasks.d.ts.map +1 -0
  32. package/dist/commands/tasks.js +599 -0
  33. package/dist/index.d.ts +18 -0
  34. package/dist/index.d.ts.map +1 -0
  35. package/dist/index.js +67 -0
  36. package/dist/lib/ai-service/ai-operations.d.ts +31 -0
  37. package/dist/lib/ai-service/ai-operations.d.ts.map +1 -0
  38. package/dist/lib/ai-service/ai-operations.js +648 -0
  39. package/dist/lib/ai-service/json-parser.d.ts +9 -0
  40. package/dist/lib/ai-service/json-parser.d.ts.map +1 -0
  41. package/dist/lib/ai-service/json-parser.js +37 -0
  42. package/dist/lib/ai-service/mcp-client.d.ts +9 -0
  43. package/dist/lib/ai-service/mcp-client.d.ts.map +1 -0
  44. package/dist/lib/ai-service/mcp-client.js +48 -0
  45. package/dist/lib/ai-service/model-provider.d.ts +8 -0
  46. package/dist/lib/ai-service/model-provider.d.ts.map +1 -0
  47. package/dist/lib/ai-service/model-provider.js +71 -0
  48. package/dist/lib/ai-service/research-tools.d.ts +4 -0
  49. package/dist/lib/ai-service/research-tools.d.ts.map +1 -0
  50. package/dist/lib/ai-service/research-tools.js +8 -0
  51. package/dist/lib/ai-service/retry-handler.d.ts +8 -0
  52. package/dist/lib/ai-service/retry-handler.d.ts.map +1 -0
  53. package/dist/lib/ai-service/retry-handler.js +62 -0
  54. package/dist/lib/better-t-stack-cli.d.ts +35 -0
  55. package/dist/lib/better-t-stack-cli.d.ts.map +1 -0
  56. package/dist/lib/better-t-stack-cli.js +118 -0
  57. package/dist/lib/config.d.ts +24 -0
  58. package/dist/lib/config.d.ts.map +1 -0
  59. package/dist/lib/config.js +160 -0
  60. package/dist/lib/context-builder.d.ts +53 -0
  61. package/dist/lib/context-builder.d.ts.map +1 -0
  62. package/dist/lib/context-builder.js +294 -0
  63. package/dist/lib/executors/executor-factory.d.ts +5 -0
  64. package/dist/lib/executors/executor-factory.d.ts.map +1 -0
  65. package/dist/lib/executors/executor-factory.js +21 -0
  66. package/dist/lib/executors/opencode-executor.d.ts +6 -0
  67. package/dist/lib/executors/opencode-executor.d.ts.map +1 -0
  68. package/dist/lib/executors/opencode-executor.js +46 -0
  69. package/dist/lib/index.d.ts +89 -0
  70. package/dist/lib/index.d.ts.map +1 -0
  71. package/dist/lib/index.js +134 -0
  72. package/dist/lib/prompt-builder.d.ts +50 -0
  73. package/dist/lib/prompt-builder.d.ts.map +1 -0
  74. package/dist/lib/prompt-builder.js +171 -0
  75. package/dist/lib/prompt-registry.d.ts +22 -0
  76. package/dist/lib/prompt-registry.d.ts.map +1 -0
  77. package/dist/lib/prompt-registry.js +201 -0
  78. package/dist/lib/storage.d.ts +60 -0
  79. package/dist/lib/storage.d.ts.map +1 -0
  80. package/dist/lib/storage.js +768 -0
  81. package/dist/lib/task-execution.d.ts +3 -0
  82. package/dist/lib/task-execution.d.ts.map +1 -0
  83. package/dist/lib/task-execution.js +130 -0
  84. package/dist/lib/validation.d.ts +4 -0
  85. package/dist/lib/validation.d.ts.map +1 -0
  86. package/dist/lib/validation.js +52 -0
  87. package/dist/mcp/prompts.d.ts +3 -0
  88. package/dist/mcp/prompts.d.ts.map +1 -0
  89. package/dist/mcp/prompts.js +7 -0
  90. package/dist/mcp/resources.d.ts +3 -0
  91. package/dist/mcp/resources.d.ts.map +1 -0
  92. package/dist/mcp/resources.js +7 -0
  93. package/dist/mcp/server.d.ts +3 -0
  94. package/dist/mcp/server.d.ts.map +1 -0
  95. package/dist/mcp/server.js +25 -0
  96. package/dist/mcp/tools.d.ts +3 -0
  97. package/dist/mcp/tools.d.ts.map +1 -0
  98. package/dist/mcp/tools.js +99 -0
  99. package/dist/prompts/documentation-detection.d.ts +2 -0
  100. package/dist/prompts/documentation-detection.d.ts.map +1 -0
  101. package/dist/prompts/documentation-detection.js +24 -0
  102. package/dist/prompts/index.d.ts +7 -0
  103. package/dist/prompts/index.d.ts.map +1 -0
  104. package/dist/prompts/index.js +22 -0
  105. package/dist/prompts/prd-parsing.d.ts +3 -0
  106. package/dist/prompts/prd-parsing.d.ts.map +1 -0
  107. package/dist/prompts/prd-parsing.js +172 -0
  108. package/dist/prompts/prd-rework.d.ts +3 -0
  109. package/dist/prompts/prd-rework.d.ts.map +1 -0
  110. package/dist/prompts/prd-rework.js +81 -0
  111. package/dist/prompts/task-breakdown.d.ts +3 -0
  112. package/dist/prompts/task-breakdown.d.ts.map +1 -0
  113. package/dist/prompts/task-breakdown.js +151 -0
  114. package/dist/prompts/task-enhancement.d.ts +3 -0
  115. package/dist/prompts/task-enhancement.d.ts.map +1 -0
  116. package/dist/prompts/task-enhancement.js +140 -0
  117. package/dist/prompts/task-planning.d.ts +3 -0
  118. package/dist/prompts/task-planning.d.ts.map +1 -0
  119. package/dist/prompts/task-planning.js +66 -0
  120. package/dist/services/prd.d.ts +32 -0
  121. package/dist/services/prd.d.ts.map +1 -0
  122. package/dist/services/prd.js +191 -0
  123. package/dist/services/tasks.d.ts +67 -0
  124. package/dist/services/tasks.d.ts.map +1 -0
  125. package/dist/services/tasks.js +596 -0
  126. package/dist/test/commands.test.d.ts +2 -0
  127. package/dist/test/commands.test.d.ts.map +1 -0
  128. package/dist/test/commands.test.js +74 -0
  129. package/dist/test/storage.test.d.ts +2 -0
  130. package/dist/test/storage.test.d.ts.map +1 -0
  131. package/dist/test/storage.test.js +207 -0
  132. package/dist/types/callbacks.d.ts +27 -0
  133. package/dist/types/callbacks.d.ts.map +1 -0
  134. package/dist/types/callbacks.js +2 -0
  135. package/dist/types/index.d.ts +252 -0
  136. package/dist/types/index.d.ts.map +1 -0
  137. package/dist/types/index.js +2 -0
  138. package/dist/types/mcp.d.ts +3 -0
  139. package/dist/types/mcp.d.ts.map +1 -0
  140. package/dist/types/mcp.js +3 -0
  141. package/dist/types/options.d.ts +94 -0
  142. package/dist/types/options.d.ts.map +1 -0
  143. package/dist/types/options.js +2 -0
  144. package/dist/types/results.d.ts +90 -0
  145. package/dist/types/results.d.ts.map +1 -0
  146. package/dist/types/results.js +2 -0
  147. package/dist/utils/ai-config-builder.d.ts +14 -0
  148. package/dist/utils/ai-config-builder.d.ts.map +1 -0
  149. package/dist/utils/ai-config-builder.js +22 -0
  150. package/dist/utils/ai-service-factory.d.ts +10 -0
  151. package/dist/utils/ai-service-factory.d.ts.map +1 -0
  152. package/dist/utils/ai-service-factory.js +52 -0
  153. package/dist/utils/stack-formatter.d.ts +11 -0
  154. package/dist/utils/stack-formatter.d.ts.map +1 -0
  155. package/dist/utils/stack-formatter.js +30 -0
  156. package/dist/utils/streaming-options.d.ts +10 -0
  157. package/dist/utils/streaming-options.d.ts.map +1 -0
  158. package/dist/utils/streaming-options.js +53 -0
  159. package/package.json +82 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,552 @@
1
+ # 🚀 task-o-matic
2
+
3
+ AI-powered task management for CLI, TUI, and web applications. Parse PRDs, enhance tasks with AI, and integrate task management into your applications using local file storage only. No backend connectivity required.
4
+
5
+ ## ✨ Features
6
+
7
+ - 🤖 **AI-Powered**: Parse PRDs and enhance tasks using multiple AI providers
8
+ - 📦 **Multi-Purpose Package**: Use as CLI tool, library, or MCP server
9
+ - 📁 **Project-Local Storage**: All data stored locally in `.task-o-matic/` directory
10
+ - 🎯 **Task Management**: Full CRUD operations with AI enhancement
11
+ - 📋 **PRD Processing**: Convert Product Requirements Documents into actionable tasks
12
+ - 🏗️ **Project Bootstrapping**: Better-T-Stack integration for new projects
13
+ - 🔧 **Multi-Provider AI**: Support for OpenAI, Anthropic, OpenRouter, and custom providers
14
+ - 📊 **Smart Breakdown**: AI-powered task decomposition into subtasks
15
+ - 🌊 **Real-time Streaming**: Watch AI responses generate live with streaming output
16
+ - 🏠 **Single-Project Focus**: Self-contained within each project directory
17
+ - 💻 **Framework-Agnostic**: Easily integrate into TUI, web apps, or any Node.js project
18
+
19
+ ## 📦 Installation
20
+
21
+ ### As a CLI Tool
22
+
23
+ ```bash
24
+ # Install globally
25
+ npm install -g task-o-matic
26
+
27
+ # Or use with npx
28
+ npx task-o-matic init
29
+ ```
30
+
31
+ ### As a Library (for TUI/Web Apps)
32
+
33
+ ```bash
34
+ # Install in your project
35
+ npm install task-o-matic
36
+ ```
37
+
38
+ ### For Development
39
+
40
+ ```bash
41
+ # Clone and install dependencies
42
+ git clone https://github.com/DimitriGilbert/task-o-matic.git
43
+ cd task-o-matic
44
+ npm install
45
+ npm run build
46
+ ```
47
+
48
+ ## 🏗️ Architecture & Mindset
49
+
50
+ ### Package Structure
51
+
52
+ ```
53
+ task-o-matic/
54
+ ├── dist/ # Compiled output (published)
55
+ │ ├── lib/ # Library entry point + core exports
56
+ │ ├── cli/ # CLI binary
57
+ │ ├── services/ # Business logic layer
58
+ │ ├── commands/ # CLI commands
59
+ │ ├── mcp/ # MCP server
60
+ │ └── types/ # TypeScript definitions
61
+ ├── src/
62
+ │ ├── lib/ # Core library (Storage, Config, AI, etc.)
63
+ │ │ └── index.ts # Main library exports
64
+ │ ├── services/ # TaskService, PRDService (framework-agnostic)
65
+ │ ├── cli/ # CLI-specific logic
66
+ │ │ └── bin.ts # CLI binary entry point
67
+ │ ├── commands/ # Commander.js command implementations
68
+ │ ├── mcp/ # MCP server implementation
69
+ │ ├── prompts/ # AI prompt templates
70
+ │ ├── types/ # TypeScript type definitions
71
+ │ └── utils/ # Shared utilities
72
+ └── docs/ # Documentation
73
+ ```
74
+
75
+ ### Core Components
76
+
77
+ - **Service Layer** (`TaskService`, `PRDService`): Framework-agnostic business logic
78
+ - **AI Service**: Uses Vercel AI SDK for multi-provider support
79
+ - **Local Storage**: JSON-based file storage in `.task-o-matic/` directory
80
+ - **Configuration**: Project-local config with AI provider settings
81
+ - **Prompt Templates**: Structured AI prompts for consistent results
82
+
83
+ ### Design Philosophy
84
+
85
+ - **Separation of Concerns**: CLI, Services, and Core are cleanly separated
86
+ - **Framework-Agnostic**: Services can be used in any environment (CLI, TUI, web)
87
+ - **Project-Local**: Each project manages its own tasks and configuration
88
+ - **AI-Enhanced**: Use AI to improve clarity and break down complexity
89
+ - **Developer-Friendly**: Simple, intuitive APIs with helpful output
90
+ - **Self-Contained**: No external dependencies, everything works offline
91
+
92
+ ## 🚀 Quick Start
93
+
94
+ ### Library Usage (TUI/Web Apps)
95
+
96
+ #### Installation
97
+
98
+ ```bash
99
+ npm install task-o-matic
100
+ ```
101
+
102
+ #### Basic Example
103
+
104
+ ```typescript
105
+ import { TaskService, PRDService, type Task, type AIConfig } from 'task-o-matic';
106
+
107
+ // Initialize the service
108
+ const taskService = new TaskService();
109
+
110
+ // Create a task with AI enhancement
111
+ const result = await taskService.createTask({
112
+ title: 'Implement user authentication',
113
+ content: 'Add login and signup functionality',
114
+ aiEnhance: true,
115
+ aiOptions: {
116
+ provider: 'anthropic',
117
+ model: 'claude-3-5-sonnet',
118
+ apiKey: process.env.ANTHROPIC_API_KEY
119
+ },
120
+ callbacks: {
121
+ onProgress: (event) => {
122
+ console.log(`Progress: ${event.message}`);
123
+ }
124
+ }
125
+ });
126
+
127
+ console.log('Task created:', result.task);
128
+ ```
129
+
130
+ #### TUI Integration Example
131
+
132
+ ```typescript
133
+ import { TaskService } from 'task-o-matic';
134
+ import type { ProgressCallback } from 'task-o-matic';
135
+
136
+ const taskService = new TaskService();
137
+
138
+ // Progress callback for TUI updates
139
+ const progressCallback: ProgressCallback = {
140
+ onProgress: (event) => {
141
+ // Update your TUI with progress
142
+ tuiStatusBar.update(event.message);
143
+ }
144
+ };
145
+
146
+ // Create task with streaming
147
+ const result = await taskService.createTask({
148
+ title: 'Add payment integration',
149
+ aiEnhance: true,
150
+ streamingOptions: {
151
+ enabled: true,
152
+ onChunk: (chunk) => {
153
+ // Update TUI in real-time
154
+ tuiTextArea.append(chunk);
155
+ },
156
+ onFinish: ({ text }) => {
157
+ tuiStatusBar.success('Task enhanced!');
158
+ }
159
+ },
160
+ callbacks: progressCallback
161
+ });
162
+ ```
163
+
164
+ #### PRD Parsing Example
165
+
166
+ ```typescript
167
+ import { PRDService } from 'task-o-matic';
168
+
169
+ const prdService = new PRDService();
170
+
171
+ const result = await prdService.parsePRD({
172
+ file: './requirements.md',
173
+ workingDirectory: process.cwd(),
174
+ aiOptions: {
175
+ provider: 'openrouter',
176
+ model: 'anthropic/claude-3.5-sonnet',
177
+ apiKey: process.env.OPENROUTER_API_KEY
178
+ },
179
+ callbacks: {
180
+ onProgress: (event) => {
181
+ console.log(event.message);
182
+ }
183
+ }
184
+ });
185
+
186
+ console.log(`Created ${result.tasks.length} tasks from PRD`);
187
+ result.tasks.forEach(task => {
188
+ console.log(`- ${task.title}`);
189
+ });
190
+ ```
191
+
192
+ #### Using Utility Factories
193
+
194
+ ```typescript
195
+ import {
196
+ getStorage,
197
+ getAIOperations,
198
+ buildAIConfig
199
+ } from 'task-o-matic';
200
+
201
+ // Get singleton instances
202
+ const storage = getStorage();
203
+ const aiOps = getAIOperations();
204
+
205
+ // Build AI configuration
206
+ const aiConfig = buildAIConfig({
207
+ provider: 'openai',
208
+ model: 'gpt-4',
209
+ apiKey: process.env.OPENAI_API_KEY
210
+ });
211
+
212
+ // Use storage directly
213
+ const allTasks = await storage.getAllTasks();
214
+ ```
215
+
216
+ #### TypeScript Support
217
+
218
+ The package includes full TypeScript type definitions:
219
+
220
+ ```typescript
221
+ import type {
222
+ Task,
223
+ AIConfig,
224
+ StreamingOptions,
225
+ CreateTaskOptions,
226
+ PRDParseResult,
227
+ TaskAIMetadata
228
+ } from 'task-o-matic';
229
+ ```
230
+
231
+ ### CLI Usage
232
+
233
+ #### 1. Initialize Your Project
234
+
235
+ ```bash
236
+ # Navigate to your project directory
237
+ cd /path/to/your/project
238
+
239
+ # Initialize task-o-matic (basic setup)
240
+ task-o-matic init init
241
+
242
+ # Initialize task-o-matic + bootstrap Better-T-Stack project (recommended)
243
+ task-o-matic init init --project-name my-app
244
+
245
+ # Initialize with custom AI settings + bootstrap
246
+ task-o-matic init init --project-name my-app --ai-provider openrouter --ai-key your-key --frontend next --backend hono
247
+ ```
248
+
249
+ This creates a `.task-o-matic/` directory with:
250
+
251
+ - `config.json` - AI configuration
252
+ - `tasks/` - Task JSON files
253
+ - `prd/` - PRD versions and logs
254
+ - `logs/` - Operation logs
255
+ - `bts-config.json` - Better-T-Stack configuration (if bootstrapped)
256
+
257
+ ### 3. Configure AI Provider
258
+
259
+ ```bash
260
+ # Option 1: Configure during init (recommended)
261
+ task-o-matic init init --project-name my-app --ai-provider openrouter --ai-model anthropic/claude-3.5-sonnet --ai-key your-key
262
+
263
+ # Option 2: Configure after init
264
+ task-o-matic config set-ai-provider openrouter anthropic/claude-3.5-sonnet
265
+
266
+ # Option 3: Use environment variables
267
+ export OPENROUTER_API_KEY="your-key-here"
268
+ export ANTHROPIC_API_KEY="your-key-here"
269
+ export OPENAI_API_KEY="your-key-here"
270
+ ```
271
+
272
+ ### 4. Bootstrap Your Project (if not done during init)
273
+
274
+ ```bash
275
+ # Bootstrap with defaults (Next.js + Hono + SQLite + Auth)
276
+ task-o-matic init bootstrap my-app
277
+
278
+ # Bootstrap with custom options
279
+ task-o-matic init bootstrap my-app --frontend next --backend hono --database postgres --addons pwa biome
280
+ ```
281
+
282
+ ### 6. Create Your First Tasks
283
+
284
+ ```bash
285
+ # Create a task with AI enhancement
286
+ task-o-matic tasks create --title "Implement user authentication" --ai-enhance
287
+
288
+ # Create a task with real-time AI streaming
289
+ task-o-matic tasks create --title "Implement user authentication" --ai-enhance --stream
290
+
291
+ # Parse a PRD into tasks
292
+ task-o-matic prd parse --file my-prd.md
293
+
294
+ # Parse PRD with real-time AI streaming
295
+ task-o-matic prd parse --file my-prd.md --stream
296
+
297
+ # List all tasks
298
+ task-o-matic tasks list
299
+ ```
300
+
301
+ ## 📚 Documentation
302
+
303
+ - [Configuration](docs/configuration.md) - AI providers and settings
304
+ - [Task Management](docs/tasks.md) - Full task lifecycle with AI features
305
+ - [PRD Processing](docs/prd.md) - Parse and rework Product Requirements Documents
306
+ - [AI Integration](docs/ai-integration.md) - AI providers and prompt engineering
307
+ - [Project Initialization](docs/projects.md) - Project setup and bootstrapping
308
+ - [Streaming Output](docs/streaming.md) - Real-time AI streaming capabilities
309
+
310
+ ## 🎯 Common Workflows
311
+
312
+ ### Workflow 1: From PRD to Tasks
313
+
314
+ ```bash
315
+ # 1. Initialize project (if not done)
316
+ task-o-matic init init
317
+
318
+ # 2. Configure AI provider
319
+ task-o-matic config set-ai-provider anthropic claude-3-5-sonnet
320
+
321
+ # 3. Parse PRD with streaming
322
+ task-o-matic prd parse --file requirements.md --stream
323
+
324
+ # 4. Review and enhance tasks
325
+ task-o-matic tasks list
326
+ task-o-matic tasks split --task-id <complex-task-id>
327
+ ```
328
+
329
+ ### Workflow 2: Task Enhancement
330
+
331
+ ```bash
332
+ # 1. Create basic task
333
+ task-o-matic tasks create --title "Add payment system"
334
+
335
+ # 2. Enhance with AI (with streaming)
336
+ task-o-matic tasks create --title "Add payment system" --ai-enhance --stream
337
+
338
+ # 3. Break down into subtasks
339
+ task-o-matic tasks split --task-id <task-id>
340
+ ```
341
+
342
+ ### Workflow 3: Project Bootstrapping
343
+
344
+ ```bash
345
+ # Option 1: One-step setup (recommended)
346
+ task-o-matic init init --project-name my-app --ai-provider openrouter --ai-key your-key
347
+
348
+ # Option 2: Two-step setup
349
+ task-o-matic init init --no-bootstrap
350
+ task-o-matic init bootstrap my-app --frontend next --backend hono
351
+
352
+ # Option 3: Manual setup
353
+ task-o-matic init init
354
+ task-o-matic config set-ai-provider openrouter anthropic/claude-3.5-sonnet
355
+ task-o-matic init bootstrap my-app
356
+
357
+ # Start managing tasks
358
+ task-o-matic tasks create --title "Set up development environment" --ai-enhance --stream
359
+ ```
360
+
361
+ ## 🔧 Environment Variables
362
+
363
+ ```bash
364
+ # AI Provider API Keys
365
+ OPENAI_API_KEY=your_openai_key
366
+ ANTHROPIC_API_KEY=your_anthropic_key
367
+ OPENROUTER_API_KEY=your_openrouter_key
368
+ CUSTOM_API_KEY=your_custom_key
369
+ CUSTOM_API_URL=https://api.custom.com/v1
370
+
371
+ # Default AI Configuration
372
+ AI_PROVIDER=openrouter
373
+ AI_MODEL=anthropic/claude-3.5-sonnet
374
+ AI_MAX_TOKENS=4000
375
+ AI_TEMPERATURE=0.7
376
+ ```
377
+
378
+ ## 🤖 AI Providers
379
+
380
+ ### Supported Providers
381
+
382
+ - **OpenAI**: GPT models with full feature support
383
+ - **Anthropic**: Claude models with enhanced reasoning
384
+ - **OpenRouter**: Access to multiple models through one API
385
+ - **Custom**: Any OpenAI-compatible API endpoint
386
+
387
+ ### Model Recommendations
388
+
389
+ - **PRD Parsing**: `claude-3.5-sonnet` or `gpt-4`
390
+ - **Task Enhancement**: `claude-3-haiku` or `gpt-3.5-turbo`
391
+ - **Task Breakdown**: `claude-3.5-sonnet` for complex tasks
392
+
393
+ ## 📁 Storage Structure
394
+
395
+ ```
396
+ your-project/
397
+ ├── .task-o-matic/
398
+ │ ├── config.json # AI configuration
399
+ │ ├── bts-config.json # Better-T-Stack configuration (if bootstrapped)
400
+ │ ├── tasks/ # Task JSON files
401
+ │ │ ├── {task-id}.json
402
+ │ │ └── ...
403
+ │ ├── prd/ # PRD versions and logs
404
+ │ │ ├── parsed-prd.json
405
+ │ │ └── ...
406
+ │ └── logs/ # Operation logs
407
+ │ └── ...
408
+ └── your-project-files...
409
+ ```
410
+
411
+ ## 🛠️ Development
412
+
413
+ ### Building from Source
414
+
415
+ ```bash
416
+ # Clone and install
417
+ git clone https://github.com/DimitriGilbert/task-o-matic.git
418
+ cd task-o-matic
419
+ npm install
420
+
421
+ # Build everything (library + CLI + MCP server)
422
+ npm run build
423
+
424
+ # Build and watch for changes
425
+ npm run build:watch
426
+
427
+ # Clean build artifacts
428
+ npm run clean
429
+ ```
430
+
431
+ ### Development Mode
432
+
433
+ ```bash
434
+ # Run the CLI in development mode
435
+ npm run dev
436
+
437
+ # Run the MCP server in development
438
+ npm run dev:mcp
439
+
440
+ # Type checking (without compilation)
441
+ npm run check-types
442
+
443
+ # Run tests
444
+ npm run test
445
+ ```
446
+
447
+ ### Testing Your Changes
448
+
449
+ ```bash
450
+ # Link for local testing
451
+ npm link
452
+
453
+ # Use the linked package
454
+ task-o-matic --version
455
+
456
+ # In another project
457
+ cd /path/to/test-project
458
+ npm link task-o-matic
459
+
460
+ # Test library import
461
+ node -e "const {TaskService} = require('task-o-matic'); console.log('Works!');"
462
+ ```
463
+
464
+ ### Package Structure
465
+
466
+ The package is structured for both CLI and library use:
467
+
468
+ ```json
469
+ {
470
+ "main": "./dist/lib/index.js", // CommonJS library entry
471
+ "types": "./dist/lib/index.d.ts", // TypeScript definitions
472
+ "bin": {
473
+ "task-o-matic": "./dist/cli/bin.js", // CLI binary
474
+ "task-o-matic-mcp": "./dist/mcp/server.js" // MCP server binary
475
+ },
476
+ "exports": {
477
+ ".": "./dist/lib/index.js", // Main library export
478
+ "./types": "./dist/types/index.js" // Type-only exports
479
+ }
480
+ }
481
+ ```
482
+
483
+ ## 🤖 MCP Server Integration
484
+
485
+ `task-o-matic` includes a built-in Model Context Protocol (MCP) server that exposes its project management capabilities directly to compatible AI models and development tools.
486
+
487
+ ### Running the MCP Server
488
+
489
+ You can run the server in development mode or as a production build.
490
+
491
+ **Development:**
492
+
493
+ ```bash
494
+ # This will start the server using tsx for live reloading
495
+ npm run dev:mcp
496
+ ```
497
+
498
+ **Production:**
499
+ First, build the server, then run the executable from your project root.
500
+
501
+ ```bash
502
+ # 1. Build the server
503
+ npm run build:mcp
504
+
505
+ # 2. Run the server
506
+ # The 'projpoc-mcp' command is now available via npx
507
+ npx projpoc-mcp
508
+ ```
509
+
510
+ ### Connecting a Client
511
+
512
+ You can connect any MCP-compatible client. For example, to connect an AI model, you would configure its tool server settings to use the `projpoc-mcp` command.
513
+
514
+ **Example Client Configuration:**
515
+
516
+ ```json
517
+ {
518
+ "mcpServers": {
519
+ "task-o-matic": {
520
+ "command": "npx",
521
+ "args": ["projpoc-mcp"]
522
+ }
523
+ }
524
+ }
525
+ ```
526
+
527
+ ### Exposed Tools
528
+
529
+ When running, the server provides the following tools:
530
+
531
+ - **`get_project_info`**: Retrieves information about the current project, including its path and AI configuration.
532
+ - **`list_tasks`**: Lists all tasks for the project.
533
+ - `filterByStatus` (optional): Filter by `todo`, `in-progress`, or `completed`.
534
+ - **`create_task`**: Creates a new task.
535
+ - `taskTitle` (required): The title of the task.
536
+ - `taskContent` (optional): The description of the task.
537
+
538
+ ## 📄 License
539
+
540
+ MIT License - see LICENSE file for details.
541
+
542
+ ## 🤝 Contributing
543
+
544
+ 1. Fork the repository
545
+ 2. Create a feature branch
546
+ 3. Make your changes
547
+ 4. Add tests if applicable
548
+ 5. Submit a pull request
549
+
550
+ ---
551
+
552
+ **Built with ❤️ using Vercel AI SDK and modern TypeScript**
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=bin.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":""}
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ Object.defineProperty(exports, "__esModule", { value: true });
4
+ const index_1 = require("../index");
5
+ (0, index_1.runCLI)().catch((error) => {
6
+ console.error(error);
7
+ process.exit(1);
8
+ });
@@ -0,0 +1,5 @@
1
+ import { DocumentationDetection } from "../../types";
2
+ export declare function displayEnhancementResult(streamEnabled: boolean): void;
3
+ export declare function displayDocumentationAnalysis(analysis: DocumentationDetection): void;
4
+ export declare function displayResearchSummary(documentation: any): void;
5
+ //# sourceMappingURL=common.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/cli/display/common.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,OAAO,GAAG,IAAI,CAIrE;AAED,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,sBAAsB,GAC/B,IAAI,CAgBN;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,GAAG,GAAG,IAAI,CAe/D"}
@@ -0,0 +1,44 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.displayEnhancementResult = displayEnhancementResult;
7
+ exports.displayDocumentationAnalysis = displayDocumentationAnalysis;
8
+ exports.displayResearchSummary = displayResearchSummary;
9
+ const chalk_1 = __importDefault(require("chalk"));
10
+ function displayEnhancementResult(streamEnabled) {
11
+ if (!streamEnabled) {
12
+ console.log(chalk_1.default.green("✓ Task enhanced with Context7 documentation"));
13
+ }
14
+ }
15
+ function displayDocumentationAnalysis(analysis) {
16
+ console.log(chalk_1.default.cyan(`
17
+ Documentation analysis complete:`));
18
+ if (analysis.libraries.length > 0) {
19
+ console.log(chalk_1.default.blue(`Libraries identified:`));
20
+ analysis.libraries.forEach((lib) => {
21
+ console.log(` • ${lib.name} (${lib.context7Id})`);
22
+ console.log(` Search Query: "${lib.searchQuery}"`);
23
+ console.log(` Reason: ${lib.reason}`);
24
+ });
25
+ console.log(chalk_1.default.green(`✓ Documentation analysis saved to task`));
26
+ }
27
+ else {
28
+ console.log(chalk_1.default.yellow("No specific documentation needs identified."));
29
+ }
30
+ }
31
+ function displayResearchSummary(documentation) {
32
+ if (documentation?.research) {
33
+ console.log(chalk_1.default.cyan(`
34
+ 📚 Research Summary:`));
35
+ Object.entries(documentation.research).forEach(([lib, entries]) => {
36
+ console.log(` • ${lib}: ${entries.length} queries cached`);
37
+ entries.forEach((entry, index) => {
38
+ console.log(` ${index + 1}. Query: "${entry.query}"`);
39
+ console.log(` Cache: ${entry.cache}`);
40
+ console.log(` Doc: ${entry.doc}`);
41
+ });
42
+ });
43
+ }
44
+ }
@@ -0,0 +1,11 @@
1
+ export declare function displayPlanCreation(taskId: string, taskTitle: string): void;
2
+ export declare function displayPlanView(taskTitle: string, taskId: string, plan: string, createdAt: number, updatedAt: number): void;
3
+ export declare function displayPlanList(plans: Array<{
4
+ taskId: string;
5
+ plan: string;
6
+ createdAt: number;
7
+ updatedAt: number;
8
+ taskTitle?: string;
9
+ }>): void;
10
+ export declare function displayPlanDeletion(taskId: string, success: boolean): void;
11
+ //# sourceMappingURL=plan.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/cli/display/plan.ts"],"names":[],"mappings":"AAGA,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAM3E;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,IAAI,CAON;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,GACD,IAAI,CAyBN;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAM1E"}
@@ -0,0 +1,42 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.displayPlanCreation = displayPlanCreation;
7
+ exports.displayPlanView = displayPlanView;
8
+ exports.displayPlanList = displayPlanList;
9
+ exports.displayPlanDeletion = displayPlanDeletion;
10
+ const chalk_1 = __importDefault(require("chalk"));
11
+ function displayPlanCreation(taskId, taskTitle) {
12
+ console.log(chalk_1.default.green(`\n✓ Implementation plan created and saved for: ${taskTitle} (${taskId})`));
13
+ }
14
+ function displayPlanView(taskTitle, taskId, plan, createdAt, updatedAt) {
15
+ console.log(chalk_1.default.green(`\n📋 Implementation Plan for ${taskTitle} (${taskId}):`));
16
+ console.log(chalk_1.default.gray(`Created: ${new Date(createdAt).toLocaleString()}`));
17
+ console.log(chalk_1.default.gray(`Updated: ${new Date(updatedAt).toLocaleString()}`));
18
+ console.log(chalk_1.default.cyan(`\n${plan}`));
19
+ }
20
+ function displayPlanList(plans) {
21
+ if (plans.length === 0) {
22
+ console.log(chalk_1.default.yellow("No plans found."));
23
+ return;
24
+ }
25
+ console.log(chalk_1.default.blue(`\n📋 Available Plans (${plans.length}):`));
26
+ for (const plan of plans) {
27
+ console.log(chalk_1.default.white(`\n• ${plan.taskId}: ${plan.taskTitle || "Unknown Task"}`));
28
+ console.log(chalk_1.default.gray(` Created: ${new Date(plan.createdAt).toLocaleDateString()}`));
29
+ console.log(chalk_1.default.gray(` Updated: ${new Date(plan.updatedAt).toLocaleDateString()}`));
30
+ // Show first 100 characters of plan as preview
31
+ const preview = plan.plan.substring(0, 100).replace(/\n/g, " ");
32
+ console.log(chalk_1.default.cyan(` Preview: ${preview}${plan.plan.length > 100 ? "..." : ""}`));
33
+ }
34
+ }
35
+ function displayPlanDeletion(taskId, success) {
36
+ if (success) {
37
+ console.log(chalk_1.default.green(`\n✓ Deleted plan for task: ${taskId}`));
38
+ }
39
+ else {
40
+ console.log(chalk_1.default.yellow(`\n⚠️ No plan found for task: ${taskId}`));
41
+ }
42
+ }