@avantmedia/af 0.0.1

package/setup/.claude/skills/pm/templates/api-endpoint.md

@@ -0,0 +1,69 @@
+# API Endpoint Template
+
+Work breakdown for implementing a new REST or GraphQL API endpoint.
+
+## Task Structure
+
+When breaking down an API endpoint epic, create these subtasks:
+
+### 1. Design & Planning
+- **Summary**: Design {endpoint} API contract
+- **Description**: Define request/response schemas, error codes, and edge cases
+- **Estimate**: 1-2h
+
+### 2. Database/Entity Changes (if needed)
+- **Summary**: Add database entities for {endpoint}
+- **Description**: Create or modify TypeORM entities, generate migration
+- **Estimate**: 1-2h
+
+### 3. Controller Implementation
+- **Summary**: Implement {endpoint} controller
+- **Description**: Create endpoint with request validation, business logic, response formatting
+- **Estimate**: 2-4h
+
+### 4. Input Validation
+- **Summary**: Add validation for {endpoint} inputs
+- **Description**: Implement request validation with proper error messages
+- **Estimate**: 1h
+
+### 5. Error Handling
+- **Summary**: Add error handling for {endpoint}
+- **Description**: Handle edge cases, return appropriate error codes
+- **Estimate**: 1h
+
+### 6. Unit Tests
+- **Summary**: Write unit tests for {endpoint}
+- **Description**: Test controller logic, validation, error cases
+- **Estimate**: 2-3h
+
+### 7. Integration Tests (optional)
+- **Summary**: Write integration tests for {endpoint}
+- **Description**: Test full request/response cycle with database
+- **Estimate**: 1-2h
+
+### 8. Documentation (optional)
+- **Summary**: Document {endpoint} API
+- **Description**: Add OpenAPI/Swagger docs or update API documentation
+- **Estimate**: 30m
+
+## Example Jira Commands
+
+```bash
+# Create subtasks for PROJ-100 (the epic)
+af jira create --project PROJ --type Sub-task --summary "Design user preferences API contract" --parent PROJ-100
+
+af jira create --project PROJ --type Sub-task --summary "Implement user preferences controller" --parent PROJ-100
+
+af jira create --project PROJ --type Sub-task --summary "Add validation for user preferences inputs" --parent PROJ-100
+
+af jira create --project PROJ --type Sub-task --summary "Write unit tests for user preferences endpoint" --parent PROJ-100
+```
+
+## Checklist
+
+Before marking the epic as done:
+- [ ] Endpoint accessible and returns expected responses
+- [ ] Input validation working with clear error messages
+- [ ] Error cases handled gracefully
+- [ ] Unit tests passing
+- [ ] No security vulnerabilities (auth, injection, etc.)

package/setup/.claude/skills/pm/templates/bug-fix.md

@@ -0,0 +1,77 @@
+# Bug Fix Template
+
+Work breakdown for investigating and fixing a bug.
+
+## Task Structure
+
+When breaking down a bug fix, create these subtasks:
+
+### 1. Reproduce
+- **Summary**: Reproduce {bug}
+- **Description**: Confirm reproduction steps, document environment, capture evidence
+- **Estimate**: 30m-1h
+
+### 2. Investigate
+- **Summary**: Investigate root cause of {bug}
+- **Description**: Debug, trace code paths, identify the source of the issue
+- **Estimate**: 1-3h
+
+### 3. Implement Fix
+- **Summary**: Fix {bug}
+- **Description**: Implement the solution, handle edge cases
+- **Estimate**: 1-3h
+
+### 4. Write Regression Test
+- **Summary**: Add regression test for {bug}
+- **Description**: Write test that would have caught this bug
+- **Estimate**: 30m-1h
+
+### 5. Verify Fix
+- **Summary**: Verify {bug} is fixed
+- **Description**: Confirm original reproduction steps no longer reproduce the issue
+- **Estimate**: 30m
+
+## Simplified Flow (Minor Bugs)
+
+For simple bugs, combine into fewer tasks:
+
+### 1. Investigate & Fix
+- **Summary**: Investigate and fix {bug}
+- **Description**: Reproduce, find root cause, implement fix
+- **Estimate**: 1-2h
+
+### 2. Add Test
+- **Summary**: Add regression test for {bug}
+- **Description**: Write test to prevent recurrence
+- **Estimate**: 30m
+
+## Example Jira Commands
+
+```bash
+# Create subtasks for PROJ-300 (the bug)
+af jira create --project PROJ --type Sub-task --summary "Reproduce login timeout bug" --parent PROJ-300
+
+af jira create --project PROJ --type Sub-task --summary "Investigate root cause of login timeout" --parent PROJ-300
+
+af jira create --project PROJ --type Sub-task --summary "Fix login timeout bug" --parent PROJ-300
+
+af jira create --project PROJ --type Sub-task --summary "Add regression test for login timeout" --parent PROJ-300
+```
+
+## Investigation Checklist
+
+When investigating:
+- [ ] Can reproduce consistently?
+- [ ] What changed recently? (git log, deployments)
+- [ ] Environment-specific? (browser, OS, data)
+- [ ] Related to recent code changes?
+- [ ] Are there similar past bugs?
+
+## Fix Checklist
+
+Before marking as done:
+- [ ] Bug no longer reproducible
+- [ ] Regression test added
+- [ ] No new issues introduced
+- [ ] Related areas tested
+- [ ] Root cause documented in ticket

