feat: add .gitkeep files to preserve empty directories (#269)

openspec/changes/add-gitkeep-empty-folders/proposal.md

@@ -0,0 +1,31 @@
+# Add .gitkeep Files to Empty Folders
+
+## Why
+
+Git does not track empty directories. When `openspec init` creates the directory structure with empty `specs/`, `changes/`, and `changes/archive/` folders, these directories disappear after a commit if no files exist in them.
+
+This causes workflow issues:
+- After cloning a fresh repository, running `openspec list` fails because the expected directories don't exist
+- New team members encounter errors when trying to use OpenSpec commands
+- Users must manually recreate directories or remember to add placeholder files
+
+## What Changes
+
+Modify the `openspec init` command to create `.gitkeep` files in the three empty directories that need to persist in Git:
+- `openspec/specs/`
+- `openspec/changes/`
+- `openspec/changes/archive/`
+
+The `.gitkeep` file is a widely-used convention to force Git to track empty directories. It's an empty file (or a file with a simple comment) that ensures the directory structure is preserved across clones.
+
+## Impact
+
+**Users Affected**: All users who run `openspec init`
+
+**Breaking Changes**: None
+
+**Migration Required**: No - existing projects work as-is, but will benefit from running `openspec init` again in extend mode to add .gitkeep files
+
+**Dependencies**: None
+
+**Timeline**: Quick fix - can be completed in one implementation session

openspec/changes/add-gitkeep-empty-folders/specs/cli-init/spec.md

@@ -0,0 +1,34 @@
+# CLI Init Specification Changes
+
+## MODIFIED Requirements
+
+### Requirement: Directory Creation
+The command SHALL create the complete OpenSpec directory structure with all required directories and files, including `.gitkeep` files to ensure empty directories are tracked by Git.
+
+#### Scenario: Creating OpenSpec structure
+- **WHEN** `openspec init` is executed
+- **THEN** create the following directory structure:
+```
+openspec/
+├── project.md
+├── AGENTS.md
+├── specs/
+│   └── .gitkeep
+└── changes/
+    ├── .gitkeep
+    └── archive/
+        └── .gitkeep
+```
+- **AND** each `.gitkeep` file SHALL be an empty file that forces Git to track the directory
+
+#### Scenario: Preserving empty directories in Git
+- **WHEN** a user commits and pushes the OpenSpec structure to a Git repository
+- **THEN** the `specs/`, `changes/`, and `changes/archive/` directories SHALL persist in the repository
+- **AND** after cloning the repository, all three directories SHALL exist
+- **AND** `openspec list` SHALL work immediately without manual directory creation
+
+#### Scenario: Working with fresh clones
+- **GIVEN** a repository initialized with OpenSpec
+- **WHEN** a new team member clones the repository
+- **THEN** running `openspec list` SHALL succeed without errors
+- **AND** no manual directory creation SHALL be required

openspec/changes/add-gitkeep-empty-folders/tasks.md

@@ -0,0 +1,19 @@
+# Tasks
+
+## Implementation
+- [ ] Modify `src/core/init.ts` `createDirectoryStructure` method to create `.gitkeep` files in empty directories
+- [ ] Add `.gitkeep` file creation for `openspec/specs/`
+- [ ] Add `.gitkeep` file creation for `openspec/changes/`
+- [ ] Add `.gitkeep` file creation for `openspec/changes/archive/`
+
+## Testing
+- [ ] Add test case verifying `.gitkeep` exists in `specs/` after init
+- [ ] Add test case verifying `.gitkeep` exists in `changes/` after init
+- [ ] Add test case verifying `.gitkeep` exists in `changes/archive/` after init
+- [ ] Run existing test suite to ensure no regressions
+
+## Validation
+- [ ] Run `openspec validate add-gitkeep-empty-folders --strict` and resolve all issues
+- [ ] Test `openspec init` manually in a fresh directory
+- [ ] Verify Git tracks the empty directories with `.gitkeep` files
+- [ ] Test `openspec list` works immediately after clone in a new repository

src/core/init.ts

@@ -716,6 +716,17 @@ export class InitCommand {
     for (const dir of directories) {
       await FileSystemUtils.createDirectory(dir);
     }
+
+    // Create .gitkeep files in empty directories to ensure Git tracks them
+    const emptyDirectories = [
+      path.join(openspecPath, 'specs', '.gitkeep'),
+      path.join(openspecPath, 'changes', '.gitkeep'),
+      path.join(openspecPath, 'changes', 'archive', '.gitkeep'),
+    ];
+
+    for (const gitkeepPath of emptyDirectories) {
+      await FileSystemUtils.writeFile(gitkeepPath, '');
+    }
   }
 
   private async generateFiles(

test/core/init.test.ts

@@ -79,6 +79,32 @@ describe('InitCommand', () => {
       ).toBe(true);
     });
 
+    it('should create .gitkeep files in empty directories', async () => {
+      queueSelections('claude', DONE);
+
+      await initCommand.execute(testDir);
+
+      const openspecPath = path.join(testDir, 'openspec');
+      expect(await fileExists(path.join(openspecPath, 'specs', '.gitkeep'))).toBe(true);
+      expect(await fileExists(path.join(openspecPath, 'changes', '.gitkeep'))).toBe(true);
+      expect(await fileExists(path.join(openspecPath, 'changes', 'archive', '.gitkeep'))).toBe(true);
+    });
+
+    it('should create empty .gitkeep files', async () => {
+      queueSelections('claude', DONE);
+
+      await initCommand.execute(testDir);
+
+      const openspecPath = path.join(testDir, 'openspec');
+      const specsGitkeep = await fs.readFile(path.join(openspecPath, 'specs', '.gitkeep'), 'utf-8');
+      const changesGitkeep = await fs.readFile(path.join(openspecPath, 'changes', '.gitkeep'), 'utf-8');
+      const archiveGitkeep = await fs.readFile(path.join(openspecPath, 'changes', 'archive', '.gitkeep'), 'utf-8');
+
+      expect(specsGitkeep).toBe('');
+      expect(changesGitkeep).toBe('');
+      expect(archiveGitkeep).toBe('');
+    });
+
     it('should create AGENTS.md and project.md', async () => {
       queueSelections('claude', DONE);