---
id: BACK-87
title: Make agent guideline file updates idempotent during init
status: Done
assignee:
  - '@claude'
created_date: '2025-06-19'
updated_date: '2025-06-20'
labels:
  - enhancement
  - cli
  - init
dependencies: []
---

## Description

Currently, when running `backlog init` and selecting agent guideline files (CLAUDE.md, AGENTS.md, .cursorrules), the system should append Backlog.md-specific instructions to existing files. However, if init is run multiple times, content may be duplicated. We need to make this process idempotent - ensuring that the Backlog.md guidelines are only added once, regardless of how many times init is executed.

## Acceptance Criteria

- [x] Running `backlog init` multiple times does not duplicate agent guideline content
- [x] Existing agent guideline files are preserved with Backlog.md content appended at the bottom
- [x] If Backlog.md content already exists in the file, it is not added again
- [x] Each agent file type has a unique marker/identifier to detect existing Backlog.md content
- [x] New files are created normally if they don't exist
- [x] The appended content includes clear section headers indicating it's from Backlog.md
- [x] All three agent file types (.cursorrules, CLAUDE.md, AGENTS.md) handle idempotency correctly
- [x] No data loss occurs when updating existing files

## Implementation Plan

1. **Add Content Markers**
   - Define unique markers/comments for each file type to identify Backlog.md sections
   - Examples: `<!-- BACKLOG.MD GUIDELINES START -->` and `<!-- BACKLOG.MD GUIDELINES END -->`

2. **Implement Detection Logic**
   - Check if files exist before writing
   - Read existing content and search for Backlog.md markers
   - Skip appending if markers are found

3. **Update Append Logic**
   - Wrap Backlog.md content with markers
   - Ensure proper newlines/spacing when appending
   - Preserve existing file content

4. **Test Scenarios**
   - Test with non-existent files
   - Test with existing files without Backlog.md content
   - Test with files already containing Backlog.md content
   - Test running init multiple times in succession

## Implementation Notes

*Created by @claude on 2025-06-20*

### Approach Taken

The solution implements idempotent behavior for agent guideline file updates by using unique markers to identify existing Backlog.md content. The implementation follows these key principles:

1. **Content Markers**: Added different marker types based on file format:
   - For markdown files (CLAUDE.md, AGENTS.md, README.md): HTML comments `<!-- BACKLOG.MD GUIDELINES START/END -->`
   - For .cursorrules: Markdown-style comments `# === BACKLOG.MD GUIDELINES START/END ===`

2. **Detection Logic**: Before appending content, the system checks if the start marker already exists in the file
3. **Idempotent Updates**: If markers are found, the file is skipped entirely to prevent duplication
4. **Content Wrapping**: All Backlog.md guidelines are now wrapped with appropriate markers when added

### Technical Decisions and Trade-offs

- **Marker Strategy**: Used different comment styles for different file types since .cursorrules doesn't support HTML comments
- **Skip vs Replace**: Chose to skip files with existing markers rather than replace content to avoid potentially overwriting user modifications between markers
- **Simple Detection**: Used basic string matching rather than more complex parsing for simplicity and performance
- **Backward Compatibility**: Existing files without markers will get markers added on first run, but won't break existing functionality

### Files Modified

1. **`/Users/agavr/projects/Backlog.md/src/agent-instructions.ts`**:
   - Added `getMarkers()` function to determine appropriate markers for each file type
   - Added `hasBacklogGuidelines()` function to check for existing markers
   - Added `wrapWithMarkers()` function to wrap content with appropriate markers
   - Modified `addAgentInstructions()` function to implement idempotent behavior
   - Preserved Windows compatibility with synchronous file reading

2. **`/Users/agavr/projects/Backlog.md/src/test/agent-instructions.test.ts`**:
   - Added comprehensive tests for idempotent behavior
   - Added tests for different file type marker handling
   - Updated existing tests to account for wrapped content format
   - Tests verify no content duplication when run multiple times

### Testing Results

All new tests pass, including:
- Idempotent behavior when running multiple times
- Proper marker insertion for different file types  
- Preservation of existing content
- No data loss during updates
- Correct handling of non-existent files

### Follow-up Tasks

No immediate follow-up tasks required. The implementation fully satisfies all acceptance criteria and maintains backward compatibility.
