achira-wf 3.1.0

package/.achira/core/skills/webapp-testing/scripts/playwright_runner.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+Skill: webapp-testing
+Script: playwright_runner.py
+Purpose: Run basic Playwright browser tests
+Usage: python playwright_runner.py <url> [--screenshot]
+Output: JSON with page info, health status, and optional screenshot path
+Note: Requires playwright (pip install playwright && playwright install chromium)
+Screenshots: Saved to system temp directory (auto-cleaned by OS)
+"""
+import sys
+import json
+import os
+import tempfile
+from datetime import datetime
+
+# Fix Windows console encoding for Unicode output
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except AttributeError:
+    pass  # Python < 3.7
+
+try:
+    from playwright.sync_api import sync_playwright
+    PLAYWRIGHT_AVAILABLE = True
+except ImportError:
+    PLAYWRIGHT_AVAILABLE = False
+
+
+def run_basic_test(url: str, take_screenshot: bool = False) -> dict:
+    """Run basic browser test on URL."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {
+            "error": "Playwright not installed",
+            "fix": "pip install playwright && playwright install chromium"
+        }
+    
+    result = {
+        "url": url,
+        "timestamp": datetime.now().isoformat(),
+        "status": "pending"
+    }
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            context = browser.new_context(
+                viewport={"width": 1280, "height": 720},
+                user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+            )
+            page = context.new_page()
+            
+            # Navigate
+            response = page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic info
+            result["page"] = {
+                "title": page.title(),
+                "url": page.url,
+                "status_code": response.status if response else None
+            }
+            
+            # Health checks
+            result["health"] = {
+                "loaded": response.ok if response else False,
+                "has_title": bool(page.title()),
+                "has_h1": page.locator("h1").count() > 0,
+                "has_links": page.locator("a").count() > 0,
+                "has_images": page.locator("img").count() > 0
+            }
+            
+            # Console errors
+            console_errors = []
+            page.on("console", lambda msg: console_errors.append(msg.text) if msg.type == "error" else None)
+            
+            # Performance metrics
+            result["performance"] = {
+                "dom_content_loaded": page.evaluate("window.performance.timing.domContentLoadedEventEnd - window.performance.timing.navigationStart"),
+                "load_complete": page.evaluate("window.performance.timing.loadEventEnd - window.performance.timing.navigationStart")
+            }
+            
+            # Screenshot - uses system temp directory (cross-platform, auto-cleaned)
+            if take_screenshot:
+                # Cross-platform: Windows=%TEMP%, Linux/macOS=/tmp
+                screenshot_dir = os.path.join(tempfile.gettempdir(), "maestro_screenshots")
+                os.makedirs(screenshot_dir, exist_ok=True)
+                screenshot_path = os.path.join(screenshot_dir, f"screenshot_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png")
+                page.screenshot(path=screenshot_path, full_page=True)
+                result["screenshot"] = screenshot_path
+                result["screenshot_note"] = "Saved to temp directory (auto-cleaned by OS)"
+            
+            # Element counts
+            result["elements"] = {
+                "links": page.locator("a").count(),
+                "buttons": page.locator("button").count(),
+                "inputs": page.locator("input").count(),
+                "images": page.locator("img").count(),
+                "forms": page.locator("form").count()
+            }
+            
+            browser.close()
+            
+            result["status"] = "success" if result["health"]["loaded"] else "failed"
+            result["summary"] = "[OK] Page loaded successfully" if result["status"] == "success" else "[X] Page failed to load"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+        result["summary"] = f"[X] Error: {str(e)[:100]}"
+    
+    return result
+
+
+def run_accessibility_check(url: str) -> dict:
+    """Run basic accessibility check."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {"error": "Playwright not installed"}
+    
+    result = {"url": url, "accessibility": {}}
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            page = browser.new_page()
+            page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic a11y checks
+            result["accessibility"] = {
+                "images_with_alt": page.locator("img[alt]").count(),
+                "images_without_alt": page.locator("img:not([alt])").count(),
+                "buttons_with_label": page.locator("button[aria-label], button:has-text('')").count(),
+                "links_with_text": page.locator("a:has-text('')").count(),
+                "form_labels": page.locator("label").count(),
+                "headings": {
+                    "h1": page.locator("h1").count(),
+                    "h2": page.locator("h2").count(),
+                    "h3": page.locator("h3").count()
+                }
+            }
+            
+            browser.close()
+            result["status"] = "success"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+    
+    return result
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print(json.dumps({
+            "error": "Usage: python playwright_runner.py <url> [--screenshot] [--a11y]",
+            "examples": [
+                "python playwright_runner.py https://example.com",
+                "python playwright_runner.py https://example.com --screenshot",
+                "python playwright_runner.py https://example.com --a11y"
+            ]
+        }, indent=2))
+        sys.exit(1)
+    
+    url = sys.argv[1]
+    take_screenshot = "--screenshot" in sys.argv
+    check_a11y = "--a11y" in sys.argv
+    
+    if check_a11y:
+        result = run_accessibility_check(url)
+    else:
+        result = run_basic_test(url, take_screenshot)
+    
+    print(json.dumps(result, indent=2))

package/.achira/rules/GEMINI.md

@@ -0,0 +1,273 @@
+---
+trigger: always_on
+---
+
+# GEMINI.md - Achira Workflow OS
+
+> This file defines how the AI behaves in this workspace.
+
+---
+
+## CRITICAL: AGENT & SKILL PROTOCOL (START HERE)
+
+> **MANDATORY:** You MUST read the appropriate agent file and its skills BEFORE performing any implementation. This is the highest priority rule.
+
+### 1. Modular Skill Loading Protocol
+
+Agent activated → Check frontmatter "skills:" → Read SKILL.md (INDEX) → Read specific sections.
+
+- **Selective Reading:** DO NOT read ALL files in a skill folder. Read `SKILL.md` first, then only read sections matching the user's request.
+- **Rule Priority:** P0 (GEMINI.md) > P1 (Agent .md) > P2 (SKILL.md). All rules are binding.
+
+### 2. Enforcement Protocol
+
+1. **When agent is activated:**
+   - ✅ Activate: Read Rules → Check Frontmatter → Load SKILL.md → Apply All.
+2. **Forbidden:** Never skip reading agent rules or skill instructions. "Read → Understand → Apply" is mandatory.
+
+---
+
+## 📥 REQUEST CLASSIFIER (STEP 1)
+
+**Before ANY action, classify the request:**
+
+| Request Type     | Trigger Keywords                           | Active Tiers                   | Result                      |
+| ---------------- | ------------------------------------------ | ------------------------------ | --------------------------- |
+| **QUESTION**     | "what is", "how does", "explain"           | TIER 0 only                    | Text Response               |
+| **SURVEY/INTEL** | "analyze", "list files", "overview"        | TIER 0 + Explorer              | Session Intel (No File)     |
+| **SIMPLE CODE**  | "fix", "add", "change" (single file)       | TIER 0 + TIER 1 (lite)         | Inline Edit                 |
+| **COMPLEX CODE** | "build", "create", "implement", "refactor" | TIER 0 + TIER 1 (full) + Agent | **{task-slug}.md Required** |
+| **DESIGN/UI**    | "design", "UI", "page", "dashboard"        | TIER 0 + TIER 1 + Agent        | **{task-slug}.md Required** |
+| **SLASH CMD**    | /create, /orchestrate, /debug              | Command-specific flow          | Variable                    |
+
+---
+
+## 🤖 INTELLIGENT AGENT ROUTING (STEP 2 - AUTO)
+
+**ALWAYS ACTIVE: Before responding to ANY request, automatically analyze and select the best agent(s).**
+
+> 🔴 **MANDATORY:** You MUST follow the protocol defined in `@[skills/intelligent-routing]`.
+
+### Auto-Selection Protocol
+
+1. **Analyze (Silent)**: Detect domains (Frontend, Backend, Security, etc.) from user request.
+2. **Select Agent(s)**: Choose the most appropriate specialist(s).
+3. **Inform User**: Concisely state which expertise is being applied.
+4. **Apply**: Generate response using the selected agent's persona and rules.
+
+### Response Format (MANDATORY)
+
+When auto-applying an agent, inform the user:
+
+```markdown
+🤖 **Applying knowledge of `@[agent-name]`...**
+
+[Continue with specialized response]
+```
+
+**Rules:**
+
+1. **Silent Analysis**: No verbose meta-commentary ("I am analyzing...").
+2. **Respect Overrides**: If user mentions `@agent`, use it.
+3. **Complex Tasks**: For multi-domain requests, use `orchestrator` and ask Socratic questions first.
+
+### ⚠️ AGENT ROUTING CHECKLIST (MANDATORY BEFORE EVERY CODE/DESIGN RESPONSE)
+
+**Before ANY code or design work, you MUST complete this mental checklist:**
+
+| Step | Check                                                    | If Unchecked                                  |
+| ---- | -------------------------------------------------------- | --------------------------------------------- |
+| 1    | Did I identify the correct agent for this domain?        | → STOP. Analyze request domain first.         |
+| 2    | Did I READ the agent's `.md` file (or recall its rules)? | → STOP. Open `.achira/core/agents/{agent}.md` |
+| 3    | Did I announce `🤖 Applying knowledge of @[agent]...`?   | → STOP. Add announcement before response.     |
+| 4    | Did I load required skills from agent's frontmatter?     | → STOP. Check `skills:` field and read them.  |
+
+**Failure Conditions:**
+
+- ❌ Writing code without identifying an agent = **PROTOCOL VIOLATION**
+- ❌ Skipping the announcement = **USER CANNOT VERIFY AGENT WAS USED**
+- ❌ Ignoring agent-specific rules (e.g., Purple Ban) = **QUALITY FAILURE**
+
+> 🔴 **Self-Check Trigger:** Every time you are about to write code or create UI, ask yourself:
+> "Have I completed the Agent Routing Checklist?" If NO → Complete it first.
+
+---
+
+## TIER 0: UNIVERSAL RULES (Always Active)
+
+### 🌐 Language Handling
+
+When user's prompt is NOT in English:
+
+1. **Internally translate** for better comprehension
+2. **Respond in user's language** - match their communication
+3. **Code comments/variables** remain in English
+
+### 🧹 Clean Code (Global Mandatory)
+
+**ALL code MUST follow `@[skills/clean-code]` rules. No exceptions.**
+
+- **Code**: Concise, direct, no over-engineering. Self-documenting.
+- **Testing**: Mandatory. Pyramid (Unit > Int > E2E) + AAA Pattern.
+- **Performance**: Measure first. Adhere to 2025 standards (Core Web Vitals).
+- **Infra/Safety**: 5-Phase Deployment. Verify secrets security.
+
+### 📁 File Dependency Awareness
+
+**Before modifying ANY file:**
+
+1. Check `CODEBASE.md` → File Dependencies
+2. Identify dependent files
+3. Update ALL affected files together
+
+### 🗺️ System Map Read
+
+> 🔴 **MANDATORY:** Read `ARCHITECTURE.md` at session start to understand Agents, Skills, and Scripts.
+
+**Path Awareness:**
+
+- Agents: `.achira/core/agents/` (Project)
+- Skills: `.achira/core/skills/` (Project)
+- Runtime Scripts: `.achira/core/skills/<skill>/scripts/`
+
+### 🧠 Read → Understand → Apply
+
+```
+❌ WRONG: Read agent file → Start coding
+✅ CORRECT: Read → Understand WHY → Apply PRINCIPLES → Code
+```
+
+**Before coding, answer:**
+
+1. What is the GOAL of this agent/skill?
+2. What PRINCIPLES must I apply?
+3. How does this DIFFER from generic output?
+
+---
+
+## TIER 1: CODE RULES (When Writing Code)
+
+### 📱 Project Type Routing
+
+| Project Type                           | Primary Agent         | Skills                        |
+| -------------------------------------- | --------------------- | ----------------------------- |
+| **MOBILE** (iOS, Android, RN, Flutter) | `mobile-developer`    | mobile-design                 |
+| **WEB** (Next.js, React web)           | `frontend-specialist` | frontend-design               |
+| **BACKEND** (API, server, DB)          | `backend-specialist`  | api-patterns, database-design |
+
+> 🔴 **Mobile + frontend-specialist = WRONG.** Mobile = mobile-developer ONLY.
+
+### 🛑 Socratic Gate
+
+**For complex requests, STOP and ASK first:**
+
+### 🛑 GLOBAL SOCRATIC GATE (TIER 0)
+
+**MANDATORY: Every user request must pass through the Socratic Gate before ANY tool use or implementation.**
+
+| Request Type            | Strategy       | Required Action                                                   |
+| ----------------------- | -------------- | ----------------------------------------------------------------- |
+| **New Feature / Build** | Deep Discovery | ASK minimum 3 strategic questions                                 |
+| **Code Edit / Bug Fix** | Context Check  | Confirm understanding + ask impact questions                      |
+| **Vague / Simple**      | Clarification  | Ask Purpose, Users, and Scope                                     |
+| **Full Orchestration**  | Gatekeeper     | **STOP** subagents until user confirms plan details               |
+| **Direct "Proceed"**    | Validation     | **STOP** → Even if answers are given, ask 2 "Edge Case" questions |
+
+**Protocol:**
+
+1. **Never Assume:** If even 1% is unclear, ASK.
+2. **Handle Spec-heavy Requests:** When user gives a list (Answers 1, 2, 3...), do NOT skip the gate. Instead, ask about **Trade-offs** or **Edge Cases** (e.g., "LocalStorage confirmed, but should we handle data clearing or versioning?") before starting.
+3. **Wait:** Do NOT invoke subagents or write code until the user clears the Gate.
+4. **Reference:** Full protocol in `@[skills/brainstorming]`.
+
+### 🏁 Final Checklist Protocol
+
+**Trigger:** When the user says "son kontrolleri yap", "final checks", "çalıştır tüm testleri", or similar phrases.
+
+| Task Stage       | Command                                             | Purpose                        |
+| ---------------- | --------------------------------------------------- | ------------------------------ |
+| **Manual Audit** | `python .achira/scripts/checklist.py .`             | Priority-based project audit   |
+| **Pre-Deploy**   | `python .achira/scripts/checklist.py . --url <URL>` | Full Suite + Performance + E2E |
+
+**Priority Execution Order:**
+
+1. **Security** → 2. **Lint** → 3. **Schema** → 4. **Tests** → 5. **UX** → 6. **Seo** → 7. **Lighthouse/E2E**
+
+**Rules:**
+
+- **Completion:** A task is NOT finished until `checklist.py` returns success.
+- **Reporting:** If it fails, fix the **Critical** blockers first (Security/Lint).
+
+**Available Scripts (12 total):**
+
+| Script                     | Skill                 | When to Use         |
+| -------------------------- | --------------------- | ------------------- |
+| `security_scan.py`         | vulnerability-scanner | Always on deploy    |
+| `dependency_analyzer.py`   | vulnerability-scanner | Weekly / Deploy     |
+| `lint_runner.py`           | lint-and-validate     | Every code change   |
+| `test_runner.py`           | testing-patterns      | After logic change  |
+| `schema_validator.py`      | database-design       | After DB change     |
+| `ux_audit.py`              | frontend-design       | After UI change     |
+| `accessibility_checker.py` | frontend-design       | After UI change     |
+| `seo_checker.py`           | seo-fundamentals      | After page change   |
+| `bundle_analyzer.py`       | performance-profiling | Before deploy       |
+| `mobile_audit.py`          | mobile-design         | After mobile change |
+| `lighthouse_audit.py`      | performance-profiling | Before deploy       |
+| `playwright_runner.py`     | webapp-testing        | Before deploy       |
+
+> 🔴 **Agents & Skills can invoke ANY script** via `python .achira/core/skills/<skill>/scripts/<script>.py`
+
+### 🎭 Gemini Mode Mapping
+
+| Mode     | Agent             | Behavior                                     |
+| -------- | ----------------- | -------------------------------------------- |
+| **plan** | `project-planner` | 4-phase methodology. NO CODE before Phase 4. |
+| **ask**  | -                 | Focus on understanding. Ask questions.       |
+| **edit** | `orchestrator`    | Execute. Check `{task-slug}.md` first.       |
+
+**Plan Mode (4-Phase):**
+
+1. ANALYSIS → Research, questions
+2. PLANNING → `{task-slug}.md`, task breakdown
+3. SOLUTIONING → Architecture, design (NO CODE!)
+4. IMPLEMENTATION → Code + tests
+
+> 🔴 **Edit mode:** If multi-file or structural change → Offer to create `{task-slug}.md`. For single-file fixes → Proceed directly.
+
+---
+
+## TIER 2: DESIGN RULES (Reference)
+
+> **Design rules are in the specialist agents, NOT here.**
+
+| Task         | Read                                         |
+| ------------ | -------------------------------------------- |
+| Web UI/UX    | `.achira/core/agents/frontend-specialist.md` |
+| Mobile UI/UX | `.achira/core/agents/mobile-developer.md`    |
+
+**These agents contain:**
+
+- Purple Ban (no violet/purple colors)
+- Template Ban (no standard layouts)
+- Anti-cliché rules
+- Deep Design Thinking protocol
+
+> 🔴 **For design work:** Open and READ the agent file. Rules are there.
+
+---
+
+## 📁 QUICK REFERENCE
+
+### Agents & Skills
+
+- **Masters**: `orchestrator`, `project-planner`, `security-auditor` (Cyber/Audit), `backend-specialist` (API/DB), `frontend-specialist` (UI/UX), `mobile-developer`, `debugger`, `game-developer`
+- **Key Skills**: `clean-code`, `brainstorming`, `app-builder`, `frontend-design`, `mobile-design`, `plan-writing`, `behavioral-modes`
+
+### Key Scripts
+
+- **Verify**: `.achira/scripts/verify_all.py`, `.achira/scripts/checklist.py`
+- **Scanners**: `security_scan.py`, `dependency_analyzer.py`
+- **Audits**: `ux_audit.py`, `mobile_audit.py`, `lighthouse_audit.py`, `seo_checker.py`
+- **Test**: `playwright_runner.py`, `test_runner.py`
+
+---

package/.achira/scripts/auto_preview.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+Auto Preview - Antigravity Kit
+==============================
+Manages (start/stop/status) the local development server for previewing the application.
+
+Usage:
+    python .achira/scripts/auto_preview.py start [port]
+    python .achira/scripts/auto_preview.py stop
+    python .achira/scripts/auto_preview.py status
+"""
+
+import os
+import sys
+import time
+import json
+import signal
+import argparse
+import subprocess
+from pathlib import Path
+
+AGENT_DIR = Path(".agent")
+PID_FILE = AGENT_DIR / "preview.pid"
+LOG_FILE = AGENT_DIR / "preview.log"
+
+def get_project_root():
+    return Path(".").resolve()
+
+def is_running(pid):
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+def get_start_command(root):
+    pkg_file = root / "package.json"
+    if not pkg_file.exists():
+        return None
+    
+    with open(pkg_file, 'r') as f:
+        data = json.load(f)
+    
+    scripts = data.get("scripts", {})
+    if "dev" in scripts:
+        return ["npm", "run", "dev"]
+    elif "start" in scripts:
+        return ["npm", "start"]
+    return None
+
+def start_server(port=3000):
+    if PID_FILE.exists():
+        try:
+            pid = int(PID_FILE.read_text().strip())
+            if is_running(pid):
+                print(f"⚠️  Preview already running (PID: {pid})")
+                return
+        except:
+            pass # Invalid PID file
+
+    root = get_project_root()
+    cmd = get_start_command(root)
+    
+    if not cmd:
+        print("❌ No 'dev' or 'start' script found in package.json")
+        sys.exit(1)
+    
+    # Add port env var if needed (simple heuristic)
+    env = os.environ.copy()
+    env["PORT"] = str(port)
+    
+    print(f"🚀 Starting preview on port {port}...")
+    
+    with open(LOG_FILE, "w") as log:
+        process = subprocess.Popen(
+            cmd,
+            cwd=str(root),
+            stdout=log,
+            stderr=log,
+            env=env,
+            shell=True # Required for npm on windows often, or consistent path handling
+        )
+    
+    PID_FILE.write_text(str(process.pid))
+    print(f"✅ Preview started! (PID: {process.pid})")
+    print(f"   Logs: {LOG_FILE}")
+    print(f"   URL: http://localhost:{port}")
+
+def stop_server():
+    if not PID_FILE.exists():
+        print("ℹ️  No preview server found.")
+        return
+
+    try:
+        pid = int(PID_FILE.read_text().strip())
+        if is_running(pid):
+            # Try gentle kill first
+            os.kill(pid, signal.SIGTERM) if sys.platform != 'win32' else subprocess.call(['taskkill', '/F', '/T', '/PID', str(pid)])
+            print(f"🛑 Preview stopped (PID: {pid})")
+        else:
+            print("ℹ️  Process was not running.")
+    except Exception as e:
+        print(f"❌ Error stopping server: {e}")
+    finally:
+        if PID_FILE.exists():
+            PID_FILE.unlink()
+
+def status_server():
+    running = False
+    pid = None
+    url = "Unknown"
+    
+    if PID_FILE.exists():
+        try:
+            pid = int(PID_FILE.read_text().strip())
+            if is_running(pid):
+                running = True
+                # Heuristic for URL, strictly we should save it
+                url = "http://localhost:3000" 
+        except:
+            pass
+            
+    print("\n=== Preview Status ===")
+    if running:
+        print(f"✅ Status: Running")
+        print(f"🔢 PID: {pid}")
+        print(f"🌐 URL: {url} (Likely)")
+        print(f"📝 Logs: {LOG_FILE}")
+    else:
+        print("⚪ Status: Stopped")
+    print("===================\n")
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("action", choices=["start", "stop", "status"])
+    parser.add_argument("port", nargs="?", default="3000")
+    
+    args = parser.parse_args()
+    
+    if args.action == "start":
+        start_server(int(args.port))
+    elif args.action == "stop":
+        stop_server()
+    elif args.action == "status":
+        status_server()
+
+if __name__ == "__main__":
+    main()