Initial commit

skills/modes/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: modes
+description: Domain-specific development mode guidelines for UI, API, database, integration, migration, and specialized workflows. Each mode provides tailored principles, checklists, and patterns for different types of development work.
+---
+
+# Development Mode Skills
+
+This skill provides domain-specific guidelines that agents activate based on the type of work being performed. Each mode extends core principles with specialized requirements for different development contexts.
+
+## Overview
+
+The mode skills provide specialized guidance for:
+- **UI Mode** (ui.yaml) - Frontend, accessibility, SEO, visual components
+- **API Mode** (api.yaml) - REST/GraphQL endpoints, API design, versioning
+- **Database Mode** (db.yaml) - Schema design, migrations, query optimization
+- **Integration Mode** (integration.yaml) - External service integration, OAuth, webhooks
+- **Migration Mode** (migration.yaml) - Data migration, version upgrades, rollback procedures
+- **Performance Mode** (performance.yaml) - Optimization, caching, load testing
+- **QA Mode** (qa.yaml) - Testing strategies, coverage requirements, test automation
+- **Security Mode** (security.yaml) - Security audits, vulnerability scanning, penetration testing
+- **Release Mode** (release.yaml) - Deployment procedures, release management, rollback
+
+## When to Use
+
+Modes are automatically activated based on work context:
+
+### UI Mode
+- **Used by**: Nova, Skye, Finn
+- **Triggers**: Frontend changes, accessibility updates, SEO optimization
+- **Focus**: Lighthouse scores, ARIA compliance, responsive design
+
+### API Mode
+- **Used by**: Skye, Kai, Mina
+- **Triggers**: Endpoint creation, API versioning, integration work
+- **Focus**: REST/GraphQL standards, documentation, versioning
+
+### Database Mode
+- **Used by**: Leo, Skye, Kai
+- **Triggers**: Schema changes, migrations, query optimization
+- **Focus**: Data integrity, indexing, rollback safety
+
+### Integration Mode
+- **Used by**: Mina, Iris, Kai
+- **Triggers**: External service integration (Stripe, Shopify, AWS, etc.)
+- **Focus**: OAuth flows, webhook handling, error resilience
+
+### Migration Mode
+- **Used by**: Blake, Leo, Kai
+- **Triggers**: Database migrations, version upgrades, data transfers
+- **Focus**: Rollback procedures, data validation, zero-downtime
+
+### Performance Mode
+- **Used by**: Kai, Nova, Theo
+- **Triggers**: Optimization work, performance issues, load testing
+- **Focus**: Caching strategies, bundle optimization, resource usage
+
+### QA Mode
+- **Used by**: Finn, Eden
+- **Triggers**: Test creation, coverage validation, quality gates
+- **Focus**: Unit/integration/E2E tests, coverage thresholds
+
+### Security Mode
+- **Used by**: Iris, Mina, Blake
+- **Triggers**: Security audits, vulnerability scans, auth changes
+- **Focus**: Secret management, SBOM generation, penetration testing
+
+### Release Mode
+- **Used by**: Blake, Eden, Theo
+- **Triggers**: Deployment preparation, release coordination
+- **Focus**: Changelog generation, deployment verification, rollback readiness
+
+## Mode Structure
+
+Each mode YAML file contains:
+
+```yaml
+name: mode-name
+extends: [core-skills]           # Inherited core principles
+description: |
+  Mode-specific description
+used_by: [Agent1, Agent2]        # Which agents use this mode
+triggers:                         # When to activate this mode
+  - trigger_condition_1
+  - trigger_condition_2
+inputs_required:                  # Required context
+  - input_1
+  - input_2
+outputs:                          # Expected deliverables
+  - output_1
+  - output_2
+principles:                       # Mode-specific guidelines
+  - principle_1
+  - principle_2
+checklist:                        # Validation requirements
+  - [ ] checklist_item_1
+  - [ ] checklist_item_2
+patterns:                         # Common solutions
+  - "Pattern description"
+hooks:                            # Integration points
+  - hook_name
+```
+
+## Usage
+
+Agents reference specific modes based on work type:
+
+```markdown
+# Nova working on UI
+See `skills/modes/ui.yaml` for accessibility and performance requirements
+
+# Leo working on database
+See `skills/modes/db.yaml` for migration and schema design guidelines
+
+# Mina integrating Stripe
+See `skills/modes/integration.yaml` for OAuth and webhook patterns
+```
+
+## File Structure
+
+```
+skills/modes/
+├── SKILL.md (this file)
+├── ui.yaml          # Frontend/accessibility/SEO
+├── api.yaml         # REST/GraphQL endpoints
+├── db.yaml          # Database schema/migrations
+├── integration.yaml # External service integration
+├── migration.yaml   # Data migration procedures
+├── performance.yaml # Optimization strategies
+├── qa.yaml          # Testing requirements
+├── security.yaml    # Security audits
+└── release.yaml     # Deployment procedures
+```
+
+## Mode Inheritance
+
+Modes extend core skills:
+- **All modes** inherit from core principles
+- **Specific modes** may extend additional core skills (e.g., ui.yaml extends performance, review-checklist, documentation)
+- **Agents** apply both core and mode-specific guidelines
+
+## Best Practices
+
+1. **Context-aware activation** - Modes activate based on work type, not manual selection
+2. **Layered guidance** - Core principles + mode-specific requirements
+3. **Agent specialization** - Each agent knows which modes to apply
+4. **Validation gates** - Each mode defines success criteria and checklists
+5. **Pattern reuse** - Common solutions documented for consistency
+
+## Integration with Agents
+
+Agents automatically apply relevant modes:
+- **Nova** (UI/UX) → ui.yaml, performance.yaml
+- **Leo** (Database) → db.yaml, migration.yaml
+- **Mina** (Integration) → integration.yaml, security.yaml
+- **Blake** (Release) → release.yaml, qa.yaml
+- **Iris** (Security) → security.yaml, integration.yaml
+- **Finn** (QA) → qa.yaml, performance.yaml
+- **Kai** (Architecture) → api.yaml, db.yaml, performance.yaml
+- **Skye** (Implementation) → ui.yaml, api.yaml, db.yaml (context-dependent)
+
+## Example Workflow
+
+When Nova receives a UI task:
+1. Activates **ui.yaml** mode
+2. Inherits principles from **core/performance.yaml**, **core/review-checklist.yaml**
+3. Applies Lighthouse A11y ≥ 95 requirement
+4. Validates keyboard/screen-reader flows
+5. Checks meta tags and OG/Twitter cards
+6. Measures CLS < 0.1, LCP within budget
+
+This ensures consistent, high-quality output across all UI work.

