fix: prevent CLAUDE.md overwrite by using imports

[ben-vargas]

Summary

This PR fixes the issue where Task Master overwrites users' existing CLAUDE.md files by implementing a non-destructive approach using Claude Code's import feature.

Fixes #929

Changes

• Task Master now creates its instructions in .taskmaster/CLAUDE.md instead of overwriting the user's CLAUDE.md
• Adds an import section with clear instructions to the user's CLAUDE.md that references the Task Master instructions
• Preserves existing user content in CLAUDE.md files
• Removed duplicate profile initialization that was causing files to be written twice

Breaking Change

Task Master instructions for Claude Code are now stored in .taskmaster/CLAUDE.md and imported into the main CLAUDE.md file. Users who previously had Task Master content directly in their CLAUDE.md will need to run:

task-master rules remove claude
task-master rules add claude

to migrate to the new structure.

Example

When running task-master rules add claude, the user's existing CLAUDE.md:

# My Project Guidelines

- Use TypeScript
- Follow team conventions

Will be updated to:

# My Project Guidelines

- Use TypeScript
- Follow team conventions

## Task Master AI Instructions
**Import Task Master's development workflow commands and guidelines, treat as if import is in the main CLAUDE.md file.**
@./.taskmaster/CLAUDE.md

And Task Master's instructions will be placed in .taskmaster/CLAUDE.md.

Test Plan

• Updated tests to verify new behavior
• All tests pass
• Code formatted with Biome
• Changeset included

[changeset-bot]

🦋 Changeset detected

Latest commit: 121cd7a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
task-master-ai	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Crunchyman-ralph]

small questions, but essentially great PR, lets merge

[Crunchyman-ralph]

Don't prefix with Fix, if its a fix, just change from minor to patch on line 2 of this file

[ben-vargas]

Done.. "unfixed" 😂

[Crunchyman-ralph]

nice

[Crunchyman-ralph]

why remove this ? just curious

[ben-vargas]

Discussed on discord, but just for documentation sake...

o3 confirmation/explanation -

Yes – the extra block in scripts/modules/commands.js is really doing the same work a second time, and that is what makes CLAUDE.md (and the other profile “integration-guide” files) get copied twice.

Why it happens

1. convertAllRulesToProfileRules(projectRoot, profileConfig)
   • For every profile it ends by calling the profile’s onPostConvertRulesProfile.
   • Every profile implements onPostConvertRulesProfile as a thin wrapper that just calls onAddRulesProfile.
   • So, after this single call, the file copy (e.g. AGENTS.md → CLAUDE.md) has already happened once.

2. Immediately afterwards, lines 4019-4023 call onAddRulesProfile again:

if (typeof profileConfig.onAddRulesProfile === 'function') {
  const assetsDir = path.join(projectRoot, 'assets');   // <-- wrong path, too
  profileConfig.onAddRulesProfile(projectRoot, assetsDir);
}

That means:

• For “simple” profiles (claude, codex, etc.) the copy runs twice – once with the correct package-internal assets directory (step 1) and again with <projectRoot>/assets, which usually doesn’t exist and can create a spurious empty folder.
• For the bigger profiles (roo, windsurf, …) you also get the duplicate execution, potentially copying the same files twice.

What the block was probably meant for
Before convertAllRulesToProfileRules grew the “post-convert” hook, CLI code had to call onAddRulesProfile itself. After the refactor, the explicit call became obsolete but was never removed.

Will removing it break “re-setup” use-cases?
No. Users re-run the copy via either

task-master rules add <profile>
# or
task-master rules --setup           (interactive)

Both paths already invoke convertAllRulesToProfileRules, which in turn fires onPostConvertRulesProfile → onAddRulesProfile. Taking out the duplicate call does not stop a user from restoring the integration file; it only prevents the second, redundant invocation (and the wrong-directory copy).

So the change Claude suggested – deleting lines 4020-4023 – is correct and safe:

- if (typeof profileConfig.onAddRulesProfile === 'function') {
-   const assetsDir = path.join(projectRoot, 'assets');
-   profileConfig.onAddRulesProfile(projectRoot, assetsDir);
- }

After this removal:

• CLAUDE.md (or the equivalent guide file for other profiles) is created exactly once.
• The assets directory path remains correct (<package>/assets/...).
• All existing CLI commands for adding / re-adding profiles continue to work.

[joedanz]

I concur. These lines are duplicative and can be removed. Tested on my end.

[vedovelli]

Hi! 👋 Do we have this solution implemented by another PR? This enhancement is a very welcome one!

[ben-vargas]

@vedovelli - See #949 - It was ready but wasn't merged in 0.20.0 but it has since been merged into next branch and I would expect the solution to be released in 0.21.

[vedovelli]

@vedovelli - See #949 - It was ready but wasn't merged in 0.20.0 but it has since been merged into next branch and I would expect the solution to be released in 0.21.

Thank you for your reply! I keep my TM always updated so this enhancement should reach me soon enough! Have a great weekend.