ac-framework 1.9.2 → 1.9.3

package/framework/web_development/.codex/skills/spec-clarification/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: spec-clarification
+description: Identify underspecified areas in the current feature spec by asking targeted clarification questions and encoding answers back into the spec.
+---
+
+# Specification Clarification
+
+## Overview
+
+Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
+
+**Goal**: Identify 5 actionable clarification questions that materially impact implementation.
+
+## Execution Steps
+
+1.  **Initialize Context**:
+    *   Load the current spec file (`spec.md`).
+    *   Perform a structured ambiguity & coverage scan.
+    *   Identify missing or partial information in: Functional Scope, Domain & Data Model, Interaction & UX Flow, Non-Functional Quality, Integration & Dependencies, Edge Cases, Constraints, Terminology, Completion Signals, Misc/Placeholders.
+
+2.  **Generate Prioritized Questions**:
+    *   Create a queue of candidate clarification questions (max 5).
+    *   **Constraints**:
+        *   Answerable with Multiple Choice (2-5 options) OR Short Answer (<=5 words).
+        *   Materially impacts architecture, data modeling, task decomposition, test design, UX, or compliance.
+        *   Exclude style preferences or plan-level details unless blocking.
+        *   Favor impact * uncertainty heuristic.
+
+3.  **Sequential Questioning Loop (Interactive)**:
+    *   Present **ONE** question at a time.
+    *   **Multiple Choice**:
+        *   Analyze options based on best practices/risk/alignment.
+        *   Present **Recommended Option** with reasoning first.
+        *   Show table of options (A, B, C...).
+        *   Prompt user to reply with letter or "yes"/"recommended".
+    *   **Short Answer**:
+        *   Provide **Suggested Answer** based on context.
+        *   Prompt user to reply "yes"/"suggested" or own answer.
+    *   **After Answer**:
+        *   Validate answer.
+        *   Record in working memory.
+        *   Stop if: All critical ambiguities resolved, User says stop, or 5 questions reached.
+
+4.  **Integration (Incremental Update)**:
+    *   **After EACH accepted answer**:
+        *   Ensure a `## Clarifications` section exists (create if missing).
+        *   Append a bullet: `- Q: <question> → A: <final answer>`.
+        *   **Apply the clarification** to the appropriate section(s) in the spec:
+            *   Functional → Functional Requirements.
+            *   User Interaction → User Stories/Actors.
+            *   Data → Data Model.
+            *   Non-Functional → NFRs.
+            *   Edge Case → Edge Cases/Error Handling.
+            *   Terminology → Normalize terms.
+        *   **Save the spec file** immediately.
+
+5.  **Validation**:
+    *   Ensure exactly one bullet per answer.
+    *   Ensure no contradictory earlier statements remain.
+    *   Ensure Markdown structure is valid.
+
+6.  **Report Completion**:
+    *   Summarize questions asked & answered.
+    *   List sections touched.
+    *   Show coverage summary table (Resolved/Deferred/Clear/Outstanding).
+    *   Recommend next steps (e.g., Proceed to Planning).
+
+## Principles
+
+*   If no ambiguities, state "No critical ambiguities detected".
+*   Never exceed 5 questions.
+*   Avoid speculative tech stack questions unless blocking functional clarity.
+*   Respect explicit user stops.

package/framework/web_development/.codex/skills/sync-index/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: sync-index
+description: Keep project documentation (.agents/project-index.md and sub-skills) in sync with codebase changes.
+---
+
+# Documentation Sync
+
+## Overview
+
+Documentation drift is a major problem. Use this skill to ensure that the project index and agent guidance files are always up-to-date with the codebase.
+
+## Workflow
+
+1.  **Detect Changes**:
+    *   Ideally run after major feature implementation or refactoring.
+    *   Compare current file structure with `project-index.md`.
+
+2.  **Run Indexer**:
+    *   Execute the `project-index` skill again.
+    *   Verify that new modules/directories are captured.
+    *   Ensure deleted files are removed from documentation.
+
+3.  **Update Guidance**:
+    *   Check `agent-*.md` files in domain directories.
+    *   Update any obsolete instructions.
+    *   Add new patterns discovered during implementation.
+
+4.  **Verify Links**:
+    *   Ensure all links in `README.md` and `AGENTS.md` point to valid locations.
+
+## Output
+
+*   Updated `project-index.md`.
+*   Updated domain-specific agent guides.
+*   Confirmation of documentation sync.

