diff --git a/.github/workflows/smoke-tests.yml b/.github/workflows/smoke-tests.yml index d476617..226579e 100644 --- a/.github/workflows/smoke-tests.yml +++ b/.github/workflows/smoke-tests.yml @@ -50,14 +50,42 @@ jobs: errors = [] checked = 0 + skipped = 0 + + # Meta files that don't need frontmatter (by name) + SKIP_FILES = { + "MIGRATION_GUIDE.md", "REFACTORING_SUMMARY.md", "_INDEX.md", + "README.md", "ENHANCEMENT_PLAN.md", "ENHANCEMENTS_SUMMARY.md", + "SKILLS_USAGE_GUIDE.md", "CLAUDE.md", "SUMMARY.txt", + "CLAUDE_MD_UPDATES.md" # Supporting documentation + } for skill_file in Path(".").rglob("*.md"): - # Skip archived and meta files + # Skip archived files if "_archive" in str(skill_file): + skipped += 1 continue - if skill_file.name in ["MIGRATION_GUIDE.md", "REFACTORING_SUMMARY.md", "_INDEX.md", "README.md", "ENHANCEMENT_PLAN.md", "ENHANCEMENTS_SUMMARY.md", "SKILLS_USAGE_GUIDE.md", "CLAUDE.md"]: + + # Skip meta files by name + if skill_file.name in SKIP_FILES: + skipped += 1 continue + # Calculate depth (number of slashes after skills/) + # skills/file.md = depth 1 ✓ + # skills/category/file.md = depth 2 ✓ + # skills/skill/SKILL.md = depth 2 ✓ + # skills/skill/references/file.md = depth 3 ✗ (supporting files) + parts = skill_file.parts + if "skills" in parts: + skills_idx = parts.index("skills") + depth = len(parts) - skills_idx - 1 + + # Skip files at depth 3+ (these are reference/foundation/implementation files) + if depth >= 3: + skipped += 1 + continue + content = skill_file.read_text(encoding='utf-8') checked += 1 @@ -88,7 +116,8 @@ jobs: if not re.match(r'^[a-z0-9-]+$', name): errors.append(f"{skill_file}: Invalid name format '{name}' (must be hyphen-case)") - print(f"Checked {checked} skill files\n") + print(f"Checked: {checked} skill files") + print(f"Skipped: {skipped} supporting/meta files\n") if errors: print("❌ FAILED: Found frontmatter errors:\n") @@ -98,6 +127,6 @@ jobs: print("="*60) sys.exit(1) else: - print("✅ SUCCESS: All frontmatter is valid") + print("✅ SUCCESS: All skill files have valid frontmatter") print("="*60) EOF diff --git a/.github/workflows/validate-dates.yml b/.github/workflows/validate-dates.yml index 73eab7b..78800ea 100644 --- a/.github/workflows/validate-dates.yml +++ b/.github/workflows/validate-dates.yml @@ -40,15 +40,39 @@ jobs: errors = [] checked = 0 + skipped = 0 + + # Meta files that don't need date validation (by name) + SKIP_FILES = { + "MIGRATION_GUIDE.md", "REFACTORING_SUMMARY.md", "_INDEX.md", + "README.md", "ENHANCEMENT_PLAN.md", "ENHANCEMENTS_SUMMARY.md", + "SKILLS_USAGE_GUIDE.md", "CLAUDE.md", "SUMMARY.txt", + "CLAUDE_MD_UPDATES.md" # Supporting documentation + } # Check skills directory for skill_file in Path(".").rglob("*.md"): - # Skip archived files and meta files + # Skip archived files if "_archive" in str(skill_file): + skipped += 1 continue - if skill_file.name in ["MIGRATION_GUIDE.md", "REFACTORING_SUMMARY.md", "_INDEX.md", "README.md", "ENHANCEMENT_PLAN.md", "ENHANCEMENTS_SUMMARY.md", "SKILLS_USAGE_GUIDE.md", "CLAUDE.md"]: + + # Skip meta files by name + if skill_file.name in SKIP_FILES: + skipped += 1 continue + # Calculate depth (number of slashes after skills/) + # Skip files at depth 3+ (these are reference/foundation/implementation files) + parts = skill_file.parts + if "skills" in parts: + skills_idx = parts.index("skills") + depth = len(parts) - skills_idx - 1 + + if depth >= 3: + skipped += 1 + continue + content = skill_file.read_text(encoding='utf-8') matches = re.findall(r'\*\*Last Updated\*\*:\s*(\d{4}-\d{2}-\d{2})', content) @@ -58,7 +82,8 @@ jobs: if date > today: errors.append(f"{skill_file}: Future date {match} (today is {today})") - print(f"Checked {checked} dates across skill files\n") + print(f"Checked: {checked} dates") + print(f"Skipped: {skipped} supporting/meta files\n") if errors: print("❌ FAILED: Found future dates:\n") diff --git a/CLAUDE.md b/CLAUDE.md index dd9d381..262fb2e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -431,6 +431,34 @@ git branch -d feature/name ## 8. Frontend Development +### Elegant Design Skill (RECOMMENDED) + +**ACTIVATE**: `elegant-design/SKILL.md` when building user interfaces that need professional polish + +**Covers**: World-class accessible interfaces, chat/messaging UIs, terminal/code display, streaming content, design systems (shadcn/ui, daisyUI, HeroUI), WCAG compliance, Core Web Vitals optimization + +**Use When**: +- Building web applications with React/Next.js +- Creating developer tools or technical interfaces +- Designing interfaces with chat, terminals, or code display +- Implementing real-time or streaming features +- Ensuring accessibility and responsive design + +**Key Features**: +- **Design Foundation**: Typography (Geist + JetBrains Mono), colors, spacing, layout patterns +- **Interactive Elements**: Chat interfaces, terminal emulators, code syntax highlighting, streaming/loading states, diffs/log viewers +- **Implementation**: Component architecture, WCAG 2.1 AA compliance, performance optimization, comprehensive testing +- **Design Systems**: shadcn/ui (primary), daisyUI, HeroUI with best practices + +**Quick Reference**: +``` +Simple UI: Read foundation/ files → Use design system components +Chat/Terminal/Code: Read SKILL.md → Read interactive/ guides → Implement +Complex interfaces: Follow full workflow (discovery → foundation → interactive → implementation) +``` + +See `skills/elegant-design/SKILL.md` for complete guidance and workflows. + ### Next.js + shadcn/ui (MANDATORY) **Step 1: Browse Blocks FIRST** @@ -494,7 +522,7 @@ open https://ui.shadcn.com/themes **New approach**: Atomic, composable skills (~300 lines avg, <500 line guideline) ### Quality Standards (as of 2025-10-23) -- ✅ **134 skills** with YAML frontmatter (agent_skills_spec.md compliant) +- ✅ **135 skills** with YAML frontmatter (agent_skills_spec.md compliant) - ✅ **0 future dates** - all dates validated by CI - ✅ **Automated testing** - code syntax validation in CI - 🔄 **Size optimization** - 89 skills >500 lines identified for splitting @@ -531,13 +559,13 @@ Read zig-memory-management.md, zig-testing-patterns.md Read beads-workflow.md + beads-context-strategies.md + beads-multi-session-patterns.md ``` -### Skills Catalog (134 Total) +### Skills Catalog (135 Total) -**Core Categories** (76 skills): +**Core Categories** (77 skills): - **API Design** (7): REST, GraphQL, auth/authz, rate limiting, versioning, error handling - **Testing** (6): Unit, integration, e2e, TDD, coverage, performance testing - **Containers** (5): Dockerfile optimization, Compose, security, networking, registries -- **Frontend** (8): React patterns, Next.js App Router, state/data/forms, a11y, performance, SEO +- **Frontend** (9): Elegant design (chat/terminal/code UIs), React patterns, Next.js App Router, state/data/forms, a11y, performance, SEO - **Database** (11): Postgres (optimization, migrations, schema), MongoDB, Redis, Redpanda/Kafka streaming, Apache Iceberg, DuckDB analytics, pooling, ORMs, selection - **Workflow & Tasks** (6): Beads workflow, context strategies, multi-session, dependency management, typed-holes refactoring - **Quality & Content Review** (1): Anti-slop detection and cleanup (text, code, design) @@ -603,7 +631,7 @@ Mobile: mobile/react-native-*.md (4) 4. **Deep dive?** Search `skills/_INDEX.md` by technology/task/problem domain 5. **Emergency?** Read relevant skill directly: `skills/api-*.md`, `skills/cicd/*.md` -**Full catalog**: `skills/_INDEX.md` (134 skills, workflows, search patterns, combinations) +**Full catalog**: `skills/_INDEX.md` (135 skills, workflows, search patterns, combinations) ### Skill Quality Assurance All skills now include: diff --git a/skills/_INDEX.md b/skills/_INDEX.md index 9a740b7..33ead1c 100644 --- a/skills/_INDEX.md +++ b/skills/_INDEX.md @@ -65,7 +65,7 @@ This index catalogs all atomic skills available in the skills system, organized --- -### Frontend Skills (8 skills) +### Frontend Skills (9 skills) | Skill | Use When | Lines | |-------|----------|-------| @@ -77,9 +77,12 @@ This index catalogs all atomic skills available in the skills system, organized | `web-accessibility.md` | WCAG 2.1 AA compliance, ARIA, keyboard navigation | ~310 | | `frontend-performance.md` | Bundle optimization, Core Web Vitals, code splitting | ~330 | | `nextjs-seo.md` | SEO with Next.js, metadata API, structured data | ~250 | +| `elegant-design/SKILL.md` | World-class accessible interfaces, chat/terminal/code UIs, streaming, design systems (shadcn/ui) | ~302 | **Common workflows:** - New Next.js app: `nextjs-app-router.md` → `react-component-patterns.md` → `react-data-fetching.md` +- Elegant UI design: `elegant-design/SKILL.md` → `react-component-patterns.md` → `web-accessibility.md` +- Chat/Terminal/Code UI: `elegant-design/SKILL.md` (read interactive/ guides) → `react-component-patterns.md` - Forms with validation: `react-form-handling.md` → `react-state-management.md` - Production optimization: `frontend-performance.md` → `web-accessibility.md` → `nextjs-seo.md` @@ -501,7 +504,7 @@ This index catalogs all atomic skills available in the skills system, organized **API Design:** Search `api-*.md`, `rest-*.md`, `graphql-*.md` **Testing:** Search `test-*.md`, `unit-*.md`, `integration-*.md`, `e2e-*.md`, `performance-*.md` **Containers/Docker:** Search `docker-*.md`, `container-*.md`, `dockerfile-*.md` -**Frontend/React:** Search `react-*.md`, `nextjs-*.md`, `web-*.md`, `frontend-*.md` +**Frontend/React:** Search `react-*.md`, `nextjs-*.md`, `web-*.md`, `frontend-*.md` | `elegant-design/` for UI/UX design systems **Database/PostgreSQL:** Search `postgres-*.md`, `database-*.md`, `mongodb-*.md`, `redis-*.md`, `orm-*.md` **Swift/SwiftUI:** Search `swiftui-*.md`, `swift-*.md`, `ios-*.md` **Modal.com:** Search `modal-*.md` @@ -602,7 +605,7 @@ This index catalogs all atomic skills available in the skills system, organized **Performance-critical:** `zig-memory-management.md`, `modal-gpu-workloads.md`, `tui-best-practices.md`, `frontend-performance.md`, `postgres-query-optimization.md`, `ci-optimization.md`, `react-native-performance.md` **Async/concurrent:** `swift-concurrency.md`, `bubbletea-architecture.md`, `ratatui-architecture.md`, `react-data-fetching.md`, `stream-processing.md` **Security:** `mtls-implementation.md`, `tailscale-vpn.md`, `network-resilience-patterns.md`, `container-security.md`, `api-authentication.md`, `api-authorization.md`, `ci-security.md`, `infrastructure-security.md` -**UI/UX:** `swiftui-*.md`, `bubbletea-*.md`, `ratatui-*.md`, `react-component-patterns.md`, `web-accessibility.md`, `react-native-*.md` +**UI/UX:** `elegant-design/SKILL.md`, `swiftui-*.md`, `bubbletea-*.md`, `ratatui-*.md`, `react-component-patterns.md`, `web-accessibility.md`, `react-native-*.md` **API Development:** `rest-api-design.md`, `graphql-schema-design.md`, `api-authentication.md`, `api-rate-limiting.md` **DevOps/SRE:** `cicd/*.md`, `infrastructure/*.md`, `observability/*.md`, `cost-optimization.md`, `heroku-*.md`, `netlify-*.md` **Data Engineering:** `data/*.md`, `stream-processing.md`, `batch-processing.md`, `data-validation.md` @@ -662,6 +665,14 @@ This index catalogs all atomic skills available in the skills system, organized 6. `web-accessibility.md` - A11y compliance 7. `nextjs-seo.md` - SEO optimization +### Elegant Interface with Chat/Terminal/Code +1. `elegant-design/SKILL.md` - Design foundation and workflow +2. Read `elegant-design/foundation/` - Typography, colors, spacing, layout +3. Read `elegant-design/interactive/` - Chat, terminals, code display, streaming +4. `react-component-patterns.md` - Component implementation +5. Read `elegant-design/implementation/` - Accessibility, performance, testing +6. `web-accessibility.md` - WCAG compliance validation + ### Production REST API 1. `rest-api-design.md` - API design patterns 2. `api-authentication.md` - JWT/OAuth setup @@ -799,6 +810,9 @@ This index catalogs all atomic skills available in the skills system, organized | Build REST API | rest-api-design.md, api-authentication.md, api-authorization.md | 1→2→3 | | Build GraphQL API | graphql-schema-design.md, api-authentication.md, api-authorization.md | 1→2→3 | | Build Next.js app | nextjs-app-router.md, react-component-patterns.md, react-data-fetching.md | 1→2→3 | +| Design elegant UI | elegant-design/SKILL.md, react-component-patterns.md, web-accessibility.md | 1→2→3 | +| Build chat interface | elegant-design/SKILL.md (read interactive/chat-and-messaging.md), react-component-patterns.md | 1→2 | +| Build terminal/code UI | elegant-design/SKILL.md (read interactive/terminals-and-code.md), react-component-patterns.md | 1→2 | | Setup testing suite | unit-testing-patterns.md, integration-testing.md, e2e-testing.md | 1→2→3 | | Practice TDD | test-driven-development.md, unit-testing-patterns.md | 1→2 | | Containerize app | dockerfile-optimization.md, docker-compose-development.md | 1→2 | @@ -847,17 +861,17 @@ This index catalogs all atomic skills available in the skills system, organized ## Total Skills Count -- **134 atomic skills** across 28 categories +- **135 atomic skills** across 28 categories - **Average 310 lines** per skill - **100% focused** - each skill has single clear purpose - **Cross-referenced** - related skills linked for discoverability ### By Category Breakdown -**Core Foundation** (76 skills): +**Core Foundation** (77 skills): - API Design: 7 skills - Testing: 6 skills - Containers: 5 skills -- Frontend: 8 skills +- Frontend: 9 skills (including elegant-design) - Database: 11 skills - Workflow & Task Management: 6 skills (including typed-holes refactoring) - Quality & Content Review: 1 skill (anti-slop detection and cleanup) @@ -907,5 +921,5 @@ See `MIGRATION_GUIDE.md` for detailed mapping. --- **Last Updated:** 2025-10-23 -**Total Skills:** 134 +**Total Skills:** 135 **Format Version:** 1.0 (Atomic) diff --git a/skills/elegant-design/SKILL.md b/skills/elegant-design/SKILL.md index d5e2924..a5857b1 100644 --- a/skills/elegant-design/SKILL.md +++ b/skills/elegant-design/SKILL.md @@ -1,5 +1,5 @@ --- -name: Designing Elegant Interfaces +name: elegant-design description: Create world-class, accessible, responsive interfaces with sophisticated interactive elements including chat, terminals, code display, and streaming content. Use when building user interfaces that need professional polish and developer-focused features. ---