package/setup/.claude/skills/pm/templates/feature.md

@@ -0,0 +1,87 @@
+# Feature Template
+
+Work breakdown for implementing a general feature.
+
+## Task Structure
+
+When breaking down a feature epic, create these subtasks:
+
+### 1. Requirements Analysis
+- **Summary**: Analyze requirements for {feature}
+- **Description**: Review specs, identify edge cases, clarify with stakeholders
+- **Estimate**: 1-2h
+
+### 2. Technical Design
+- **Summary**: Design implementation approach for {feature}
+- **Description**: Plan architecture, data models, API changes, UI components
+- **Estimate**: 1-3h
+
+### 3. Backend Implementation
+- **Summary**: Implement backend for {feature}
+- **Description**: Database changes, API endpoints, business logic
+- **Estimate**: 2-8h (varies by complexity)
+
+### 4. Frontend Implementation
+- **Summary**: Implement frontend for {feature}
+- **Description**: UI components, state management, API integration
+- **Estimate**: 2-8h (varies by complexity)
+
+### 5. Integration
+- **Summary**: Integrate {feature} frontend and backend
+- **Description**: Connect UI to API, handle loading/error states
+- **Estimate**: 1-2h
+
+### 6. Testing
+- **Summary**: Test {feature}
+- **Description**: Unit tests, integration tests, E2E tests
+- **Estimate**: 2-4h
+
+### 7. Documentation
+- **Summary**: Document {feature}
+- **Description**: Update user docs, API docs, or internal documentation
+- **Estimate**: 1h
+
+## Scaling for Complexity
+
+**Small Feature** (1-2 days):
+- Combine analysis + design
+- Single implementation task
+- Basic testing
+
+**Medium Feature** (3-5 days):
+- Separate analysis and design
+- Split backend/frontend
+- Comprehensive testing
+
+**Large Feature** (1+ weeks):
+- Detailed requirements analysis
+- Technical design document
+- Multiple implementation phases
+- Phased testing (unit -> integration -> E2E)
+- Documentation and training
+
+## Example Jira Commands
+
+```bash
+# Create subtasks for PROJ-400 (the epic)
+af jira create --project PROJ --type Sub-task --summary "Analyze requirements for email notifications" --parent PROJ-400
+
+af jira create --project PROJ --type Sub-task --summary "Design email notification system" --parent PROJ-400
+
+af jira create --project PROJ --type Sub-task --summary "Implement email notification backend" --parent PROJ-400
+
+af jira create --project PROJ --type Sub-task --summary "Implement email notification UI" --parent PROJ-400
+
+af jira create --project PROJ --type Sub-task --summary "Write tests for email notifications" --parent PROJ-400
+```
+
+## Definition of Done
+
+Before marking the epic as done:
+- [ ] All acceptance criteria met
+- [ ] Code reviewed and approved
+- [ ] Tests passing (unit, integration, E2E as appropriate)
+- [ ] No known bugs or regressions
+- [ ] Documentation updated
+- [ ] Deployed to staging and verified
+- [ ] Product owner sign-off (if applicable)

