class-ai-agent 1.4.0 → 1.5.0

package/.agents/skills/ui-ux-pro-max/scripts/search.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography
+Stacks: html-tailwind, react, nextjs
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help="Stack-specific search (html-tailwind, react, nextjs)")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query, 
+            args.project_name, 
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/.agents/workflows/build.md

@@ -0,0 +1,132 @@
+---
+description: "Implement tasks incrementally using TDD and vertical slices"
+---
+
+# /build — Incremental Implementation
+
+> "The simplest thing that could work."
+
+## Purpose
+
+Implement tasks one at a time using Test-Driven Development. Each increment leaves the system in a working, testable state.
+
+## Prerequisites
+
+- A plan exists (`tasks/todo.md`)
+- Understanding of task acceptance criteria
+
+## Workflow
+
+### For Each Task
+
+#### Step 1: Load Context
+
+```
+1. Read `.agent/SESSION.md` if present (or run `/resume` at session start)
+2. Read the task's acceptance criteria from `tasks/todo.md`
+3. Identify relevant existing code and patterns
+4. Understand types and interfaces involved
+```
+
+#### Step 2: RED — Write Failing Test
+
+```javascript
+// Write a test that describes expected behavior
+// This test MUST fail initially
+
+describe('createTask', () => {
+  it('should create a task with title and return id', async () => {
+    const result = await createTask({ title: 'Test' });
+    expect(result.id).toBeDefined();
+    expect(result.title).toBe('Test');
+  });
+});
+```
+
+Run test — confirm it **fails**.
+
+#### Step 3: GREEN — Minimal Implementation
+
+```javascript
+// Write the MINIMUM code to pass the test
+// No extra features, no premature optimization
+
+async function createTask({ title }) {
+  const task = await db.task.create({ data: { title } });
+  return task;
+}
+```
+
+Run test — confirm it **passes**.
+
+#### Step 4: REFACTOR — Improve Code Quality
+
+```javascript
+// Clean up while keeping tests green
+// - Improve naming
+// - Extract helpers if needed
+// - Remove duplication
+```
+
+Run tests — confirm they **still pass**.
+
+#### Step 5: Verify & Commit
+
+```bash
+# Run full test suite
+npm test
+
+# Run build
+npm run build
+
+# Commit with clear message
+git add .
+git commit -m "feat(tasks): add createTask function"
+```
+
+#### Step 6: Mark Complete
+
+Update `tasks/todo.md` and `.agent/SESSION.md` (**Done**, **In progress**, **Next**):
+```markdown
+- [x] Task 1.1: Create task endpoint
+```
+
+### Rules
+
+| Rule | Why |
+|------|-----|
+| **100-line limit** | Test before writing more than ~100 lines |
+| **Touch only what's needed** | Don't refactor adjacent code |
+| **Keep it building** | Project must compile after each increment |
+| **Feature flags** | Use flags for incomplete features that need merging |
+| **Rollback-friendly** | Each increment should be independently revertable |
+
+### When Stuck
+
+If a step fails:
+
+1. **Stop** — Don't push through broken code
+2. **Diagnose** — Use `/debug` to find root cause
+3. **Fix** — Address the actual problem
+4. **Guard** — Add test to prevent recurrence
+5. **Resume** — Continue from where you stopped
+
+## Red Flags
+
+Stop and reassess if you find yourself:
+
+- Writing > 100 lines without testing
+- Mixing unrelated changes in one commit
+- Expanding scope mid-task
+- Breaking the build between increments
+- Creating abstractions "for later"
+
+## Output
+
+- Working, tested code
+- Updated `tasks/todo.md` with completed items
+- Clean git history with atomic commits
+
+## Next Step
+
+After all tasks complete, run `/review` for final quality check.

package/.agents/workflows/debug.md