skills/modes/api.yaml

@@ -0,0 +1,28 @@
+name: api
+extends: [coding-standards, qa, security, documentation]
+description: |
+  Mode skill for API design/implementation and contract governance (REST/GraphQL/gRPC).
+used_by: [Kai, Skye, Leo, Finn, Iris]
+triggers:
+  - new_endpoint
+  - contract_change
+  - latency_budget_defined
+inputs_required:
+  - api_style (REST/GraphQL/gRPC)
+  - contract_source (OpenAPI/SDL/IDL)
+  - non_functional (latency/error budgets, rate limits)
+outputs:
+  - openapi.yaml
+  - api-change-log.md
+principles:
+  - Contract-first: generate server/clients from spec when possible.
+  - Backward-compatibility by default; version when breaking.
+  - Validate and sanitize all inputs at boundaries.
+checklist:
+  - [ ] OpenAPI/SDL updated and validated
+  - [ ] Error model consistent (problem+json or equivalent)
+  - [ ] AuthN/Z documented (scopes/claims)
+  - [ ] Load/perf smoke tests exist
+hooks:
+  - before_pr
+  - before_merge

skills/modes/db.yaml

@@ -0,0 +1,30 @@
+name: db
+extends: [security, documentation]
+description: |
+  Mode skill for relational schemas, migrations, RLS/policies, and type contracts.
+used_by: [Leo, Kai, Skye, Iris]
+triggers:
+  - schema_change
+  - migration_needed
+  - rls_or_policy_change
+inputs_required:
+  - migration_plan (up/down)
+  - data_backfill_strategy
+  - locking_risk_assessment
+  - rls_specs (who can read/write what)
+outputs:
+  - migration.sql
+  - db-changes.md
+  - policy-review.md
+principles:
+  - Small, reversible migrations with clear downtime expectations.
+  - Types drive code; generate types from DB where feasible.
+  - RLS least-privilege and audited.
+checklist:
+  - [ ] Dry-run migration passed in staging snapshot
+  - [ ] Rollback (down) script tested
+  - [ ] RLS/Policies peer-reviewed (Iris)
+  - [ ] Data backfill verified and idempotent
+hooks:
+  - before_pr
+  - before_merge