package/setup/.claude/skills/pm/templates/ui-component.md

@@ -0,0 +1,78 @@
+# UI Component Template
+
+Work breakdown for implementing a new React UI component or page.
+
+## Task Structure
+
+When breaking down a UI component epic, create these subtasks:
+
+### 1. Design Review
+- **Summary**: Review design for {component}
+- **Description**: Analyze mockups/designs, identify edge cases, confirm responsive requirements
+- **Estimate**: 30m-1h
+
+### 2. Component Structure
+- **Summary**: Create {component} component structure
+- **Description**: Set up component files, props interface, basic layout
+- **Estimate**: 1-2h
+
+### 3. Styling
+- **Summary**: Implement {component} styling
+- **Description**: Apply design system styles, handle responsive breakpoints
+- **Estimate**: 1-2h
+
+### 4. State Management
+- **Summary**: Add state management for {component}
+- **Description**: Implement local state, connect to global state if needed
+- **Estimate**: 1-2h
+
+### 5. API Integration
+- **Summary**: Connect {component} to API
+- **Description**: Implement data fetching, loading states, error handling
+- **Estimate**: 1-2h
+
+### 6. User Interactions
+- **Summary**: Implement {component} interactions
+- **Description**: Add event handlers, form validation, user feedback
+- **Estimate**: 1-2h
+
+### 7. Accessibility
+- **Summary**: Add accessibility to {component}
+- **Description**: ARIA labels, keyboard navigation, screen reader support
+- **Estimate**: 1h
+
+### 8. Unit Tests
+- **Summary**: Write tests for {component}
+- **Description**: Test component rendering, interactions, edge cases
+- **Estimate**: 1-2h
+
+### 9. E2E Tests
+- **Summary**: Add E2E test for {component}
+- **Description**: Test user flow with Playwright
+- **Estimate**: 1h
+
+## Example Jira Commands
+
+```bash
+# Create subtasks for PROJ-200 (the epic)
+af jira create --project PROJ --type Sub-task --summary "Create BookingCalendar component structure" --parent PROJ-200
+
+af jira create --project PROJ --type Sub-task --summary "Implement BookingCalendar styling" --parent PROJ-200
+
+af jira create --project PROJ --type Sub-task --summary "Connect BookingCalendar to booking API" --parent PROJ-200
+
+af jira create --project PROJ --type Sub-task --summary "Write tests for BookingCalendar" --parent PROJ-200
+
+af jira create --project PROJ --type Sub-task --summary "Add E2E test for BookingCalendar flow" --parent PROJ-200
+```
+
+## Checklist
+
+Before marking the epic as done:
+- [ ] Component matches design mockups
+- [ ] Responsive on all target breakpoints
+- [ ] Loading and error states implemented
+- [ ] Keyboard accessible
+- [ ] Unit tests passing
+- [ ] E2E test covering main flow
+- [ ] No console errors or warnings

package/utils/change-select-render.tsx

@@ -0,0 +1,44 @@
+import React from 'react';
+import { ChangeSelect } from '../components/change-select.tsx';
+import { render } from './ink-render.tsx';
+import type { OngoingChange } from './openspec.ts';
+
+/**
+ * Render the interactive change selection UI and return the selected change ID.
+ *
+ * @param changes - Array of ongoing changes to choose from
+ * @param prompt - Custom prompt text to display (default: "Select a change:")
+ * @returns Promise that resolves to selected change ID, or null if cancelled
+ */
+export function renderChangeSelect(
+    changes: OngoingChange[],
+    prompt?: string,
+): Promise<string | null> {
+    return new Promise(resolve => {
+        let cancelled = false;
+
+        const { unmount } = render(
+            <ChangeSelect
+                changes={changes}
+                prompt={prompt}
+                onSelect={selectedId => {
+                    unmount();
+                    resolve(selectedId);
+                }}
+                onCancel={() => {
+                    cancelled = true;
+                    unmount();
+                    resolve(null);
+                }}
+            />,
+        );
+
+        // Handle case where component is unmounted without selection
+        process.on('SIGINT', () => {
+            if (!cancelled) {
+                unmount();
+                resolve(null);
+            }
+        });
+    });
+}

