feat: implement change creation utilities

Add createChange() and validateChangeName() functions for programmatic
change directory creation with kebab-case validation.

- createChange(projectRoot, name) creates openspec/changes/<name>/
- validateChangeName() enforces kebab-case naming conventions
- Comprehensive test coverage (21 tests)

Author: TabishB

openspec/changes/add-change-manager/design.md

@@ -31,8 +31,7 @@ export function validateChangeName(name: string): { valid: boolean; error?: stri
 
 export async function createChange(
   projectRoot: string,
-  name: string,
-  description?: string
+  name: string
 ): Promise<void>
 ```
 
@@ -58,21 +57,6 @@ Invalid: `Add-Auth`, `add auth`, `add_auth`, `-add-auth`, `add-auth-`, `add--aut
 - URL-safe (for future web UI)
 - Consistent with existing change naming in repo
 
-### Decision 3: README.md for Change Metadata
-
-**Choice**: `createChange()` generates a `README.md` with name and optional description.
-
-```markdown
-# add-auth
-
-Add user authentication system
-```
-
-**Why**:
-- Human-readable in GitHub/GitLab UI
-- Minimal overhead
-- Matches existing manual change creation patterns
-
 ## File Changes
 
 ### New Files

openspec/changes/add-change-manager/proposal.md

@@ -8,7 +8,7 @@ There's no programmatic way to create a new change directory. Users must manuall
 This is error-prone and blocks automation (e.g., Claude commands, scripts).
 
 **This proposal adds:**
-1. `createChange(name, description?)` - Create change directories programmatically
+1. `createChange(projectRoot, name)` - Create change directories programmatically
 2. `validateChangeName(name)` - Enforce kebab-case naming conventions
 
 ## What Changes
@@ -17,7 +17,7 @@ This is error-prone and blocks automation (e.g., Claude commands, scripts).
 
 | Function | Description |
 |----------|-------------|
-| `createChange(name, description?)` | Creates `openspec/changes/<name>/` with README.md |
+| `createChange(projectRoot, name)` | Creates `openspec/changes/<name>/` directory |
 | `validateChangeName(name)` | Returns `{ valid: boolean; error?: string }` |
 
 ### Name Validation Rules

openspec/changes/add-change-manager/specs/change-creation/spec.md

@@ -3,15 +3,9 @@
 ### Requirement: Change Creation
 The system SHALL provide a function to create new change directories programmatically.
 
-#### Scenario: Create change with name only
+#### Scenario: Create change
 - **WHEN** `createChange(projectRoot, 'add-auth')` is called
 - **THEN** the system creates `openspec/changes/add-auth/` directory
-- **AND** creates a `README.md` file with the change name as title
-
-#### Scenario: Create change with description
-- **WHEN** `createChange(projectRoot, 'add-auth', 'Add user authentication')` is called
-- **THEN** the system creates `openspec/changes/add-auth/` directory
-- **AND** creates a `README.md` file with the change name and description
 
 #### Scenario: Duplicate change rejected
 - **WHEN** `createChange(projectRoot, 'add-auth')` is called and `openspec/changes/add-auth/` already exists

openspec/changes/add-change-manager/tasks.md

@@ -1,32 +1,30 @@
 ## Phase 1: Implement Name Validation
 
-- [ ] 1.1 Create `src/utils/change-utils.ts`
-- [ ] 1.2 Implement `validateChangeName()` with kebab-case pattern
-- [ ] 1.3 Pattern: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`
-- [ ] 1.4 Return `{ valid: boolean; error?: string }`
-- [ ] 1.5 Add test: valid names accepted (`add-auth`, `refactor`, `add-feature-2`)
-- [ ] 1.6 Add test: uppercase rejected
-- [ ] 1.7 Add test: spaces rejected
-- [ ] 1.8 Add test: underscores rejected
-- [ ] 1.9 Add test: special characters rejected
-- [ ] 1.10 Add test: leading/trailing hyphens rejected
-- [ ] 1.11 Add test: consecutive hyphens rejected
+- [x] 1.1 Create `src/utils/change-utils.ts`
+- [x] 1.2 Implement `validateChangeName()` with kebab-case pattern
+- [x] 1.3 Pattern: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`
+- [x] 1.4 Return `{ valid: boolean; error?: string }`
+- [x] 1.5 Add test: valid names accepted (`add-auth`, `refactor`, `add-feature-2`)
+- [x] 1.6 Add test: uppercase rejected
+- [x] 1.7 Add test: spaces rejected
+- [x] 1.8 Add test: underscores rejected
+- [x] 1.9 Add test: special characters rejected
+- [x] 1.10 Add test: leading/trailing hyphens rejected
+- [x] 1.11 Add test: consecutive hyphens rejected
 
 ## Phase 2: Implement Change Creation
 
-- [ ] 2.1 Implement `createChange(projectRoot, name, description?)`
-- [ ] 2.2 Validate name before creating
-- [ ] 2.3 Create parent directories if needed (`openspec/changes/`)
-- [ ] 2.4 Generate README.md with name and optional description
-- [ ] 2.5 Throw if change already exists
-- [ ] 2.6 Add test: creates directory and README with name only
-- [ ] 2.7 Add test: creates directory and README with description
-- [ ] 2.8 Add test: duplicate change throws error
-- [ ] 2.9 Add test: invalid name throws validation error
-- [ ] 2.10 Add test: creates parent directories if needed
+- [x] 2.1 Implement `createChange(projectRoot, name)`
+- [x] 2.2 Validate name before creating
+- [x] 2.3 Create parent directories if needed (`openspec/changes/`)
+- [x] 2.4 Throw if change already exists
+- [x] 2.5 Add test: creates directory
+- [x] 2.6 Add test: duplicate change throws error
+- [x] 2.7 Add test: invalid name throws validation error
+- [x] 2.8 Add test: creates parent directories if needed
 
 ## Phase 3: Integration
 
-- [ ] 3.1 Export functions from `src/utils/index.ts`
-- [ ] 3.2 Add JSDoc comments
-- [ ] 3.3 Run all tests to verify no regressions
+- [x] 3.1 Export functions from `src/utils/index.ts`
+- [x] 3.2 Add JSDoc comments
+- [x] 3.3 Run all tests to verify no regressions

src/utils/change-utils.ts

@@ -0,0 +1,102 @@
+import path from 'path';
+import { FileSystemUtils } from './file-system.js';
+
+/**
+ * Result of validating a change name.
+ */
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+}
+
+/**
+ * Validates that a change name follows kebab-case conventions.
+ *
+ * Valid names:
+ * - Start with a lowercase letter
+ * - Contain only lowercase letters, numbers, and hyphens
+ * - Do not start or end with a hyphen
+ * - Do not contain consecutive hyphens
+ *
+ * @param name - The change name to validate
+ * @returns Validation result with `valid: true` or `valid: false` with an error message
+ *
+ * @example
+ * validateChangeName('add-auth') // { valid: true }
+ * validateChangeName('Add-Auth') // { valid: false, error: '...' }
+ */
+export function validateChangeName(name: string): ValidationResult {
+  // Pattern: starts with lowercase letter, followed by lowercase letters/numbers,
+  // optionally followed by hyphen + lowercase letters/numbers (repeatable)
+  const kebabCasePattern = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+  if (!name) {
+    return { valid: false, error: 'Change name cannot be empty' };
+  }
+
+  if (!kebabCasePattern.test(name)) {
+    // Provide specific error messages for common mistakes
+    if (/[A-Z]/.test(name)) {
+      return { valid: false, error: 'Change name must be lowercase (use kebab-case)' };
+    }
+    if (/\s/.test(name)) {
+      return { valid: false, error: 'Change name cannot contain spaces (use hyphens instead)' };
+    }
+    if (/_/.test(name)) {
+      return { valid: false, error: 'Change name cannot contain underscores (use hyphens instead)' };
+    }
+    if (name.startsWith('-')) {
+      return { valid: false, error: 'Change name cannot start with a hyphen' };
+    }
+    if (name.endsWith('-')) {
+      return { valid: false, error: 'Change name cannot end with a hyphen' };
+    }
+    if (/--/.test(name)) {
+      return { valid: false, error: 'Change name cannot contain consecutive hyphens' };
+    }
+    if (/[^a-z0-9-]/.test(name)) {
+      return { valid: false, error: 'Change name can only contain lowercase letters, numbers, and hyphens' };
+    }
+    if (/^[0-9]/.test(name)) {
+      return { valid: false, error: 'Change name must start with a letter' };
+    }
+
+    return { valid: false, error: 'Change name must follow kebab-case convention (e.g., add-auth, refactor-db)' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Creates a new change directory.
+ *
+ * @param projectRoot - The root directory of the project (where `openspec/` lives)
+ * @param name - The change name (must be valid kebab-case)
+ * @throws Error if the change name is invalid
+ * @throws Error if the change directory already exists
+ *
+ * @example
+ * // Creates openspec/changes/add-auth/
+ * await createChange('/path/to/project', 'add-auth')
+ */
+export async function createChange(
+  projectRoot: string,
+  name: string
+): Promise<void> {
+  // Validate the name first
+  const validation = validateChangeName(name);
+  if (!validation.valid) {
+    throw new Error(validation.error);
+  }
+
+  // Build the change directory path
+  const changeDir = path.join(projectRoot, 'openspec', 'changes', name);
+
+  // Check if change already exists
+  if (await FileSystemUtils.directoryExists(changeDir)) {
+    throw new Error(`Change '${name}' already exists at ${changeDir}`);
+  }
+
+  // Create the directory (including parent directories if needed)
+  await FileSystemUtils.createDirectory(changeDir);
+}

src/utils/index.ts

@@ -1,2 +1,3 @@
-// Shared utilities will be implemented here
-export {};
+// Shared utilities
+export { validateChangeName, createChange } from './change-utils.js';
+export type { ValidationResult } from './change-utils.js';