@geraldmaron/construct 1.0.0

package/skills/frontend-design/state-management.md

@@ -0,0 +1,118 @@
+<!--
+skills/frontend-design/state-management.md — Frontend State Management — Use this skill when choosing state management tools, structuring application sta
+
+Use this skill when choosing state management tools, structuring application state, or debugging state issues. ## State Categories
+-->
+# Frontend State Management
+
+Use this skill when choosing state management tools, structuring application state, or debugging state issues.
+
+## State Categories
+
+| Category | Examples | Recommended Approach |
+|---|---|---|
+| Server state | API data, cached queries | TanStack Query, SWR, tRPC |
+| Client state | Theme, sidebar open, wizard step | Zustand, Jotai, signals, context |
+| URL state | Filters, sort, page, active tab | Router / URL search params |
+| Form state | Input values, validation, dirty | React Hook Form, Formik, native |
+| Transient state | Hover, focus, animation progress | Component-local useState/ref |
+
+- Do not duplicate server state into client stores
+- Do not store derived values; compute them
+
+## Server State
+
+### Stale-While-Revalidate
+- Return cached data immediately; refetch in the background
+- Configurable stale time and cache time
+- Background refetch on window focus, reconnect, and intervals
+- Optimistic updates for responsive UI
+
+### Query Keys
+- Structured keys that include all variables: `['users', { page, filter }]`
+- Invalidate related queries after mutations
+- Prefetch data for likely next actions (hover, pagination)
+
+### Error and Loading States
+- Distinguish: idle, loading, error, success
+- Show skeleton or placeholder during initial load
+- Show stale data with background indicator during refetch
+- Retry failed requests with exponential backoff
+
+## Client State
+
+### Zustand
+- Small, focused stores per domain
+- Actions colocated with state in the store
+- Selectors for derived data and render optimization
+- Middleware: persist, devtools, immer for immutable updates
+
+### Jotai / Signals
+- Atomic state: each piece of state is an independent atom
+- Derived atoms compute from other atoms
+- Fine-grained reactivity: only re-renders components that use changed atoms
+- Good for: settings, preferences, feature flags
+
+### Context
+- Use for low-frequency updates: theme, locale, user identity
+- Avoid for high-frequency updates (causes re-renders of entire subtree)
+- Split contexts by concern; do not put everything in one provider
+- Combine with `useMemo` to prevent unnecessary re-renders
+
+## URL State
+
+### What Belongs in the URL
+- Filters, search query, sort order, pagination
+- Active tab, selected item, modal open state
+- Anything a user should be able to share or bookmark
+
+### Implementation
+- Read from URL search params; write updates to the URL
+- Treat the URL as the source of truth
+- Validate URL params; fall back to defaults for invalid values
+- Use `URLSearchParams` API or a routing library's hooks
+
+## Form State
+
+### Controlled vs Uncontrolled
+- Controlled: React state drives the input value; use for complex validation
+- Uncontrolled: DOM owns the value; access via ref on submit; simpler, faster
+- Form libraries (React Hook Form) offer uncontrolled performance with controlled DX
+
+### Validation
+- Client-side for immediate feedback; server-side for security
+- Validate on blur for individual fields; on submit for the full form
+- Zod or Yup for schema-based validation shared with backend
+- Show errors inline, next to the field, in context
+
+## State Synchronization
+
+### Optimistic Updates
+1. Snapshot current state
+2. Apply the expected change immediately
+3. Send the mutation to the server
+4. On success: confirm or refetch
+5. On failure: rollback to snapshot and show error
+
+### Pessimistic Updates
+1. Send the mutation
+2. Show loading indicator
+3. Update UI with server response
+- Use when: the operation is complex, the server may reject, or correctness is critical
+
+## Debugging State
+
+- React DevTools for component state and context
+- Zustand/Jotai devtools middleware
+- TanStack Query DevTools for server state
+- `console.trace` to find where state changes originate
+- Time-travel debugging with Redux DevTools protocol
+
+## Anti-Patterns
+
+- Global store for everything (mixing server, client, form, and URL state)
+- Duplicating server data into client stores (stale data, sync bugs)
+- Storing derived data instead of computing it
+- Context for high-frequency state (causes unnecessary re-renders)
+- Prop drilling through many levels instead of lifting state or using context
+- Mutating state directly instead of creating new references

