TeamB

id: task-93 title: Fix Windows agent instructions file reading hang status: Done assignee:

'@claude' created_date: '2025-06-19' updated_date: '2025-06-19' labels: [] dependencies: []

Description

When running backlog init on Windows from a globally installed package, the agent instructions selection hangs when trying to read existing files with Bun.file().text(). The issue occurs when checking if files already exist to determine whether to append or create new files.

Acceptance Criteria

[x] File reading doesn't hang on Windows when selecting agent instructions
[x] Agent instruction files are created/appended correctly on Windows
[x] Existing functionality works on all platforms
[x] Tests pass on all platforms

Implementation Plan

Identify that Bun.file().text() hangs on Windows when reading existing files
Add existsSync() check before attempting to read files
Implement platform-specific fallback using readFileSync on Windows
Add error handling and logging
Test the solution
Ensure all tests pass

Implementation Notes

The issue was that Bun.file(filePath).text() was hanging on Windows when the backlog executable was run from a globally installed package. The embedded guideline files worked fine - the problem was specifically when checking if existing files needed to be appended versus created.

Key changes made:

Added existsSync() check before attempting to read files to prevent hanging
Implemented platform-specific fallback: on Windows, use synchronous readFileSync() instead of Bun.file().text()
Added better error handling with logging to help debug future issues
Modified src/agent-instructions.ts to handle Windows file operations differently
Added type declaration for markdown imports in src/types/markdown.d.ts

Files modified:

src/agent-instructions.ts - Added Windows-specific file reading logic
src/types/markdown.d.ts - Added type declarations for .md imports
package.json - Cleaned up build script

All tests pass and the functionality has been verified to work correctly on all platforms.