skills/modes/integration.yaml

@@ -0,0 +1,29 @@
+name: integration
+extends: [security, documentation, qa]
+description: |
+  Mode skill for third-party/platform integrations (Shopify, Sanity, Supabase, AWS, Stripe, etc.).
+used_by: [Mina, Kai, Skye, Iris, Finn]
+triggers:
+  - includes_integrations
+  - needs_oauth_or_webhooks
+  - cross_service_data_flow
+inputs_required:
+  - credentials_location (secret store path)
+  - oauth_scopes
+  - webhook_endpoints_and_retries
+  - rate_limit_and_backoff_strategy
+outputs:
+  - integration_runbook.md
+  - healthcheck.spec.md
+principles:
+  - Least-privilege credentials; rotate regularly.
+  - Retries with jitter; idempotency keys where applicable.
+  - Observability first: health checks and dashboards.
+checklist:
+  - [ ] Secrets from vault (no .env commits)
+  - [ ] OAuth scopes minimized and documented
+  - [ ] Webhook signatures validated; replay protected
+  - [ ] Circuit-breakers / retry policies in place
+hooks:
+  - before_pr
+  - before_merge

skills/modes/migration.yaml

@@ -0,0 +1,29 @@
+name: migration
+extends: [db, release, qa, documentation]
+description: |
+  Mode skill for coordinated changes across code, schema, and data with safe rollout/rollback.
+used_by: [Kai, Leo, Skye, Blake, Finn]
+triggers:
+  - breaking_change
+  - multi_step_rollout
+  - data_backfill_required
+inputs_required:
+  - phased_plan (T+0, T+1, T+2 steps)
+  - observability_checks (metrics/logs)
+  - rollback_switch (feature flag / traffic split)
+outputs:
+  - migration-plan.md
+  - backfill-script.(py|ts|sql)
+  - rollback-plan.md
+principles:
+  - Dark launch → dual-write/dual-read → cutover → cleanup.
+  - Reversible at every step; time-boxed checkpoints.
+  - Communicate windows and fallback.
+checklist:
+  - [ ] Feature flags or traffic router configured
+  - [ ] Dual-read/write verified in staging
+  - [ ] Backfill idempotent with checkpoints
+  - [ ] Cutover + rollback rehearsed
+hooks:
+  - before_merge
+  - before_deploy

skills/modes/performance.yaml

@@ -0,0 +1,27 @@
+name: performance
+extends: [performance]   # from core; this file specializes targets/workflows
+description: |
+  Mode specialization for setting budgets and running perf diagnostics across UI/API.
+used_by: [Nova, Finn, Kai, Theo, Skye]
+triggers:
+  - perf_budget_defined
+  - perf_regression_detected
+  - slo_or_sli_violation
+inputs_required:
+  - target_metrics (TTFB/LCP/CLS/API P95 latency)
+  - baseline_report (Lighthouse/Profiler)
+  - test_scenarios (user journeys / endpoints)
+outputs:
+  - perf-report.md
+  - lighthouse-report.json
+  - traces/
+principles:
+  - Always measure on realistic data and device profiles.
+  - Track budgets in CI; block on critical regression.
+checklist:
+  - [ ] Baseline captured and committed
+  - [ ] CI perf step green with budgets
+  - [ ] Bottleneck hypothesis & fix PR linked
+hooks:
+  - before_merge
+  - after_deploy

skills/modes/qa.yaml