package/utils/claude.ts

@@ -0,0 +1,9 @@
+/**
+ * Gets the configured agent command name from the ARTIFEX_AGENT environment variable.
+ * Falls back to 'claude' if not set.
+ *
+ * @returns The agent command name to use
+ */
+export function getAgentCommand(): string {
+    return process.env.ARTIFEX_AGENT || 'claude';
+}

package/utils/config.ts

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Configuration for the stop-hook command.
+ */
+export interface StopHookConfig {
+    ignoredPaths: string[];
+    command: string;
+}
+
+/**
+ * Full af.json configuration structure.
+ */
+export interface AfConfig {
+    stopHook?: Partial<StopHookConfig>;
+}
+
+/**
+ * Default configuration values.
+ */
+const DEFAULT_STOP_HOOK_CONFIG: StopHookConfig = {
+    ignoredPaths: ['openspec/'],
+    command: 'af e2e',
+};
+
+/**
+ * Load configuration from af.json in the current working directory.
+ * Returns undefined if the file doesn't exist.
+ * Throws if the file exists but is invalid JSON.
+ */
+export function loadAfConfig(): AfConfig | undefined {
+    const configPath = join(process.cwd(), 'af.json');
+
+    if (!existsSync(configPath)) {
+        return undefined;
+    }
+
+    const content = readFileSync(configPath, 'utf-8');
+    return JSON.parse(content) as AfConfig;
+}
+
+/**
+ * Get the stop-hook configuration, merging af.json settings with defaults.
+ * If ignoredPaths is specified in af.json, it completely replaces the defaults.
+ */
+export function getStopHookConfig(): StopHookConfig {
+    const afConfig = loadAfConfig();
+
+    if (!afConfig?.stopHook) {
+        return DEFAULT_STOP_HOOK_CONFIG;
+    }
+
+    return {
+        ignoredPaths: afConfig.stopHook.ignoredPaths ?? DEFAULT_STOP_HOOK_CONFIG.ignoredPaths,
+        command: afConfig.stopHook.command ?? DEFAULT_STOP_HOOK_CONFIG.command,
+    };
+}

package/utils/env.ts

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Load environment variables from a .env file in the current working directory.
+ * Silently skips if the file doesn't exist - never fails.
+ *
+ * Features:
+ * - Parses KEY=value pairs
+ * - Handles quoted values (single and double quotes)
+ * - Ignores comments (lines starting with #)
+ * - Ignores empty lines
+ * - Does not overwrite existing environment variables
+ */
+export function loadEnv(): void {
+    const envPath = join(process.cwd(), '.env');
+
+    if (!existsSync(envPath)) {
+        return; // Silently skip if .env doesn't exist
+    }
+
+    const content = readFileSync(envPath, 'utf-8');
+
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+
+        // Skip empty lines and comments
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+
+        const eqIndex = trimmed.indexOf('=');
+        if (eqIndex === -1) {
+            continue;
+        }
+
+        const key = trimmed.slice(0, eqIndex).trim();
+        let value = trimmed.slice(eqIndex + 1).trim();
+
+        // Remove surrounding quotes if present
+        if (
+            (value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))
+        ) {
+            value = value.slice(1, -1);
+        }
+
+        // Don't overwrite existing environment variables
+        if (process.env[key] === undefined) {
+            process.env[key] = value;
+        }
+    }
+}

package/utils/git.ts