package/framework/web_development/.codex/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Manager wants it fixed NOW (systematic is faster than thrashing)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+   **Example (multi-layer system):**
+   ```bash
+   # Layer 1: Workflow
+   echo "=== Secrets available in workflow: ==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # Layer 2: Build script
+   echo "=== Env vars in build script: ==="
+   env | grep IDENTITY || echo "IDENTITY not in environment"
+
+   # Layer 3: Signing script
+   echo "=== Keychain state: ==="
+   security list-keychains
+   security find-identity -v
+
+   # Layer 4: Actual signing
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+
+   See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
+
+   **Quick version:**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask for help
+   - Research more
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - One-off test script if no framework
+   - MUST have before fixing
+   - Use the `superpowers:test-driven-development` skill for writing proper failing tests
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question the architecture (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new shared state/coupling/problem in different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we "sticking with it through sheer inertia"?
+   - Should we refactor architecture vs. continue fixing symptoms?
+
+   **Discuss with your human partner before attempting more fixes**
+
+   This is NOT a failed hypothesis - this is a wrong architecture.
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+
+## your human partner's Signals You're Doing It Wrong
+
+**Watch for these redirections:**
+- "Is that not happening?" - You assumed without verifying
+- "Will it show us...?" - You should have added evidence gathering
+- "Stop guessing" - You're proposing fixes without understanding
+- "Ultrathink this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Your approach isn't working
+
+**When you see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Supporting Techniques
+
+These techniques are part of systematic debugging and available in this directory:
+
+- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
+- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
+- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
+
+**Related skills:**
+- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
+- **superpowers:verification-before-completion** - Verify fix worked before claiming success
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common

package/framework/web_development/.codex/skills/test-generator/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: test-generator
+description: Generate comprehensive test suites ensuring requirements are met. Strategies for Unit, Integration, and E2E testing.
+---
+
+# Test Generation and Strategy
+
+## Overview
+
+Use this skill to systematically test features by generating high-quality test cases based on specifications and architectural design.
+
+## Workflow
+
+1.  **Analyze Requirements**:
+    *   Understand the "Why" and "What" from specs and user stories.
+    *   Identify key scenarios, edge cases, and failure modes.
+
+2.  **Define Test Strategy**:
+    *   **Unit Tests**: Test individual functions/methods in isolation. Mock external dependencies.
+    *   **Integration Tests**: Test interactions between modules (e.g., API + Database).
+    *   **End-to-End (E2E) Tests**: Test complete user flows from frontend to backend.
+    *   **Pyramid**: Ideally follow the test pyramid (Many Unit > Some Integration > Few E2E).
+
+3.  **Generate Test Code**:
+    *   Write test cases *before* implementation if possible (TDD).
+    *   Use established testing frameworks (Jest, PyTest, Mocha, Cypress, Playwright).
+    *   Ensure descriptive test names: `it("should return 404 when user not found")`.
+    *   Apply AAA pattern: Arrange, Act, Assert.
+
+## Quality Checklist
+
+*   **Coverage**: Do tests cover positive, negative, and edge cases?
+*   **Isolation**: Are unit tests independent and fast?
+*   **Reliability**: Are tests deterministic (no flaky tests)?
+*   **Mocking**: Are external services mocked appropriately?
+
+## Output
+
+*   Fully functional test files.
+*   Instructions on how to run tests.
+*   Suggestions for coverage improvements.

package/framework/web_development/.codex/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