@@ -0,0 +1,27 @@
+name: qa
+extends: [qa]   # from core; specialize suites by change type
+description: |
+  Mode specialization for selecting/maintaining the right automated suites.
+used_by: [Finn, Blake, Theo]
+triggers:
+  - pre_merge
+  - pre_deploy
+  - incident_repro
+inputs_required:
+  - change_scope (ui/api/db/integration)
+  - critical_paths (top user journeys)
+  - perf_targets (if applicable)
+outputs:
+  - test-plan.md
+  - e2e-specs/
+  - smoke-report.md
+principles:
+  - Prioritize high-risk/high-impact paths.
+  - Keep suites fast; parallelize; quarantine flakies.
+checklist:
+  - [ ] Unit + integration pass
+  - [ ] E2E covers critical paths
+  - [ ] Smoke tests green in staging
+hooks:
+  - before_merge
+  - before_deploy

skills/modes/release.yaml

@@ -0,0 +1,27 @@
+name: release
+extends: [release, qa, documentation, security]
+description: |
+  Mode specialization for staging→prod promotion, canary, and rollback orchestration.
+used_by: [Blake, Theo, Finn, Iris]
+triggers:
+  - ready_for_release
+  - stage == 'pre-deploy'
+  - rollback_or_hotfix_needed
+inputs_required:
+  - release_notes
+  - rollout_plan (regions/percentages)
+  - rollback_criteria (metrics/alerts)
+outputs:
+  - changelog.md
+  - release-notes.md
+  - rollout-status.md
+principles:
+  - Canary by default; fast rollback path.
+  - Communicate status; capture evidence artifacts.
+checklist:
+  - [ ] All pre-deploy gates passed (QA/Sec)
+  - [ ] Canary + metrics watch window configured
+  - [ ] Rollback script/steps verified
+hooks:
+  - before_deploy
+  - after_deploy

skills/modes/security.yaml

@@ -0,0 +1,28 @@
+name: security
+extends: [security]   # from core; specialize platform checks
+description: |
+  Mode specialization for platform-aware checks (headers/CSP, IAM, SBOM, supply-chain).
+used_by: [Iris, Mina, Leo, Blake]
+triggers:
+  - deps_changed
+  - sbom_update_needed
+  - contains_secrets
+  - iam_or_policy_change
+inputs_required:
+  - sbom_tool (syft/cyclonedx)
+  - scanning_tool (grype/trivy)
+  - policy_diff (IAM/RLS/CSP)
+outputs:
+  - security-report.md
+  - sbom.json
+principles:
+  - Shift-left: check early; block risky merges.
+  - Signed artifacts; pinned versions.
+checklist:
+  - [ ] SBOM updated and scanned
+  - [ ] Secrets scans pass (no leak/noise triaged)
+  - [ ] CSP/headers validated in staging
+  - [ ] IAM/RLS diffs approved
+hooks:
+  - before_pr
+  - before_merge

skills/modes/ui.yaml

@@ -0,0 +1,33 @@
+name: ui
+extends: [performance, review-checklist, documentation]   # from skills/core
+description: |
+  Mode skill for user-facing UI work: layout, components, A11y, SEO, visual polish.
+  Applies to Next.js/React, Shopify theme (Liquid/JSON), and general frontend stacks.
+used_by: [Nova, Skye, Finn]
+triggers:
+  - touches_ui
+  - user_facing_change
+  - a11y_changes
+  - seo_changes
+inputs_required:
+  - design_reference (Figma/URL/screenshot) optional
+  - target_devices (desktop/mobile)
+  - accessibility_budget (e.g., WCAG 2.1 AA)
+  - seo_targets (title/desc/canonical/open-graph)
+outputs:
+  - ui-change-notes.md
+  - updated-components/
+principles:
+  - Prefer accessible, semantic markup; ARIA only when necessary.
+  - Keep components pure and state minimal; co-locate styles/types.
+  - Enforce design tokens; no magic numbers.
+checklist:
+  - [ ] Lighthouse A11y ≥ 95, Best Practices ≥ 95
+  - [ ] Keyboard and screen-reader flows validated
+  - [ ] Meta tags, canonical, OG/Twitter cards present
+  - [ ] CLS < 0.1, LCP within budget (desktop/mobile targets specified)
+patterns:
+  - "Add an accessible label and role where semantics are insufficient."
+  - "Use CSS logical properties for RTL/i18n readiness."
+hooks:
+  - before_merge