ac-framework 1.6.0 → 1.8.0

package/framework/.cursor/skills/testing-qa/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: testing-qa
+description: Automate the generation and maintenance of unit, integration, and end-to-end tests, as well as test data generation and debugging. Use when writing tests for new features, maintaining existing tests after API/UI changes, generating synthetic test data, or debugging test failures. Essential for ensuring code quality and preventing regressions.
+license: MIT
+metadata:
+  author: AC Framework
+  version: "1.0"
+---
+
+# Testing & QA
+
+Automated test generation, maintenance, and quality assurance for comprehensive code validation.
+
+## When to Use This Skill
+
+Use this skill when:
+- Writing tests for new features or components
+- Maintaining existing tests after API or UI changes
+- Generating synthetic test data for development/testing
+- Debugging failing tests or investigating coverage gaps
+- Setting up test infrastructure for a project
+- Running test suites and analyzing results
+
+## Instructions
+
+### Step 1: Analyze Test Requirements
+
+1. **Review the specification** or change document
+2. **Identify testable components**:
+   - Business logic functions
+   - API endpoints
+   - UI components/interactions
+   - Integration points
+3. **Determine test types needed**:
+   - Unit tests (isolated functions)
+   - Integration tests (component interactions)
+   - E2E tests (user workflows)
+
+### Step 2: Generate Test Cases
+
+For each component, generate tests covering:
+
+**Unit Tests**:
+- Happy path (normal operation)
+- Edge cases (empty input, max values, nulls)
+- Error cases (exceptions, invalid inputs)
+- Boundary conditions
+
+**Integration Tests**:
+- Component interactions
+- Data flow between modules
+- API contract validation
+- Database operations
+
+**E2E Tests**:
+- Critical user workflows
+- Multi-step processes
+- Cross-browser compatibility (if applicable)
+- Mobile responsiveness (if applicable)
+
+### Step 3: Create Test Files
+
+Follow project conventions:
+
+```
+test-file-naming:
+  unit: "*.test.js" or "*.spec.js"
+  integration: "*.integration.test.js"
+  e2e: "*.e2e.test.js" or in "e2e/" folder
+
+test-structure:
+  describe: "Component/Feature name"
+  it: "should [expected behavior] when [condition]"
+```
+
+### Step 4: Generate Test Data
+
+Create realistic test data:
+
+**Static Data**:
+```javascript
+const mockUsers = [
+  { id: 1, name: "John Doe", email: "john@example.com" },
+  { id: 2, name: "Jane Smith", email: "jane@example.com" }
+];
+```
+
+**Dynamic Data** (using factories):
+```javascript
+const generateUser = (overrides = {}) => ({
+  id: faker.datatype.uuid(),
+  name: faker.name.fullName(),
+  email: faker.internet.email(),
+  ...overrides
+});
+```
+
+**Synthetic Data for Load Testing**:
+- Large datasets for performance testing
+- Edge case data (max length strings, special characters)
+- Internationalization test data (Unicode, RTL languages)
+
+### Step 5: Implement Tests
+
+Write tests following best practices:
+
+**Arrange-Act-Assert Pattern**:
+```javascript
+test('should calculate total price with tax', () => {
+  // Arrange
+  const cart = { items: [{ price: 100, quantity: 2 }] };
+  const taxRate = 0.08;
+  
+  // Act
+  const total = calculateTotal(cart, taxRate);
+  
+  // Assert
+  expect(total).toBe(216); // 200 + 16 tax
+});
+```
+
+**Mock External Dependencies**:
+```javascript
+jest.mock('../api/client', () => ({
+  fetchUser: jest.fn()
+}));
+
+beforeEach(() => {
+  fetchUser.mockResolvedValue({ id: 1, name: 'Test User' });
+});
+```
+
+### Step 6: Run Tests and Debug
+
+1. **Execute test suite**:
+   ```bash
+   npm test
+   # or
+   npm run test:unit
+   npm run test:integration
+   npm run test:e2e
+   ```
+
+2. **Analyze failures**:
+   - Read error messages carefully
+   - Check stack traces
+   - Verify mocks are set up correctly
+   - Compare expected vs actual values
+
+3. **Debug failing tests**:
+   - Add console.log for debugging
+   - Use debugger statement
+   - Check test isolation (beforeEach/afterEach)
+   - Verify async handling (await, done callback)
+
+### Step 7: Maintain Tests
+
+When APIs or UI changes:
+
+1. **Identify affected tests** (run test suite)
+2. **Update test expectations** to match new behavior
+3. **Add new tests** for new functionality
+4. **Remove obsolete tests** for removed features
+5. **Update mocks** to match new interfaces
+
+### Step 8: Coverage Analysis
+
+1. **Run coverage report**:
+   ```bash
+   npm run test:coverage
+   ```
+
+2. **Identify gaps**:
+   - Uncovered branches (if/else conditions)
+   - Missing edge cases
+   - Untested error paths
+
+3. **Add tests** to cover gaps
+
+## Integration with OpenSpec
+
+- Use `openspec-verify-change` to validate tests pass
+- Link test files to tasks in tasks.md
+- Include test requirements in design.md
+- Reference test coverage in verification reports
+
+## Guardrails
+
+- **Test behavior, not implementation** - Tests should verify what code does, not how
+- **One assertion per test** (ideally) - Makes failures clearer
+- **Keep tests fast** - Unit tests should run in milliseconds
+- **Mock external systems** - Don't hit real databases/APIs in unit tests
+- **Clean up after tests** - Use afterEach to reset state
+- **Don't test framework code** - Focus on business logic
+
+## Common Patterns
+
+**Testing Async Code**:
+```javascript
+test('should fetch user data', async () => {
+  const user = await fetchUser(1);
+  expect(user).toEqual({ id: 1, name: 'John' });
+});
+```
+
+**Testing React Components**:
+```javascript
+import { render, screen, fireEvent } from '@testing-library/react';
+
+test('should toggle visibility on click', () => {
+  render(<ToggleButton />);
+  const button = screen.getByRole('button');
+  
+  fireEvent.click(button);
+  expect(screen.getByText('Visible')).toBeInTheDocument();
+  
+  fireEvent.click(button);
+  expect(screen.queryByText('Visible')).not.toBeInTheDocument();
+});
+```
+
+**Testing API Endpoints**:
+```javascript
+import request from 'supertest';
+import app from '../app';
+
+test('POST /api/users should create user', async () => {
+  const response = await request(app)
+    .post('/api/users')
+    .send({ name: 'John', email: 'john@example.com' });
+    
+  expect(response.status).toBe(201);
+  expect(response.body).toHaveProperty('id');
+});
+```
+
+## Requirements
+
+- Access to test runner (Jest, Mocha, Vitest, etc.)
+- Test utilities (@testing-library/react, supertest, etc.)
+- Code coverage tool (Istanbul, c8, etc.)
+- Access to the codebase being tested
+
+## See Also
+
+- `test-generator` - Generate initial test suite
+- `openspec-verify-change` - Validate implementation with tests
+- `systematic-debugging` - Debug failing tests
+- `secure-coding-cybersecurity` - Security-focused testing

