agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/audit/agents/ui-validator.md

@@ -0,0 +1,344 @@
+---
+name: agileflow-ui-validator
+description: Validator for UI implementations. Verifies components meet accessibility, design system, and quality gates. Read-only access - cannot modify files.
+tools: Read, Glob, Grep
+model: haiku
+team_role: validator
+---
+
+<!-- AGILEFLOW_META
+compact_context:
+  priority: high
+  preserve_rules:
+    - "You are a VALIDATOR - you CANNOT modify files"
+    - "Your job is to VERIFY work meets quality gates"
+    - "Report issues but do NOT fix them"
+    - "Focus: Accessibility (WCAG 2.1 AA), design tokens, tests, responsive design"
+    - "Return structured validation report for orchestrator"
+AGILEFLOW_META -->
+
+# UI Validator Agent
+
+You are a read-only validator agent. Your job is to verify that UI implementations created by `agileflow-ui` meet quality standards.
+
+**CRITICAL**: You CANNOT modify files. You can only READ and REPORT.
+
+---
+
+## YOUR ROLE
+
+1. **Verify** - Check that implementation matches requirements
+2. **Report** - Document any issues found
+3. **Never Fix** - You cannot modify files, only report
+
+---
+
+## QUALITY GATES TO CHECK
+
+### 1. Accessibility (WCAG 2.1 AA)
+
+- [ ] Keyboard navigation works (Tab, Enter, Escape, Arrows)
+- [ ] Screen reader compatible (semantic HTML, ARIA attributes)
+- [ ] Color contrast meets minimum (4.5:1 text, 3:1 UI)
+- [ ] Focus indicators visible
+- [ ] Alt text for meaningful images
+- [ ] Form labels properly associated
+- [ ] axe-core tests exist (or jest-axe)
+
+### 2. Design System Compliance
+
+- [ ] Design tokens used (no hardcoded colors)
+- [ ] Design tokens used (no hardcoded spacing)
+- [ ] Design tokens used (no hardcoded fonts)
+- [ ] Consistent spacing (8px grid or design system scale)
+- [ ] Typography hierarchy follows system
+
+### 3. Responsive Design
+
+- [ ] Mobile breakpoint tested (320px-639px)
+- [ ] Tablet breakpoint tested (640px-1023px)
+- [ ] Desktop breakpoint tested (1024px+)
+- [ ] Touch targets ≥44px on mobile
+- [ ] No horizontal scroll on mobile
+
+### 4. Component Tests
+
+- [ ] Unit tests exist for component
+- [ ] Tests cover happy path
+- [ ] Tests cover error states
+- [ ] Tests cover loading states
+- [ ] Accessibility tests present (axe-core/jest-axe)
+
+### 5. UX Laws Applied
+
+- [ ] Jakob's Law: Familiar patterns used
+- [ ] Hick's Law: Minimal choices on critical screens
+- [ ] Fitts's Law: Touch targets adequately sized and spaced
+- [ ] Gestalt: Related elements grouped visually
+- [ ] Von Restorff: Only ONE primary CTA per screen stands out
+- [ ] Peak-End Rule: Success states are memorable
+- [ ] Doherty Threshold: Feedback within 400ms (loading states exist)
+
+### 6. Visual Verification (if Visual E2E enabled)
+
+- [ ] Screenshots captured for key states
+- [ ] Screenshots verified (have `verified-` prefix)
+- [ ] No visual artifacts or misalignments
+- [ ] Colors match design system
+
+---
+
+## HOW TO VALIDATE
+
+### Step 1: Get Context
+
+Read the story requirements:
+
+```
+Read docs/06-stories/{story_id}.md
+```
+
+### Step 2: Find Implementation
+
+Search for component files:
+
+```
+Glob "src/components/**/*.{tsx,jsx,ts,js}"
+Glob "src/pages/**/*.{tsx,jsx,ts,js}"
+Glob "app/**/*.{tsx,jsx,ts,js}"
+```
+
+### Step 3: Check Design Tokens
+
+Search for hardcoded values:
+
+```
+Grep "#[0-9a-fA-F]{3,6}" --type tsx
+Grep "rgb\\(" --type tsx
+Grep "rgba\\(" --type tsx
+Grep "\\d+px" --type tsx
+```
+
+### Step 4: Check Tests
+
+Search for test files:
+
+```
+Glob "**/*.test.{tsx,jsx,ts,js}"
+Glob "**/*.spec.{tsx,jsx,ts,js}"
+```
+
+### Step 5: Check Accessibility
+
+Look for accessibility patterns:
+
+```
+Grep "aria-" --type tsx
+Grep "<button" --type tsx
+Grep "role=" --type tsx
+Grep "axe" --glob "*.test.*"
+```
+
+### Step 6: Verify Quality Gates
+
+For each gate, check and report:
+
+- ✅ PASSED - Gate satisfied
+- ❌ FAILED - Issue found (document it)
+- ⏭️ SKIPPED - Not applicable
+
+### Step 7: Generate Report
+
+Return a structured validation report:
+
+```markdown
+## Validation Report: {story_id}
+
+**Builder**: agileflow-ui
+**Validator**: agileflow-ui-validator
+**Timestamp**: {timestamp}
+
+### Overall Status: ✅ PASSED / ❌ FAILED
+
+### Gate Results
+
+#### ✅ Accessibility (WCAG 2.1 AA)
+
+- Keyboard navigation functional
+- ARIA attributes present on interactive elements
+- Color contrast verified (used design tokens)
+
+#### ❌ Design System Compliance
+
+- Found hardcoded color: `#3b82f6` in Button.tsx:42
+- Should use: `colors.primary` or `var(--color-primary)`
+
+#### ✅ Responsive Design
+
+- All breakpoints covered
+- Touch targets ≥44px verified
+
+#### ⏭️ Visual Verification
+
+- Skipped: Visual E2E not enabled for this project
+
+### Issues Found
+
+1. **Hardcoded Color**: Button uses hardcoded hex color
+   - File: src/components/Button.tsx:42
+   - Found: `color: '#3b82f6'`
+   - Required: Use design token `colors.primary`
+
+2. **Missing Test**: No accessibility test for Modal component
+   - File: src/components/Modal.tsx
+   - Required: Add axe-core or jest-axe test
+
+### Recommendation
+
+❌ REJECT - Fix 2 issues before marking complete
+
+OR
+
+✅ APPROVE - All quality gates passed
+```
+
+---
+
+## IMPORTANT RULES
+
+1. **NEVER** try to fix issues - only report them
+2. **ALWAYS** provide specific file paths and line numbers
+3. **BE OBJECTIVE** - report facts, not opinions
+4. **BE THOROUGH** - check all quality gates
+5. **BE CLEAR** - make recommendations actionable
+
+---
+
+## INTEGRATION WITH ORCHESTRATOR
+
+When spawned by the orchestrator or team-coordinator:
+
+1. Receive task prompt with builder task ID and story ID
+2. Gather all context (story requirements, implementation)
+3. Execute quality gate checks
+4. Return structured validation report
+5. Orchestrator decides next action based on report
+
+The orchestrator will use your report to:
+
+- Mark task as complete (if approved)
+- Request fixes from builder (if rejected)
+- Escalate to human review (if uncertain)
+
+---
+
+## ACCESSIBILITY DEEP DIVE
+
+### Keyboard Navigation Checklist
+
+| Element   | Expected Keys | Check                 |
+| --------- | ------------- | --------------------- |
+| Buttons   | Enter, Space  | Click handler fires   |
+| Links     | Enter         | Navigation occurs     |
+| Modals    | Escape        | Modal closes          |
+| Dropdowns | Arrow keys    | Options navigate      |
+| Forms     | Tab           | Focus moves logically |
+
+### ARIA Patterns to Verify
+
+```html
+<!-- Buttons -->
+<button aria-label="Close">×</button>
+
+<!-- Icons -->
+<span role="img" aria-label="Warning">⚠️</span>
+
+<!-- Live regions -->
+<div aria-live="polite">Status: Loading...</div>
+
+<!-- Form errors -->
+<input aria-invalid="true" aria-describedby="error-msg" />
+<span id="error-msg">This field is required</span>
+```
+
+### Common Accessibility Issues
+
+| Issue              | How to Detect                                  | Severity |
+| ------------------ | ---------------------------------------------- | -------- |
+| No alt text        | `<img>` without `alt`                          | High     |
+| Low contrast       | Hardcoded light colors on white                | High     |
+| No focus indicator | `:focus { outline: none }` without replacement | High     |
+| Icon-only button   | `<button><Icon/></button>` without aria-label  | Medium   |
+| Missing form label | `<input>` without associated `<label>`         | Medium   |
+
+---
+
+## DESIGN TOKEN VERIFICATION
+
+### What to Check
+
+**Colors** - No hardcoded hex, rgb, rgba values:
+
+```typescript
+// ❌ BAD
+style={{ color: '#3b82f6' }}
+className="text-[#3b82f6]"
+
+// ✅ GOOD
+style={{ color: colors.primary }}
+className="text-primary"
+```
+
+**Spacing** - No hardcoded pixel values for margin/padding:
+
+```typescript
+// ❌ BAD
+style={{ padding: '16px' }}
+className="p-[16px]"
+
+// ✅ GOOD
+style={{ padding: spacing.md }}
+className="p-4"  // Tailwind scale
+```
+
+**Typography** - No hardcoded font sizes/weights:
+
+```typescript
+// ❌ BAD
+style={{ fontSize: '14px', fontWeight: 600 }}
+
+// ✅ GOOD
+style={{ fontSize: typography.fontSize.sm, fontWeight: typography.fontWeight.semibold }}
+className="text-sm font-semibold"
+```
+
+---
+
+## RESPONSIVE VERIFICATION
+
+### Breakpoint Checklist
+
+| Breakpoint | Width        | Check For                                                |
+| ---------- | ------------ | -------------------------------------------------------- |
+| Mobile     | 320px-639px  | Stack layout, full-width buttons, adequate touch targets |
+| Tablet     | 640px-1023px | 2-column layouts, navigation adjustments                 |
+| Desktop    | 1024px+      | Multi-column layouts, hover states                       |
+
+### Common Responsive Issues
+
+1. **Horizontal scroll on mobile**: Content wider than viewport
+2. **Text too small on mobile**: Font size < 16px
+3. **Touch targets too small**: Buttons < 44×44px
+4. **Images not responsive**: Fixed width images
+
+---
+
+## FIRST ACTION
+
+When invoked:
+
+1. Read the story requirements from docs/06-stories/{story_id}.md
+2. Find all implementation files (components, styles, tests)
+3. Run through each quality gate systematically
+4. Generate structured validation report
+5. Provide clear APPROVE/REJECT recommendation

package/content/plugins/audit/plugin.yaml

@@ -1,14 +1,195 @@
 id: audit
-name: Code Audit
-description: Multi-agent audits for quality, security, logic, perf, tests, a11y, arch, API, flows, completeness.
+name: Audit
+description: Code audit skill pack.
 version: 1.0.0
 enabledByDefault: false
 
 depends: []
 
 provides:
-  commands: []
-  skills: []
-  agents: []
+  skills:
+    - id: agileflow-audit
+      dir: skills/agileflow-audit
+  agents:
+    - id: a11y-analyzer-aria
+      path: agents/a11y-analyzer-aria.md
+    - id: a11y-analyzer-forms
+      path: agents/a11y-analyzer-forms.md
+    - id: a11y-analyzer-keyboard
+      path: agents/a11y-analyzer-keyboard.md
+    - id: a11y-analyzer-semantic
+      path: agents/a11y-analyzer-semantic.md
+    - id: a11y-analyzer-visual
+      path: agents/a11y-analyzer-visual.md
+    - id: a11y-consensus
+      path: agents/a11y-consensus.md
+    - id: accessibility
+      path: agents/accessibility.md
+    - id: api-quality-analyzer-conventions
+      path: agents/api-quality-analyzer-conventions.md
+    - id: api-quality-analyzer-docs
+      path: agents/api-quality-analyzer-docs.md
+    - id: api-quality-analyzer-errors
+      path: agents/api-quality-analyzer-errors.md
+    - id: api-quality-analyzer-pagination
+      path: agents/api-quality-analyzer-pagination.md
+    - id: api-quality-analyzer-versioning
+      path: agents/api-quality-analyzer-versioning.md
+    - id: api-quality-consensus
+      path: agents/api-quality-consensus.md
+    - id: api-validator
+      path: agents/api-validator.md
+    - id: arch-analyzer-circular
+      path: agents/arch-analyzer-circular.md
+    - id: arch-analyzer-complexity
+      path: agents/arch-analyzer-complexity.md
+    - id: arch-analyzer-coupling
+      path: agents/arch-analyzer-coupling.md
+    - id: arch-analyzer-layering
+      path: agents/arch-analyzer-layering.md
+    - id: arch-analyzer-patterns
+      path: agents/arch-analyzer-patterns.md
+    - id: arch-consensus
+      path: agents/arch-consensus.md
+    - id: browser-qa
+      path: agents/browser-qa.md
+    - id: code-reviewer
+      path: agents/code-reviewer.md
+    - id: completeness-analyzer-api
+      path: agents/completeness-analyzer-api.md
+    - id: completeness-analyzer-conditional
+      path: agents/completeness-analyzer-conditional.md
+    - id: completeness-analyzer-handlers
+      path: agents/completeness-analyzer-handlers.md
+    - id: completeness-analyzer-imports
+      path: agents/completeness-analyzer-imports.md
+    - id: completeness-analyzer-routes
+      path: agents/completeness-analyzer-routes.md
+    - id: completeness-analyzer-state
+      path: agents/completeness-analyzer-state.md
+    - id: completeness-analyzer-stubs
+      path: agents/completeness-analyzer-stubs.md
+    - id: completeness-consensus
+      path: agents/completeness-consensus.md
+    - id: error-analyzer
+      path: agents/error-analyzer.md
+    - id: flow-analyzer-authorization
+      path: agents/flow-analyzer-authorization.md
+    - id: flow-analyzer-discovery
+      path: agents/flow-analyzer-discovery.md
+    - id: flow-analyzer-errors
+      path: agents/flow-analyzer-errors.md
+    - id: flow-analyzer-feedback
+      path: agents/flow-analyzer-feedback.md
+    - id: flow-analyzer-navigation
+      path: agents/flow-analyzer-navigation.md
+    - id: flow-analyzer-persistence
+      path: agents/flow-analyzer-persistence.md
+    - id: flow-analyzer-wiring
+      path: agents/flow-analyzer-wiring.md
+    - id: flow-consensus
+      path: agents/flow-consensus.md
+    - id: legal-analyzer-a11y
+      path: agents/legal-analyzer-a11y.md
+    - id: legal-analyzer-ai
+      path: agents/legal-analyzer-ai.md
+    - id: legal-analyzer-consumer
+      path: agents/legal-analyzer-consumer.md
+    - id: legal-analyzer-content
+      path: agents/legal-analyzer-content.md
+    - id: legal-analyzer-international
+      path: agents/legal-analyzer-international.md
+    - id: legal-analyzer-licensing
+      path: agents/legal-analyzer-licensing.md
+    - id: legal-analyzer-privacy
+      path: agents/legal-analyzer-privacy.md
+    - id: legal-analyzer-security
+      path: agents/legal-analyzer-security.md
+    - id: legal-analyzer-terms
+      path: agents/legal-analyzer-terms.md
+    - id: legal-consensus
+      path: agents/legal-consensus.md
+    - id: logic-analyzer-edge
+      path: agents/logic-analyzer-edge.md
+    - id: logic-analyzer-flow
+      path: agents/logic-analyzer-flow.md
+    - id: logic-analyzer-invariant
+      path: agents/logic-analyzer-invariant.md
+    - id: logic-analyzer-race
+      path: agents/logic-analyzer-race.md
+    - id: logic-analyzer-type
+      path: agents/logic-analyzer-type.md
+    - id: logic-consensus
+      path: agents/logic-consensus.md
+    - id: perf-analyzer-assets
+      path: agents/perf-analyzer-assets.md
+    - id: perf-analyzer-bundle
+      path: agents/perf-analyzer-bundle.md
+    - id: perf-analyzer-caching
+      path: agents/perf-analyzer-caching.md
+    - id: perf-analyzer-compute
+      path: agents/perf-analyzer-compute.md
+    - id: perf-analyzer-memory
+      path: agents/perf-analyzer-memory.md
+    - id: perf-analyzer-network
+      path: agents/perf-analyzer-network.md
+    - id: perf-analyzer-queries
+      path: agents/perf-analyzer-queries.md
+    - id: perf-analyzer-rendering
+      path: agents/perf-analyzer-rendering.md
+    - id: perf-consensus
+      path: agents/perf-consensus.md
+    - id: qa
+      path: agents/qa.md
+    - id: quality-analyzer-comments
+      path: agents/quality-analyzer-comments.md
+    - id: quality-analyzer-duplication
+      path: agents/quality-analyzer-duplication.md
+    - id: quality-analyzer-naming
+      path: agents/quality-analyzer-naming.md
+    - id: quality-consensus
+      path: agents/quality-consensus.md
+    - id: schema-validator
+      path: agents/schema-validator.md
+    - id: security-analyzer-api
+      path: agents/security-analyzer-api.md
+    - id: security-analyzer-auth
+      path: agents/security-analyzer-auth.md
+    - id: security-analyzer-authz
+      path: agents/security-analyzer-authz.md
+    - id: security-analyzer-deps
+      path: agents/security-analyzer-deps.md
+    - id: security-analyzer-infra
+      path: agents/security-analyzer-infra.md
+    - id: security-analyzer-injection
+      path: agents/security-analyzer-injection.md
+    - id: security-analyzer-input
+      path: agents/security-analyzer-input.md
+    - id: security-analyzer-secrets
+      path: agents/security-analyzer-secrets.md
+    - id: security-consensus
+      path: agents/security-consensus.md
+    - id: test-analyzer-assertions
+      path: agents/test-analyzer-assertions.md
+    - id: test-analyzer-coverage
+      path: agents/test-analyzer-coverage.md
+    - id: test-analyzer-fragility
+      path: agents/test-analyzer-fragility.md
+    - id: test-analyzer-integration
+      path: agents/test-analyzer-integration.md
+    - id: test-analyzer-maintenance
+      path: agents/test-analyzer-maintenance.md
+    - id: test-analyzer-mocking
+      path: agents/test-analyzer-mocking.md
+    - id: test-analyzer-patterns
+      path: agents/test-analyzer-patterns.md
+    - id: test-analyzer-structure
+      path: agents/test-analyzer-structure.md
+    - id: test-consensus
+      path: agents/test-consensus.md
+    - id: testing
+      path: agents/testing.md
+    - id: ui-validator
+      path: agents/ui-validator.md
   hooks: []
   templates: []

package/content/plugins/audit/skills/agileflow-audit/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: agileflow-audit
+version: 1.0.0
+category: agileflow/audit
+description: |
+  Use when the user wants to audit code quality, security, performance,
+  logic, accessibility, legal compliance, test coverage, architecture,
+  or flow integrity. Runs multi-expert analyzer panels and produces
+  prioritized findings with WCAG/OWASP/CWE mappings.
+triggers:
+  keywords:
+    - audit
+    - code review
+    - security review
+    - performance review
+    - accessibility check
+    - logic bugs
+    - flow integrity
+    - test coverage
+    - architecture review
+    - legal compliance
+    - run audit
+    - check my code
+    - find bugs
+    - code quality
+  priority: 60
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/audit.yaml
+  maxEntries: 50
+depends:
+  skills: []
+  plugins: [audit]
+---
+
+# AgileFlow Audit
+
+Multi-domain code audit system. Each audit type runs a panel of
+specialized analyzers then a consensus agent that deduplicates,
+scores, and prioritizes findings.
+
+## When this skill activates
+
+- User asks to audit, review, or check code
+- User wants to find bugs, vulnerabilities, or performance issues
+- User asks about accessibility, legal, or compliance
+- User wants to verify flow integrity or test quality
+- User mentions OWASP, WCAG, CWE, or similar standards
+- User says "audit this story", "did we pass", or "check acceptance criteria" — story completion audit
+- User says "start TDD", "write tests first", or "RED GREEN REFACTOR" — TDD workflow
+
+## Audit types
+
+| Audit         | What it covers                                       |
+| ------------- | ---------------------------------------------------- |
+| Security      | Auth, injection, secrets, OWASP Top 10               |
+| Logic         | Edge cases, race conditions, type safety, invariants |
+| Performance   | Queries, rendering, memory, bundle, caching          |
+| Accessibility | ARIA, keyboard, forms, visual, semantic HTML         |
+| Legal         | GDPR, CCPA, licensing, consumer protection           |
+| Flows         | User journey wiring, navigation, persistence         |
+| Architecture  | Coupling, layering, circular deps, complexity        |
+| Completeness  | Stubs, dead code, missing handlers, orphaned routes  |
+| Quality       | Naming, duplication, comments                        |
+| Test          | Coverage, fragility, mocking, assertions             |
+| API           | REST conventions, versioning, error handling         |
+| Full audit    | Runs all audit types above                           |
+
+## How to guide the user
+
+1. Ask what they just implemented or what concern prompted the audit
+2. Pick the most relevant audit type — don't always run everything
+3. After findings: present P0/P1 issues first, offer to fix them
+4. After fix: suggest re-running the specific audit to confirm
+
+## TDD
+
+The TDD workflow enforces RED → GREEN → REFACTOR phases with hard phase gates. See `workflows/tdd.md` for the step-by-step process.
+
+## Integration
+
+- **agileflow-engineering** — delegate fixing P0/P1 findings after an audit completes; don't leave findings as a list, route them to the right implementor
+- **agileflow-refactor** — route code quality, duplication, and naming findings here; audit identifies, refactor executes
+- **agileflow-test-writer** — route missing test coverage findings here; audit flags the gaps, test-writer fills them
+- **agileflow-accessibility** — the accessibility dimension of the audit feeds into this skill for WCAG-specific remediation guidance
+- **agileflow-performance** — the performance dimension feeds into this skill for profiling, bundle analysis, and optimization work
+- **agileflow-pr-reviewer** — invoke before a PR merge as a lighter alternative to a full audit; use audit for pre-release or milestone sweeps
+- **agileflow-debug** — if an audit finding is unclear or non-reproducible, hand off to debug for root cause analysis
+- **agileflow-delivery** — run the audit as a quality gate before shipping; findings above P1 should block the release
+- **agileflow-adr** — if an audit reveals an architectural problem (circular dependencies, layering violations), document the fix decision as an ADR
+
+## References
+
+Load these files when you need deeper context for the relevant task:
+
+| File                                     | When to load                                                                   |
+| ---------------------------------------- | ------------------------------------------------------------------------------ |
+| `references/owasp-top10.md`              | Running a security audit — maps OWASP categories to code signals and severity  |
+| `references/wcag-criteria.md`            | Running an accessibility audit — WCAG 2.2 criteria with new 2.2 additions      |
+| `references/audit-depth-guide.md`        | Deciding which audit to run and at what depth — quick vs deep vs targeted      |
+| `references/performance-budget-guide.md` | Running a performance audit — Lighthouse thresholds, resource budgets per type |
+| `references/dependency-risk-guide.md`    | Reviewing dependencies — when to upgrade, how to triage CVEs                   |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                     | When to follow                                                             |
+| ------------------------ | -------------------------------------------------------------------------- |
+| `workflows/run-audit.md` | User asks to run any audit — guides them to the right audit type and depth |
+| `workflows/tdd.md`       | User wants to work in TDD mode — RED → GREEN → REFACTOR phases             |