Fixes#1550
This PR addresses the documentation chaos reported in issue #1550 by:
1. Creating a comprehensive Claude Code setup guide at apps/docs/integrations/claude-code.mdx that:
- Clearly explains all 3 integration options (MCP Server, Plugin, Provider)
- Includes a comparison table to help users choose the right option
- Clarifies the naming confusion between task-master-ai (MCP package) and task-master (CLI)
- Provides comprehensive troubleshooting for common issues
2. Simplifying README.md:
- Consolidated duplicate Claude Code installation sections
- Added prominent links to the comprehensive guide
- Reduced confusion by pointing to single source of truth
3. Updating documentation navigation:
- Added new 'Integrations' section to docs.json
- Made Claude Code guide easily discoverable
4. Deprecating redundant documentation:
- Added deprecation notices to docs/claude-code-integration.md
- Added deprecation notices to docs/examples/claude-code-usage.md
- Both files now point to the new consolidated guide
5. Adding context to existing files:
- Explained CLAUDE.md auto-load purpose
- Clarified CLAUDE_CODE_PLUGIN.md is for plugin users
- Added setup guide link to TM_COMMANDS_GUIDE.md
This creates a single landing page (docs.task-master.dev/integrations/claude-code)
that new users can reference, eliminating the confusion from multiple
installation methods scattered across 5+ different files.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Ralph Khreish <Crunchyman-ralph@users.noreply.github.com>
CHANGES:
- Rename forcePrompt option to forceSelection in EnsureOrgOptions interface
- Update all call sites in export.command.ts and commands.js
- Fix AuthManager type in export.command.ts by importing from @tm/core
- Replace dirty (this.taskMasterCore.auth as any).authManager hack with AuthManager.getInstance()
- Use type import for AuthManager in org-selection.ts
CHANGES:
- Add forcePrompt option to ensureOrgSelected utility
- When forcePrompt=true, always fetch orgs and prompt (if >1 org exists)
- Pre-select current org in dropdown when forcePrompt is used
- Show '(current)' label next to currently selected org in prompt
PARSE-PRD:
- Force org selection after authentication (forcePrompt: true)
- User can choose which org to create the brief in
- Auto-selects if only one org available
EXPORT:
- Force org selection after tag selection (forcePrompt: true)
- User can choose which org to export to
- Auto-selects if only one org available
INIT:
- Removed process.exit(0) hack that was incorrectly added
This ensures users explicitly choose (or confirm) their target organization
before creating briefs, preventing accidental exports to wrong orgs.
CHANGES:
- Add ensureOrgSelected to auth-guard.ts for all auth flows (existing & new sessions)
- Add ensureOrgSelected to parse-prd flow in commands.js (after authentication) -- NOT WORKING.
- Add ensureOrgSelected to init.js cloud storage flow (using shared utility)
- Remove duplicate 'Authentication successful!' boxen messages (auth.command.ts, auth-guard.ts)
- Export authenticateWithBrowserMFA and ensureOrgSelected from @tm/cli utils
- init.js now uses shared authenticateWithBrowserMFA instead of custom OAuth flow
- auth-guard.ts now checks context.orgId before making API calls (optimization)
FIXES:
- Org selection now happens after login in parse-prd, init, and export commands
- Single source of truth for browser auth with MFA support
- Removed redundant auth UI code from init.js
KNOWN ISSUES:
- tm init and tm export may hang after completion (Supabase auto-refresh timer)
- Root cause: AuthManager/Supabase client keeps event loop alive
- tm auth login works because it uses setupContextInteractive from ContextCommand
- Proper fix would be to add cleanup method to SupabaseAuthClient to stop auto-refresh
- Workaround (process.exit) was attempted but reverted as too dirty
The hanging issue requires further investigation into how auth login handles
cleanup vs how ensureAuthenticated/ensureOrgSelected interact with Supabase.
- Create shared authenticateWithBrowserMFA utility in auth-ui.ts
- Update auth.command.ts to use shared utility for tm auth login
- Update auth-guard.ts to use shared utility for parse-prd/export
- Fix oauth-service.ts to NOT call onError for MFA_REQUIRED
(MFA requirement is a continuation, not a failure)
All login paths now use the same MFA-aware browser auth flow:
- tm auth login
- tm parse-prd (Bring it to Hamster)
- tm export
