feat: implement api update-task (#1214)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

.changeset/config.json

@@ -8,10 +8,11 @@
   ],
   "commit": false,
   "fixed": [],
-  "linked": [],
+  "linked": [
+    ["task-master-ai", "@tm/cli", "@tm/core"]
+  ],
   "access": "public",
   "baseBranch": "main",
-  "updateInternalDependencies": "patch",
   "ignore": [
     "docs"
   ]

.changeset/crazy-meals-hope.md

@@ -1,27 +0,0 @@
----
-"task-master-ai": minor
----
-
-Add cross-tag task movement functionality for organizing tasks across different contexts.
-
-This feature enables moving tasks between different tags (contexts) in your project, making it easier to organize work across different branches, environments, or project phases.
-
-## CLI Usage Examples
-
-Move a single task from one tag to another:
-```bash
-# Move task 5 from backlog tag to in-progress tag
-task-master move --from=5 --from-tag=backlog --to-tag=feature-1
-
-# Move task with its dependencies
-task-master move --from=5 --from-tag=backlog --to-tag=feature-2 --with-dependencies
-
-# Move task without checking dependencies
-task-master move --from=5 --from-tag=backlog --to-tag=bug-3 --ignore-dependencies
-```
-
-Move multiple tasks at once:
-```bash
-# Move multiple tasks between tags
-task-master move --from=5,6,7 --from-tag=backlog --to-tag=bug-4 --with-dependencies
-```

.changeset/curly-poets-move.md

@@ -1,6 +0,0 @@
----
-"extension": minor
-"task-master-ai": minor
----
-
-"Add Kilo Code profile integration with custom modes and MCP configuration"

.changeset/cute-files-pay.md

@@ -1,12 +0,0 @@
----
-"task-master-ai": minor
----
-
-Add compact mode --compact / -c flag to the `tm list` CLI command
-
-- outputs tasks in a minimal, git-style one-line format. This reduces verbose output from ~30+ lines of dashboards and tables to just 1 line per task, making it much easier to quickly scan available tasks.
-  - Git-style format: ID STATUS TITLE (PRIORITY) → DEPS
-  - Color-coded status, priority, and dependencies
-  - Smart title truncation and dependency abbreviation
-  - Subtask support with indentation
-  - Full backward compatibility with existing list options

.changeset/cute-files-read.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": patch
----
-
-Update Cursor one-click install link to new URL format

.changeset/floppy-starts-find.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": minor
----
-
-Add CLI & MCP progress tracking for parse-prd command.

.changeset/light-crabs-warn.md

@@ -1,5 +0,0 @@
----
-"extension": minor
----
-
-Display current task ID on task details page

.changeset/moody-oranges-slide.md

@@ -0,0 +1,5 @@
+---
+"task-master-ai": minor
+---
+
+Test out the RC

.changeset/odd-otters-tan.md

@@ -0,0 +1,5 @@
+---
+"@tm/cli": minor
+---
+
+testing this stuff out to see how the release candidate works with monorepo

.changeset/rude-moments-search.md

@@ -1,7 +0,0 @@
----
-"task-master-ai": patch
----
-
-Fix `add-tag --from-branch` command error where `projectRoot` was not properly referenced
-
-The command was failing with "projectRoot is not defined" error because the code was directly referencing `projectRoot` instead of `context.projectRoot` in the git repository checks. This fix corrects the variable references to use the proper context object.

.changeset/slow-readers-deny.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": minor
----
-
-Add support for ollama `gpt-oss:20b` and `gpt-oss:120b`

.changeset/wet-seas-float.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": minor
----
-
-Remove `clear` Taskmaster claude code commands since they were too close to the claude-code clear command

.changeset/wild-ears-look.md

@@ -0,0 +1,5 @@
+---
+"extension": minor
+---
+
+Added a Start Build button to the VSCODE Task Properties Right Panel

.claude/commands/dedupe.md

@@ -33,6 +33,6 @@ This issue will be automatically closed as a duplicate in 3 days.
 - If your issue is a duplicate, please close it and 👍 the existing issue instead
 - To prevent auto-closure, add a comment or 👎 this comment
 
-🤖 Generated with [Claude Code](https://claude.ai/code)
+🤖 Generated with \[Task Master Bot\]
 
 ---

.github/workflows/ci.yml

@@ -9,70 +9,121 @@ on:
     branches:
       - main
       - next
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
 
 permissions:
   contents: read
 
+env:
+  DO_NOT_TRACK: 1
+  NODE_ENV: development
+
 jobs:
-  setup:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: 'npm'
-
-      - name: Install Dependencies
-        id: install
-        run: npm ci
-        timeout-minutes: 2
-
-      - name: Cache node_modules
-        uses: actions/cache@v4
-        with:
-          path: node_modules
-          key: ${{ runner.os }}-node-modules-${{ hashFiles('**/package-lock.json') }}
-
+  # Fast checks that can run in parallel
   format-check:
-    needs: setup
+    name: Format Check
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
 
       - uses: actions/setup-node@v4
         with:
           node-version: 20
+          cache: "npm"
 
-      - name: Restore node_modules
-        uses: actions/cache@v4
-        with:
-          path: node_modules
-          key: ${{ runner.os }}-node-modules-${{ hashFiles('**/package-lock.json') }}
+      - name: Install dependencies
+        run: npm install --frozen-lockfile --prefer-offline
+        timeout-minutes: 5
 
       - name: Format Check
         run: npm run format-check
         env:
           FORCE_COLOR: 1
 
-  test:
-    needs: setup
+  typecheck:
+    name: Typecheck
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
 
       - uses: actions/setup-node@v4
         with:
           node-version: 20
+          cache: "npm"
 
-      - name: Restore node_modules
-        uses: actions/cache@v4
+      - name: Install dependencies
+        run: npm install --frozen-lockfile --prefer-offline
+        timeout-minutes: 5
+
+      - name: Typecheck
+        run: npm run turbo:typecheck
+        env:
+          FORCE_COLOR: 1
+
+  # Build job to ensure everything compiles
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
         with:
-          path: node_modules
-          key: ${{ runner.os }}-node-modules-${{ hashFiles('**/package-lock.json') }}
+          fetch-depth: 2
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm install --frozen-lockfile --prefer-offline
+        timeout-minutes: 5
+
+      - name: Build
+        run: npm run turbo:build
+        env:
+          NODE_ENV: production
+          FORCE_COLOR: 1
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-artifacts
+          path: dist/
+          retention-days: 1
+
+  test:
+    name: Test
+    timeout-minutes: 15
+    runs-on: ubuntu-latest
+    needs: [format-check, typecheck, build]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm install --frozen-lockfile --prefer-offline
+        timeout-minutes: 5
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: build-artifacts
+          path: dist/
 
       - name: Run Tests
         run: |
@@ -81,7 +132,6 @@ jobs:
           NODE_ENV: test
           CI: true
           FORCE_COLOR: 1
-        timeout-minutes: 10
 
       - name: Upload Test Results
         if: always()

.github/workflows/claude-docs-trigger.yml

@@ -0,0 +1,57 @@
+name: Trigger Claude Documentation Update
+
+on:
+  push:
+    branches:
+      - next
+    paths-ignore:
+      - "apps/docs/**"
+      - "*.md"
+      - ".github/workflows/**"
+
+jobs:
+  trigger-docs-update:
+    # Only run if changes were merged (not direct pushes from bots)
+    if: github.actor != 'github-actions[bot]' && github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2 # Need previous commit for comparison
+
+      - name: Get changed files
+        id: changed-files
+        run: |
+          echo "Changed files in this push:"
+          git diff --name-only HEAD^ HEAD | tee changed_files.txt
+
+          # Store changed files for Claude to analyze (escaped for JSON)
+          CHANGED_FILES=$(git diff --name-only HEAD^ HEAD | jq -Rs .)
+          echo "changed_files=$CHANGED_FILES" >> $GITHUB_OUTPUT
+
+          # Get the commit message (escaped for JSON)
+          COMMIT_MSG=$(git log -1 --pretty=%B | jq -Rs .)
+          echo "commit_message=$COMMIT_MSG" >> $GITHUB_OUTPUT
+
+          # Get diff for documentation context (escaped for JSON)
+          COMMIT_DIFF=$(git diff HEAD^ HEAD --stat | jq -Rs .)
+          echo "commit_diff=$COMMIT_DIFF" >> $GITHUB_OUTPUT
+
+          # Get commit SHA
+          echo "commit_sha=${{ github.sha }}" >> $GITHUB_OUTPUT
+
+      - name: Trigger Claude workflow
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Trigger the Claude docs updater workflow with the change information
+          gh workflow run claude-docs-updater.yml \
+            --ref next \
+            -f commit_sha="${{ steps.changed-files.outputs.commit_sha }}" \
+            -f commit_message=${{ steps.changed-files.outputs.commit_message }} \
+            -f changed_files=${{ steps.changed-files.outputs.changed_files }} \
+            -f commit_diff=${{ steps.changed-files.outputs.commit_diff }}

.github/workflows/claude-docs-updater.yml

@@ -1,50 +1,38 @@
 name: Claude Documentation Updater
 
 on:
-  push:
-    branches:
-      - next
-    paths-ignore:
-      - 'apps/docs/**'
-      - '*.md'
-      - '.github/workflows/**'
+  workflow_dispatch:
+    inputs:
+      commit_sha:
+        description: 'The commit SHA that triggered this update'
+        required: true
+        type: string
+      commit_message:
+        description: 'The commit message'
+        required: true
+        type: string
+      changed_files:
+        description: 'List of changed files'
+        required: true
+        type: string
+      commit_diff:
+        description: 'Diff summary of changes'
+        required: true
+        type: string
 
 jobs:
   update-docs:
-    # Only run if changes were merged (not direct pushes from bots)
-    if: github.event.pusher.name != 'github-actions[bot]' && github.event.pusher.name != 'dependabot[bot]'
     runs-on: ubuntu-latest
     permissions:
       contents: write
       pull-requests: write
       issues: write
-      id-token: write
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
-          fetch-depth: 2  # Need previous commit for comparison
-
-      - name: Get changed files
-        id: changed-files
-        run: |
-          echo "Changed files in this push:"
-          git diff --name-only HEAD^ HEAD | tee changed_files.txt
-          
-          # Store changed files for Claude to analyze
-          echo "changed_files<<EOF" >> $GITHUB_OUTPUT
-          git diff --name-only HEAD^ HEAD >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
-          
-          # Get the commit message and changes summary
-          echo "commit_message<<EOF" >> $GITHUB_OUTPUT
-          git log -1 --pretty=%B >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
-          
-          # Get diff for documentation context
-          echo "commit_diff<<EOF" >> $GITHUB_OUTPUT
-          git diff HEAD^ HEAD --stat >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
+          ref: next
+          fetch-depth: 0 # Need full history to checkout specific commit
 
       - name: Create docs update branch
         id: create-branch
@@ -58,23 +46,26 @@ jobs:
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           timeout_minutes: "30"
-          mode: "auto"
+          mode: "agent"
+          github_token: ${{ secrets.GITHUB_TOKEN }}
           experimental_allowed_domains: |
             .anthropic.com
             .github.com
             api.github.com
             .githubusercontent.com
             registry.npmjs.org
-          prompt: |
+            .task-master.dev
+          base_branch: "next"
+          direct_prompt: |
             You are a documentation specialist. Analyze the recent changes pushed to the 'next' branch and update the documentation accordingly.
 
             Recent changes:
-            - Commit: ${{ steps.changed-files.outputs.commit_message }}
+            - Commit: ${{ inputs.commit_message }}
             - Changed files:
-            ${{ steps.changed-files.outputs.changed_files }}
+            ${{ inputs.changed_files }}
 
             - Changes summary:
-            ${{ steps.changed-files.outputs.commit_diff }}
+            ${{ inputs.commit_diff }}
 
             Your task:
             1. Analyze the changes to understand what functionality was added, modified, or removed
@@ -111,7 +102,7 @@ jobs:
 
             This PR was automatically generated to update documentation based on recent changes.
             
-            Original commit: ${{ steps.changed-files.outputs.commit_message }}
+            Original commit: ${{ inputs.commit_message }}
             
             Co-authored-by: Claude <claude-assistant@anthropic.com>"
           fi
@@ -131,12 +122,12 @@ jobs:
             This PR automatically updates documentation based on recent changes merged to the \`next\` branch.
 
             ### Original Changes
-            **Commit:** ${{ github.sha }}
-            **Message:** ${{ steps.changed-files.outputs.commit_message }}
+            **Commit:** ${{ inputs.commit_sha }}
+            **Message:** ${{ inputs.commit_message }}
             
             ### Changed Files in Original Commit
             \`\`\`
-            ${{ steps.changed-files.outputs.changed_files }}
+            ${{ inputs.changed_files }}
             \`\`\`
 
             ### Documentation Updates

.github/workflows/pre-release.yml

@@ -65,6 +65,17 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
+      - name: Run format
+        run: npm run format
+        env:
+          FORCE_COLOR: 1
+
+      - name: Build packages
+        run: npm run turbo:build
+        env:
+          NODE_ENV: production
+          FORCE_COLOR: 1
+
       - name: Create Release Candidate Pull Request or Publish Release Candidate to npm
         uses: changesets/action@v1
         with:

.github/workflows/release.yml

@@ -41,6 +41,12 @@ jobs:
       - name: Check pre-release mode
         run: node ./.github/scripts/check-pre-release-mode.mjs "main"
 
+      - name: Build packages
+        run: npm run turbo:build
+        env:
+          NODE_ENV: production
+          FORCE_COLOR: 1
+
       - name: Create Release Pull Request or Publish to npm
         uses: changesets/action@v1
         with:

.gitignore

@@ -94,3 +94,6 @@ apps/extension/.vscode-test/
 
 # apps/extension
 apps/extension/vsix-build/
+
+# turbo
+.turbo

.taskmaster/docs/MIGRATION-ROADMAP.md

@@ -0,0 +1,188 @@
+# Task Master Migration Roadmap
+
+## Overview
+Gradual migration from scripts-based architecture to a clean monorepo with separated concerns.
+
+## Architecture Vision
+
+```
+┌─────────────────────────────────────────────────┐
+│                  User Interfaces                 │
+├──────────┬──────────┬──────────┬────────────────┤
+│  @tm/cli │ @tm/mcp  │ @tm/ext  │  @tm/web      │
+│  (CLI)   │  (MCP)   │  (VSCode)│  (Future)     │
+└──────────┴──────────┴──────────┴────────────────┘
+                    │
+                    ▼
+        ┌──────────────────────┐
+        │      @tm/core        │
+        │  (Business Logic)    │
+        └──────────────────────┘
+```
+
+## Migration Phases
+
+### Phase 1: Core Extraction ✅ (In Progress)
+**Goal**: Move all business logic to @tm/core
+
+- [x] Create @tm/core package structure
+- [x] Move types and interfaces
+- [x] Implement TaskMasterCore facade
+- [x] Move storage adapters
+- [x] Move task services
+- [ ] Move AI providers
+- [ ] Move parser logic
+- [ ] Complete test coverage
+
+### Phase 2: CLI Package Creation 🚧 (Started)
+**Goal**: Create @tm/cli as a thin presentation layer
+
+- [x] Create @tm/cli package structure
+- [x] Implement Command interface pattern
+- [x] Create CommandRegistry
+- [x] Build legacy bridge/adapter
+- [x] Migrate list-tasks command
+- [ ] Migrate remaining commands one by one
+- [ ] Remove UI logic from core
+
+### Phase 3: Transitional Integration
+**Goal**: Use new packages in existing scripts without breaking changes
+
+```javascript
+// scripts/modules/commands.js gradually adopts new commands
+import { ListTasksCommand } from '@tm/cli';
+const listCommand = new ListTasksCommand();
+
+// Old interface remains the same
+programInstance
+  .command('list')
+  .action(async (options) => {
+    // Use new command internally
+    const result = await listCommand.execute(convertOptions(options));
+  });
+```
+
+### Phase 4: MCP Package
+**Goal**: Separate MCP server as its own package
+
+- [ ] Create @tm/mcp package
+- [ ] Move MCP server code
+- [ ] Use @tm/core for all logic
+- [ ] MCP becomes a thin RPC layer
+
+### Phase 5: Complete Migration
+**Goal**: Remove old scripts, pure monorepo
+
+- [ ] All commands migrated to @tm/cli
+- [ ] Remove scripts/modules/task-manager/*
+- [ ] Remove scripts/modules/commands.js
+- [ ] Update bin/task-master.js to use @tm/cli
+- [ ] Clean up dependencies
+
+## Current Transitional Strategy
+
+### 1. Adapter Pattern (commands-adapter.js)
+```javascript
+// Checks if new CLI is available and uses it
+// Falls back to legacy implementation if not
+export async function listTasksAdapter(...args) {
+  if (cliAvailable) {
+    return useNewImplementation(...args);
+  }
+  return useLegacyImplementation(...args);
+}
+```
+
+### 2. Command Bridge Pattern
+```javascript
+// Allows new commands to work in old code
+const bridge = new CommandBridge(new ListTasksCommand());
+const data = await bridge.run(legacyOptions); // Legacy style
+const result = await bridge.execute(newOptions); // New style
+```
+
+### 3. Gradual File Migration
+Instead of big-bang refactoring:
+1. Create new implementation in @tm/cli
+2. Add adapter in commands-adapter.js
+3. Update commands.js to use adapter
+4. Test both paths work
+5. Eventually remove adapter when all migrated
+
+## Benefits of This Approach
+
+1. **No Breaking Changes**: Existing CLI continues to work
+2. **Incremental PRs**: Each command can be migrated separately
+3. **Parallel Development**: New features can use new architecture
+4. **Easy Rollback**: Can disable new implementation if issues
+5. **Clear Separation**: Business logic (core) vs presentation (cli/mcp/etc)
+
+## Example PR Sequence
+
+### PR 1: Core Package Setup ✅
+- Create @tm/core
+- Move types and interfaces
+- Basic TaskMasterCore implementation
+
+### PR 2: CLI Package Foundation ✅
+- Create @tm/cli
+- Command interface and registry
+- Legacy bridge utilities
+
+### PR 3: First Command Migration
+- Migrate list-tasks to new system
+- Add adapter in scripts
+- Test both implementations
+
+### PR 4-N: Migrate Commands One by One
+- Each PR migrates 1-2 related commands
+- Small, reviewable changes
+- Continuous delivery
+
+### Final PR: Cleanup
+- Remove legacy implementations
+- Remove adapters
+- Update documentation
+
+## Testing Strategy
+
+### Dual Testing During Migration
+```javascript
+describe('List Tasks', () => {
+  it('works with legacy implementation', async () => {
+    // Force legacy
+    const result = await legacyListTasks(...);
+    expect(result).toBeDefined();
+  });
+
+  it('works with new implementation', async () => {
+    // Force new
+    const command = new ListTasksCommand();
+    const result = await command.execute(...);
+    expect(result.success).toBe(true);
+  });
+
+  it('adapter chooses correctly', async () => {
+    // Let adapter decide
+    const result = await listTasksAdapter(...);
+    expect(result).toBeDefined();
+  });
+});
+```
+
+## Success Metrics
+
+- [ ] All commands migrated without breaking changes
+- [ ] Test coverage maintained or improved
+- [ ] Performance maintained or improved
+- [ ] Cleaner, more maintainable codebase
+- [ ] Easy to add new interfaces (web, desktop, etc.)
+
+## Notes for Contributors
+
+1. **Keep PRs Small**: Migrate one command at a time
+2. **Test Both Paths**: Ensure legacy and new both work
+3. **Document Changes**: Update this roadmap as you go
+4. **Communicate**: Discuss in PRs if architecture needs adjustment
+
+This is a living document - update as the migration progresses!

.taskmaster/reports/task-complexity-report_tm-core-phase-1.json

@@ -0,0 +1,77 @@
+{
+	"meta": {
+		"generatedAt": "2025-08-06T12:39:03.250Z",
+		"tasksAnalyzed": 8,
+		"totalTasks": 11,
+		"analysisCount": 8,
+		"thresholdScore": 5,
+		"projectName": "Taskmaster",
+		"usedResearch": false
+	},
+	"complexityAnalysis": [
+		{
+			"taskId": 118,
+			"taskTitle": "Create AI Provider Base Architecture",
+			"complexityScore": 7,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Break down the implementation of BaseProvider abstract TypeScript class into subtasks focusing on: 1) Converting existing JavaScript base-provider.js to TypeScript with proper interface definitions, 2) Implementing the Template Method pattern with abstract methods, 3) Adding comprehensive error handling and retry logic with exponential backoff, 4) Creating proper TypeScript types for all method signatures and options, 5) Setting up comprehensive unit tests with MockProvider. Consider that the existing codebase uses JavaScript ES modules and Vercel AI SDK, so the TypeScript implementation needs to maintain compatibility while adding type safety.",
+			"reasoning": "This task requires significant architectural work including converting existing JavaScript code to TypeScript, creating new interfaces, implementing design patterns, and ensuring backward compatibility. The existing base-provider.js already implements a sophisticated provider pattern using Vercel AI SDK, so the TypeScript conversion needs careful consideration of type definitions and maintaining existing functionality."
+		},
+		{
+			"taskId": 119,
+			"taskTitle": "Implement Provider Factory with Dynamic Imports",
+			"complexityScore": 5,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Break down the Provider Factory implementation into: 1) Creating the ProviderFactory class structure with proper TypeScript typing, 2) Implementing the switch statement for provider selection logic, 3) Adding dynamic imports for each provider to enable tree-shaking, 4) Handling provider instantiation with configuration passing, 5) Implementing comprehensive error handling for module loading failures. Note that the existing codebase already has a provider selection mechanism in the JavaScript files, so ensure the factory pattern integrates smoothly with existing infrastructure.",
+			"reasoning": "This is a moderate complexity task that involves creating a factory pattern with dynamic imports. The existing codebase already has provider management logic, so the main complexity is in creating a clean TypeScript implementation with proper dynamic imports while maintaining compatibility with the existing JavaScript module system."
+		},
+		{
+			"taskId": 120,
+			"taskTitle": "Implement Anthropic Provider",
+			"complexityScore": 6,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Implement the AnthropicProvider class in stages: 1) Set up the class structure extending BaseProvider with proper TypeScript imports and type definitions, 2) Implement constructor with Anthropic SDK client initialization and configuration handling, 3) Implement generateCompletion method with proper message format transformation and error handling, 4) Add token calculation methods and utility functions (getName, getModel, getDefaultModel), 5) Implement comprehensive error handling with custom error wrapping and type exports. The existing anthropic.js provider can serve as a reference but needs to be reimplemented to extend the new TypeScript BaseProvider.",
+			"reasoning": "This task involves integrating with an external SDK (@anthropic-ai/sdk) and implementing all abstract methods from BaseProvider. The existing JavaScript implementation provides a good reference, but the TypeScript version needs proper type definitions, error handling, and must work with the new abstract base class architecture."
+		},
+		{
+			"taskId": 121,
+			"taskTitle": "Create Prompt Builder and Task Parser",
+			"complexityScore": 8,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Implement PromptBuilder and TaskParser with focus on: 1) Creating PromptBuilder class with template methods for building structured prompts with JSON format instructions, 2) Implementing TaskParser class structure with dependency injection of IAIProvider and IConfiguration, 3) Implementing parsePRD method with file reading, prompt generation, and AI provider integration, 4) Adding task enrichment logic with metadata, validation, and structure verification, 5) Implementing comprehensive error handling for all failure scenarios including file I/O, AI provider errors, and JSON parsing. The existing parse-prd.js provides complex logic that needs to be reimplemented with proper TypeScript types and cleaner architecture.",
+			"reasoning": "This is a complex task that involves multiple components working together: file I/O, AI provider integration, JSON parsing, and data validation. The existing parse-prd.js implementation is quite sophisticated with Zod schemas and complex task processing logic that needs to be reimplemented in TypeScript with proper separation of concerns."
+		},
+		{
+			"taskId": 122,
+			"taskTitle": "Implement Configuration Management",
+			"complexityScore": 6,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Create ConfigManager implementation focusing on: 1) Setting up Zod validation schema that matches the IConfiguration interface structure, 2) Implementing ConfigManager constructor with default values merging and storage initialization, 3) Creating validate method with Zod schema parsing and user-friendly error transformation, 4) Implementing type-safe get method using TypeScript generics and keyof operator, 5) Adding getAll method and ensuring proper immutability and module exports. The existing config-manager.js has complex configuration loading logic that can inform the TypeScript implementation but needs cleaner architecture.",
+			"reasoning": "This task involves creating a configuration management system with validation using Zod. The existing JavaScript config-manager.js is quite complex with multiple configuration sources, defaults, and validation logic. The TypeScript version needs to provide a cleaner API while maintaining the flexibility of the current system."
+		},
+		{
+			"taskId": 123,
+			"taskTitle": "Create Utility Functions and Error Handling",
+			"complexityScore": 4,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Implement utilities and error handling in stages: 1) Create ID generation module with generateTaskId and generateSubtaskId functions using proper random generation, 2) Implement base TaskMasterError class extending Error with proper TypeScript typing, 3) Add error sanitization methods to prevent sensitive data exposure in production, 4) Implement development-only logging with environment detection, 5) Create specialized error subclasses (FileNotFoundError, ParseError, ValidationError, APIError) with appropriate error codes and formatting.",
+			"reasoning": "This is a relatively straightforward task involving utility functions and error class hierarchies. The main complexity is in ensuring proper error sanitization for production use and creating a well-structured error hierarchy that can be used throughout the application."
+		},
+		{
+			"taskId": 124,
+			"taskTitle": "Implement TaskMasterCore Facade",
+			"complexityScore": 7,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Build TaskMasterCore facade implementation: 1) Create class structure with proper TypeScript imports and type definitions for all subsystem interfaces, 2) Implement initialize method for lazy loading AI provider and parser instances based on configuration, 3) Create parsePRD method that coordinates parser, AI provider, and storage subsystems, 4) Implement getTasks and other facade methods for task retrieval and management, 5) Create createTaskMaster factory function and set up all module exports including type re-exports. Ensure proper ESM compatibility with .js extensions in imports.",
+			"reasoning": "This is a complex integration task that brings together all the other components into a cohesive facade. It requires understanding of the facade pattern, proper dependency management, lazy initialization, and careful module export structure for the public API."
+		},
+		{
+			"taskId": 125,
+			"taskTitle": "Create Placeholder Providers and Complete Testing",
+			"complexityScore": 5,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Complete the implementation with placeholders and testing: 1) Create OpenAIProvider placeholder class extending BaseProvider with 'not yet implemented' errors, 2) Create GoogleProvider placeholder class with similar structure, 3) Implement MockProvider in tests/mocks directory with configurable responses and behavior simulation, 4) Write comprehensive unit tests for TaskParser covering all methods and edge cases, 5) Create integration tests for the complete parse-prd workflow ensuring 80% code coverage. Follow kebab-case naming convention for test files.",
+			"reasoning": "This task involves creating placeholder implementations and a comprehensive test suite. While the placeholder providers are simple, creating a good MockProvider and comprehensive tests requires understanding the entire system architecture and ensuring all edge cases are covered."
+		}
+	]
+}

.taskmaster/reports/tm-core-complexity.json

@@ -0,0 +1,77 @@
+{
+	"meta": {
+		"generatedAt": "2025-08-06T12:15:01.327Z",
+		"tasksAnalyzed": 8,
+		"totalTasks": 11,
+		"analysisCount": 8,
+		"thresholdScore": 5,
+		"projectName": "Taskmaster",
+		"usedResearch": false
+	},
+	"complexityAnalysis": [
+		{
+			"taskId": 118,
+			"taskTitle": "Create AI Provider Base Architecture",
+			"complexityScore": 4,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Break down the conversion of base-provider.js to TypeScript BaseProvider class: 1) Convert to TypeScript and define IAIProvider interface, 2) Implement abstract class with core properties, 3) Define abstract methods and Template Method pattern, 4) Add retry logic with exponential backoff, 5) Implement validation and logging. Focus on maintaining compatibility with existing provider pattern while adding type safety.",
+			"reasoning": "The codebase already has a well-established BaseAIProvider class in JavaScript. Converting to TypeScript mainly involves adding type definitions and ensuring the existing pattern is preserved. The complexity is moderate because the pattern is already proven in the codebase."
+		},
+		{
+			"taskId": 119,
+			"taskTitle": "Implement Provider Factory with Dynamic Imports",
+			"complexityScore": 3,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Create ProviderFactory implementation: 1) Set up class structure and types, 2) Implement provider selection switch statement, 3) Add dynamic imports for tree-shaking, 4) Handle provider instantiation with config, 5) Add comprehensive error handling. The existing PROVIDERS registry pattern should guide the implementation.",
+			"reasoning": "The codebase already uses a dual registry pattern (static PROVIDERS and dynamic ProviderRegistry). Creating a factory is straightforward as the provider registration patterns are well-established. Dynamic imports are already used in the codebase."
+		},
+		{
+			"taskId": 120,
+			"taskTitle": "Implement Anthropic Provider",
+			"complexityScore": 3,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Implement AnthropicProvider following existing patterns: 1) Create class structure with imports, 2) Implement constructor and client initialization, 3) Add generateCompletion with Claude API integration, 4) Implement token calculation and utility methods, 5) Add error handling and exports. Use the existing anthropic.js provider as reference.",
+			"reasoning": "AnthropicProvider already exists in the codebase with full implementation. This task essentially involves adapting the existing implementation to match the new TypeScript architecture, making it relatively straightforward."
+		},
+		{
+			"taskId": 121,
+			"taskTitle": "Create Prompt Builder and Task Parser",
+			"complexityScore": 6,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Build prompt system and parser: 1) Create PromptBuilder with template methods, 2) Implement TaskParser with dependency injection, 3) Add parsePRD core logic with file reading, 4) Implement task enrichment and metadata, 5) Add comprehensive error handling. Leverage the existing prompt management system in src/prompts/.",
+			"reasoning": "While the codebase has a sophisticated prompt management system, creating a new PromptBuilder and TaskParser requires understanding the existing prompt templates, JSON schema validation, and integration with the AI provider system. The task involves significant new code."
+		},
+		{
+			"taskId": 122,
+			"taskTitle": "Implement Configuration Management",
+			"complexityScore": 5,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Create ConfigManager with validation: 1) Define Zod schema for IConfiguration, 2) Implement constructor with defaults, 3) Add validate method with error handling, 4) Create type-safe get method with generics, 5) Implement getAll and finalize exports. Reference existing config-manager.js for patterns.",
+			"reasoning": "The codebase has an existing config-manager.js with sophisticated configuration handling. Adding Zod validation and TypeScript generics adds complexity, but the existing patterns provide a solid foundation."
+		},
+		{
+			"taskId": 123,
+			"taskTitle": "Create Utility Functions and Error Handling",
+			"complexityScore": 2,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Implement utilities and error handling: 1) Create ID generation module with unique formats, 2) Build TaskMasterError base class, 3) Add error sanitization for security, 4) Implement development-only logging, 5) Create specialized error subclasses. Keep implementation simple and focused.",
+			"reasoning": "This is a straightforward utility implementation task. The codebase already has error handling patterns, and ID generation is a simple algorithmic task. The main work is creating clean, reusable utilities."
+		},
+		{
+			"taskId": 124,
+			"taskTitle": "Implement TaskMasterCore Facade",
+			"complexityScore": 7,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Create main facade class: 1) Set up TaskMasterCore structure with imports, 2) Implement lazy initialization logic, 3) Add parsePRD coordination method, 4) Implement getTasks and other facade methods, 5) Create factory function and exports. This ties together all other components into a cohesive API.",
+			"reasoning": "This is the most complex task as it requires understanding and integrating all other components. The facade must coordinate between configuration, providers, storage, and parsing while maintaining a clean API. It's the architectural keystone of the system."
+		},
+		{
+			"taskId": 125,
+			"taskTitle": "Create Placeholder Providers and Complete Testing",
+			"complexityScore": 5,
+			"recommendedSubtasks": 5,
+			"expansionPrompt": "Implement testing infrastructure: 1) Create OpenAIProvider placeholder, 2) Create GoogleProvider placeholder, 3) Build MockProvider for testing, 4) Write TaskParser unit tests, 5) Create integration tests for parse-prd flow. Follow the existing test patterns in tests/ directory.",
+			"reasoning": "While creating placeholder providers is simple, the testing infrastructure requires understanding Jest with ES modules, mocking patterns, and comprehensive test coverage. The existing test structure provides good examples to follow."
+		}
+	]
+}

.taskmaster/state.json

@@ -1,6 +1,6 @@
 {
 	"currentTag": "master",
-	"lastSwitched": "2025-08-01T14:09:25.838Z",
+	"lastSwitched": "2025-08-27T21:03:20.550Z",
 	"branchTagMapping": {
 		"v017-adds": "v017-adds",
 		"next": "next"

.taskmaster/tasks/tasks.json

@@ -7297,5 +7297,763 @@
       "updated": "2025-07-22T09:38:19.341Z",
       "description": "Tasks for cc-kiro-hooks context"
     }
+  },
+  "tm-core-phase-1": {
+    "tasks": [
+      {
+        "id": 115,
+        "title": "Initialize tm-core Package Structure",
+        "description": "Create the initial package structure for tm-core with all required directories and configuration files",
+        "details": "Create the packages/tm-core directory structure with all subdirectories as specified: src/, tests/, and all nested folders. Set up package.json with proper ESM/CJS configuration, tsconfig.json with strict TypeScript settings, tsup.config.js for dual format builds, and jest.config.js for testing. Ensure all barrel export files (index.ts) are created in each directory for clean imports.",
+        "testStrategy": "Verify directory structure matches specification exactly, ensure all configuration files are valid JSON/JS, run 'npm install' to verify package.json is correct, run 'tsc --noEmit' to verify TypeScript configuration",
+        "priority": "high",
+        "dependencies": [],
+        "status": "done",
+        "subtasks": [
+          {
+            "id": 1,
+            "title": "Create tm-core directory structure and base configuration files",
+            "description": "Set up the packages/tm-core directory with all required subdirectories and initialize core configuration files",
+            "dependencies": [],
+            "details": "Create packages/tm-core directory with subdirectories: src/, src/types/, src/interfaces/, src/providers/, src/parsers/, src/builders/, src/utils/, src/errors/, tests/, tests/unit/, tests/integration/, tests/mocks/. Create package.json with name '@task-master/tm-core', version '1.0.0', type 'module', main/module/types fields for dual ESM/CJS support, and necessary dependencies (typescript, tsup, jest, @types/node). Set up tsconfig.json with strict mode, ES2022 target, module resolution, and proper include/exclude patterns.\n<info added on 2025-08-06T10:49:59.891Z>\nImplementation completed as specified. Directory structure verified with all paths created correctly. Package.json configured with dual ESM/CJS support using tsup build tool, exports field properly set for both formats. TypeScript configuration established with strict mode enabled, ES2022 target for modern JavaScript features, and path mappings configured for clean imports like '@/types' and '@/utils'. All configuration files are valid and ready for development.\n</info added on 2025-08-06T10:49:59.891Z>",
+            "status": "done",
+            "testStrategy": "Verify directory structure with fs.existsSync() checks, validate package.json structure with JSON.parse(), ensure tsconfig.json compiles without errors"
+          },
+          {
+            "id": 2,
+            "title": "Configure build and test infrastructure",
+            "description": "Set up tsup build configuration for dual format support and Jest testing configuration",
+            "dependencies": [
+              "115.1"
+            ],
+            "details": "Create tsup.config.js with dual format configuration (ESM and CJS), entry points from src/index.ts, declaration files generation, and sourcemaps. Configure jest.config.js with TypeScript preset, ESM support, proper module name mapping, coverage thresholds (80%), and test environment setup. Create .gitignore for node_modules, dist, and coverage directories. Add npm scripts in package.json for build, test, test:watch, and test:coverage commands.\n<info added on 2025-08-06T10:50:49.396Z>\nBuild process successfully configured with tsup.config.ts (TypeScript configuration file instead of JavaScript) supporting dual format output and multiple entry points including submodules. Jest configuration established with comprehensive ESM support and path alias mapping. Created tests/setup.ts for centralized test environment configuration. Added ES2022 compilation target for modern JavaScript features. Enhanced .gitignore to exclude additional development-specific files beyond the basic directories.\n</info added on 2025-08-06T10:50:49.396Z>",
+            "status": "done",
+            "testStrategy": "Run 'npm run build' to verify tsup configuration works, execute 'npm test' with a simple test file to confirm Jest setup, check that both .mjs and .cjs files are generated in dist/"
+          },
+          {
+            "id": 3,
+            "title": "Create barrel export files for all directories",
+            "description": "Implement index.ts files in each directory to enable clean imports throughout the package",
+            "dependencies": [
+              "115.1"
+            ],
+            "details": "Create index.ts in src/ that exports from all subdirectories. Create index.ts in each subdirectory (types/, interfaces/, providers/, parsers/, builders/, utils/, errors/) with appropriate exports. For now, add placeholder comments indicating what will be exported from each module. Ensure proper export syntax for TypeScript types and interfaces using 'export type' where appropriate. Structure exports to allow consumers to import like '@task-master/tm-core/types' or from the main entry point.\n<info added on 2025-08-06T10:51:56.837Z>\nImplementation complete. All barrel export files have been created successfully with:\n\n- Main src/index.ts exporting from all subdirectories with proper TypeScript syntax\n- Individual index.ts files in types/, providers/, storage/, parser/, utils/, and errors/ directories\n- Proper ES module syntax with .js extensions for TypeScript compatibility\n- Placeholder exports with @deprecated JSDoc tags to indicate future implementation\n- Clean module structure supporting both root imports and submodule imports like '@task-master/tm-core/types'\n- All files include appropriate documentation comments explaining their purpose\n</info added on 2025-08-06T10:51:56.837Z>",
+            "status": "done",
+            "testStrategy": "Compile with TypeScript to ensure all index.ts files are valid, verify no circular dependencies exist, check that imports from package root work correctly"
+          },
+          {
+            "id": 4,
+            "title": "Add development tooling and documentation",
+            "description": "Set up development tools, linting, and initial documentation structure",
+            "dependencies": [
+              "115.1",
+              "115.2"
+            ],
+            "details": "Create .eslintrc.js with TypeScript plugin and recommended rules for consistent code style. Add prettier configuration for code formatting. Create README.md with package overview, installation instructions, and usage examples (marked as 'coming soon'). Add CHANGELOG.md to track version changes. Create npm scripts for linting and formatting. Add pre-commit hooks configuration if needed. Document the dual ESM/CJS support in README.\n<info added on 2025-08-06T10:53:45.056Z>\nI'll analyze the user's request and the context to determine what new information should be added to the subtask's details.Successfully completed development tooling and documentation setup. Created .eslintrc.js with TypeScript plugin and comprehensive rules including no-explicit-any, consistent-type-imports, and proper TypeScript checks. Added .prettierrc.json with sensible defaults for consistent code formatting. Created comprehensive README.md with package overview, installation instructions, usage examples for both ESM and CommonJS, modular imports, architecture description, development setup, and detailed roadmap for tasks 116-125. Added CHANGELOG.md following Keep a Changelog format with current package status and planned features. All development tooling is configured and ready for use.\n</info added on 2025-08-06T10:53:45.056Z>",
+            "status": "done",
+            "testStrategy": "Run eslint on sample TypeScript files, verify prettier formats code consistently, ensure all npm scripts execute without errors"
+          },
+          {
+            "id": 5,
+            "title": "Validate package structure and prepare for development",
+            "description": "Perform final validation of the package structure and ensure it's ready for implementation",
+            "dependencies": [
+              "115.1",
+              "115.2",
+              "115.3",
+              "115.4"
+            ],
+            "details": "Run 'npm install' to ensure all dependencies are properly resolved. Execute 'tsc --noEmit' to verify TypeScript configuration is correct. Create a simple smoke test in tests/ that imports from the package to verify module resolution works. Ensure the package can be linked locally for testing in other projects. Verify that both CommonJS and ESM imports work correctly. Create a checklist in README for remaining implementation tasks based on tasks 116-125.\n<info added on 2025-08-06T11:02:21.457Z>\nSuccessfully validated package structure with comprehensive testing. All validations passed: npm install resolved dependencies without issues, TypeScript compilation (tsc --noEmit) showed no errors, and dual-format build (npm run build) successfully generated both ESM and CJS outputs with proper TypeScript declarations. Created and executed comprehensive smoke test suite covering all module imports, placeholder functionality, and type definitions - all 8 tests passing. Code quality tools (ESLint, Prettier) are properly configured and show no issues. Package is confirmed ready for local linking and supports both CommonJS and ESM import patterns. README updated with implementation checklist marking Task 115 as complete and clearly outlining remaining implementation tasks 116-125. Package structure validation is complete and development environment is fully prepared for core implementation phase.\n</info added on 2025-08-06T11:02:21.457Z>",
+            "status": "done",
+            "testStrategy": "Successfully run all build and test commands, verify package can be imported in both ESM and CJS test files, ensure TypeScript compilation produces no errors, confirm all directories contain appropriate index.ts files"
+          }
+        ]
+      },
+      {
+        "id": 116,
+        "title": "Define Core TypeScript Types and Interfaces",
+        "description": "Create all TypeScript type definitions and interfaces for the tm-core package",
+        "details": "Create types/index.ts with Task, Subtask, TaskMetadata interfaces and type literals (TaskStatus, TaskPriority, TaskComplexity). Create all interface files: storage.interface.ts with IStorage methods, ai-provider.interface.ts with IAIProvider and AIOptions, configuration.interface.ts with IConfiguration. Use strict typing throughout, no 'any' types allowed. Follow naming conventions: interfaces prefixed with 'I', type literals in PascalCase.",
+        "testStrategy": "Compile with TypeScript to ensure no type errors, create mock implementations to verify interfaces are complete, use type checking in IDE to confirm all required properties are defined",
+        "priority": "high",
+        "dependencies": [
+          115
+        ],
+        "status": "done",
+        "subtasks": [
+          {
+            "id": 1,
+            "title": "Create Core Task and Subtask Type Definitions",
+            "description": "Create types/index.ts with fundamental Task and Subtask interfaces including all required properties",
+            "dependencies": [],
+            "details": "Create types/index.ts file. Define Task interface with properties: id (string), title (string), description (string), status (TaskStatus), priority (TaskPriority), dependencies (string[]), details (string), testStrategy (string), subtasks (Subtask[]). Define Subtask interface extending Task but with numeric id. Define TaskMetadata interface with version (string), lastModified (string), taskCount (number), completedCount (number). Export all interfaces.\n<info added on 2025-08-06T11:03:44.220Z>\nImplementation completed with comprehensive type system. Created all required interfaces with strict typing, added optional properties for enhanced functionality (createdAt, updatedAt, effort, actualEffort, tags). Implemented utility types for create/update operations with proper type constraints. Added filter interfaces for advanced querying. Included runtime type guards for safe type narrowing. Successfully compiled without TypeScript errors, ready for integration with storage and AI provider implementations.\n</info added on 2025-08-06T11:03:44.220Z>",
+            "status": "done",
+            "testStrategy": "Compile TypeScript files to ensure no type errors, create sample objects conforming to interfaces to verify completeness"
+          },
+          {
+            "id": 2,
+            "title": "Define Type Literals and Enums",
+            "description": "Create all type literal definitions for TaskStatus, TaskPriority, and TaskComplexity in the types file",
+            "dependencies": [
+              "116.1"
+            ],
+            "details": "In types/index.ts, define type literals: TaskStatus = 'pending' | 'in-progress' | 'done' | 'deferred' | 'cancelled' | 'blocked'; TaskPriority = 'low' | 'medium' | 'high' | 'critical'; TaskComplexity = 'simple' | 'moderate' | 'complex' | 'very-complex'. Consider using const assertions for better type inference. Export all type literals.\n<info added on 2025-08-06T11:04:04.675Z>\nType literals were already implemented in subtask 116.1 as part of the comprehensive type system. The types/index.ts file includes all required type literals: TaskStatus with values 'pending' | 'in-progress' | 'done' | 'deferred' | 'cancelled' | 'blocked' | 'review', TaskPriority with values 'low' | 'medium' | 'high' | 'critical', and TaskComplexity with values 'simple' | 'moderate' | 'complex' | 'very-complex'. All type literals are properly exported and include comprehensive JSDoc documentation. TypeScript compilation verified the types work correctly.\n</info added on 2025-08-06T11:04:04.675Z>",
+            "status": "done",
+            "testStrategy": "Use TypeScript compiler to verify type literals work correctly, test with invalid values to ensure type checking catches errors"
+          },
+          {
+            "id": 3,
+            "title": "Create Storage Interface Definition",
+            "description": "Create storage.interface.ts with IStorage interface defining all storage operation methods",
+            "dependencies": [
+              "116.1"
+            ],
+            "details": "Create interfaces/storage.interface.ts file. Define IStorage interface with methods: loadTasks(tag?: string): Promise<Task[]>; saveTasks(tasks: Task[], tag?: string): Promise<void>; appendTasks(tasks: Task[], tag?: string): Promise<void>; updateTask(taskId: string, updates: Partial<Task>, tag?: string): Promise<void>; deleteTask(taskId: string, tag?: string): Promise<void>; exists(tag?: string): Promise<boolean>. Import Task type from types/index.ts.\n<info added on 2025-08-06T11:05:00.573Z>\nImplementation completed successfully. Extended IStorage interface beyond original specification to include metadata operations (loadMetadata, saveMetadata), tag management (getAllTags, deleteTag, renameTag, copyTag), and lifecycle methods (initialize, close, getStats). Added StorageStats interface for monitoring storage metrics and StorageConfig interface for configuration options. Implemented BaseStorage abstract class that provides common functionality including task validation using validateTask method, tag sanitization with sanitizeTag to ensure valid filenames, and backup path generation through getBackupPath for data safety. The abstract class serves as a foundation for concrete storage implementations, reducing code duplication and ensuring consistent behavior across different storage backends. All methods properly typed with async/await patterns and comprehensive error handling considerations.\n</info added on 2025-08-06T11:05:00.573Z>",
+            "status": "done",
+            "testStrategy": "Create mock implementation of IStorage to verify all methods are properly typed, ensure Promise return types are correct"
+          },
+          {
+            "id": 4,
+            "title": "Create AI Provider Interface Definition",
+            "description": "Create ai-provider.interface.ts with IAIProvider interface and AIOptions type",
+            "dependencies": [
+              "116.1"
+            ],
+            "details": "Create interfaces/ai-provider.interface.ts file. Define AIOptions interface with properties: temperature (number), maxTokens (number), stream (boolean), topP (number), frequencyPenalty (number). Define IAIProvider interface with methods: generateCompletion(prompt: string, options?: AIOptions): Promise<string>; calculateTokens(text: string): number; getName(): string; getModel(): string; getDefaultModel(): string; isAvailable(): Promise<boolean>.\n<info added on 2025-08-06T11:06:15.795Z>\nFile successfully updated with expanded interface implementation details including comprehensive method signatures and supporting interfaces: AIOptions with full parameter set (temperature, maxTokens, stream, model, topP, topK, frequencyPenalty, presencePenalty, stopSequences, systemPrompt), AIResponse structure with content and usage metadata, AIModel interface for model information, ProviderInfo for capability tracking, ProviderUsageStats for usage monitoring, AIProviderConfig for initialization, and additional interfaces for streaming support. Documented BaseAIProvider abstract class implementation with validation, usage tracking, and common utility methods. All interfaces properly typed with strict TypeScript patterns and async/await support. No compilation errors.\n</info added on 2025-08-06T11:06:15.795Z>",
+            "status": "done",
+            "testStrategy": "Create stub implementation to verify interface completeness, test optional parameters work correctly"
+          },
+          {
+            "id": 5,
+            "title": "Create Configuration Interface Definition",
+            "description": "Create configuration.interface.ts with IConfiguration interface for all config options",
+            "dependencies": [
+              "116.1",
+              "116.2"
+            ],
+            "details": "Create interfaces/configuration.interface.ts file. Define IConfiguration interface with properties: projectPath (string), aiProvider (string), apiKeys (Record<string, string>), models (object with main, research, fallback as strings), enableTags (boolean), defaultTag (string), maxConcurrentTasks (number), retryAttempts (number), retryDelay (number). Import necessary types from types/index.ts. Ensure all properties have appropriate types with no 'any' usage.\n<info added on 2025-08-06T11:07:43.367Z>\nImplementation completed successfully. Created comprehensive configuration system with:\n\n- Core IConfiguration interface with all required properties: projectPath, aiProvider, apiKeys, models configuration, providers settings, tasks management, tags configuration, storage options, retry behavior, logging preferences, and security settings\n- Supporting interfaces for each configuration section: ModelConfig for AI model selection, ProviderConfig for API provider settings, TaskSettings for task management options, TagSettings for tag-based organization, StorageSettings for persistence configuration, RetrySettings for error handling, LoggingSettings for debugging options, SecuritySettings for API key management\n- Configuration management system with IConfigurationFactory for creating configs from various sources (file, environment, defaults) and IConfigurationManager for runtime config operations including loading, saving, validation, watching for changes, and merging configurations\n- Validation system with ConfigValidationResult interface for detailed error reporting, ConfigSchema for JSON schema validation, and EnvironmentConfig for environment variable mapping\n- DEFAULT_CONFIG_VALUES constant providing sensible defaults for all configuration options\n- All interfaces properly typed with strict TypeScript typing, no 'any' usage, proper imports from types/index\n- Successfully exported all interfaces through main index.ts for package consumers\n- TypeScript compilation confirmed passing without any type errors\n</info added on 2025-08-06T11:07:43.367Z>",
+            "status": "done",
+            "testStrategy": "Create sample configuration objects to verify interface covers all needed options, test with partial configs to ensure optional properties work"
+          }
+        ]
+      },
+      {
+        "id": 117,
+        "title": "Implement Storage Layer with Repository Pattern",
+        "description": "Create FileStorage class implementing IStorage interface for task persistence",
+        "details": "Implement FileStorage class in storage/file-storage.ts following Repository pattern. Constructor accepts projectPath, private basePath property set to {projectPath}/.taskmaster. Implement all IStorage methods: loadTasks, saveTasks, appendTasks, updateTask, deleteTask, exists. Handle file operations with proper error handling (ENOENT returns empty arrays). Use JSON format with tasks array and metadata object containing version and lastModified. Create getTasksPath method to handle tag-based file paths.",
+        "testStrategy": "Unit test all FileStorage methods with mock file system, test error scenarios (missing files, invalid JSON), verify tag-based path generation, test concurrent operations, ensure proper directory creation",
+        "priority": "high",
+        "dependencies": [
+          116
+        ],
+        "status": "done",
+        "subtasks": [
+          {
+            "id": 1,
+            "title": "Create FileStorage class structure and constructor",
+            "description": "Set up the FileStorage class skeleton with proper TypeScript typing and implement the constructor that accepts projectPath parameter",
+            "dependencies": [],
+            "details": "Create storage/file-storage.ts file. Import necessary Node.js modules (fs/promises, path). Import IStorage interface and Task type from types. Define FileStorage class implementing IStorage. Create constructor accepting projectPath string parameter. Initialize private basePath property as `${projectPath}/.taskmaster`. Add private property for managing file locks if needed for concurrent operations.",
+            "status": "done",
+            "testStrategy": "Unit test constructor initialization, verify basePath is correctly set, test with various projectPath inputs including edge cases"
+          },
+          {
+            "id": 2,
+            "title": "Implement file path management and helper methods",
+            "description": "Create internal helper methods for managing file paths and ensuring directory structure exists",
+            "dependencies": [
+              "117.1"
+            ],
+            "details": "Implement private getTasksPath(tag?: string) method that returns path to tasks file based on optional tag parameter. If tag provided, return `${basePath}/tasks/${tag}.json`, otherwise `${basePath}/tasks/tasks.json`. Create private ensureDirectoryExists() method that creates .taskmaster and tasks directories if they don't exist using fs.mkdir with recursive option. Add private method for safe JSON parsing with error handling.",
+            "status": "done",
+            "testStrategy": "Test getTasksPath with and without tags, verify directory creation works recursively, test JSON parsing with valid and invalid data"
+          },
+          {
+            "id": 3,
+            "title": "Implement read operations: loadTasks and exists",
+            "description": "Implement methods for reading tasks from the file system with proper error handling",
+            "dependencies": [
+              "117.2"
+            ],
+            "details": "Implement loadTasks(tag?: string) method: use getTasksPath to get file path, read file using fs.readFile, parse JSON content, return tasks array from parsed data. Handle ENOENT error by returning empty array. Handle JSON parse errors appropriately. Implement exists(tag?: string) method: use fs.access to check if file exists at getTasksPath location, return boolean result.",
+            "status": "done",
+            "testStrategy": "Test loadTasks with existing files, missing files (ENOENT), corrupted JSON files. Test exists method with present and absent files"
+          },
+          {
+            "id": 4,
+            "title": "Implement write operations: saveTasks and appendTasks",
+            "description": "Implement methods for persisting tasks to the file system with metadata",
+            "dependencies": [
+              "117.3"
+            ],
+            "details": "Implement saveTasks(tasks: Task[], tag?: string) method: ensure directory exists, create data object with tasks array and metadata object containing version (e.g., '1.0.0') and lastModified (ISO timestamp). Write to file using fs.writeFile with JSON.stringify and proper formatting. Implement appendTasks(tasks: Task[], tag?: string) method: load existing tasks, merge with new tasks (avoiding duplicates by ID), call saveTasks with merged array.",
+            "status": "done",
+            "testStrategy": "Test saveTasks creates files with correct structure, verify metadata is included, test appendTasks merges correctly without duplicates"
+          },
+          {
+            "id": 5,
+            "title": "Implement update and delete operations",
+            "description": "Implement methods for modifying and removing individual tasks with atomic operations",
+            "dependencies": [
+              "117.4"
+            ],
+            "details": "Implement updateTask(taskId: string, updates: Partial<Task>, tag?: string) method: load tasks, find task by ID, merge updates using object spread, save updated tasks array. Return boolean indicating success. Implement deleteTask(taskId: string, tag?: string) method: load tasks, filter out task with matching ID, save filtered array. Return boolean indicating if task was found and deleted. Ensure both operations are atomic using temporary files if needed.",
+            "status": "done",
+            "testStrategy": "Test updateTask with existing and non-existing tasks, verify partial updates work correctly. Test deleteTask removes correct task, handles missing tasks gracefully"
+          }
+        ]
+      },
+      {
+        "id": 118,
+        "title": "Create AI Provider Base Architecture",
+        "description": "Implement abstract BaseProvider class and provider interfaces using Template Method pattern",
+        "details": "Convert existing base-provider.js to TypeScript abstract class BaseProvider implementing IAIProvider. Add protected properties for apiKey and model. Create abstract methods: generateCompletion, calculateTokens, getName, getModel, getDefaultModel. Apply Template Method pattern for common provider logic like error handling and retry logic. Ensure proper type safety throughout.",
+        "testStrategy": "Create MockProvider extending BaseProvider to test abstract class functionality, verify all abstract methods are properly defined, test error handling and common logic",
+        "priority": "high",
+        "dependencies": [
+          116
+        ],
+        "status": "done",
+        "subtasks": [
+          {
+            "id": 1,
+            "title": "Convert base-provider.js to TypeScript and define IAIProvider interface",
+            "description": "Create the IAIProvider interface with all required method signatures and convert the existing base-provider.js file to a TypeScript file with proper type definitions",
+            "dependencies": [],
+            "details": "Create src/types/providers.ts with IAIProvider interface containing methods: generateCompletion(prompt: string, options?: CompletionOptions): Promise<CompletionResult>, calculateTokens(text: string): number, getName(): string, getModel(): string, getDefaultModel(): string. Move base-provider.js to src/providers/base-provider.ts and add initial TypeScript types.\n<info added on 2025-08-06T12:16:45.893Z>\nSince the IAIProvider interface already exists in src/interfaces/ai-provider.interface.ts with all required methods and type definitions, update the subtask to focus on converting base-provider.js to TypeScript and implementing the BaseAIProvider abstract class. The conversion should extend the existing BaseAIProvider from src/interfaces/ai-provider.interface.ts rather than creating duplicate interfaces. Ensure the implementation aligns with the comprehensive interface that includes AIOptions, AIResponse, AIModel, ProviderInfo types and methods for streaming, validation, and usage tracking.\n</info added on 2025-08-06T12:16:45.893Z>",
+            "status": "done",
+            "testStrategy": "Verify that the interface is properly defined and that TypeScript compilation succeeds without errors"
+          },
+          {
+            "id": 2,
+            "title": "Implement BaseProvider abstract class with core properties",
+            "description": "Create the abstract BaseProvider class implementing IAIProvider with protected properties for apiKey and model configuration",
+            "dependencies": [
+              "118.1"
+            ],
+            "details": "In base-provider.ts, define abstract class BaseProvider implements IAIProvider with protected properties: apiKey: string, model: string, maxRetries: number = 3, retryDelay: number = 1000. Add constructor that accepts BaseProviderConfig interface with apiKey and optional model. Implement getModel() method to return current model.\n<info added on 2025-08-06T12:28:45.485Z>\nI've reviewed the existing BaseAIProvider interface in the interfaces file. The task requires creating a separate BaseProvider abstract class in base-provider.ts that implements the IAIProvider interface, with specific protected properties and configuration. This appears to be a deliberate architectural decision to have a more concrete base class with built-in retry logic and configuration management that all provider implementations will extend.\n</info added on 2025-08-06T12:28:45.485Z>\n<info added on 2025-08-06T13:14:24.539Z>\nSuccessfully implemented BaseProvider abstract class:\n\nIMPLEMENTED FILES:\n✅ packages/tm-core/src/providers/base-provider.ts - Created new BaseProvider abstract class\n✅ packages/tm-core/src/providers/index.ts - Updated to export BaseProvider\n\nIMPLEMENTATION DETAILS:\n- Created BaseProviderConfig interface with required apiKey and optional model\n- BaseProvider abstract class implements IAIProvider interface\n- Protected properties implemented as specified:\n  - apiKey: string \n  - model: string\n  - maxRetries: number = 3\n  - retryDelay: number = 1000\n- Constructor accepts BaseProviderConfig and sets apiKey and model (using getDefaultModel() if not provided)\n- Implemented getModel() method that returns current model\n- All IAIProvider methods declared as abstract (to be implemented by concrete providers)\n- Uses .js extension for ESM import compatibility\n- TypeScript compilation verified successful\n\nThe BaseProvider provides the foundation for concrete provider implementations with shared retry logic properties and standardized configuration.\n</info added on 2025-08-06T13:14:24.539Z>\n<info added on 2025-08-20T17:16:14.037Z>\nREFACTORING REQUIRED: The BaseProvider implementation needs to be relocated from packages/tm-core/src/providers/base-provider.ts to packages/tm-core/src/providers/ai/base-provider.ts following the new directory structure. The class must implement the Template Method pattern with the following structure:\n\n1. Keep constructor concise (under 10 lines) - only initialize apiKey and model properties\n2. Remove maxRetries and retryDelay from constructor - these should be class-level constants or configurable separately\n3. Implement all abstract methods from IAIProvider: generateCompletion, calculateTokens, getName, getModel, getDefaultModel\n4. Add protected template methods for extensibility:\n   - validateInput(input: string): void - for input validation with early returns\n   - prepareRequest(input: string, options?: any): any - for request preparation\n   - handleResponse(response: any): string - for response processing\n   - handleError(error: any): never - for consistent error handling\n5. Apply clean code principles: extract complex logic into small focused methods, use early returns to reduce nesting, ensure each method has single responsibility\n\nThe refactored BaseProvider will serve as a robust foundation using Template Method pattern, allowing concrete providers to override specific behaviors while maintaining consistent structure and error handling across all AI provider implementations.\n</info added on 2025-08-20T17:16:14.037Z>\n<info added on 2025-08-21T15:57:30.467Z>\nREFACTORING UPDATE: The BaseProvider implementation in packages/tm-core/src/providers/base-provider.ts is now affected by the core/ folder removal and needs its import paths updated. Since base-provider.ts imports from '../interfaces/provider.interface.js', this import remains valid as both providers/ and interfaces/ are at the same level. No changes needed to BaseProvider imports due to the flattening. The file structure reorganization maintains the relative path relationship between providers/ and interfaces/ directories.\n</info added on 2025-08-21T15:57:30.467Z>",
+            "status": "done",
+            "testStrategy": "Create a test file that attempts to instantiate BaseProvider directly (should fail) and verify that protected properties are accessible in child classes"
+          },
+          {
+            "id": 3,
+            "title": "Define abstract methods and implement Template Method pattern",
+            "description": "Add all abstract methods to BaseProvider and implement the Template Method pattern for common provider operations",
+            "dependencies": [
+              "118.2"
+            ],
+            "details": "Add abstract methods: protected abstract generateCompletionInternal(prompt: string, options?: CompletionOptions): Promise<CompletionResult>, abstract calculateTokens(text: string): number, abstract getName(): string, abstract getDefaultModel(): string. Implement public generateCompletion() as template method that calls generateCompletionInternal() with error handling and retry logic.\n<info added on 2025-08-20T17:16:38.315Z>\nApply Template Method pattern following clean code principles:\n\nDefine abstract methods:\n- protected abstract generateCompletionInternal(prompt: string, options?: CompletionOptions): Promise<CompletionResult>\n- protected abstract calculateTokens(text: string): number\n- protected abstract getName(): string\n- protected abstract getDefaultModel(): string\n- protected abstract getMaxRetries(): number\n- protected abstract getRetryDelay(): number\n\nImplement template method generateCompletion():\n- Call validateInput() with early returns for invalid prompt/options\n- Call prepareRequest() to format the request\n- Execute generateCompletionInternal() with retry logic\n- Call handleResponse() to process the result\n- Call handleError() in catch blocks\n\nAdd protected helper methods:\n- validateInput(prompt: string, options?: CompletionOptions): ValidationResult - Check prompt length, validate options, return early on errors\n- prepareRequest(prompt: string, options?: CompletionOptions): PreparedRequest - Format prompt, merge with defaults, add metadata\n- handleResponse(result: CompletionResult): ProcessedResult - Validate response format, extract completion text, add usage metrics\n- handleError(error: unknown, attempt: number): void - Log error details, determine if retryable, throw TaskMasterError\n\nExtract retry logic helpers:\n- shouldRetry(error: unknown, attempt: number): boolean - Check error type and attempt count\n- calculateBackoffDelay(attempt: number): number - Use exponential backoff with jitter\n- isRateLimitError(error: unknown): boolean - Detect rate limit responses\n- isTimeoutError(error: unknown): boolean - Detect timeout errors\n\nUse named constants:\n- DEFAULT_MAX_RETRIES = 3\n- BASE_RETRY_DELAY_MS = 1000\n- MAX_RETRY_DELAY_MS = 32000\n- BACKOFF_MULTIPLIER = 2\n- JITTER_FACTOR = 0.1\n\nEnsure each method stays under 30 lines by extracting complex logic into focused helper methods.\n</info added on 2025-08-20T17:16:38.315Z>",
+            "status": "done",
+            "testStrategy": "Create MockProvider extending BaseProvider to verify all abstract methods must be implemented and template method properly delegates to internal methods"
+          },
+          {
+            "id": 4,
+            "title": "Implement error handling and retry logic with exponential backoff",
+            "description": "Add comprehensive error handling and retry mechanism with exponential backoff for API calls in the template method",
+            "dependencies": [
+              "118.3"
+            ],
+            "details": "In generateCompletion() template method, wrap generateCompletionInternal() in try-catch with retry logic. Implement exponential backoff: delay * Math.pow(2, attempt). Add error types: ProviderError, RateLimitError, AuthenticationError extending Error. Log errors in development mode only. Handle specific error cases like rate limits (429), authentication errors (401), and network timeouts.",
+            "status": "done",
+            "testStrategy": "Test retry logic with MockProvider that fails N times then succeeds, verify exponential backoff timing, test different error scenarios and their handling"
+          },
+          {
+            "id": 5,
+            "title": "Add validation, logging, and completion options handling",
+            "description": "Implement input validation, debug logging for development, and proper handling of completion options like temperature and max tokens",
+            "dependencies": [
+              "118.4"
+            ],
+            "details": "Add validatePrompt() method to check for empty/invalid prompts. Add validateOptions() to ensure temperature is between 0-2, maxTokens is positive. Implement debug logging using console.log only when NODE_ENV !== 'production'. Create CompletionOptions interface with optional temperature, maxTokens, topP, frequencyPenalty, presencePenalty. Ensure all validation errors throw descriptive ProviderError instances.",
+            "status": "done",
+            "testStrategy": "Test validation with invalid inputs (empty prompts, negative maxTokens, temperature > 2), verify logging only occurs in development, test option merging with defaults"
+          }
+        ]
+      },
+      {
+        "id": 119,
+        "title": "Implement Provider Factory with Dynamic Imports",
+        "description": "Create ProviderFactory class using Factory pattern for AI provider instantiation",
+        "details": "Implement ProviderFactory class in ai/provider-factory.ts with static create method. Use switch statement for provider selection ('anthropic', 'openai', 'google'). Implement dynamic imports for each provider to enable tree-shaking. Return Promise<IAIProvider> from create method. Handle unknown providers with meaningful error messages. Ensure proper typing for configuration object.",
+        "testStrategy": "Test factory with each provider type, verify dynamic imports work correctly, test error handling for unknown providers, mock dynamic imports for unit testing",
+        "priority": "medium",
+        "dependencies": [
+          118
+        ],
+        "status": "pending",
+        "subtasks": [
+          {
+            "id": 1,
+            "title": "Create ProviderFactory class structure and types",
+            "description": "Set up the ProviderFactory class file with proper TypeScript types and interfaces",
+            "dependencies": [],
+            "details": "Create ai/provider-factory.ts file. Define ProviderFactory class with static create method signature. Import IAIProvider interface from base provider. Define ProviderType as union type ('anthropic' | 'openai' | 'google'). Set up proper return type as Promise<IAIProvider> for the create method to support dynamic imports.\n<info added on 2025-08-20T17:16:56.506Z>\nClean code architecture implementation: Move to src/providers/ai/provider-factory.ts. Follow Single Responsibility Principle - factory only creates providers, no other responsibilities. Create validateProviderConfig() method for provider configuration validation. Define PROVIDER_NAMES constant object with provider string values. Implement create() method with early returns pattern for better readability. Apply Dependency Inversion - factory depends on IAIProvider interface abstraction, not concrete implementations. Keep method under 40 lines following clean code practices.\n</info added on 2025-08-20T17:16:56.506Z>",
+            "status": "pending",
+            "testStrategy": "Verify file structure and type definitions compile correctly"
+          },
+          {
+            "id": 2,
+            "title": "Implement provider selection logic with switch statement",
+            "description": "Add the core switch statement logic to handle different provider types",
+            "dependencies": [
+              "119.1"
+            ],
+            "details": "Inside the static create method, implement switch statement on provider type parameter. Add cases for 'anthropic', 'openai', and 'google'. Add default case that throws a descriptive error for unknown providers (e.g., throw new Error(`Unknown provider: ${providerType}`)). Structure each case to prepare for dynamic imports.",
+            "status": "pending",
+            "testStrategy": "Test switch statement with valid and invalid provider types, verify error messages"
+          },
+          {
+            "id": 3,
+            "title": "Add dynamic imports for each provider",
+            "description": "Implement dynamic import() statements for lazy loading provider modules",
+            "dependencies": [
+              "119.2"
+            ],
+            "details": "In each switch case, use dynamic import() to load the provider module: for 'anthropic' case use await import('./providers/anthropic-provider'), similar for OpenAI and Google providers. Extract the default export or specific class from each dynamic import. This enables tree-shaking by only loading the selected provider.",
+            "status": "pending",
+            "testStrategy": "Mock dynamic imports in tests, verify only requested provider is loaded"
+          },
+          {
+            "id": 4,
+            "title": "Instantiate providers with configuration",
+            "description": "Create provider instances with proper configuration passing",
+            "dependencies": [
+              "119.3"
+            ],
+            "details": "After each dynamic import, instantiate the provider class with the configuration object passed to create method. Ensure configuration object is properly typed (use IConfiguration or relevant subset). Return the instantiated provider instance. Handle any instantiation errors and wrap them with context about which provider failed.",
+            "status": "pending",
+            "testStrategy": "Test provider instantiation with various configuration objects, verify configuration is passed correctly"
+          },
+          {
+            "id": 5,
+            "title": "Add error handling and validation",
+            "description": "Implement comprehensive error handling for all failure scenarios",
+            "dependencies": [
+              "119.4"
+            ],
+            "details": "Wrap dynamic imports in try-catch blocks to handle module loading failures. Add validation for configuration object before passing to providers. Create custom error messages that include the provider type and specific failure reason. Consider adding a ProviderFactoryError custom error class. Ensure all errors bubble up properly while maintaining async/await chain.",
+            "status": "pending",
+            "testStrategy": "Test various error scenarios: missing provider modules, invalid configurations, network failures during dynamic import"
+          }
+        ]
+      },
+      {
+        "id": 120,
+        "title": "Implement Anthropic Provider",
+        "description": "Create AnthropicProvider class extending BaseProvider with full Anthropic SDK integration",
+        "details": "Create AnthropicProvider class in ai/providers/anthropic-provider.ts extending BaseProvider. Import and use @anthropic-ai/sdk. Initialize private client property in constructor. Implement all abstract methods: generateCompletion using Claude API, calculateTokens using appropriate tokenizer, getName returning 'anthropic', getModel returning current model, getDefaultModel returning 'claude-3-sonnet-20240229'. Wrap API errors with context.",
+        "testStrategy": "Mock Anthropic SDK for unit tests, test API error handling, verify token calculation accuracy, test with different model configurations",
+        "priority": "high",
+        "dependencies": [
+          118
+        ],
+        "status": "pending",
+        "subtasks": [
+          {
+            "id": 1,
+            "title": "Set up AnthropicProvider class structure and dependencies",
+            "description": "Create the AnthropicProvider class file with proper imports and class structure extending BaseProvider",
+            "dependencies": [],
+            "details": "Create ai/providers/anthropic-provider.ts file. Import BaseProvider from base-provider.ts and import Anthropic from @anthropic-ai/sdk. Import necessary types including IAIProvider, ChatMessage, and ChatCompletion. Set up the class declaration extending BaseProvider with proper TypeScript typing. Add private client property declaration of type Anthropic.\n<info added on 2025-08-20T17:17:15.019Z>\nFile should be created at src/providers/ai/adapters/anthropic-provider.ts instead of ai/providers/anthropic-provider.ts. Follow clean code principles: keep constructor minimal (under 10 lines) with only client initialization. Extract API call logic into separate small methods (each under 20 lines). Use early returns in generateCompletionInternal() for better readability. Extract error mapping logic to a dedicated mapAnthropicError() method. Avoid magic strings - define constants for model names and API parameters.\n</info added on 2025-08-20T17:17:15.019Z>",
+            "status": "pending",
+            "testStrategy": "Verify file structure and imports compile without errors, ensure class properly extends BaseProvider"
+          },
+          {
+            "id": 2,
+            "title": "Implement constructor and client initialization",
+            "description": "Create the constructor that accepts configuration and initializes the Anthropic SDK client",
+            "dependencies": [
+              "120.1"
+            ],
+            "details": "Implement constructor accepting IConfiguration parameter. Call super(config) to initialize BaseProvider. Initialize the private client property by creating new Anthropic instance with apiKey from config.apiKeys.anthropic. Add validation to ensure API key exists, throwing meaningful error if missing. Store the model configuration from config.model or use default.",
+            "status": "pending",
+            "testStrategy": "Test constructor with valid and invalid configurations, verify client initialization, test API key validation"
+          },
+          {
+            "id": 3,
+            "title": "Implement generateCompletion method with Claude API",
+            "description": "Implement the main generateCompletion method that calls Anthropic's Claude API and handles responses",
+            "dependencies": [
+              "120.2"
+            ],
+            "details": "Implement async generateCompletion method accepting ChatMessage array. Map ChatMessage format to Anthropic's expected format (role and content). Use client.messages.create() with appropriate parameters including model, max_tokens, and messages. Transform Anthropic response format to ChatCompletion interface. Handle streaming vs non-streaming responses. Implement proper error handling wrapping API errors with context.",
+            "status": "pending",
+            "testStrategy": "Mock Anthropic SDK client.messages.create, test with various message formats, verify response transformation, test error scenarios"
+          },
+          {
+            "id": 4,
+            "title": "Implement token calculation and utility methods",
+            "description": "Implement calculateTokens method and other required abstract methods from BaseProvider",
+            "dependencies": [
+              "120.3"
+            ],
+            "details": "Implement calculateTokens method using appropriate tokenizer (tiktoken or claude-tokenizer if available). Implement getName method returning 'anthropic' string constant. Implement getModel method returning current model from configuration. Implement getDefaultModel method returning 'claude-3-sonnet-20240229'. Add any additional helper methods for token counting or message formatting.",
+            "status": "pending",
+            "testStrategy": "Test token calculation accuracy with various input strings, verify utility methods return correct values"
+          },
+          {
+            "id": 5,
+            "title": "Add comprehensive error handling and type exports",
+            "description": "Implement robust error handling throughout the class and ensure proper TypeScript exports",
+            "dependencies": [
+              "120.4"
+            ],
+            "details": "Wrap all Anthropic API calls in try-catch blocks. Create custom error messages that include context about the operation being performed. Handle rate limiting errors specifically. Ensure all methods have proper TypeScript return types. Export the AnthropicProvider class as default export. Add JSDoc comments for all public methods. Ensure proper error propagation maintaining stack traces.",
+            "status": "pending",
+            "testStrategy": "Test various API error scenarios, verify error messages include context, test rate limit handling, ensure TypeScript types are correctly exported"
+          }
+        ]
+      },
+      {
+        "id": 121,
+        "title": "Create Prompt Builder and Task Parser",
+        "description": "Implement PromptBuilder class and TaskParser with Dependency Injection",
+        "details": "Create PromptBuilder class with buildParsePrompt and buildExpandPrompt methods using template literals. Include specific JSON format instructions. Create TaskParser class accepting IAIProvider and IConfiguration via constructor (Dependency Injection). Implement parsePRD method to read PRD file, use PromptBuilder to create prompt, call AI provider, extract tasks from response, and enrich with metadata. Handle parsing errors gracefully.",
+        "testStrategy": "Unit test prompt building with various inputs, mock AI provider responses, test JSON extraction logic, verify error handling for malformed responses, integration test with real PRD files",
+        "priority": "high",
+        "dependencies": [
+          119,
+          120
+        ],
+        "status": "pending",
+        "subtasks": [
+          {
+            "id": 1,
+            "title": "Create PromptBuilder Class Structure",
+            "description": "Implement the PromptBuilder class with template methods for generating AI prompts",
+            "dependencies": [],
+            "details": "Create src/services/prompt-builder.ts. Define PromptBuilder class with two public methods: buildParsePrompt(prdContent: string): string and buildExpandPrompt(task: Task): string. Use template literals to construct prompts with clear JSON format instructions. Include system instructions for AI to follow specific output formats. Add private helper methods for common prompt sections like JSON schema definitions and response format examples.\n<info added on 2025-08-20T17:17:31.467Z>\nRefactor to src/services/prompts/prompt-builder.ts to separate concerns. Implement buildTaskPrompt() method. Define prompt template constants: PARSE_PROMPT_TEMPLATE, EXPAND_PROMPT_TEMPLATE, TASK_PROMPT_TEMPLATE, JSON_FORMAT_INSTRUCTIONS. Move JSON schema definitions and format instructions to constants. Ensure each template uses template literals with ${} placeholders. Keep all methods under 40 lines by extracting logic into focused helper methods. Use descriptive constant names for all repeated strings or instruction blocks.\n</info added on 2025-08-20T17:17:31.467Z>",
+            "status": "pending",
+            "testStrategy": "Unit test both prompt methods with sample inputs. Verify prompt contains required JSON structure instructions. Test edge cases like empty PRD content or minimal task objects."
+          },
+          {
+            "id": 2,
+            "title": "Implement TaskParser Class with DI",
+            "description": "Create TaskParser class accepting IAIProvider and IConfiguration through constructor injection",
+            "dependencies": [
+              "121.1"
+            ],
+            "details": "Create src/services/task-parser.ts. Define TaskParser class with constructor(private aiProvider: IAIProvider, private config: IConfiguration). Add private promptBuilder property initialized in constructor. Implement basic class structure with placeholder methods. Ensure proper TypeScript typing for all parameters and properties. Follow dependency injection pattern for testability.\n<info added on 2025-08-20T17:17:49.624Z>\nUpdate file location to src/services/tasks/task-parser.ts instead of src/services/task-parser.ts. Refactor parsePRD() method to stay under 40 lines by extracting logic into helper methods: readPRD(), validatePRD(), extractTasksFromResponse(), and enrichTasksWithMetadata(). Each helper method should be under 20 lines. Implement early returns in validation methods for cleaner code flow. Remove any file I/O operations from the parser class - delegate all storage operations to injected dependencies. Ensure clean separation of concerns with parser focused only on task parsing logic.\n</info added on 2025-08-20T17:17:49.624Z>",
+            "status": "pending",
+            "testStrategy": "Test constructor properly stores injected dependencies. Verify class instantiation with mock providers. Test TypeScript compilation with proper interface implementations."
+          },
+          {
+            "id": 3,
+            "title": "Implement parsePRD Method Core Logic",
+            "description": "Create the main parsePRD method that orchestrates the PRD parsing workflow",
+            "dependencies": [
+              "121.2"
+            ],
+            "details": "Implement parsePRD(filePath: string): Promise<ParsedTask[]> method in TaskParser. Read PRD file using fs.promises.readFile. Use promptBuilder.buildParsePrompt() to create AI prompt. Call aiProvider.generateResponse() with constructed prompt. Extract JSON array from AI response using regex or JSON.parse. Handle potential parsing errors with try-catch blocks. Return empty array on errors after logging.",
+            "status": "pending",
+            "testStrategy": "Test with mock AI provider returning valid JSON. Test file reading with various file paths. Mock file system for controlled testing. Verify proper error logging without throwing."
+          },
+          {
+            "id": 4,
+            "title": "Add Task Enrichment and Metadata",
+            "description": "Enhance parsed tasks with additional metadata and validation",
+            "dependencies": [
+              "121.3"
+            ],
+            "details": "After extracting tasks from AI response, enrich each task with metadata: add createdAt timestamp, set initial status to 'pending', validate required fields (id, title, description). Add priority field with default 'medium' if not provided. Ensure all tasks have valid structure before returning. Create private enrichTask(task: any): ParsedTask method for this logic. Handle missing or malformed task data gracefully.",
+            "status": "pending",
+            "testStrategy": "Test enrichment adds all required metadata. Verify validation catches malformed tasks. Test default values are applied correctly. Ensure timestamps are properly formatted."
+          },
+          {
+            "id": 5,
+            "title": "Implement Comprehensive Error Handling",
+            "description": "Add robust error handling throughout the TaskParser implementation",
+            "dependencies": [
+              "121.4"
+            ],
+            "details": "Wrap file reading in try-catch to handle FILE_NOT_FOUND errors. Catch AI provider errors and wrap in appropriate TaskMasterError. Handle JSON parsing errors when extracting from AI response. Add specific error handling for network timeouts, rate limits, and malformed responses. Log errors with context in development mode only. Return meaningful error messages without exposing internals. Ensure all errors are properly typed as TaskMasterError instances.",
+            "status": "pending",
+            "testStrategy": "Test each error scenario separately: missing files, AI provider failures, malformed JSON, network errors. Verify proper error codes are used. Test that errors don't expose sensitive information."
+          }
+        ]
+      },
+      {
+        "id": 122,
+        "title": "Implement Configuration Management",
+        "description": "Create ConfigManager class with Zod validation for configuration",
+        "details": "Implement ConfigManager in config/config-manager.ts accepting Partial<IConfiguration> in constructor. Use Zod to create validation schema matching IConfiguration interface. Implement get method with TypeScript generics for type-safe access, getAll returning full config, validate method for validation. Set defaults: projectPath = process.cwd(), aiProvider = 'anthropic', enableTags = true. Handle validation errors with clear messages.",
+        "testStrategy": "Test with various configuration combinations, verify Zod validation catches invalid configs, test default values, ensure type safety of get method",
+        "priority": "medium",
+        "dependencies": [
+          116
+        ],
+        "status": "in-progress",
+        "subtasks": [
+          {
+            "id": 1,
+            "title": "Create Zod validation schema for IConfiguration",
+            "description": "Define a Zod schema that matches the IConfiguration interface structure with proper validation rules",
+            "dependencies": [],
+            "details": "Create configSchema in config/config-manager.ts using z.object() to define validation for all IConfiguration properties. Include string validations for projectPath, enum validation for aiProvider ('anthropic', 'openai', etc.), boolean for enableTags, and any other configuration fields. Use z.string().min(1) for required strings, z.enum() for provider types, and appropriate validators for other fields.\n<info added on 2025-08-06T13:14:58.822Z>\nCompleted Zod validation schema implementation in packages/tm-core/src/config/validation.ts\n\nIMPLEMENTATION DETAILS:\n- Created comprehensive Zod schemas matching IConfiguration interface structure exactly\n- All required schemas exported as expected by config-schema.ts:\n  * configurationSchema - Main configuration validation with custom refinements\n  * partialConfigurationSchema - For partial updates (using base schema without refinements)\n  * modelConfigSchema - Model configuration validation\n  * providerConfigSchema - AI provider configuration validation  \n  * taskSettingsSchema - Task management settings validation\n  * loggingSettingsSchema/loggingConfigSchema - Logging configuration (with legacy alias)\n  * tagSettingsSchema - Tag management settings validation\n  * storageSettingsSchema - Storage configuration validation\n  * retrySettingsSchema - Retry/resilience settings validation\n  * securitySettingsSchema - Security settings validation\n  * cacheConfigSchema - Cache configuration stub (for consistency)\n\nKEY FEATURES:\n- Proper Zod validation rules applied (string lengths, number ranges, enums)\n- Custom refinements for business logic (maxRetryDelay >= retryDelay)\n- Comprehensive enum schemas for all union types\n- Legacy alias support for backwards compatibility\n- All 13 nested interface schemas implemented with appropriate constraints\n- Type exports for runtime validation\n\nVALIDATION INCLUDES:\n- String validations with min lengths for required fields\n- Enum validation for providers, priorities, complexities, log levels, etc.\n- Number range validations (min/max constraints)\n- URL validation for baseUrl fields\n- Array validations with proper item types\n- Record validations for dynamic key-value pairs\n- Optional field handling with appropriate defaults\n\nTESTED AND VERIFIED:\n- All schemas compile correctly with TypeScript\n- Import/export chain works properly through config-schema.ts\n- Basic validation tests pass for key schemas\n- No conflicts with existing IConfiguration interface structure\n</info added on 2025-08-06T13:14:58.822Z>\n<info added on 2025-08-20T17:18:12.343Z>\nCreated ConfigManager class at src/config/config-manager.ts with the following implementation:\n\nSTRUCTURE:\n- DEFAULT_CONFIG constant defined with complete default values for all configuration properties\n- Constructor validates config using validate() method (follows Fail-Fast principle)\n- Constructor kept under 15 lines as required\n- Type-safe get<K>() method using TypeScript generics for accessing specific config properties\n- getAll() method returns complete validated configuration\n- validate() method extracted for configuration validation using Zod schema\n- mergeWithDefaults() helper extracted for merging partial config with defaults\n\nKEY IMPLEMENTATION DETAILS:\n- Imports configurationSchema from src/config/schemas/config.schema.ts\n- Uses z.infer<typeof configurationSchema> for type safety\n- Validates on construction with clear error messages\n- No nested ternaries used\n- Proper error handling with ConfigValidationError\n- Type-safe property access with keyof IConfiguration constraint\n\nMETHODS:\n- constructor(config?: Partial<IConfiguration>) - Validates and stores config\n- get<K extends keyof IConfiguration>(key: K): IConfiguration[K] - Type-safe getter\n- getAll(): IConfiguration - Returns full config\n- private validate(config: unknown): IConfiguration - Validates using Zod\n- private mergeWithDefaults(config: Partial<IConfiguration>): IConfiguration - Merges with defaults\n\nAlso created src/config/schemas/config.schema.ts importing the configurationSchema from validation.ts for cleaner organization.\n</info added on 2025-08-20T17:18:12.343Z>",
+            "status": "review",
+            "testStrategy": "Test schema validation with valid and invalid configurations, ensure all IConfiguration fields are covered"
+          },
+          {
+            "id": 2,
+            "title": "Implement ConfigManager class constructor and storage",
+            "description": "Create ConfigManager class with constructor that accepts Partial<IConfiguration> and initializes configuration with defaults",
+            "dependencies": [
+              "122.1"
+            ],
+            "details": "Define ConfigManager class with private config property. In constructor, merge provided partial config with defaults (projectPath = process.cwd(), aiProvider = 'anthropic', enableTags = true). Store the merged configuration internally. Ensure the class is properly typed with IConfiguration interface.",
+            "status": "pending",
+            "testStrategy": "Test constructor with various partial configs, verify defaults are applied correctly, test with empty config"
+          },
+          {
+            "id": 3,
+            "title": "Implement validate method with error handling",
+            "description": "Create validate method that uses Zod schema to validate configuration and provides clear error messages",
+            "dependencies": [
+              "122.1",
+              "122.2"
+            ],
+            "details": "Implement validate(): void method that runs configSchema.parse(this.config) within try-catch block. On ZodError, transform the error into user-friendly messages that clearly indicate which fields are invalid and why. Consider creating a custom error class for configuration validation errors. The method should throw if validation fails.",
+            "status": "pending",
+            "testStrategy": "Test with invalid configs to ensure proper error messages, verify all validation rules work correctly"
+          },
+          {
+            "id": 4,
+            "title": "Implement type-safe get method with generics",
+            "description": "Create generic get method for retrieving individual configuration values with TypeScript type inference",
+            "dependencies": [
+              "122.2"
+            ],
+            "details": "Implement get<K extends keyof IConfiguration>(key: K): IConfiguration[K] method that returns the value for a specific configuration key. Use TypeScript generics and keyof operator to ensure type safety. The method should provide proper type inference so consumers get the correct type based on the key they request.",
+            "status": "pending",
+            "testStrategy": "Test type inference with different keys, verify TypeScript catches invalid keys at compile time"
+          },
+          {
+            "id": 5,
+            "title": "Implement getAll method and finalize class",
+            "description": "Create getAll method to return full configuration and ensure proper exports",
+            "dependencies": [
+              "122.2",
+              "122.3",
+              "122.4"
+            ],
+            "details": "Implement getAll(): IConfiguration method that returns a deep copy of the entire configuration object to prevent external mutations. Add JSDoc comments to all public methods. Export the ConfigManager class and ensure it's properly integrated with the module structure. Consider adding a static factory method if needed.",
+            "status": "pending",
+            "testStrategy": "Test getAll returns complete config, verify returned object is immutable, test integration with other modules"
+          }
+        ]
+      },
+      {
+        "id": 123,
+        "title": "Create Utility Functions and Error Handling",
+        "description": "Implement ID generation utilities and custom error classes",
+        "details": "Create id-generator.ts with generateTaskId and generateSubtaskId functions using specified formats with timestamp and random components. Create TaskMasterError class extending Error in errors/task-master-error.ts with error codes (FILE_NOT_FOUND, PARSE_ERROR, etc.). Ensure errors don't expose internal details. Add development-only logging.",
+        "testStrategy": "Test ID generation for uniqueness and format compliance, verify error classes properly extend Error, test error message formatting, ensure no sensitive data in errors",
+        "priority": "low",
+        "dependencies": [
+          116
+        ],
+        "status": "in-progress",
+        "subtasks": [
+          {
+            "id": 1,
+            "title": "Create ID generation utilities module",
+            "description": "Implement the id-generator.ts module with functions for generating unique task and subtask IDs",
+            "dependencies": [],
+            "details": "Create src/utils/id-generator.ts file. Implement generateTaskId() function that returns format 'TASK-{timestamp}-{random}' where timestamp is Date.now() and random is 4-character alphanumeric string. Implement generateSubtaskId(parentId) function that returns format '{parentId}.{sequential}' where sequential increments based on existing subtasks. Use crypto.randomBytes or Math.random for randomness. Export both functions as named exports.\n<info added on 2025-08-06T12:42:22.203Z>\nThe ID generator module has been successfully implemented with the following completed features:\n- generateTaskId() function that creates unique IDs in 'TASK-{timestamp}-{random}' format\n- generateSubtaskId() function that generates sequential subtask IDs in '{parentId}.{sequential}' format\n- Input validation functions to ensure ID integrity\n- Proper TypeScript type definitions and interfaces\n- Comprehensive JSDoc documentation with usage examples\n- All functions exported as named exports from src/utils/id-generator.ts\n</info added on 2025-08-06T12:42:22.203Z>",
+            "status": "done",
+            "testStrategy": "Test uniqueness by generating 1000 IDs and checking for duplicates, verify format compliance with regex, test subtask ID sequential numbering"
+          },
+          {
+            "id": 2,
+            "title": "Create base error class structure",
+            "description": "Implement the TaskMasterError base class that extends Error with proper error handling capabilities",
+            "dependencies": [],
+            "details": "Create src/errors/task-master-error.ts file. Define TaskMasterError class extending Error. Add constructor accepting (message: string, code: string, details?: any). Set this.name = 'TaskMasterError'. Create error code constants: FILE_NOT_FOUND = 'FILE_NOT_FOUND', PARSE_ERROR = 'PARSE_ERROR', VALIDATION_ERROR = 'VALIDATION_ERROR', API_ERROR = 'API_ERROR'. Override toString() to format errors appropriately. Ensure stack trace is preserved.\n<info added on 2025-08-06T13:13:11.635Z>\nCompleted TaskMasterError base class implementation:\n\nIMPLEMENTATION DETAILS:\n- TaskMasterError class fully implemented extending Error\n- Added proper prototype chain fix with Object.setPrototypeOf(this, TaskMasterError.prototype)\n- Includes all required properties: code (from ERROR_CODES), timestamp, context, cause\n- toJSON method implemented for full serialization support\n- Error sanitization implemented via getSanitizedDetails() and containsSensitiveInfo() methods\n- Error chaining with cause property fully supported\n- Additional utility methods: getUserMessage(), toString(), is(), hasCode(), withContext(), wrap()\n\nSUCCESS CRITERIA VERIFIED:\n✅ TaskMasterError class fully implemented\n✅ Extends Error with proper prototype chain fix (Object.setPrototypeOf)\n✅ Includes all required properties and methods\n✅ toJSON method for serialization\n✅ Error sanitization logic for production (containsSensitiveInfo method)\n✅ Comprehensive error context and metadata support\n\nFILE MODIFIED: packages/tm-core/src/errors/task-master-error.ts\n</info added on 2025-08-06T13:13:11.635Z>\n<info added on 2025-08-20T17:18:38.499Z>\nRefactored to follow clean code principles:\n\nCLEAN CODE IMPROVEMENTS:\n- Moved TaskMasterError class to be under 40 lines by extracting methods\n- Created separate error-codes.ts file with ERROR_CODES constant object\n- Extracted sanitizeMessage() method to handle message sanitization\n- Extracted addContext() method for adding error context\n- Extracted toJSON() method for serialization\n- Added static factory methods: fromError(), notFound(), parseError(), validationError(), apiError()\n- Improved error chaining with proper 'cause' property handling\n- Ensured user-friendly messages that hide implementation details\n- Maintained all existing functionality while improving code organization\n\nFILES CREATED/MODIFIED:\n- packages/tm-core/src/errors/error-codes.ts (new file with ERROR_CODES)\n- packages/tm-core/src/errors/task-master-error.ts (refactored to under 40 lines)\n</info added on 2025-08-20T17:18:38.499Z>",
+            "status": "review",
+            "testStrategy": "Test that error extends Error properly, verify error.name is set correctly, test toString() output format, ensure stack trace exists"
+          },
+          {
+            "id": 3,
+            "title": "Implement error sanitization and security features",
+            "description": "Add security features to prevent exposure of sensitive internal details in error messages",
+            "dependencies": [
+              "123.2"
+            ],
+            "details": "In TaskMasterError class, add private sanitizeDetails() method that removes sensitive data like API keys, file paths beyond project root, and internal state. Implement toJSON() method that returns sanitized error object for external consumption. Add static isSafeForProduction() method to validate error messages don't contain patterns like absolute paths, environment variables, or API credentials. Store original details in private property for debugging.",
+            "status": "pending",
+            "testStrategy": "Test sanitization removes absolute paths, API keys, and sensitive patterns, verify toJSON returns safe object, test original details are preserved internally"
+          },
+          {
+            "id": 4,
+            "title": "Add development-only logging functionality",
+            "description": "Implement conditional logging that only operates in development environment",
+            "dependencies": [
+              "123.2",
+              "123.3"
+            ],
+            "details": "In task-master-error.ts, add static enableDevLogging property defaulting to process.env.NODE_ENV !== 'production'. Add logError() method that console.error's full error details only when enableDevLogging is true. Include timestamp, error code, sanitized message, and full stack trace in dev logs. In production, log only error code and safe message. Create static setDevLogging(enabled: boolean) to control logging.",
+            "status": "pending",
+            "testStrategy": "Test logging output in dev vs production modes, verify sensitive data isn't logged in production, test log format includes all required fields"
+          },
+          {
+            "id": 5,
+            "title": "Create specialized error subclasses",
+            "description": "Implement specific error classes for different error scenarios inheriting from TaskMasterError",
+            "dependencies": [
+              "123.2",
+              "123.3",
+              "123.4"
+            ],
+            "details": "Create FileNotFoundError extending TaskMasterError with code FILE_NOT_FOUND, accepting filePath parameter. Create ParseError with code PARSE_ERROR for parsing failures, accepting source and line number. Create ValidationError with code VALIDATION_ERROR for data validation, accepting field and value. Create APIError with code API_ERROR for external API failures, accepting statusCode and provider. Each should format appropriate user-friendly messages while storing technical details internally.",
+            "status": "pending",
+            "testStrategy": "Test each error class constructor and message formatting, verify inheritance chain, test that each error type has correct code, ensure specialized errors work with logging system"
+          }
+        ]
+      },
+      {
+        "id": 124,
+        "title": "Implement TaskMasterCore Facade",
+        "description": "Create main TaskMasterCore class as Facade pattern entry point",
+        "details": "Create TaskMasterCore class in index.ts with private properties for config, storage, aiProvider, and parser. Implement initialize method for lazy loading of AI provider. Implement parsePRD method that coordinates parser, storage, and configuration. Implement getTasks for retrieving stored tasks. Apply Facade pattern to hide complexity. Export createTaskMaster factory function, all types and interfaces. Use proper import paths with .js extensions for ESM.",
+        "testStrategy": "Integration test full parse flow, test lazy initialization, verify facade properly delegates to subsystems, test with different configurations, ensure exports are correct",
+        "priority": "high",
+        "dependencies": [
+          117,
+          121,
+          122
+        ],
+        "status": "pending",
+        "subtasks": [
+          {
+            "id": 1,
+            "title": "Create TaskMasterCore class structure with type definitions",
+            "description": "Set up the main TaskMasterCore class in src/index.ts with all necessary imports, type definitions, and class structure following the Facade pattern",
+            "dependencies": [],
+            "details": "Create src/index.ts file. Import IConfiguration, ITaskStorage, IAIProvider, and IPRDParser interfaces. Define TaskMasterCore class with private properties: _config (ConfigManager), _storage (ITaskStorage), _aiProvider (IAIProvider | null), _parser (IPRDParser | null). Add constructor accepting options parameter of type Partial<IConfiguration>. Initialize _config with ConfigManager, set other properties to null for lazy loading. Import all necessary types from their respective modules using .js extensions for ESM compatibility.\n<info added on 2025-08-20T17:18:56.625Z>\nApply Facade pattern principles: simple public interface, hide subsystem complexity. Keep all methods under 30 lines by extracting logic. Implement lazy initialization pattern in initialize() method - only create dependencies when first needed. Extract createDependencies() private helper method to handle creation of storage, AI provider, and parser instances. Add createTaskMaster() factory function for convenient instance creation. Use barrel exports pattern - export all public types and interfaces that clients need (IConfiguration, ITaskStorage, IAIProvider, IPRDParser, TaskMasterCore). Follow Interface Segregation Principle - only expose methods and types that clients actually need, hide internal implementation details.\n</info added on 2025-08-20T17:18:56.625Z>",
+            "status": "pending",
+            "testStrategy": "Test class instantiation with various configuration options, verify private properties are correctly initialized, ensure TypeScript types are properly enforced"
+          },
+          {
+            "id": 2,
+            "title": "Implement initialize method for lazy loading",
+            "description": "Create the initialize method that handles lazy loading of AI provider and parser instances based on configuration",
+            "dependencies": [
+              "124.1"
+            ],
+            "details": "Implement async initialize() method in TaskMasterCore. Check if _aiProvider is null, if so create appropriate provider based on config.aiProvider value using a factory pattern or switch statement. Similarly initialize _parser if null. Store instances in private properties for reuse. Handle provider initialization errors gracefully. Ensure method is idempotent - calling multiple times should not recreate instances. Use dynamic imports if needed for code splitting.",
+            "status": "pending",
+            "testStrategy": "Test lazy initialization occurs only once, verify correct provider is instantiated based on config, test error handling for invalid providers, ensure idempotency"
+          },
+          {
+            "id": 3,
+            "title": "Implement parsePRD method with coordination logic",
+            "description": "Create parsePRD method that coordinates the parser, AI provider, and storage to parse PRD content and store results",
+            "dependencies": [
+              "124.1",
+              "124.2"
+            ],
+            "details": "Implement async parsePRD(content: string) method. First call initialize() to ensure components are loaded. Use _parser.parse() to parse the PRD content, passing the AI provider for task generation. Take the parsed tasks and use _storage.saveTasks() to persist them. Handle errors from parser or storage operations. Return the parsed tasks array. Implement proper error context and logging for debugging.",
+            "status": "pending",
+            "testStrategy": "Integration test with mock parser and storage, verify coordination between components, test error propagation from subsystems, ensure tasks are properly stored"
+          },
+          {
+            "id": 4,
+            "title": "Implement getTasks method and other facade methods",
+            "description": "Create getTasks method and any other necessary facade methods to retrieve and manage tasks",
+            "dependencies": [
+              "124.1"
+            ],
+            "details": "Implement async getTasks() method that calls _storage.loadTasks() and returns the tasks array. Add getTask(id: string) for retrieving single task. Consider adding updateTask, deleteTask methods if needed. All methods should follow facade pattern - simple interface hiding complex operations. Add proper TypeScript return types for all methods. Handle storage not initialized scenarios.",
+            "status": "pending",
+            "testStrategy": "Test task retrieval with various scenarios, verify proper delegation to storage, test edge cases like empty task lists or invalid IDs"
+          },
+          {
+            "id": 5,
+            "title": "Create factory function and module exports",
+            "description": "Implement createTaskMaster factory function and set up all module exports including types and interfaces",
+            "dependencies": [
+              "124.1",
+              "124.2",
+              "124.3",
+              "124.4"
+            ],
+            "details": "Create createTaskMaster(options?: Partial<IConfiguration>) factory function that returns a new TaskMasterCore instance. Export this as the primary entry point. Re-export all types and interfaces from submodules: ITask, IConfiguration, IAIProvider, ITaskStorage, IPRDParser, etc. Use 'export type' for type-only exports. Ensure all imports use .js extensions for ESM. Create index.d.ts if needed for better TypeScript support. Add JSDoc comments for public API.",
+            "status": "pending",
+            "testStrategy": "Test factory function creates proper instances, verify all exports are accessible, test TypeScript type inference works correctly, ensure ESM imports resolve properly"
+          }
+        ]
+      },
+      {
+        "id": 125,
+        "title": "Create Placeholder Providers and Complete Testing",
+        "description": "Implement placeholder providers for OpenAI and Google, create comprehensive test suite",
+        "details": "Create OpenAIProvider and GoogleProvider classes extending BaseProvider, throwing 'not yet implemented' errors. Create MockProvider in tests/mocks for testing without API calls. Write unit tests for TaskParser, integration tests for parse-prd flow, ensure 80% code coverage. Follow kebab-case naming for test files. Test error scenarios comprehensively.",
+        "testStrategy": "Run full test suite with coverage report, verify all edge cases are tested, ensure mock provider behaves like real providers, test both success and failure paths",
+        "priority": "medium",
+        "dependencies": [
+          120,
+          124
+        ],
+        "status": "pending",
+        "subtasks": [
+          {
+            "id": 1,
+            "title": "Create OpenAIProvider placeholder class",
+            "description": "Implement OpenAIProvider class that extends BaseProvider with all required methods throwing 'not yet implemented' errors",
+            "dependencies": [],
+            "details": "Create src/providers/openai-provider.ts file. Import BaseProvider from base-provider.ts. Implement class OpenAIProvider extends BaseProvider. Override parseText() method to throw new Error('OpenAI provider not yet implemented'). Add proper TypeScript types and JSDoc comments. Export the class as default.",
+            "status": "pending",
+            "testStrategy": "Write unit test to verify OpenAIProvider extends BaseProvider correctly and throws expected error when parseText is called"
+          },
+          {
+            "id": 2,
+            "title": "Create GoogleProvider placeholder class",
+            "description": "Implement GoogleProvider class that extends BaseProvider with all required methods throwing 'not yet implemented' errors",
+            "dependencies": [],
+            "details": "Create src/providers/google-provider.ts file. Import BaseProvider from base-provider.ts. Implement class GoogleProvider extends BaseProvider. Override parseText() method to throw new Error('Google provider not yet implemented'). Add proper TypeScript types and JSDoc comments. Export the class as default.",
+            "status": "pending",
+            "testStrategy": "Write unit test to verify GoogleProvider extends BaseProvider correctly and throws expected error when parseText is called"
+          },
+          {
+            "id": 3,
+            "title": "Create MockProvider for testing",
+            "description": "Implement MockProvider class in tests/mocks directory that simulates provider behavior without making actual API calls",
+            "dependencies": [],
+            "details": "Create tests/mocks/mock-provider.ts file. Extend BaseProvider class. Implement parseText() to return predefined mock task data based on input. Add methods to configure mock responses, simulate errors, and track method calls. Include delay simulation for realistic testing. Export class and helper functions for test setup.",
+            "status": "pending",
+            "testStrategy": "Test MockProvider returns consistent mock data, can simulate different scenarios (success/failure), and properly tracks method invocations"
+          },
+          {
+            "id": 4,
+            "title": "Write unit tests for TaskParser",
+            "description": "Create comprehensive unit tests for TaskParser class covering all methods and edge cases",
+            "dependencies": [
+              "125.3"
+            ],
+            "details": "Create tests/unit/task-parser.test.ts file. Test TaskParser constructor with different providers. Test parseFromText method with valid/invalid inputs. Test error handling for malformed responses. Use MockProvider to simulate API responses. Test task ID generation and structure validation. Ensure all public methods are covered.",
+            "status": "pending",
+            "testStrategy": "Achieve 100% code coverage for TaskParser class, test both success and failure paths, verify error messages are appropriate"
+          },
+          {
+            "id": 5,
+            "title": "Write integration tests for parse-prd flow",
+            "description": "Create end-to-end integration tests for the complete PRD parsing workflow",
+            "dependencies": [
+              "125.3",
+              "125.4"
+            ],
+            "details": "Create tests/integration/parse-prd-flow.test.ts file. Test full flow from PRD input to task output. Test with MockProvider simulating successful parsing. Test error scenarios (file not found, parse errors, network failures). Test task dependency resolution. Verify output format matches expected structure. Test with different PRD formats and sizes.",
+            "status": "pending",
+            "testStrategy": "Run coverage report to ensure 80% overall coverage, verify all critical paths are tested, ensure tests are deterministic and don't depend on external services"
+          }
+        ]
+      }
+    ],
+    "metadata": {
+      "created": "2025-08-06T08:51:19.649Z",
+      "updated": "2025-08-20T21:32:21.837Z",
+      "description": "Tasks for tm-core-phase-1 context"
+    }
   }
 }

.vscode/settings.json

@@ -10,5 +10,18 @@
 	},
 
 	"json.format.enable": true,
-	"json.validate.enable": true
+	"json.validate.enable": true,
+	"typescript.tsdk": "node_modules/typescript/lib",
+	"[typescript]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[typescriptreact]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[javascript]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[json]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	}
 }

CHANGELOG.md

@@ -1,5 +1,211 @@
 # task-master-ai
 
+## 0.26.0
+
+### Minor Changes
+
+- [#1133](https://github.com/eyaltoledano/claude-task-master/pull/1133) [`df26c65`](https://github.com/eyaltoledano/claude-task-master/commit/df26c65632000874a73504963b08f18c46283144) Thanks [@neonwatty](https://github.com/neonwatty)! - Restore Taskmaster claude-code commands and move clear commands under /remove to avoid collision with the claude-code /clear command.
+
+- [#1163](https://github.com/eyaltoledano/claude-task-master/pull/1163) [`37af0f1`](https://github.com/eyaltoledano/claude-task-master/commit/37af0f191227a68d119b7f89a377bf932ee3ac66) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Enhanced Gemini CLI provider with codebase-aware task generation
+
+  Added automatic codebase analysis for Gemini CLI provider in parse-prd, and analyze-complexity, add-task, udpate-task, update, update-subtask commands
+  When using Gemini CLI as the AI provider, Task Master now instructs the AI to analyze the project structure, existing implementations, and patterns before generating tasks or subtasks
+  Tasks and subtasks generated by Claude Code are now informed by actual codebase analysis, resulting in more accurate and contextual outputs
+
+- [#1165](https://github.com/eyaltoledano/claude-task-master/pull/1165) [`c4f92f6`](https://github.com/eyaltoledano/claude-task-master/commit/c4f92f6a0aee3435c56eb8d27d9aa9204284833e) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Add configurable codebase analysis feature flag with multiple configuration sources
+
+  Users can now control whether codebase analysis features (Claude Code and Gemini CLI integration) are enabled through environment variables, MCP configuration, or project config files.
+
+  Priority order: .env > MCP session env > .taskmaster/config.json.
+
+  Set `TASKMASTER_ENABLE_CODEBASE_ANALYSIS=false` in `.env` to disable codebase analysis prompts and tool integration.
+
+- [#1135](https://github.com/eyaltoledano/claude-task-master/pull/1135) [`8783708`](https://github.com/eyaltoledano/claude-task-master/commit/8783708e5e3389890a78fcf685d3da0580e73b3f) Thanks [@mm-parthy](https://github.com/mm-parthy)! - feat(move): improve cross-tag move UX and safety
+  - CLI: print "Next Steps" tips after cross-tag moves that used --ignore-dependencies (validate/fix guidance)
+  - CLI: show dedicated help block on ID collisions (destination tag already has the ID)
+  - Core: add structured suggestions to TASK_ALREADY_EXISTS errors
+  - MCP: map ID collision errors to TASK_ALREADY_EXISTS and include suggestions
+  - Tests: cover MCP options, error suggestions, CLI tips printing, and integration error payload suggestions
+
+  ***
+
+- [#1162](https://github.com/eyaltoledano/claude-task-master/pull/1162) [`4dad2fd`](https://github.com/eyaltoledano/claude-task-master/commit/4dad2fd613ceac56a65ae9d3c1c03092b8860ac9) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Enhanced Claude Code and Google CLI integration with automatic codebase analysis for task operations
+
+  When using Claude Code as the AI provider, task management commands now automatically analyze your codebase before generating or updating tasks. This provides more accurate, context-aware implementation details that align with your project's existing architecture and patterns.
+
+  Commands contextualised:
+  - add-task
+  - update-subtask
+  - update-task
+  - update
+
+### Patch Changes
+
+- [#1135](https://github.com/eyaltoledano/claude-task-master/pull/1135) [`8783708`](https://github.com/eyaltoledano/claude-task-master/commit/8783708e5e3389890a78fcf685d3da0580e73b3f) Thanks [@mm-parthy](https://github.com/mm-parthy)! - docs(move): clarify cross-tag move docs; deprecate "force"; add explicit --with-dependencies/--ignore-dependencies examples
+
+## 0.26.0-rc.1
+
+### Minor Changes
+
+- [#1165](https://github.com/eyaltoledano/claude-task-master/pull/1165) [`c4f92f6`](https://github.com/eyaltoledano/claude-task-master/commit/c4f92f6a0aee3435c56eb8d27d9aa9204284833e) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Add configurable codebase analysis feature flag with multiple configuration sources
+
+  Users can now control whether codebase analysis features (Claude Code and Gemini CLI integration) are enabled through environment variables, MCP configuration, or project config files.
+
+  Priority order: .env > MCP session env > .taskmaster/config.json.
+
+  Set `TASKMASTER_ENABLE_CODEBASE_ANALYSIS=false` in `.env` to disable codebase analysis prompts and tool integration.
+
+## 0.26.0-rc.0
+
+### Minor Changes
+
+- [#1163](https://github.com/eyaltoledano/claude-task-master/pull/1163) [`37af0f1`](https://github.com/eyaltoledano/claude-task-master/commit/37af0f191227a68d119b7f89a377bf932ee3ac66) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Enhanced Gemini CLI provider with codebase-aware task generation
+
+  Added automatic codebase analysis for Gemini CLI provider in parse-prd, and analyze-complexity, add-task, udpate-task, update, update-subtask commands
+  When using Gemini CLI as the AI provider, Task Master now instructs the AI to analyze the project structure, existing implementations, and patterns before generating tasks or subtasks
+  Tasks and subtasks generated by Claude Code are now informed by actual codebase analysis, resulting in more accurate and contextual outputs
+
+- [#1135](https://github.com/eyaltoledano/claude-task-master/pull/1135) [`8783708`](https://github.com/eyaltoledano/claude-task-master/commit/8783708e5e3389890a78fcf685d3da0580e73b3f) Thanks [@mm-parthy](https://github.com/mm-parthy)! - feat(move): improve cross-tag move UX and safety
+  - CLI: print "Next Steps" tips after cross-tag moves that used --ignore-dependencies (validate/fix guidance)
+  - CLI: show dedicated help block on ID collisions (destination tag already has the ID)
+  - Core: add structured suggestions to TASK_ALREADY_EXISTS errors
+  - MCP: map ID collision errors to TASK_ALREADY_EXISTS and include suggestions
+  - Tests: cover MCP options, error suggestions, CLI tips printing, and integration error payload suggestions
+
+  ***
+
+- [#1162](https://github.com/eyaltoledano/claude-task-master/pull/1162) [`4dad2fd`](https://github.com/eyaltoledano/claude-task-master/commit/4dad2fd613ceac56a65ae9d3c1c03092b8860ac9) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Enhanced Claude Code and Google CLI integration with automatic codebase analysis for task operations
+
+  When using Claude Code as the AI provider, task management commands now automatically analyze your codebase before generating or updating tasks. This provides more accurate, context-aware implementation details that align with your project's existing architecture and patterns.
+
+  Commands contextualised:
+  - add-task
+  - update-subtask
+  - update-task
+  - update
+
+### Patch Changes
+
+- [#1135](https://github.com/eyaltoledano/claude-task-master/pull/1135) [`8783708`](https://github.com/eyaltoledano/claude-task-master/commit/8783708e5e3389890a78fcf685d3da0580e73b3f) Thanks [@mm-parthy](https://github.com/mm-parthy)! - docs(move): clarify cross-tag move docs; deprecate "force"; add explicit --with-dependencies/--ignore-dependencies examples
+
+## 0.25.1
+
+### Patch Changes
+
+- [#1152](https://github.com/eyaltoledano/claude-task-master/pull/1152) [`8933557`](https://github.com/eyaltoledano/claude-task-master/commit/89335578ffffc65504b2055c0c85aa7521e5e79b) Thanks [@ben-vargas](https://github.com/ben-vargas)! - fix(claude-code): prevent crash/hang when the optional `@anthropic-ai/claude-code` SDK is missing by guarding `AbortError instanceof` checks and adding explicit SDK presence checks in `doGenerate`/`doStream`. Also bump the optional dependency to `^1.0.88` for improved export consistency.
+
+  Related to JSON truncation handling in #920; this change addresses a separate error-path crash reported in #1142.
+
+- [#1151](https://github.com/eyaltoledano/claude-task-master/pull/1151) [`db720a9`](https://github.com/eyaltoledano/claude-task-master/commit/db720a954d390bb44838cd021b8813dde8f3d8de) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Temporarily disable streaming for improved model compatibility - will be re-enabled in upcoming release
+
+## 0.25.0
+
+### Minor Changes
+
+- [#1088](https://github.com/eyaltoledano/claude-task-master/pull/1088) [`04e11b5`](https://github.com/eyaltoledano/claude-task-master/commit/04e11b5e828597c0ba5b82ca7d5fb6f933e4f1e8) Thanks [@mm-parthy](https://github.com/mm-parthy)! - Add cross-tag task movement functionality for organizing tasks across different contexts.
+
+  This feature enables moving tasks between different tags (contexts) in your project, making it easier to organize work across different branches, environments, or project phases.
+
+  ## CLI Usage Examples
+
+  Move a single task from one tag to another:
+
+  ```bash
+  # Move task 5 from backlog tag to in-progress tag
+  task-master move --from=5 --from-tag=backlog --to-tag=feature-1
+
+  # Move task with its dependencies
+  task-master move --from=5 --from-tag=backlog --to-tag=feature-2 --with-dependencies
+
+  # Move task without checking dependencies
+  task-master move --from=5 --from-tag=backlog --to-tag=bug-3 --ignore-dependencies
+  ```
+
+  Move multiple tasks at once:
+
+  ```bash
+  # Move multiple tasks between tags
+  task-master move --from=5,6,7 --from-tag=backlog --to-tag=bug-4 --with-dependencies
+  ```
+
+- [#1040](https://github.com/eyaltoledano/claude-task-master/pull/1040) [`fc47714`](https://github.com/eyaltoledano/claude-task-master/commit/fc477143400fd11d953727bf1b4277af5ad308d1) Thanks [@DomVidja](https://github.com/DomVidja)! - "Add Kilo Code profile integration with custom modes and MCP configuration"
+
+- [#1054](https://github.com/eyaltoledano/claude-task-master/pull/1054) [`782728f`](https://github.com/eyaltoledano/claude-task-master/commit/782728ff95aa2e3b766d48273b57f6c6753e8573) Thanks [@martincik](https://github.com/martincik)! - Add compact mode --compact / -c flag to the `tm list` CLI command
+  - outputs tasks in a minimal, git-style one-line format. This reduces verbose output from ~30+ lines of dashboards and tables to just 1 line per task, making it much easier to quickly scan available tasks.
+    - Git-style format: ID STATUS TITLE (PRIORITY) → DEPS
+    - Color-coded status, priority, and dependencies
+    - Smart title truncation and dependency abbreviation
+    - Subtask support with indentation
+    - Full backward compatibility with existing list options
+
+- [#1048](https://github.com/eyaltoledano/claude-task-master/pull/1048) [`e3ed4d7`](https://github.com/eyaltoledano/claude-task-master/commit/e3ed4d7c14b56894d7da675eb2b757423bea8f9d) Thanks [@joedanz](https://github.com/joedanz)! - Add CLI & MCP progress tracking for parse-prd command.
+
+- [#1124](https://github.com/eyaltoledano/claude-task-master/pull/1124) [`95640dc`](https://github.com/eyaltoledano/claude-task-master/commit/95640dcde87ce7879858c0a951399fb49f3b6397) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Add support for ollama `gpt-oss:20b` and `gpt-oss:120b`
+
+- [#1123](https://github.com/eyaltoledano/claude-task-master/pull/1123) [`311b243`](https://github.com/eyaltoledano/claude-task-master/commit/311b2433e23c771c8d3a4d3f5ac577302b8321e5) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Remove `clear` Taskmaster claude code commands since they were too close to the claude-code clear command
+
+### Patch Changes
+
+- [#1131](https://github.com/eyaltoledano/claude-task-master/pull/1131) [`3dee60d`](https://github.com/eyaltoledano/claude-task-master/commit/3dee60dc3d566e3cff650accb30f994b8bb3a15e) Thanks [@joedanz](https://github.com/joedanz)! - Update Cursor one-click install link to new URL format
+
+- [#1088](https://github.com/eyaltoledano/claude-task-master/pull/1088) [`04e11b5`](https://github.com/eyaltoledano/claude-task-master/commit/04e11b5e828597c0ba5b82ca7d5fb6f933e4f1e8) Thanks [@mm-parthy](https://github.com/mm-parthy)! - Fix `add-tag --from-branch` command error where `projectRoot` was not properly referenced
+
+  The command was failing with "projectRoot is not defined" error because the code was directly referencing `projectRoot` instead of `context.projectRoot` in the git repository checks. This fix corrects the variable references to use the proper context object.
+
+## 0.25.0-rc.0
+
+### Minor Changes
+
+- [#1088](https://github.com/eyaltoledano/claude-task-master/pull/1088) [`04e11b5`](https://github.com/eyaltoledano/claude-task-master/commit/04e11b5e828597c0ba5b82ca7d5fb6f933e4f1e8) Thanks [@mm-parthy](https://github.com/mm-parthy)! - Add cross-tag task movement functionality for organizing tasks across different contexts.
+
+  This feature enables moving tasks between different tags (contexts) in your project, making it easier to organize work across different branches, environments, or project phases.
+
+  ## CLI Usage Examples
+
+  Move a single task from one tag to another:
+
+  ```bash
+  # Move task 5 from backlog tag to in-progress tag
+  task-master move --from=5 --from-tag=backlog --to-tag=feature-1
+
+  # Move task with its dependencies
+  task-master move --from=5 --from-tag=backlog --to-tag=feature-2 --with-dependencies
+
+  # Move task without checking dependencies
+  task-master move --from=5 --from-tag=backlog --to-tag=bug-3 --ignore-dependencies
+  ```
+
+  Move multiple tasks at once:
+
+  ```bash
+  # Move multiple tasks between tags
+  task-master move --from=5,6,7 --from-tag=backlog --to-tag=bug-4 --with-dependencies
+  ```
+
+- [#1040](https://github.com/eyaltoledano/claude-task-master/pull/1040) [`fc47714`](https://github.com/eyaltoledano/claude-task-master/commit/fc477143400fd11d953727bf1b4277af5ad308d1) Thanks [@DomVidja](https://github.com/DomVidja)! - "Add Kilo Code profile integration with custom modes and MCP configuration"
+
+- [#1054](https://github.com/eyaltoledano/claude-task-master/pull/1054) [`782728f`](https://github.com/eyaltoledano/claude-task-master/commit/782728ff95aa2e3b766d48273b57f6c6753e8573) Thanks [@martincik](https://github.com/martincik)! - Add compact mode --compact / -c flag to the `tm list` CLI command
+  - outputs tasks in a minimal, git-style one-line format. This reduces verbose output from ~30+ lines of dashboards and tables to just 1 line per task, making it much easier to quickly scan available tasks.
+    - Git-style format: ID STATUS TITLE (PRIORITY) → DEPS
+    - Color-coded status, priority, and dependencies
+    - Smart title truncation and dependency abbreviation
+    - Subtask support with indentation
+    - Full backward compatibility with existing list options
+
+- [#1048](https://github.com/eyaltoledano/claude-task-master/pull/1048) [`e3ed4d7`](https://github.com/eyaltoledano/claude-task-master/commit/e3ed4d7c14b56894d7da675eb2b757423bea8f9d) Thanks [@joedanz](https://github.com/joedanz)! - Add CLI & MCP progress tracking for parse-prd command.
+
+- [#1124](https://github.com/eyaltoledano/claude-task-master/pull/1124) [`95640dc`](https://github.com/eyaltoledano/claude-task-master/commit/95640dcde87ce7879858c0a951399fb49f3b6397) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Add support for ollama `gpt-oss:20b` and `gpt-oss:120b`
+
+- [#1123](https://github.com/eyaltoledano/claude-task-master/pull/1123) [`311b243`](https://github.com/eyaltoledano/claude-task-master/commit/311b2433e23c771c8d3a4d3f5ac577302b8321e5) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Remove `clear` Taskmaster claude code commands since they were too close to the claude-code clear command
+
+### Patch Changes
+
+- [#1131](https://github.com/eyaltoledano/claude-task-master/pull/1131) [`3dee60d`](https://github.com/eyaltoledano/claude-task-master/commit/3dee60dc3d566e3cff650accb30f994b8bb3a15e) Thanks [@joedanz](https://github.com/joedanz)! - Update Cursor one-click install link to new URL format
+
+- [#1088](https://github.com/eyaltoledano/claude-task-master/pull/1088) [`04e11b5`](https://github.com/eyaltoledano/claude-task-master/commit/04e11b5e828597c0ba5b82ca7d5fb6f933e4f1e8) Thanks [@mm-parthy](https://github.com/mm-parthy)! - Fix `add-tag --from-branch` command error where `projectRoot` was not properly referenced
+
+  The command was failing with "projectRoot is not defined" error because the code was directly referencing `projectRoot` instead of `context.projectRoot` in the git repository checks. This fix corrects the variable references to use the proper context object.
+
 ## 0.24.0
 
 ### Minor Changes

apps/cli/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @tm/cli
+
+## 1.1.0-rc.0
+
+### Minor Changes
+
+- [#1213](https://github.com/eyaltoledano/claude-task-master/pull/1213) [`cd90b4d`](https://github.com/eyaltoledano/claude-task-master/commit/cd90b4d65fc2f04bdad9fb73aba320b58a124240) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - testing this stuff out to see how the release candidate works with monorepo

apps/cli/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@tm/cli",
+	"version": "0.26.0",
+	"description": "Task Master CLI - Command line interface for task management",
+	"type": "module",
+	"private": true,
+	"main": "./dist/index.js",
+	"types": "./src/index.ts",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": ["dist", "README.md"],
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check src",
+		"format": "biome format --write src",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:coverage": "vitest run --coverage",
+		"test:unit": "vitest run -t unit",
+		"test:integration": "vitest run -t integration",
+		"test:e2e": "vitest run --dir tests/e2e",
+		"test:ci": "vitest run --coverage --reporter=dot"
+	},
+	"dependencies": {
+		"@tm/core": "*",
+		"boxen": "^7.1.1",
+		"chalk": "5.6.2",
+		"cli-table3": "^0.6.5",
+		"commander": "^12.1.0",
+		"inquirer": "^9.2.10",
+		"ora": "^8.1.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.4",
+		"@types/inquirer": "^9.0.3",
+		"@types/node": "^22.10.5",
+		"tsx": "^4.20.4",
+		"typescript": "^5.7.3",
+		"vitest": "^2.1.8"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"keywords": ["task-master", "cli", "task-management", "productivity"],
+	"author": "",
+	"license": "MIT",
+	"typesVersions": {
+		"*": {
+			"*": ["src/*"]
+		}
+	}
+}

apps/cli/src/commands/auth.command.ts

@@ -0,0 +1,514 @@
+/**
+ * @fileoverview Auth command using Commander's native class pattern
+ * Extends Commander.Command for better integration with the framework
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import ora, { type Ora } from 'ora';
+import open from 'open';
+import {
+	AuthManager,
+	AuthenticationError,
+	type AuthCredentials
+} from '@tm/core/auth';
+import * as ui from '../utils/ui.js';
+
+/**
+ * Result type from auth command
+ */
+export interface AuthResult {
+	success: boolean;
+	action: 'login' | 'logout' | 'status' | 'refresh';
+	credentials?: AuthCredentials;
+	message?: string;
+}
+
+/**
+ * AuthCommand extending Commander's Command class
+ * This is a thin presentation layer over @tm/core's AuthManager
+ */
+export class AuthCommand extends Command {
+	private authManager: AuthManager;
+	private lastResult?: AuthResult;
+
+	constructor(name?: string) {
+		super(name || 'auth');
+
+		// Initialize auth manager
+		this.authManager = AuthManager.getInstance();
+
+		// Configure the command with subcommands
+		this.description('Manage authentication with tryhamster.com');
+
+		// Add subcommands
+		this.addLoginCommand();
+		this.addLogoutCommand();
+		this.addStatusCommand();
+		this.addRefreshCommand();
+
+		// Default action shows help
+		this.action(() => {
+			this.help();
+		});
+	}
+
+	/**
+	 * Add login subcommand
+	 */
+	private addLoginCommand(): void {
+		this.command('login')
+			.description('Authenticate with tryhamster.com')
+			.action(async () => {
+				await this.executeLogin();
+			});
+	}
+
+	/**
+	 * Add logout subcommand
+	 */
+	private addLogoutCommand(): void {
+		this.command('logout')
+			.description('Logout and clear credentials')
+			.action(async () => {
+				await this.executeLogout();
+			});
+	}
+
+	/**
+	 * Add status subcommand
+	 */
+	private addStatusCommand(): void {
+		this.command('status')
+			.description('Display authentication status')
+			.action(async () => {
+				await this.executeStatus();
+			});
+	}
+
+	/**
+	 * Add refresh subcommand
+	 */
+	private addRefreshCommand(): void {
+		this.command('refresh')
+			.description('Refresh authentication token')
+			.action(async () => {
+				await this.executeRefresh();
+			});
+	}
+
+	/**
+	 * Execute login command
+	 */
+	private async executeLogin(): Promise<void> {
+		try {
+			const result = await this.performInteractiveAuth();
+			this.setLastResult(result);
+
+			if (!result.success) {
+				process.exit(1);
+			}
+
+			// Exit cleanly after successful authentication
+			// Small delay to ensure all output is flushed
+			setTimeout(() => {
+				process.exit(0);
+			}, 100);
+		} catch (error: any) {
+			this.handleError(error);
+			process.exit(1);
+		}
+	}
+
+	/**
+	 * Execute logout command
+	 */
+	private async executeLogout(): Promise<void> {
+		try {
+			const result = await this.performLogout();
+			this.setLastResult(result);
+
+			if (!result.success) {
+				process.exit(1);
+			}
+		} catch (error: any) {
+			this.handleError(error);
+			process.exit(1);
+		}
+	}
+
+	/**
+	 * Execute status command
+	 */
+	private async executeStatus(): Promise<void> {
+		try {
+			const result = this.displayStatus();
+			this.setLastResult(result);
+		} catch (error: any) {
+			this.handleError(error);
+			process.exit(1);
+		}
+	}
+
+	/**
+	 * Execute refresh command
+	 */
+	private async executeRefresh(): Promise<void> {
+		try {
+			const result = await this.refreshToken();
+			this.setLastResult(result);
+
+			if (!result.success) {
+				process.exit(1);
+			}
+		} catch (error: any) {
+			this.handleError(error);
+			process.exit(1);
+		}
+	}
+
+	/**
+	 * Display authentication status
+	 */
+	private displayStatus(): AuthResult {
+		const credentials = this.authManager.getCredentials();
+
+		console.log(chalk.cyan('\n🔐 Authentication Status\n'));
+
+		if (credentials) {
+			console.log(chalk.green('✓ Authenticated'));
+			console.log(chalk.gray(`  Email: ${credentials.email || 'N/A'}`));
+			console.log(chalk.gray(`  User ID: ${credentials.userId}`));
+			console.log(
+				chalk.gray(`  Token Type: ${credentials.tokenType || 'standard'}`)
+			);
+
+			if (credentials.expiresAt) {
+				const expiresAt = new Date(credentials.expiresAt);
+				const now = new Date();
+				const hoursRemaining = Math.floor(
+					(expiresAt.getTime() - now.getTime()) / (1000 * 60 * 60)
+				);
+
+				if (hoursRemaining > 0) {
+					console.log(
+						chalk.gray(
+							`  Expires: ${expiresAt.toLocaleString()} (${hoursRemaining} hours remaining)`
+						)
+					);
+				} else {
+					console.log(
+						chalk.yellow(`  Token expired at: ${expiresAt.toLocaleString()}`)
+					);
+				}
+			} else {
+				console.log(chalk.gray('  Expires: Never (API key)'));
+			}
+
+			console.log(
+				chalk.gray(`  Saved: ${new Date(credentials.savedAt).toLocaleString()}`)
+			);
+
+			return {
+				success: true,
+				action: 'status',
+				credentials,
+				message: 'Authenticated'
+			};
+		} else {
+			console.log(chalk.yellow('✗ Not authenticated'));
+			console.log(
+				chalk.gray('\n  Run "task-master auth login" to authenticate')
+			);
+
+			return {
+				success: false,
+				action: 'status',
+				message: 'Not authenticated'
+			};
+		}
+	}
+
+	/**
+	 * Perform logout
+	 */
+	private async performLogout(): Promise<AuthResult> {
+		try {
+			await this.authManager.logout();
+			ui.displaySuccess('Successfully logged out');
+
+			return {
+				success: true,
+				action: 'logout',
+				message: 'Successfully logged out'
+			};
+		} catch (error) {
+			const message = `Failed to logout: ${(error as Error).message}`;
+			ui.displayError(message);
+
+			return {
+				success: false,
+				action: 'logout',
+				message
+			};
+		}
+	}
+
+	/**
+	 * Refresh authentication token
+	 */
+	private async refreshToken(): Promise<AuthResult> {
+		const spinner = ora('Refreshing authentication token...').start();
+
+		try {
+			const credentials = await this.authManager.refreshToken();
+			spinner.succeed('Token refreshed successfully');
+
+			console.log(
+				chalk.gray(
+					`  New expiration: ${credentials.expiresAt ? new Date(credentials.expiresAt).toLocaleString() : 'Never'}`
+				)
+			);
+
+			return {
+				success: true,
+				action: 'refresh',
+				credentials,
+				message: 'Token refreshed successfully'
+			};
+		} catch (error) {
+			spinner.fail('Failed to refresh token');
+
+			if ((error as AuthenticationError).code === 'NO_REFRESH_TOKEN') {
+				ui.displayWarning(
+					'No refresh token available. Please re-authenticate.'
+				);
+			} else {
+				ui.displayError(`Refresh failed: ${(error as Error).message}`);
+			}
+
+			return {
+				success: false,
+				action: 'refresh',
+				message: `Failed to refresh: ${(error as Error).message}`
+			};
+		}
+	}
+
+	/**
+	 * Perform interactive authentication
+	 */
+	private async performInteractiveAuth(): Promise<AuthResult> {
+		ui.displayBanner('Task Master Authentication');
+
+		// Check if already authenticated
+		if (this.authManager.isAuthenticated()) {
+			const { continueAuth } = await inquirer.prompt([
+				{
+					type: 'confirm',
+					name: 'continueAuth',
+					message:
+						'You are already authenticated. Do you want to re-authenticate?',
+					default: false
+				}
+			]);
+
+			if (!continueAuth) {
+				const credentials = this.authManager.getCredentials();
+				ui.displaySuccess('Using existing authentication');
+
+				if (credentials) {
+					console.log(chalk.gray(`  Email: ${credentials.email || 'N/A'}`));
+					console.log(chalk.gray(`  User ID: ${credentials.userId}`));
+				}
+
+				return {
+					success: true,
+					action: 'login',
+					credentials: credentials || undefined,
+					message: 'Using existing authentication'
+				};
+			}
+		}
+
+		try {
+			// Direct browser authentication - no menu needed
+			const credentials = await this.authenticateWithBrowser();
+
+			ui.displaySuccess('Authentication successful!');
+			console.log(
+				chalk.gray(`  Logged in as: ${credentials.email || credentials.userId}`)
+			);
+
+			return {
+				success: true,
+				action: 'login',
+				credentials,
+				message: 'Authentication successful'
+			};
+		} catch (error) {
+			this.handleAuthError(error as AuthenticationError);
+
+			return {
+				success: false,
+				action: 'login',
+				message: `Authentication failed: ${(error as Error).message}`
+			};
+		}
+	}
+
+	/**
+	 * Authenticate with browser using OAuth 2.0 with PKCE
+	 */
+	private async authenticateWithBrowser(): Promise<AuthCredentials> {
+		let authSpinner: Ora | null = null;
+
+		try {
+			// Use AuthManager's new unified OAuth flow method with callbacks
+			const credentials = await this.authManager.authenticateWithOAuth({
+				// Callback to handle browser opening
+				openBrowser: async (authUrl) => {
+					await open(authUrl);
+				},
+				timeout: 5 * 60 * 1000, // 5 minutes
+
+				// Callback when auth URL is ready
+				onAuthUrl: (authUrl) => {
+					// Display authentication instructions
+					console.log(chalk.blue.bold('\n🔐 Browser Authentication\n'));
+					console.log(chalk.white('  Opening your browser to authenticate...'));
+					console.log(chalk.gray("  If the browser doesn't open, visit:"));
+					console.log(chalk.cyan.underline(`  ${authUrl}\n`));
+				},
+
+				// Callback when waiting for authentication
+				onWaitingForAuth: () => {
+					authSpinner = ora({
+						text: 'Waiting for authentication...',
+						spinner: 'dots'
+					}).start();
+				},
+
+				// Callback on success
+				onSuccess: () => {
+					if (authSpinner) {
+						authSpinner.succeed('Authentication successful!');
+					}
+				},
+
+				// Callback on error
+				onError: () => {
+					if (authSpinner) {
+						authSpinner.fail('Authentication failed');
+					}
+				}
+			});
+
+			return credentials;
+		} catch (error) {
+			throw error;
+		}
+	}
+
+	/**
+	 * Handle authentication errors
+	 */
+	private handleAuthError(error: AuthenticationError): void {
+		console.error(chalk.red(`\n✗ ${error.message}`));
+
+		switch (error.code) {
+			case 'NETWORK_ERROR':
+				ui.displayWarning(
+					'Please check your internet connection and try again.'
+				);
+				break;
+			case 'INVALID_CREDENTIALS':
+				ui.displayWarning('Please check your credentials and try again.');
+				break;
+			case 'AUTH_EXPIRED':
+				ui.displayWarning(
+					'Your session has expired. Please authenticate again.'
+				);
+				break;
+			default:
+				if (process.env.DEBUG) {
+					console.error(chalk.gray(error.stack || ''));
+				}
+		}
+	}
+
+	/**
+	 * Handle general errors
+	 */
+	private handleError(error: any): void {
+		if (error instanceof AuthenticationError) {
+			this.handleAuthError(error);
+		} else {
+			const msg = error?.getSanitizedDetails?.() ?? {
+				message: error?.message ?? String(error)
+			};
+			console.error(chalk.red(`Error: ${msg.message || 'Unexpected error'}`));
+
+			if (error.stack && process.env.DEBUG) {
+				console.error(chalk.gray(error.stack));
+			}
+		}
+	}
+
+	/**
+	 * Set the last result for programmatic access
+	 */
+	private setLastResult(result: AuthResult): void {
+		this.lastResult = result;
+	}
+
+	/**
+	 * Get the last result (for programmatic usage)
+	 */
+	getLastResult(): AuthResult | undefined {
+		return this.lastResult;
+	}
+
+	/**
+	 * Get current authentication status (for programmatic usage)
+	 */
+	isAuthenticated(): boolean {
+		return this.authManager.isAuthenticated();
+	}
+
+	/**
+	 * Get current credentials (for programmatic usage)
+	 */
+	getCredentials(): AuthCredentials | null {
+		return this.authManager.getCredentials();
+	}
+
+	/**
+	 * Clean up resources
+	 */
+	async cleanup(): Promise<void> {
+		// No resources to clean up for auth command
+		// But keeping method for consistency with other commands
+	}
+
+	/**
+	 * Static method to register this command on an existing program
+	 * This is for gradual migration - allows commands.js to use this
+	 */
+	static registerOn(program: Command): Command {
+		const authCommand = new AuthCommand();
+		program.addCommand(authCommand);
+		return authCommand;
+	}
+
+	/**
+	 * Alternative registration that returns the command for chaining
+	 * Can also configure the command name if needed
+	 */
+	static register(program: Command, name?: string): AuthCommand {
+		const authCommand = new AuthCommand(name);
+		program.addCommand(authCommand);
+		return authCommand;
+	}
+}

apps/cli/src/commands/context.command.ts

@@ -0,0 +1,570 @@
+/**
+ * @fileoverview Context command for managing org/brief selection
+ * Provides a clean interface for workspace context management
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import ora from 'ora';
+import {
+	AuthManager,
+	AuthenticationError,
+	type UserContext
+} from '@tm/core/auth';
+import * as ui from '../utils/ui.js';
+
+/**
+ * Result type from context command
+ */
+export interface ContextResult {
+	success: boolean;
+	action: 'show' | 'select-org' | 'select-brief' | 'clear' | 'set';
+	context?: UserContext;
+	message?: string;
+}
+
+/**
+ * ContextCommand extending Commander's Command class
+ * Manages user's workspace context (org/brief selection)
+ */
+export class ContextCommand extends Command {
+	private authManager: AuthManager;
+	private lastResult?: ContextResult;
+
+	constructor(name?: string) {
+		super(name || 'context');
+
+		// Initialize auth manager
+		this.authManager = AuthManager.getInstance();
+
+		// Configure the command
+		this.description(
+			'Manage workspace context (organization and brief selection)'
+		);
+
+		// Add subcommands
+		this.addOrgCommand();
+		this.addBriefCommand();
+		this.addClearCommand();
+		this.addSetCommand();
+
+		// Default action shows current context
+		this.action(async () => {
+			await this.executeShow();
+		});
+	}
+
+	/**
+	 * Add org selection subcommand
+	 */
+	private addOrgCommand(): void {
+		this.command('org')
+			.description('Select an organization')
+			.action(async () => {
+				await this.executeSelectOrg();
+			});
+	}
+
+	/**
+	 * Add brief selection subcommand
+	 */
+	private addBriefCommand(): void {
+		this.command('brief')
+			.description('Select a brief within the current organization')
+			.action(async () => {
+				await this.executeSelectBrief();
+			});
+	}
+
+	/**
+	 * Add clear subcommand
+	 */
+	private addClearCommand(): void {
+		this.command('clear')
+			.description('Clear all context selections')
+			.action(async () => {
+				await this.executeClear();
+			});
+	}
+
+	/**
+	 * Add set subcommand for direct context setting
+	 */
+	private addSetCommand(): void {
+		this.command('set')
+			.description('Set context directly')
+			.option('--org <id>', 'Organization ID')
+			.option('--org-name <name>', 'Organization name')
+			.option('--brief <id>', 'Brief ID')
+			.option('--brief-name <name>', 'Brief name')
+			.action(async (options) => {
+				await this.executeSet(options);
+			});
+	}
+
+	/**
+	 * Execute show current context
+	 */
+	private async executeShow(): Promise<void> {
+		try {
+			const result = this.displayContext();
+			this.setLastResult(result);
+		} catch (error: any) {
+			this.handleError(error);
+			process.exit(1);
+		}
+	}
+
+	/**
+	 * Display current context
+	 */
+	private displayContext(): ContextResult {
+		// Check authentication first
+		if (!this.authManager.isAuthenticated()) {
+			console.log(chalk.yellow('✗ Not authenticated'));
+			console.log(chalk.gray('\n  Run "tm auth login" to authenticate first'));
+
+			return {
+				success: false,
+				action: 'show',
+				message: 'Not authenticated'
+			};
+		}
+
+		const context = this.authManager.getContext();
+
+		console.log(chalk.cyan('\n🌍 Workspace Context\n'));
+
+		if (context && (context.orgId || context.briefId)) {
+			if (context.orgName || context.orgId) {
+				console.log(chalk.green('✓ Organization'));
+				if (context.orgName) {
+					console.log(chalk.white(`  ${context.orgName}`));
+				}
+				if (context.orgId) {
+					console.log(chalk.gray(`  ID: ${context.orgId}`));
+				}
+			}
+
+			if (context.briefName || context.briefId) {
+				console.log(chalk.green('\n✓ Brief'));
+				if (context.briefName) {
+					console.log(chalk.white(`  ${context.briefName}`));
+				}
+				if (context.briefId) {
+					console.log(chalk.gray(`  ID: ${context.briefId}`));
+				}
+			}
+
+			if (context.updatedAt) {
+				console.log(
+					chalk.gray(
+						`\n  Last updated: ${new Date(context.updatedAt).toLocaleString()}`
+					)
+				);
+			}
+
+			return {
+				success: true,
+				action: 'show',
+				context,
+				message: 'Context loaded'
+			};
+		} else {
+			console.log(chalk.yellow('✗ No context selected'));
+			console.log(
+				chalk.gray('\n  Run "tm context org" to select an organization')
+			);
+			console.log(chalk.gray('  Run "tm context brief" to select a brief'));
+
+			return {
+				success: true,
+				action: 'show',
+				message: 'No context selected'
+			};
+		}
+	}
+
+	/**
+	 * Execute org selection
+	 */
+	private async executeSelectOrg(): Promise<void> {
+		try {
+			// Check authentication
+			if (!this.authManager.isAuthenticated()) {
+				ui.displayError('Not authenticated. Run "tm auth login" first.');
+				process.exit(1);
+			}
+
+			const result = await this.selectOrganization();
+			this.setLastResult(result);
+
+			if (!result.success) {
+				process.exit(1);
+			}
+		} catch (error: any) {
+			this.handleError(error);
+			process.exit(1);
+		}
+	}
+
+	/**
+	 * Select an organization interactively
+	 */
+	private async selectOrganization(): Promise<ContextResult> {
+		const spinner = ora('Fetching organizations...').start();
+
+		try {
+			// Fetch organizations from API
+			const organizations = await this.authManager.getOrganizations();
+			spinner.stop();
+
+			if (organizations.length === 0) {
+				ui.displayWarning('No organizations available');
+				return {
+					success: false,
+					action: 'select-org',
+					message: 'No organizations available'
+				};
+			}
+
+			// Prompt for selection
+			const { selectedOrg } = await inquirer.prompt([
+				{
+					type: 'list',
+					name: 'selectedOrg',
+					message: 'Select an organization:',
+					choices: organizations.map((org) => ({
+						name: org.name,
+						value: org
+					}))
+				}
+			]);
+
+			// Update context
+			await this.authManager.updateContext({
+				orgId: selectedOrg.id,
+				orgName: selectedOrg.name,
+				// Clear brief when changing org
+				briefId: undefined,
+				briefName: undefined
+			});
+
+			ui.displaySuccess(`Selected organization: ${selectedOrg.name}`);
+
+			return {
+				success: true,
+				action: 'select-org',
+				context: this.authManager.getContext() || undefined,
+				message: `Selected organization: ${selectedOrg.name}`
+			};
+		} catch (error) {
+			spinner.fail('Failed to fetch organizations');
+			throw error;
+		}
+	}
+
+	/**
+	 * Execute brief selection
+	 */
+	private async executeSelectBrief(): Promise<void> {
+		try {
+			// Check authentication
+			if (!this.authManager.isAuthenticated()) {
+				ui.displayError('Not authenticated. Run "tm auth login" first.');
+				process.exit(1);
+			}
+
+			// Check if org is selected
+			const context = this.authManager.getContext();
+			if (!context?.orgId) {
+				ui.displayError(
+					'No organization selected. Run "tm context org" first.'
+				);
+				process.exit(1);
+			}
+
+			const result = await this.selectBrief(context.orgId);
+			this.setLastResult(result);
+
+			if (!result.success) {
+				process.exit(1);
+			}
+		} catch (error: any) {
+			this.handleError(error);
+			process.exit(1);
+		}
+	}
+
+	/**
+	 * Select a brief within the current organization
+	 */
+	private async selectBrief(orgId: string): Promise<ContextResult> {
+		const spinner = ora('Fetching briefs...').start();
+
+		try {
+			// Fetch briefs from API
+			const briefs = await this.authManager.getBriefs(orgId);
+			spinner.stop();
+
+			if (briefs.length === 0) {
+				ui.displayWarning('No briefs available in this organization');
+				return {
+					success: false,
+					action: 'select-brief',
+					message: 'No briefs available'
+				};
+			}
+
+			// Prompt for selection
+			const { selectedBrief } = await inquirer.prompt([
+				{
+					type: 'list',
+					name: 'selectedBrief',
+					message: 'Select a brief:',
+					choices: [
+						{ name: '(No brief - organization level)', value: null },
+						...briefs.map((brief) => ({
+							name: `Brief ${brief.id} (${new Date(brief.createdAt).toLocaleDateString()})`,
+							value: brief
+						}))
+					]
+				}
+			]);
+
+			if (selectedBrief) {
+				// Update context with brief
+				const briefName = `Brief ${selectedBrief.id.slice(0, 8)}`;
+				await this.authManager.updateContext({
+					briefId: selectedBrief.id,
+					briefName: briefName
+				});
+
+				ui.displaySuccess(`Selected brief: ${briefName}`);
+
+				return {
+					success: true,
+					action: 'select-brief',
+					context: this.authManager.getContext() || undefined,
+					message: `Selected brief: ${selectedBrief.name}`
+				};
+			} else {
+				// Clear brief selection
+				await this.authManager.updateContext({
+					briefId: undefined,
+					briefName: undefined
+				});
+
+				ui.displaySuccess('Cleared brief selection (organization level)');
+
+				return {
+					success: true,
+					action: 'select-brief',
+					context: this.authManager.getContext() || undefined,
+					message: 'Cleared brief selection'
+				};
+			}
+		} catch (error) {
+			spinner.fail('Failed to fetch briefs');
+			throw error;
+		}
+	}
+
+	/**
+	 * Execute clear context
+	 */
+	private async executeClear(): Promise<void> {
+		try {
+			// Check authentication
+			if (!this.authManager.isAuthenticated()) {
+				ui.displayError('Not authenticated. Run "tm auth login" first.');
+				process.exit(1);
+			}
+
+			const result = await this.clearContext();
+			this.setLastResult(result);
+
+			if (!result.success) {
+				process.exit(1);
+			}
+		} catch (error: any) {
+			this.handleError(error);
+			process.exit(1);
+		}
+	}
+
+	/**
+	 * Clear all context selections
+	 */
+	private async clearContext(): Promise<ContextResult> {
+		try {
+			await this.authManager.clearContext();
+			ui.displaySuccess('Context cleared');
+
+			return {
+				success: true,
+				action: 'clear',
+				message: 'Context cleared'
+			};
+		} catch (error) {
+			ui.displayError(`Failed to clear context: ${(error as Error).message}`);
+
+			return {
+				success: false,
+				action: 'clear',
+				message: `Failed to clear context: ${(error as Error).message}`
+			};
+		}
+	}
+
+	/**
+	 * Execute set context with options
+	 */
+	private async executeSet(options: any): Promise<void> {
+		try {
+			// Check authentication
+			if (!this.authManager.isAuthenticated()) {
+				ui.displayError('Not authenticated. Run "tm auth login" first.');
+				process.exit(1);
+			}
+
+			const result = await this.setContext(options);
+			this.setLastResult(result);
+
+			if (!result.success) {
+				process.exit(1);
+			}
+		} catch (error: any) {
+			this.handleError(error);
+			process.exit(1);
+		}
+	}
+
+	/**
+	 * Set context directly from options
+	 */
+	private async setContext(options: any): Promise<ContextResult> {
+		try {
+			const context: Partial<UserContext> = {};
+
+			if (options.org) {
+				context.orgId = options.org;
+			}
+			if (options.orgName) {
+				context.orgName = options.orgName;
+			}
+			if (options.brief) {
+				context.briefId = options.brief;
+			}
+			if (options.briefName) {
+				context.briefName = options.briefName;
+			}
+
+			if (Object.keys(context).length === 0) {
+				ui.displayWarning('No context options provided');
+				return {
+					success: false,
+					action: 'set',
+					message: 'No context options provided'
+				};
+			}
+
+			await this.authManager.updateContext(context);
+			ui.displaySuccess('Context updated');
+
+			// Display what was set
+			if (context.orgName || context.orgId) {
+				console.log(
+					chalk.gray(`  Organization: ${context.orgName || context.orgId}`)
+				);
+			}
+			if (context.briefName || context.briefId) {
+				console.log(
+					chalk.gray(`  Brief: ${context.briefName || context.briefId}`)
+				);
+			}
+
+			return {
+				success: true,
+				action: 'set',
+				context: this.authManager.getContext() || undefined,
+				message: 'Context updated'
+			};
+		} catch (error) {
+			ui.displayError(`Failed to set context: ${(error as Error).message}`);
+
+			return {
+				success: false,
+				action: 'set',
+				message: `Failed to set context: ${(error as Error).message}`
+			};
+		}
+	}
+
+	/**
+	 * Handle errors
+	 */
+	private handleError(error: any): void {
+		if (error instanceof AuthenticationError) {
+			console.error(chalk.red(`\n✗ ${error.message}`));
+
+			if (error.code === 'NOT_AUTHENTICATED') {
+				ui.displayWarning('Please authenticate first: tm auth login');
+			}
+		} else {
+			const msg = error?.message ?? String(error);
+			console.error(chalk.red(`Error: ${msg}`));
+
+			if (error.stack && process.env.DEBUG) {
+				console.error(chalk.gray(error.stack));
+			}
+		}
+	}
+
+	/**
+	 * Set the last result for programmatic access
+	 */
+	private setLastResult(result: ContextResult): void {
+		this.lastResult = result;
+	}
+
+	/**
+	 * Get the last result (for programmatic usage)
+	 */
+	getLastResult(): ContextResult | undefined {
+		return this.lastResult;
+	}
+
+	/**
+	 * Get current context (for programmatic usage)
+	 */
+	getContext(): UserContext | null {
+		return this.authManager.getContext();
+	}
+
+	/**
+	 * Clean up resources
+	 */
+	async cleanup(): Promise<void> {
+		// No resources to clean up for context command
+	}
+
+	/**
+	 * Static method to register this command on an existing program
+	 */
+	static registerOn(program: Command): Command {
+		const contextCommand = new ContextCommand();
+		program.addCommand(contextCommand);
+		return contextCommand;
+	}
+
+	/**
+	 * Alternative registration that returns the command for chaining
+	 */
+	static register(program: Command, name?: string): ContextCommand {
+		const contextCommand = new ContextCommand(name);
+		program.addCommand(contextCommand);
+		return contextCommand;
+	}
+}

apps/cli/src/commands/list.command.ts

@@ -0,0 +1,488 @@
+/**
+ * @fileoverview ListTasks command using Commander's native class pattern
+ * Extends Commander.Command for better integration with the framework
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import {
+	createTaskMasterCore,
+	type Task,
+	type TaskStatus,
+	type TaskMasterCore,
+	TASK_STATUSES,
+	OUTPUT_FORMATS,
+	STATUS_ICONS,
+	type OutputFormat
+} from '@tm/core';
+import type { StorageType } from '@tm/core/types';
+import * as ui from '../utils/ui.js';
+import {
+	displayHeader,
+	displayDashboards,
+	calculateTaskStatistics,
+	calculateSubtaskStatistics,
+	calculateDependencyStatistics,
+	getPriorityBreakdown,
+	displayRecommendedNextTask,
+	getTaskDescription,
+	displaySuggestedNextSteps,
+	type NextTaskInfo
+} from '../ui/index.js';
+
+/**
+ * Options interface for the list command
+ */
+export interface ListCommandOptions {
+	status?: string;
+	tag?: string;
+	withSubtasks?: boolean;
+	format?: OutputFormat;
+	silent?: boolean;
+	project?: string;
+}
+
+/**
+ * Result type from list command
+ */
+export interface ListTasksResult {
+	tasks: Task[];
+	total: number;
+	filtered: number;
+	tag?: string;
+	storageType: Exclude<StorageType, 'auto'>;
+}
+
+/**
+ * ListTasksCommand extending Commander's Command class
+ * This is a thin presentation layer over @tm/core
+ */
+export class ListTasksCommand extends Command {
+	private tmCore?: TaskMasterCore;
+	private lastResult?: ListTasksResult;
+
+	constructor(name?: string) {
+		super(name || 'list');
+
+		// Configure the command
+		this.description('List tasks with optional filtering')
+			.alias('ls')
+			.option('-s, --status <status>', 'Filter by status (comma-separated)')
+			.option('-t, --tag <tag>', 'Filter by tag')
+			.option('--with-subtasks', 'Include subtasks in the output')
+			.option(
+				'-f, --format <format>',
+				'Output format (text, json, compact)',
+				'text'
+			)
+			.option('--silent', 'Suppress output (useful for programmatic usage)')
+			.option('-p, --project <path>', 'Project root directory', process.cwd())
+			.action(async (options: ListCommandOptions) => {
+				await this.executeCommand(options);
+			});
+	}
+
+	/**
+	 * Execute the list command
+	 */
+	private async executeCommand(options: ListCommandOptions): Promise<void> {
+		try {
+			// Validate options
+			if (!this.validateOptions(options)) {
+				process.exit(1);
+			}
+
+			// Initialize tm-core
+			await this.initializeCore(options.project || process.cwd());
+
+			// Get tasks from core
+			const result = await this.getTasks(options);
+
+			// Store result for programmatic access
+			this.setLastResult(result);
+
+			// Display results
+			if (!options.silent) {
+				this.displayResults(result, options);
+			}
+		} catch (error: any) {
+			const msg = error?.getSanitizedDetails?.() ?? {
+				message: error?.message ?? String(error)
+			};
+			console.error(chalk.red(`Error: ${msg.message || 'Unexpected error'}`));
+			if (error.stack && process.env.DEBUG) {
+				console.error(chalk.gray(error.stack));
+			}
+			process.exit(1);
+		}
+	}
+
+	/**
+	 * Validate command options
+	 */
+	private validateOptions(options: ListCommandOptions): boolean {
+		// Validate format
+		if (
+			options.format &&
+			!OUTPUT_FORMATS.includes(options.format as OutputFormat)
+		) {
+			console.error(chalk.red(`Invalid format: ${options.format}`));
+			console.error(chalk.gray(`Valid formats: ${OUTPUT_FORMATS.join(', ')}`));
+			return false;
+		}
+
+		// Validate status
+		if (options.status) {
+			const statuses = options.status.split(',').map((s: string) => s.trim());
+
+			for (const status of statuses) {
+				if (status !== 'all' && !TASK_STATUSES.includes(status as TaskStatus)) {
+					console.error(chalk.red(`Invalid status: ${status}`));
+					console.error(
+						chalk.gray(`Valid statuses: ${TASK_STATUSES.join(', ')}`)
+					);
+					return false;
+				}
+			}
+		}
+
+		return true;
+	}
+
+	/**
+	 * Initialize TaskMasterCore
+	 */
+	private async initializeCore(projectRoot: string): Promise<void> {
+		if (!this.tmCore) {
+			this.tmCore = await createTaskMasterCore({ projectPath: projectRoot });
+		}
+	}
+
+	/**
+	 * Get tasks from tm-core
+	 */
+	private async getTasks(
+		options: ListCommandOptions
+	): Promise<ListTasksResult> {
+		if (!this.tmCore) {
+			throw new Error('TaskMasterCore not initialized');
+		}
+
+		// Build filter
+		const filter =
+			options.status && options.status !== 'all'
+				? {
+						status: options.status
+							.split(',')
+							.map((s: string) => s.trim() as TaskStatus)
+					}
+				: undefined;
+
+		// Call tm-core
+		const result = await this.tmCore.getTaskList({
+			tag: options.tag,
+			filter,
+			includeSubtasks: options.withSubtasks
+		});
+
+		return result as ListTasksResult;
+	}
+
+	/**
+	 * Display results based on format
+	 */
+	private displayResults(
+		result: ListTasksResult,
+		options: ListCommandOptions
+	): void {
+		const format = (options.format || 'text') as OutputFormat | 'text';
+
+		switch (format) {
+			case 'json':
+				this.displayJson(result);
+				break;
+
+			case 'compact':
+				this.displayCompact(result.tasks, options.withSubtasks);
+				break;
+
+			case 'text':
+			default:
+				this.displayText(result, options.withSubtasks);
+				break;
+		}
+	}
+
+	/**
+	 * Display in JSON format
+	 */
+	private displayJson(data: ListTasksResult): void {
+		console.log(
+			JSON.stringify(
+				{
+					tasks: data.tasks,
+					metadata: {
+						total: data.total,
+						filtered: data.filtered,
+						tag: data.tag,
+						storageType: data.storageType
+					}
+				},
+				null,
+				2
+			)
+		);
+	}
+
+	/**
+	 * Display in compact format
+	 */
+	private displayCompact(tasks: Task[], withSubtasks?: boolean): void {
+		tasks.forEach((task) => {
+			const icon = STATUS_ICONS[task.status];
+			console.log(`${chalk.cyan(task.id)} ${icon} ${task.title}`);
+
+			if (withSubtasks && task.subtasks?.length) {
+				task.subtasks.forEach((subtask) => {
+					const subIcon = STATUS_ICONS[subtask.status];
+					console.log(
+						`  ${chalk.gray(`${task.id}.${subtask.id}`)} ${subIcon} ${chalk.gray(subtask.title)}`
+					);
+				});
+			}
+		});
+	}
+
+	/**
+	 * Display in text format with tables
+	 */
+	private displayText(data: ListTasksResult, withSubtasks?: boolean): void {
+		const { tasks, tag } = data;
+
+		// Get file path for display
+		const filePath = this.tmCore ? `.taskmaster/tasks/tasks.json` : undefined;
+
+		// Display header without banner (banner already shown by main CLI)
+		displayHeader({
+			tag: tag || 'master',
+			filePath: filePath
+		});
+
+		// No tasks message
+		if (tasks.length === 0) {
+			ui.displayWarning('No tasks found matching the criteria.');
+			return;
+		}
+
+		// Calculate statistics
+		const taskStats = calculateTaskStatistics(tasks);
+		const subtaskStats = calculateSubtaskStatistics(tasks);
+		const depStats = calculateDependencyStatistics(tasks);
+		const priorityBreakdown = getPriorityBreakdown(tasks);
+
+		// Find next task following the same logic as findNextTask
+		const nextTask = this.findNextTask(tasks);
+
+		// Display dashboard boxes
+		displayDashboards(
+			taskStats,
+			subtaskStats,
+			priorityBreakdown,
+			depStats,
+			nextTask
+		);
+
+		// Task table - no title, just show the table directly
+		console.log(
+			ui.createTaskTable(tasks, {
+				showSubtasks: withSubtasks,
+				showDependencies: true,
+				showComplexity: true // Enable complexity column
+			})
+		);
+
+		// Display recommended next task section immediately after table
+		if (nextTask) {
+			// Find the full task object to get description
+			const fullTask = tasks.find((t) => String(t.id) === String(nextTask.id));
+			const description = fullTask ? getTaskDescription(fullTask) : undefined;
+
+			displayRecommendedNextTask({
+				...nextTask,
+				status: 'pending', // Next task is typically pending
+				description
+			});
+		} else {
+			displayRecommendedNextTask(undefined);
+		}
+
+		// Display suggested next steps at the end
+		displaySuggestedNextSteps();
+	}
+
+	/**
+	 * Set the last result for programmatic access
+	 */
+	private setLastResult(result: ListTasksResult): void {
+		this.lastResult = result;
+	}
+
+	/**
+	 * Find the next task to work on
+	 * Implements the same logic as scripts/modules/task-manager/find-next-task.js
+	 */
+	private findNextTask(tasks: Task[]): NextTaskInfo | undefined {
+		const priorityValues: Record<string, number> = {
+			critical: 4,
+			high: 3,
+			medium: 2,
+			low: 1
+		};
+
+		// Build set of completed task IDs (including subtasks)
+		const completedIds = new Set<string>();
+		tasks.forEach((t) => {
+			if (t.status === 'done' || t.status === 'completed') {
+				completedIds.add(String(t.id));
+			}
+			if (t.subtasks) {
+				t.subtasks.forEach((st) => {
+					if (st.status === 'done' || st.status === 'completed') {
+						completedIds.add(`${t.id}.${st.id}`);
+					}
+				});
+			}
+		});
+
+		// First, look for eligible subtasks in in-progress parent tasks
+		const candidateSubtasks: NextTaskInfo[] = [];
+
+		tasks
+			.filter(
+				(t) => t.status === 'in-progress' && t.subtasks && t.subtasks.length > 0
+			)
+			.forEach((parent) => {
+				parent.subtasks!.forEach((st) => {
+					const stStatus = (st.status || 'pending').toLowerCase();
+					if (stStatus !== 'pending' && stStatus !== 'in-progress') return;
+
+					// Check if dependencies are satisfied
+					const fullDeps =
+						st.dependencies?.map((d) => {
+							// Handle both numeric and string IDs
+							if (typeof d === 'string' && d.includes('.')) {
+								return d;
+							}
+							return `${parent.id}.${d}`;
+						}) ?? [];
+
+					const depsSatisfied =
+						fullDeps.length === 0 ||
+						fullDeps.every((depId) => completedIds.has(String(depId)));
+
+					if (depsSatisfied) {
+						candidateSubtasks.push({
+							id: `${parent.id}.${st.id}`,
+							title: st.title || `Subtask ${st.id}`,
+							priority: st.priority || parent.priority || 'medium',
+							dependencies: fullDeps.map((d) => String(d))
+						});
+					}
+				});
+			});
+
+		if (candidateSubtasks.length > 0) {
+			// Sort by priority, then by dependencies count, then by ID
+			candidateSubtasks.sort((a, b) => {
+				const pa = priorityValues[a.priority || 'medium'] ?? 2;
+				const pb = priorityValues[b.priority || 'medium'] ?? 2;
+				if (pb !== pa) return pb - pa;
+
+				const depCountA = a.dependencies?.length || 0;
+				const depCountB = b.dependencies?.length || 0;
+				if (depCountA !== depCountB) return depCountA - depCountB;
+
+				return String(a.id).localeCompare(String(b.id));
+			});
+			return candidateSubtasks[0];
+		}
+
+		// Fall back to finding eligible top-level tasks
+		const eligibleTasks = tasks.filter((task) => {
+			// Skip non-eligible statuses
+			const status = (task.status || 'pending').toLowerCase();
+			if (status !== 'pending' && status !== 'in-progress') return false;
+
+			// Check dependencies
+			const deps = task.dependencies || [];
+			const depsSatisfied =
+				deps.length === 0 ||
+				deps.every((depId) => completedIds.has(String(depId)));
+
+			return depsSatisfied;
+		});
+
+		if (eligibleTasks.length === 0) return undefined;
+
+		// Sort eligible tasks
+		eligibleTasks.sort((a, b) => {
+			// Priority (higher first)
+			const pa = priorityValues[a.priority || 'medium'] ?? 2;
+			const pb = priorityValues[b.priority || 'medium'] ?? 2;
+			if (pb !== pa) return pb - pa;
+
+			// Dependencies count (fewer first)
+			const depCountA = a.dependencies?.length || 0;
+			const depCountB = b.dependencies?.length || 0;
+			if (depCountA !== depCountB) return depCountA - depCountB;
+
+			// ID (lower first)
+			return Number(a.id) - Number(b.id);
+		});
+
+		const nextTask = eligibleTasks[0];
+		return {
+			id: nextTask.id,
+			title: nextTask.title,
+			priority: nextTask.priority,
+			dependencies: nextTask.dependencies?.map((d) => String(d))
+		};
+	}
+
+	/**
+	 * Get the last result (for programmatic usage)
+	 */
+	getLastResult(): ListTasksResult | undefined {
+		return this.lastResult;
+	}
+
+	/**
+	 * Clean up resources
+	 */
+	async cleanup(): Promise<void> {
+		if (this.tmCore) {
+			await this.tmCore.close();
+			this.tmCore = undefined;
+		}
+	}
+
+	/**
+	 * Static method to register this command on an existing program
+	 * This is for gradual migration - allows commands.js to use this
+	 */
+	static registerOn(program: Command): Command {
+		const listCommand = new ListTasksCommand();
+		program.addCommand(listCommand);
+		return listCommand;
+	}
+
+	/**
+	 * Alternative registration that returns the command for chaining
+	 * Can also configure the command name if needed
+	 */
+	static register(program: Command, name?: string): ListTasksCommand {
+		const listCommand = new ListTasksCommand(name);
+		program.addCommand(listCommand);
+		return listCommand;
+	}
+}

apps/cli/src/commands/set-status.command.ts

@@ -0,0 +1,318 @@
+/**
+ * @fileoverview SetStatusCommand using Commander's native class pattern
+ * Extends Commander.Command for better integration with the framework
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import boxen from 'boxen';
+import {
+	createTaskMasterCore,
+	type TaskMasterCore,
+	type TaskStatus
+} from '@tm/core';
+import type { StorageType } from '@tm/core/types';
+
+/**
+ * Valid task status values for validation
+ */
+const VALID_TASK_STATUSES: TaskStatus[] = [
+	'pending',
+	'in-progress',
+	'done',
+	'deferred',
+	'cancelled',
+	'blocked',
+	'review'
+];
+
+/**
+ * Options interface for the set-status command
+ */
+export interface SetStatusCommandOptions {
+	id?: string;
+	status?: TaskStatus;
+	format?: 'text' | 'json';
+	silent?: boolean;
+	project?: string;
+}
+
+/**
+ * Result type from set-status command
+ */
+export interface SetStatusResult {
+	success: boolean;
+	updatedTasks: Array<{
+		taskId: string;
+		oldStatus: TaskStatus;
+		newStatus: TaskStatus;
+	}>;
+	storageType: Exclude<StorageType, 'auto'>;
+}
+
+/**
+ * SetStatusCommand extending Commander's Command class
+ * This is a thin presentation layer over @tm/core
+ */
+export class SetStatusCommand extends Command {
+	private tmCore?: TaskMasterCore;
+	private lastResult?: SetStatusResult;
+
+	constructor(name?: string) {
+		super(name || 'set-status');
+
+		// Configure the command
+		this.description('Update the status of one or more tasks')
+			.requiredOption(
+				'-i, --id <id>',
+				'Task ID(s) to update (comma-separated for multiple, supports subtasks like 5.2)'
+			)
+			.requiredOption(
+				'-s, --status <status>',
+				`New status (${VALID_TASK_STATUSES.join(', ')})`
+			)
+			.option('-f, --format <format>', 'Output format (text, json)', 'text')
+			.option('--silent', 'Suppress output (useful for programmatic usage)')
+			.option('-p, --project <path>', 'Project root directory', process.cwd())
+			.action(async (options: SetStatusCommandOptions) => {
+				await this.executeCommand(options);
+			});
+	}
+
+	/**
+	 * Execute the set-status command
+	 */
+	private async executeCommand(
+		options: SetStatusCommandOptions
+	): Promise<void> {
+		try {
+			// Validate required options
+			if (!options.id) {
+				console.error(chalk.red('Error: Task ID is required. Use -i or --id'));
+				process.exit(1);
+			}
+
+			if (!options.status) {
+				console.error(
+					chalk.red('Error: Status is required. Use -s or --status')
+				);
+				process.exit(1);
+			}
+
+			// Validate status
+			if (!VALID_TASK_STATUSES.includes(options.status)) {
+				console.error(
+					chalk.red(
+						`Error: Invalid status "${options.status}". Valid options: ${VALID_TASK_STATUSES.join(', ')}`
+					)
+				);
+				process.exit(1);
+			}
+
+			// Initialize TaskMaster core
+			this.tmCore = await createTaskMasterCore({
+				projectPath: options.project || process.cwd()
+			});
+
+			// Parse task IDs (handle comma-separated values)
+			const taskIds = options.id.split(',').map((id) => id.trim());
+
+			// Update each task
+			const updatedTasks: Array<{
+				taskId: string;
+				oldStatus: TaskStatus;
+				newStatus: TaskStatus;
+			}> = [];
+
+			for (const taskId of taskIds) {
+				try {
+					const result = await this.tmCore.updateTaskStatus(
+						taskId,
+						options.status
+					);
+					updatedTasks.push({
+						taskId: result.taskId,
+						oldStatus: result.oldStatus,
+						newStatus: result.newStatus
+					});
+				} catch (error) {
+					const errorMessage =
+						error instanceof Error ? error.message : String(error);
+
+					if (!options.silent) {
+						console.error(
+							chalk.red(`Failed to update task ${taskId}: ${errorMessage}`)
+						);
+					}
+					if (options.format === 'json') {
+						console.log(
+							JSON.stringify({
+								success: false,
+								error: errorMessage,
+								taskId,
+								timestamp: new Date().toISOString()
+							})
+						);
+					}
+					process.exit(1);
+				}
+			}
+
+			// Store result for potential reuse
+			this.lastResult = {
+				success: true,
+				updatedTasks,
+				storageType: this.tmCore.getStorageType() as Exclude<
+					StorageType,
+					'auto'
+				>
+			};
+
+			// Display results
+			this.displayResults(this.lastResult, options);
+		} catch (error) {
+			const errorMessage =
+				error instanceof Error ? error.message : 'Unknown error occurred';
+
+			if (!options.silent) {
+				console.error(chalk.red(`Error: ${errorMessage}`));
+			}
+
+			if (options.format === 'json') {
+				console.log(JSON.stringify({ success: false, error: errorMessage }));
+			}
+
+			process.exit(1);
+		} finally {
+			// Clean up resources
+			if (this.tmCore) {
+				await this.tmCore.close();
+			}
+		}
+	}
+
+	/**
+	 * Display results based on format
+	 */
+	private displayResults(
+		result: SetStatusResult,
+		options: SetStatusCommandOptions
+	): void {
+		const format = options.format || 'text';
+
+		switch (format) {
+			case 'json':
+				console.log(JSON.stringify(result, null, 2));
+				break;
+
+			case 'text':
+			default:
+				if (!options.silent) {
+					this.displayTextResults(result);
+				}
+				break;
+		}
+	}
+
+	/**
+	 * Display results in text format
+	 */
+	private displayTextResults(result: SetStatusResult): void {
+		if (result.updatedTasks.length === 1) {
+			// Single task update
+			const update = result.updatedTasks[0];
+			console.log(
+				boxen(
+					chalk.white.bold(`✅ Successfully updated task ${update.taskId}`) +
+						'\n\n' +
+						`${chalk.blue('From:')} ${this.getStatusDisplay(update.oldStatus)}\n` +
+						`${chalk.blue('To:')}   ${this.getStatusDisplay(update.newStatus)}`,
+					{
+						padding: 1,
+						borderColor: 'green',
+						borderStyle: 'round',
+						margin: { top: 1 }
+					}
+				)
+			);
+		} else {
+			// Multiple task updates
+			console.log(
+				boxen(
+					chalk.white.bold(
+						`✅ Successfully updated ${result.updatedTasks.length} tasks`
+					) +
+						'\n\n' +
+						result.updatedTasks
+							.map(
+								(update) =>
+									`${chalk.cyan(update.taskId)}: ${this.getStatusDisplay(update.oldStatus)} → ${this.getStatusDisplay(update.newStatus)}`
+							)
+							.join('\n'),
+					{
+						padding: 1,
+						borderColor: 'green',
+						borderStyle: 'round',
+						margin: { top: 1 }
+					}
+				)
+			);
+		}
+
+		// Show storage info
+		console.log(chalk.gray(`\nUsing ${result.storageType} storage`));
+	}
+
+	/**
+	 * Get colored status display
+	 */
+	private getStatusDisplay(status: TaskStatus): string {
+		const statusColors: Record<TaskStatus, (text: string) => string> = {
+			pending: chalk.yellow,
+			'in-progress': chalk.blue,
+			done: chalk.green,
+			deferred: chalk.gray,
+			cancelled: chalk.red,
+			blocked: chalk.red,
+			review: chalk.magenta,
+			completed: chalk.green
+		};
+
+		const colorFn = statusColors[status] || chalk.white;
+		return colorFn(status);
+	}
+
+	/**
+	 * Get the last command result (useful for testing or chaining)
+	 */
+	getLastResult(): SetStatusResult | undefined {
+		return this.lastResult;
+	}
+
+	/**
+	 * Static method to register this command on an existing program
+	 * This is for gradual migration - allows commands.js to use this
+	 */
+	static registerOn(program: Command): Command {
+		const setStatusCommand = new SetStatusCommand();
+		program.addCommand(setStatusCommand);
+		return setStatusCommand;
+	}
+
+	/**
+	 * Alternative registration that returns the command for chaining
+	 * Can also configure the command name if needed
+	 */
+	static register(program: Command, name?: string): SetStatusCommand {
+		const setStatusCommand = new SetStatusCommand(name);
+		program.addCommand(setStatusCommand);
+		return setStatusCommand;
+	}
+}
+
+/**
+ * Factory function to create and configure the set-status command
+ */
+export function createSetStatusCommand(): SetStatusCommand {
+	return new SetStatusCommand();
+}

apps/cli/src/commands/show.command.ts

@@ -0,0 +1,383 @@
+/**
+ * @fileoverview ShowCommand using Commander's native class pattern
+ * Extends Commander.Command for better integration with the framework
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import boxen from 'boxen';
+import { createTaskMasterCore, type Task, type TaskMasterCore } from '@tm/core';
+import type { StorageType } from '@tm/core/types';
+import * as ui from '../utils/ui.js';
+import {
+	displayTaskHeader,
+	displayTaskProperties,
+	displayImplementationDetails,
+	displayTestStrategy,
+	displaySubtasks,
+	displaySuggestedActions
+} from '../ui/components/task-detail.component.js';
+
+/**
+ * Options interface for the show command
+ */
+export interface ShowCommandOptions {
+	id?: string;
+	status?: string;
+	format?: 'text' | 'json';
+	silent?: boolean;
+	project?: string;
+}
+
+/**
+ * Result type from show command
+ */
+export interface ShowTaskResult {
+	task: Task | null;
+	found: boolean;
+	storageType: Exclude<StorageType, 'auto'>;
+}
+
+/**
+ * Result type for multiple tasks
+ */
+export interface ShowMultipleTasksResult {
+	tasks: Task[];
+	notFound: string[];
+	storageType: Exclude<StorageType, 'auto'>;
+}
+
+/**
+ * ShowCommand extending Commander's Command class
+ * This is a thin presentation layer over @tm/core
+ */
+export class ShowCommand extends Command {
+	private tmCore?: TaskMasterCore;
+	private lastResult?: ShowTaskResult | ShowMultipleTasksResult;
+
+	constructor(name?: string) {
+		super(name || 'show');
+
+		// Configure the command
+		this.description('Display detailed information about one or more tasks')
+			.argument('[id]', 'Task ID(s) to show (comma-separated for multiple)')
+			.option(
+				'-i, --id <id>',
+				'Task ID(s) to show (comma-separated for multiple)'
+			)
+			.option('-s, --status <status>', 'Filter subtasks by status')
+			.option('-f, --format <format>', 'Output format (text, json)', 'text')
+			.option('--silent', 'Suppress output (useful for programmatic usage)')
+			.option('-p, --project <path>', 'Project root directory', process.cwd())
+			.action(
+				async (taskId: string | undefined, options: ShowCommandOptions) => {
+					await this.executeCommand(taskId, options);
+				}
+			);
+	}
+
+	/**
+	 * Execute the show command
+	 */
+	private async executeCommand(
+		taskId: string | undefined,
+		options: ShowCommandOptions
+	): Promise<void> {
+		try {
+			// Validate options
+			if (!this.validateOptions(options)) {
+				process.exit(1);
+			}
+
+			// Initialize tm-core
+			await this.initializeCore(options.project || process.cwd());
+
+			// Get the task ID from argument or option
+			const idArg = taskId || options.id;
+			if (!idArg) {
+				console.error(chalk.red('Error: Please provide a task ID'));
+				process.exit(1);
+			}
+
+			// Check if multiple IDs are provided (comma-separated)
+			const taskIds = idArg
+				.split(',')
+				.map((id) => id.trim())
+				.filter((id) => id.length > 0);
+
+			// Get tasks from core
+			const result =
+				taskIds.length > 1
+					? await this.getMultipleTasks(taskIds, options)
+					: await this.getSingleTask(taskIds[0], options);
+
+			// Store result for programmatic access
+			this.setLastResult(result);
+
+			// Display results
+			if (!options.silent) {
+				this.displayResults(result, options);
+			}
+		} catch (error: any) {
+			const msg = error?.getSanitizedDetails?.() ?? {
+				message: error?.message ?? String(error)
+			};
+			console.error(chalk.red(`Error: ${msg.message || 'Unexpected error'}`));
+			if (error.stack && process.env.DEBUG) {
+				console.error(chalk.gray(error.stack));
+			}
+			process.exit(1);
+		}
+	}
+
+	/**
+	 * Validate command options
+	 */
+	private validateOptions(options: ShowCommandOptions): boolean {
+		// Validate format
+		if (options.format && !['text', 'json'].includes(options.format)) {
+			console.error(chalk.red(`Invalid format: ${options.format}`));
+			console.error(chalk.gray(`Valid formats: text, json`));
+			return false;
+		}
+
+		return true;
+	}
+
+	/**
+	 * Initialize TaskMasterCore
+	 */
+	private async initializeCore(projectRoot: string): Promise<void> {
+		if (!this.tmCore) {
+			this.tmCore = await createTaskMasterCore({ projectPath: projectRoot });
+		}
+	}
+
+	/**
+	 * Get a single task from tm-core
+	 */
+	private async getSingleTask(
+		taskId: string,
+		_options: ShowCommandOptions
+	): Promise<ShowTaskResult> {
+		if (!this.tmCore) {
+			throw new Error('TaskMasterCore not initialized');
+		}
+
+		// Get the task
+		const task = await this.tmCore.getTask(taskId);
+
+		// Get storage type
+		const storageType = this.tmCore.getStorageType();
+
+		return {
+			task,
+			found: task !== null,
+			storageType: storageType as Exclude<StorageType, 'auto'>
+		};
+	}
+
+	/**
+	 * Get multiple tasks from tm-core
+	 */
+	private async getMultipleTasks(
+		taskIds: string[],
+		_options: ShowCommandOptions
+	): Promise<ShowMultipleTasksResult> {
+		if (!this.tmCore) {
+			throw new Error('TaskMasterCore not initialized');
+		}
+
+		const tasks: Task[] = [];
+		const notFound: string[] = [];
+
+		// Get each task individually
+		for (const taskId of taskIds) {
+			const task = await this.tmCore.getTask(taskId);
+			if (task) {
+				tasks.push(task);
+			} else {
+				notFound.push(taskId);
+			}
+		}
+
+		// Get storage type
+		const storageType = this.tmCore.getStorageType();
+
+		return {
+			tasks,
+			notFound,
+			storageType: storageType as Exclude<StorageType, 'auto'>
+		};
+	}
+
+	/**
+	 * Display results based on format
+	 */
+	private displayResults(
+		result: ShowTaskResult | ShowMultipleTasksResult,
+		options: ShowCommandOptions
+	): void {
+		const format = options.format || 'text';
+
+		switch (format) {
+			case 'json':
+				this.displayJson(result);
+				break;
+
+			case 'text':
+			default:
+				if ('task' in result) {
+					// Single task result
+					this.displaySingleTask(result, options);
+				} else {
+					// Multiple tasks result
+					this.displayMultipleTasks(result, options);
+				}
+				break;
+		}
+	}
+
+	/**
+	 * Display in JSON format
+	 */
+	private displayJson(result: ShowTaskResult | ShowMultipleTasksResult): void {
+		console.log(JSON.stringify(result, null, 2));
+	}
+
+	/**
+	 * Display a single task in text format
+	 */
+	private displaySingleTask(
+		result: ShowTaskResult,
+		options: ShowCommandOptions
+	): void {
+		if (!result.found || !result.task) {
+			console.log(
+				boxen(chalk.yellow(`Task not found!`), {
+					padding: { top: 0, bottom: 0, left: 1, right: 1 },
+					borderColor: 'yellow',
+					borderStyle: 'round',
+					margin: { top: 1 }
+				})
+			);
+			return;
+		}
+
+		const task = result.task;
+
+		// Display header with tag
+		displayTaskHeader(task.id, task.title);
+
+		// Display task properties in table format
+		displayTaskProperties(task);
+
+		// Display implementation details if available
+		if (task.details) {
+			console.log(); // Empty line for spacing
+			displayImplementationDetails(task.details);
+		}
+
+		// Display test strategy if available
+		if ('testStrategy' in task && task.testStrategy) {
+			console.log(); // Empty line for spacing
+			displayTestStrategy(task.testStrategy as string);
+		}
+
+		// Display subtasks if available
+		if (task.subtasks && task.subtasks.length > 0) {
+			// Filter subtasks by status if provided
+			const filteredSubtasks = options.status
+				? task.subtasks.filter((sub) => sub.status === options.status)
+				: task.subtasks;
+
+			if (filteredSubtasks.length === 0 && options.status) {
+				console.log(
+					chalk.gray(`  No subtasks with status '${options.status}'`)
+				);
+			} else {
+				displaySubtasks(filteredSubtasks, task.id);
+			}
+		}
+
+		// Display suggested actions
+		displaySuggestedActions(task.id);
+	}
+
+	/**
+	 * Display multiple tasks in text format
+	 */
+	private displayMultipleTasks(
+		result: ShowMultipleTasksResult,
+		_options: ShowCommandOptions
+	): void {
+		// Header
+		ui.displayBanner(`Tasks (${result.tasks.length} found)`);
+
+		if (result.notFound.length > 0) {
+			console.log(chalk.yellow(`\n⚠ Not found: ${result.notFound.join(', ')}`));
+		}
+
+		if (result.tasks.length === 0) {
+			ui.displayWarning('No tasks found matching the criteria.');
+			return;
+		}
+
+		// Task table
+		console.log(chalk.blue.bold(`\n📋 Tasks:\n`));
+		console.log(
+			ui.createTaskTable(result.tasks, {
+				showSubtasks: true,
+				showDependencies: true
+			})
+		);
+
+		console.log(`\n${chalk.gray('Storage: ' + result.storageType)}`);
+	}
+
+	/**
+	 * Set the last result for programmatic access
+	 */
+	private setLastResult(
+		result: ShowTaskResult | ShowMultipleTasksResult
+	): void {
+		this.lastResult = result;
+	}
+
+	/**
+	 * Get the last result (for programmatic usage)
+	 */
+	getLastResult(): ShowTaskResult | ShowMultipleTasksResult | undefined {
+		return this.lastResult;
+	}
+
+	/**
+	 * Clean up resources
+	 */
+	async cleanup(): Promise<void> {
+		if (this.tmCore) {
+			await this.tmCore.close();
+			this.tmCore = undefined;
+		}
+	}
+
+	/**
+	 * Static method to register this command on an existing program
+	 * This is for gradual migration - allows commands.js to use this
+	 */
+	static registerOn(program: Command): Command {
+		const showCommand = new ShowCommand();
+		program.addCommand(showCommand);
+		return showCommand;
+	}
+
+	/**
+	 * Alternative registration that returns the command for chaining
+	 * Can also configure the command name if needed
+	 */
+	static register(program: Command, name?: string): ShowCommand {
+		const showCommand = new ShowCommand(name);
+		program.addCommand(showCommand);
+		return showCommand;
+	}
+}

apps/cli/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Main entry point for @tm/cli package
+ * Exports all public APIs for the CLI presentation layer
+ */
+
+// Commands
+export { ListTasksCommand } from './commands/list.command.js';
+export { ShowCommand } from './commands/show.command.js';
+export { AuthCommand } from './commands/auth.command.js';
+export { ContextCommand } from './commands/context.command.js';
+export { SetStatusCommand } from './commands/set-status.command.js';
+
+// UI utilities (for other commands to use)
+export * as ui from './utils/ui.js';
+
+// Re-export commonly used types from tm-core
+export type {
+	Task,
+	TaskStatus,
+	TaskPriority,
+	TaskMasterCore
+} from '@tm/core';

apps/cli/src/ui/components/dashboard.component.ts

@@ -0,0 +1,567 @@
+/**
+ * @fileoverview Dashboard components for Task Master CLI
+ * Displays project statistics and dependency information
+ */
+
+import chalk from 'chalk';
+import boxen from 'boxen';
+import type { Task, TaskPriority } from '@tm/core/types';
+
+/**
+ * Statistics for task collection
+ */
+export interface TaskStatistics {
+	total: number;
+	done: number;
+	inProgress: number;
+	pending: number;
+	blocked: number;
+	deferred: number;
+	cancelled: number;
+	review?: number;
+	completionPercentage: number;
+}
+
+/**
+ * Statistics for dependencies
+ */
+export interface DependencyStatistics {
+	tasksWithNoDeps: number;
+	tasksReadyToWork: number;
+	tasksBlockedByDeps: number;
+	mostDependedOnTaskId?: number;
+	mostDependedOnCount?: number;
+	avgDependenciesPerTask: number;
+}
+
+/**
+ * Next task information
+ */
+export interface NextTaskInfo {
+	id: string | number;
+	title: string;
+	priority?: TaskPriority;
+	dependencies?: (string | number)[];
+	complexity?: number | string;
+}
+
+/**
+ * Status breakdown for progress bars
+ */
+export interface StatusBreakdown {
+	'in-progress'?: number;
+	pending?: number;
+	blocked?: number;
+	deferred?: number;
+	cancelled?: number;
+	review?: number;
+}
+
+/**
+ * Create a progress bar with color-coded status segments
+ */
+function createProgressBar(
+	completionPercentage: number,
+	width: number = 30,
+	statusBreakdown?: StatusBreakdown
+): string {
+	// If no breakdown provided, use simple green bar
+	if (!statusBreakdown) {
+		const filled = Math.round((completionPercentage / 100) * width);
+		const empty = width - filled;
+		return chalk.green('█').repeat(filled) + chalk.gray('░').repeat(empty);
+	}
+
+	// Build the bar with different colored sections
+	// Order matches the status display: Done, Cancelled, Deferred, In Progress, Review, Pending, Blocked
+	let bar = '';
+	let charsUsed = 0;
+
+	// 1. Green filled blocks for completed tasks (done)
+	const completedChars = Math.round((completionPercentage / 100) * width);
+	if (completedChars > 0) {
+		bar += chalk.green('█').repeat(completedChars);
+		charsUsed += completedChars;
+	}
+
+	// 2. Gray filled blocks for cancelled (won't be done)
+	if (statusBreakdown.cancelled && charsUsed < width) {
+		const cancelledChars = Math.round(
+			(statusBreakdown.cancelled / 100) * width
+		);
+		const actualChars = Math.min(cancelledChars, width - charsUsed);
+		if (actualChars > 0) {
+			bar += chalk.gray('█').repeat(actualChars);
+			charsUsed += actualChars;
+		}
+	}
+
+	// 3. Gray filled blocks for deferred (won't be done now)
+	if (statusBreakdown.deferred && charsUsed < width) {
+		const deferredChars = Math.round((statusBreakdown.deferred / 100) * width);
+		const actualChars = Math.min(deferredChars, width - charsUsed);
+		if (actualChars > 0) {
+			bar += chalk.gray('█').repeat(actualChars);
+			charsUsed += actualChars;
+		}
+	}
+
+	// 4. Blue filled blocks for in-progress (actively working)
+	if (statusBreakdown['in-progress'] && charsUsed < width) {
+		const inProgressChars = Math.round(
+			(statusBreakdown['in-progress'] / 100) * width
+		);
+		const actualChars = Math.min(inProgressChars, width - charsUsed);
+		if (actualChars > 0) {
+			bar += chalk.blue('█').repeat(actualChars);
+			charsUsed += actualChars;
+		}
+	}
+
+	// 5. Magenta empty blocks for review (almost done)
+	if (statusBreakdown.review && charsUsed < width) {
+		const reviewChars = Math.round((statusBreakdown.review / 100) * width);
+		const actualChars = Math.min(reviewChars, width - charsUsed);
+		if (actualChars > 0) {
+			bar += chalk.magenta('░').repeat(actualChars);
+			charsUsed += actualChars;
+		}
+	}
+
+	// 6. Yellow empty blocks for pending (ready to start)
+	if (statusBreakdown.pending && charsUsed < width) {
+		const pendingChars = Math.round((statusBreakdown.pending / 100) * width);
+		const actualChars = Math.min(pendingChars, width - charsUsed);
+		if (actualChars > 0) {
+			bar += chalk.yellow('░').repeat(actualChars);
+			charsUsed += actualChars;
+		}
+	}
+
+	// 7. Red empty blocks for blocked (can't start yet)
+	if (statusBreakdown.blocked && charsUsed < width) {
+		const blockedChars = Math.round((statusBreakdown.blocked / 100) * width);
+		const actualChars = Math.min(blockedChars, width - charsUsed);
+		if (actualChars > 0) {
+			bar += chalk.red('░').repeat(actualChars);
+			charsUsed += actualChars;
+		}
+	}
+
+	// Fill any remaining space with gray empty yellow blocks
+	if (charsUsed < width) {
+		bar += chalk.yellow('░').repeat(width - charsUsed);
+	}
+
+	return bar;
+}
+
+/**
+ * Calculate task statistics from a list of tasks
+ */
+export function calculateTaskStatistics(tasks: Task[]): TaskStatistics {
+	const stats: TaskStatistics = {
+		total: tasks.length,
+		done: 0,
+		inProgress: 0,
+		pending: 0,
+		blocked: 0,
+		deferred: 0,
+		cancelled: 0,
+		review: 0,
+		completionPercentage: 0
+	};
+
+	tasks.forEach((task) => {
+		switch (task.status) {
+			case 'done':
+				stats.done++;
+				break;
+			case 'in-progress':
+				stats.inProgress++;
+				break;
+			case 'pending':
+				stats.pending++;
+				break;
+			case 'blocked':
+				stats.blocked++;
+				break;
+			case 'deferred':
+				stats.deferred++;
+				break;
+			case 'cancelled':
+				stats.cancelled++;
+				break;
+			case 'review':
+				stats.review = (stats.review || 0) + 1;
+				break;
+		}
+	});
+
+	stats.completionPercentage =
+		stats.total > 0 ? Math.round((stats.done / stats.total) * 100) : 0;
+
+	return stats;
+}
+
+/**
+ * Calculate subtask statistics from tasks
+ */
+export function calculateSubtaskStatistics(tasks: Task[]): TaskStatistics {
+	const stats: TaskStatistics = {
+		total: 0,
+		done: 0,
+		inProgress: 0,
+		pending: 0,
+		blocked: 0,
+		deferred: 0,
+		cancelled: 0,
+		review: 0,
+		completionPercentage: 0
+	};
+
+	tasks.forEach((task) => {
+		if (task.subtasks && task.subtasks.length > 0) {
+			task.subtasks.forEach((subtask) => {
+				stats.total++;
+				switch (subtask.status) {
+					case 'done':
+						stats.done++;
+						break;
+					case 'in-progress':
+						stats.inProgress++;
+						break;
+					case 'pending':
+						stats.pending++;
+						break;
+					case 'blocked':
+						stats.blocked++;
+						break;
+					case 'deferred':
+						stats.deferred++;
+						break;
+					case 'cancelled':
+						stats.cancelled++;
+						break;
+					case 'review':
+						stats.review = (stats.review || 0) + 1;
+						break;
+				}
+			});
+		}
+	});
+
+	stats.completionPercentage =
+		stats.total > 0 ? Math.round((stats.done / stats.total) * 100) : 0;
+
+	return stats;
+}
+
+/**
+ * Calculate dependency statistics
+ */
+export function calculateDependencyStatistics(
+	tasks: Task[]
+): DependencyStatistics {
+	const completedTaskIds = new Set(
+		tasks.filter((t) => t.status === 'done').map((t) => t.id)
+	);
+
+	const tasksWithNoDeps = tasks.filter(
+		(t) =>
+			t.status !== 'done' && (!t.dependencies || t.dependencies.length === 0)
+	).length;
+
+	const tasksWithAllDepsSatisfied = tasks.filter(
+		(t) =>
+			t.status !== 'done' &&
+			t.dependencies &&
+			t.dependencies.length > 0 &&
+			t.dependencies.every((depId) => completedTaskIds.has(depId))
+	).length;
+
+	const tasksBlockedByDeps = tasks.filter(
+		(t) =>
+			t.status !== 'done' &&
+			t.dependencies &&
+			t.dependencies.length > 0 &&
+			!t.dependencies.every((depId) => completedTaskIds.has(depId))
+	).length;
+
+	// Calculate most depended-on task
+	const dependencyCount: Record<string, number> = {};
+	tasks.forEach((task) => {
+		if (task.dependencies && task.dependencies.length > 0) {
+			task.dependencies.forEach((depId) => {
+				const key = String(depId);
+				dependencyCount[key] = (dependencyCount[key] || 0) + 1;
+			});
+		}
+	});
+
+	let mostDependedOnTaskId: number | undefined;
+	let mostDependedOnCount = 0;
+
+	for (const [taskId, count] of Object.entries(dependencyCount)) {
+		if (count > mostDependedOnCount) {
+			mostDependedOnCount = count;
+			mostDependedOnTaskId = parseInt(taskId);
+		}
+	}
+
+	// Calculate average dependencies
+	const totalDependencies = tasks.reduce(
+		(sum, task) => sum + (task.dependencies ? task.dependencies.length : 0),
+		0
+	);
+	const avgDependenciesPerTask =
+		tasks.length > 0 ? totalDependencies / tasks.length : 0;
+
+	return {
+		tasksWithNoDeps,
+		tasksReadyToWork: tasksWithNoDeps + tasksWithAllDepsSatisfied,
+		tasksBlockedByDeps,
+		mostDependedOnTaskId,
+		mostDependedOnCount,
+		avgDependenciesPerTask
+	};
+}
+
+/**
+ * Get priority counts
+ */
+export function getPriorityBreakdown(
+	tasks: Task[]
+): Record<TaskPriority, number> {
+	const breakdown: Record<TaskPriority, number> = {
+		critical: 0,
+		high: 0,
+		medium: 0,
+		low: 0
+	};
+
+	tasks.forEach((task) => {
+		const priority = task.priority || 'medium';
+		breakdown[priority]++;
+	});
+
+	return breakdown;
+}
+
+/**
+ * Calculate status breakdown as percentages
+ */
+function calculateStatusBreakdown(stats: TaskStatistics): StatusBreakdown {
+	if (stats.total === 0) return {};
+
+	return {
+		'in-progress': (stats.inProgress / stats.total) * 100,
+		pending: (stats.pending / stats.total) * 100,
+		blocked: (stats.blocked / stats.total) * 100,
+		deferred: (stats.deferred / stats.total) * 100,
+		cancelled: (stats.cancelled / stats.total) * 100,
+		review: ((stats.review || 0) / stats.total) * 100
+	};
+}
+
+/**
+ * Format status counts in the correct order with colors
+ * @param stats - The statistics object containing counts
+ * @param isSubtask - Whether this is for subtasks (affects "Done" vs "Completed" label)
+ */
+function formatStatusLine(
+	stats: TaskStatistics,
+	isSubtask: boolean = false
+): string {
+	const parts: string[] = [];
+
+	// Order: Done, Cancelled, Deferred, In Progress, Review, Pending, Blocked
+	if (isSubtask) {
+		parts.push(`Completed: ${chalk.green(`${stats.done}/${stats.total}`)}`);
+	} else {
+		parts.push(`Done: ${chalk.green(stats.done)}`);
+	}
+
+	parts.push(`Cancelled: ${chalk.gray(stats.cancelled)}`);
+	parts.push(`Deferred: ${chalk.gray(stats.deferred)}`);
+
+	// Add line break for second row
+	const firstLine = parts.join('  ');
+	parts.length = 0;
+
+	parts.push(`In Progress: ${chalk.blue(stats.inProgress)}`);
+	parts.push(`Review: ${chalk.magenta(stats.review || 0)}`);
+	parts.push(`Pending: ${chalk.yellow(stats.pending)}`);
+	parts.push(`Blocked: ${chalk.red(stats.blocked)}`);
+
+	const secondLine = parts.join('  ');
+
+	return firstLine + '\n' + secondLine;
+}
+
+/**
+ * Display the project dashboard box
+ */
+export function displayProjectDashboard(
+	taskStats: TaskStatistics,
+	subtaskStats: TaskStatistics,
+	priorityBreakdown: Record<TaskPriority, number>
+): string {
+	// Calculate status breakdowns using the helper function
+	const taskStatusBreakdown = calculateStatusBreakdown(taskStats);
+	const subtaskStatusBreakdown = calculateStatusBreakdown(subtaskStats);
+
+	// Create progress bars with the breakdowns
+	const taskProgressBar = createProgressBar(
+		taskStats.completionPercentage,
+		30,
+		taskStatusBreakdown
+	);
+	const subtaskProgressBar = createProgressBar(
+		subtaskStats.completionPercentage,
+		30,
+		subtaskStatusBreakdown
+	);
+
+	const taskPercentage = `${taskStats.completionPercentage}% ${taskStats.done}/${taskStats.total}`;
+	const subtaskPercentage = `${subtaskStats.completionPercentage}% ${subtaskStats.done}/${subtaskStats.total}`;
+
+	const content =
+		chalk.white.bold('Project Dashboard') +
+		'\n' +
+		`Tasks Progress: ${taskProgressBar} ${chalk.yellow(taskPercentage)}\n` +
+		formatStatusLine(taskStats, false) +
+		'\n\n' +
+		`Subtasks Progress: ${subtaskProgressBar} ${chalk.cyan(subtaskPercentage)}\n` +
+		formatStatusLine(subtaskStats, true) +
+		'\n\n' +
+		chalk.cyan.bold('Priority Breakdown:') +
+		'\n' +
+		`${chalk.red('•')} ${chalk.white('High priority:')} ${priorityBreakdown.high}\n` +
+		`${chalk.yellow('•')} ${chalk.white('Medium priority:')} ${priorityBreakdown.medium}\n` +
+		`${chalk.green('•')} ${chalk.white('Low priority:')} ${priorityBreakdown.low}`;
+
+	return content;
+}
+
+/**
+ * Display the dependency dashboard box
+ */
+export function displayDependencyDashboard(
+	depStats: DependencyStatistics,
+	nextTask?: NextTaskInfo
+): string {
+	const content =
+		chalk.white.bold('Dependency Status & Next Task') +
+		'\n' +
+		chalk.cyan.bold('Dependency Metrics:') +
+		'\n' +
+		`${chalk.green('•')} ${chalk.white('Tasks with no dependencies:')} ${depStats.tasksWithNoDeps}\n` +
+		`${chalk.green('•')} ${chalk.white('Tasks ready to work on:')} ${depStats.tasksReadyToWork}\n` +
+		`${chalk.yellow('•')} ${chalk.white('Tasks blocked by dependencies:')} ${depStats.tasksBlockedByDeps}\n` +
+		`${chalk.magenta('•')} ${chalk.white('Most depended-on task:')} ${
+			depStats.mostDependedOnTaskId
+				? chalk.cyan(
+						`#${depStats.mostDependedOnTaskId} (${depStats.mostDependedOnCount} dependents)`
+					)
+				: chalk.gray('None')
+		}\n` +
+		`${chalk.blue('•')} ${chalk.white('Avg dependencies per task:')} ${depStats.avgDependenciesPerTask.toFixed(1)}\n\n` +
+		chalk.cyan.bold('Next Task to Work On:') +
+		'\n' +
+		`ID: ${nextTask ? chalk.cyan(String(nextTask.id)) : chalk.gray('N/A')} - ${
+			nextTask
+				? chalk.white.bold(nextTask.title)
+				: chalk.yellow('No task available')
+		}\n` +
+		`Priority: ${nextTask?.priority || chalk.gray('N/A')}  Dependencies: ${
+			nextTask?.dependencies?.length
+				? chalk.cyan(nextTask.dependencies.join(', '))
+				: chalk.gray('None')
+		}\n` +
+		`Complexity: ${nextTask?.complexity || chalk.gray('N/A')}`;
+
+	return content;
+}
+
+/**
+ * Display dashboard boxes side by side or stacked
+ */
+export function displayDashboards(
+	taskStats: TaskStatistics,
+	subtaskStats: TaskStatistics,
+	priorityBreakdown: Record<TaskPriority, number>,
+	depStats: DependencyStatistics,
+	nextTask?: NextTaskInfo
+): void {
+	const projectDashboardContent = displayProjectDashboard(
+		taskStats,
+		subtaskStats,
+		priorityBreakdown
+	);
+	const dependencyDashboardContent = displayDependencyDashboard(
+		depStats,
+		nextTask
+	);
+
+	// Get terminal width
+	const terminalWidth = process.stdout.columns || 80;
+	const minDashboardWidth = 50;
+	const minDependencyWidth = 50;
+	const totalMinWidth = minDashboardWidth + minDependencyWidth + 4;
+
+	// If terminal is wide enough, show side by side
+	if (terminalWidth >= totalMinWidth) {
+		const halfWidth = Math.floor(terminalWidth / 2);
+		const boxContentWidth = halfWidth - 4;
+
+		const dashboardBox = boxen(projectDashboardContent, {
+			padding: 1,
+			borderColor: 'blue',
+			borderStyle: 'round',
+			width: boxContentWidth,
+			dimBorder: false
+		});
+
+		const dependencyBox = boxen(dependencyDashboardContent, {
+			padding: 1,
+			borderColor: 'magenta',
+			borderStyle: 'round',
+			width: boxContentWidth,
+			dimBorder: false
+		});
+
+		// Create side-by-side layout
+		const dashboardLines = dashboardBox.split('\n');
+		const dependencyLines = dependencyBox.split('\n');
+		const maxHeight = Math.max(dashboardLines.length, dependencyLines.length);
+
+		const combinedLines = [];
+		for (let i = 0; i < maxHeight; i++) {
+			const dashLine = i < dashboardLines.length ? dashboardLines[i] : '';
+			const depLine = i < dependencyLines.length ? dependencyLines[i] : '';
+			const paddedDashLine = dashLine.padEnd(halfWidth, ' ');
+			combinedLines.push(paddedDashLine + depLine);
+		}
+
+		console.log(combinedLines.join('\n'));
+	} else {
+		// Show stacked vertically
+		const dashboardBox = boxen(projectDashboardContent, {
+			padding: 1,
+			borderColor: 'blue',
+			borderStyle: 'round',
+			margin: { top: 0, bottom: 1 }
+		});
+
+		const dependencyBox = boxen(dependencyDashboardContent, {
+			padding: 1,
+			borderColor: 'magenta',
+			borderStyle: 'round',
+			margin: { top: 0, bottom: 1 }
+		});
+
+		console.log(dashboardBox);
+		console.log(dependencyBox);
+	}
+}

apps/cli/src/ui/components/header.component.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Task Master header component
+ * Displays the banner, version, project info, and file path
+ */
+
+import chalk from 'chalk';
+
+/**
+ * Header configuration options
+ */
+export interface HeaderOptions {
+	title?: string;
+	tag?: string;
+	filePath?: string;
+}
+
+/**
+ * Display the Task Master header with project info
+ */
+export function displayHeader(options: HeaderOptions = {}): void {
+	const { filePath, tag } = options;
+
+	// Display tag and file path info
+	if (tag) {
+		let tagInfo = '';
+
+		if (tag && tag !== 'master') {
+			tagInfo = `🏷 tag: ${chalk.cyan(tag)}`;
+		} else {
+			tagInfo = `🏷 tag: ${chalk.cyan('master')}`;
+		}
+
+		console.log(tagInfo);
+
+		if (filePath) {
+			// Convert to absolute path if it's relative
+			const absolutePath = filePath.startsWith('/')
+				? filePath
+				: `${process.cwd()}/${filePath}`;
+			console.log(`Listing tasks from: ${chalk.dim(absolutePath)}`);
+		}
+
+		console.log(); // Empty line for spacing
+	}
+}

apps/cli/src/ui/components/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview UI components exports
+ */
+
+export * from './header.component.js';
+export * from './dashboard.component.js';
+export * from './next-task.component.js';
+export * from './suggested-steps.component.js';
+export * from './task-detail.component.js';

apps/cli/src/ui/components/next-task.component.ts

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Next task recommendation component
+ * Displays detailed information about the recommended next task
+ */
+
+import chalk from 'chalk';
+import boxen from 'boxen';
+import type { Task } from '@tm/core/types';
+
+/**
+ * Next task display options
+ */
+export interface NextTaskDisplayOptions {
+	id: string | number;
+	title: string;
+	priority?: string;
+	status?: string;
+	dependencies?: (string | number)[];
+	description?: string;
+}
+
+/**
+ * Display the recommended next task section
+ */
+export function displayRecommendedNextTask(
+	task: NextTaskDisplayOptions | undefined
+): void {
+	if (!task) {
+		// If no task available, show a message
+		console.log(
+			boxen(
+				chalk.yellow(
+					'No tasks available to work on. All tasks are either completed, blocked by dependencies, or in progress.'
+				),
+				{
+					padding: 1,
+					borderStyle: 'round',
+					borderColor: 'yellow',
+					title: '⚠ NO TASKS AVAILABLE ⚠',
+					titleAlignment: 'center'
+				}
+			)
+		);
+		return;
+	}
+
+	// Build the content for the next task box
+	const content = [];
+
+	// Task header with ID and title
+	content.push(
+		`🔥 ${chalk.hex('#FF8800').bold('Next Task to Work On:')} ${chalk.yellow(`#${task.id}`)}${chalk.hex('#FF8800').bold(` - ${task.title}`)}`
+	);
+	content.push('');
+
+	// Priority and Status line
+	const statusLine = [];
+	if (task.priority) {
+		const priorityColor =
+			task.priority === 'high'
+				? chalk.red
+				: task.priority === 'medium'
+					? chalk.yellow
+					: chalk.gray;
+		statusLine.push(`Priority: ${priorityColor.bold(task.priority)}`);
+	}
+	if (task.status) {
+		const statusDisplay =
+			task.status === 'pending'
+				? chalk.yellow('○ pending')
+				: task.status === 'in-progress'
+					? chalk.blue('▶ in-progress')
+					: chalk.gray(task.status);
+		statusLine.push(`Status: ${statusDisplay}`);
+	}
+	content.push(statusLine.join('  '));
+
+	// Dependencies
+	const depsDisplay =
+		!task.dependencies || task.dependencies.length === 0
+			? chalk.gray('None')
+			: chalk.cyan(task.dependencies.join(', '));
+	content.push(`Dependencies: ${depsDisplay}`);
+
+	// Description if available
+	if (task.description) {
+		content.push('');
+		content.push(`Description: ${chalk.white(task.description)}`);
+	}
+
+	// Action commands
+	content.push('');
+	content.push(
+		`${chalk.cyan('Start working:')} ${chalk.yellow(`task-master set-status --id=${task.id} --status=in-progress`)}`
+	);
+	content.push(
+		`${chalk.cyan('View details:')} ${chalk.yellow(`task-master show ${task.id}`)}`
+	);
+
+	// Display in a styled box with orange border
+	console.log(
+		boxen(content.join('\n'), {
+			padding: 1,
+			margin: { top: 1, bottom: 1 },
+			borderStyle: 'round',
+			borderColor: '#FFA500', // Orange color
+			title: chalk.hex('#FFA500')('⚡ RECOMMENDED NEXT TASK ⚡'),
+			titleAlignment: 'center',
+			width: process.stdout.columns * 0.97,
+			fullscreen: false
+		})
+	);
+}
+
+/**
+ * Get task description from the full task object
+ */
+export function getTaskDescription(task: Task): string | undefined {
+	// Try to get description from the task
+	// This could be from task.description or the first line of task.details
+	if ('description' in task && task.description) {
+		return task.description as string;
+	}
+
+	if ('details' in task && task.details) {
+		// Take first sentence or line from details
+		const details = task.details as string;
+		const firstLine = details.split('\n')[0];
+		const firstSentence = firstLine.split('.')[0];
+		return firstSentence;
+	}
+
+	return undefined;
+}

apps/cli/src/ui/components/suggested-steps.component.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Suggested next steps component
+ * Displays helpful command suggestions at the end of the list
+ */
+
+import chalk from 'chalk';
+import boxen from 'boxen';
+
+/**
+ * Display suggested next steps section
+ */
+export function displaySuggestedNextSteps(): void {
+	const steps = [
+		`${chalk.cyan('1.')} Run ${chalk.yellow('task-master next')} to see what to work on next`,
+		`${chalk.cyan('2.')} Run ${chalk.yellow('task-master expand --id=<id>')} to break down a task into subtasks`,
+		`${chalk.cyan('3.')} Run ${chalk.yellow('task-master set-status --id=<id> --status=done')} to mark a task as complete`
+	];
+
+	console.log(
+		boxen(
+			chalk.white.bold('Suggested Next Steps:') + '\n\n' + steps.join('\n'),
+			{
+				padding: 1,
+				margin: { top: 0, bottom: 1 },
+				borderStyle: 'round',
+				borderColor: 'gray',
+				width: process.stdout.columns * 0.97
+			}
+		)
+	);
+}

apps/cli/src/ui/components/task-detail.component.ts

@@ -0,0 +1,264 @@
+/**
+ * @fileoverview Task detail component for show command
+ * Displays detailed task information in a structured format
+ */
+
+import chalk from 'chalk';
+import boxen from 'boxen';
+import Table from 'cli-table3';
+import { marked, MarkedExtension } from 'marked';
+import { markedTerminal } from 'marked-terminal';
+import type { Task } from '@tm/core/types';
+import { getStatusWithColor, getPriorityWithColor } from '../../utils/ui.js';
+
+// Configure marked to use terminal renderer with subtle colors
+marked.use(
+	markedTerminal({
+		// More subtle colors that match the overall design
+		code: (code: string) => {
+			// Custom code block handler to preserve formatting
+			return code
+				.split('\n')
+				.map((line) => '    ' + chalk.cyan(line))
+				.join('\n');
+		},
+		blockquote: chalk.gray.italic,
+		html: chalk.gray,
+		heading: chalk.white.bold, // White bold for headings
+		hr: chalk.gray,
+		listitem: chalk.white, // White for list items
+		paragraph: chalk.white, // White for paragraphs (default text color)
+		strong: chalk.white.bold, // White bold for strong text
+		em: chalk.white.italic, // White italic for emphasis
+		codespan: chalk.cyan, // Cyan for inline code (no background)
+		del: chalk.dim.strikethrough,
+		link: chalk.blue,
+		href: chalk.blue.underline,
+		// Add more explicit code block handling
+		showSectionPrefix: false,
+		unescape: true,
+		emoji: false,
+		// Try to preserve whitespace in code blocks
+		tab: 4,
+		width: 120
+	}) as MarkedExtension
+);
+
+// Also set marked options to preserve whitespace
+marked.setOptions({
+	breaks: true,
+	gfm: true
+});
+
+/**
+ * Display the task header with tag
+ */
+export function displayTaskHeader(
+	taskId: string | number,
+	title: string
+): void {
+	// Display task header box
+	console.log(
+		boxen(chalk.white.bold(`Task: #${taskId} - ${title}`), {
+			padding: { top: 0, bottom: 0, left: 1, right: 1 },
+			borderColor: 'blue',
+			borderStyle: 'round'
+		})
+	);
+}
+
+/**
+ * Display task properties in a table format
+ */
+export function displayTaskProperties(task: Task): void {
+	const terminalWidth = process.stdout.columns * 0.95 || 100;
+	// Create table for task properties - simple 2-column layout
+	const table = new Table({
+		head: [],
+		style: {
+			head: [],
+			border: ['grey']
+		},
+		colWidths: [
+			Math.floor(terminalWidth * 0.2),
+			Math.floor(terminalWidth * 0.8)
+		],
+		wordWrap: true
+	});
+
+	const deps =
+		task.dependencies && task.dependencies.length > 0
+			? task.dependencies.map((d) => String(d)).join(', ')
+			: 'None';
+
+	// Build the left column (labels) and right column (values)
+	const labels = [
+		chalk.cyan('ID:'),
+		chalk.cyan('Title:'),
+		chalk.cyan('Status:'),
+		chalk.cyan('Priority:'),
+		chalk.cyan('Dependencies:'),
+		chalk.cyan('Complexity:'),
+		chalk.cyan('Description:')
+	].join('\n');
+
+	const values = [
+		String(task.id),
+		task.title,
+		getStatusWithColor(task.status),
+		getPriorityWithColor(task.priority),
+		deps,
+		'N/A',
+		task.description || ''
+	].join('\n');
+
+	table.push([labels, values]);
+
+	console.log(table.toString());
+}
+
+/**
+ * Display implementation details in a box
+ */
+export function displayImplementationDetails(details: string): void {
+	// Handle all escaped characters properly
+	const cleanDetails = details
+		.replace(/\\n/g, '\n') // Convert \n to actual newlines
+		.replace(/\\t/g, '\t') // Convert \t to actual tabs
+		.replace(/\\"/g, '"') // Convert \" to actual quotes
+		.replace(/\\\\/g, '\\'); // Convert \\ to single backslash
+
+	const terminalWidth = process.stdout.columns * 0.95 || 100;
+
+	// Parse markdown to terminal-friendly format
+	const markdownResult = marked(cleanDetails);
+	const formattedDetails =
+		typeof markdownResult === 'string' ? markdownResult.trim() : cleanDetails; // Fallback to original if Promise
+
+	console.log(
+		boxen(
+			chalk.white.bold('Implementation Details:') + '\n\n' + formattedDetails,
+			{
+				padding: 1,
+				borderStyle: 'round',
+				borderColor: 'cyan', // Changed to cyan to match the original
+				width: terminalWidth // Fixed width to match the original
+			}
+		)
+	);
+}
+
+/**
+ * Display test strategy in a box
+ */
+export function displayTestStrategy(testStrategy: string): void {
+	// Handle all escaped characters properly (same as implementation details)
+	const cleanStrategy = testStrategy
+		.replace(/\\n/g, '\n') // Convert \n to actual newlines
+		.replace(/\\t/g, '\t') // Convert \t to actual tabs
+		.replace(/\\"/g, '"') // Convert \" to actual quotes
+		.replace(/\\\\/g, '\\'); // Convert \\ to single backslash
+
+	const terminalWidth = process.stdout.columns * 0.95 || 100;
+
+	// Parse markdown to terminal-friendly format (same as implementation details)
+	const markdownResult = marked(cleanStrategy);
+	const formattedStrategy =
+		typeof markdownResult === 'string' ? markdownResult.trim() : cleanStrategy; // Fallback to original if Promise
+
+	console.log(
+		boxen(chalk.white.bold('Test Strategy:') + '\n\n' + formattedStrategy, {
+			padding: 1,
+			borderStyle: 'round',
+			borderColor: 'cyan', // Changed to cyan to match implementation details
+			width: terminalWidth
+		})
+	);
+}
+
+/**
+ * Display subtasks in a table format
+ */
+export function displaySubtasks(
+	subtasks: Array<{
+		id: string | number;
+		title: string;
+		status: any;
+		description?: string;
+		dependencies?: string[];
+	}>,
+	parentId: string | number
+): void {
+	const terminalWidth = process.stdout.columns * 0.95 || 100;
+	// Display subtasks header
+	console.log(
+		boxen(chalk.magenta.bold('Subtasks'), {
+			padding: { top: 0, bottom: 0, left: 1, right: 1 },
+			borderColor: 'magenta',
+			borderStyle: 'round',
+			margin: { top: 1, bottom: 0 }
+		})
+	);
+
+	// Create subtasks table
+	const table = new Table({
+		head: [
+			chalk.magenta.bold('ID'),
+			chalk.magenta.bold('Status'),
+			chalk.magenta.bold('Title'),
+			chalk.magenta.bold('Deps')
+		],
+		style: {
+			head: [],
+			border: ['grey']
+		},
+		colWidths: [
+			Math.floor(terminalWidth * 0.1),
+			Math.floor(terminalWidth * 0.15),
+			Math.floor(terminalWidth * 0.6),
+			Math.floor(terminalWidth * 0.15)
+		],
+		wordWrap: true
+	});
+
+	subtasks.forEach((subtask) => {
+		const subtaskId = `${parentId}.${subtask.id}`;
+
+		// Format dependencies
+		const deps =
+			subtask.dependencies && subtask.dependencies.length > 0
+				? subtask.dependencies.join(', ')
+				: 'None';
+
+		table.push([
+			subtaskId,
+			getStatusWithColor(subtask.status),
+			subtask.title,
+			deps
+		]);
+	});
+
+	console.log(table.toString());
+}
+
+/**
+ * Display suggested actions
+ */
+export function displaySuggestedActions(taskId: string | number): void {
+	console.log(
+		boxen(
+			chalk.white.bold('Suggested Actions:') +
+				'\n\n' +
+				`${chalk.cyan('1.')} Run ${chalk.yellow(`task-master set-status --id=${taskId} --status=in-progress`)} to start working\n` +
+				`${chalk.cyan('2.')} Run ${chalk.yellow(`task-master expand --id=${taskId}`)} to break down into subtasks\n` +
+				`${chalk.cyan('3.')} Run ${chalk.yellow(`task-master update-task --id=${taskId} --prompt="..."`)} to update details`,
+			{
+				padding: 1,
+				margin: { top: 1 },
+				borderStyle: 'round',
+				borderColor: 'green',
+				width: process.stdout.columns * 0.95 || 100
+			}
+		)
+	);
+}

apps/cli/src/ui/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Main UI exports
+ */
+
+// Export all components
+export * from './components/index.js';
+
+// Re-export existing UI utilities
+export * from '../utils/ui.js';

apps/cli/src/utils/ui.ts

@@ -0,0 +1,362 @@
+/**
+ * @fileoverview UI utilities for Task Master CLI
+ * Provides formatting, display, and visual components for the command line interface
+ */
+
+import chalk from 'chalk';
+import boxen from 'boxen';
+import Table from 'cli-table3';
+import type { Task, TaskStatus, TaskPriority } from '@tm/core/types';
+
+/**
+ * Get colored status display with ASCII icons (matches scripts/modules/ui.js style)
+ */
+export function getStatusWithColor(
+	status: TaskStatus,
+	forTable: boolean = false
+): string {
+	const statusConfig = {
+		done: {
+			color: chalk.green,
+			icon: '✓',
+			tableIcon: '✓'
+		},
+		pending: {
+			color: chalk.yellow,
+			icon: '○',
+			tableIcon: '○'
+		},
+		'in-progress': {
+			color: chalk.hex('#FFA500'),
+			icon: '▶',
+			tableIcon: '▶'
+		},
+		deferred: {
+			color: chalk.gray,
+			icon: 'x',
+			tableIcon: 'x'
+		},
+		review: {
+			color: chalk.magenta,
+			icon: '?',
+			tableIcon: '?'
+		},
+		cancelled: {
+			color: chalk.gray,
+			icon: 'x',
+			tableIcon: 'x'
+		},
+		blocked: {
+			color: chalk.red,
+			icon: '!',
+			tableIcon: '!'
+		},
+		completed: {
+			color: chalk.green,
+			icon: '✓',
+			tableIcon: '✓'
+		}
+	};
+
+	const config = statusConfig[status] || {
+		color: chalk.red,
+		icon: 'X',
+		tableIcon: 'X'
+	};
+
+	const icon = forTable ? config.tableIcon : config.icon;
+	return config.color(`${icon} ${status}`);
+}
+
+/**
+ * Get colored priority display
+ */
+export function getPriorityWithColor(priority: TaskPriority): string {
+	const priorityColors: Record<TaskPriority, (text: string) => string> = {
+		critical: chalk.red.bold,
+		high: chalk.red,
+		medium: chalk.yellow,
+		low: chalk.gray
+	};
+
+	const colorFn = priorityColors[priority] || chalk.white;
+	return colorFn(priority);
+}
+
+/**
+ * Get colored complexity display
+ */
+export function getComplexityWithColor(complexity: number | string): string {
+	const score =
+		typeof complexity === 'string' ? parseInt(complexity, 10) : complexity;
+
+	if (isNaN(score)) {
+		return chalk.gray('N/A');
+	}
+
+	if (score >= 8) {
+		return chalk.red.bold(`${score} (High)`);
+	} else if (score >= 5) {
+		return chalk.yellow(`${score} (Medium)`);
+	} else {
+		return chalk.green(`${score} (Low)`);
+	}
+}
+
+/**
+ * Truncate text to specified length
+ */
+export function truncate(text: string, maxLength: number): string {
+	if (text.length <= maxLength) {
+		return text;
+	}
+	return text.substring(0, maxLength - 3) + '...';
+}
+
+/**
+ * Create a progress bar
+ */
+export function createProgressBar(
+	completed: number,
+	total: number,
+	width: number = 30
+): string {
+	if (total === 0) {
+		return chalk.gray('No tasks');
+	}
+
+	const percentage = Math.round((completed / total) * 100);
+	const filled = Math.round((completed / total) * width);
+	const empty = width - filled;
+
+	const bar = chalk.green('█').repeat(filled) + chalk.gray('░').repeat(empty);
+
+	return `${bar} ${chalk.cyan(`${percentage}%`)} (${completed}/${total})`;
+}
+
+/**
+ * Display a fancy banner
+ */
+export function displayBanner(title: string = 'Task Master'): void {
+	console.log(
+		boxen(chalk.white.bold(title), {
+			padding: 1,
+			margin: { top: 1, bottom: 1 },
+			borderStyle: 'round',
+			borderColor: 'blue',
+			textAlignment: 'center'
+		})
+	);
+}
+
+/**
+ * Display an error message (matches scripts/modules/ui.js style)
+ */
+export function displayError(message: string, details?: string): void {
+	console.error(
+		boxen(
+			chalk.red.bold('X Error: ') +
+				chalk.white(message) +
+				(details ? '\n\n' + chalk.gray(details) : ''),
+			{
+				padding: 1,
+				borderStyle: 'round',
+				borderColor: 'red'
+			}
+		)
+	);
+}
+
+/**
+ * Display a success message
+ */
+export function displaySuccess(message: string): void {
+	console.log(
+		boxen(
+			chalk.green.bold(String.fromCharCode(8730) + ' ') + chalk.white(message),
+			{
+				padding: 1,
+				borderStyle: 'round',
+				borderColor: 'green'
+			}
+		)
+	);
+}
+
+/**
+ * Display a warning message
+ */
+export function displayWarning(message: string): void {
+	console.log(
+		boxen(chalk.yellow.bold('⚠ ') + chalk.white(message), {
+			padding: 1,
+			borderStyle: 'round',
+			borderColor: 'yellow'
+		})
+	);
+}
+
+/**
+ * Display info message
+ */
+export function displayInfo(message: string): void {
+	console.log(
+		boxen(chalk.blue.bold('i ') + chalk.white(message), {
+			padding: 1,
+			borderStyle: 'round',
+			borderColor: 'blue'
+		})
+	);
+}
+
+/**
+ * Format dependencies with their status
+ */
+export function formatDependenciesWithStatus(
+	dependencies: string[] | number[],
+	tasks: Task[]
+): string {
+	if (!dependencies || dependencies.length === 0) {
+		return chalk.gray('none');
+	}
+
+	const taskMap = new Map(tasks.map((t) => [t.id.toString(), t]));
+
+	return dependencies
+		.map((depId) => {
+			const task = taskMap.get(depId.toString());
+			if (!task) {
+				return chalk.red(`${depId} (not found)`);
+			}
+
+			const statusIcon =
+				task.status === 'done'
+					? '✓'
+					: task.status === 'in-progress'
+						? '►'
+						: '○';
+
+			return `${depId}${statusIcon}`;
+		})
+		.join(', ');
+}
+
+/**
+ * Create a task table for display
+ */
+export function createTaskTable(
+	tasks: Task[],
+	options?: {
+		showSubtasks?: boolean;
+		showComplexity?: boolean;
+		showDependencies?: boolean;
+	}
+): string {
+	const {
+		showSubtasks = false,
+		showComplexity = false,
+		showDependencies = true
+	} = options || {};
+
+	// Calculate dynamic column widths based on terminal width
+	const terminalWidth = process.stdout.columns * 0.9 || 100;
+	// Adjust column widths to better match the original layout
+	const baseColWidths = showComplexity
+		? [
+				Math.floor(terminalWidth * 0.06),
+				Math.floor(terminalWidth * 0.4),
+				Math.floor(terminalWidth * 0.15),
+				Math.floor(terminalWidth * 0.12),
+				Math.floor(terminalWidth * 0.2),
+				Math.floor(terminalWidth * 0.12)
+			] // ID, Title, Status, Priority, Dependencies, Complexity
+		: [
+				Math.floor(terminalWidth * 0.08),
+				Math.floor(terminalWidth * 0.4),
+				Math.floor(terminalWidth * 0.18),
+				Math.floor(terminalWidth * 0.12),
+				Math.floor(terminalWidth * 0.2)
+			]; // ID, Title, Status, Priority, Dependencies
+
+	const headers = [
+		chalk.blue.bold('ID'),
+		chalk.blue.bold('Title'),
+		chalk.blue.bold('Status'),
+		chalk.blue.bold('Priority')
+	];
+	const colWidths = baseColWidths.slice(0, 4);
+
+	if (showDependencies) {
+		headers.push(chalk.blue.bold('Dependencies'));
+		colWidths.push(baseColWidths[4]);
+	}
+
+	if (showComplexity) {
+		headers.push(chalk.blue.bold('Complexity'));
+		colWidths.push(baseColWidths[5] || 12);
+	}
+
+	const table = new Table({
+		head: headers,
+		style: { head: [], border: [] },
+		colWidths,
+		wordWrap: true
+	});
+
+	tasks.forEach((task) => {
+		const row: string[] = [
+			chalk.cyan(task.id.toString()),
+			truncate(task.title, colWidths[1] - 3),
+			getStatusWithColor(task.status, true), // Use table version
+			getPriorityWithColor(task.priority)
+		];
+
+		if (showDependencies) {
+			// For table display, show simple format without status icons
+			if (!task.dependencies || task.dependencies.length === 0) {
+				row.push(chalk.gray('None'));
+			} else {
+				row.push(
+					chalk.cyan(task.dependencies.map((d) => String(d)).join(', '))
+				);
+			}
+		}
+
+		if (showComplexity) {
+			// Show N/A if no complexity score
+			row.push(chalk.gray('N/A'));
+		}
+
+		table.push(row);
+
+		// Add subtasks if requested
+		if (showSubtasks && task.subtasks && task.subtasks.length > 0) {
+			task.subtasks.forEach((subtask) => {
+				const subRow: string[] = [
+					chalk.gray(` └─ ${subtask.id}`),
+					chalk.gray(truncate(subtask.title, colWidths[1] - 6)),
+					chalk.gray(getStatusWithColor(subtask.status, true)),
+					chalk.gray(subtask.priority || 'medium')
+				];
+
+				if (showDependencies) {
+					subRow.push(
+						chalk.gray(
+							subtask.dependencies && subtask.dependencies.length > 0
+								? subtask.dependencies.map((dep) => String(dep)).join(', ')
+								: 'None'
+						)
+					);
+				}
+
+				if (showComplexity) {
+					subRow.push(chalk.gray('--'));
+				}
+
+				table.push(subRow);
+			});
+		}
+	});
+
+	return table.toString();
+}

apps/cli/tsconfig.json

@@ -0,0 +1,36 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "NodeNext",
+		"lib": ["ES2022"],
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true,
+		"outDir": "./dist",
+		"baseUrl": ".",
+		"rootDir": "./src",
+		"strict": true,
+		"noImplicitAny": true,
+		"strictNullChecks": true,
+		"strictFunctionTypes": true,
+		"strictBindCallApply": true,
+		"strictPropertyInitialization": true,
+		"noImplicitThis": true,
+		"alwaysStrict": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"noImplicitReturns": true,
+		"noFallthroughCasesInSwitch": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"moduleResolution": "NodeNext",
+		"moduleDetection": "force",
+		"types": ["node"],
+		"resolveJsonModule": true,
+		"isolatedModules": true,
+		"allowImportingTsExtensions": false
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist", "tests", "**/*.test.ts", "**/*.spec.ts"]
+}

apps/docs/CHANGELOG.md

@@ -0,0 +1,5 @@
+# docs
+
+## 0.0.2
+
+## 0.0.1

apps/docs/package.json

@@ -1,14 +1,13 @@
 {
 	"name": "docs",
-	"version": "0.0.0",
+	"version": "0.0.2",
 	"private": true,
 	"description": "Task Master documentation powered by Mintlify",
 	"scripts": {
 		"dev": "mintlify dev",
-		"build": "mintlify build",
 		"preview": "mintlify preview"
 	},
 	"devDependencies": {
-		"mintlify": "^4.0.0"
+		"mintlify": "^4.2.111"
 	}
 }

apps/extension/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Change Log
 
+## 0.24.2
+
+### Patch Changes
+
+- Updated dependencies [[`8783708`](https://github.com/eyaltoledano/claude-task-master/commit/8783708e5e3389890a78fcf685d3da0580e73b3f), [`df26c65`](https://github.com/eyaltoledano/claude-task-master/commit/df26c65632000874a73504963b08f18c46283144), [`37af0f1`](https://github.com/eyaltoledano/claude-task-master/commit/37af0f191227a68d119b7f89a377bf932ee3ac66), [`c4f92f6`](https://github.com/eyaltoledano/claude-task-master/commit/c4f92f6a0aee3435c56eb8d27d9aa9204284833e), [`8783708`](https://github.com/eyaltoledano/claude-task-master/commit/8783708e5e3389890a78fcf685d3da0580e73b3f), [`4dad2fd`](https://github.com/eyaltoledano/claude-task-master/commit/4dad2fd613ceac56a65ae9d3c1c03092b8860ac9)]:
+  - task-master-ai@0.26.0
+
+## 0.24.2-rc.1
+
+### Patch Changes
+
+- Updated dependencies [[`c4f92f6`](https://github.com/eyaltoledano/claude-task-master/commit/c4f92f6a0aee3435c56eb8d27d9aa9204284833e)]:
+  - task-master-ai@0.26.0-rc.1
+
+## 0.24.2-rc.0
+
+### Patch Changes
+
+- Updated dependencies [[`8783708`](https://github.com/eyaltoledano/claude-task-master/commit/8783708e5e3389890a78fcf685d3da0580e73b3f), [`37af0f1`](https://github.com/eyaltoledano/claude-task-master/commit/37af0f191227a68d119b7f89a377bf932ee3ac66), [`8783708`](https://github.com/eyaltoledano/claude-task-master/commit/8783708e5e3389890a78fcf685d3da0580e73b3f), [`4dad2fd`](https://github.com/eyaltoledano/claude-task-master/commit/4dad2fd613ceac56a65ae9d3c1c03092b8860ac9)]:
+  - task-master-ai@0.26.0-rc.0
+
+## 0.24.1
+
+### Patch Changes
+
+- Updated dependencies [[`8933557`](https://github.com/eyaltoledano/claude-task-master/commit/89335578ffffc65504b2055c0c85aa7521e5e79b), [`db720a9`](https://github.com/eyaltoledano/claude-task-master/commit/db720a954d390bb44838cd021b8813dde8f3d8de)]:
+  - task-master-ai@0.25.1
+
+## 0.24.0
+
+### Minor Changes
+
+- [#1100](https://github.com/eyaltoledano/claude-task-master/pull/1100) [`30ca144`](https://github.com/eyaltoledano/claude-task-master/commit/30ca144231c36a6c63911f20adc225d38fb15a2f) Thanks [@vedovelli](https://github.com/vedovelli)! - Display current task ID on task details page
+
+### Patch Changes
+
+- Updated dependencies [[`04e11b5`](https://github.com/eyaltoledano/claude-task-master/commit/04e11b5e828597c0ba5b82ca7d5fb6f933e4f1e8), [`fc47714`](https://github.com/eyaltoledano/claude-task-master/commit/fc477143400fd11d953727bf1b4277af5ad308d1), [`782728f`](https://github.com/eyaltoledano/claude-task-master/commit/782728ff95aa2e3b766d48273b57f6c6753e8573), [`3dee60d`](https://github.com/eyaltoledano/claude-task-master/commit/3dee60dc3d566e3cff650accb30f994b8bb3a15e), [`e3ed4d7`](https://github.com/eyaltoledano/claude-task-master/commit/e3ed4d7c14b56894d7da675eb2b757423bea8f9d), [`04e11b5`](https://github.com/eyaltoledano/claude-task-master/commit/04e11b5e828597c0ba5b82ca7d5fb6f933e4f1e8), [`95640dc`](https://github.com/eyaltoledano/claude-task-master/commit/95640dcde87ce7879858c0a951399fb49f3b6397), [`311b243`](https://github.com/eyaltoledano/claude-task-master/commit/311b2433e23c771c8d3a4d3f5ac577302b8321e5)]:
+  - task-master-ai@0.25.0
+
+## 0.24.0-rc.0
+
+### Minor Changes
+
+- [#1040](https://github.com/eyaltoledano/claude-task-master/pull/1040) [`fc47714`](https://github.com/eyaltoledano/claude-task-master/commit/fc477143400fd11d953727bf1b4277af5ad308d1) Thanks [@DomVidja](https://github.com/DomVidja)! - "Add Kilo Code profile integration with custom modes and MCP configuration"
+
+- [#1100](https://github.com/eyaltoledano/claude-task-master/pull/1100) [`30ca144`](https://github.com/eyaltoledano/claude-task-master/commit/30ca144231c36a6c63911f20adc225d38fb15a2f) Thanks [@vedovelli](https://github.com/vedovelli)! - Display current task ID on task details page
+
+### Patch Changes
+
+- Updated dependencies [[`04e11b5`](https://github.com/eyaltoledano/claude-task-master/commit/04e11b5e828597c0ba5b82ca7d5fb6f933e4f1e8), [`fc47714`](https://github.com/eyaltoledano/claude-task-master/commit/fc477143400fd11d953727bf1b4277af5ad308d1), [`782728f`](https://github.com/eyaltoledano/claude-task-master/commit/782728ff95aa2e3b766d48273b57f6c6753e8573), [`3dee60d`](https://github.com/eyaltoledano/claude-task-master/commit/3dee60dc3d566e3cff650accb30f994b8bb3a15e), [`e3ed4d7`](https://github.com/eyaltoledano/claude-task-master/commit/e3ed4d7c14b56894d7da675eb2b757423bea8f9d), [`04e11b5`](https://github.com/eyaltoledano/claude-task-master/commit/04e11b5e828597c0ba5b82ca7d5fb6f933e4f1e8), [`95640dc`](https://github.com/eyaltoledano/claude-task-master/commit/95640dcde87ce7879858c0a951399fb49f3b6397), [`311b243`](https://github.com/eyaltoledano/claude-task-master/commit/311b2433e23c771c8d3a4d3f5ac577302b8321e5)]:
+  - task-master-ai@0.25.0-rc.0
+
 ## 0.23.1
 
 ### Patch Changes

apps/extension/esbuild.js

@@ -103,8 +103,8 @@ async function main() {
 		// This prevents the multiple React instances issue
 		// Ensure React is resolved from the workspace root to avoid duplicates
 		alias: {
-			react: path.resolve(__dirname, 'node_modules/react'),
-			'react-dom': path.resolve(__dirname, 'node_modules/react-dom')
+			react: path.resolve(__dirname, '../../node_modules/react'),
+			'react-dom': path.resolve(__dirname, '../../node_modules/react-dom')
 		},
 		define: {
 			'process.env.NODE_ENV': production ? '"production"' : '"development"',
@@ -135,8 +135,8 @@ async function main() {
 		jsxImportSource: 'react',
 		external: ['*.css'],
 		alias: {
-			react: path.resolve(__dirname, 'node_modules/react'),
-			'react-dom': path.resolve(__dirname, 'node_modules/react-dom')
+			react: path.resolve(__dirname, '../../node_modules/react'),
+			'react-dom': path.resolve(__dirname, '../../node_modules/react-dom')
 		},
 		define: {
 			'process.env.NODE_ENV': production ? '"production"' : '"development"',

apps/extension/package.json

@@ -3,7 +3,7 @@
 	"private": true,
 	"displayName": "TaskMaster",
 	"description": "A visual Kanban board interface for TaskMaster projects in VS Code",
-	"version": "0.23.1",
+	"version": "0.24.2",
 	"publisher": "Hamster",
 	"icon": "assets/icon.png",
 	"engines": {
@@ -229,6 +229,7 @@
 		"build": "npm run build:js && npm run build:css",
 		"build:js": "node ./esbuild.js --production",
 		"build:css": "npx @tailwindcss/cli -i ./src/webview/index.css -o ./dist/index.css --minify",
+		"dev": "npm run watch",
 		"package": "npm exec node ./package.mjs",
 		"package:direct": "node ./package.mjs",
 		"debug:env": "node ./debug-env.mjs",
@@ -239,7 +240,7 @@
 		"check-types": "tsc --noEmit"
 	},
 	"dependencies": {
-		"task-master-ai": "0.24.0"
+		"task-master-ai": "*"
 	},
 	"devDependencies": {
 		"@dnd-kit/core": "^6.3.1",

apps/extension/src/components/TaskDetails/TaskMetadataSidebar.tsx

@@ -1,9 +1,10 @@
 import type React from 'react';
 import { useState, useEffect } from 'react';
 import { Button } from '@/components/ui/button';
-import { Loader2 } from 'lucide-react';
+import { Loader2, Play } from 'lucide-react';
 import { PriorityBadge } from './PriorityBadge';
 import type { TaskMasterTask } from '../../webview/types';
+import { useVSCodeContext } from '../../webview/contexts/VSCodeContext';
 
 interface TaskMetadataSidebarProps {
 	currentTask: TaskMasterTask;
@@ -28,10 +29,12 @@ export const TaskMetadataSidebar: React.FC<TaskMetadataSidebarProps> = ({
 	isRegenerating = false,
 	isAppending = false
 }) => {
+	const { vscode } = useVSCodeContext();
 	const [isLoadingComplexity, setIsLoadingComplexity] = useState(false);
 	const [mcpComplexityScore, setMcpComplexityScore] = useState<
 		number | undefined
 	>(undefined);
+	const [isStartingTask, setIsStartingTask] = useState(false);
 
 	// Get complexity score from task
 	const currentComplexityScore = complexity?.score;
@@ -97,6 +100,29 @@ export const TaskMetadataSidebar: React.FC<TaskMetadataSidebarProps> = ({
 		}
 	};
 
+	// Handle starting a task
+	const handleStartTask = () => {
+		if (!currentTask || isStartingTask) {
+			return;
+		}
+
+		setIsStartingTask(true);
+
+		// Send message to extension to open terminal
+		if (vscode) {
+			vscode.postMessage({
+				type: 'openTerminal',
+				taskId: currentTask.id,
+				taskTitle: currentTask.title
+			});
+		}
+
+		// Reset loading state after a short delay
+		setTimeout(() => {
+			setIsStartingTask(false);
+		}, 500);
+	};
+
 	// Effect to handle complexity on task change
 	useEffect(() => {
 		if (currentTask?.id) {
@@ -284,6 +310,30 @@ export const TaskMetadataSidebar: React.FC<TaskMetadataSidebarProps> = ({
 					{currentTask.dependencies && currentTask.dependencies.length > 0 && (
 						<div className="border-b border-textSeparator-foreground" />
 					)}
+
+					{/* Start Task Button */}
+					<div className="mt-4">
+						<Button
+							onClick={handleStartTask}
+							variant="default"
+							size="sm"
+							className="w-full text-xs"
+							disabled={
+								isRegenerating ||
+								isAppending ||
+								isStartingTask ||
+								currentTask?.status === 'done' ||
+								currentTask?.status === 'in-progress'
+							}
+						>
+							{isStartingTask ? (
+								<Loader2 className="w-4 h-4 mr-2 animate-spin" />
+							) : (
+								<Play className="w-4 h-4 mr-2" />
+							)}
+							{isStartingTask ? 'Starting...' : 'Start Task'}
+						</Button>
+					</div>
 				</div>
 			</div>
 		</div>

apps/extension/src/services/webview-manager.ts

@@ -361,6 +361,30 @@ export class WebviewManager {
 					}
 					return;
 
+				case 'openTerminal':
+					// Open VS Code terminal for task execution
+					this.logger.log(
+						`Opening terminal for task ${data.taskId}: ${data.taskTitle}`
+					);
+
+					try {
+						const terminal = vscode.window.createTerminal({
+							name: `Task ${data.taskId}: ${data.taskTitle}`,
+							cwd: vscode.workspace.workspaceFolders?.[0]?.uri.fsPath
+						});
+						terminal.show();
+
+						this.logger.log('Terminal created and shown successfully');
+						response = { success: true };
+					} catch (error) {
+						this.logger.error('Failed to create terminal:', error);
+						response = {
+							success: false,
+							error: error instanceof Error ? error.message : 'Unknown error'
+						};
+					}
+					break;
+
 				default:
 					throw new Error(`Unknown message type: ${type}`);
 			}

assets/claude/commands/tm/remove-subtasks/remove-all-subtasks.md

@@ -0,0 +1,93 @@
+Clear all subtasks from all tasks globally.
+
+## Global Subtask Clearing
+
+Remove all subtasks across the entire project. Use with extreme caution.
+
+## Execution
+
+```bash
+task-master clear-subtasks --all
+```
+
+## Pre-Clear Analysis
+
+1. **Project-Wide Summary**
+   ```
+   Global Subtask Summary
+   ━━━━━━━━━━━━━━━━━━━━
+   Total parent tasks: 12
+   Total subtasks: 47
+   - Completed: 15
+   - In-progress: 8
+   - Pending: 24
+   
+   Work at risk: ~120 hours
+   ```
+
+2. **Critical Warnings**
+   - In-progress subtasks that will lose work
+   - Completed subtasks with valuable history
+   - Complex dependency chains
+   - Integration test results
+
+## Double Confirmation
+
+```
+⚠️  DESTRUCTIVE OPERATION WARNING ⚠️
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+This will remove ALL 47 subtasks from your project
+Including 8 in-progress and 15 completed subtasks
+
+This action CANNOT be undone
+
+Type 'CLEAR ALL SUBTASKS' to confirm:
+```
+
+## Smart Safeguards
+
+- Require explicit confirmation phrase
+- Create automatic backup
+- Log all removed data
+- Option to export first
+
+## Use Cases
+
+Valid reasons for global clear:
+- Project restructuring
+- Major pivot in approach
+- Starting fresh breakdown
+- Switching to different task organization
+
+## Process
+
+1. Full project analysis
+2. Create backup file
+3. Show detailed impact
+4. Require confirmation
+5. Execute removal
+6. Generate summary report
+
+## Alternative Suggestions
+
+Before clearing all:
+- Export subtasks to file
+- Clear only pending subtasks
+- Clear by task category
+- Archive instead of delete
+
+## Post-Clear Report
+
+```
+Global Subtask Clear Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Removed: 47 subtasks from 12 tasks
+Backup saved: .taskmaster/backup/subtasks-20240115.json
+Parent tasks updated: 12
+Time estimates adjusted: Yes
+
+Next steps:
+- Review updated task list
+- Re-expand complex tasks as needed
+- Check project timeline
+```

assets/claude/commands/tm/remove-subtasks/remove-subtasks.md

@@ -0,0 +1,86 @@
+Clear all subtasks from a specific task.
+
+Arguments: $ARGUMENTS (task ID)
+
+Remove all subtasks from a parent task at once.
+
+## Clearing Subtasks
+
+Bulk removal of all subtasks from a parent task.
+
+## Execution
+
+```bash
+task-master clear-subtasks --id=<task-id>
+```
+
+## Pre-Clear Analysis
+
+1. **Subtask Summary**
+   - Number of subtasks
+   - Completion status of each
+   - Work already done
+   - Dependencies affected
+
+2. **Impact Assessment**
+   - Data that will be lost
+   - Dependencies to be removed
+   - Effect on project timeline
+   - Parent task implications
+
+## Confirmation Required
+
+```
+Clear Subtasks Confirmation
+━━━━━━━━━━━━━━━━━━━━━━━━━
+Parent Task: #5 "Implement user authentication"
+Subtasks to remove: 4
+- #5.1 "Setup auth framework" (done)
+- #5.2 "Create login form" (in-progress)
+- #5.3 "Add validation" (pending)
+- #5.4 "Write tests" (pending)
+
+⚠️  This will permanently delete all subtask data
+Continue? (y/n)
+```
+
+## Smart Features
+
+- Option to convert to standalone tasks
+- Backup task data before clearing
+- Preserve completed work history
+- Update parent task appropriately
+
+## Process
+
+1. List all subtasks for confirmation
+2. Check for in-progress work
+3. Remove all subtasks
+4. Update parent task
+5. Clean up dependencies
+
+## Alternative Options
+
+Suggest alternatives:
+- Convert important subtasks to tasks
+- Keep completed subtasks
+- Archive instead of delete
+- Export subtask data first
+
+## Post-Clear
+
+- Show updated parent task
+- Recalculate time estimates
+- Update task complexity
+- Suggest next steps
+
+## Example
+
+```
+/project:tm/clear-subtasks 5
+→ Found 4 subtasks to remove
+→ Warning: Subtask #5.2 is in-progress
+→ Cleared all subtasks from task #5
+→ Updated parent task estimates
+→ Suggestion: Consider re-expanding with better breakdown
+```

bin/task-master.js

@@ -20,357 +20,8 @@
  * Main entry point for globally installed package
  */
 
-import { fileURLToPath } from 'url';
-import { dirname, resolve } from 'path';
-import { createRequire } from 'module';
-import { spawn } from 'child_process';
-import { Command } from 'commander';
-import { displayHelp, displayBanner } from '../scripts/modules/ui.js';
-import { registerCommands } from '../scripts/modules/commands.js';
-import { detectCamelCaseFlags } from '../scripts/modules/utils.js';
-import chalk from 'chalk';
+// Direct imports instead of spawning child processes
+import { runCLI } from '../scripts/modules/commands.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const require = createRequire(import.meta.url);
-
-// Get package information
-const packageJson = require('../package.json');
-const version = packageJson.version;
-
-// Get paths to script files
-const devScriptPath = resolve(__dirname, '../scripts/dev.js');
-const initScriptPath = resolve(__dirname, '../scripts/init.js');
-
-// Helper function to run dev.js with arguments
-function runDevScript(args) {
-	// Debug: Show the transformed arguments when DEBUG=1 is set
-	if (process.env.DEBUG === '1') {
-		console.error('\nDEBUG - CLI Wrapper Analysis:');
-		console.error('- Original command: ' + process.argv.join(' '));
-		console.error('- Transformed args: ' + args.join(' '));
-		console.error(
-			'- dev.js will receive: node ' +
-				devScriptPath +
-				' ' +
-				args.join(' ') +
-				'\n'
-		);
-	}
-
-	// For testing: If TEST_MODE is set, just print args and exit
-	if (process.env.TEST_MODE === '1') {
-		console.log('Would execute:');
-		console.log(`node ${devScriptPath} ${args.join(' ')}`);
-		process.exit(0);
-		return;
-	}
-
-	const child = spawn('node', [devScriptPath, ...args], {
-		stdio: 'inherit',
-		cwd: process.cwd()
-	});
-
-	child.on('close', (code) => {
-		process.exit(code);
-	});
-}
-
-// Helper function to detect camelCase and convert to kebab-case
-const toKebabCase = (str) => str.replace(/([A-Z])/g, '-$1').toLowerCase();
-
-/**
- * Create a wrapper action that passes the command to dev.js
- * @param {string} commandName - The name of the command
- * @returns {Function} Wrapper action function
- */
-function createDevScriptAction(commandName) {
-	return (options, cmd) => {
-		// Check for camelCase flags and error out with helpful message
-		const camelCaseFlags = detectCamelCaseFlags(process.argv);
-
-		// If camelCase flags were found, show error and exit
-		if (camelCaseFlags.length > 0) {
-			console.error('\nError: Please use kebab-case for CLI flags:');
-			camelCaseFlags.forEach((flag) => {
-				console.error(`  Instead of: --${flag.original}`);
-				console.error(`  Use:        --${flag.kebabCase}`);
-			});
-			console.error(
-				'\nExample: task-master parse-prd --num-tasks=5 instead of --numTasks=5\n'
-			);
-			process.exit(1);
-		}
-
-		// Since we've ensured no camelCase flags, we can now just:
-		// 1. Start with the command name
-		const args = [commandName];
-
-		// 3. Get positional arguments and explicit flags from the command line
-		const commandArgs = [];
-		const positionals = new Set(); // Track positional args we've seen
-
-		// Find the command in raw process.argv to extract args
-		const commandIndex = process.argv.indexOf(commandName);
-		if (commandIndex !== -1) {
-			// Process all args after the command name
-			for (let i = commandIndex + 1; i < process.argv.length; i++) {
-				const arg = process.argv[i];
-
-				if (arg.startsWith('--')) {
-					// It's a flag - pass through as is
-					commandArgs.push(arg);
-					// Skip the next arg if this is a flag with a value (not --flag=value format)
-					if (
-						!arg.includes('=') &&
-						i + 1 < process.argv.length &&
-						!process.argv[i + 1].startsWith('--')
-					) {
-						commandArgs.push(process.argv[++i]);
-					}
-				} else if (!positionals.has(arg)) {
-					// It's a positional argument we haven't seen
-					commandArgs.push(arg);
-					positionals.add(arg);
-				}
-			}
-		}
-
-		// Add all command line args we collected
-		args.push(...commandArgs);
-
-		// 4. Add default options from Commander if not specified on command line
-		// Track which options we've seen on the command line
-		const userOptions = new Set();
-		for (const arg of commandArgs) {
-			if (arg.startsWith('--')) {
-				// Extract option name (without -- and value)
-				const name = arg.split('=')[0].slice(2);
-				userOptions.add(name);
-
-				// Add the kebab-case version too, to prevent duplicates
-				const kebabName = name.replace(/([A-Z])/g, '-$1').toLowerCase();
-				userOptions.add(kebabName);
-
-				// Add the camelCase version as well
-				const camelName = kebabName.replace(/-([a-z])/g, (_, letter) =>
-					letter.toUpperCase()
-				);
-				userOptions.add(camelName);
-			}
-		}
-
-		// Add Commander-provided defaults for options not specified by user
-		Object.entries(options).forEach(([key, value]) => {
-			// Debug output to see what keys we're getting
-			if (process.env.DEBUG === '1') {
-				console.error(`DEBUG - Processing option: ${key} = ${value}`);
-			}
-
-			// Special case for numTasks > num-tasks (a known problem case)
-			if (key === 'numTasks') {
-				if (process.env.DEBUG === '1') {
-					console.error('DEBUG - Converting numTasks to num-tasks');
-				}
-				if (!userOptions.has('num-tasks') && !userOptions.has('numTasks')) {
-					args.push(`--num-tasks=${value}`);
-				}
-				return;
-			}
-
-			// Skip built-in Commander properties and options the user provided
-			if (
-				['parent', 'commands', 'options', 'rawArgs'].includes(key) ||
-				userOptions.has(key)
-			) {
-				return;
-			}
-
-			// Also check the kebab-case version of this key
-			const kebabKey = key.replace(/([A-Z])/g, '-$1').toLowerCase();
-			if (userOptions.has(kebabKey)) {
-				return;
-			}
-
-			// Add default values, using kebab-case for the parameter name
-			if (value !== undefined) {
-				if (typeof value === 'boolean') {
-					if (value === true) {
-						args.push(`--${kebabKey}`);
-					} else if (value === false && key === 'generate') {
-						args.push('--skip-generate');
-					}
-				} else {
-					// Always use kebab-case for option names
-					args.push(`--${kebabKey}=${value}`);
-				}
-			}
-		});
-
-		// Special handling for parent parameter (uses -p)
-		if (options.parent && !args.includes('-p') && !userOptions.has('parent')) {
-			args.push('-p', options.parent);
-		}
-
-		// Debug output for troubleshooting
-		if (process.env.DEBUG === '1') {
-			console.error('DEBUG - Command args:', commandArgs);
-			console.error('DEBUG - User options:', Array.from(userOptions));
-			console.error('DEBUG - Commander options:', options);
-			console.error('DEBUG - Final args:', args);
-		}
-
-		// Run the script with our processed args
-		runDevScript(args);
-	};
-}
-
-// // Special case for the 'init' command which uses a different script
-// function registerInitCommand(program) {
-// 	program
-// 		.command('init')
-// 		.description('Initialize a new project')
-// 		.option('-y, --yes', 'Skip prompts and use default values')
-// 		.option('-n, --name <name>', 'Project name')
-// 		.option('-d, --description <description>', 'Project description')
-// 		.option('-v, --version <version>', 'Project version')
-// 		.option('-a, --author <author>', 'Author name')
-// 		.option('--skip-install', 'Skip installing dependencies')
-// 		.option('--dry-run', 'Show what would be done without making changes')
-// 		.action((options) => {
-// 			// Pass through any options to the init script
-// 			const args = [
-// 				'--yes',
-// 				'name',
-// 				'description',
-// 				'version',
-// 				'author',
-// 				'skip-install',
-// 				'dry-run'
-// 			]
-// 				.filter((opt) => options[opt])
-// 				.map((opt) => {
-// 					if (opt === 'yes' || opt === 'skip-install' || opt === 'dry-run') {
-// 						return `--${opt}`;
-// 					}
-// 					return `--${opt}=${options[opt]}`;
-// 				});
-
-// 			const child = spawn('node', [initScriptPath, ...args], {
-// 				stdio: 'inherit',
-// 				cwd: process.cwd()
-// 			});
-
-// 			child.on('close', (code) => {
-// 				process.exit(code);
-// 			});
-// 		});
-// }
-
-// Set up the command-line interface
-const program = new Command();
-
-program
-	.name('task-master')
-	.description('Claude Task Master CLI')
-	.version(version)
-	.addHelpText('afterAll', () => {
-		// Use the same help display function as dev.js for consistency
-		displayHelp();
-		return ''; // Return empty string to prevent commander's default help
-	});
-
-// Add custom help option to directly call our help display
-program.helpOption('-h, --help', 'Display help information');
-program.on('--help', () => {
-	displayHelp();
-});
-
-// // Add special case commands
-// registerInitCommand(program);
-
-program
-	.command('dev')
-	.description('Run the dev.js script')
-	.action(() => {
-		const args = process.argv.slice(process.argv.indexOf('dev') + 1);
-		runDevScript(args);
-	});
-
-// Use a temporary Command instance to get all command definitions
-const tempProgram = new Command();
-registerCommands(tempProgram);
-
-// For each command in the temp instance, add a modified version to our actual program
-tempProgram.commands.forEach((cmd) => {
-	if (['dev'].includes(cmd.name())) {
-		// Skip commands we've already defined specially
-		return;
-	}
-
-	// Create a new command with the same name and description
-	const newCmd = program.command(cmd.name()).description(cmd.description());
-
-	// Copy all options
-	cmd.options.forEach((opt) => {
-		newCmd.option(opt.flags, opt.description, opt.defaultValue);
-	});
-
-	// Set the action to proxy to dev.js
-	newCmd.action(createDevScriptAction(cmd.name()));
-});
-
-// Parse the command line arguments
-program.parse(process.argv);
-
-// Add global error handling for unknown commands and options
-process.on('uncaughtException', (err) => {
-	// Check if this is a commander.js unknown option error
-	if (err.code === 'commander.unknownOption') {
-		const option = err.message.match(/'([^']+)'/)?.[1];
-		const commandArg = process.argv.find(
-			(arg) =>
-				!arg.startsWith('-') &&
-				arg !== 'task-master' &&
-				!arg.includes('/') &&
-				arg !== 'node'
-		);
-		const command = commandArg || 'unknown';
-
-		console.error(chalk.red(`Error: Unknown option '${option}'`));
-		console.error(
-			chalk.yellow(
-				`Run 'task-master ${command} --help' to see available options for this command`
-			)
-		);
-		process.exit(1);
-	}
-
-	// Check if this is a commander.js unknown command error
-	if (err.code === 'commander.unknownCommand') {
-		const command = err.message.match(/'([^']+)'/)?.[1];
-
-		console.error(chalk.red(`Error: Unknown command '${command}'`));
-		console.error(
-			chalk.yellow(`Run 'task-master --help' to see available commands`)
-		);
-		process.exit(1);
-	}
-
-	// Handle other uncaught exceptions
-	console.error(chalk.red(`Error: ${err.message}`));
-	if (process.env.DEBUG === '1') {
-		console.error(err);
-	}
-	process.exit(1);
-});
-
-// Show help if no command was provided (just 'task-master' with no args)
-if (process.argv.length <= 2) {
-	displayBanner();
-	displayHelp();
-	process.exit(0);
-}
-
-// Add exports at the end of the file
-export { detectCamelCaseFlags };
+// Simply run the CLI directly
+runCLI();

docs/CLI-COMMANDER-PATTERN.md

@@ -0,0 +1,131 @@
+# CLI Commander Class Pattern
+
+## Overview
+We're using Commander.js's native class pattern instead of custom abstractions. This is cleaner, more maintainable, and uses the framework as designed.
+
+## Architecture
+
+```
+@tm/core (Business Logic)          @tm/cli (Presentation)
+┌─────────────────────┐            ┌──────────────────────────┐
+│ TaskMasterCore      │◄───────────│ ListTasksCommand         │
+│ - getTaskList()     │            │ extends Commander.Command│
+│ - getTask()         │            │ - display logic only     │
+│ - getNextTask()     │            │ - formatting             │
+└─────────────────────┘            └──────────────────────────┘
+         ▲                                      ▲
+         │                                      │
+         └──────── Gets Data ──────────────────┘
+                                     Displays Data
+```
+
+## Implementation
+
+### Command Class Pattern
+
+```typescript
+// apps/cli/src/commands/list-tasks-commander.ts
+export class ListTasksCommand extends Command {
+  constructor(name?: string) {
+    super(name || 'list');
+    
+    this
+      .description('List tasks')
+      .option('-s, --status <status>', 'Filter by status')
+      .action(async (options) => {
+        // 1. Get data from @tm/core
+        const result = await this.tmCore.getTaskList(options);
+        
+        // 2. Display data (presentation only)
+        this.displayResults(result, options);
+      });
+  }
+}
+```
+
+### Main CLI Class
+
+```typescript
+// apps/cli/src/cli-commander.ts
+class TaskMasterCLI extends Command {
+  createCommand(name?: string): Command {
+    switch (name) {
+      case 'list':
+        return new ListTasksCommand(name);
+      default:
+        return new Command(name);
+    }
+  }
+}
+```
+
+## Integration with Existing Scripts
+
+### Gradual Migration Path
+
+```javascript
+// scripts/modules/commands.js
+
+// OLD WAY (keep working during migration)
+program
+  .command('old-list')
+  .action(async (options) => {
+    await listTasksV2(...);
+  });
+
+// NEW WAY (add alongside old)
+import { ListTasksCommand } from '@tm/cli';
+program.addCommand(new ListTasksCommand());
+```
+
+### Benefits
+
+1. **No Custom Abstractions**: Using Commander.js as designed
+2. **Clean Separation**: Business logic in core, presentation in CLI
+3. **Gradual Migration**: Can migrate one command at a time
+4. **Type Safety**: Full TypeScript support with Commander types
+5. **Framework Native**: Better documentation, examples, and community support
+
+## Migration Steps
+
+1. **Phase 1**: Build command classes in @tm/cli (current)
+2. **Phase 2**: Import in scripts/modules/commands.js
+3. **Phase 3**: Replace old implementations one by one
+4. **Phase 4**: Remove old code when all migrated
+
+## Example Usage
+
+### In New Code
+```javascript
+import { ListTasksCommand } from '@tm/cli';
+const program = new Command();
+program.addCommand(new ListTasksCommand());
+```
+
+### In Existing Scripts
+```javascript
+// Gradual adoption
+const listCmd = new ListTasksCommand();
+program.addCommand(listCmd);
+```
+
+### Programmatic Usage
+```javascript
+const listCommand = new ListTasksCommand();
+await listCommand.parseAsync(['node', 'script', '--format', 'json']);
+```
+
+## POC Status
+
+✅ **Completed**:
+- ListTasksCommand extends Commander.Command
+- Clean separation of concerns
+- Integration examples
+- Build configuration
+
+🚧 **Next Steps**:
+- Migrate more commands
+- Update existing scripts to use new classes
+- Remove old implementations gradually
+
+This POC proves the pattern works and provides a clean migration path!

docs/cross-tag-task-movement.md

@@ -65,11 +65,10 @@ This removes the dependency relationships and moves only the specified task.
 
 ### Force Move
 
-Force the move even with dependency conflicts:
+Note: Force moves are no longer supported. Instead, use one of these options:
 
-```bash
-task-master move --from=5 --from-tag=backlog --to-tag=in-progress --force
-```
+- `--with-dependencies` — move dependents together
+- `--ignore-dependencies` — break cross-tag dependencies
 
 ⚠️ **Warning**: This may break dependency relationships and should be used with caution.
 
@@ -93,7 +92,7 @@ Resolution options:
   2. Break dependencies: task-master move --from=5,6 --from-tag=backlog --to-tag=in-progress --ignore-dependencies
   3. Validate and fix dependencies: task-master validate-dependencies && task-master fix-dependencies
   4. Move dependencies first: task-master move --from=2,3 --from-tag=backlog --to-tag=in-progress
-  5. Force move (may break dependencies): task-master move --from=5,6 --from-tag=backlog --to-tag=in-progress --force
+  5. After deciding, re-run the move with either --with-dependencies or --ignore-dependencies
 ```
 
 ### Subtask Movement Restrictions
@@ -149,7 +148,6 @@ task-master fix-dependencies
 
 - **`--with-dependencies`**: When you want to maintain task relationships
 - **`--ignore-dependencies`**: When you want to break cross-tag dependencies
-- **`--force`**: Only when you understand the consequences
 
 ### 3. Organize by Context
 
@@ -265,9 +263,14 @@ task-master move --from=5 --from-tag=backlog --to-tag=done --ignore-dependencies
 
 ### Scenario 3: Force Move
 
+Choose one of these options explicitly:
+
 ```bash
-# Force move despite conflicts
-task-master move --from=5 --from-tag=backlog --to-tag=in-progress --force
+# Move together with dependencies
+task-master move --from=5 --from-tag=backlog --to-tag=in-progress --with-dependencies
+
+# Or break dependencies
+task-master move --from=5 --from-tag=backlog --to-tag=in-progress --ignore-dependencies
 ```
 
 ### Scenario 4: Moving Subtasks

jest.config.js

@@ -18,7 +18,17 @@ export default {
 	testMatch: ['**/__tests__/**/*.js', '**/?(*.)+(spec|test).js'],
 
 	// Transform files
-	transform: {},
+	preset: 'ts-jest/presets/default-esm',
+	extensionsToTreatAsEsm: ['.ts'],
+	moduleFileExtensions: ['js', 'ts', 'json', 'node'],
+	transform: {
+		'^.+\\.ts$': [
+			'ts-jest',
+			{
+				useESM: true
+			}
+		]
+	},
 
 	// Disable transformations for node_modules
 	transformIgnorePatterns: ['/node_modules/'],
@@ -27,6 +37,7 @@ export default {
 	moduleNameMapper: {
 		'^@/(.*)$': '<rootDir>/$1'
 	},
+	resolver: '<rootDir>/jest.resolver.cjs',
 
 	// Setup module aliases
 	moduleDirectories: ['node_modules', '<rootDir>'],

jest.resolver.cjs

@@ -0,0 +1,19 @@
+const { defaultResolver } = require('jest-resolve');
+module.exports = function customResolver(request, options) {
+	const resolve = options.defaultResolver || defaultResolver;
+
+	try {
+		return resolve(request, options);
+	} catch (error) {
+		if (request.startsWith('.') && request.endsWith('.js')) {
+			try {
+				return resolve(request.replace(/\.js$/, '.ts'), options);
+			} catch (tsError) {
+				tsError.cause = tsError.cause ?? error;
+				throw tsError;
+			}
+		}
+
+		throw error;
+	}
+};

mcp-server/src/core/direct-functions/move-task-cross-tag.js

@@ -189,6 +189,17 @@ export async function moveTaskCrossTagDirect(args, log, context = {}) {
 				'Verify task IDs exist: task-master list',
 				'Check task details: task-master show <id>'
 			];
+		} else if (
+			error.code === 'TASK_ALREADY_EXISTS' ||
+			error.message?.includes('already exists in target tag')
+		) {
+			// Target tag has an ID collision
+			errorCode = 'TASK_ALREADY_EXISTS';
+			suggestions = [
+				'Choose a different target tag without conflicting IDs',
+				'Move a different set of IDs (avoid existing ones)',
+				'If needed, move within-tag to a new ID first, then cross-tag move'
+			];
 		}
 
 		return {

mcp-server/src/index.js

@@ -7,6 +7,7 @@ import logger from './logger.js';
 import { registerTaskMasterTools } from './tools/index.js';
 import ProviderRegistry from '../../src/provider-registry/index.js';
 import { MCPProvider } from './providers/mcp-provider.js';
+import packageJson from '../../package.json' with { type: 'json' };
 
 // Load environment variables
 dotenv.config();
@@ -20,10 +21,6 @@ const __dirname = path.dirname(__filename);
  */
 class TaskMasterMCPServer {
 	constructor() {
-		// Get version from package.json using synchronous fs
-		const packagePath = path.join(__dirname, '../../package.json');
-		const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
-
 		this.options = {
 			name: 'Task Master MCP Server',
 			version: packageJson.version

mcp-server/src/tools/utils.js

@@ -8,6 +8,7 @@ import path from 'path';
 import fs from 'fs';
 import { contextManager } from '../core/context-manager.js'; // Import the singleton
 import { fileURLToPath } from 'url';
+import packageJson from '../../../package.json' with { type: 'json' };
 import { getCurrentTag } from '../../../scripts/modules/utils.js';
 
 // Import path utilities to ensure consistent path resolution
@@ -31,34 +32,13 @@ function getVersionInfo() {
 		return cachedVersionInfo;
 	}
 
-	try {
-		// Navigate to the project root from the tools directory
-		const packageJsonPath = path.join(
-			path.dirname(__filename),
-			'../../../package.json'
-		);
-		if (fs.existsSync(packageJsonPath)) {
-			const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+	// Use the imported packageJson directly
 	cachedVersionInfo = {
-				version: packageJson.version,
-				name: packageJson.name
+		version: packageJson.version || 'unknown',
+		name: packageJson.name || 'task-master-ai'
 	};
 	return cachedVersionInfo;
 }
-		cachedVersionInfo = {
-			version: 'unknown',
-			name: 'task-master-ai'
-		};
-		return cachedVersionInfo;
-	} catch (error) {
-		// Fallback version info if package.json can't be read
-		cachedVersionInfo = {
-			version: 'unknown',
-			name: 'task-master-ai'
-		};
-		return cachedVersionInfo;
-	}
-}
 
 /**
  * Get current tag information for MCP responses

package.json

@@ -1,27 +1,37 @@
 {
 	"name": "task-master-ai",
-	"version": "0.24.0",
+	"version": "0.26.0",
 	"description": "A task management system for ambitious AI-driven development that doesn't overwhelm and confuse Cursor.",
 	"main": "index.js",
 	"type": "module",
 	"bin": {
-		"task-master": "bin/task-master.js",
-		"task-master-mcp": "mcp-server/server.js",
-		"task-master-ai": "mcp-server/server.js"
+		"task-master": "dist/task-master.js",
+		"task-master-mcp": "dist/mcp-server.js",
+		"task-master-ai": "dist/mcp-server.js"
 	},
-	"workspaces": ["apps/*", "."],
+	"workspaces": ["apps/*", "packages/*", "."],
 	"scripts": {
+		"build": "npm run build:build-config && cross-env NODE_ENV=production tsdown",
+		"dev": "tsdown --watch",
+		"turbo:dev": "turbo dev",
+		"turbo:build": "turbo build",
+		"turbo:typecheck": "turbo typecheck",
+		"build:build-config": "npm run build -w @tm/build-config",
 		"test": "node --experimental-vm-modules node_modules/.bin/jest",
+		"test:unit": "node --experimental-vm-modules node_modules/.bin/jest --testPathPattern=unit",
+		"test:integration": "node --experimental-vm-modules node_modules/.bin/jest --testPathPattern=integration",
 		"test:fails": "node --experimental-vm-modules node_modules/.bin/jest --onlyFailures",
 		"test:watch": "node --experimental-vm-modules node_modules/.bin/jest --watch",
 		"test:coverage": "node --experimental-vm-modules node_modules/.bin/jest --coverage",
+		"test:ci": "node --experimental-vm-modules node_modules/.bin/jest --coverage --ci",
 		"test:e2e": "./tests/e2e/run_e2e.sh",
 		"test:e2e-report": "./tests/e2e/run_e2e.sh --analyze-log",
-		"prepare": "chmod +x bin/task-master.js mcp-server/server.js",
+		"postpack": "chmod +x dist/task-master.js dist/mcp-server.js",
 		"changeset": "changeset",
 		"release": "changeset publish",
-		"inspector": "npx @modelcontextprotocol/inspector node mcp-server/server.js",
-		"mcp-server": "node mcp-server/server.js",
+		"publish-packages": "turbo run build lint test && changeset version && changeset publish",
+		"inspector": "npx @modelcontextprotocol/inspector node dist/mcp-server.js",
+		"mcp-server": "node dist/mcp-server.js",
 		"format-check": "biome format .",
 		"format": "biome format . --write"
 	},
@@ -55,11 +65,12 @@
 		"@inquirer/search": "^3.0.15",
 		"@openrouter/ai-sdk-provider": "^0.4.5",
 		"@streamparser/json": "^0.0.22",
+		"@tm/cli": "*",
 		"ai": "^4.3.10",
 		"ajv": "^8.17.1",
 		"ajv-formats": "^3.0.1",
 		"boxen": "^8.0.1",
-		"chalk": "^5.4.1",
+		"chalk": "5.6.2",
 		"cli-highlight": "^2.1.11",
 		"cli-progress": "^3.12.0",
 		"cli-table3": "^0.6.5",
@@ -78,6 +89,8 @@
 		"jsonrepair": "^3.13.0",
 		"jsonwebtoken": "^9.0.2",
 		"lru-cache": "^10.2.0",
+		"marked": "^15.0.12",
+		"marked-terminal": "^7.3.0",
 		"ollama-ai-provider": "^1.2.0",
 		"openai": "^4.89.0",
 		"ora": "^8.2.0",
@@ -86,13 +99,14 @@
 		"zod-to-json-schema": "^3.24.5"
 	},
 	"optionalDependencies": {
-		"@anthropic-ai/claude-code": "^1.0.25",
+		"@anthropic-ai/claude-code": "^1.0.88",
 		"@biomejs/cli-linux-x64": "^1.9.4",
-		"ai-sdk-provider-gemini-cli": "^0.1.1"
+		"ai-sdk-provider-gemini-cli": "^0.1.3"
 	},
 	"engines": {
 		"node": ">=18.0.0"
 	},
+	"packageManager": "npm@10.9.2",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/eyaltoledano/claude-task-master.git"
@@ -101,16 +115,7 @@
 	"bugs": {
 		"url": "https://github.com/eyaltoledano/claude-task-master/issues"
 	},
-	"files": [
-		"scripts/**",
-		"assets/**",
-		".cursor/**",
-		"README-task-master.md",
-		"index.js",
-		"bin/**",
-		"mcp-server/**",
-		"src/**"
-	],
+	"files": ["dist/**", "README-task-master.md", "README.md", "LICENSE"],
 	"overrides": {
 		"node-fetch": "^2.6.12",
 		"whatwg-url": "^11.0.0"
@@ -120,13 +125,20 @@
 		"@changesets/changelog-github": "^0.5.1",
 		"@changesets/cli": "^2.28.1",
 		"@types/jest": "^29.5.14",
+		"@types/marked-terminal": "^6.1.1",
+		"concurrently": "^9.2.1",
+		"cross-env": "^10.0.0",
+		"dotenv-mono": "^1.5.1",
 		"execa": "^8.0.1",
-		"ink": "^5.0.1",
 		"jest": "^29.7.0",
 		"jest-environment-node": "^29.7.0",
 		"mock-fs": "^5.5.0",
 		"prettier": "^3.5.3",
 		"supertest": "^7.1.0",
-		"tsx": "^4.16.2"
+		"ts-jest": "^29.4.2",
+		"tsdown": "^0.15.2",
+		"tsx": "^4.16.2",
+		"turbo": "^2.5.6",
+		"typescript": "^5.9.2"
 	}
 }

packages/build-config/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "@tm/build-config",
+	"version": "1.0.0",
+	"description": "Shared build configuration for Task Master monorepo",
+	"type": "module",
+	"private": true,
+	"main": "./dist/tsdown.base.js",
+	"types": "./src/tsdown.base.ts",
+	"exports": {
+		".": {
+			"types": "./src/tsdown.base.ts",
+			"import": "./dist/tsdown.base.js"
+		}
+	},
+	"files": ["dist", "src"],
+	"keywords": ["build-config", "tsup", "monorepo"],
+	"author": "",
+	"license": "MIT",
+	"scripts": {
+		"build": "tsc",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"dotenv-mono": "^1.5.1",
+		"typescript": "^5.7.3"
+	},
+	"dependencies": {
+		"tsup": "^8.5.0"
+	}
+}

packages/build-config/src/tsdown.base.ts

@@ -0,0 +1,46 @@
+/**
+ * Base tsdown configuration for Task Master monorepo
+ * Provides shared configuration that can be extended by individual packages
+ */
+import type { UserConfig } from 'tsdown';
+
+const isProduction = process.env.NODE_ENV === 'production';
+const isDevelopment = !isProduction;
+
+/**
+ * Environment helpers
+ */
+export const env = {
+	isProduction,
+	isDevelopment,
+	NODE_ENV: process.env.NODE_ENV || 'development'
+};
+
+/**
+ * Base tsdown configuration for all packages
+ * Since everything gets bundled into root dist/ anyway, use consistent settings
+ */
+export const baseConfig: Partial<UserConfig> = {
+	sourcemap: isDevelopment,
+	format: 'esm',
+	platform: 'node',
+	dts: isDevelopment,
+	minify: isProduction,
+	treeshake: isProduction,
+	// Keep all npm dependencies external (available via node_modules)
+	external: [/^[^@./]/, /^@(?!tm\/)/]
+};
+
+/**
+ * Utility function to merge configurations
+ * Simplified for tsdown usage
+ */
+export function mergeConfig(
+	base: Partial<UserConfig>,
+	overrides: Partial<UserConfig>
+): Partial<UserConfig> {
+	return {
+		...base,
+		...overrides
+	};
+}

packages/build-config/tsconfig.json

@@ -0,0 +1,21 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"lib": ["ES2022"],
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"allowSyntheticDefaultImports": true,
+		"esModuleInterop": true,
+		"baseUrl": ".",
+		"outDir": "dist",
+		"allowJs": true,
+		"strict": true,
+		"resolveJsonModule": true,
+		"isolatedModules": true,
+		"declaration": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}

packages/tm-core/.gitignore

@@ -0,0 +1,83 @@
+# Dependencies
+node_modules/
+*.pnp
+.pnp.js
+
+# Build output
+dist/
+build/
+*.tsbuildinfo
+
+# Coverage reports
+coverage/
+*.lcov
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# nyc test coverage
+.nyc_output
+
+# Dependency directories
+jspm_packages/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

packages/tm-core/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to the @task-master/tm-core package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial package structure and configuration
+- TypeScript support with strict mode
+- Dual ESM/CJS build system with tsup
+- Jest testing framework with TypeScript support
+- ESLint and Prettier for code quality
+- Modular architecture with barrel exports
+- Placeholder implementations for all modules
+- Comprehensive documentation and README
+
+### Development Infrastructure
+- tsup configuration for dual format builds
+- Jest configuration with ESM support
+- ESLint configuration with TypeScript rules
+- Prettier configuration for consistent formatting
+- Complete package.json with all required fields
+- TypeScript configuration with strict settings
+- .gitignore for development files
+
+### Package Structure
+- `src/types/` - TypeScript type definitions (placeholder)
+- `src/providers/` - AI provider implementations (placeholder)
+- `src/storage/` - Storage layer abstractions (placeholder)
+- `src/parser/` - Task parsing utilities (placeholder)
+- `src/utils/` - Common utility functions (placeholder)
+- `src/errors/` - Custom error classes (placeholder)
+- `tests/` - Test directories and setup
+
+## [1.0.0] - TBD
+
+### Planned Features
+- Complete TypeScript type system
+- AI provider implementations
+- Storage adapters
+- Task parsing capabilities
+- Comprehensive utility functions
+- Custom error handling
+- Full test coverage
+- Complete documentation
+
+---
+
+## Release Notes
+
+### Version 1.0.0 (Coming Soon)
+This will be the first stable release of tm-core with complete implementations of all modules. Currently, all modules contain placeholder implementations to establish the package structure and enable development of dependent packages.
+
+### Development Status
+- ✅ Package structure and configuration
+- ✅ Build and test infrastructure
+- ✅ Development tooling setup
+- 🚧 TypeScript types implementation (Task 116)
+- 🚧 AI provider system (Task 117)
+- 🚧 Storage layer (Task 118)
+- 🚧 Task parser (Task 119)
+- 🚧 Utility functions (Task 120)
+- 🚧 Error handling (Task 121)
+- 🚧 Configuration system (Task 122)
+- 🚧 Testing infrastructure (Task 123)
+- 🚧 Documentation (Task 124)
+- 🚧 Package finalization (Task 125)

packages/tm-core/POC-STATUS.md

@@ -0,0 +1,194 @@
+# GetTaskList POC Status
+
+## ✅ What We've Accomplished
+
+We've successfully implemented a complete end-to-end proof of concept for the `getTaskList` functionality with improved separation of concerns:
+
+### 1. Clean Architecture Layers with Proper Separation
+
+#### Configuration Layer (ConfigManager)
+- Single source of truth for configuration
+- Manages active tag and storage settings
+- Handles config.json persistence
+- Determines storage type (file vs API)
+
+#### Service Layer (TaskService)
+- Core business logic and operations
+- `getTaskList()` method that coordinates between ConfigManager and Storage
+- Handles all filtering and task processing
+- Manages storage lifecycle
+
+#### Facade Layer (TaskMasterCore)
+- Simplified API for consumers
+- Delegates to TaskService for operations
+- Backwards compatible `listTasks()` method
+- New `getTaskList()` method (preferred naming)
+
+#### Domain Layer (Entities)
+- `TaskEntity` with business logic
+- Validation and status transitions
+- Dependency checking (`canComplete()`)
+
+#### Infrastructure Layer (Storage)
+- `IStorage` interface for abstraction
+- `FileStorage` for local files (handles 'master' tag correctly)
+- `ApiStorage` for Hamster integration
+- `StorageFactory` for automatic selection
+- **NO business logic** - only persistence
+
+### 2. Storage Abstraction Benefits
+
+```typescript
+// Same API works with different backends
+const fileCore = createTaskMasterCore(path, { 
+  storage: { type: 'file' } 
+});
+
+const apiCore = createTaskMasterCore(path, { 
+  storage: { 
+    type: 'api',
+    apiEndpoint: 'https://hamster.ai',
+    apiAccessToken: 'xxx' 
+  } 
+});
+
+// Identical usage
+const result = await core.listTasks({ 
+  filter: { status: 'pending' } 
+});
+```
+
+### 3. Type Safety Throughout
+
+- Full TypeScript implementation
+- Comprehensive interfaces
+- Type-safe filters and options
+- Proper error types
+
+### 4. Testing Coverage
+
+- 50 tests passing
+- Unit tests for core components
+- Integration tests for listTasks
+- Mock implementations for testing
+
+## 📊 Architecture Validation
+
+### ✅ Separation of Concerns
+- **CLI** handles UI/formatting only
+- **tm-core** handles business logic
+- **Storage** handles persistence
+- Each layer is independently testable
+
+### ✅ Extensibility
+- Easy to add new storage types (database, S3, etc.)
+- New filters can be added to `TaskFilter`
+- AI providers follow same pattern (BaseProvider)
+
+### ✅ Error Handling
+- Consistent `TaskMasterError` with codes
+- Context preservation
+- User-friendly messages
+
+### ✅ Performance Considerations
+- File locking for concurrent access
+- Atomic writes with temp files
+- Retry logic with exponential backoff
+- Request timeout handling
+
+## 🔄 Integration Path
+
+### Current CLI Structure
+```javascript
+// scripts/modules/task-manager/list-tasks.js
+listTasks(tasksPath, statusFilter, reportPath, withSubtasks, outputFormat, context)
+// Directly reads files, handles all logic
+```
+
+### New Integration Structure
+```javascript
+// Using tm-core with proper separation of concerns
+const tmCore = createTaskMasterCore(projectPath, config);
+const result = await tmCore.getTaskList(options);
+// CLI only handles formatting result for display
+
+// Under the hood:
+// 1. ConfigManager determines active tag and storage type
+// 2. TaskService uses storage to fetch tasks for the tag
+// 3. TaskService applies business logic and filters
+// 4. Storage only handles reading/writing - no business logic
+```
+
+## 📈 Metrics
+
+### Code Quality
+- **Clean Code**: Methods under 40 lines ✅
+- **Single Responsibility**: Each class has one purpose ✅
+- **DRY**: No code duplication ✅
+- **Type Coverage**: 100% TypeScript ✅
+
+### Test Coverage
+- **Unit Tests**: BaseProvider, TaskEntity ✅
+- **Integration Tests**: Full listTasks flow ✅
+- **Storage Tests**: File and API operations ✅
+
+## 🎯 POC Success Criteria
+
+| Criteria | Status | Notes |
+|----------|--------|-------|
+| Clean architecture | ✅ | Clear layer separation |
+| Storage abstraction | ✅ | File + API storage working |
+| Type safety | ✅ | Full TypeScript |
+| Error handling | ✅ | Comprehensive error system |
+| Testing | ✅ | 50 tests passing |
+| Performance | ✅ | Optimized with caching, batching |
+| Documentation | ✅ | Architecture docs created |
+
+## 🚀 Next Steps
+
+### Immediate (Complete ListTasks Integration)
+1. Create npm script to test integration example
+2. Add mock Hamster API for testing
+3. Create migration guide for CLI
+
+### Phase 1 Remaining Work
+Based on this POC success, implement remaining operations:
+- `addTask()` - Add new tasks
+- `updateTask()` - Update existing tasks  
+- `deleteTask()` - Remove tasks
+- `expandTask()` - Break into subtasks
+- Tag management operations
+
+### Phase 2 (AI Integration)
+- Complete AI provider implementations
+- Task generation from PRD
+- Task complexity analysis
+- Auto-expansion of tasks
+
+## 💡 Lessons Learned
+
+### What Worked Well
+1. **Separation of Concerns** - ConfigManager, TaskService, and Storage have clear responsibilities
+2. **Storage Factory Pattern** - Clean abstraction for multiple backends
+3. **Entity Pattern** - Business logic encapsulation
+4. **Template Method Pattern** - BaseProvider for AI providers
+5. **Comprehensive Error Handling** - TaskMasterError with context
+
+### Improvements Made
+1. Migrated from Jest to Vitest (faster)
+2. Replaced ESLint/Prettier with Biome (unified tooling)
+3. Fixed conflicting interface definitions
+4. Added proper TypeScript exports
+5. **Better Architecture** - Separated configuration, business logic, and persistence
+6. **Proper Tag Handling** - 'master' tag maps correctly to tasks.json
+7. **Clean Storage Layer** - Removed business logic from storage
+
+## ✨ Conclusion
+
+The ListTasks POC successfully validates our architecture. The structure is:
+- **Clean and maintainable**
+- **Properly abstracted** 
+- **Well-tested**
+- **Ready for extension**
+
+We can confidently proceed with implementing the remaining functionality following this same pattern.

packages/tm-core/README.md

@@ -0,0 +1,226 @@
+# @task-master/tm-core
+
+Core library for Task Master AI - providing task management and orchestration capabilities with TypeScript support.
+
+## Overview
+
+`tm-core` is the foundational library that powers Task Master AI's task management system. It provides a comprehensive set of tools for creating, managing, and orchestrating tasks with AI integration.
+
+## Features
+
+- **TypeScript-first**: Built with full TypeScript support and strict type checking
+- **Dual Format**: Supports both ESM and CommonJS with automatic format detection
+- **Modular Architecture**: Clean separation of concerns with dedicated modules for different functionality
+- **AI Provider Integration**: Pluggable AI provider system for task generation and management
+- **Flexible Storage**: Abstracted storage layer supporting different persistence strategies
+- **Task Parsing**: Advanced parsing capabilities for various task definition formats
+- **Error Handling**: Comprehensive error system with specific error types
+- **Testing**: Complete test coverage with Jest and TypeScript support
+
+## Installation
+
+```bash
+npm install @task-master/tm-core
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { generateTaskId, PlaceholderTask } from '@task-master/tm-core';
+
+// Generate a unique task ID
+const taskId = generateTaskId();
+
+// Create a task (coming soon - full implementation)
+const task: PlaceholderTask = {
+  id: taskId,
+  title: 'My Task',
+  status: 'pending',
+  priority: 'medium'
+};
+```
+
+### Modular Imports
+
+You can import specific modules to reduce bundle size:
+
+```typescript
+// Import types only
+import type { TaskId, TaskStatus } from '@task-master/tm-core/types';
+
+// Import utilities
+import { generateTaskId, formatDate } from '@task-master/tm-core/utils';
+
+// Import providers (AI providers coming soon)
+// import { AIProvider } from '@task-master/tm-core/providers';
+
+// Import storage
+import { PlaceholderStorage } from '@task-master/tm-core/storage';
+
+// Import parsers
+import { PlaceholderParser } from '@task-master/tm-core/parser';
+
+// Import errors
+import { TmCoreError, TaskNotFoundError } from '@task-master/tm-core/errors';
+```
+
+## Architecture
+
+The library is organized into several key modules:
+
+- **types/**: TypeScript type definitions and interfaces
+- **providers/**: AI provider implementations for task generation
+- **storage/**: Storage adapters for different persistence strategies
+- **parser/**: Task parsing utilities for various formats
+- **utils/**: Common utility functions and helpers
+- **errors/**: Custom error classes and error handling
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- npm or yarn
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Build the library
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+### Scripts
+
+- `build`: Build the library for both ESM and CJS formats
+- `build:watch`: Build in watch mode for development
+- `test`: Run the test suite
+- `test:watch`: Run tests in watch mode
+- `test:coverage`: Run tests with coverage reporting
+- `lint`: Lint TypeScript files
+- `lint:fix`: Lint and auto-fix issues
+- `format`: Format code with Prettier
+- `format:check`: Check code formatting
+- `typecheck`: Type-check without emitting files
+- `clean`: Clean build artifacts
+- `dev`: Development mode with watch
+
+## ESM and CommonJS Support
+
+This package supports both ESM and CommonJS formats automatically:
+
+```javascript
+// ESM
+import { generateTaskId } from '@task-master/tm-core';
+
+// CommonJS
+const { generateTaskId } = require('@task-master/tm-core');
+```
+
+## Roadmap
+
+This is the initial package structure. The following features are planned for implementation:
+
+### Task 116: TypeScript Types
+- [ ] Complete type definitions for tasks, projects, and configurations
+- [ ] Zod schema validation
+- [ ] Generic type utilities
+
+### Task 117: AI Provider System
+- [ ] Base provider interface
+- [ ] Anthropic Claude integration
+- [ ] OpenAI integration
+- [ ] Perplexity integration
+- [ ] Provider factory and registry
+
+### Task 118: Storage Layer
+- [ ] File system storage adapter
+- [ ] Memory storage adapter
+- [ ] Storage interface and factory
+
+### Task 119: Task Parser
+- [ ] PRD parser implementation
+- [ ] Markdown parser
+- [ ] JSON task format parser
+- [ ] Validation utilities
+
+### Task 120: Utility Functions
+- [ ] Task ID generation
+- [ ] Date formatting
+- [ ] Validation helpers
+- [ ] File system utilities
+
+### Task 121: Error Handling
+- [ ] Task-specific errors
+- [ ] Storage errors
+- [ ] Provider errors
+- [ ] Validation errors
+
+### Task 122: Configuration System
+- [ ] Configuration schema
+- [ ] Default configurations
+- [ ] Environment variable support
+
+### Task 123: Testing Infrastructure
+- [ ] Unit test coverage
+- [ ] Integration tests
+- [ ] Mock utilities
+
+### Task 124: Documentation
+- [ ] API documentation
+- [ ] Usage examples
+- [ ] Migration guides
+
+### Task 125: Package Finalization
+- [ ] Final testing and validation
+- [ ] Release preparation
+- [ ] CI/CD integration
+
+## Implementation Checklist
+
+### ✅ Task 115: Initialize tm-core Package Structure (COMPLETED)
+- [x] Create tm-core directory structure and base configuration files
+- [x] Configure build and test infrastructure 
+- [x] Create barrel export files for all directories
+- [x] Add development tooling and documentation
+- [x] Validate package structure and prepare for development
+
+### 🚧 Remaining Implementation Tasks
+- [ ] **Task 116**: TypeScript Types - Complete type definitions for tasks, projects, and configurations
+- [ ] **Task 117**: AI Provider System - Base provider interface and integrations
+- [ ] **Task 118**: Storage Layer - File system and memory storage adapters
+- [ ] **Task 119**: Task Parser - PRD, Markdown, and JSON parsers
+- [ ] **Task 120**: Utility Functions - Task ID generation, validation helpers
+- [ ] **Task 121**: Error Handling - Task-specific and validation errors
+- [ ] **Task 122**: Configuration System - Schema and environment support
+- [ ] **Task 123**: Testing Infrastructure - Complete unit and integration tests
+- [ ] **Task 124**: Documentation - API docs and usage examples
+- [ ] **Task 125**: Package Finalization - Release preparation and CI/CD
+
+## Contributing
+
+This package is part of the Task Master AI project. Please refer to the main project's contributing guidelines.
+
+## License
+
+MIT - See the main project's LICENSE file for details.
+
+## Support
+
+For questions and support, please refer to the main Task Master AI documentation.

packages/tm-core/docs/listTasks-architecture.md

@@ -0,0 +1,161 @@
+# ListTasks Architecture - End-to-End POC
+
+## Current Implementation Structure
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         CLI Layer                            │
+│  scripts/modules/task-manager/list-tasks.js                 │
+│  - Complex UI rendering (tables, progress bars)             │
+│  - Multiple output formats (json, text, markdown, compact)  │
+│  - Status filtering and statistics                          │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              │ Currently reads directly
+                              │ from files (needs integration)
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      tm-core Package                         │
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │            TaskMasterCore (Facade)                   │   │
+│  │  src/task-master-core.ts                            │   │
+│  │                                                      │   │
+│  │  - listTasks(options)                               │   │
+│  │    • tag filtering                                  │   │
+│  │    • status filtering                               │   │
+│  │    • include/exclude subtasks                       │   │
+│  │  - getTask(id)                                      │   │
+│  │  - getTasksByStatus(status)                         │   │
+│  │  - getTaskStats()                                   │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                              │                               │
+│                              ▼                               │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │              Storage Layer (IStorage)                │   │
+│  │                                                      │   │
+│  │  ┌──────────────┐        ┌──────────────┐          │   │
+│  │  │ FileStorage  │        │ ApiStorage   │          │   │
+│  │  │              │        │ (Hamster)    │          │   │
+│  │  └──────────────┘        └──────────────┘          │   │
+│  │                                                      │   │
+│  │  StorageFactory.create() selects based on config    │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │            Domain Layer (Entities)                   │   │
+│  │                                                      │   │
+│  │  TaskEntity                                         │   │
+│  │  - Business logic                                   │   │
+│  │  - Validation                                       │   │
+│  │  - Status transitions                               │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## ListTasks Data Flow
+
+### 1. CLI Request
+```javascript
+// Current CLI (needs update to use tm-core)
+listTasks(tasksPath, statusFilter, reportPath, withSubtasks, outputFormat, context)
+```
+
+### 2. TaskMasterCore Processing
+```typescript
+// Our new implementation
+const tmCore = createTaskMasterCore(projectPath, { 
+  storage: { 
+    type: 'api',  // or 'file'
+    apiEndpoint: 'https://hamster.ai/api',
+    apiAccessToken: 'xxx'
+  }
+});
+
+const result = await tmCore.listTasks({
+  tag: 'feature-branch',
+  filter: {
+    status: ['pending', 'in-progress'],
+    priority: 'high',
+    search: 'authentication'
+  },
+  includeSubtasks: true
+});
+```
+
+### 3. Storage Selection
+```typescript
+// StorageFactory automatically selects storage
+const storage = StorageFactory.create(config, projectPath);
+// Returns either FileStorage or ApiStorage based on config
+```
+
+### 4. Data Loading
+```typescript
+// FileStorage
+- Reads from .taskmaster/tasks/tasks.json (or tag-specific file)
+- Local file system operations
+
+// ApiStorage (Hamster)
+- Makes HTTP requests to Hamster API
+- Uses access token from config
+- Handles retries and rate limiting
+```
+
+### 5. Entity Processing
+```typescript
+// Convert raw data to TaskEntity for business logic
+const taskEntities = TaskEntity.fromArray(rawTasks);
+
+// Apply filters
+const filtered = applyFilters(taskEntities, filter);
+
+// Convert back to plain objects
+const tasks = filtered.map(entity => entity.toJSON());
+```
+
+### 6. Response Structure
+```typescript
+interface ListTasksResult {
+  tasks: Task[];        // Filtered tasks
+  total: number;        // Total task count
+  filtered: number;     // Filtered task count  
+  tag?: string;         // Tag context if applicable
+}
+```
+
+## Integration Points Needed
+
+### 1. CLI Integration
+- [ ] Update `scripts/modules/task-manager/list-tasks.js` to use tm-core
+- [ ] Map CLI options to TaskMasterCore options
+- [ ] Handle output formatting in CLI layer
+
+### 2. Configuration Loading
+- [ ] Load `.taskmaster/config.json` for storage settings
+- [ ] Support environment variables for API tokens
+- [ ] Handle storage type selection
+
+### 3. Testing Requirements
+- [x] Unit tests for TaskEntity
+- [x] Unit tests for BaseProvider
+- [x] Integration tests for listTasks with FileStorage
+- [ ] Integration tests for listTasks with ApiStorage (mock API)
+- [ ] E2E tests with real Hamster API (optional)
+
+## Benefits of This Architecture
+
+1. **Storage Abstraction**: Switch between file and API storage without changing business logic
+2. **Clean Separation**: UI (CLI) separate from business logic (tm-core)
+3. **Testability**: Each layer can be tested independently
+4. **Extensibility**: Easy to add new storage types (database, cloud, etc.)
+5. **Type Safety**: Full TypeScript support throughout
+6. **Error Handling**: Consistent error handling with TaskMasterError
+
+## Next Steps
+
+1. Create a simple CLI wrapper that uses tm-core
+2. Test with file storage (existing functionality)
+3. Test with mock API storage
+4. Integrate with actual Hamster API when available
+5. Migrate other commands (addTask, updateTask, etc.) following same pattern

packages/tm-core/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@tm/core",
+	"version": "0.26.0",
+	"private": true,
+	"description": "Core library for Task Master - TypeScript task management system",
+	"type": "module",
+	"types": "./src/index.ts",
+	"main": "./dist/index.js",
+	"exports": {
+		".": "./src/index.ts",
+		"./auth": "./src/auth/index.ts",
+		"./storage": "./src/storage/index.ts",
+		"./config": "./src/config/index.ts",
+		"./providers": "./src/providers/index.ts",
+		"./services": "./src/services/index.ts",
+		"./errors": "./src/errors/index.ts",
+		"./logger": "./src/logger/index.ts",
+		"./types": "./src/types/index.ts",
+		"./interfaces": "./src/interfaces/index.ts",
+		"./utils": "./src/utils/index.ts"
+	},
+	"scripts": {
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:coverage": "vitest run --coverage",
+		"lint": "biome check --write",
+		"lint:check": "biome check",
+		"lint:fix": "biome check --fix --unsafe",
+		"format": "biome format --write",
+		"format:check": "biome format",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@supabase/supabase-js": "^2.57.4",
+		"zod": "^3.22.4"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.4",
+		"@tm/build-config": "*",
+		"@types/node": "^20.11.30",
+		"@vitest/coverage-v8": "^2.0.5",
+		"dotenv-mono": "^1.3.14",
+		"ts-node": "^10.9.2",
+		"tsup": "^8.5.0",
+		"typescript": "^5.4.3",
+		"vitest": "^2.0.5"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"files": ["src", "README.md", "CHANGELOG.md"],
+	"keywords": ["task-management", "typescript", "ai", "prd", "parser"],
+	"author": "Task Master AI",
+	"license": "MIT"
+}

packages/tm-core/src/auth/auth-manager.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Tests for AuthManager singleton behavior
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+// Mock the logger to verify warnings (must be hoisted before SUT import)
+const mockLogger = {
+	warn: vi.fn(),
+	info: vi.fn(),
+	debug: vi.fn(),
+	error: vi.fn()
+};
+
+vi.mock('../logger/index.js', () => ({
+	getLogger: () => mockLogger
+}));
+
+// Spy on CredentialStore constructor to verify config propagation
+const CredentialStoreSpy = vi.fn();
+vi.mock('./credential-store.js', () => {
+	return {
+		CredentialStore: class {
+			constructor(config: any) {
+				CredentialStoreSpy(config);
+				this.getCredentials = vi.fn(() => null);
+			}
+			getCredentials() {
+				return null;
+			}
+			saveCredentials() {}
+			clearCredentials() {}
+			hasValidCredentials() {
+				return false;
+			}
+		}
+	};
+});
+
+// Mock OAuthService to avoid side effects
+vi.mock('./oauth-service.js', () => {
+	return {
+		OAuthService: class {
+			constructor() {}
+			authenticate() {
+				return Promise.resolve({});
+			}
+			getAuthorizationUrl() {
+				return null;
+			}
+		}
+	};
+});
+
+// Mock SupabaseAuthClient to avoid side effects
+vi.mock('../clients/supabase-client.js', () => {
+	return {
+		SupabaseAuthClient: class {
+			constructor() {}
+			refreshSession() {
+				return Promise.resolve({});
+			}
+			signOut() {
+				return Promise.resolve();
+			}
+		}
+	};
+});
+
+// Import SUT after mocks
+import { AuthManager } from './auth-manager.js';
+
+describe('AuthManager Singleton', () => {
+	beforeEach(() => {
+		// Reset singleton before each test
+		AuthManager.resetInstance();
+		vi.clearAllMocks();
+		CredentialStoreSpy.mockClear();
+	});
+
+	it('should return the same instance on multiple calls', () => {
+		const instance1 = AuthManager.getInstance();
+		const instance2 = AuthManager.getInstance();
+
+		expect(instance1).toBe(instance2);
+	});
+
+	it('should use config on first call', () => {
+		const config = {
+			baseUrl: 'https://test.auth.com',
+			configDir: '/test/config',
+			configFile: '/test/config/auth.json'
+		};
+
+		const instance = AuthManager.getInstance(config);
+		expect(instance).toBeDefined();
+
+		// Assert that CredentialStore was constructed with the provided config
+		expect(CredentialStoreSpy).toHaveBeenCalledTimes(1);
+		expect(CredentialStoreSpy).toHaveBeenCalledWith(config);
+
+		// Verify the config is passed to internal components through observable behavior
+		// getCredentials would look in the configured file path
+		const credentials = instance.getCredentials();
+		expect(credentials).toBeNull(); // File doesn't exist, but config was propagated correctly
+	});
+
+	it('should warn when config is provided after initialization', () => {
+		// Clear previous calls
+		mockLogger.warn.mockClear();
+
+		// First call with config
+		AuthManager.getInstance({ baseUrl: 'https://first.auth.com' });
+
+		// Second call with different config
+		AuthManager.getInstance({ baseUrl: 'https://second.auth.com' });
+
+		// Verify warning was logged
+		expect(mockLogger.warn).toHaveBeenCalledWith(
+			expect.stringMatching(/config.*after initialization.*ignored/i)
+		);
+	});
+
+	it('should not warn when no config is provided after initialization', () => {
+		// Clear previous calls
+		mockLogger.warn.mockClear();
+
+		// First call with config
+		AuthManager.getInstance({ configDir: '/test/config' });
+
+		// Second call without config
+		AuthManager.getInstance();
+
+		// Verify no warning was logged
+		expect(mockLogger.warn).not.toHaveBeenCalled();
+	});
+
+	it('should allow resetting the instance', () => {
+		const instance1 = AuthManager.getInstance();
+
+		// Reset the instance
+		AuthManager.resetInstance();
+
+		// Get new instance
+		const instance2 = AuthManager.getInstance();
+
+		// They should be different instances
+		expect(instance1).not.toBe(instance2);
+	});
+});

packages/tm-core/src/auth/auth-manager.ts

@@ -0,0 +1,280 @@
+/**
+ * Authentication manager for Task Master CLI
+ */
+
+import {
+	AuthCredentials,
+	OAuthFlowOptions,
+	AuthenticationError,
+	AuthConfig,
+	UserContext
+} from './types.js';
+import { CredentialStore } from './credential-store.js';
+import { OAuthService } from './oauth-service.js';
+import { SupabaseAuthClient } from '../clients/supabase-client.js';
+import {
+	OrganizationService,
+	type Organization,
+	type Brief,
+	type RemoteTask
+} from '../services/organization.service.js';
+import { getLogger } from '../logger/index.js';
+
+/**
+ * Authentication manager class
+ */
+export class AuthManager {
+	private static instance: AuthManager | null = null;
+	private credentialStore: CredentialStore;
+	private oauthService: OAuthService;
+	private supabaseClient: SupabaseAuthClient;
+	private organizationService?: OrganizationService;
+
+	private constructor(config?: Partial<AuthConfig>) {
+		this.credentialStore = CredentialStore.getInstance(config);
+		this.supabaseClient = new SupabaseAuthClient();
+		this.oauthService = new OAuthService(this.credentialStore, config);
+
+		// Initialize Supabase client with session restoration
+		this.initializeSupabaseSession();
+	}
+
+	/**
+	 * Initialize Supabase session from stored credentials
+	 */
+	private async initializeSupabaseSession(): Promise<void> {
+		try {
+			await this.supabaseClient.initialize();
+		} catch (error) {
+			// Log but don't throw - session might not exist yet
+			const logger = getLogger('AuthManager');
+			logger.debug('No existing session to restore');
+		}
+	}
+
+	/**
+	 * Get singleton instance
+	 */
+	static getInstance(config?: Partial<AuthConfig>): AuthManager {
+		if (!AuthManager.instance) {
+			AuthManager.instance = new AuthManager(config);
+		} else if (config) {
+			// Warn if config is provided after initialization
+			const logger = getLogger('AuthManager');
+			logger.warn(
+				'getInstance called with config after initialization; config is ignored.'
+			);
+		}
+		return AuthManager.instance;
+	}
+
+	/**
+	 * Reset the singleton instance (useful for testing)
+	 */
+	static resetInstance(): void {
+		AuthManager.instance = null;
+		CredentialStore.resetInstance();
+	}
+
+	/**
+	 * Get stored authentication credentials
+	 */
+	getCredentials(): AuthCredentials | null {
+		return this.credentialStore.getCredentials();
+	}
+
+	/**
+	 * Start OAuth 2.0 Authorization Code Flow with browser handling
+	 */
+	async authenticateWithOAuth(
+		options: OAuthFlowOptions = {}
+	): Promise<AuthCredentials> {
+		return this.oauthService.authenticate(options);
+	}
+
+	/**
+	 * Get the authorization URL (for browser opening)
+	 */
+	getAuthorizationUrl(): string | null {
+		return this.oauthService.getAuthorizationUrl();
+	}
+
+	/**
+	 * Refresh authentication token using Supabase session
+	 */
+	async refreshToken(): Promise<AuthCredentials> {
+		try {
+			// Use Supabase's built-in session refresh
+			const session = await this.supabaseClient.refreshSession();
+
+			if (!session) {
+				throw new AuthenticationError(
+					'Failed to refresh session',
+					'REFRESH_FAILED'
+				);
+			}
+
+			// Get existing credentials to preserve context
+			const existingCredentials = this.credentialStore.getCredentials({
+				allowExpired: true
+			});
+
+			// Update authentication data from session
+			const newAuthData: AuthCredentials = {
+				token: session.access_token,
+				refreshToken: session.refresh_token,
+				userId: session.user.id,
+				email: session.user.email,
+				expiresAt: session.expires_at
+					? new Date(session.expires_at * 1000).toISOString()
+					: undefined,
+				savedAt: new Date().toISOString(),
+				selectedContext: existingCredentials?.selectedContext
+			};
+
+			this.credentialStore.saveCredentials(newAuthData);
+			return newAuthData;
+		} catch (error) {
+			if (error instanceof AuthenticationError) {
+				throw error;
+			}
+			throw new AuthenticationError(
+				`Token refresh failed: ${(error as Error).message}`,
+				'REFRESH_FAILED'
+			);
+		}
+	}
+
+	/**
+	 * Logout and clear credentials
+	 */
+	async logout(): Promise<void> {
+		try {
+			// First try to sign out from Supabase to revoke tokens
+			await this.supabaseClient.signOut();
+		} catch (error) {
+			// Log but don't throw - we still want to clear local credentials
+			getLogger('AuthManager').warn('Failed to sign out from Supabase:', error);
+		}
+
+		// Always clear local credentials (removes auth.json file)
+		this.credentialStore.clearCredentials();
+	}
+
+	/**
+	 * Check if authenticated
+	 */
+	isAuthenticated(): boolean {
+		return this.credentialStore.hasValidCredentials();
+	}
+
+	/**
+	 * Get the current user context (org/brief selection)
+	 */
+	getContext(): UserContext | null {
+		const credentials = this.getCredentials();
+		return credentials?.selectedContext || null;
+	}
+
+	/**
+	 * Update the user context (org/brief selection)
+	 */
+	async updateContext(context: Partial<UserContext>): Promise<void> {
+		const credentials = this.getCredentials();
+		if (!credentials) {
+			throw new AuthenticationError('Not authenticated', 'NOT_AUTHENTICATED');
+		}
+
+		// Merge with existing context
+		const existingContext = credentials.selectedContext || {};
+		const newContext: UserContext = {
+			...existingContext,
+			...context,
+			updatedAt: new Date().toISOString()
+		};
+
+		// Save updated credentials with new context
+		const updatedCredentials: AuthCredentials = {
+			...credentials,
+			selectedContext: newContext
+		};
+
+		this.credentialStore.saveCredentials(updatedCredentials);
+	}
+
+	/**
+	 * Clear the user context
+	 */
+	async clearContext(): Promise<void> {
+		const credentials = this.getCredentials();
+		if (!credentials) {
+			throw new AuthenticationError('Not authenticated', 'NOT_AUTHENTICATED');
+		}
+
+		// Remove context from credentials
+		const { selectedContext, ...credentialsWithoutContext } = credentials;
+		this.credentialStore.saveCredentials(credentialsWithoutContext);
+	}
+
+	/**
+	 * Get the organization service instance
+	 * Uses the Supabase client with the current session or token
+	 */
+	private async getOrganizationService(): Promise<OrganizationService> {
+		if (!this.organizationService) {
+			// First check if we have credentials with a token
+			const credentials = this.getCredentials();
+			if (!credentials || !credentials.token) {
+				throw new AuthenticationError('Not authenticated', 'NOT_AUTHENTICATED');
+			}
+
+			// Initialize session if needed (this will load from our storage adapter)
+			await this.supabaseClient.initialize();
+
+			// Use the SupabaseAuthClient which now has the session
+			const supabaseClient = this.supabaseClient.getClient();
+			this.organizationService = new OrganizationService(supabaseClient as any);
+		}
+		return this.organizationService;
+	}
+
+	/**
+	 * Get all organizations for the authenticated user
+	 */
+	async getOrganizations(): Promise<Organization[]> {
+		const service = await this.getOrganizationService();
+		return service.getOrganizations();
+	}
+
+	/**
+	 * Get all briefs for a specific organization
+	 */
+	async getBriefs(orgId: string): Promise<Brief[]> {
+		const service = await this.getOrganizationService();
+		return service.getBriefs(orgId);
+	}
+
+	/**
+	 * Get a specific organization by ID
+	 */
+	async getOrganization(orgId: string): Promise<Organization | null> {
+		const service = await this.getOrganizationService();
+		return service.getOrganization(orgId);
+	}
+
+	/**
+	 * Get a specific brief by ID
+	 */
+	async getBrief(briefId: string): Promise<Brief | null> {
+		const service = await this.getOrganizationService();
+		return service.getBrief(briefId);
+	}
+
+	/**
+	 * Get all tasks for a specific brief
+	 */
+	async getTasks(briefId: string): Promise<RemoteTask[]> {
+		const service = await this.getOrganizationService();
+		return service.getTasks(briefId);
+	}
+}

packages/tm-core/src/auth/config.ts

@@ -0,0 +1,37 @@
+/**
+ * Centralized authentication configuration
+ */
+
+import os from 'os';
+import path from 'path';
+import { AuthConfig } from './types.js';
+
+// Single base domain for all URLs
+// Build-time: process.env.TM_PUBLIC_BASE_DOMAIN gets replaced by tsup's env option
+// Default: https://tryhamster.com for production
+const BASE_DOMAIN =
+	process.env.TM_PUBLIC_BASE_DOMAIN || // This gets replaced at build time by tsup
+	'https://tryhamster.com';
+
+/**
+ * Default authentication configuration
+ * All URL configuration is derived from the single BASE_DOMAIN
+ */
+export const DEFAULT_AUTH_CONFIG: AuthConfig = {
+	// Base domain for all services
+	baseUrl: BASE_DOMAIN,
+
+	// Configuration directory and file paths
+	configDir: path.join(os.homedir(), '.taskmaster'),
+	configFile: path.join(os.homedir(), '.taskmaster', 'auth.json')
+};
+
+/**
+ * Get merged configuration with optional overrides
+ */
+export function getAuthConfig(overrides?: Partial<AuthConfig>): AuthConfig {
+	return {
+		...DEFAULT_AUTH_CONFIG,
+		...overrides
+	};
+}

packages/tm-core/src/auth/credential-store.test.ts

@@ -0,0 +1,575 @@
+/**
+ * Tests for CredentialStore with numeric and string timestamp handling
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { CredentialStore } from './credential-store.js';
+import { AuthenticationError } from './types.js';
+import type { AuthCredentials } from './types.js';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// Mock fs module
+vi.mock('fs');
+
+// Mock logger
+const mockLogger = {
+	warn: vi.fn(),
+	info: vi.fn(),
+	debug: vi.fn(),
+	error: vi.fn()
+};
+
+vi.mock('../logger/index.js', () => ({
+	getLogger: () => mockLogger
+}));
+
+describe('CredentialStore', () => {
+	let store: CredentialStore;
+	const testDir = '/test/config';
+	const configFile = '/test/config/auth.json';
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		store = new CredentialStore({
+			configDir: testDir,
+			configFile: configFile,
+			baseUrl: 'https://api.test.com'
+		});
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	describe('getCredentials with timestamp migration', () => {
+		it('should handle string ISO timestamp correctly', () => {
+			const futureDate = new Date(Date.now() + 3600000); // 1 hour from now
+			const mockCredentials: AuthCredentials = {
+				token: 'test-token',
+				userId: 'user-123',
+				email: 'test@example.com',
+				expiresAt: futureDate.toISOString(),
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue(
+				JSON.stringify(mockCredentials)
+			);
+
+			const result = store.getCredentials();
+
+			expect(result).not.toBeNull();
+			expect(result?.token).toBe('test-token');
+			// The timestamp should be normalized to numeric milliseconds
+			expect(typeof result?.expiresAt).toBe('number');
+			expect(result?.expiresAt).toBe(futureDate.getTime());
+		});
+
+		it('should handle numeric timestamp correctly', () => {
+			const futureTimestamp = Date.now() + 7200000; // 2 hours from now
+			const mockCredentials = {
+				token: 'test-token',
+				userId: 'user-456',
+				email: 'test2@example.com',
+				expiresAt: futureTimestamp,
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue(
+				JSON.stringify(mockCredentials)
+			);
+
+			const result = store.getCredentials();
+
+			expect(result).not.toBeNull();
+			expect(result?.token).toBe('test-token');
+			// Numeric timestamp should remain as-is
+			expect(typeof result?.expiresAt).toBe('number');
+			expect(result?.expiresAt).toBe(futureTimestamp);
+		});
+
+		it('should reject invalid string timestamp', () => {
+			const mockCredentials = {
+				token: 'test-token',
+				userId: 'user-789',
+				expiresAt: 'invalid-date-string',
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue(
+				JSON.stringify(mockCredentials)
+			);
+
+			const result = store.getCredentials();
+
+			expect(result).toBeNull();
+			expect(mockLogger.warn).toHaveBeenCalledWith(
+				'No valid expiration time provided for token'
+			);
+		});
+
+		it('should reject NaN timestamp', () => {
+			const mockCredentials = {
+				token: 'test-token',
+				userId: 'user-nan',
+				expiresAt: NaN,
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue(
+				JSON.stringify(mockCredentials)
+			);
+
+			const result = store.getCredentials();
+
+			expect(result).toBeNull();
+			expect(mockLogger.warn).toHaveBeenCalledWith(
+				'No valid expiration time provided for token'
+			);
+		});
+
+		it('should reject Infinity timestamp', () => {
+			const mockCredentials = {
+				token: 'test-token',
+				userId: 'user-inf',
+				expiresAt: Infinity,
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue(
+				JSON.stringify(mockCredentials)
+			);
+
+			const result = store.getCredentials();
+
+			expect(result).toBeNull();
+			expect(mockLogger.warn).toHaveBeenCalledWith(
+				'No valid expiration time provided for token'
+			);
+		});
+
+		it('should handle missing expiresAt field', () => {
+			const mockCredentials = {
+				token: 'test-token',
+				userId: 'user-no-expiry',
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+				// No expiresAt field
+			};
+
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue(
+				JSON.stringify(mockCredentials)
+			);
+
+			const result = store.getCredentials();
+
+			expect(result).toBeNull();
+			expect(mockLogger.warn).toHaveBeenCalledWith(
+				'No valid expiration time provided for token'
+			);
+		});
+
+		it('should check token expiration correctly', () => {
+			const expiredTimestamp = Date.now() - 3600000; // 1 hour ago
+			const mockCredentials = {
+				token: 'expired-token',
+				userId: 'user-expired',
+				expiresAt: expiredTimestamp,
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue(
+				JSON.stringify(mockCredentials)
+			);
+
+			const result = store.getCredentials();
+
+			expect(result).toBeNull();
+			expect(mockLogger.warn).toHaveBeenCalledWith(
+				expect.stringContaining('Authentication token has expired'),
+				expect.any(Object)
+			);
+		});
+
+		it('should allow expired tokens when requested', () => {
+			const expiredTimestamp = Date.now() - 3600000; // 1 hour ago
+			const mockCredentials = {
+				token: 'expired-token',
+				userId: 'user-expired',
+				expiresAt: expiredTimestamp,
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue(
+				JSON.stringify(mockCredentials)
+			);
+
+			const result = store.getCredentials({ allowExpired: true });
+
+			expect(result).not.toBeNull();
+			expect(result?.token).toBe('expired-token');
+		});
+	});
+
+	describe('saveCredentials with timestamp normalization', () => {
+		beforeEach(() => {
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.mkdirSync).mockImplementation(() => undefined);
+			vi.mocked(fs.writeFileSync).mockImplementation(() => undefined);
+			vi.mocked(fs.renameSync).mockImplementation(() => undefined);
+		});
+
+		it('should normalize string timestamp to ISO string when saving', () => {
+			const futureDate = new Date(Date.now() + 3600000);
+			const credentials: AuthCredentials = {
+				token: 'test-token',
+				userId: 'user-123',
+				expiresAt: futureDate.toISOString(),
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			store.saveCredentials(credentials);
+
+			expect(fs.writeFileSync).toHaveBeenCalledWith(
+				expect.stringContaining('.tmp'),
+				expect.stringContaining('"expiresAt":'),
+				expect.any(Object)
+			);
+
+			// Check that the written data contains a valid ISO string
+			const writtenData = vi.mocked(fs.writeFileSync).mock
+				.calls[0][1] as string;
+			const parsed = JSON.parse(writtenData);
+			expect(typeof parsed.expiresAt).toBe('string');
+			expect(new Date(parsed.expiresAt).toISOString()).toBe(parsed.expiresAt);
+		});
+
+		it('should convert numeric timestamp to ISO string when saving', () => {
+			const futureTimestamp = Date.now() + 7200000;
+			const credentials: AuthCredentials = {
+				token: 'test-token',
+				userId: 'user-456',
+				expiresAt: futureTimestamp,
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			store.saveCredentials(credentials);
+
+			const writtenData = vi.mocked(fs.writeFileSync).mock
+				.calls[0][1] as string;
+			const parsed = JSON.parse(writtenData);
+			expect(typeof parsed.expiresAt).toBe('string');
+			expect(new Date(parsed.expiresAt).getTime()).toBe(futureTimestamp);
+		});
+
+		it('should reject invalid string timestamp when saving', () => {
+			const credentials: AuthCredentials = {
+				token: 'test-token',
+				userId: 'user-789',
+				expiresAt: 'invalid-date' as any,
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			let err: unknown;
+			try {
+				store.saveCredentials(credentials);
+			} catch (e) {
+				err = e;
+			}
+			expect(err).toBeInstanceOf(AuthenticationError);
+			expect((err as Error).message).toContain('Invalid expiresAt format');
+		});
+
+		it('should reject NaN timestamp when saving', () => {
+			const credentials: AuthCredentials = {
+				token: 'test-token',
+				userId: 'user-nan',
+				expiresAt: NaN as any,
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			let err: unknown;
+			try {
+				store.saveCredentials(credentials);
+			} catch (e) {
+				err = e;
+			}
+			expect(err).toBeInstanceOf(AuthenticationError);
+			expect((err as Error).message).toContain('Invalid expiresAt format');
+		});
+
+		it('should reject Infinity timestamp when saving', () => {
+			const credentials: AuthCredentials = {
+				token: 'test-token',
+				userId: 'user-inf',
+				expiresAt: Infinity as any,
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			let err: unknown;
+			try {
+				store.saveCredentials(credentials);
+			} catch (e) {
+				err = e;
+			}
+			expect(err).toBeInstanceOf(AuthenticationError);
+			expect((err as Error).message).toContain('Invalid expiresAt format');
+		});
+
+		it('should handle missing expiresAt when saving', () => {
+			const credentials: AuthCredentials = {
+				token: 'test-token',
+				userId: 'user-no-expiry',
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+				// No expiresAt
+			};
+
+			store.saveCredentials(credentials);
+
+			const writtenData = vi.mocked(fs.writeFileSync).mock
+				.calls[0][1] as string;
+			const parsed = JSON.parse(writtenData);
+			expect(parsed.expiresAt).toBeUndefined();
+		});
+
+		it('should not mutate the original credentials object', () => {
+			const originalTimestamp = Date.now() + 3600000;
+			const credentials: AuthCredentials = {
+				token: 'test-token',
+				userId: 'user-123',
+				expiresAt: originalTimestamp,
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			const originalCredentialsCopy = { ...credentials };
+
+			store.saveCredentials(credentials);
+
+			// Original object should not be modified
+			expect(credentials).toEqual(originalCredentialsCopy);
+			expect(credentials.expiresAt).toBe(originalTimestamp);
+		});
+	});
+
+	describe('corrupt file handling', () => {
+		it('should quarantine corrupt file on JSON parse error', () => {
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue('invalid json {');
+			vi.mocked(fs.renameSync).mockImplementation(() => undefined);
+
+			const result = store.getCredentials();
+
+			expect(result).toBeNull();
+			expect(fs.renameSync).toHaveBeenCalledWith(
+				configFile,
+				expect.stringContaining('.corrupt-')
+			);
+			expect(mockLogger.warn).toHaveBeenCalledWith(
+				expect.stringContaining('Quarantined corrupt auth file')
+			);
+		});
+
+		it('should handle quarantine failure gracefully', () => {
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue('invalid json {');
+			vi.mocked(fs.renameSync).mockImplementation(() => {
+				throw new Error('Permission denied');
+			});
+
+			const result = store.getCredentials();
+
+			expect(result).toBeNull();
+			expect(mockLogger.debug).toHaveBeenCalledWith(
+				expect.stringContaining('Could not quarantine corrupt file')
+			);
+		});
+	});
+
+	describe('clearCredentials', () => {
+		it('should delete the auth file when it exists', () => {
+			// Mock file exists
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.unlinkSync).mockImplementation(() => undefined);
+
+			store.clearCredentials();
+
+			expect(fs.existsSync).toHaveBeenCalledWith('/test/config/auth.json');
+			expect(fs.unlinkSync).toHaveBeenCalledWith('/test/config/auth.json');
+		});
+
+		it('should not throw when auth file does not exist', () => {
+			// Mock file does not exist
+			vi.mocked(fs.existsSync).mockReturnValue(false);
+
+			// Should not throw
+			expect(() => store.clearCredentials()).not.toThrow();
+
+			// Should not try to unlink non-existent file
+			expect(fs.unlinkSync).not.toHaveBeenCalled();
+		});
+
+		it('should throw AuthenticationError when unlink fails', () => {
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.unlinkSync).mockImplementation(() => {
+				throw new Error('Permission denied');
+			});
+
+			let err: unknown;
+			try {
+				store.clearCredentials();
+			} catch (e) {
+				err = e;
+			}
+
+			expect(err).toBeInstanceOf(AuthenticationError);
+			expect((err as Error).message).toContain('Failed to clear credentials');
+			expect((err as Error).message).toContain('Permission denied');
+		});
+	});
+
+	describe('hasValidCredentials', () => {
+		it('should return true when valid unexpired credentials exist', () => {
+			const futureDate = new Date(Date.now() + 3600000); // 1 hour from now
+			const credentials = {
+				token: 'valid-token',
+				userId: 'user-123',
+				expiresAt: futureDate.toISOString(),
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(credentials));
+
+			expect(store.hasValidCredentials()).toBe(true);
+		});
+
+		it('should return false when credentials are expired', () => {
+			const pastDate = new Date(Date.now() - 3600000); // 1 hour ago
+			const credentials = {
+				token: 'expired-token',
+				userId: 'user-123',
+				expiresAt: pastDate.toISOString(),
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(credentials));
+
+			expect(store.hasValidCredentials()).toBe(false);
+		});
+
+		it('should return false when no credentials exist', () => {
+			vi.mocked(fs.existsSync).mockReturnValue(false);
+
+			expect(store.hasValidCredentials()).toBe(false);
+		});
+
+		it('should return false when file contains invalid JSON', () => {
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue('invalid json {');
+			vi.mocked(fs.renameSync).mockImplementation(() => undefined);
+
+			expect(store.hasValidCredentials()).toBe(false);
+		});
+
+		it('should return false for credentials without expiry', () => {
+			const credentials = {
+				token: 'no-expiry-token',
+				userId: 'user-123',
+				tokenType: 'standard',
+				savedAt: new Date().toISOString()
+			};
+
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(credentials));
+
+			// Credentials without expiry are considered invalid
+			expect(store.hasValidCredentials()).toBe(false);
+
+			// Should log warning about missing expiration
+			expect(mockLogger.warn).toHaveBeenCalledWith(
+				'No valid expiration time provided for token'
+			);
+		});
+
+		it('should use allowExpired=false by default', () => {
+			// Spy on getCredentials to verify it's called with correct params
+			const getCredentialsSpy = vi.spyOn(store, 'getCredentials');
+
+			vi.mocked(fs.existsSync).mockReturnValue(false);
+			store.hasValidCredentials();
+
+			expect(getCredentialsSpy).toHaveBeenCalledWith({ allowExpired: false });
+		});
+	});
+
+	describe('cleanupCorruptFiles', () => {
+		it('should remove old corrupt files', () => {
+			const now = Date.now();
+			const oldFile = 'auth.json.corrupt-' + (now - 8 * 24 * 60 * 60 * 1000); // 8 days old
+			const newFile = 'auth.json.corrupt-' + (now - 1000); // 1 second old
+
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readdirSync).mockReturnValue([
+				{ name: oldFile, isFile: () => true },
+				{ name: newFile, isFile: () => true },
+				{ name: 'auth.json', isFile: () => true }
+			] as any);
+			vi.mocked(fs.statSync).mockImplementation((filePath) => {
+				if (filePath.includes(oldFile)) {
+					return { mtimeMs: now - 8 * 24 * 60 * 60 * 1000 } as any;
+				}
+				return { mtimeMs: now - 1000 } as any;
+			});
+			vi.mocked(fs.unlinkSync).mockImplementation(() => undefined);
+
+			store.cleanupCorruptFiles();
+
+			expect(fs.unlinkSync).toHaveBeenCalledWith(
+				expect.stringContaining(oldFile)
+			);
+			expect(fs.unlinkSync).not.toHaveBeenCalledWith(
+				expect.stringContaining(newFile)
+			);
+		});
+
+		it('should handle cleanup errors gracefully', () => {
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+			vi.mocked(fs.readdirSync).mockImplementation(() => {
+				throw new Error('Permission denied');
+			});
+
+			// Should not throw
+			expect(() => store.cleanupCorruptFiles()).not.toThrow();
+			expect(mockLogger.debug).toHaveBeenCalledWith(
+				expect.stringContaining('Error during corrupt file cleanup')
+			);
+		});
+	});
+});

packages/tm-core/src/auth/credential-store.ts

@@ -0,0 +1,265 @@
+/**
+ * Credential storage and management
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { AuthCredentials, AuthenticationError, AuthConfig } from './types.js';
+import { getAuthConfig } from './config.js';
+import { getLogger } from '../logger/index.js';
+
+/**
+ * CredentialStore manages the persistence and retrieval of authentication credentials.
+ *
+ * Runtime vs Persisted Shape:
+ * - When retrieved (getCredentials): expiresAt is normalized to number (milliseconds since epoch)
+ * - When persisted (saveCredentials): expiresAt is stored as ISO string for readability
+ *
+ * This normalization ensures consistent runtime behavior while maintaining
+ * human-readable persisted format in the auth.json file.
+ */
+export class CredentialStore {
+	private static instance: CredentialStore | null = null;
+	private logger = getLogger('CredentialStore');
+	private config: AuthConfig;
+	// Clock skew tolerance for expiry checks (30 seconds)
+	private readonly CLOCK_SKEW_MS = 30_000;
+
+	private constructor(config?: Partial<AuthConfig>) {
+		this.config = getAuthConfig(config);
+	}
+
+	/**
+	 * Get the singleton instance of CredentialStore
+	 */
+	static getInstance(config?: Partial<AuthConfig>): CredentialStore {
+		if (!CredentialStore.instance) {
+			CredentialStore.instance = new CredentialStore(config);
+		} else if (config) {
+			// Warn if config is provided after initialization
+			const logger = getLogger('CredentialStore');
+			logger.warn(
+				'getInstance called with config after initialization; config is ignored.'
+			);
+		}
+		return CredentialStore.instance;
+	}
+
+	/**
+	 * Reset the singleton instance (useful for testing)
+	 */
+	static resetInstance(): void {
+		CredentialStore.instance = null;
+	}
+
+	/**
+	 * Get stored authentication credentials
+	 * @returns AuthCredentials with expiresAt as number (milliseconds) for runtime use
+	 */
+	getCredentials(options?: { allowExpired?: boolean }): AuthCredentials | null {
+		try {
+			if (!fs.existsSync(this.config.configFile)) {
+				return null;
+			}
+
+			const authData = JSON.parse(
+				fs.readFileSync(this.config.configFile, 'utf-8')
+			) as AuthCredentials;
+
+			// Normalize/migrate timestamps to numeric (handles both number and ISO string)
+			let expiresAtMs: number | undefined;
+			if (typeof authData.expiresAt === 'number') {
+				expiresAtMs = Number.isFinite(authData.expiresAt)
+					? authData.expiresAt
+					: undefined;
+			} else if (typeof authData.expiresAt === 'string') {
+				const parsed = Date.parse(authData.expiresAt);
+				expiresAtMs = Number.isNaN(parsed) ? undefined : parsed;
+			} else {
+				expiresAtMs = undefined;
+			}
+
+			// Validate expiration time for tokens
+			if (expiresAtMs === undefined) {
+				this.logger.warn('No valid expiration time provided for token');
+				return null;
+			}
+
+			// Update the authData with normalized timestamp
+			authData.expiresAt = expiresAtMs;
+
+			// Check if the token has expired (with clock skew tolerance)
+			const now = Date.now();
+			const allowExpired = options?.allowExpired ?? false;
+			if (now >= expiresAtMs - this.CLOCK_SKEW_MS && !allowExpired) {
+				this.logger.warn(
+					'Authentication token has expired or is about to expire',
+					{
+						expiresAt: authData.expiresAt,
+						currentTime: new Date(now).toISOString(),
+						skewWindow: `${this.CLOCK_SKEW_MS / 1000}s`
+					}
+				);
+				return null;
+			}
+
+			// Return valid token
+			return authData;
+		} catch (error) {
+			this.logger.error(
+				`Failed to read auth credentials: ${(error as Error).message}`
+			);
+
+			// Quarantine corrupt file to prevent repeated errors
+			try {
+				if (fs.existsSync(this.config.configFile)) {
+					const corruptFile = `${this.config.configFile}.corrupt-${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+					fs.renameSync(this.config.configFile, corruptFile);
+					this.logger.warn(`Quarantined corrupt auth file to: ${corruptFile}`);
+				}
+			} catch (quarantineError) {
+				// If we can't quarantine, log but don't throw
+				this.logger.debug(
+					`Could not quarantine corrupt file: ${(quarantineError as Error).message}`
+				);
+			}
+
+			return null;
+		}
+	}
+
+	/**
+	 * Save authentication credentials
+	 * @param authData - Credentials with expiresAt as number or string (will be persisted as ISO string)
+	 */
+	saveCredentials(authData: AuthCredentials): void {
+		try {
+			// Ensure directory exists
+			if (!fs.existsSync(this.config.configDir)) {
+				fs.mkdirSync(this.config.configDir, { recursive: true, mode: 0o700 });
+			}
+
+			// Add timestamp without mutating caller's object
+			authData = { ...authData, savedAt: new Date().toISOString() };
+
+			// Validate and normalize expiresAt timestamp
+			if (authData.expiresAt !== undefined) {
+				let validTimestamp: number | undefined;
+
+				if (typeof authData.expiresAt === 'number') {
+					validTimestamp = Number.isFinite(authData.expiresAt)
+						? authData.expiresAt
+						: undefined;
+				} else if (typeof authData.expiresAt === 'string') {
+					const parsed = Date.parse(authData.expiresAt);
+					validTimestamp = Number.isNaN(parsed) ? undefined : parsed;
+				}
+
+				if (validTimestamp === undefined) {
+					throw new AuthenticationError(
+						`Invalid expiresAt format: ${authData.expiresAt}`,
+						'SAVE_FAILED'
+					);
+				}
+
+				// Store as ISO string for consistency
+				authData.expiresAt = new Date(validTimestamp).toISOString();
+			}
+
+			// Save credentials atomically with secure permissions
+			const tempFile = `${this.config.configFile}.tmp`;
+			fs.writeFileSync(tempFile, JSON.stringify(authData, null, 2), {
+				mode: 0o600
+			});
+			fs.renameSync(tempFile, this.config.configFile);
+		} catch (error) {
+			throw new AuthenticationError(
+				`Failed to save auth credentials: ${(error as Error).message}`,
+				'SAVE_FAILED',
+				error
+			);
+		}
+	}
+
+	/**
+	 * Clear stored credentials
+	 */
+	clearCredentials(): void {
+		try {
+			if (fs.existsSync(this.config.configFile)) {
+				fs.unlinkSync(this.config.configFile);
+			}
+		} catch (error) {
+			throw new AuthenticationError(
+				`Failed to clear credentials: ${(error as Error).message}`,
+				'CLEAR_FAILED',
+				error
+			);
+		}
+	}
+
+	/**
+	 * Check if credentials exist and are valid
+	 */
+	hasValidCredentials(): boolean {
+		const credentials = this.getCredentials({ allowExpired: false });
+		return credentials !== null;
+	}
+
+	/**
+	 * Get configuration
+	 */
+	getConfig(): AuthConfig {
+		return { ...this.config };
+	}
+
+	/**
+	 * Clean up old corrupt auth files
+	 * Removes corrupt files older than the specified age
+	 */
+	cleanupCorruptFiles(maxAgeMs: number = 7 * 24 * 60 * 60 * 1000): void {
+		try {
+			const dir = path.dirname(this.config.configFile);
+			const baseName = path.basename(this.config.configFile);
+			const prefix = `${baseName}.corrupt-`;
+
+			if (!fs.existsSync(dir)) {
+				return;
+			}
+
+			const entries = fs.readdirSync(dir, { withFileTypes: true });
+			const now = Date.now();
+
+			for (const entry of entries) {
+				if (!entry.isFile()) continue;
+				const file = entry.name;
+
+				// Check if file matches pattern: baseName.corrupt-{timestamp}
+				if (!file.startsWith(prefix)) continue;
+				const suffix = file.slice(prefix.length);
+				if (!/^\d+$/.test(suffix)) continue; // Fixed regex, not from variable input
+
+				const filePath = path.join(dir, file);
+				try {
+					const stats = fs.statSync(filePath);
+					const age = now - stats.mtimeMs;
+
+					if (age > maxAgeMs) {
+						fs.unlinkSync(filePath);
+						this.logger.debug(`Cleaned up old corrupt file: ${file}`);
+					}
+				} catch (error) {
+					// Ignore errors for individual file cleanup
+					this.logger.debug(
+						`Could not clean up corrupt file ${file}: ${(error as Error).message}`
+					);
+				}
+			}
+		} catch (error) {
+			// Log but don't throw - this is a cleanup operation
+			this.logger.debug(
+				`Error during corrupt file cleanup: ${(error as Error).message}`
+			);
+		}
+	}
+}

packages/tm-core/src/auth/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Authentication module exports
+ */
+
+export { AuthManager } from './auth-manager.js';
+export { CredentialStore } from './credential-store.js';
+export { OAuthService } from './oauth-service.js';
+export { SupabaseSessionStorage } from './supabase-session-storage.js';
+export type {
+	Organization,
+	Brief,
+	RemoteTask
+} from '../services/organization.service.js';
+
+export type {
+	AuthCredentials,
+	OAuthFlowOptions,
+	AuthConfig,
+	CliData,
+	UserContext
+} from './types.js';
+
+export { AuthenticationError } from './types.js';
+
+export {
+	DEFAULT_AUTH_CONFIG,
+	getAuthConfig
+} from './config.js';

packages/tm-core/src/auth/oauth-service.ts

@@ -0,0 +1,403 @@
+/**
+ * OAuth 2.0 Authorization Code Flow service
+ */
+
+import http from 'http';
+import { URL } from 'url';
+import crypto from 'crypto';
+import os from 'os';
+import {
+	AuthCredentials,
+	AuthenticationError,
+	OAuthFlowOptions,
+	AuthConfig,
+	CliData
+} from './types.js';
+import { CredentialStore } from './credential-store.js';
+import { SupabaseAuthClient } from '../clients/supabase-client.js';
+import { getAuthConfig } from './config.js';
+import { getLogger } from '../logger/index.js';
+import packageJson from '../../../../package.json' with { type: 'json' };
+
+export class OAuthService {
+	private logger = getLogger('OAuthService');
+	private credentialStore: CredentialStore;
+	private supabaseClient: SupabaseAuthClient;
+	private baseUrl: string;
+	private authorizationUrl: string | null = null;
+	private originalState: string | null = null;
+	private authorizationReady: Promise<void> | null = null;
+	private resolveAuthorizationReady: (() => void) | null = null;
+
+	constructor(
+		credentialStore: CredentialStore,
+		config: Partial<AuthConfig> = {}
+	) {
+		this.credentialStore = credentialStore;
+		this.supabaseClient = new SupabaseAuthClient();
+		const authConfig = getAuthConfig(config);
+		this.baseUrl = authConfig.baseUrl;
+	}
+
+	/**
+	 * Start OAuth 2.0 Authorization Code Flow with browser handling
+	 */
+	async authenticate(options: OAuthFlowOptions = {}): Promise<AuthCredentials> {
+		const {
+			openBrowser,
+			timeout = 300000, // 5 minutes default
+			onAuthUrl,
+			onWaitingForAuth,
+			onSuccess,
+			onError
+		} = options;
+
+		try {
+			// Start the OAuth flow (starts local server)
+			const authPromise = this.startFlow(timeout);
+
+			// Wait for server to be ready and URL to be generated
+			if (this.authorizationReady) {
+				await this.authorizationReady;
+			}
+
+			// Get the authorization URL
+			const authUrl = this.getAuthorizationUrl();
+
+			if (!authUrl) {
+				throw new AuthenticationError(
+					'Failed to generate authorization URL',
+					'URL_GENERATION_FAILED'
+				);
+			}
+
+			// Notify about the auth URL
+			if (onAuthUrl) {
+				onAuthUrl(authUrl);
+			}
+
+			// Open browser if callback provided
+			if (openBrowser) {
+				try {
+					await openBrowser(authUrl);
+					this.logger.debug('Browser opened successfully with URL:', authUrl);
+				} catch (error) {
+					// Log the error but don't throw - user can still manually open the URL
+					this.logger.warn('Failed to open browser automatically:', error);
+				}
+			}
+
+			// Notify that we're waiting for authentication
+			if (onWaitingForAuth) {
+				onWaitingForAuth();
+			}
+
+			// Wait for authentication to complete
+			const credentials = await authPromise;
+
+			// Notify success
+			if (onSuccess) {
+				onSuccess(credentials);
+			}
+
+			return credentials;
+		} catch (error) {
+			const authError =
+				error instanceof AuthenticationError
+					? error
+					: new AuthenticationError(
+							`OAuth authentication failed: ${(error as Error).message}`,
+							'OAUTH_FAILED',
+							error
+						);
+
+			// Notify error
+			if (onError) {
+				onError(authError);
+			}
+
+			throw authError;
+		}
+	}
+
+	/**
+	 * Start the OAuth flow (internal implementation)
+	 */
+	private async startFlow(timeout: number = 300000): Promise<AuthCredentials> {
+		const state = this.generateState();
+
+		// Store the original state for verification
+		this.originalState = state;
+
+		// Create a promise that will resolve when the server is ready
+		this.authorizationReady = new Promise<void>((resolve) => {
+			this.resolveAuthorizationReady = resolve;
+		});
+
+		return new Promise((resolve, reject) => {
+			let timeoutId: NodeJS.Timeout;
+			// Create local HTTP server for OAuth callback
+			const server = http.createServer();
+
+			// Start server on localhost only, bind to port 0 for automatic port assignment
+			server.listen(0, '127.0.0.1', () => {
+				const address = server.address();
+				if (!address || typeof address === 'string') {
+					reject(new Error('Failed to get server address'));
+					return;
+				}
+				const port = address.port;
+				const callbackUrl = `http://localhost:${port}/callback`;
+
+				// Set up request handler after we know the port
+				server.on('request', async (req, res) => {
+					const url = new URL(req.url!, `http://127.0.0.1:${port}`);
+
+					if (url.pathname === '/callback') {
+						await this.handleCallback(
+							url,
+							res,
+							server,
+							resolve,
+							reject,
+							timeoutId
+						);
+					} else {
+						// Handle other paths (favicon, etc.)
+						res.writeHead(404);
+						res.end();
+					}
+				});
+
+				// Prepare CLI data object (server handles OAuth/PKCE)
+				const cliData: CliData = {
+					callback: callbackUrl,
+					state: state,
+					name: 'Task Master CLI',
+					version: this.getCliVersion(),
+					device: os.hostname(),
+					user: os.userInfo().username,
+					platform: os.platform(),
+					timestamp: Date.now()
+				};
+
+				// Build authorization URL for CLI-specific sign-in page
+				const authUrl = new URL(`${this.baseUrl}/auth/cli/sign-in`);
+
+				// Encode CLI data as base64
+				const cliParam = Buffer.from(JSON.stringify(cliData)).toString(
+					'base64'
+				);
+
+				// Set the single CLI parameter with all encoded data
+				authUrl.searchParams.append('cli', cliParam);
+
+				// Store auth URL for browser opening
+				this.authorizationUrl = authUrl.toString();
+
+				this.logger.info(
+					`OAuth session started - ${cliData.name} v${cliData.version} on port ${port}`
+				);
+				this.logger.debug('CLI data:', cliData);
+
+				// Signal that the server is ready and URL is available
+				if (this.resolveAuthorizationReady) {
+					this.resolveAuthorizationReady();
+					this.resolveAuthorizationReady = null;
+				}
+			});
+
+			// Set timeout for authentication
+			timeoutId = setTimeout(() => {
+				if (server.listening) {
+					server.close();
+					// Clean up the readiness promise if still pending
+					if (this.resolveAuthorizationReady) {
+						this.resolveAuthorizationReady();
+						this.resolveAuthorizationReady = null;
+					}
+					reject(
+						new AuthenticationError('Authentication timeout', 'AUTH_TIMEOUT')
+					);
+				}
+			}, timeout);
+		});
+	}
+
+	/**
+	 * Handle OAuth callback
+	 */
+	private async handleCallback(
+		url: URL,
+		res: http.ServerResponse,
+		server: http.Server,
+		resolve: (value: AuthCredentials) => void,
+		reject: (error: any) => void,
+		timeoutId?: NodeJS.Timeout
+	): Promise<void> {
+		// Server now returns tokens directly instead of code
+		const type = url.searchParams.get('type');
+		const returnedState = url.searchParams.get('state');
+		const accessToken = url.searchParams.get('access_token');
+		const refreshToken = url.searchParams.get('refresh_token');
+		const expiresIn = url.searchParams.get('expires_in');
+		const error = url.searchParams.get('error');
+		const errorDescription = url.searchParams.get('error_description');
+
+		// Server handles displaying success/failure, just close connection
+		res.writeHead(200);
+		res.end();
+
+		if (error) {
+			if (server.listening) {
+				server.close();
+			}
+			reject(
+				new AuthenticationError(
+					errorDescription || error || 'Authentication failed',
+					'OAUTH_ERROR'
+				)
+			);
+			return;
+		}
+
+		// Verify state parameter for CSRF protection
+		if (returnedState !== this.originalState) {
+			if (server.listening) {
+				server.close();
+			}
+			reject(
+				new AuthenticationError('Invalid state parameter', 'INVALID_STATE')
+			);
+			return;
+		}
+
+		// Handle authorization code for PKCE flow
+		const code = url.searchParams.get('code');
+		if (code && type === 'pkce_callback') {
+			try {
+				this.logger.info('Received authorization code for PKCE flow');
+
+				// Exchange code for session using PKCE
+				const session = await this.supabaseClient.exchangeCodeForSession(code);
+
+				// Save authentication data
+				const authData: AuthCredentials = {
+					token: session.access_token,
+					refreshToken: session.refresh_token,
+					userId: session.user.id,
+					email: session.user.email,
+					expiresAt: session.expires_at
+						? new Date(session.expires_at * 1000).toISOString()
+						: undefined,
+					tokenType: 'standard',
+					savedAt: new Date().toISOString()
+				};
+
+				this.credentialStore.saveCredentials(authData);
+
+				if (server.listening) {
+					server.close();
+				}
+				// Clear timeout since authentication succeeded
+				if (timeoutId) {
+					clearTimeout(timeoutId);
+				}
+				resolve(authData);
+				return;
+			} catch (error) {
+				if (server.listening) {
+					server.close();
+				}
+				reject(error);
+				return;
+			}
+		}
+
+		// Handle direct token response from server (legacy flow)
+		if (
+			accessToken &&
+			(type === 'oauth_success' || type === 'session_transfer')
+		) {
+			try {
+				this.logger.info(`Received tokens via ${type}`);
+
+				// Create a session with the tokens and set it in Supabase client
+				const session = {
+					access_token: accessToken,
+					refresh_token: refreshToken || '',
+					expires_at: expiresIn
+						? Math.floor(Date.now() / 1000) + parseInt(expiresIn)
+						: undefined,
+					expires_in: expiresIn ? parseInt(expiresIn) : undefined,
+					token_type: 'bearer',
+					user: null as any // Will be populated by setSession
+				};
+
+				// Set the session in Supabase client
+				await this.supabaseClient.setSession(session as any);
+
+				// Get user info from the session
+				const user = await this.supabaseClient.getUser();
+
+				// Calculate expiration time
+				const expiresAt = expiresIn
+					? new Date(Date.now() + parseInt(expiresIn) * 1000).toISOString()
+					: undefined;
+
+				// Save authentication data
+				const authData: AuthCredentials = {
+					token: accessToken,
+					refreshToken: refreshToken || undefined,
+					userId: user?.id || 'unknown',
+					email: user?.email,
+					expiresAt: expiresAt,
+					tokenType: 'standard',
+					savedAt: new Date().toISOString()
+				};
+
+				this.credentialStore.saveCredentials(authData);
+
+				if (server.listening) {
+					server.close();
+				}
+				// Clear timeout since authentication succeeded
+				if (timeoutId) {
+					clearTimeout(timeoutId);
+				}
+				resolve(authData);
+			} catch (error) {
+				if (server.listening) {
+					server.close();
+				}
+				reject(error);
+			}
+		} else {
+			if (server.listening) {
+				server.close();
+			}
+			reject(new AuthenticationError('No access token received', 'NO_TOKEN'));
+		}
+	}
+
+	/**
+	 * Generate state for OAuth flow
+	 */
+	private generateState(): string {
+		return crypto.randomBytes(32).toString('base64url');
+	}
+
+	/**
+	 * Get CLI version from package.json if available
+	 */
+	private getCliVersion(): string {
+		return packageJson.version || 'unknown';
+	}
+
+	/**
+	 * Get the authorization URL (for browser opening)
+	 */
+	getAuthorizationUrl(): string | null {
+		return this.authorizationUrl;
+	}
+}

packages/tm-core/src/auth/supabase-session-storage.ts

@@ -0,0 +1,155 @@
+/**
+ * Custom storage adapter for Supabase Auth sessions in CLI environment
+ * Implements the SupportedStorage interface required by Supabase Auth
+ *
+ * This adapter bridges Supabase's session management with our existing
+ * auth.json credential storage, maintaining backward compatibility
+ */
+
+import { SupportedStorage } from '@supabase/supabase-js';
+import { CredentialStore } from './credential-store.js';
+import { AuthCredentials } from './types.js';
+import { getLogger } from '../logger/index.js';
+
+const STORAGE_KEY = 'sb-taskmaster-auth-token';
+
+export class SupabaseSessionStorage implements SupportedStorage {
+	private store: CredentialStore;
+	private logger = getLogger('SupabaseSessionStorage');
+
+	constructor(store: CredentialStore) {
+		this.store = store;
+	}
+
+	/**
+	 * Build a Supabase session object from our credentials
+	 */
+	private buildSessionFromCredentials(credentials: AuthCredentials): any {
+		// Create a session object that Supabase expects
+		const session = {
+			access_token: credentials.token,
+			refresh_token: credentials.refreshToken || '',
+			expires_at: credentials.expiresAt
+				? Math.floor(new Date(credentials.expiresAt).getTime() / 1000)
+				: Math.floor(Date.now() / 1000) + 3600, // Default to 1 hour
+			token_type: 'bearer',
+			user: {
+				id: credentials.userId,
+				email: credentials.email || '',
+				aud: 'authenticated',
+				role: 'authenticated',
+				email_confirmed_at: new Date().toISOString(),
+				app_metadata: {},
+				user_metadata: {},
+				created_at: new Date().toISOString(),
+				updated_at: new Date().toISOString()
+			}
+		};
+		return session;
+	}
+
+	/**
+	 * Parse a Supabase session back to our credentials
+	 */
+	private parseSessionToCredentials(
+		sessionData: any
+	): Partial<AuthCredentials> {
+		try {
+			const session = JSON.parse(sessionData);
+			return {
+				token: session.access_token,
+				refreshToken: session.refresh_token,
+				userId: session.user?.id || 'unknown',
+				email: session.user?.email,
+				expiresAt: session.expires_at
+					? new Date(session.expires_at * 1000).toISOString()
+					: undefined
+			};
+		} catch (error) {
+			this.logger.error('Error parsing session:', error);
+			return {};
+		}
+	}
+
+	/**
+	 * Get item from storage - Supabase will request the session with a specific key
+	 */
+	getItem(key: string): string | null {
+		// Supabase uses a specific key pattern for sessions
+		if (key === STORAGE_KEY || key.includes('auth-token')) {
+			try {
+				const credentials = this.store.getCredentials({ allowExpired: true });
+				if (credentials && credentials.token) {
+					// Build and return a session object from our stored credentials
+					const session = this.buildSessionFromCredentials(credentials);
+					return JSON.stringify(session);
+				}
+			} catch (error) {
+				this.logger.error('Error getting session:', error);
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Set item in storage - Supabase will store the session with a specific key
+	 */
+	setItem(key: string, value: string): void {
+		// Only handle Supabase session keys
+		if (key === STORAGE_KEY || key.includes('auth-token')) {
+			try {
+				// Parse the session and update our credentials
+				const sessionUpdates = this.parseSessionToCredentials(value);
+				const existingCredentials = this.store.getCredentials({
+					allowExpired: true
+				});
+
+				if (sessionUpdates.token) {
+					const updatedCredentials: AuthCredentials = {
+						...existingCredentials,
+						...sessionUpdates,
+						savedAt: new Date().toISOString(),
+						selectedContext: existingCredentials?.selectedContext
+					} as AuthCredentials;
+
+					this.store.saveCredentials(updatedCredentials);
+				}
+			} catch (error) {
+				this.logger.error('Error setting session:', error);
+			}
+		}
+	}
+
+	/**
+	 * Remove item from storage - Called when signing out
+	 */
+	removeItem(key: string): void {
+		if (key === STORAGE_KEY || key.includes('auth-token')) {
+			// Don't actually remove credentials, just clear the tokens
+			// This preserves other data like selectedContext
+			try {
+				const credentials = this.store.getCredentials({ allowExpired: true });
+				if (credentials) {
+					// Keep context but clear auth tokens
+					const clearedCredentials: AuthCredentials = {
+						...credentials,
+						token: '',
+						refreshToken: undefined,
+						expiresAt: undefined
+					} as AuthCredentials;
+					this.store.saveCredentials(clearedCredentials);
+				}
+			} catch (error) {
+				this.logger.error('Error removing session:', error);
+			}
+		}
+	}
+
+	/**
+	 * Clear all session data
+	 */
+	clear(): void {
+		// Clear auth tokens but preserve context
+		this.removeItem(STORAGE_KEY);
+	}
+}

packages/tm-core/src/auth/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Authentication types and interfaces
+ */
+
+export interface AuthCredentials {
+	token: string;
+	refreshToken?: string;
+	userId: string;
+	email?: string;
+	expiresAt?: string | number;
+	tokenType?: 'standard';
+	savedAt: string;
+	selectedContext?: UserContext;
+}
+
+export interface UserContext {
+	orgId?: string;
+	orgName?: string;
+	briefId?: string;
+	briefName?: string;
+	updatedAt: string;
+}
+
+export interface OAuthFlowOptions {
+	/** Callback to open the browser with the auth URL. If not provided, browser won't be opened */
+	openBrowser?: (url: string) => Promise<void>;
+	/** Timeout for the OAuth flow in milliseconds. Default: 300000 (5 minutes) */
+	timeout?: number;
+	/** Callback to be invoked with the authorization URL */
+	onAuthUrl?: (url: string) => void;
+	/** Callback to be invoked when waiting for authentication */
+	onWaitingForAuth?: () => void;
+	/** Callback to be invoked on successful authentication */
+	onSuccess?: (credentials: AuthCredentials) => void;
+	/** Callback to be invoked on authentication error */
+	onError?: (error: AuthenticationError) => void;
+}
+
+export interface AuthConfig {
+	baseUrl: string;
+	configDir: string;
+	configFile: string;
+}
+
+export interface CliData {
+	callback: string;
+	state: string;
+	name: string;
+	version: string;
+	device?: string;
+	user?: string;
+	platform?: string;
+	timestamp?: number;
+}
+
+/**
+ * Authentication error codes
+ */
+export type AuthErrorCode =
+	| 'AUTH_TIMEOUT'
+	| 'AUTH_EXPIRED'
+	| 'OAUTH_FAILED'
+	| 'OAUTH_ERROR'
+	| 'OAUTH_CANCELED'
+	| 'URL_GENERATION_FAILED'
+	| 'INVALID_STATE'
+	| 'NO_TOKEN'
+	| 'TOKEN_EXCHANGE_FAILED'
+	| 'INVALID_CREDENTIALS'
+	| 'NO_REFRESH_TOKEN'
+	| 'NOT_AUTHENTICATED'
+	| 'NETWORK_ERROR'
+	| 'CONFIG_MISSING'
+	| 'SAVE_FAILED'
+	| 'CLEAR_FAILED'
+	| 'STORAGE_ERROR'
+	| 'NOT_SUPPORTED'
+	| 'REFRESH_FAILED'
+	| 'INVALID_RESPONSE'
+	| 'PKCE_INIT_FAILED'
+	| 'PKCE_FAILED'
+	| 'CODE_EXCHANGE_FAILED'
+	| 'SESSION_SET_FAILED';
+
+/**
+ * Authentication error class
+ */
+export class AuthenticationError extends Error {
+	constructor(
+		message: string,
+		public code: AuthErrorCode,
+		public cause?: unknown
+	) {
+		super(message);
+		this.name = 'AuthenticationError';
+		if (cause && cause instanceof Error) {
+			this.stack = `${this.stack}\nCaused by: ${cause.stack}`;
+		}
+	}
+}

packages/tm-core/src/clients/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Client exports
+ */
+
+export { SupabaseAuthClient } from './supabase-client.js';

packages/tm-core/src/clients/supabase-client.ts

@@ -0,0 +1,312 @@
+/**
+ * Supabase authentication client for CLI auth flows
+ */
+
+import {
+	createClient,
+	SupabaseClient as SupabaseJSClient,
+	User,
+	Session
+} from '@supabase/supabase-js';
+import { AuthenticationError } from '../auth/types.js';
+import { getLogger } from '../logger/index.js';
+import { SupabaseSessionStorage } from '../auth/supabase-session-storage.js';
+import { CredentialStore } from '../auth/credential-store.js';
+
+export class SupabaseAuthClient {
+	private client: SupabaseJSClient | null = null;
+	private sessionStorage: SupabaseSessionStorage;
+	private logger = getLogger('SupabaseAuthClient');
+
+	constructor() {
+		const credentialStore = CredentialStore.getInstance();
+		this.sessionStorage = new SupabaseSessionStorage(credentialStore);
+	}
+
+	/**
+	 * Get Supabase client with proper session management
+	 */
+	getClient(): SupabaseJSClient {
+		if (!this.client) {
+			// Get Supabase configuration from environment - using TM_PUBLIC prefix
+			const supabaseUrl = process.env.TM_PUBLIC_SUPABASE_URL;
+			const supabaseAnonKey = process.env.TM_PUBLIC_SUPABASE_ANON_KEY;
+
+			if (!supabaseUrl || !supabaseAnonKey) {
+				throw new AuthenticationError(
+					'Supabase configuration missing. Please set TM_PUBLIC_SUPABASE_URL and TM_PUBLIC_SUPABASE_ANON_KEY environment variables.',
+					'CONFIG_MISSING'
+				);
+			}
+
+			// Create client with custom storage adapter (similar to React Native AsyncStorage)
+			this.client = createClient(supabaseUrl, supabaseAnonKey, {
+				auth: {
+					storage: this.sessionStorage,
+					autoRefreshToken: true,
+					persistSession: true,
+					detectSessionInUrl: false
+				}
+			});
+		}
+
+		return this.client;
+	}
+
+	/**
+	 * Initialize the client and restore session if available
+	 */
+	async initialize(): Promise<Session | null> {
+		const client = this.getClient();
+
+		try {
+			// Get the current session from storage
+			const {
+				data: { session },
+				error
+			} = await client.auth.getSession();
+
+			if (error) {
+				this.logger.warn('Failed to restore session:', error);
+				return null;
+			}
+
+			if (session) {
+				this.logger.info('Session restored successfully');
+			}
+
+			return session;
+		} catch (error) {
+			this.logger.error('Error initializing session:', error);
+			return null;
+		}
+	}
+
+	/**
+	 * Sign in with PKCE flow (for CLI auth)
+	 */
+	async signInWithPKCE(): Promise<{ url: string; codeVerifier: string }> {
+		const client = this.getClient();
+
+		try {
+			// Generate PKCE challenge
+			const { data, error } = await client.auth.signInWithOAuth({
+				provider: 'github',
+				options: {
+					redirectTo:
+						process.env.TM_AUTH_CALLBACK_URL ||
+						'http://localhost:3421/auth/callback',
+					scopes: 'email'
+				}
+			});
+
+			if (error) {
+				throw new AuthenticationError(
+					`Failed to initiate PKCE flow: ${error.message}`,
+					'PKCE_INIT_FAILED'
+				);
+			}
+
+			if (!data?.url) {
+				throw new AuthenticationError(
+					'No authorization URL returned',
+					'INVALID_RESPONSE'
+				);
+			}
+
+			// Extract code_verifier from the URL or generate it
+			// Note: Supabase handles PKCE internally, we just need to handle the callback
+			return {
+				url: data.url,
+				codeVerifier: '' // Supabase manages this internally
+			};
+		} catch (error) {
+			if (error instanceof AuthenticationError) {
+				throw error;
+			}
+
+			throw new AuthenticationError(
+				`Failed to start PKCE flow: ${(error as Error).message}`,
+				'PKCE_FAILED'
+			);
+		}
+	}
+
+	/**
+	 * Exchange authorization code for session (PKCE flow)
+	 */
+	async exchangeCodeForSession(code: string): Promise<Session> {
+		const client = this.getClient();
+
+		try {
+			const { data, error } = await client.auth.exchangeCodeForSession(code);
+
+			if (error) {
+				throw new AuthenticationError(
+					`Failed to exchange code: ${error.message}`,
+					'CODE_EXCHANGE_FAILED'
+				);
+			}
+
+			if (!data?.session) {
+				throw new AuthenticationError(
+					'No session returned from code exchange',
+					'INVALID_RESPONSE'
+				);
+			}
+
+			this.logger.info('Successfully exchanged code for session');
+			return data.session;
+		} catch (error) {
+			if (error instanceof AuthenticationError) {
+				throw error;
+			}
+
+			throw new AuthenticationError(
+				`Code exchange failed: ${(error as Error).message}`,
+				'CODE_EXCHANGE_FAILED'
+			);
+		}
+	}
+
+	/**
+	 * Get the current session
+	 */
+	async getSession(): Promise<Session | null> {
+		const client = this.getClient();
+
+		try {
+			const {
+				data: { session },
+				error
+			} = await client.auth.getSession();
+
+			if (error) {
+				this.logger.warn('Failed to get session:', error);
+				return null;
+			}
+
+			return session;
+		} catch (error) {
+			this.logger.error('Error getting session:', error);
+			return null;
+		}
+	}
+
+	/**
+	 * Refresh the current session
+	 */
+	async refreshSession(): Promise<Session | null> {
+		const client = this.getClient();
+
+		try {
+			this.logger.info('Refreshing session...');
+
+			// Supabase will automatically use the stored refresh token
+			const {
+				data: { session },
+				error
+			} = await client.auth.refreshSession();
+
+			if (error) {
+				this.logger.error('Failed to refresh session:', error);
+				throw new AuthenticationError(
+					`Failed to refresh session: ${error.message}`,
+					'REFRESH_FAILED'
+				);
+			}
+
+			if (session) {
+				this.logger.info('Successfully refreshed session');
+			}
+
+			return session;
+		} catch (error) {
+			if (error instanceof AuthenticationError) {
+				throw error;
+			}
+
+			throw new AuthenticationError(
+				`Failed to refresh session: ${(error as Error).message}`,
+				'REFRESH_FAILED'
+			);
+		}
+	}
+
+	/**
+	 * Get current user from session
+	 */
+	async getUser(): Promise<User | null> {
+		const client = this.getClient();
+
+		try {
+			const {
+				data: { user },
+				error
+			} = await client.auth.getUser();
+
+			if (error) {
+				this.logger.warn('Failed to get user:', error);
+				return null;
+			}
+
+			return user;
+		} catch (error) {
+			this.logger.error('Error getting user:', error);
+			return null;
+		}
+	}
+
+	/**
+	 * Sign out and clear session
+	 */
+	async signOut(): Promise<void> {
+		const client = this.getClient();
+
+		try {
+			// Sign out with global scope to revoke all refresh tokens
+			const { error } = await client.auth.signOut({ scope: 'global' });
+
+			if (error) {
+				this.logger.warn('Failed to sign out:', error);
+			}
+
+			// Clear cached session data
+			this.sessionStorage.clear();
+		} catch (error) {
+			this.logger.error('Error during sign out:', error);
+		}
+	}
+
+	/**
+	 * Set session from external auth (e.g., from server callback)
+	 */
+	async setSession(session: Session): Promise<void> {
+		const client = this.getClient();
+
+		try {
+			const { error } = await client.auth.setSession({
+				access_token: session.access_token,
+				refresh_token: session.refresh_token
+			});
+
+			if (error) {
+				throw new AuthenticationError(
+					`Failed to set session: ${error.message}`,
+					'SESSION_SET_FAILED'
+				);
+			}
+
+			this.logger.info('Session set successfully');
+		} catch (error) {
+			if (error instanceof AuthenticationError) {
+				throw error;
+			}
+
+			throw new AuthenticationError(
+				`Failed to set session: ${(error as Error).message}`,
+				'SESSION_SET_FAILED'
+			);
+		}
+	}
+}

packages/tm-core/src/config/config-manager.spec.ts

@@ -0,0 +1,394 @@
+/**
+ * @fileoverview Integration tests for ConfigManager
+ * Tests the orchestration of all configuration services
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { ConfigManager } from './config-manager.js';
+import { ConfigLoader } from './services/config-loader.service.js';
+import { ConfigMerger } from './services/config-merger.service.js';
+import { RuntimeStateManager } from './services/runtime-state-manager.service.js';
+import { ConfigPersistence } from './services/config-persistence.service.js';
+import { EnvironmentConfigProvider } from './services/environment-config-provider.service.js';
+
+// Mock all services
+vi.mock('./services/config-loader.service.js');
+vi.mock('./services/config-merger.service.js');
+vi.mock('./services/runtime-state-manager.service.js');
+vi.mock('./services/config-persistence.service.js');
+vi.mock('./services/environment-config-provider.service.js');
+
+describe('ConfigManager', () => {
+	let manager: ConfigManager;
+	const testProjectRoot = '/test/project';
+	const originalEnv = { ...process.env };
+
+	beforeEach(async () => {
+		vi.clearAllMocks();
+
+		// Clear environment variables
+		Object.keys(process.env).forEach((key) => {
+			if (key.startsWith('TASKMASTER_')) {
+				delete process.env[key];
+			}
+		});
+
+		// Setup default mock behaviors
+		vi.mocked(ConfigLoader).mockImplementation(
+			() =>
+				({
+					getDefaultConfig: vi.fn().mockReturnValue({
+						models: { main: 'default-model', fallback: 'fallback-model' },
+						storage: { type: 'file' },
+						version: '1.0.0'
+					}),
+					loadLocalConfig: vi.fn().mockResolvedValue(null),
+					loadGlobalConfig: vi.fn().mockResolvedValue(null),
+					hasLocalConfig: vi.fn().mockResolvedValue(false),
+					hasGlobalConfig: vi.fn().mockResolvedValue(false)
+				}) as any
+		);
+
+		vi.mocked(ConfigMerger).mockImplementation(
+			() =>
+				({
+					addSource: vi.fn(),
+					clearSources: vi.fn(),
+					merge: vi.fn().mockReturnValue({
+						models: { main: 'merged-model', fallback: 'fallback-model' },
+						storage: { type: 'file' }
+					}),
+					getSources: vi.fn().mockReturnValue([]),
+					hasSource: vi.fn().mockReturnValue(false),
+					removeSource: vi.fn().mockReturnValue(false)
+				}) as any
+		);
+
+		vi.mocked(RuntimeStateManager).mockImplementation(
+			() =>
+				({
+					loadState: vi.fn().mockResolvedValue({ activeTag: 'master' }),
+					saveState: vi.fn().mockResolvedValue(undefined),
+					getActiveTag: vi.fn().mockReturnValue('master'),
+					setActiveTag: vi.fn().mockResolvedValue(undefined),
+					getState: vi.fn().mockReturnValue({ activeTag: 'master' }),
+					updateMetadata: vi.fn().mockResolvedValue(undefined),
+					clearState: vi.fn().mockResolvedValue(undefined)
+				}) as any
+		);
+
+		vi.mocked(ConfigPersistence).mockImplementation(
+			() =>
+				({
+					saveConfig: vi.fn().mockResolvedValue(undefined),
+					configExists: vi.fn().mockResolvedValue(false),
+					deleteConfig: vi.fn().mockResolvedValue(undefined),
+					getBackups: vi.fn().mockResolvedValue([]),
+					restoreFromBackup: vi.fn().mockResolvedValue(undefined)
+				}) as any
+		);
+
+		vi.mocked(EnvironmentConfigProvider).mockImplementation(
+			() =>
+				({
+					loadConfig: vi.fn().mockReturnValue({}),
+					getRuntimeState: vi.fn().mockReturnValue({}),
+					hasEnvVar: vi.fn().mockReturnValue(false),
+					getAllTaskmasterEnvVars: vi.fn().mockReturnValue({}),
+					addMapping: vi.fn(),
+					getMappings: vi.fn().mockReturnValue([])
+				}) as any
+		);
+
+		// Since constructor is private, we need to use the factory method
+		// But for testing, we'll create a test instance using create()
+		manager = await ConfigManager.create(testProjectRoot);
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+		process.env = { ...originalEnv };
+	});
+
+	describe('creation', () => {
+		it('should initialize all services when created', () => {
+			// Services should have been initialized during beforeEach
+			expect(ConfigLoader).toHaveBeenCalledWith(testProjectRoot);
+			expect(ConfigMerger).toHaveBeenCalled();
+			expect(RuntimeStateManager).toHaveBeenCalledWith(testProjectRoot);
+			expect(ConfigPersistence).toHaveBeenCalledWith(testProjectRoot);
+			expect(EnvironmentConfigProvider).toHaveBeenCalled();
+		});
+	});
+
+	describe('create (factory method)', () => {
+		it('should create and initialize manager', async () => {
+			const createdManager = await ConfigManager.create(testProjectRoot);
+
+			expect(createdManager).toBeInstanceOf(ConfigManager);
+			expect(createdManager.getConfig()).toBeDefined();
+		});
+	});
+
+	describe('initialization (via create)', () => {
+		it('should load and merge all configuration sources', () => {
+			// Manager was created in beforeEach, so initialization already happened
+			const loader = (manager as any).loader;
+			const merger = (manager as any).merger;
+			const stateManager = (manager as any).stateManager;
+			const envProvider = (manager as any).envProvider;
+
+			// Verify loading sequence
+			expect(merger.clearSources).toHaveBeenCalled();
+			expect(loader.getDefaultConfig).toHaveBeenCalled();
+			expect(loader.loadGlobalConfig).toHaveBeenCalled();
+			expect(loader.loadLocalConfig).toHaveBeenCalled();
+			expect(envProvider.loadConfig).toHaveBeenCalled();
+			expect(merger.merge).toHaveBeenCalled();
+			expect(stateManager.loadState).toHaveBeenCalled();
+		});
+
+		it('should add sources with correct precedence during creation', () => {
+			const merger = (manager as any).merger;
+
+			// Check that sources were added with correct precedence
+			expect(merger.addSource).toHaveBeenCalledWith(
+				expect.objectContaining({
+					name: 'defaults',
+					precedence: 0
+				})
+			);
+
+			// Note: local and env sources may not be added if they don't exist
+			// The mock setup determines what gets called
+		});
+	});
+
+	describe('configuration access', () => {
+		// Manager is already initialized in the main beforeEach
+
+		it('should return merged configuration', () => {
+			const config = manager.getConfig();
+			expect(config).toEqual({
+				models: { main: 'merged-model', fallback: 'fallback-model' },
+				storage: { type: 'file' }
+			});
+		});
+
+		it('should return storage configuration', () => {
+			const storage = manager.getStorageConfig();
+			expect(storage).toEqual({ type: 'file' });
+		});
+
+		it('should return API storage configuration when configured', async () => {
+			// Create a new instance with API storage config
+			vi.mocked(ConfigMerger).mockImplementationOnce(
+				() =>
+					({
+						addSource: vi.fn(),
+						clearSources: vi.fn(),
+						merge: vi.fn().mockReturnValue({
+							storage: {
+								type: 'api',
+								apiEndpoint: 'https://api.example.com',
+								apiAccessToken: 'token123'
+							}
+						}),
+						getSources: vi.fn().mockReturnValue([]),
+						hasSource: vi.fn().mockReturnValue(false),
+						removeSource: vi.fn().mockReturnValue(false)
+					}) as any
+			);
+
+			const apiManager = await ConfigManager.create(testProjectRoot);
+
+			const storage = apiManager.getStorageConfig();
+			expect(storage).toEqual({
+				type: 'api',
+				apiEndpoint: 'https://api.example.com',
+				apiAccessToken: 'token123'
+			});
+		});
+
+		it('should return model configuration', () => {
+			const models = manager.getModelConfig();
+			expect(models).toEqual({
+				main: 'merged-model',
+				fallback: 'fallback-model'
+			});
+		});
+
+		it('should return default models when not configured', () => {
+			// Update the mock for current instance
+			const merger = (manager as any).merger;
+			merger.merge.mockReturnValue({});
+			// Force re-merge
+			(manager as any).config = merger.merge();
+
+			const models = manager.getModelConfig();
+			expect(models).toEqual({
+				main: 'claude-3-5-sonnet-20241022',
+				fallback: 'gpt-4o-mini'
+			});
+		});
+
+		it('should return response language', () => {
+			const language = manager.getResponseLanguage();
+			expect(language).toBe('English');
+		});
+
+		it('should return custom response language', () => {
+			// Update config for current instance
+			(manager as any).config = {
+				custom: { responseLanguage: 'Spanish' }
+			};
+
+			const language = manager.getResponseLanguage();
+			expect(language).toBe('Spanish');
+		});
+
+		it('should return project root', () => {
+			expect(manager.getProjectRoot()).toBe(testProjectRoot);
+		});
+
+		it('should check if API is explicitly configured', () => {
+			expect(manager.isApiExplicitlyConfigured()).toBe(false);
+		});
+
+		it('should detect when API is explicitly configured', () => {
+			// Update config for current instance
+			(manager as any).config = {
+				storage: {
+					type: 'api',
+					apiEndpoint: 'https://api.example.com',
+					apiAccessToken: 'token'
+				}
+			};
+
+			expect(manager.isApiExplicitlyConfigured()).toBe(true);
+		});
+	});
+
+	describe('runtime state', () => {
+		// Manager is already initialized in the main beforeEach
+
+		it('should get active tag from state manager', () => {
+			const tag = manager.getActiveTag();
+			expect(tag).toBe('master');
+		});
+
+		it('should set active tag through state manager', async () => {
+			await manager.setActiveTag('feature-branch');
+
+			const stateManager = (manager as any).stateManager;
+			expect(stateManager.setActiveTag).toHaveBeenCalledWith('feature-branch');
+		});
+	});
+
+	describe('configuration updates', () => {
+		// Manager is already initialized in the main beforeEach
+
+		it('should update configuration and save', async () => {
+			const updates = {
+				models: { main: 'new-model', fallback: 'fallback-model' }
+			};
+			await manager.updateConfig(updates);
+
+			const persistence = (manager as any).persistence;
+			expect(persistence.saveConfig).toHaveBeenCalled();
+		});
+
+		it('should re-initialize after update to maintain precedence', async () => {
+			const merger = (manager as any).merger;
+			merger.clearSources.mockClear();
+
+			await manager.updateConfig({ custom: { test: 'value' } });
+
+			expect(merger.clearSources).toHaveBeenCalled();
+		});
+
+		it('should set response language', async () => {
+			await manager.setResponseLanguage('French');
+
+			const persistence = (manager as any).persistence;
+			expect(persistence.saveConfig).toHaveBeenCalledWith(
+				expect.objectContaining({
+					custom: { responseLanguage: 'French' }
+				})
+			);
+		});
+
+		it('should save configuration with options', async () => {
+			await manager.saveConfig();
+
+			const persistence = (manager as any).persistence;
+			expect(persistence.saveConfig).toHaveBeenCalledWith(expect.any(Object), {
+				createBackup: true,
+				atomic: true
+			});
+		});
+	});
+
+	describe('utilities', () => {
+		// Manager is already initialized in the main beforeEach
+
+		it('should reset configuration to defaults', async () => {
+			await manager.reset();
+
+			const persistence = (manager as any).persistence;
+			const stateManager = (manager as any).stateManager;
+
+			expect(persistence.deleteConfig).toHaveBeenCalled();
+			expect(stateManager.clearState).toHaveBeenCalled();
+		});
+
+		it('should re-initialize after reset', async () => {
+			const merger = (manager as any).merger;
+			merger.clearSources.mockClear();
+
+			await manager.reset();
+
+			expect(merger.clearSources).toHaveBeenCalled();
+		});
+
+		it('should get configuration sources for debugging', () => {
+			const merger = (manager as any).merger;
+			const mockSources = [{ name: 'test', config: {}, precedence: 1 }];
+			merger.getSources.mockReturnValue(mockSources);
+
+			const sources = manager.getConfigSources();
+
+			expect(sources).toEqual(mockSources);
+		});
+
+		it('should return no-op function for watch (not implemented)', () => {
+			const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+			const callback = vi.fn();
+
+			const unsubscribe = manager.watch(callback);
+
+			expect(warnSpy).toHaveBeenCalledWith(
+				'Configuration watching not yet implemented'
+			);
+			expect(unsubscribe).toBeInstanceOf(Function);
+
+			// Calling unsubscribe should not throw
+			expect(() => unsubscribe()).not.toThrow();
+
+			warnSpy.mockRestore();
+		});
+	});
+
+	describe('error handling', () => {
+		it('should handle missing services gracefully', async () => {
+			// Even if a service fails, manager should still work
+			const loader = (manager as any).loader;
+			loader.loadLocalConfig.mockRejectedValue(new Error('File error'));
+
+			// Creating a new manager should not throw even if service fails
+			await expect(
+				ConfigManager.create(testProjectRoot)
+			).resolves.not.toThrow();
+		});
+	});
+});

packages/tm-core/src/config/config-manager.ts

@@ -0,0 +1,279 @@
+/**
+ * @fileoverview Configuration Manager
+ * Orchestrates configuration services following clean architecture principles
+ *
+ * This ConfigManager delegates responsibilities to specialized services for better
+ * maintainability, testability, and separation of concerns.
+ */
+
+import type {
+	PartialConfiguration,
+	RuntimeStorageConfig
+} from '../interfaces/configuration.interface.js';
+import { ConfigLoader } from './services/config-loader.service.js';
+import {
+	ConfigMerger,
+	CONFIG_PRECEDENCE
+} from './services/config-merger.service.js';
+import { RuntimeStateManager } from './services/runtime-state-manager.service.js';
+import { ConfigPersistence } from './services/config-persistence.service.js';
+import { EnvironmentConfigProvider } from './services/environment-config-provider.service.js';
+
+/**
+ * ConfigManager orchestrates all configuration services
+ *
+ * This class delegates responsibilities to specialized services:
+ * - ConfigLoader: Loads configuration from files
+ * - ConfigMerger: Merges configurations with precedence
+ * - RuntimeStateManager: Manages runtime state
+ * - ConfigPersistence: Handles file persistence
+ * - EnvironmentConfigProvider: Extracts env var configuration
+ */
+export class ConfigManager {
+	private projectRoot: string;
+	private config: PartialConfiguration = {};
+	private initialized = false;
+
+	// Services
+	private loader: ConfigLoader;
+	private merger: ConfigMerger;
+	private stateManager: RuntimeStateManager;
+	private persistence: ConfigPersistence;
+	private envProvider: EnvironmentConfigProvider;
+
+	/**
+	 * Create and initialize a new ConfigManager instance
+	 * This is the ONLY way to create a ConfigManager
+	 *
+	 * @param projectRoot - The root directory of the project
+	 * @returns Fully initialized ConfigManager instance
+	 */
+	static async create(projectRoot: string): Promise<ConfigManager> {
+		const manager = new ConfigManager(projectRoot);
+		await manager.initialize();
+		return manager;
+	}
+
+	/**
+	 * Private constructor - use ConfigManager.create() instead
+	 * This ensures the ConfigManager is always properly initialized
+	 */
+	private constructor(projectRoot: string) {
+		this.projectRoot = projectRoot;
+
+		// Initialize services
+		this.loader = new ConfigLoader(projectRoot);
+		this.merger = new ConfigMerger();
+		this.stateManager = new RuntimeStateManager(projectRoot);
+		this.persistence = new ConfigPersistence(projectRoot);
+		this.envProvider = new EnvironmentConfigProvider();
+	}
+
+	/**
+	 * Initialize by loading configuration from all sources
+	 * Private - only called by the factory method
+	 */
+	private async initialize(): Promise<void> {
+		if (this.initialized) return;
+
+		// Clear any existing configuration sources
+		this.merger.clearSources();
+
+		// 1. Load default configuration (lowest precedence)
+		this.merger.addSource({
+			name: 'defaults',
+			config: this.loader.getDefaultConfig(),
+			precedence: CONFIG_PRECEDENCE.DEFAULTS
+		});
+
+		// 2. Load global configuration (if exists)
+		const globalConfig = await this.loader.loadGlobalConfig();
+		if (globalConfig) {
+			this.merger.addSource({
+				name: 'global',
+				config: globalConfig,
+				precedence: CONFIG_PRECEDENCE.GLOBAL
+			});
+		}
+
+		// 3. Load local project configuration
+		const localConfig = await this.loader.loadLocalConfig();
+		if (localConfig) {
+			this.merger.addSource({
+				name: 'local',
+				config: localConfig,
+				precedence: CONFIG_PRECEDENCE.LOCAL
+			});
+		}
+
+		// 4. Load environment variables (highest precedence)
+		const envConfig = this.envProvider.loadConfig();
+		if (Object.keys(envConfig).length > 0) {
+			this.merger.addSource({
+				name: 'environment',
+				config: envConfig,
+				precedence: CONFIG_PRECEDENCE.ENVIRONMENT
+			});
+		}
+
+		// 5. Merge all configurations
+		this.config = this.merger.merge();
+
+		// 6. Load runtime state
+		await this.stateManager.loadState();
+
+		this.initialized = true;
+	}
+
+	// ==================== Configuration Access ====================
+
+	/**
+	 * Get full configuration
+	 */
+	getConfig(): PartialConfiguration {
+		return this.config;
+	}
+
+	/**
+	 * Get storage configuration
+	 */
+	getStorageConfig(): RuntimeStorageConfig {
+		const storage = this.config.storage;
+
+		// Return the configured type (including 'auto')
+		const storageType = storage?.type || 'auto';
+		const basePath = storage?.basePath ?? this.projectRoot;
+
+		if (storageType === 'api' || storageType === 'auto') {
+			return {
+				type: storageType,
+				basePath,
+				apiEndpoint: storage?.apiEndpoint,
+				apiAccessToken: storage?.apiAccessToken,
+				apiConfigured: Boolean(storage?.apiEndpoint || storage?.apiAccessToken)
+			};
+		}
+
+		return {
+			type: storageType,
+			basePath,
+			apiConfigured: false
+		};
+	}
+
+	/**
+	 * Get model configuration
+	 */
+	getModelConfig() {
+		return (
+			this.config.models || {
+				main: 'claude-3-5-sonnet-20241022',
+				fallback: 'gpt-4o-mini'
+			}
+		);
+	}
+
+	/**
+	 * Get response language setting
+	 */
+	getResponseLanguage(): string {
+		const customConfig = this.config.custom as any;
+		return customConfig?.responseLanguage || 'English';
+	}
+
+	/**
+	 * Get project root path
+	 */
+	getProjectRoot(): string {
+		return this.projectRoot;
+	}
+
+	/**
+	 * Check if explicitly configured to use API storage
+	 * Excludes 'auto' type
+	 */
+	isApiExplicitlyConfigured(): boolean {
+		return this.getStorageConfig().type === 'api';
+	}
+
+	// ==================== Runtime State ====================
+
+	/**
+	 * Get the currently active tag
+	 */
+	getActiveTag(): string {
+		return this.stateManager.getCurrentTag();
+	}
+
+	/**
+	 * Set the active tag
+	 */
+	async setActiveTag(tag: string): Promise<void> {
+		await this.stateManager.setCurrentTag(tag);
+	}
+
+	// ==================== Configuration Updates ====================
+
+	/**
+	 * Update configuration
+	 */
+	async updateConfig(updates: PartialConfiguration): Promise<void> {
+		// Merge updates into current config
+		Object.assign(this.config, updates);
+
+		// Save to persistence
+		await this.persistence.saveConfig(this.config);
+
+		// Re-initialize to respect precedence
+		this.initialized = false;
+		await this.initialize();
+	}
+
+	/**
+	 * Set response language
+	 */
+	async setResponseLanguage(language: string): Promise<void> {
+		if (!this.config.custom) {
+			this.config.custom = {};
+		}
+		(this.config.custom as any).responseLanguage = language;
+		await this.persistence.saveConfig(this.config);
+	}
+
+	/**
+	 * Save current configuration
+	 */
+	async saveConfig(): Promise<void> {
+		await this.persistence.saveConfig(this.config, {
+			createBackup: true,
+			atomic: true
+		});
+	}
+
+	// ==================== Utilities ====================
+
+	/**
+	 * Reset configuration to defaults
+	 */
+	async reset(): Promise<void> {
+		// Clear configuration file
+		await this.persistence.deleteConfig();
+
+		// Clear runtime state
+		await this.stateManager.clearState();
+
+		// Reset internal state
+		this.initialized = false;
+		this.config = {};
+
+		// Re-initialize with defaults
+		await this.initialize();
+	}
+
+	/**
+	 * Get configuration sources for debugging
+	 */
+	getConfigSources() {
+		return this.merger.getSources();
+	}
+}

packages/tm-core/src/config/index.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Configuration module exports
+ * Exports the main ConfigManager and all configuration services
+ */
+
+// Export the main ConfigManager
+export { ConfigManager } from './config-manager.js';
+
+// Export all configuration services for advanced usage
+export {
+	ConfigLoader,
+	ConfigMerger,
+	CONFIG_PRECEDENCE,
+	RuntimeStateManager,
+	ConfigPersistence,
+	EnvironmentConfigProvider,
+	type ConfigSource,
+	type RuntimeState,
+	type PersistenceOptions
+} from './services/index.js';
+
+// Re-export configuration interfaces
+export type {
+	IConfiguration,
+	PartialConfiguration,
+	ModelConfig,
+	ProviderConfig,
+	TaskSettings,
+	TagSettings,
+	StorageSettings,
+	RetrySettings,
+	LoggingSettings,
+	SecuritySettings,
+	ConfigValidationResult,
+	EnvironmentConfig,
+	ConfigSchema,
+	ConfigProperty,
+	IConfigurationFactory,
+	IConfigurationManager
+} from '../interfaces/configuration.interface.js';
+
+// Re-export default values
+export { DEFAULT_CONFIG_VALUES } from '../interfaces/configuration.interface.js';

packages/tm-core/src/config/services/config-loader.service.spec.ts

@@ -0,0 +1,144 @@
+/**
+ * @fileoverview Unit tests for ConfigLoader service
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import { ConfigLoader } from './config-loader.service.js';
+import { DEFAULT_CONFIG_VALUES } from '../../interfaces/configuration.interface.js';
+
+vi.mock('node:fs', () => ({
+	promises: {
+		readFile: vi.fn(),
+		access: vi.fn()
+	}
+}));
+
+describe('ConfigLoader', () => {
+	let configLoader: ConfigLoader;
+	const testProjectRoot = '/test/project';
+
+	beforeEach(() => {
+		configLoader = new ConfigLoader(testProjectRoot);
+		vi.clearAllMocks();
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	describe('getDefaultConfig', () => {
+		it('should return default configuration values', () => {
+			const config = configLoader.getDefaultConfig();
+
+			expect(config.models).toEqual({
+				main: DEFAULT_CONFIG_VALUES.MODELS.MAIN,
+				fallback: DEFAULT_CONFIG_VALUES.MODELS.FALLBACK
+			});
+
+			expect(config.storage).toEqual({
+				type: DEFAULT_CONFIG_VALUES.STORAGE.TYPE,
+				encoding: DEFAULT_CONFIG_VALUES.STORAGE.ENCODING,
+				enableBackup: false,
+				maxBackups: DEFAULT_CONFIG_VALUES.STORAGE.MAX_BACKUPS,
+				enableCompression: false,
+				atomicOperations: true
+			});
+
+			expect(config.version).toBe(DEFAULT_CONFIG_VALUES.VERSION);
+		});
+	});
+
+	describe('loadLocalConfig', () => {
+		it('should load and parse local configuration file', async () => {
+			const mockConfig = {
+				models: { main: 'test-model' },
+				storage: { type: 'api' as const }
+			};
+
+			vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(mockConfig));
+
+			const result = await configLoader.loadLocalConfig();
+
+			expect(fs.readFile).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/config.json',
+				'utf-8'
+			);
+			expect(result).toEqual(mockConfig);
+		});
+
+		it('should return null when config file does not exist', async () => {
+			const error = new Error('File not found') as any;
+			error.code = 'ENOENT';
+			vi.mocked(fs.readFile).mockRejectedValue(error);
+
+			const result = await configLoader.loadLocalConfig();
+
+			expect(result).toBeNull();
+		});
+
+		it('should throw TaskMasterError for other file errors', async () => {
+			const error = new Error('Permission denied');
+			vi.mocked(fs.readFile).mockRejectedValue(error);
+
+			await expect(configLoader.loadLocalConfig()).rejects.toThrow(
+				'Failed to load local configuration'
+			);
+		});
+
+		it('should throw error for invalid JSON', async () => {
+			vi.mocked(fs.readFile).mockResolvedValue('invalid json');
+
+			await expect(configLoader.loadLocalConfig()).rejects.toThrow();
+		});
+	});
+
+	describe('loadGlobalConfig', () => {
+		it('should return null (not implemented yet)', async () => {
+			const result = await configLoader.loadGlobalConfig();
+			expect(result).toBeNull();
+		});
+	});
+
+	describe('hasLocalConfig', () => {
+		it('should return true when local config exists', async () => {
+			vi.mocked(fs.access).mockResolvedValue(undefined);
+
+			const result = await configLoader.hasLocalConfig();
+
+			expect(fs.access).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/config.json'
+			);
+			expect(result).toBe(true);
+		});
+
+		it('should return false when local config does not exist', async () => {
+			vi.mocked(fs.access).mockRejectedValue(new Error('Not found'));
+
+			const result = await configLoader.hasLocalConfig();
+
+			expect(result).toBe(false);
+		});
+	});
+
+	describe('hasGlobalConfig', () => {
+		it('should check global config path', async () => {
+			vi.mocked(fs.access).mockResolvedValue(undefined);
+
+			const result = await configLoader.hasGlobalConfig();
+
+			expect(fs.access).toHaveBeenCalledWith(
+				expect.stringContaining('.taskmaster/config.json')
+			);
+			expect(result).toBe(true);
+		});
+
+		it('should return false when global config does not exist', async () => {
+			vi.mocked(fs.access).mockRejectedValue(new Error('Not found'));
+
+			const result = await configLoader.hasGlobalConfig();
+
+			expect(result).toBe(false);
+		});
+	});
+});

packages/tm-core/src/config/services/config-loader.service.ts

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Configuration Loader Service
+ * Responsible for loading configuration from various file sources
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import type { PartialConfiguration } from '../../interfaces/configuration.interface.js';
+import { DEFAULT_CONFIG_VALUES } from '../../interfaces/configuration.interface.js';
+import {
+	ERROR_CODES,
+	TaskMasterError
+} from '../../errors/task-master-error.js';
+
+/**
+ * ConfigLoader handles loading configuration from files
+ * Single responsibility: File-based configuration loading
+ */
+export class ConfigLoader {
+	private localConfigPath: string;
+	private globalConfigPath: string;
+
+	constructor(projectRoot: string) {
+		this.localConfigPath = path.join(projectRoot, '.taskmaster', 'config.json');
+		this.globalConfigPath = path.join(
+			process.env.HOME || '',
+			'.taskmaster',
+			'config.json'
+		);
+	}
+
+	/**
+	 * Get default configuration values
+	 */
+	getDefaultConfig(): PartialConfiguration {
+		return {
+			models: {
+				main: DEFAULT_CONFIG_VALUES.MODELS.MAIN,
+				fallback: DEFAULT_CONFIG_VALUES.MODELS.FALLBACK
+			},
+			storage: {
+				type: DEFAULT_CONFIG_VALUES.STORAGE.TYPE,
+				encoding: DEFAULT_CONFIG_VALUES.STORAGE.ENCODING,
+				enableBackup: false,
+				maxBackups: DEFAULT_CONFIG_VALUES.STORAGE.MAX_BACKUPS,
+				enableCompression: false,
+				atomicOperations: true
+			},
+			version: DEFAULT_CONFIG_VALUES.VERSION
+		};
+	}
+
+	/**
+	 * Load local project configuration
+	 */
+	async loadLocalConfig(): Promise<PartialConfiguration | null> {
+		try {
+			const configData = await fs.readFile(this.localConfigPath, 'utf-8');
+			return JSON.parse(configData);
+		} catch (error: any) {
+			if (error.code === 'ENOENT') {
+				// File doesn't exist, return null
+				console.debug('No local config.json found, using defaults');
+				return null;
+			}
+			throw new TaskMasterError(
+				'Failed to load local configuration',
+				ERROR_CODES.CONFIG_ERROR,
+				{ configPath: this.localConfigPath },
+				error
+			);
+		}
+	}
+
+	/**
+	 * Load global user configuration
+	 * @future-implementation Full implementation pending
+	 */
+	async loadGlobalConfig(): Promise<PartialConfiguration | null> {
+		// TODO: Implement in future PR
+		// For now, return null to indicate no global config
+		return null;
+
+		// Future implementation:
+		// try {
+		//   const configData = await fs.readFile(this.globalConfigPath, 'utf-8');
+		//   return JSON.parse(configData);
+		// } catch (error: any) {
+		//   if (error.code === 'ENOENT') {
+		//     return null;
+		//   }
+		//   throw new TaskMasterError(
+		//     'Failed to load global configuration',
+		//     ERROR_CODES.CONFIG_ERROR,
+		//     { configPath: this.globalConfigPath },
+		//     error
+		//   );
+		// }
+	}
+
+	/**
+	 * Check if local config exists
+	 */
+	async hasLocalConfig(): Promise<boolean> {
+		try {
+			await fs.access(this.localConfigPath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	/**
+	 * Check if global config exists
+	 */
+	async hasGlobalConfig(): Promise<boolean> {
+		try {
+			await fs.access(this.globalConfigPath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+}

packages/tm-core/src/config/services/config-merger.service.spec.ts

@@ -0,0 +1,237 @@
+/**
+ * @fileoverview Unit tests for ConfigMerger service
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ConfigMerger, CONFIG_PRECEDENCE } from './config-merger.service.js';
+
+describe('ConfigMerger', () => {
+	let merger: ConfigMerger;
+
+	beforeEach(() => {
+		merger = new ConfigMerger();
+	});
+
+	describe('addSource', () => {
+		it('should add configuration source', () => {
+			const source = {
+				name: 'test',
+				config: { test: true },
+				precedence: 1
+			};
+
+			merger.addSource(source);
+			const sources = merger.getSources();
+
+			expect(sources).toHaveLength(1);
+			expect(sources[0]).toEqual(source);
+		});
+
+		it('should add multiple sources', () => {
+			merger.addSource({ name: 'source1', config: {}, precedence: 1 });
+			merger.addSource({ name: 'source2', config: {}, precedence: 2 });
+
+			expect(merger.getSources()).toHaveLength(2);
+		});
+	});
+
+	describe('clearSources', () => {
+		it('should remove all configuration sources', () => {
+			merger.addSource({ name: 'test', config: {}, precedence: 1 });
+			merger.clearSources();
+
+			expect(merger.getSources()).toHaveLength(0);
+		});
+	});
+
+	describe('merge', () => {
+		it('should merge configurations based on precedence', () => {
+			merger.addSource({
+				name: 'low',
+				config: { a: 1, b: 2 },
+				precedence: 1
+			});
+
+			merger.addSource({
+				name: 'high',
+				config: { a: 3, c: 4 },
+				precedence: 2
+			});
+
+			const result = merger.merge();
+
+			expect(result).toEqual({
+				a: 3, // High precedence wins
+				b: 2, // Only in low
+				c: 4 // Only in high
+			});
+		});
+
+		it('should deep merge nested objects', () => {
+			merger.addSource({
+				name: 'base',
+				config: {
+					models: { main: 'model1', fallback: 'model2' },
+					storage: { type: 'file' as const }
+				},
+				precedence: 1
+			});
+
+			merger.addSource({
+				name: 'override',
+				config: {
+					models: { main: 'model3' },
+					storage: { encoding: 'utf8' as const }
+				},
+				precedence: 2
+			});
+
+			const result = merger.merge();
+
+			expect(result).toEqual({
+				models: {
+					main: 'model3', // Overridden
+					fallback: 'model2' // Preserved
+				},
+				storage: {
+					type: 'file', // Preserved
+					encoding: 'utf8' // Added
+				}
+			});
+		});
+
+		it('should handle arrays by replacement', () => {
+			merger.addSource({
+				name: 'base',
+				config: { items: [1, 2, 3] },
+				precedence: 1
+			});
+
+			merger.addSource({
+				name: 'override',
+				config: { items: [4, 5] },
+				precedence: 2
+			});
+
+			const result = merger.merge();
+
+			expect(result.items).toEqual([4, 5]); // Arrays are replaced, not merged
+		});
+
+		it('should ignore null and undefined values', () => {
+			merger.addSource({
+				name: 'base',
+				config: { a: 1, b: 2 },
+				precedence: 1
+			});
+
+			merger.addSource({
+				name: 'override',
+				config: { a: null, b: undefined, c: 3 } as any,
+				precedence: 2
+			});
+
+			const result = merger.merge();
+
+			expect(result).toEqual({
+				a: 1, // null ignored
+				b: 2, // undefined ignored
+				c: 3 // new value added
+			});
+		});
+
+		it('should return empty object when no sources', () => {
+			const result = merger.merge();
+			expect(result).toEqual({});
+		});
+
+		it('should use CONFIG_PRECEDENCE constants correctly', () => {
+			merger.addSource({
+				name: 'defaults',
+				config: { level: 'default' },
+				precedence: CONFIG_PRECEDENCE.DEFAULTS
+			});
+
+			merger.addSource({
+				name: 'local',
+				config: { level: 'local' },
+				precedence: CONFIG_PRECEDENCE.LOCAL
+			});
+
+			merger.addSource({
+				name: 'environment',
+				config: { level: 'env' },
+				precedence: CONFIG_PRECEDENCE.ENVIRONMENT
+			});
+
+			const result = merger.merge();
+
+			expect(result.level).toBe('env'); // Highest precedence wins
+		});
+	});
+
+	describe('getSources', () => {
+		it('should return sources sorted by precedence (highest first)', () => {
+			merger.addSource({ name: 'low', config: {}, precedence: 1 });
+			merger.addSource({ name: 'high', config: {}, precedence: 3 });
+			merger.addSource({ name: 'medium', config: {}, precedence: 2 });
+
+			const sources = merger.getSources();
+
+			expect(sources[0].name).toBe('high');
+			expect(sources[1].name).toBe('medium');
+			expect(sources[2].name).toBe('low');
+		});
+
+		it('should return a copy of sources array', () => {
+			merger.addSource({ name: 'test', config: {}, precedence: 1 });
+
+			const sources1 = merger.getSources();
+			const sources2 = merger.getSources();
+
+			expect(sources1).not.toBe(sources2); // Different array instances
+			expect(sources1).toEqual(sources2); // Same content
+		});
+	});
+
+	describe('hasSource', () => {
+		it('should return true when source exists', () => {
+			merger.addSource({ name: 'test', config: {}, precedence: 1 });
+
+			expect(merger.hasSource('test')).toBe(true);
+		});
+
+		it('should return false when source does not exist', () => {
+			expect(merger.hasSource('nonexistent')).toBe(false);
+		});
+	});
+
+	describe('removeSource', () => {
+		it('should remove source by name and return true', () => {
+			merger.addSource({ name: 'test', config: {}, precedence: 1 });
+			merger.addSource({ name: 'keep', config: {}, precedence: 2 });
+
+			const removed = merger.removeSource('test');
+
+			expect(removed).toBe(true);
+			expect(merger.hasSource('test')).toBe(false);
+			expect(merger.hasSource('keep')).toBe(true);
+		});
+
+		it('should return false when source does not exist', () => {
+			const removed = merger.removeSource('nonexistent');
+
+			expect(removed).toBe(false);
+		});
+
+		it('should handle removing all sources', () => {
+			merger.addSource({ name: 'test1', config: {}, precedence: 1 });
+			merger.addSource({ name: 'test2', config: {}, precedence: 2 });
+
+			merger.removeSource('test1');
+			merger.removeSource('test2');
+
+			expect(merger.getSources()).toHaveLength(0);
+		});
+	});
+});

packages/tm-core/src/config/services/config-merger.service.ts

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview Configuration Merger Service
+ * Responsible for merging configurations from multiple sources with precedence
+ */
+
+import type { PartialConfiguration } from '../../interfaces/configuration.interface.js';
+
+/**
+ * Configuration source with precedence
+ */
+export interface ConfigSource {
+	/** Source name for debugging */
+	name: string;
+	/** Configuration data from this source */
+	config: PartialConfiguration;
+	/** Precedence level (higher = more important) */
+	precedence: number;
+}
+
+/**
+ * Configuration precedence levels (higher number = higher priority)
+ */
+export const CONFIG_PRECEDENCE = {
+	DEFAULTS: 0,
+	GLOBAL: 1, // Reserved for future implementation
+	LOCAL: 2,
+	ENVIRONMENT: 3
+} as const;
+
+/**
+ * ConfigMerger handles merging configurations with precedence rules
+ * Single responsibility: Configuration merging logic
+ */
+export class ConfigMerger {
+	private configSources: ConfigSource[] = [];
+
+	/**
+	 * Add a configuration source
+	 */
+	addSource(source: ConfigSource): void {
+		this.configSources.push(source);
+	}
+
+	/**
+	 * Clear all configuration sources
+	 */
+	clearSources(): void {
+		this.configSources = [];
+	}
+
+	/**
+	 * Merge all configuration sources based on precedence
+	 */
+	merge(): PartialConfiguration {
+		// Sort sources by precedence (lowest first)
+		const sortedSources = [...this.configSources].sort(
+			(a, b) => a.precedence - b.precedence
+		);
+
+		// Merge from lowest to highest precedence
+		let merged: PartialConfiguration = {};
+		for (const source of sortedSources) {
+			merged = this.deepMerge(merged, source.config);
+		}
+
+		return merged;
+	}
+
+	/**
+	 * Deep merge two configuration objects
+	 * Higher precedence values override lower ones
+	 */
+	private deepMerge(target: any, source: any): any {
+		if (!source) return target;
+		if (!target) return source;
+
+		const result = { ...target };
+
+		for (const key in source) {
+			if (source[key] === null || source[key] === undefined) {
+				continue;
+			}
+
+			if (typeof source[key] === 'object' && !Array.isArray(source[key])) {
+				result[key] = this.deepMerge(result[key] || {}, source[key]);
+			} else {
+				result[key] = source[key];
+			}
+		}
+
+		return result;
+	}
+
+	/**
+	 * Get configuration sources for debugging
+	 */
+	getSources(): ConfigSource[] {
+		return [...this.configSources].sort((a, b) => b.precedence - a.precedence);
+	}
+
+	/**
+	 * Check if a source exists
+	 */
+	hasSource(name: string): boolean {
+		return this.configSources.some((source) => source.name === name);
+	}
+
+	/**
+	 * Remove a source by name
+	 */
+	removeSource(name: string): boolean {
+		const initialLength = this.configSources.length;
+		this.configSources = this.configSources.filter(
+			(source) => source.name !== name
+		);
+		return this.configSources.length < initialLength;
+	}
+}

packages/tm-core/src/config/services/config-persistence.service.spec.ts

@@ -0,0 +1,316 @@
+/**
+ * @fileoverview Unit tests for ConfigPersistence service
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import { ConfigPersistence } from './config-persistence.service.js';
+
+vi.mock('node:fs', () => ({
+	promises: {
+		readFile: vi.fn(),
+		writeFile: vi.fn(),
+		mkdir: vi.fn(),
+		unlink: vi.fn(),
+		access: vi.fn(),
+		readdir: vi.fn(),
+		rename: vi.fn()
+	}
+}));
+
+describe('ConfigPersistence', () => {
+	let persistence: ConfigPersistence;
+	const testProjectRoot = '/test/project';
+
+	beforeEach(() => {
+		persistence = new ConfigPersistence(testProjectRoot);
+		vi.clearAllMocks();
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	describe('saveConfig', () => {
+		const mockConfig = {
+			models: { main: 'test-model' },
+			storage: { type: 'file' as const }
+		};
+
+		it('should save configuration to file', async () => {
+			vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+			await persistence.saveConfig(mockConfig);
+
+			expect(fs.mkdir).toHaveBeenCalledWith('/test/project/.taskmaster', {
+				recursive: true
+			});
+
+			expect(fs.writeFile).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/config.json',
+				JSON.stringify(mockConfig, null, 2),
+				'utf-8'
+			);
+		});
+
+		it('should use atomic write when specified', async () => {
+			vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+			vi.mocked(fs.rename).mockResolvedValue(undefined);
+
+			await persistence.saveConfig(mockConfig, { atomic: true });
+
+			// Should write to temp file first
+			expect(fs.writeFile).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/config.json.tmp',
+				JSON.stringify(mockConfig, null, 2),
+				'utf-8'
+			);
+
+			// Then rename to final location
+			expect(fs.rename).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/config.json.tmp',
+				'/test/project/.taskmaster/config.json'
+			);
+		});
+
+		it('should create backup when requested', async () => {
+			vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+			vi.mocked(fs.access).mockResolvedValue(undefined); // Config exists
+			vi.mocked(fs.readFile).mockResolvedValue('{"old": "config"}');
+			vi.mocked(fs.readdir).mockResolvedValue([]);
+
+			await persistence.saveConfig(mockConfig, { createBackup: true });
+
+			// Should create backup directory
+			expect(fs.mkdir).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/backups',
+				{ recursive: true }
+			);
+
+			// Should read existing config for backup
+			expect(fs.readFile).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/config.json',
+				'utf-8'
+			);
+
+			// Should write backup file
+			expect(fs.writeFile).toHaveBeenCalledWith(
+				expect.stringContaining('/test/project/.taskmaster/backups/config-'),
+				'{"old": "config"}',
+				'utf-8'
+			);
+		});
+
+		it('should not create backup if config does not exist', async () => {
+			vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+			vi.mocked(fs.access).mockRejectedValue(new Error('Not found'));
+
+			await persistence.saveConfig(mockConfig, { createBackup: true });
+
+			// Should not read or create backup
+			expect(fs.readFile).not.toHaveBeenCalled();
+			expect(fs.writeFile).toHaveBeenCalledTimes(1); // Only the main config
+		});
+
+		it('should throw TaskMasterError on save failure', async () => {
+			vi.mocked(fs.mkdir).mockRejectedValue(new Error('Disk full'));
+
+			await expect(persistence.saveConfig(mockConfig)).rejects.toThrow(
+				'Failed to save configuration'
+			);
+		});
+	});
+
+	describe('configExists', () => {
+		it('should return true when config exists', async () => {
+			vi.mocked(fs.access).mockResolvedValue(undefined);
+
+			const exists = await persistence.configExists();
+
+			expect(fs.access).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/config.json'
+			);
+			expect(exists).toBe(true);
+		});
+
+		it('should return false when config does not exist', async () => {
+			vi.mocked(fs.access).mockRejectedValue(new Error('Not found'));
+
+			const exists = await persistence.configExists();
+
+			expect(exists).toBe(false);
+		});
+	});
+
+	describe('deleteConfig', () => {
+		it('should delete configuration file', async () => {
+			vi.mocked(fs.unlink).mockResolvedValue(undefined);
+
+			await persistence.deleteConfig();
+
+			expect(fs.unlink).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/config.json'
+			);
+		});
+
+		it('should not throw when file does not exist', async () => {
+			const error = new Error('File not found') as any;
+			error.code = 'ENOENT';
+			vi.mocked(fs.unlink).mockRejectedValue(error);
+
+			await expect(persistence.deleteConfig()).resolves.not.toThrow();
+		});
+
+		it('should throw TaskMasterError for other errors', async () => {
+			vi.mocked(fs.unlink).mockRejectedValue(new Error('Permission denied'));
+
+			await expect(persistence.deleteConfig()).rejects.toThrow(
+				'Failed to delete configuration'
+			);
+		});
+	});
+
+	describe('getBackups', () => {
+		it('should return list of backup files sorted newest first', async () => {
+			vi.mocked(fs.readdir).mockResolvedValue([
+				'config-2024-01-01T10-00-00-000Z.json',
+				'config-2024-01-02T10-00-00-000Z.json',
+				'config-2024-01-03T10-00-00-000Z.json',
+				'other-file.txt'
+			] as any);
+
+			const backups = await persistence.getBackups();
+
+			expect(fs.readdir).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/backups'
+			);
+
+			expect(backups).toEqual([
+				'config-2024-01-03T10-00-00-000Z.json',
+				'config-2024-01-02T10-00-00-000Z.json',
+				'config-2024-01-01T10-00-00-000Z.json'
+			]);
+		});
+
+		it('should return empty array when backup directory does not exist', async () => {
+			vi.mocked(fs.readdir).mockRejectedValue(new Error('Not found'));
+
+			const backups = await persistence.getBackups();
+
+			expect(backups).toEqual([]);
+		});
+
+		it('should filter out non-backup files', async () => {
+			vi.mocked(fs.readdir).mockResolvedValue([
+				'config-2024-01-01T10-00-00-000Z.json',
+				'README.md',
+				'.DS_Store',
+				'config.json',
+				'config-backup.json' // Wrong format
+			] as any);
+
+			const backups = await persistence.getBackups();
+
+			expect(backups).toEqual(['config-2024-01-01T10-00-00-000Z.json']);
+		});
+	});
+
+	describe('restoreFromBackup', () => {
+		const backupFile = 'config-2024-01-01T10-00-00-000Z.json';
+		const backupContent = '{"restored": "config"}';
+
+		it('should restore configuration from backup', async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(backupContent);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+			await persistence.restoreFromBackup(backupFile);
+
+			expect(fs.readFile).toHaveBeenCalledWith(
+				`/test/project/.taskmaster/backups/${backupFile}`,
+				'utf-8'
+			);
+
+			expect(fs.writeFile).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/config.json',
+				backupContent,
+				'utf-8'
+			);
+		});
+
+		it('should throw TaskMasterError when backup file not found', async () => {
+			vi.mocked(fs.readFile).mockRejectedValue(new Error('File not found'));
+
+			await expect(
+				persistence.restoreFromBackup('nonexistent.json')
+			).rejects.toThrow('Failed to restore from backup');
+		});
+
+		it('should throw TaskMasterError on write failure', async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(backupContent);
+			vi.mocked(fs.writeFile).mockRejectedValue(new Error('Disk full'));
+
+			await expect(persistence.restoreFromBackup(backupFile)).rejects.toThrow(
+				'Failed to restore from backup'
+			);
+		});
+	});
+
+	describe('backup management', () => {
+		it('should clean old backups when limit exceeded', async () => {
+			vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+			vi.mocked(fs.access).mockResolvedValue(undefined);
+			vi.mocked(fs.readFile).mockResolvedValue('{"old": "config"}');
+			vi.mocked(fs.unlink).mockResolvedValue(undefined);
+
+			// Mock 7 existing backups
+			vi.mocked(fs.readdir).mockResolvedValue([
+				'config-2024-01-01T10-00-00-000Z.json',
+				'config-2024-01-02T10-00-00-000Z.json',
+				'config-2024-01-03T10-00-00-000Z.json',
+				'config-2024-01-04T10-00-00-000Z.json',
+				'config-2024-01-05T10-00-00-000Z.json',
+				'config-2024-01-06T10-00-00-000Z.json',
+				'config-2024-01-07T10-00-00-000Z.json'
+			] as any);
+
+			await persistence.saveConfig({}, { createBackup: true });
+
+			// Should delete oldest backups (keeping 5)
+			expect(fs.unlink).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/backups/config-2024-01-01T10-00-00-000Z.json'
+			);
+			expect(fs.unlink).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/backups/config-2024-01-02T10-00-00-000Z.json'
+			);
+		});
+
+		it('should handle backup cleanup errors gracefully', async () => {
+			vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+			vi.mocked(fs.access).mockResolvedValue(undefined);
+			vi.mocked(fs.readFile).mockResolvedValue('{"old": "config"}');
+			vi.mocked(fs.readdir).mockResolvedValue(['config-old.json'] as any);
+			vi.mocked(fs.unlink).mockRejectedValue(new Error('Permission denied'));
+
+			// Mock console.warn to verify it's called
+			const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+			// Should not throw even if cleanup fails
+			await expect(
+				persistence.saveConfig({}, { createBackup: true })
+			).resolves.not.toThrow();
+
+			expect(warnSpy).toHaveBeenCalledWith(
+				'Failed to clean old backups:',
+				expect.any(Error)
+			);
+
+			warnSpy.mockRestore();
+		});
+	});
+});

packages/tm-core/src/config/services/config-persistence.service.ts

@@ -0,0 +1,186 @@
+/**
+ * @fileoverview Configuration Persistence Service
+ * Handles saving and backup of configuration files
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import type { PartialConfiguration } from '../../interfaces/configuration.interface.js';
+import {
+	ERROR_CODES,
+	TaskMasterError
+} from '../../errors/task-master-error.js';
+
+/**
+ * Persistence options
+ */
+export interface PersistenceOptions {
+	/** Enable backup before saving */
+	createBackup?: boolean;
+	/** Maximum number of backups to keep */
+	maxBackups?: number;
+	/** Use atomic write operations */
+	atomic?: boolean;
+}
+
+/**
+ * ConfigPersistence handles all configuration file I/O operations
+ * Single responsibility: Configuration persistence
+ */
+export class ConfigPersistence {
+	private localConfigPath: string;
+	private backupDir: string;
+
+	constructor(projectRoot: string) {
+		this.localConfigPath = path.join(projectRoot, '.taskmaster', 'config.json');
+		this.backupDir = path.join(projectRoot, '.taskmaster', 'backups');
+	}
+
+	/**
+	 * Save configuration to file
+	 */
+	async saveConfig(
+		config: PartialConfiguration,
+		options: PersistenceOptions = {}
+	): Promise<void> {
+		const { createBackup = false, atomic = true } = options;
+
+		try {
+			// Create backup if requested
+			if (createBackup && (await this.configExists())) {
+				await this.createBackup();
+			}
+
+			// Ensure directory exists
+			const configDir = path.dirname(this.localConfigPath);
+			await fs.mkdir(configDir, { recursive: true });
+
+			const jsonContent = JSON.stringify(config, null, 2);
+
+			if (atomic) {
+				// Atomic write: write to temp file then rename
+				const tempPath = `${this.localConfigPath}.tmp`;
+				await fs.writeFile(tempPath, jsonContent, 'utf-8');
+				await fs.rename(tempPath, this.localConfigPath);
+			} else {
+				// Direct write
+				await fs.writeFile(this.localConfigPath, jsonContent, 'utf-8');
+			}
+		} catch (error) {
+			throw new TaskMasterError(
+				'Failed to save configuration',
+				ERROR_CODES.CONFIG_ERROR,
+				{ configPath: this.localConfigPath },
+				error as Error
+			);
+		}
+	}
+
+	/**
+	 * Create a backup of the current configuration
+	 */
+	private async createBackup(): Promise<string> {
+		try {
+			await fs.mkdir(this.backupDir, { recursive: true });
+
+			const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+			const backupPath = path.join(this.backupDir, `config-${timestamp}.json`);
+
+			const configContent = await fs.readFile(this.localConfigPath, 'utf-8');
+			await fs.writeFile(backupPath, configContent, 'utf-8');
+
+			// Clean old backups
+			await this.cleanOldBackups();
+
+			return backupPath;
+		} catch (error) {
+			console.warn('Failed to create backup:', error);
+			throw error;
+		}
+	}
+
+	/**
+	 * Clean old backup files
+	 */
+	private async cleanOldBackups(maxBackups = 5): Promise<void> {
+		try {
+			const files = await fs.readdir(this.backupDir);
+			const backupFiles = files
+				.filter((f) => f.startsWith('config-') && f.endsWith('.json'))
+				.sort()
+				.reverse();
+
+			// Remove old backups
+			const toDelete = backupFiles.slice(maxBackups);
+			for (const file of toDelete) {
+				await fs.unlink(path.join(this.backupDir, file));
+			}
+		} catch (error) {
+			console.warn('Failed to clean old backups:', error);
+		}
+	}
+
+	/**
+	 * Check if config file exists
+	 */
+	async configExists(): Promise<boolean> {
+		try {
+			await fs.access(this.localConfigPath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	/**
+	 * Delete configuration file
+	 */
+	async deleteConfig(): Promise<void> {
+		try {
+			await fs.unlink(this.localConfigPath);
+		} catch (error: any) {
+			if (error.code !== 'ENOENT') {
+				throw new TaskMasterError(
+					'Failed to delete configuration',
+					ERROR_CODES.CONFIG_ERROR,
+					{ configPath: this.localConfigPath },
+					error
+				);
+			}
+		}
+	}
+
+	/**
+	 * Get list of available backups
+	 */
+	async getBackups(): Promise<string[]> {
+		try {
+			const files = await fs.readdir(this.backupDir);
+			return files
+				.filter((f) => f.startsWith('config-') && f.endsWith('.json'))
+				.sort()
+				.reverse();
+		} catch {
+			return [];
+		}
+	}
+
+	/**
+	 * Restore from a backup
+	 */
+	async restoreFromBackup(backupFile: string): Promise<void> {
+		const backupPath = path.join(this.backupDir, backupFile);
+
+		try {
+			const backupContent = await fs.readFile(backupPath, 'utf-8');
+			await fs.writeFile(this.localConfigPath, backupContent, 'utf-8');
+		} catch (error) {
+			throw new TaskMasterError(
+				'Failed to restore from backup',
+				ERROR_CODES.CONFIG_ERROR,
+				{ backupPath },
+				error as Error
+			);
+		}
+	}
+}

packages/tm-core/src/config/services/environment-config-provider.service.spec.ts

@@ -0,0 +1,343 @@
+/**
+ * @fileoverview Unit tests for EnvironmentConfigProvider service
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { EnvironmentConfigProvider } from './environment-config-provider.service.js';
+
+describe('EnvironmentConfigProvider', () => {
+	let provider: EnvironmentConfigProvider;
+	const originalEnv = { ...process.env };
+
+	beforeEach(() => {
+		// Clear all TASKMASTER_ env vars
+		Object.keys(process.env).forEach((key) => {
+			if (key.startsWith('TASKMASTER_')) {
+				delete process.env[key];
+			}
+		});
+		provider = new EnvironmentConfigProvider();
+	});
+
+	afterEach(() => {
+		// Restore original environment
+		process.env = { ...originalEnv };
+	});
+
+	describe('loadConfig', () => {
+		it('should load configuration from environment variables', () => {
+			process.env.TASKMASTER_STORAGE_TYPE = 'api';
+			process.env.TASKMASTER_API_ENDPOINT = 'https://api.example.com';
+			process.env.TASKMASTER_MODEL_MAIN = 'gpt-4';
+
+			const config = provider.loadConfig();
+
+			expect(config).toEqual({
+				storage: {
+					type: 'api',
+					apiEndpoint: 'https://api.example.com'
+				},
+				models: {
+					main: 'gpt-4'
+				}
+			});
+		});
+
+		it('should return empty object when no env vars are set', () => {
+			const config = provider.loadConfig();
+			expect(config).toEqual({});
+		});
+
+		it('should skip runtime state variables', () => {
+			process.env.TASKMASTER_TAG = 'feature-branch';
+			process.env.TASKMASTER_MODEL_MAIN = 'claude-3';
+
+			const config = provider.loadConfig();
+
+			expect(config).toEqual({
+				models: { main: 'claude-3' }
+			});
+			expect(config).not.toHaveProperty('activeTag');
+		});
+
+		it('should validate storage type values', () => {
+			// Mock console.warn to check validation
+			const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+			process.env.TASKMASTER_STORAGE_TYPE = 'invalid';
+
+			const config = provider.loadConfig();
+
+			expect(config).toEqual({});
+			expect(warnSpy).toHaveBeenCalledWith(
+				'Invalid value for TASKMASTER_STORAGE_TYPE: invalid'
+			);
+
+			warnSpy.mockRestore();
+		});
+
+		it('should accept valid storage type values', () => {
+			process.env.TASKMASTER_STORAGE_TYPE = 'file';
+			let config = provider.loadConfig();
+			expect(config.storage?.type).toBe('file');
+
+			process.env.TASKMASTER_STORAGE_TYPE = 'api';
+			provider = new EnvironmentConfigProvider(); // Reset provider
+			config = provider.loadConfig();
+			expect(config.storage?.type).toBe('api');
+		});
+
+		it('should handle nested configuration paths', () => {
+			process.env.TASKMASTER_MODEL_MAIN = 'model1';
+			process.env.TASKMASTER_MODEL_RESEARCH = 'model2';
+			process.env.TASKMASTER_MODEL_FALLBACK = 'model3';
+
+			const config = provider.loadConfig();
+
+			expect(config).toEqual({
+				models: {
+					main: 'model1',
+					research: 'model2',
+					fallback: 'model3'
+				}
+			});
+		});
+
+		it('should handle custom response language', () => {
+			process.env.TASKMASTER_RESPONSE_LANGUAGE = 'Spanish';
+
+			const config = provider.loadConfig();
+
+			expect(config).toEqual({
+				custom: {
+					responseLanguage: 'Spanish'
+				}
+			});
+		});
+
+		it('should ignore empty string values', () => {
+			process.env.TASKMASTER_MODEL_MAIN = '';
+			process.env.TASKMASTER_MODEL_FALLBACK = 'fallback-model';
+
+			const config = provider.loadConfig();
+
+			expect(config).toEqual({
+				models: {
+					fallback: 'fallback-model'
+				}
+			});
+		});
+	});
+
+	describe('getRuntimeState', () => {
+		it('should extract runtime state variables', () => {
+			process.env.TASKMASTER_TAG = 'develop';
+			process.env.TASKMASTER_MODEL_MAIN = 'model'; // Should not be included
+
+			const state = provider.getRuntimeState();
+
+			expect(state).toEqual({
+				activeTag: 'develop'
+			});
+		});
+
+		it('should return empty object when no runtime state vars', () => {
+			process.env.TASKMASTER_MODEL_MAIN = 'model';
+
+			const state = provider.getRuntimeState();
+
+			expect(state).toEqual({});
+		});
+	});
+
+	describe('hasEnvVar', () => {
+		it('should return true when env var exists', () => {
+			process.env.TASKMASTER_MODEL_MAIN = 'test';
+
+			expect(provider.hasEnvVar('TASKMASTER_MODEL_MAIN')).toBe(true);
+		});
+
+		it('should return false when env var does not exist', () => {
+			expect(provider.hasEnvVar('TASKMASTER_NONEXISTENT')).toBe(false);
+		});
+
+		it('should return false for undefined values', () => {
+			process.env.TASKMASTER_TEST = undefined as any;
+
+			expect(provider.hasEnvVar('TASKMASTER_TEST')).toBe(false);
+		});
+	});
+
+	describe('getAllTaskmasterEnvVars', () => {
+		it('should return all TASKMASTER_ prefixed variables', () => {
+			process.env.TASKMASTER_VAR1 = 'value1';
+			process.env.TASKMASTER_VAR2 = 'value2';
+			process.env.OTHER_VAR = 'other';
+			process.env.TASK_MASTER = 'wrong-prefix';
+
+			const vars = provider.getAllTaskmasterEnvVars();
+
+			expect(vars).toEqual({
+				TASKMASTER_VAR1: 'value1',
+				TASKMASTER_VAR2: 'value2'
+			});
+		});
+
+		it('should return empty object when no TASKMASTER_ vars', () => {
+			process.env.OTHER_VAR = 'value';
+
+			const vars = provider.getAllTaskmasterEnvVars();
+
+			expect(vars).toEqual({});
+		});
+
+		it('should filter out undefined values', () => {
+			process.env.TASKMASTER_DEFINED = 'value';
+			process.env.TASKMASTER_UNDEFINED = undefined as any;
+
+			const vars = provider.getAllTaskmasterEnvVars();
+
+			expect(vars).toEqual({
+				TASKMASTER_DEFINED: 'value'
+			});
+		});
+	});
+
+	describe('custom mappings', () => {
+		it('should use custom mappings when provided', () => {
+			const customMappings = [{ env: 'CUSTOM_VAR', path: ['custom', 'value'] }];
+
+			const customProvider = new EnvironmentConfigProvider(customMappings);
+			process.env.CUSTOM_VAR = 'test-value';
+
+			const config = customProvider.loadConfig();
+
+			expect(config).toEqual({
+				custom: {
+					value: 'test-value'
+				}
+			});
+		});
+
+		it('should add new mapping with addMapping', () => {
+			process.env.NEW_MAPPING = 'new-value';
+
+			provider.addMapping({
+				env: 'NEW_MAPPING',
+				path: ['new', 'mapping']
+			});
+
+			const config = provider.loadConfig();
+
+			expect(config).toHaveProperty('new.mapping', 'new-value');
+		});
+
+		it('should return current mappings with getMappings', () => {
+			const mappings = provider.getMappings();
+
+			expect(mappings).toBeInstanceOf(Array);
+			expect(mappings.length).toBeGreaterThan(0);
+
+			// Check for some expected mappings
+			const envNames = mappings.map((m) => m.env);
+			expect(envNames).toContain('TASKMASTER_STORAGE_TYPE');
+			expect(envNames).toContain('TASKMASTER_MODEL_MAIN');
+			expect(envNames).toContain('TASKMASTER_TAG');
+		});
+
+		it('should return copy of mappings array', () => {
+			const mappings1 = provider.getMappings();
+			const mappings2 = provider.getMappings();
+
+			expect(mappings1).not.toBe(mappings2); // Different instances
+			expect(mappings1).toEqual(mappings2); // Same content
+		});
+	});
+
+	describe('validation', () => {
+		it('should validate values when validator is provided', () => {
+			const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+			process.env.TASKMASTER_STORAGE_TYPE = 'database'; // Invalid
+
+			const config = provider.loadConfig();
+
+			expect(config).toEqual({});
+			expect(warnSpy).toHaveBeenCalledWith(
+				'Invalid value for TASKMASTER_STORAGE_TYPE: database'
+			);
+
+			warnSpy.mockRestore();
+		});
+
+		it('should accept values that pass validation', () => {
+			process.env.TASKMASTER_STORAGE_TYPE = 'file';
+
+			const config = provider.loadConfig();
+
+			expect(config.storage?.type).toBe('file');
+		});
+
+		it('should work with custom validators', () => {
+			const customProvider = new EnvironmentConfigProvider([
+				{
+					env: 'CUSTOM_NUMBER',
+					path: ['custom', 'number'],
+					validate: (v) => !isNaN(Number(v))
+				}
+			]);
+
+			process.env.CUSTOM_NUMBER = '123';
+			let config = customProvider.loadConfig();
+			expect(config.custom?.number).toBe('123');
+
+			process.env.CUSTOM_NUMBER = 'not-a-number';
+			const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+			customProvider = new EnvironmentConfigProvider([
+				{
+					env: 'CUSTOM_NUMBER',
+					path: ['custom', 'number'],
+					validate: (v) => !isNaN(Number(v))
+				}
+			]);
+			config = customProvider.loadConfig();
+			expect(config).toEqual({});
+			expect(warnSpy).toHaveBeenCalled();
+
+			warnSpy.mockRestore();
+		});
+	});
+
+	describe('edge cases', () => {
+		it('should handle special characters in values', () => {
+			process.env.TASKMASTER_API_ENDPOINT =
+				'https://api.example.com/v1?key=abc&token=xyz';
+			process.env.TASKMASTER_API_TOKEN = 'Bearer abc123!@#$%^&*()';
+
+			const config = provider.loadConfig();
+
+			expect(config.storage?.apiEndpoint).toBe(
+				'https://api.example.com/v1?key=abc&token=xyz'
+			);
+			expect(config.storage?.apiAccessToken).toBe('Bearer abc123!@#$%^&*()');
+		});
+
+		it('should handle whitespace in values', () => {
+			process.env.TASKMASTER_MODEL_MAIN = '  claude-3  ';
+
+			const config = provider.loadConfig();
+
+			// Note: We're not trimming, preserving the value as-is
+			expect(config.models?.main).toBe('  claude-3  ');
+		});
+
+		it('should handle very long values', () => {
+			const longValue = 'a'.repeat(10000);
+			process.env.TASKMASTER_API_TOKEN = longValue;
+
+			const config = provider.loadConfig();
+
+			expect(config.storage?.apiAccessToken).toBe(longValue);
+		});
+	});
+});

packages/tm-core/src/config/services/environment-config-provider.service.ts

@@ -0,0 +1,166 @@
+/**
+ * @fileoverview Environment Configuration Provider
+ * Extracts configuration from environment variables
+ */
+
+import type { PartialConfiguration } from '../../interfaces/configuration.interface.js';
+
+/**
+ * Environment variable mapping definition
+ */
+interface EnvMapping {
+	/** Environment variable name */
+	env: string;
+	/** Path in configuration object */
+	path: readonly string[];
+	/** Optional validator function */
+	validate?: (value: string) => boolean;
+	/** Whether this is runtime state (not configuration) */
+	isRuntimeState?: boolean;
+}
+
+/**
+ * EnvironmentConfigProvider extracts configuration from environment variables
+ * Single responsibility: Environment variable configuration extraction
+ */
+export class EnvironmentConfigProvider {
+	/**
+	 * Default environment variable mappings
+	 */
+	private static readonly DEFAULT_MAPPINGS: EnvMapping[] = [
+		{
+			env: 'TASKMASTER_STORAGE_TYPE',
+			path: ['storage', 'type'],
+			validate: (v: string) => ['file', 'api'].includes(v)
+		},
+		{ env: 'TASKMASTER_API_ENDPOINT', path: ['storage', 'apiEndpoint'] },
+		{ env: 'TASKMASTER_API_TOKEN', path: ['storage', 'apiAccessToken'] },
+		{ env: 'TASKMASTER_MODEL_MAIN', path: ['models', 'main'] },
+		{ env: 'TASKMASTER_MODEL_RESEARCH', path: ['models', 'research'] },
+		{ env: 'TASKMASTER_MODEL_FALLBACK', path: ['models', 'fallback'] },
+		{
+			env: 'TASKMASTER_RESPONSE_LANGUAGE',
+			path: ['custom', 'responseLanguage']
+		}
+	];
+
+	/**
+	 * Runtime state mappings (separate from configuration)
+	 */
+	private static readonly RUNTIME_STATE_MAPPINGS: EnvMapping[] = [
+		{ env: 'TASKMASTER_TAG', path: ['activeTag'], isRuntimeState: true }
+	];
+
+	private mappings: EnvMapping[];
+
+	constructor(customMappings?: EnvMapping[]) {
+		this.mappings = customMappings || [
+			...EnvironmentConfigProvider.DEFAULT_MAPPINGS,
+			...EnvironmentConfigProvider.RUNTIME_STATE_MAPPINGS
+		];
+	}
+
+	/**
+	 * Load configuration from environment variables
+	 */
+	loadConfig(): PartialConfiguration {
+		const config: PartialConfiguration = {};
+
+		for (const mapping of this.mappings) {
+			// Skip runtime state variables
+			if (mapping.isRuntimeState) continue;
+
+			const value = process.env[mapping.env];
+			if (!value) continue;
+
+			// Validate value if validator is provided
+			if (mapping.validate && !mapping.validate(value)) {
+				console.warn(`Invalid value for ${mapping.env}: ${value}`);
+				continue;
+			}
+
+			// Set the value in the config object
+			this.setNestedProperty(config, mapping.path, value);
+		}
+
+		return config;
+	}
+
+	/**
+	 * Get runtime state from environment variables
+	 */
+	getRuntimeState(): Record<string, string> {
+		const state: Record<string, string> = {};
+
+		for (const mapping of this.mappings) {
+			if (!mapping.isRuntimeState) continue;
+
+			const value = process.env[mapping.env];
+			if (value) {
+				const key = mapping.path[mapping.path.length - 1];
+				state[key] = value;
+			}
+		}
+
+		return state;
+	}
+
+	/**
+	 * Helper to set a nested property in an object
+	 */
+	private setNestedProperty(
+		obj: any,
+		path: readonly string[],
+		value: any
+	): void {
+		const lastKey = path[path.length - 1];
+		const keys = path.slice(0, -1);
+
+		let current = obj;
+		for (const key of keys) {
+			if (!current[key]) {
+				current[key] = {};
+			}
+			current = current[key];
+		}
+
+		current[lastKey] = value;
+	}
+
+	/**
+	 * Check if an environment variable is set
+	 */
+	hasEnvVar(envName: string): boolean {
+		return envName in process.env && process.env[envName] !== undefined;
+	}
+
+	/**
+	 * Get all environment variables that match our prefix
+	 */
+	getAllTaskmasterEnvVars(): Record<string, string> {
+		const vars: Record<string, string> = {};
+		const prefix = 'TASKMASTER_';
+
+		for (const [key, value] of Object.entries(process.env)) {
+			if (key.startsWith(prefix) && value !== undefined) {
+				vars[key] = value;
+			}
+		}
+
+		return vars;
+	}
+
+	/**
+	 * Add a custom mapping
+	 */
+	addMapping(mapping: EnvMapping): void {
+		this.mappings.push(mapping);
+	}
+
+	/**
+	 * Get current mappings
+	 */
+	getMappings(): EnvMapping[] {
+		return [...this.mappings];
+	}
+}

packages/tm-core/src/config/services/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Configuration services exports
+ * Export all configuration-related services
+ */
+
+export { ConfigLoader } from './config-loader.service.js';
+export {
+	ConfigMerger,
+	CONFIG_PRECEDENCE,
+	type ConfigSource
+} from './config-merger.service.js';
+export {
+	RuntimeStateManager,
+	type RuntimeState
+} from './runtime-state-manager.service.js';
+export {
+	ConfigPersistence,
+	type PersistenceOptions
+} from './config-persistence.service.js';
+export { EnvironmentConfigProvider } from './environment-config-provider.service.js';

packages/tm-core/src/config/services/runtime-state-manager.service.spec.ts

@@ -0,0 +1,272 @@
+/**
+ * @fileoverview Unit tests for RuntimeStateManager service
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import { RuntimeStateManager } from './runtime-state-manager.service.js';
+import { DEFAULT_CONFIG_VALUES } from '../../interfaces/configuration.interface.js';
+
+vi.mock('node:fs', () => ({
+	promises: {
+		readFile: vi.fn(),
+		writeFile: vi.fn(),
+		mkdir: vi.fn(),
+		unlink: vi.fn()
+	}
+}));
+
+describe('RuntimeStateManager', () => {
+	let stateManager: RuntimeStateManager;
+	const testProjectRoot = '/test/project';
+
+	beforeEach(() => {
+		stateManager = new RuntimeStateManager(testProjectRoot);
+		vi.clearAllMocks();
+		// Clear environment variables
+		delete process.env.TASKMASTER_TAG;
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+		delete process.env.TASKMASTER_TAG;
+	});
+
+	describe('loadState', () => {
+		it('should load state from file', async () => {
+			const mockState = {
+				activeTag: 'feature-branch',
+				lastUpdated: '2024-01-01T00:00:00.000Z',
+				metadata: { test: 'data' }
+			};
+
+			vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(mockState));
+
+			const state = await stateManager.loadState();
+
+			expect(fs.readFile).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/state.json',
+				'utf-8'
+			);
+			expect(state.activeTag).toBe('feature-branch');
+			expect(state.metadata).toEqual({ test: 'data' });
+		});
+
+		it('should override with environment variable if set', async () => {
+			const mockState = { activeTag: 'file-tag' };
+			vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(mockState));
+
+			process.env.TASKMASTER_TAG = 'env-tag';
+
+			const state = await stateManager.loadState();
+
+			expect(state.activeTag).toBe('env-tag');
+		});
+
+		it('should use default state when file does not exist', async () => {
+			const error = new Error('File not found') as any;
+			error.code = 'ENOENT';
+			vi.mocked(fs.readFile).mockRejectedValue(error);
+
+			const state = await stateManager.loadState();
+
+			expect(state.activeTag).toBe(DEFAULT_CONFIG_VALUES.TAGS.DEFAULT_TAG);
+		});
+
+		it('should use environment variable when file does not exist', async () => {
+			const error = new Error('File not found') as any;
+			error.code = 'ENOENT';
+			vi.mocked(fs.readFile).mockRejectedValue(error);
+
+			process.env.TASKMASTER_TAG = 'env-tag';
+
+			const state = await stateManager.loadState();
+
+			expect(state.activeTag).toBe('env-tag');
+		});
+
+		it('should handle file read errors gracefully', async () => {
+			vi.mocked(fs.readFile).mockRejectedValue(new Error('Permission denied'));
+
+			const state = await stateManager.loadState();
+
+			expect(state.activeTag).toBe(DEFAULT_CONFIG_VALUES.TAGS.DEFAULT_TAG);
+		});
+
+		it('should handle invalid JSON gracefully', async () => {
+			vi.mocked(fs.readFile).mockResolvedValue('invalid json');
+
+			// Mock console.warn to avoid noise in tests
+			const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+			const state = await stateManager.loadState();
+
+			expect(state.activeTag).toBe(DEFAULT_CONFIG_VALUES.TAGS.DEFAULT_TAG);
+			expect(warnSpy).toHaveBeenCalled();
+
+			warnSpy.mockRestore();
+		});
+	});
+
+	describe('saveState', () => {
+		it('should save state to file with timestamp', async () => {
+			vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+			// Set a specific state
+			await stateManager.setActiveTag('test-tag');
+
+			// Verify mkdir was called
+			expect(fs.mkdir).toHaveBeenCalledWith('/test/project/.taskmaster', {
+				recursive: true
+			});
+
+			// Verify writeFile was called with correct data
+			expect(fs.writeFile).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/state.json',
+				expect.stringContaining('"activeTag":"test-tag"'),
+				'utf-8'
+			);
+
+			// Verify timestamp is included
+			expect(fs.writeFile).toHaveBeenCalledWith(
+				expect.any(String),
+				expect.stringContaining('"lastUpdated"'),
+				'utf-8'
+			);
+		});
+
+		it('should throw TaskMasterError on save failure', async () => {
+			vi.mocked(fs.mkdir).mockRejectedValue(new Error('Disk full'));
+
+			await expect(stateManager.saveState()).rejects.toThrow(
+				'Failed to save runtime state'
+			);
+		});
+
+		it('should format JSON with proper indentation', async () => {
+			vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+			await stateManager.saveState();
+
+			const writeCall = vi.mocked(fs.writeFile).mock.calls[0];
+			const jsonContent = writeCall[1] as string;
+
+			// Check for 2-space indentation
+			expect(jsonContent).toMatch(/\n  /);
+		});
+	});
+
+	describe('getActiveTag', () => {
+		it('should return current active tag', () => {
+			const tag = stateManager.getActiveTag();
+			expect(tag).toBe(DEFAULT_CONFIG_VALUES.TAGS.DEFAULT_TAG);
+		});
+
+		it('should return updated tag after setActiveTag', async () => {
+			vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+			await stateManager.setActiveTag('new-tag');
+
+			expect(stateManager.getActiveTag()).toBe('new-tag');
+		});
+	});
+
+	describe('setActiveTag', () => {
+		it('should update active tag and save state', async () => {
+			vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+			await stateManager.setActiveTag('feature-xyz');
+
+			expect(stateManager.getActiveTag()).toBe('feature-xyz');
+			expect(fs.writeFile).toHaveBeenCalled();
+		});
+	});
+
+	describe('getState', () => {
+		it('should return copy of current state', () => {
+			const state1 = stateManager.getState();
+			const state2 = stateManager.getState();
+
+			expect(state1).not.toBe(state2); // Different instances
+			expect(state1).toEqual(state2); // Same content
+			expect(state1.activeTag).toBe(DEFAULT_CONFIG_VALUES.TAGS.DEFAULT_TAG);
+		});
+	});
+
+	describe('updateMetadata', () => {
+		it('should update metadata and save state', async () => {
+			vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+			await stateManager.updateMetadata({ key1: 'value1' });
+
+			const state = stateManager.getState();
+			expect(state.metadata).toEqual({ key1: 'value1' });
+			expect(fs.writeFile).toHaveBeenCalled();
+		});
+
+		it('should merge metadata with existing values', async () => {
+			vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+			await stateManager.updateMetadata({ key1: 'value1' });
+			await stateManager.updateMetadata({ key2: 'value2' });
+
+			const state = stateManager.getState();
+			expect(state.metadata).toEqual({
+				key1: 'value1',
+				key2: 'value2'
+			});
+		});
+
+		it('should override existing metadata values', async () => {
+			vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+			vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+			await stateManager.updateMetadata({ key1: 'value1' });
+			await stateManager.updateMetadata({ key1: 'value2' });
+
+			const state = stateManager.getState();
+			expect(state.metadata).toEqual({ key1: 'value2' });
+		});
+	});
+
+	describe('clearState', () => {
+		it('should delete state file and reset to defaults', async () => {
+			vi.mocked(fs.unlink).mockResolvedValue(undefined);
+
+			await stateManager.clearState();
+
+			expect(fs.unlink).toHaveBeenCalledWith(
+				'/test/project/.taskmaster/state.json'
+			);
+			expect(stateManager.getActiveTag()).toBe(
+				DEFAULT_CONFIG_VALUES.TAGS.DEFAULT_TAG
+			);
+			expect(stateManager.getState().metadata).toBeUndefined();
+		});
+
+		it('should ignore ENOENT errors when file does not exist', async () => {
+			const error = new Error('File not found') as any;
+			error.code = 'ENOENT';
+			vi.mocked(fs.unlink).mockRejectedValue(error);
+
+			await expect(stateManager.clearState()).resolves.not.toThrow();
+			expect(stateManager.getActiveTag()).toBe(
+				DEFAULT_CONFIG_VALUES.TAGS.DEFAULT_TAG
+			);
+		});
+
+		it('should throw other errors', async () => {
+			vi.mocked(fs.unlink).mockRejectedValue(new Error('Permission denied'));
+
+			await expect(stateManager.clearState()).rejects.toThrow(
+				'Permission denied'
+			);
+		});
+	});
+});

packages/tm-core/src/config/services/runtime-state-manager.service.ts

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview Runtime State Manager Service
+ * Manages runtime state separate from configuration
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import {
+	ERROR_CODES,
+	TaskMasterError
+} from '../../errors/task-master-error.js';
+import { DEFAULT_CONFIG_VALUES } from '../../interfaces/configuration.interface.js';
+
+/**
+ * Runtime state data structure
+ */
+export interface RuntimeState {
+	/** Currently active tag */
+	currentTag: string;
+	/** Last updated timestamp */
+	lastUpdated?: string;
+	/** Additional metadata */
+	metadata?: Record<string, unknown>;
+}
+
+/**
+ * RuntimeStateManager handles runtime state persistence
+ * Single responsibility: Runtime state management (separate from config)
+ */
+export class RuntimeStateManager {
+	private stateFilePath: string;
+	private currentState: RuntimeState;
+
+	constructor(projectRoot: string) {
+		this.stateFilePath = path.join(projectRoot, '.taskmaster', 'state.json');
+		this.currentState = {
+			currentTag: DEFAULT_CONFIG_VALUES.TAGS.DEFAULT_TAG
+		};
+	}
+
+	/**
+	 * Load runtime state from disk
+	 */
+	async loadState(): Promise<RuntimeState> {
+		try {
+			const stateData = await fs.readFile(this.stateFilePath, 'utf-8');
+			const rawState = JSON.parse(stateData);
+
+			// Map legacy field names to current interface
+			const state: RuntimeState = {
+				currentTag:
+					rawState.currentTag ||
+					rawState.activeTag ||
+					DEFAULT_CONFIG_VALUES.TAGS.DEFAULT_TAG,
+				lastUpdated: rawState.lastUpdated,
+				metadata: rawState.metadata
+			};
+
+			// Apply environment variable override for current tag
+			if (process.env.TASKMASTER_TAG) {
+				state.currentTag = process.env.TASKMASTER_TAG;
+			}
+
+			this.currentState = state;
+			return state;
+		} catch (error: any) {
+			if (error.code === 'ENOENT') {
+				// State file doesn't exist, use defaults
+				console.debug('No state.json found, using default state');
+
+				// Check environment variable
+				if (process.env.TASKMASTER_TAG) {
+					this.currentState.currentTag = process.env.TASKMASTER_TAG;
+				}
+
+				return this.currentState;
+			}
+
+			console.warn('Failed to load state file:', error.message);
+			return this.currentState;
+		}
+	}
+
+	/**
+	 * Save runtime state to disk
+	 */
+	async saveState(): Promise<void> {
+		const stateDir = path.dirname(this.stateFilePath);
+
+		try {
+			await fs.mkdir(stateDir, { recursive: true });
+
+			const stateToSave = {
+				...this.currentState,
+				lastUpdated: new Date().toISOString()
+			};
+
+			await fs.writeFile(
+				this.stateFilePath,
+				JSON.stringify(stateToSave, null, 2),
+				'utf-8'
+			);
+		} catch (error) {
+			throw new TaskMasterError(
+				'Failed to save runtime state',
+				ERROR_CODES.CONFIG_ERROR,
+				{ statePath: this.stateFilePath },
+				error as Error
+			);
+		}
+	}
+
+	/**
+	 * Get the currently active tag
+	 */
+	getCurrentTag(): string {
+		return this.currentState.currentTag;
+	}
+
+	/**
+	 * Set the current tag
+	 */
+	async setCurrentTag(tag: string): Promise<void> {
+		this.currentState.currentTag = tag;
+		await this.saveState();
+	}
+
+	/**
+	 * Get current state
+	 */
+	getState(): RuntimeState {
+		return { ...this.currentState };
+	}
+
+	/**
+	 * Update metadata
+	 */
+	async updateMetadata(metadata: Record<string, unknown>): Promise<void> {
+		this.currentState.metadata = {
+			...this.currentState.metadata,
+			...metadata
+		};
+		await this.saveState();
+	}
+
+	/**
+	 * Clear state file
+	 */
+	async clearState(): Promise<void> {
+		try {
+			await fs.unlink(this.stateFilePath);
+		} catch (error: any) {
+			if (error.code !== 'ENOENT') {
+				throw error;
+			}
+		}
+		this.currentState = {
+			currentTag: DEFAULT_CONFIG_VALUES.TAGS.DEFAULT_TAG
+		};
+	}
+}

packages/tm-core/src/constants/index.ts

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Constants for Task Master Core
+ * Single source of truth for all constant values
+ */
+
+import type {
+	TaskStatus,
+	TaskPriority,
+	TaskComplexity
+} from '../types/index.js';
+
+/**
+ * Valid task status values
+ */
+export const TASK_STATUSES: readonly TaskStatus[] = [
+	'pending',
+	'in-progress',
+	'done',
+	'deferred',
+	'cancelled',
+	'blocked',
+	'review'
+] as const;
+
+/**
+ * Valid task priority values
+ */
+export const TASK_PRIORITIES: readonly TaskPriority[] = [
+	'low',
+	'medium',
+	'high',
+	'critical'
+] as const;
+
+/**
+ * Valid task complexity values
+ */
+export const TASK_COMPLEXITIES: readonly TaskComplexity[] = [
+	'simple',
+	'moderate',
+	'complex',
+	'very-complex'
+] as const;
+
+/**
+ * Valid output formats for task display
+ */
+export const OUTPUT_FORMATS = ['text', 'json', 'compact'] as const;
+export type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+
+/**
+ * Status icons for display
+ */
+export const STATUS_ICONS: Record<TaskStatus, string> = {
+	done: '✓',
+	completed: '✓',
+	'in-progress': '►',
+	blocked: '⭕',
+	pending: '○',
+	deferred: '⏸',
+	cancelled: '✗',
+	review: '👁'
+} as const;
+
+/**
+ * Status colors for display (using chalk color names)
+ */
+export const STATUS_COLORS: Record<TaskStatus, string> = {
+	pending: 'yellow',
+	'in-progress': 'blue',
+	done: 'green',
+	deferred: 'gray',
+	cancelled: 'red',
+	blocked: 'magenta',
+	review: 'cyan',
+	completed: 'green'
+} as const;