chore: refactor tm-core to host more of our "core" commands (#1331)

CLAUDE.md

@@ -33,6 +33,48 @@
   });
   ```
 
+## Architecture Guidelines
+
+### Business Logic Separation
+
+**CRITICAL RULE**: ALL business logic must live in `@tm/core`, NOT in presentation layers.
+
+- **`@tm/core`** (packages/tm-core/):
+  - Contains ALL business logic, domain models, services, and utilities
+  - Provides clean facade APIs through domain objects (tasks, auth, workflow, git, config)
+  - Houses all complexity - parsing, validation, transformations, calculations, etc.
+  - Example: Task ID parsing, subtask extraction, status validation, dependency resolution
+
+- **`@tm/cli`** (apps/cli/):
+  - Thin presentation layer ONLY
+  - Calls tm-core methods and displays results
+  - Handles CLI-specific concerns: argument parsing, output formatting, user prompts
+  - NO business logic, NO data transformations, NO calculations
+
+- **`@tm/mcp`** (apps/mcp/):
+  - Thin presentation layer ONLY
+  - Calls tm-core methods and returns MCP-formatted responses
+  - Handles MCP-specific concerns: tool schemas, parameter validation, response formatting
+  - NO business logic, NO data transformations, NO calculations
+
+- **`apps/extension`** (future):
+  - Thin presentation layer ONLY
+  - Calls tm-core methods and displays in VS Code UI
+  - NO business logic
+
+**Examples of violations to avoid:**
+
+- ❌ Creating helper functions in CLI/MCP to parse task IDs → Move to tm-core
+- ❌ Data transformation logic in CLI/MCP → Move to tm-core
+- ❌ Validation logic in CLI/MCP → Move to tm-core
+- ❌ Duplicating logic across CLI and MCP → Implement once in tm-core
+
+**Correct approach:**
+- ✅ Add method to TasksDomain: `tasks.get(taskId)` (automatically handles task and subtask IDs)
+- ✅ CLI calls: `await tmCore.tasks.get(taskId)` (supports "1", "1.2", "HAM-123", "HAM-123.2")
+- ✅ MCP calls: `await tmCore.tasks.get(taskId)` (same intelligent ID parsing)
+- ✅ Single source of truth in tm-core
+
 ## Documentation Guidelines
 
 - **Documentation location**: Write docs in `apps/docs/` (Mintlify site source), not `docs/`