@devran-ai/kit 4.1.0

package/.agent/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/.agent/skills/verification-loop/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: verification-loop
+description: Comprehensive verification running all quality gates
+triggers: [manual, pre-commit]
+---
+
+# Verification Loop Skill
+
+> **Purpose**: Continuous quality assurance through automated verification
+
+---
+
+## Overview
+
+The verification loop runs all quality gates to ensure code meets professional standards before committing or deploying.
+
+---
+
+## Workflow
+
+### 1. Build Check
+
+```bash
+npm run build
+```
+
+**Pass Criteria**: Exit code 0, no TypeScript errors
+
+### 2. Lint Check
+
+```bash
+npm run lint
+```
+
+**Pass Criteria**: No errors (warnings acceptable)
+
+### 3. Type Check
+
+```bash
+npx tsc --noEmit
+```
+
+**Pass Criteria**: Zero type errors
+
+### 4. Unit Tests
+
+```bash
+npm run test
+```
+
+**Pass Criteria**: All tests pass
+
+### 5. Coverage Check
+
+```bash
+npm run test:coverage
+```
+
+**Pass Criteria**: ≥80% coverage
+
+### 6. Security Scan
+
+```bash
+npm audit --audit-level=high
+```
+
+**Pass Criteria**: No high/critical vulnerabilities
+
+---
+
+## Configuration
+
+```json
+{
+  "verification": {
+    "coverageThreshold": 80,
+    "allowWarnings": true,
+    "securityLevel": "high"
+  }
+}
+```
+
+---
+
+## Integration
+
+- Invoked by `/verify` command
+- Can be used as pre-commit hook
+- Reports to Code Reviewer agent

package/.agent/skills/webapp-testing/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: webapp-testing
+description: Web application testing principles. E2E, Playwright, component testing, and deep audit strategies.
+version: 1.0.0
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Web App Testing
+
+> Discover and test everything. Leave no route untested.
+
+---
+
+## 1. Deep Audit Approach
+
+### Discovery First
+
+| Target        | How to Find                     |
+| ------------- | ------------------------------- |
+| Routes        | Scan app/, pages/, router files |
+| API endpoints | Grep for HTTP methods           |
+| Components    | Find component directories      |
+| Features      | Read documentation              |
+
+### Systematic Testing
+
+1. **Map** - List all routes/APIs
+2. **Scan** - Verify they respond
+3. **Test** - Cover critical paths
+
+---
+
+## 2. Testing Pyramid
+
+```
+        /\          E2E (Few)
+       /  \         Critical user flows
+      /----\
+     /      \       Integration (Some)
+    /--------\      API, data flow
+   /          \
+  /------------\    Unit/Component (Many)
+                    Individual pieces
+```
+
+---
+
+## 3. E2E Test Principles
+
+### What to Test
+
+| Priority | Tests                     |
+| -------- | ------------------------- |
+| 1        | Happy path user flows     |
+| 2        | Authentication flows      |
+| 3        | Critical business actions |
+| 4        | Error handling            |
+
+### Best Practices
+
+| Practice           | Why                |
+| ------------------ | ------------------ |
+| Use data-testid    | Stable selectors   |
+| Wait for elements  | Avoid flaky tests  |
+| Clean state        | Independent tests  |
+| Avoid impl details | Test user behavior |
+
+---
+
+## 4. Playwright Configuration
+
+### Recommended Settings
+
+| Setting     | Recommendation    |
+| ----------- | ----------------- |
+| Retries     | 2 on CI           |
+| Trace       | on-first-retry    |
+| Screenshots | on-failure        |
+| Video       | retain-on-failure |
+
+### Core Concepts
+
+| Concept           | Use                    |
+| ----------------- | ---------------------- |
+| Page Object Model | Encapsulate page logic |
+| Fixtures          | Reusable test setup    |
+| Assertions        | Built-in auto-wait     |
+| Trace Viewer      | Debug failures         |
+
+---
+
+## 5. Test Organization
+
+### File Structure
+
+```
+tests/
+├── e2e/           # Full user flows
+├── integration/   # API, data
+├── component/     # UI units
+└── fixtures/      # Shared data
+```
+
+### Naming Convention
+
+| Pattern       | Example                     |
+| ------------- | --------------------------- |
+| Feature-based | `login.spec.ts`             |
+| Descriptive   | `user-can-checkout.spec.ts` |
+
+---
+
+## 6. API Testing
+
+### Coverage Areas
+
+| Area           | Tests                       |
+| -------------- | --------------------------- |
+| Status codes   | 200, 400, 404, 500          |
+| Response shape | Matches schema              |
+| Error messages | User-friendly               |
+| Edge cases     | Empty, large, special chars |
+
+---
+
+## 7. CI Integration
+
+### Pipeline Steps
+
+1. Install dependencies
+2. Install browsers (`npx playwright install`)
+3. Run tests
+4. Upload artifacts (traces, screenshots)
+
+### Parallelization
+
+| Strategy | Use                |
+| -------- | ------------------ |
+| Per file | Playwright default |
+| Sharding | Large suites       |
+| Workers  | Multiple browsers  |
+
+---
+
+## 8. Anti-Patterns
+
+| ❌ Don't            | ✅ Do          |
+| ------------------- | -------------- |
+| Test implementation | Test behavior  |
+| Hardcode waits      | Use auto-wait  |
+| Skip cleanup        | Isolate tests  |
+| Ignore flaky tests  | Fix root cause |
+
+---
+
+## 9. Recommended Testing Standards
+
+### Required Coverage
+
+| Vertical      | Minimum Coverage |
+| ------------- | ---------------- |
+| Auth          | 90%+             |
+| Payment       | 95%+             |
+| Core Features | 80%+             |
+
+### Test Types Required
+
+- [ ] Unit tests (Jest/Vitest)
+- [ ] Integration tests (Supertest)
+- [ ] E2E tests (Playwright)
+- [ ] Visual regression (optional)
+
+---
+
+> **Remember:** E2E tests are expensive. Use them for critical paths only.

