id: task-105 title: Remove dot from .backlog folder name status: Done assignee: [] created_date: '2025-07-03' updated_date: '2025-07-06' labels: [] dependencies: []

Description

Currently tasks are stored in .backlog directory which is hidden. This causes issues with file referencing (e.g., Claude's @ tool) and user interaction outside the CLI. Remove the dot to make it a visible 'backlog' folder.

Migration Strategy: Make the backlog directory configurable with 'backlog' as the new default. For backward compatibility, existing installations without the backlogDirectory config field will automatically default to '.backlog' to preserve existing folder structures. Users can manually migrate by renaming their folder and updating their config.

Acceptance Criteria

• [x] Folder renamed from .backlog to backlog (now configurable with 'backlog' as default)
• [x] All documentation files updated to reference 'backlog' instead of '.backlog'
• [x] All test files updated to use 'backlog' instead of '.backlog'
• [x] All source code references updated from '.backlog' to 'backlog'
• [x] All functionality works correctly after the change
• [x] Made configurable via backlog_directory setting in config.yml
• [x] Backward compatibility maintained through configuration
• [x] Migration logic: configs without backlogDirectory field default to '.backlog' for backward compatibility
• [x] New installations use 'backlog' as default directory name
• [x] Users can manually migrate by renaming folder and updating config

Implementation Notes

Approach taken:

• Made the backlog directory configurable through a new backlogDirectory field in BacklogConfig
• Changed the default from ".backlog" to "backlog" in constants
• Implemented automatic migration logic to detect legacy configs and set them to use ".backlog"
• Updated all hardcoded references throughout the codebase to use the configurable directory

Features implemented:

• Configurable backlog directory via backlog_directory setting in config.yml
• Automatic backward compatibility migration that writes missing config field
• Updated FileSystem class to use async directory getters based on config
• Updated GitOperations to accept configurable directory parameter
• Updated CLI and core classes to use configurable directory paths

Technical decisions and trade-offs:

• Simple migration approach: Instead of complex folder detection, we simply auto-add backlogDirectory: ".backlog" to configs missing this field. This is much cleaner and avoids runtime fallbacks.
• Explicit config updates: The migration writes the config field permanently rather than using runtime defaults, ensuring clarity.
• Manual user migration: Users who want the new visible folder must manually rename and update config, giving them full control.

Modified files:

• src/types/index.ts: Added backlogDirectory field to BacklogConfig interface
• src/constants/index.ts: Changed DEFAULT_DIRECTORIES.BACKLOG from ".backlog" to "backlog"
• src/file-system/operations.ts: Added configurable directory logic and migration
• src/core/backlog.ts: Updated to use configurable directory for git operations
• src/git/operations.ts: Made stageBacklogDirectory accept directory parameter
• src/cli.ts: Updated to use configurable directory for remote task loading
• src/core/cross-branch-tasks.ts: Updated to use configurable directory paths
• src/core/remote-tasks.ts: Updated to use configurable directory paths
• All test files: Updated to use new "backlog" default
• All documentation files: Updated references from ".backlog" to "backlog"