package/framework/.factory/commands/ac-lite.md

@@ -0,0 +1,192 @@
+**Fundamental Principle**: *"Quality with focused context. Load only what is necessary, when it is necessary."*
+
+---
+
+## Purpose
+
+`ac-lite` keeps the same spec-driven quality bar as `ac.md`, but reduces token usage by:
+
+1. Loading only the core workflow skills by default.
+2. Activating extra skills only when objective risk gates require them.
+3. Enforcing mandatory quality checkpoints before implementation and archive.
+
+---
+
+## Default Skill Set (Always Load)
+
+These are the only mandatory skills for every change:
+
+1. `acfm-spec-workflow`
+2. `openspec-new-change` OR `openspec-ff-change`
+3. `openspec-continue-change`
+4. `openspec-apply-change`
+5. `openspec-verify-change`
+6. `openspec-archive-change`
+
+---
+
+## Conditional Skills (Load Only If Gate Triggers)
+
+### Security Gate
+
+Load `secure-coding-cybersecurity` if the change touches any of:
+
+- Auth/session/permissions
+- User input handling or validation
+- SQL/ORM queries or dynamic filters
+- File paths/uploads
+- Secrets/tokens/credentials
+- Shell/command execution
+
+### Testing Gate
+
+Load `test-generator` if:
+
+- There are no tests for the changed behavior, or
+- Existing tests do not cover acceptance criteria, or
+- Regression risk is medium/high.
+
+### Consistency Gate
+
+Load `spec-analysis` and `requirement-checklist` if:
+
+- Requirements are ambiguous, or
+- Change spans multiple modules, or
+- Change modifies core domain behavior.
+
+### API Gate
+
+Load `api-design-principles` if API contracts/endpoints/schemas are added or modified.
+
+### UI Gate
+
+Load `interface-design` if dashboard/app UI behavior is introduced or changed.
+
+### Performance Gate
+
+Load `performance-optimizer` if:
+
+- The change affects hot paths, or
+- Latency/throughput targets exist, or
+- A performance regression is detected/suspected.
+
+### Context Scale Gate
+
+Load `project-index` and/or `context-synthesizer` if:
+
+- Codebase is large and discovery cost is high, or
+- Session is long and context drift appears.
+
+### Debug Gate
+
+Load `systematic-debugging` when blocked by non-trivial bugs or unstable behavior.
+
+---
+
+## Mandatory Quality Gates
+
+These gates are non-optional in `ac-lite`.
+
+### Gate A: Ready to Implement
+
+Before `openspec-apply-change`, all must be true:
+
+- Change exists and status is valid (`acfm spec status --change <name> --json`)
+- `tasks.md` exists with actionable checkboxes
+- Acceptance criteria are clear in artifacts
+- Required conditional skills (if triggered) were executed
+
+If any item fails: stop, resolve, then continue.
+
+### Gate B: Ready to Archive
+
+Before `openspec-archive-change`, all must be true:
+
+- `openspec-verify-change` completed
+- No CRITICAL findings remain
+- Relevant tests pass for changed behavior
+- Tasks are complete or explicitly accepted by user with warning
+
+If any item fails: stop, fix, re-verify.
+
+---
+
+## Lite Workflows
+
+### New Change (Default Path)
+
+1. Run `acfm-spec-workflow` checks (`acfm spec status --json`, init if needed).
+2. Create change with `openspec-new-change` (or `openspec-ff-change` if user requests speed).
+3. Build artifacts with `openspec-continue-change` until apply-ready.
+4. Evaluate conditional gates and load only triggered skills.
+5. Pass Gate A.
+6. Implement with `openspec-apply-change`.
+7. Verify with `openspec-verify-change`.
+8. Pass Gate B.
+9. Archive with `openspec-archive-change`.
+
+### Existing Change (Default Path)
+
+1. Confirm initialization and active changes.
+2. Select target change.
+3. Refresh artifact status.
+4. Evaluate conditional gates (only load what triggers).
+5. Pass Gate A.
+6. Implement.
+7. Verify.
+8. Pass Gate B.
+9. Archive.
+
+---
+
+## Operational Rules
+
+1. Do not load broad quality/documentation skills by default.
+2. Do not run optional skills "just in case".
+3. If risk increases during implementation, activate the matching conditional skill immediately.
+4. Prefer deterministic CLI checks over narrative assumptions.
+5. Keep outputs concise but auditable (show which gates passed/failed and why).
+
+---
+
+## Suggested Minimal Execution Template
+
+Use this structure in each run:
+
+1. **Change Context**
+   - Change name
+   - Current artifact progress
+
+2. **Triggered Gates**
+   - Security: pass/fail + reason
+   - Testing: pass/fail + reason
+   - Consistency/API/UI/Performance/Context/Debug: pass/fail + reason
+
+3. **Skills Loaded**
+   - Core: always list
+   - Conditional: list only triggered ones
+
+4. **Gate A Status**
+   - Ready to implement: yes/no
+
+5. **Implementation + Verify**
+   - What was implemented
+   - Verify findings summary
+
+6. **Gate B Status**
+   - Ready to archive: yes/no
+
+7. **Archive Result**
+   - Archive path and timestamp
+
+---
+
+## Token Strategy Summary
+
+`ac-lite` reduces cost by replacing "load everything first" with:
+
+- Mandatory core workflow only
+- Risk-gated skill expansion
+- Hard quality checkpoints at implementation and archive boundaries
+
+This preserves software quality while avoiding unnecessary instruction/context overhead.