cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skills/README.md

@@ -0,0 +1,78 @@
+# Codex Skills
+
+This directory contains all skills for the CFSA pipeline in Codex.
+
+## Subdirectories
+
+### Top-level workflow skill directories
+Pipeline workflow skills now live directly under `.codex/skills/<workflow-name>/SKILL.md`. Parent workflows and shard workflows both use the same top-level directory pattern so Codex can resolve them as proper skills.
+
+Examples:
+- `.codex/skills/ideate/SKILL.md`
+- `.codex/skills/create-prd/SKILL.md`
+- `.codex/skills/write-fe-spec/SKILL.md`
+- `.codex/skills/plan-phase/SKILL.md`
+- `.codex/skills/validate-phase/SKILL.md`
+
+### `setup/`
+Setup and bootstrap skills for initializing the CFSA pipeline:
+
+- `setup-cfsa.md` — Main setup skill (equivalent to `/bootstrap-agents`)
+- `setup-fill-placeholders.md` — Fill tech stack and placeholder values
+- `setup-provision-skills.md` — Install skills from skill library
+- `setup-verify.md` — Verify installation and readiness
+
+### `utilities/`
+Helper skills used throughout the pipeline:
+
+- `resolve-skill.md` — Dynamic skill resolution with 4-tier chain
+
+## Skill Structure
+
+Each skill follows this format:
+
+```yaml
+---
+name: skill-name
+description: Human-readable description
+parameters:
+  - name: input
+    type: string
+    required: true
+---
+
+## Overview
+[Brief description]
+
+## Prerequisites
+[Required conditions]
+
+## Step-by-Step
+### Step 1 — [Name]
+[Detailed instructions]
+
+## Completion Checklist
+- [ ] Verification steps
+
+## Next Steps
+[Recommended next actions]
+```
+
+## Invocation
+
+Skills are invoked by Codex based on context, user request, or orchestration by other skills.
+
+## Difference from Antigravity Workflows
+
+Antigravity workflows are passive markdown files that agents read and follow. Codex skills are active, executable units that:
+
+1. Accept parameters and return structured outputs
+2. Can call other skills (composition)
+3. Integrate with Codex's Tasks system
+4. Maintain state across sessions via memory protocols
+
+## See Also
+
+- `.codex/instructions/workflow.md` — Mandatory execution sequence
+- `.codex/rules/` — Always-active rules
+- `.memory/` — Canonical shared state management and session continuity

package/template/.codex/skills/accessibility/SKILL.md