package/.agent/templates/adr-template.md

@@ -0,0 +1,32 @@
+# ADR Template
+
+Use this template for all Architecture Decision Records.
+
+## ADR-NNN: [Decision Title]
+
+### Status
+
+**[Proposed / Accepted / Deprecated / Superseded]** — [Date]
+
+### Context
+
+[What is the issue that we're seeing that is motivating this decision or change?]
+
+### Decision
+
+[What is the change that we're proposing and/or doing?]
+
+### Consequences
+
+#### Positive
+- [Benefit 1]
+- [Benefit 2]
+
+#### Negative
+- [Trade-off 1]
+- [Trade-off 2]
+
+### Alternatives Considered
+
+1. **[Alternative 1]** — [Why rejected]
+2. **[Alternative 2]** — [Why rejected]

package/.agent/templates/bug-report.md

@@ -0,0 +1,37 @@
+# Bug Report Template
+
+## Description
+
+[Clear description of the bug]
+
+## Steps to Reproduce
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Expected Behavior
+
+[What should happen]
+
+## Actual Behavior
+
+[What actually happens]
+
+## Environment
+
+- **OS**: [e.g., Windows 11, macOS 15, Ubuntu 24.04]
+- **Node.js**: [e.g., 20.x]
+- **Devran AI Kit version**: [e.g., 2.1.0]
+- **IDE**: [e.g., VS Code 1.95, Cursor 0.45]
+
+## Screenshots / Logs
+
+[Attach any relevant screenshots or error logs]
+
+## Severity
+
+- [ ] Critical (system unusable)
+- [ ] High (major feature broken)
+- [ ] Medium (workaround exists)
+- [ ] Low (cosmetic issue)

package/.agent/templates/feature-request.md

@@ -0,0 +1,32 @@
+# Feature Request Template
+
+## Feature Description
+
+[Clear, concise description of the desired feature]
+
+## Problem Statement
+
+[What problem does this feature solve? Why is it needed?]
+
+## Proposed Solution
+
+[High-level description of how this could be implemented]
+
+## Acceptance Criteria
+
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+
+## Technical Considerations
+
+- **Complexity**: [Low / Medium / High]
+- **Breaking Changes**: [Yes / No]
+- **Dependencies**: [List any new dependencies needed]
+
+## Priority
+
+- [ ] Critical (blocks production)
+- [ ] High (needed this sprint)
+- [ ] Medium (next sprint)
+- [ ] Low (backlog)

package/.agent/workflows/README.md

@@ -0,0 +1,101 @@
+# Devran AI Kit — Workflows
+
+> **Purpose**: Process templates for common development tasks
+> **Count**: 21 Workflows
+> **Standard**: Enterprise Workflow Standard (EWS) v1.0
+
+---
+
+## Overview
+
+Workflows are structured process templates that guide you through complex tasks. Each workflow follows the EWS v1.0 standard with 11 mandatory sections including trigger/lifecycle definition, critical rules, argument parsing, governance alerts, and completion criteria.
+
+Invoke them using slash commands (e.g., `/brainstorm authentication system`).
+
+---
+
+## Available Workflows
+
+| Workflow | Command | Lifecycle | Description |
+| :---------------- | :--------------- | :------------ | :----------------------------------------------- |
+| **brainstorm** | `/brainstorm` | Discover | Creative ideation and option exploration |
+| **quality-gate** | `/quality-gate` | Discover | Pre-task market research, gap analysis, ethics |
+| **plan** | `/plan` | Plan | Structured implementation planning |
+| **create** | `/create` | Build | Scaffold new features, components, or modules |
+| **enhance** | `/enhance` | Build | Iterative feature development on existing code |
+| **preview** | `/preview` | Build | Local development server management |
+| **ui-ux-pro-max** | `/ui-ux-pro-max` | Build | Premium UI/UX design and implementation |
+| **test** | `/test` | Verify | Systematic test writing and execution |
+| **review** | `/review` | Verify | Sequential quality gate pipeline |
+| **preflight** | `/preflight` | Verify | Production readiness assessment with 10-domain scoring |
+| **pr** | `/pr` | Ship | Production-grade PR creation with branch validation and size guards |
+| **pr-review** | `/pr-review` | Verify | Multi-perspective PR review with senior engineering expertise |
+| **pr-fix** | `/pr-fix` | Build | Fix PR issues based on review comments with verification |
+| **pr-merge** | `/pr-merge` | Ship | Safe PR merge with dependency validation and post-merge checks |
+| **pr-split** | `/pr-split` | Build | Split oversized PRs into focused sub-PRs by concern category |
+| **deploy** | `/deploy` | Ship | Production deployment with pre-flight checks |
+| **debug** | `/debug` | Reactive | Systematic problem investigation |
+| **orchestrate** | `/orchestrate` | Reactive | Multi-agent coordination for complex tasks |
+| **retrospective** | `/retrospective` | Evaluate | Tier-1 quality audit against market standards |
+| **status** | `/status` | Cross-cutting | Project status overview and health check |
+| **upgrade** | `/upgrade` | Maintenance | Formal protocol for non-destructive framework upgrades |
+
+---
+
+## SDLC Lifecycle Map
+
+```
+Discover ──► Plan ──► Build ──► Verify ──► Ship ──► Evaluate
+   │           │        │         │         │          │
+   ▼           ▼        ▼         ▼         ▼          ▼
+/brainstorm  /plan   /create   /test       /pr        /retrospective
+/quality-gate        /enhance  /review     /pr-merge
+                     /preview  /preflight  /deploy
+                     /pr-fix   /pr-review
+                     /pr-split
+                     /ui-ux-pro-max
+
+    Reactive (any phase)          Cross-cutting (any phase)
+    ────────────────────          ────────────────────────
+    /debug                        /status
+    /orchestrate                  /upgrade
+```
+
+---
+
+## EWS v1.0 Standard
+
+Every workflow conforms to the Enterprise Workflow Standard v1.0 with these sections:
+
+| # | Section | Purpose |
+| :- | :------------------- | :----------------------------------------------- |
+| 1 | Frontmatter | `description` and `version` fields |
+| 2 | Trigger / Lifecycle | When and where in SDLC this workflow runs |
+| 3 | Governance Alert | Risk-appropriate alert (NOTE/IMPORTANT/CAUTION) |
+| 4 | Critical Rules | Non-negotiable behavioral constraints |
+| 5 | Argument Parsing | Sub-commands and argument table |
+| 6 | Steps | Ordered steps with `// turbo` annotations |
+| 7 | Output Template | Structured output format |
+| 8 | Governance Footer | PROHIBITED / REQUIRED behavioral contracts |
+| 9 | Completion Criteria | Checklist of done criteria |
+| 10 | Related Resources | Links to skills, agents, and related workflows |
+| 11 | Scope Filter | When applicable: commit-type filtering table |
+
+---
+
+## Turbo Annotation Policy
+
+Steps annotated with `// turbo` can be auto-executed without user confirmation:
+
+- **Allowed**: Read-only steps (analysis, detection, research, diagnostics)
+- **Prohibited**: State-mutating steps (server start, deployment, code generation)
+
+---
+
+## Creating Custom Workflows
+
+1. Create `workflows/my-workflow.md`
+2. Add frontmatter with `description` and `version` fields
+3. Follow the EWS v1.0 template (11 sections)
+4. Map to an SDLC lifecycle phase
+5. Link to relevant skills and agents in Related Resources

package/.agent/workflows/brainstorm.md

@@ -0,0 +1,86 @@
+---
+description: Structured brainstorming. Explore options before committing to implementation.
+version: 2.1.0
+sdlc-phase: discover
+skills: [brainstorming]
+commit-types: [docs]
+---
+
+# /brainstorm — Structured Idea Exploration
+
+> **Trigger**: `/brainstorm [topic]`
+> **Lifecycle**: Discover — before `/quality-gate` or `/plan`
+
+> Standards: See `rules/workflow-standards.md`
+
+---
+
+## Critical Rules
+
+1. No code — produce ideas, analysis only
+2. Minimum 3 options with pros/cons
+3. Evidence-based recommendations
+4. Socratic exploration — clarify before generating
+5. Honest tradeoffs — never hide complexity
+6. User decides — present and recommend, don't choose
+
+---
+
+## Steps
+
+// turbo
+1. **Gather Context** — problem, target user, constraints, what's been tried
+
+// turbo
+2. **Research** — existing patterns in codebase, industry best practices, architectural constraints
+
+3. **Generate Options** — 3+ distinct approaches with pros, cons, effort, risk
+
+4. **Compare & Recommend** — comparison table, clear recommendation with reasoning, ask user direction
+
+---
+
+## Output Template
+
+```markdown
+## Brainstorm: [Topic]
+
+### Context
+[Problem and constraints]
+
+### Options
+**Option A/B/C**: [description, pros, cons, effort, risk]
+
+### Comparison
+| Criteria | A | B | C |
+| :--- | :--- | :--- | :--- |
+| Effort / Risk / Scalability / Maintainability | ... |
+
+### Recommendation
+**Option [X]** because [reasoning].
+
+**Next**: `/quality-gate` or `/plan`
+```
+
+---
+
+## Governance
+
+**PROHIBITED:** Writing code · fewer than 3 options · hiding complexity
+
+**REQUIRED:** Clarifying questions · evidence-based reasoning · comparison matrix · user confirmation
+
+---
+
+## Completion Criteria
+
+- [ ] 3+ options with tradeoffs
+- [ ] Comparison matrix included
+- [ ] User selected direction
+
+---
+
+## Related Resources
+
+- **Next**: `/quality-gate` · `/plan`
+- **Skill**: `.agent/skills/brainstorming/SKILL.md`