@@ -0,0 +1,242 @@
+---
+description: "Systematic debugging and error recovery — find root cause, not symptoms"
+---
+
+# /debug — Debugging & Error Recovery
+
+> "Fix root causes, not symptoms."
+
+## Purpose
+
+Systematically diagnose and fix errors. Stop feature work, preserve evidence, find root cause, add guards, then resume.
+
+## The Stop-the-Line Rule
+
+When unexpected failures occur:
+
+1. **STOP** — Halt feature work immediately
+2. **PRESERVE** — Save error messages, logs, stack traces
+3. **DIAGNOSE** — Follow the 6-step triage process
+4. **FIX** — Address root cause, not symptoms
+5. **GUARD** — Add tests to prevent recurrence
+6. **RESUME** — Only continue after verification; update `.agent/SESSION.md` with root cause, guard tests, and **Next**
+
+---
+
+## 6-Step Triage Process
+
+### Step 1: Reproduce
+
+Make the failure happen reliably.
+
+```bash
+# Run the failing test
+npm test -- --grep "failing test name"
+
+# Or reproduce manually with specific steps
+```
+
+**If not reproducible**, investigate:
+- Timing/race conditions
+- Environment differences (dev vs CI)
+- State leakage between tests
+- Random/flaky behavior
+
+### Step 2: Localize
+
+Identify which layer fails:
+
+| Layer | Symptoms |
+|-------|----------|
+| **UI/Frontend** | Render errors, missing elements, wrong display |
+| **API/Backend** | HTTP errors, wrong responses, timeout |
+| **Database** | Query errors, constraint violations, missing data |
+| **Build** | Compilation errors, missing dependencies |
+| **External** | Third-party API failures, network issues |
+| **Test itself** | Flaky assertion, wrong expectations |
+
+**Use `git bisect` for regressions:**
+
+```bash
+git bisect start
+git bisect bad HEAD
+git bisect good <last-known-good-commit>
+# Git will guide you to the breaking commit
+```
+
+### Step 3: Reduce
+
+Strip away unrelated elements:
+
+```javascript
+// Original complex failing code
+const result = await complexFunction(
+  await getConfig(),
+  await fetchData(),
+  processOptions(opts)
+);
+
+// Reduced to find the problem
+const config = await getConfig();
+console.log('config:', config);  // Check each step
+
+const data = await fetchData();
+console.log('data:', data);
+
+const result = await complexFunction(config, data, opts);
+```
+
+### Step 4: Fix Root Cause
+
+**Fix the actual problem, not the symptom:**
+
+| Symptom | Bad Fix | Good Fix |
+|---------|---------|----------|
+| Duplicate list items | Dedupe in UI | Fix query returning duplicates |
+| Null reference error | Add `?.` everywhere | Ensure data is loaded before access |
+| Slow API response | Increase timeout | Optimize the query |
+| Flaky test | Add retry logic | Fix the race condition |
+
+### Step 5: Guard Against Recurrence
+
+Write a test that catches this specific failure:
+
+```javascript
+it('should not return duplicate items (regression #123)', async () => {
+  // Setup that caused the original bug
+  await createOrder({ items: [item, item] });
+  
+  // The query that was returning duplicates
+  const result = await getOrderItems();
+  
+  // Guard: ensure no duplicates
+  const ids = result.map(r => r.id);
+  expect(ids).toEqual([...new Set(ids)]);
+});
+```
+
+### Step 6: Verify End-to-End
+
+```bash
+# Run the specific test
+npm test -- --grep "regression"
+
+# Run full test suite
+npm test
+
+# Run build
+npm run build
+
+# Manual verification if needed
+```
+
+---
+
+## Error-Specific Triage Trees
+
+### Test Failure
+
+```
+Test fails
+├── Assertion error
+│   ├── Expected value wrong → Check test expectation
+│   └── Actual value wrong → Debug implementation
+├── Runtime error
+│   ├── ReferenceError → Check imports, variable names
+│   ├── TypeError → Check types, null checks
+│   └── NetworkError → Check test setup, mocks
+└── Timeout
+    ├── Async not awaited → Add missing await
+    └── Infinite loop → Check loop conditions
+```
+
+### Build Error
+
+```
+Build fails
+├── TypeScript error
+│   ├── Type mismatch → Fix types or add assertion
+│   └── Missing import → Add import statement
+├── Module not found
+│   ├── Package missing → npm install
+│   └── Path wrong → Fix import path
+└── Syntax error
+    └── Check recent changes → git diff
+```
+
+### Runtime Error
+
+```
+Runtime error
+├── API returns error
+│   ├── 4xx → Client issue, check request
+│   └── 5xx → Server issue, check logs
+├── CORS error
+│   └── Check server CORS config
+├── Undefined/null
+│   └── Add loading state or null check
+└── Network timeout
+    └── Check connectivity, increase timeout
+```
+
+---
+
+## Debugging Tools
+
+### Console Logging (Temporary)
+
+```javascript
+// Add strategic logs
+console.log('[DEBUG] Input:', input);
+console.log('[DEBUG] After transform:', result);
+
+// Remove all debug logs before commit
+git diff | grep console.log
+```
+
+### Node Inspector
+
+```bash
+# Debug Node.js
+node --inspect-brk src/index.js
+
+# Debug tests
+node --inspect-brk node_modules/.bin/vitest
+```
+
+### Git Bisect
+
+```bash
+git bisect start
+git bisect bad                    # Current commit is broken
+git bisect good abc123            # This commit was working
+# Test each commit git suggests
+git bisect good  # or  git bisect bad
+git bisect reset                  # When done
+```
+
+---
+
+## Common Rationalizations (Avoid These)
+
+| Excuse | Reality |
+|--------|---------|
+| "It works on my machine" | Environment differences are bugs |
+| "It's just flaky" | Flaky tests have root causes |
+| "Let's just retry" | Retries hide real problems |
+| "It's a third-party issue" | Still need to handle gracefully |
+| "We'll fix it later" | Tech debt compounds |
+
+---
+
+## Output
+
+- Root cause identified and fixed
+- Regression test added
+- All tests passing
+- Clear commit message explaining the fix
+- **`.agent/SESSION.md`** updated (Gotchas, Decisions, **Next**)
+
+## Next Step
+
+After fixing, continue with `/build` or run `/review` for verification.