@@ -0,0 +1,120 @@
+import { execSync } from 'node:child_process';
+
+/**
+ * Stage files in a specific directory for git commit.
+ *
+ * @param directory - The directory path to stage (relative to repo root)
+ * @returns true if staging succeeds, false otherwise
+ */
+export function stageDirectory(directory: string): boolean {
+    try {
+        console.log(`git add "${directory}"`);
+        execSync(`git add "${directory}"`, { stdio: 'pipe' });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Create a git commit with the specified message.
+ *
+ * @param message - The commit message
+ * @returns true if commit succeeds, false otherwise
+ */
+export function createCommit(message: string): boolean {
+    try {
+        execSync(`git commit -m "${message}"`, { stdio: 'pipe' });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Stage files and create a commit.
+ *
+ * @param directory - The directory to stage
+ * @param message - The commit message
+ * @returns Object with success status and optional error message
+ */
+export function stageAndCommit(
+    directory: string,
+    message: string,
+): { success: boolean; error?: string } {
+    if (!stageDirectory(directory)) {
+        return { success: false, error: 'Failed to stage files' };
+    }
+
+    if (!createCommit(message)) {
+        return { success: false, error: 'Failed to create commit' };
+    }
+
+    return { success: true };
+}
+
+/**
+ * Stage all changes (tracked and untracked) and create a commit.
+ *
+ * @param message - The commit message
+ * @returns Object with success status and optional error message
+ */
+export function stageAllAndCommit(message: string): { success: boolean; error?: string } {
+    try {
+        execSync('git add -A', { stdio: 'pipe' });
+    } catch {
+        return { success: false, error: 'Failed to stage files' };
+    }
+
+    if (!createCommit(message)) {
+        return { success: false, error: 'Failed to create commit' };
+    }
+
+    return { success: true };
+}
+
+/**
+ * Check if there are any changes to commit.
+ *
+ * @returns true if there are staged or unstaged changes, false otherwise
+ */
+export function hasChangesToCommit(): boolean {
+    try {
+        const status = execSync('git status --porcelain', { stdio: 'pipe' }).toString();
+        return status.trim().length > 0;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Stage all changes and create a commit with optional trailers.
+ *
+ * @param message - The commit message
+ * @param trailers - Array of trailer objects with key and value
+ * @returns Object with success status and optional error message
+ */
+export function stageAllAndCommitWithTrailers(
+    message: string,
+    trailers: Array<{ key: string; value: string }> = [],
+): { success: boolean; error?: string } {
+    try {
+        execSync('git add .', { stdio: 'pipe' });
+    } catch {
+        return { success: false, error: 'Failed to stage files' };
+    }
+
+    // Build commit command with trailers
+    const trailerArgs = trailers.map(t => `--trailer "${t.key}: ${t.value}"`).join(' ');
+    const commitCmd = trailerArgs
+        ? `git commit -m "${message}" ${trailerArgs}`
+        : `git commit -m "${message}"`;
+
+    try {
+        execSync(commitCmd, { stdio: 'pipe' });
+    } catch {
+        return { success: false, error: 'Failed to create commit' };
+    }
+
+    return { success: true };
+}

package/utils/ink-render.tsx

@@ -0,0 +1,50 @@
+import { render as inkRender } from 'ink';
+import type { ReactElement } from 'react';
+
+/**
+ * Render an Ink component to the terminal with signal handling
+ * @param element The React element to render
+ * @returns Object with cleanup function and promise that resolves when component unmounts
+ */
+export function render(element: ReactElement) {
+    const { unmount, waitUntilExit, clear } = inkRender(element);
+
+    // Handle graceful shutdown on SIGINT (Ctrl+C)
+    const handleSigInt = () => {
+        unmount();
+        process.exit(0);
+    };
+
+    // Handle graceful shutdown on SIGTERM
+    const handleSigTerm = () => {
+        unmount();
+        process.exit(0);
+    };
+
+    process.on('SIGINT', handleSigInt);
+    process.on('SIGTERM', handleSigTerm);
+
+    // Clean up signal handlers when component unmounts
+    const cleanup = () => {
+        process.off('SIGINT', handleSigInt);
+        process.off('SIGTERM', handleSigTerm);
+        unmount();
+    };
+
+    return {
+        unmount,
+        cleanup,
+        waitUntilExit,
+        clear,
+    };
+}
+
+/**
+ * Render an Ink component synchronously and wait for it to finish
+ * Useful for fire-and-forget static content
+ * @param element The React element to render
+ */
+export function renderSync(element: ReactElement): void {
+    const { waitUntilExit } = render(element);
+    waitUntilExit();
+}