[FEATURE] Add plansDir Setting for Project-Local Plan Documents

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

What problem are you trying to solve?

When working on large features that require multi-phase planning, I need to create hierarchical plan documents (main plan → phase 1 plan, phase 2 plan, etc.) that stay with the project and can be version-controlled alongside the code.

Current Workflow Issue:

1. I enter plan mode to create a multi-phase plan for a complex feature
2. I ask Claude: "Create a plan document for Phase 1"
3. Claude creates the document in the global plans directory (plan mode's default behavior)
4. I actually wanted it in my project's .claude/plans/ directory
5. Claude gets confused because my request mentioned the project but plan mode created it globally
6. Claude then creates a DUPLICATE file in the project directory
7. Result: Wasted context tokens handling the confusion + duplicate files in two locations

Real Example:

User: "Create Phase 1 plan in the project"
Claude: [Creates in global ~/.claude/plans/] "Done!"
User: "No, I meant in THIS project's directory"
Claude: "Oh sorry!" [Creates duplicate, wastes 1000+ tokens on confusion]

Why do you need this feature?

Multi-Phase Planning Workflow:

• Large features need a main plan document
• From the main plan, I break down into phase-specific plans (Phase 1: Database, Phase 2: API, Phase 3: UI)
• These plans need to live with the code in version control
• I need to reference these plans across different Claude Code sessions
• Team members need access to the same plans when working on the project

The Core Problem:
Plan mode defaults to global storage, but the natural place for project-specific plans is in the project directory. This mismatch causes confusion and wastes context on manual file management instead of actual development work.

Proposed Solution

How would you like this to work?

Add a simple plansDir configuration option in .claude/settings.json:

{
  "plansDir": ".claude/plans"
}

Ideal User Experience

Configuration:

1. I add "plansDir": ".claude/plans" to my project's .claude/settings.json
2. That's it - no other setup needed

Behavior:
When I'm in plan mode and create plan documents, they are automatically created in .claude/plans/ within my project directory instead of the global location.

Example Workflow:

User: "Create main plan for subscription system"
Claude: Creates .claude/plans/subscription-main.md ✓

User: "Create plan for Phase 1: Database"
Claude: Creates .claude/plans/subscription-phase-1.md ✓

User: "Create plan for Phase 2: Payment"
Claude: Creates .claude/plans/subscription-phase-2.md ✓

Project Structure:

my-flutter-project/
├── .claude/
│   ├── plans/
│   │   ├── subscription-main.md
│   │   ├── subscription-phase-1.md
│   │   └── subscription-phase-2.md
│   └── settings.json          # Contains "plansDir": ".claude/plans"
├── lib/
└── README.md

Benefits:

• ✅ Plans go exactly where I expect them
• ✅ No confusion, no duplicates
• ✅ No wasted context on "move this file here" conversations
• ✅ Plans are version-controlled with git
• ✅ Team members see the same plans
• ✅ Clean hierarchical organization (main → phases)

Implementation Notes

• Default behavior: If plansDir is not specified, continue using global directory (backward compatible)
• Relative paths: Resolve relative to the workspace root
• Auto-create: Create the directory if it doesn't exist
• Everything else stays the same: No changes to plan mode functionality, just where files are created

Alternative Solutions

1. Manual file copying after creation

• Problem: This is what happens now when there's confusion - Claude creates a duplicate
• Why it doesn't work: Wastes significant context tokens on file operations instead of planning/development

2. Not using plan mode for phase plans

• Problem: Just create regular markdown files manually
• Why it doesn't work: Loses all the benefits of plan mode's structured planning workflow and tooling integration

3. Manually moving files from global directory to project

• Problem: After plan mode creates files globally, manually move them to the project
• Why it doesn't work: Extra manual steps, easy to forget, files get out of sync

4. Creating project directory structure outside of Claude

• Problem: Create .claude/plans/ structure manually and ask Claude to use it
• Why it doesn't work: Claude defaults to global plans directory anyway, leading to the same confusion

Current Workaround

I have a .claude/plans/ directory in my project, but when I ask Claude to create phase-specific plan documents during plan mode, it creates them in the global directory. This causes confusion and duplicate files, wasting context tokens that should be spent on actual planning and development.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

Concrete Real-World Scenario: Implementing a Subscription System

Context: I'm building a subscription management feature for a Flutter business application. This is a large, multi-phase feature that will take several weeks and multiple Claude Code sessions.

Step-by-Step Workflow:

Day 1 - Initial Planning

1. I configure my project: Add "plansDir": ".claude/plans" to .claude/settings.json
2. I start a Claude Code session and enter plan mode
3. I say: "Create a main plan for implementing a subscription system with RevenueCat integration"
4. Claude creates .claude/plans/subscription-system-main.md with the overall architecture and phases:

• Phase 1: Database schema and models
• Phase 2: RevenueCat SDK integration and entitlements
• Phase 3: UI components and admin dashboard
• Phase 4: Testing and finalization

1. I commit this plan to git: git add .claude/plans/ && git commit -m "Add subscription system plan"

Day 2 - Phase 1 Deep Dive

1. New Claude Code session, I enter plan mode again
2. I say: "Create a detailed plan for Phase 1: Database schema and models"
3. Claude creates .claude/plans/subscription-phase-1-database.md with:

• Specific table structures
• Model relationships
• Migration strategy
• DAO implementations

1. I reference both the main plan and Phase 1 plan while implementing
2. Commit: git add .claude/plans/ && git commit -m "Add Phase 1 detailed plan"

Day 5 - Team Collaboration

1. My teammate pulls the latest code
2. They see both plan documents in .claude/plans/
3. They open a PR suggesting improvements to Phase 2 approach
4. They modify .claude/plans/subscription-phase-2-revenuecat.md with alternative webhook handling for purchase events
5. We discuss the plan changes in PR review before writing any code

Week 2 - Continuing Development

1. I start a new Claude Code session after a week break
2. I open .claude/plans/subscription-system-main.md to see overall progress
3. I check .claude/plans/subscription-phase-1-database.md - already implemented ✓
4. I start Phase 2, referencing .claude/plans/subscription-phase-2-revenuecat.md
5. Claude creates .claude/plans/subscription-phase-3-ui.md for the next phase

Benefits Demonstrated:

• ✅ All plans stay with the project across sessions
• ✅ Team can collaborate on planning through git
• ✅ Clear hierarchical structure (main → phases)
• ✅ No confusion about where files are located
• ✅ Plans evolve with the codebase in version control
• ✅ Easy to reference previous decisions

Without this feature:

• Plans would be in a global directory somewhere on my machine
• Teammate wouldn't see my plans
• I'd forget what I planned after a week break
• Claude would create duplicate files when I ask for "project plans"
• No git history of planning decisions

Additional Context

• Current Claude Code version: 2.0.70 (Claude Code)
• This would be consistent with existing project-local directories: .claude/skills/, .claude/agents/
• Simple feature with clear benefits: reduce confusion, save context, improve version control