package/.agents/workflows/deploy.md

@@ -0,0 +1,43 @@
+---
+description: "deploy"
+---
+# Deploy Command
+
+## Description
+Deploy the application to the target environment.
+
+## Usage
+Tell Claude: "Run the deploy command" or "Deploy to [environment]"
+
+## Steps
+
+### 1. Pre-deploy Checklist
+- [ ] All tests pass (`npm test`)
+- [ ] No linting errors (`npm run lint`)
+- [ ] Environment variables are configured
+- [ ] Database migrations are ready
+
+### 2. Build
+```bash
+npm run build
+```
+
+### 3. Deploy
+```bash
+# Development
+npm run deploy:dev
+
+# Production
+npm run deploy:prod
+```
+
+### 4. Post-deploy Verification
+- Check application health endpoint
+- Verify logs for errors
+- Run smoke tests
+
+## Rollback
+If deployment fails:
+```bash
+npm run rollback
+```

package/.agents/workflows/fix-issue.md

@@ -0,0 +1,45 @@
+---
+description: "fix-issue"
+---
+# Fix Issue Command
+
+## Description
+Analyze and fix a reported bug or issue systematically.
+
+## Usage
+Tell Claude: "Fix issue: [describe the issue]" or "Fix bug in [file/module]"
+
+## Process
+
+### 1. Understand the Issue
+- Read the error message or bug description carefully
+- Identify the affected component(s)
+- Reproduce the issue locally if possible
+
+### 2. Root Cause Analysis
+- Check recent git changes: `git log --oneline -20`
+- Review affected files
+- Look for related tests that may reveal expected behavior
+
+### 3. Plan the Fix
+- Identify the minimal change needed
+- Consider side effects on other components
+- Update or add tests to cover the fix
+
+### 4. Implement
+- Make the targeted fix
+- Ensure code follows `.agent/rules/code-style.md`
+- Handle errors per `.agent/rules/error-handling.md`
+
+### 5. Verify
+- Run relevant tests: `npm test -- --testPathPattern=[affected]`
+- Run full test suite: `npm test`
+- Check linting: `npm run lint`
+
+### 6. Commit
+Follow `.agent/rules/git-workflow.md`:
+```
+fix: [short description of the fix]
+
+Closes #[issue-number]
+```