@@ -0,0 +1,522 @@
+---
+name: accessibility
+description: Audit and improve web accessibility following WCAG 2.1 guidelines. Use when asked to "improve accessibility", "a11y audit", "WCAG compliance", "screen reader support", "keyboard navigation", or "make accessible".
+license: MIT
+metadata:
+  author: web-quality-skills
+  version: "1.0"
+---
+
+# Accessibility (a11y)
+
+Comprehensive accessibility guidelines based on WCAG 2.1 and Lighthouse accessibility audits. Goal: make content usable by everyone, including people with disabilities.
+
+## WCAG Principles: POUR
+
+| Principle | Description |
+|-----------|-------------|
+| **P**erceivable | Content can be perceived through different senses |
+| **O**perable | Interface can be operated by all users |
+| **U**nderstandable | Content and interface are understandable |
+| **R**obust | Content works with assistive technologies |
+
+## Conformance levels
+
+| Level | Requirement | Target |
+|-------|-------------|--------|
+| **A** | Minimum accessibility | Must pass |
+| **AA** | Standard compliance | Should pass (legal requirement in many jurisdictions) |
+| **AAA** | Enhanced accessibility | Nice to have |
+
+---
+
+## Perceivable
+
+### Text alternatives (1.1)
+
+**Images require alt text:**
+```html
+<!-- ❌ Missing alt -->
+<img src="chart.png">
+
+<!-- ✅ Descriptive alt -->
+<img src="chart.png" alt="Bar chart showing 40% increase in Q3 sales">
+
+<!-- ✅ Decorative image (empty alt) -->
+<img src="decorative-border.png" alt="" role="presentation">
+
+<!-- ✅ Complex image with longer description -->
+<figure>
+  <img src="infographic.png" alt="2024 market trends infographic" 
+       aria-describedby="infographic-desc">
+  <figcaption id="infographic-desc">
+    <!-- Detailed description -->
+  </figcaption>
+</figure>
+```
+
+**Icon buttons need accessible names:**
+```html
+<!-- ❌ No accessible name -->
+<button><svg><!-- menu icon --></svg></button>
+
+<!-- ✅ Using aria-label -->
+<button aria-label="Open menu">
+  <svg aria-hidden="true"><!-- menu icon --></svg>
+</button>
+
+<!-- ✅ Using visually hidden text -->
+<button>
+  <svg aria-hidden="true"><!-- menu icon --></svg>
+  <span class="visually-hidden">Open menu</span>
+</button>
+```
+
+**Visually hidden class:**
+```css
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+```
+
+### Color contrast (1.4.3, 1.4.6)
+
+| Text Size | AA minimum | AAA enhanced |
+|-----------|------------|--------------|
+| Normal text (< 18px / < 14px bold) | 4.5:1 | 7:1 |
+| Large text (≥ 18px / ≥ 14px bold) | 3:1 | 4.5:1 |
+| UI components & graphics | 3:1 | 3:1 |
+
+```css
+/* ❌ Low contrast (2.5:1) */
+.low-contrast {
+  color: #999;
+  background: #fff;
+}
+
+/* ✅ Sufficient contrast (7:1) */
+.high-contrast {
+  color: #333;
+  background: #fff;
+}
+
+/* ✅ Focus states need contrast too */
+:focus-visible {
+  outline: 2px solid #005fcc;
+  outline-offset: 2px;
+}
+```
+
+**Don't rely on color alone:**
+```html
+<!-- ❌ Only color indicates error -->
+<input class="error-border">
+<style>.error-border { border-color: red; }</style>
+
+<!-- ✅ Color + icon + text -->
+<div class="field-error">
+  <input aria-invalid="true" aria-describedby="email-error">
+  <span id="email-error" class="error-message">
+    <svg aria-hidden="true"><!-- error icon --></svg>
+    Please enter a valid email address
+  </span>
+</div>
+```
+
+### Media alternatives (1.2)
+
+```html
+<!-- Video with captions -->
+<video controls>
+  <source src="video.mp4" type="video/mp4">
+  <track kind="captions" src="captions.vtt" srclang="en" label="English" default>
+  <track kind="descriptions" src="descriptions.vtt" srclang="en" label="Descriptions">
+</video>
+
+<!-- Audio with transcript -->
+<audio controls>
+  <source src="podcast.mp3" type="audio/mp3">
+</audio>
+<details>
+  <summary>Transcript</summary>
+  <p>Full transcript text...</p>
+</details>
+```
+
+---
+
+## Operable
+
+### Keyboard accessible (2.1)
+
+**All functionality must be keyboard accessible:**
+```javascript
+// ❌ Only handles click
+element.addEventListener('click', handleAction);
+
+// ✅ Handles both click and keyboard
+element.addEventListener('click', handleAction);
+element.addEventListener('keydown', (e) => {
+  if (e.key === 'Enter' || e.key === ' ') {
+    e.preventDefault();
+    handleAction();
+  }
+});
+```
+
+**No keyboard traps:**
+```javascript
+// Modal focus management
+function openModal(modal) {
+  const focusableElements = modal.querySelectorAll(
+    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+  );
+  const firstElement = focusableElements[0];
+  const lastElement = focusableElements[focusableElements.length - 1];
+  
+  // Trap focus within modal
+  modal.addEventListener('keydown', (e) => {
+    if (e.key === 'Tab') {
+      if (e.shiftKey && document.activeElement === firstElement) {
+        e.preventDefault();
+        lastElement.focus();
+      } else if (!e.shiftKey && document.activeElement === lastElement) {
+        e.preventDefault();
+        firstElement.focus();
+      }
+    }
+    if (e.key === 'Escape') {
+      closeModal();
+    }
+  });
+  
+  firstElement.focus();
+}
+```
+
+### Focus visible (2.4.7)
+
+```css
+/* ❌ Never remove focus outlines */
+*:focus { outline: none; }
+
+/* ✅ Use :focus-visible for keyboard-only focus */
+:focus {
+  outline: none;
+}
+
+:focus-visible {
+  outline: 2px solid #005fcc;
+  outline-offset: 2px;
+}
+
+/* ✅ Or custom focus styles */
+button:focus-visible {
+  box-shadow: 0 0 0 3px rgba(0, 95, 204, 0.5);
+}
+```
+
+### Skip links (2.4.1)
+
+```html
+<body>
+  <a href="#main-content" class="skip-link">Skip to main content</a>
+  <header><!-- navigation --></header>
+  <main id="main-content" tabindex="-1">
+    <!-- main content -->
+  </main>
+</body>
+```
+
+```css
+.skip-link {
+  position: absolute;
+  top: -40px;
+  left: 0;
+  background: #000;
+  color: #fff;
+  padding: 8px 16px;
+  z-index: 100;
+}
+
+.skip-link:focus {
+  top: 0;
+}
+```
+
+### Timing (2.2)
+
+```javascript
+// Allow users to extend time limits
+function showSessionWarning() {
+  const modal = createModal({
+    title: 'Session Expiring',
+    content: 'Your session will expire in 2 minutes.',
+    actions: [
+      { label: 'Extend session', action: extendSession },
+      { label: 'Log out', action: logout }
+    ],
+    timeout: 120000 // 2 minutes to respond
+  });
+}
+```
+
+### Motion (2.3)
+
+```css
+/* Respect reduced motion preference */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+---
+
+## Understandable
+
+### Page language (3.1.1)
+
+```html
+<!-- ❌ No language specified -->
+<html>
+
+<!-- ✅ Language specified -->
+<html lang="en">
+
+<!-- ✅ Language changes within page -->
+<p>The French word for hello is <span lang="fr">bonjour</span>.</p>
+```
+
+### Consistent navigation (3.2.3)
+
+```html
+<!-- Navigation should be consistent across pages -->
+<nav aria-label="Main">
+  <ul>
+    <li><a href="/" aria-current="page">Home</a></li>
+    <li><a href="/products">Products</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+```
+
+### Form labels (3.3.2)
+
+```html
+<!-- ❌ No label association -->
+<input type="email" placeholder="Email">
+
+<!-- ✅ Explicit label -->
+<label for="email">Email address</label>
+<input type="email" id="email" name="email" 
+       autocomplete="email" required>
+
+<!-- ✅ Implicit label -->
+<label>
+  Email address
+  <input type="email" name="email" autocomplete="email" required>
+</label>
+
+<!-- ✅ With instructions -->
+<label for="password">Password</label>
+<input type="password" id="password" 
+       aria-describedby="password-requirements">
+<p id="password-requirements">
+  Must be at least 8 characters with one number.
+</p>
+```
+
+### Error handling (3.3.1, 3.3.3)
+
+```html
+<!-- Announce errors to screen readers -->
+<form novalidate>
+  <div class="field" aria-live="polite">
+    <label for="email">Email</label>
+    <input type="email" id="email" 
+           aria-invalid="true"
+           aria-describedby="email-error">
+    <p id="email-error" class="error" role="alert">
+      Please enter a valid email address (e.g., name@example.com)
+    </p>
+  </div>
+</form>
+```
+
+```javascript
+// Focus first error on submit
+form.addEventListener('submit', (e) => {
+  const firstError = form.querySelector('[aria-invalid="true"]');
+  if (firstError) {
+    e.preventDefault();
+    firstError.focus();
+    
+    // Announce error summary
+    const errorSummary = document.getElementById('error-summary');
+    errorSummary.textContent = `${errors.length} errors found. Please fix them and try again.`;
+    errorSummary.focus();
+  }
+});
+```
+
+---
+
+## Robust
+
+### Valid HTML (4.1.1)
+
+```html
+<!-- ❌ Duplicate IDs -->
+<div id="content">...</div>
+<div id="content">...</div>
+
+<!-- ❌ Invalid nesting -->
+<a href="/"><button>Click</button></a>
+
+<!-- ✅ Unique IDs -->
+<div id="main-content">...</div>
+<div id="sidebar-content">...</div>
+
+<!-- ✅ Proper nesting -->
+<a href="/" class="button-link">Click</a>
+```
+
+### ARIA usage (4.1.2)
+
+**Prefer native elements:**
+```html
+<!-- ❌ ARIA role on div -->
+<div role="button" tabindex="0">Click me</div>
+
+<!-- ✅ Native button -->
+<button>Click me</button>
+
+<!-- ❌ ARIA checkbox -->
+<div role="checkbox" aria-checked="false">Option</div>
+
+<!-- ✅ Native checkbox -->
+<label><input type="checkbox"> Option</label>
+```
+
+**When ARIA is needed:**
+```html
+<!-- Custom tabs component -->
+<div role="tablist" aria-label="Product information">
+  <button role="tab" id="tab-1" aria-selected="true" 
+          aria-controls="panel-1">Description</button>
+  <button role="tab" id="tab-2" aria-selected="false" 
+          aria-controls="panel-2" tabindex="-1">Reviews</button>
+</div>
+<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
+  <!-- Panel content -->
+</div>
+<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
+  <!-- Panel content -->
+</div>
+```
+
+### Live regions (4.1.3)
+
+```html
+<!-- Status updates -->
+<div aria-live="polite" aria-atomic="true" class="status">
+  <!-- Content updates announced to screen readers -->
+</div>
+
+<!-- Urgent alerts -->
+<div role="alert" aria-live="assertive">
+  <!-- Interrupts current announcement -->
+</div>
+```
+
+```javascript
+// Announce dynamic content changes
+function showNotification(message, type = 'polite') {
+  const container = document.getElementById(`${type}-announcer`);
+  container.textContent = ''; // Clear first
+  requestAnimationFrame(() => {
+    container.textContent = message;
+  });
+}
+```
+
+---
+
+## Testing checklist
+
+### Automated testing
+```bash
+# Lighthouse accessibility audit
+npx lighthouse https://example.com --only-categories=accessibility
+
+# axe-core
+npm install @axe-core/cli -g
+axe https://example.com
+```
+
+### Manual testing
+
+- [ ] **Keyboard navigation:** Tab through entire page, use Enter/Space to activate
+- [ ] **Screen reader:** Test with VoiceOver (Mac), NVDA (Windows), or TalkBack (Android)
+- [ ] **Zoom:** Content usable at 200% zoom
+- [ ] **High contrast:** Test with Windows High Contrast Mode
+- [ ] **Reduced motion:** Test with `prefers-reduced-motion: reduce`
+- [ ] **Focus order:** Logical and follows visual order
+
+### Screen reader commands
+
+| Action | VoiceOver (Mac) | NVDA (Windows) |
+|--------|-----------------|----------------|
+| Start/Stop | ⌘ + F5 | Ctrl + Alt + N |
+| Next item | VO + → | ↓ |
+| Previous item | VO + ← | ↑ |
+| Activate | VO + Space | Enter |
+| Headings list | VO + U, then arrows | H / Shift + H |
+| Links list | VO + U | K / Shift + K |
+
+---
+
+## Common issues by impact
+
+### Critical (fix immediately)
+1. Missing form labels
+2. Missing image alt text
+3. Insufficient color contrast
+4. Keyboard traps
+5. No focus indicators
+
+### Serious (fix before launch)
+1. Missing page language
+2. Missing heading structure
+3. Non-descriptive link text
+4. Auto-playing media
+5. Missing skip links
+
+### Moderate (fix soon)
+1. Missing ARIA labels on icons
+2. Inconsistent navigation
+3. Missing error identification
+4. Timing without controls
+5. Missing landmark regions
+
+## References
+
+- [WCAG 2.1 Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/)
+- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
+- [Deque axe Rules](https://dequeuniversity.com/rules/axe/)
+- [Web Quality Audit](../web-quality-audit/SKILL.md)