package/skills/frontend-design/ui-aesthetics.md

@@ -0,0 +1,102 @@
+<!--
+skills/frontend-design/ui-aesthetics.md — UI Aesthetics — Use this skill when making visual design decisions: color, typography, layout, s
+
+Use this skill when making visual design decisions: color, typography, layout, spacing, and visual hierarchy. ## Color
+-->
+# UI Aesthetics
+
+Use this skill when making visual design decisions: color, typography, layout, spacing, and visual hierarchy.
+
+## Color
+
+### System Design
+- Define a palette with semantic roles: primary, secondary, surface, text, error, warning, success
+- Use perceptually uniform color spaces (OKLCH, OKLAB) for consistent contrast and harmony
+- 60-30-10 rule: dominant surface, secondary accent, tertiary highlight
+- Ensure WCAG AA contrast ratios: 4.5:1 for normal text, 3:1 for large text
+
+### Application
+- Color communicates hierarchy: brightest/most saturated draws attention first
+- Limit palette to 3-5 hues; vary lightness and saturation for range
+- Use opacity and surface layering to create depth
+- Test both light and dark themes if both are supported; do not auto-invert
+- Avoid pure black (#000) on white (#fff); reduce contrast slightly for comfort
+
+## Typography
+
+### Selection
+- Maximum two typeface families per project
+- Pair a serif and sans-serif, or two weights of one family
+- Ensure readability at body size (16px minimum for body text)
+- License fonts correctly; subset to used glyphs for performance
+
+### Scale
+- Use a modular scale (1.25, 1.333, 1.5 ratio) for consistent sizing
+- Fluid type with `clamp()`: `font-size: clamp(1rem, 0.9rem + 0.5vw, 1.25rem)`
+- Limit to 5-6 distinct sizes
+- Line height: 1.4-1.6 for body, 1.1-1.2 for headings
+- Measure (line length): 45-75 characters for body text
+
+### Hierarchy
+- Size contrast between heading levels: at least 1.25x step
+- Weight contrast: regular body, semibold subheads, bold headlines
+- Use case, spacing, and color as secondary hierarchy signals
+- Avoid all-caps for more than short labels
+
+## Spacing
+
+### System
+- Define a spacing scale: 4, 8, 12, 16, 24, 32, 48, 64, 96 (or similar)
+- Use consistent spacing tokens throughout
+- Larger spacing between unrelated groups; tighter within related items
+- White space is a design element, not wasted space
+
+### Rhythm
+- Vertical rhythm: consistent baseline grid for text and components
+- Horizontal rhythm: align to a column grid (8, 12, or 16 columns)
+- Irregular spacing breaks rhythm intentionally for emphasis
+
+## Layout
+
+### Hierarchy
+- Visual weight: size, color, contrast, whitespace, and position create hierarchy
+- Most important element is largest, highest contrast, or most isolated
+- Progressive disclosure: show overview first, detail on demand
+- F-pattern or Z-pattern for content scanning
+
+### Grid
+- CSS Grid for two-dimensional layouts
+- Flexbox for one-dimensional alignment
+- Break the grid intentionally for editorial emphasis
+- Responsive: define breakpoints by content, not by device
+
+### Composition
+- Bento layouts for dashboard-style content
+- Asymmetric layouts for editorial content
+- Card-based layouts for scannable collections
+- Full-bleed sections for immersive moments
+
+## Depth and Surface
+
+- Layer surfaces with elevation: background < card < modal < toast
+- Shadows should be soft, directional, and consistent with a single light source
+- Blur and transparency for glassmorphic surfaces (use sparingly)
+- Border and divider lines: thin (1px), low contrast, used to separate not decorate
+
+## Motion
+
+- Motion clarifies transitions and relationships
+- Duration: 150ms for micro-interactions, 300ms for transitions, 500ms+ for choreographed sequences
+- Easing: ease-out for entrances, ease-in for exits, ease-in-out for state changes
+- Animate compositor-friendly properties: transform, opacity, clip-path
+- Respect `prefers-reduced-motion`
+
+## Quality Checklist
+
+- [ ] Clear visual hierarchy: can you identify primary, secondary, and tertiary elements?
+- [ ] Consistent spacing rhythm throughout
+- [ ] Color palette is cohesive with semantic meaning
+- [ ] Typography pairing is intentional and readable
+- [ ] Depth and surface use supports hierarchy
+- [ ] No orphaned or floating elements without visual anchoring
+- [ ] Design looks intentional, not templated

package/skills/frontend-design/ux-principles.md

@@ -0,0 +1,126 @@
+<!--
+skills/frontend-design/ux-principles.md — UX Principles — Use this skill when designing user flows, evaluating usability, or planning info
+
+Use this skill when designing user flows, evaluating usability, or planning information architecture. ## Core Heuristics
+-->
+# UX Principles
+
+Use this skill when designing user flows, evaluating usability, or planning information architecture.
+
+## Core Heuristics
+
+### Visibility of System Status
+- Users should always know what is happening
+- Loading states, progress indicators, success/error feedback
+- Show the current state of interactive elements (selected, disabled, active)
+
+### Match Between System and Real World
+- Use language and concepts familiar to the user
+- Follow real-world conventions for order and grouping
+- Icons and metaphors should be universally understood or labeled
+
+### User Control and Freedom
+- Undo and redo for destructive actions
+- Clear exit points from flows and modals
+- Back navigation that preserves state
+- Confirmation for irreversible actions; skip confirmation for reversible ones
+
+### Consistency and Standards
+- Same action, same result, every time
+- Follow platform conventions (native app vs web vs mobile)
+- Internal consistency: identical patterns across your own product
+
+### Error Prevention
+- Constraints: disable invalid actions, limit input ranges
+- Defaults: prefill with safe, common values
+- Confirmation: warn before destructive actions
+- Inline validation: immediate feedback on input errors
+
+### Recognition Over Recall
+- Visible options and actions; do not require memorization
+- Recently used items, search suggestions, autocomplete
+- Breadcrumbs and navigation landmarks
+
+### Flexibility and Efficiency
+- Keyboard shortcuts for power users
+- Customizable workflows where users have varying needs
+- Progressive disclosure: simple by default, advanced on demand
+
+### Aesthetic and Minimalist Design
+- Remove elements that do not serve the user's task
+- Information hierarchy: most important content first
+- White space directs attention; clutter diffuses it
+
+### Help Users Recognize and Recover from Errors
+- Error messages in plain language, not codes
+- Identify what went wrong and suggest next steps
+- Preserve user input after errors; do not clear the form
+
+### Help and Documentation
+- Contextual help at the point of need
+- Searchable documentation
+- Onboarding for first-time users; dismissable for returning users
+
+## Information Architecture
+
+### Organization
+- Group related items; separate unrelated items
+- Use familiar categories and labels
+- Card sorting (open and closed) to validate groupings
+- Tree testing to validate navigation structure
+
+### Navigation
+- Primary navigation: 5-7 top-level items maximum
+- Breadcrumbs for hierarchical content
+- Search for content-heavy applications
+- Consistent navigation across all pages
+
+### Labeling
+- Action labels describe the outcome: "Save Changes" not "Submit"
+- Navigation labels match page titles
+- Avoid jargon; test labels with real users
+
+## User Flows
+
+### Flow Design
+- Map the happy path first, then error and edge cases
+- Minimize steps to complete the primary task
+- Show progress in multi-step flows
+- Allow saving and resuming long flows
+- Exit points should not lose work
+
+### Forms
+- One column layout for most forms
+- Group related fields with visual separation
+- Label above input for scannability
+- Required vs optional clearly marked
+- Inline validation on blur, not on every keystroke
+- Smart defaults reduce input effort
+
+## Responsive Design
+
+- Content-first: design for the content, then adapt to viewports
+- Mobile-first: start with the smallest viewport, enhance upward
+- Touch targets: minimum 44x44px on mobile
+- Thumb zone: primary actions within easy reach on mobile
+- Test at real breakpoints: 320, 375, 768, 1024, 1440
+
+## Accessibility as UX
+
+- Keyboard navigation for all interactive elements
+- Focus indicators that are visible and intentional
+- Color is never the only way to convey information
+- Text alternatives for non-text content
+- Reduced motion mode respected
+- Screen reader testing with VoiceOver and NVDA
+
+## Research Methods
+
+| Method | When |
+|---|---|
+| User interviews | Understanding needs and context |
+| Usability testing | Validating a design with real users |
+| A/B testing | Choosing between design variants with data |
+| Analytics | Understanding actual usage patterns |
+| Card sorting | Organizing content and navigation |
+| Heuristic evaluation | Expert review against known principles |

package/skills/quality-gates/review-work.md

@@ -0,0 +1,90 @@
+<!--
+skills/quality-gates/review-work.md — Parallel Adversarial Review — Use this methodology when a change needs rigorous pre-merge validation. Five ind
+
+Use this methodology when a change needs rigorous pre-merge validation. Five independent review roles run concurrently. All must pass. ## When to use
+-->
+# Parallel Adversarial Review
+
+Use this methodology when a change needs rigorous pre-merge validation. Five independent review roles run concurrently. All must pass.
+
+## When to use
+
+- Changes to auth, payments, or security-sensitive paths
+- New public APIs or external integrations
+- Architecture changes touching multiple modules
+- Any change requested via `/work:parallel-review`
+- When the `cx-reviewer` determines a change warrants deeper scrutiny
+
+## The 5 Review Roles
+
+### 1. Correctness (cx-reviewer)
+- Does the code do what it claims?
+- Are there logic bugs, off-by-ones, or incorrect control flow?
+- Does it handle nil/null/empty/zero correctly?
+- Are error paths exercised?
+
+### 2. Security (cx-security)
+- Injection risks (SQL, command, LDAP, XPath)
+- Authentication and authorization gaps
+- Sensitive data in logs, responses, or error messages
+- Unvalidated external input
+- Secret exposure (hardcoded keys, environment leakage)
+- SSRF, path traversal, CSRF
+
+### 3. Test Coverage (cx-qa)
+- What behaviors have no test coverage?
+- Which edge cases are untested?
+- Are tests verifying behavior or just implementation?
+- Would these tests catch a regression if the implementation changed?
+
+### 4. Assumptions (cx-devil-advocate)
+- What are we assuming that could be wrong?
+- What happens at scale or under load?
+- What external dependencies could fail?
+- What invariants does this break?
+- What's the blast radius if this is wrong?
+
+### 5. Quality (cx-accessibility for UI; cx-trace-reviewer for non-UI)
+
+**UI changes — cx-accessibility:**
+- Keyboard navigation
+- Screen reader compatibility
+- Color contrast and focus visibility
+- Reduced motion support
+
+**Non-UI changes — cx-trace-reviewer:**
+- N+1 queries or unbounded loops
+- Memory or connection leaks
+- Missing caching for expensive operations
+- Latency impact on hot paths
+
+## Merge Gate Rules
+
+| Severity | Action |
+|---|---|
+| CRITICAL | Block. Fix before proceeding. |
+| HIGH | Block. Fix before proceeding. |
+| MEDIUM | Acknowledge. Document why it's acceptable or fix it. |
+| LOW | Informational. No action required. |
+
+## Output Format
+
+```
+[CORRECTNESS] PASS | FAIL
+- [HIGH] description of finding
+
+[SECURITY] PASS | FAIL
+- [CRITICAL] description of finding
+
+[COVERAGE] PASS | FAIL
+- [MEDIUM] description of finding
+
+[ASSUMPTIONS] PASS | FAIL
+- [LOW] description of finding
+
+[ACCESSIBILITY|PERFORMANCE] PASS | FAIL
+- [MEDIUM] description of finding
+
+VERDICT: MERGE READY | BLOCKED
+Blocking findings: (list if BLOCKED)
+```

package/skills/quality-gates/verify-change.md

@@ -0,0 +1,94 @@
+<!--
+skills/quality-gates/verify-change.md — Verify Change — Use this skill to analyze the impact of code changes and verify documentation an
+
+Use this skill to analyze the impact of code changes and verify documentation and tests are in sync. ## Change Inventory
+-->
+# Verify Change
+
+Use this skill to analyze the impact of code changes and verify documentation and tests are in sync.
+
+## Change Inventory
+
+1. List all files modified, added, or deleted
+2. Categorize each change: feature, fix, refactor, config, test, docs
+3. Identify the blast radius: what modules, APIs, or surfaces are affected
+
+## Breaking Change Detection
+
+- [ ] Public API signatures unchanged or versioned
+- [ ] Database schema changes have a migration
+- [ ] Configuration keys unchanged or explicitly migrated
+- [ ] Environment variables documented if added or renamed
+- [ ] Event/message contracts unchanged or versioned
+- [ ] CLI flags and arguments preserved or deprecated gracefully
+
+**Severity**: Silent breaking change = Critical. Undocumented migration = High.
+
+## Dependency Impact
+
+- [ ] No circular dependency introduced
+- [ ] Import graph depth not significantly increased
+- [ ] Shared utilities not modified in ways that affect other consumers
+- [ ] New dependencies justified and audited
+- [ ] Lock file updated consistently with manifest
+
+**Severity**: Circular dependency = High. Unjustified new dependency = Medium.
+
+## Test Sync
+
+- [ ] New code paths have corresponding tests
+- [ ] Modified code paths have updated tests
+- [ ] Deleted code has corresponding test removal
+- [ ] No tests reference removed or renamed identifiers
+- [ ] Edge cases from the change are covered
+- [ ] Test coverage did not decrease
+
+**Severity**: New path without test = High. Stale test = Medium.
+
+## Documentation Sync
+
+- [ ] README updated if public interface changed
+- [ ] API documentation reflects new or modified endpoints
+- [ ] Inline comments updated if behavior changed
+- [ ] Migration guides written for breaking changes
+- [ ] Core docs updated for user-visible or architectural changes (`.cx/context.*`, `.cx/workflow.json`, `docs/README.md`, `docs/architecture.md`)
+- [ ] Architecture decision records created for significant shifts
+
+**Severity**: Stale API docs = High. Missing core-doc update for project reality changes = High. Stale comment = Low.
+
+## Configuration Sync
+
+- [ ] Environment variable additions documented
+- [ ] Default values are safe for all environments
+- [ ] Feature flags added for risky changes
+- [ ] CI/CD pipeline updated if build steps changed
+
+**Severity**: Missing env var docs = High. Unsafe default = High.
+
+## Rollback Safety
+
+- [ ] Database migrations are reversible
+- [ ] Feature flags allow disabling the change in production
+- [ ] No destructive data operations without confirmation
+- [ ] Deployment can be rolled back without data loss
+
+**Severity**: Irreversible migration = Critical. No rollback path = High.
+
+## Review Checklist
+
+Before approving the change:
+
+1. Run `git diff` against the base branch to see the full scope
+2. Verify each category above
+3. Flag any item that is not addressed
+4. Confirm all CI checks pass
+5. Verify the change works in a representative environment
+
+## Severity Reference
+
+| Level | Meaning | Action |
+|---|---|---|
+| Critical | Breaking change or data risk | Must fix before merge |
+| High | Missing coverage or stale docs | Should fix before merge |
+| Medium | Minor drift or gap | Fix when practical |
+| Low | Suggestion | Optional |

package/skills/quality-gates/verify-module.md

@@ -0,0 +1,96 @@
+<!--
+skills/quality-gates/verify-module.md — Verify Module — Use this skill to check that a module or package is structurally complete and re
+
+Use this skill to check that a module or package is structurally complete and ready for use. ## Exports
+-->
+# Verify Module
+
+Use this skill to check that a module or package is structurally complete and ready for use.
+
+## Exports
+
+- [ ] Public API is explicitly exported (barrel file, `__init__.py`, `mod.rs`, etc.)
+- [ ] Internal helpers are not exposed in the public surface
+- [ ] Export names are stable and follow project naming conventions
+- [ ] Re-exports are intentional, not accidental leaks
+
+**Severity**: Accidental internal export = High. Missing public export = High.
+
+## Types
+
+- [ ] All public functions have typed parameters and return values
+- [ ] Shared data structures have explicit type definitions
+- [ ] No use of `any` or equivalent without documented justification
+- [ ] Nullable fields are explicitly marked and handled
+- [ ] Generic types are constrained appropriately
+
+**Severity**: Untyped public API = High. Unconstrained generic = Medium.
+
+## Tests
+
+- [ ] Unit tests exist for all public functions
+- [ ] Edge cases covered: empty input, null, boundary values, error paths
+- [ ] Tests are colocated or clearly mapped to the module
+- [ ] Test file naming follows project convention
+- [ ] Coverage meets minimum threshold (80%)
+- [ ] Tests run independently without shared mutable state
+
+**Severity**: No tests for public function = High. Below coverage = Medium.
+
+## Error Handling
+
+- [ ] All error conditions documented or typed (error types, result types)
+- [ ] Errors include enough context for callers to act
+- [ ] No panics or unhandled exceptions in library code
+- [ ] Async errors propagated correctly
+- [ ] Resource cleanup handled in all exit paths
+
+**Severity**: Unhandled panic in library = Critical. Missing error context = Medium.
+
+## Documentation
+
+- [ ] README exists with: purpose, installation, usage example, API summary
+- [ ] Public functions have doc comments explaining behavior, not implementation
+- [ ] Parameters and return values described
+- [ ] Side effects documented
+- [ ] Examples are runnable and correct
+
+**Severity**: No README = Medium. No doc comments on public API = Medium.
+
+## Dependencies
+
+- [ ] Only necessary dependencies imported
+- [ ] No circular dependencies with sibling modules
+- [ ] External dependencies pinned to compatible ranges
+- [ ] No vendored code without justification
+
+**Severity**: Circular dependency = High. Unnecessary dependency = Low.
+
+## Structure
+
+- [ ] Single responsibility: module does one coherent thing
+- [ ] Files within the module are organized by concern
+- [ ] No file exceeds 800 lines
+- [ ] Entry point is obvious (index, main, mod, __init__)
+- [ ] Internal structure matches project conventions
+
+**Severity**: Mixed responsibilities = High. Oversized file = Medium.
+
+## Configuration
+
+- [ ] Configurable values externalized (not hardcoded)
+- [ ] Defaults are safe and documented
+- [ ] Required configuration fails fast with clear error on missing values
+
+**Severity**: Hardcoded config = Medium. Silent missing config = High.
+
+## Completeness Checklist
+
+A module is ready when all of these are true:
+
+1. Public API is typed, exported, and documented
+2. Tests exist and pass with adequate coverage
+3. Errors are handled and propagated correctly
+4. Dependencies are minimal and justified
+5. Structure follows project conventions
+6. README provides enough context to use the module without reading source