package/.agents/workflows/handoff.md

@@ -0,0 +1,93 @@
+---
+description: "End-of-session — update .agent/SESSION.md for the next agent or tool"
+---
+
+# /handoff — Session handoff
+
+> "Leave the next agent a map, not a maze."
+
+## Purpose
+
+Capture current work in **`.agent/SESSION.md`** so another chat, persona, or tool (Cursor, Claude Code, Kiro) can continue without re-discovering context.
+
+## When to use
+
+- End of a work session (before closing chat)
+- Switching tools (Cursor → Claude Code → Kiro)
+- Switching persona (e.g. architect → backend)
+- After completing a workflow phase (spec, plan, build, test, review)
+- Before opening a PR (document what reviewers should know)
+
+## Prerequisites
+
+- `.agent/SESSION.md` exists (created by `npx class-ai-agent` or copy from `.agent/SESSION.template.md`)
+- You have context on what was done this session
+
+## Workflow
+
+### Phase 1: Gather state
+
+1. **Review git** — branch name, uncommitted files, last commits
+2. **Review tasks** — open `tasks/todo.md`; sync checkboxes with reality
+3. **Review spec** — note linked `SPEC.md` or `docs/specs/...` path
+4. **Scan decisions** — what did we choose that is not obvious from code alone?
+5. **Scan gotchas** — what failed, env quirks, commands that matter
+
+### Phase 2: Update `.agent/SESSION.md`
+
+Refresh every section (use `.agent/SESSION.template.md` as schema):
+
+| Section | Content |
+|---------|---------|
+| **Meta** | `Updated` (today), `Phase`, `Tool` (cursor/claude/kiro), optional `Persona` |
+| **Goal** | One paragraph — still accurate? |
+| **Done** | Bullets with file paths or commit refs |
+| **In progress** | Current task; **Blockers** (none or describe) |
+| **Next** | Numbered steps for the *next* agent |
+| **Decisions** | Non-obvious choices made this session |
+| **Gotchas** | Failed attempts, test commands, env notes |
+| **Pointers** | Spec path, `tasks/todo.md`, branch, key files |
+
+### Phase 3: Sync `tasks/todo.md`
+
+- Mark completed items `[x]`
+- Add new tasks discovered during work
+- Remove or defer items that are out of scope
+
+### Phase 4: Risk note (if applicable)
+
+If work is **not** safe to pick up blindly, add under **Gotchas** or **In progress**:
+
+- Uncommitted changes and why
+- Failing tests or broken build
+- External blockers (API, review, dependency)
+
+### Phase 5: Optional milestone archive
+
+For major milestones, copy `SESSION.md` to:
+
+```
+.agent/history/YYYY-MM-DD-short-slug.md
+```
+
+Commit both `SESSION.md` and the history file when ready.
+
+## Security
+
+**Never** write to `SESSION.md`:
+
+- API keys, passwords, tokens, credentials
+- PII or customer data
+- Full stack traces with secrets
+
+Use issue links or commit SHAs instead.
+
+## Output
+
+- Updated **`.agent/SESSION.md`**
+- Updated **`tasks/todo.md`** (if it exists)
+- Short summary for the user: phase, next steps, blockers
+
+## Next step
+
+Tell the user to run **`/resume`** in the next session or tool, or commit and share the branch.