achira-wf 3.1.0

package/.achira/workflows/orchestrate.md

@@ -0,0 +1,237 @@
+---
+description: Coordinate multiple agents for complex tasks. Use for multi-perspective analysis, comprehensive reviews, or tasks requiring different domain expertise.
+---
+
+# Multi-Agent Orchestration
+
+You are now in **ORCHESTRATION MODE**. Your task: coordinate specialized agents to solve this complex problem.
+
+## Task to Orchestrate
+$ARGUMENTS
+
+---
+
+## 🔴 CRITICAL: Minimum Agent Requirement
+
+> ⚠️ **ORCHESTRATION = MINIMUM 3 DIFFERENT AGENTS**
+> 
+> If you use fewer than 3 agents, you are NOT orchestrating - you're just delegating.
+> 
+> **Validation before completion:**
+> - Count invoked agents
+> - If `agent_count < 3` → STOP and invoke more agents
+> - Single agent = FAILURE of orchestration
+
+### Agent Selection Matrix
+
+| Task Type | REQUIRED Agents (minimum) |
+|-----------|---------------------------|
+| **Web App** | frontend-specialist, backend-specialist, test-engineer |
+| **API** | backend-specialist, security-auditor, test-engineer |
+| **UI/Design** | frontend-specialist, seo-specialist, performance-optimizer |
+| **Database** | database-architect, backend-specialist, security-auditor |
+| **Full Stack** | project-planner, frontend-specialist, backend-specialist, devops-engineer |
+| **Debug** | debugger, explorer-agent, test-engineer |
+| **Security** | security-auditor, penetration-tester, devops-engineer |
+
+---
+
+## Pre-Flight: Mode Check
+
+| Current Mode | Task Type | Action |
+|--------------|-----------|--------|
+| **plan** | Any | ✅ Proceed with planning-first approach |
+| **edit** | Simple execution | ✅ Proceed directly |
+| **edit** | Complex/multi-file | ⚠️ Ask: "This task requires planning. Switch to plan mode?" |
+| **ask** | Any | ⚠️ Ask: "Ready to orchestrate. Switch to edit or plan mode?" |
+
+---
+
+## 🔴 STRICT 2-PHASE ORCHESTRATION
+
+### PHASE 1: PLANNING (Sequential - NO parallel agents)
+
+| Step | Agent | Action |
+|------|-------|--------|
+| 1 | `project-planner` | Create docs/PLAN.md |
+| 2 | (optional) `explorer-agent` | Codebase discovery if needed |
+
+> 🔴 **NO OTHER AGENTS during planning!** Only project-planner and explorer-agent.
+
+### ⏸️ CHECKPOINT: User Approval
+
+```
+After PLAN.md is complete, ASK:
+
+"✅ Plan created: docs/PLAN.md
+
+Do you approve? (Y/N)
+- Y: Start implementation
+- N: I'll revise the plan"
+```
+
+> 🔴 **DO NOT proceed to Phase 2 without explicit user approval!**
+
+### PHASE 2: IMPLEMENTATION (Parallel agents after approval)
+
+| Parallel Group | Agents |
+|----------------|--------|
+| Foundation | `database-architect`, `security-auditor` |
+| Core | `backend-specialist`, `frontend-specialist` |
+| Polish | `test-engineer`, `devops-engineer` |
+
+> ✅ After user approval, invoke multiple agents in PARALLEL.
+
+## Available Agents (17 total)
+
+| Agent | Domain | Use When |
+|-------|--------|----------|
+| `project-planner` | Planning | Task breakdown, PLAN.md |
+| `explorer-agent` | Discovery | Codebase mapping |
+| `frontend-specialist` | UI/UX | React, Vue, CSS, HTML |
+| `backend-specialist` | Server | API, Node.js, Python |
+| `database-architect` | Data | SQL, NoSQL, Schema |
+| `security-auditor` | Security | Vulnerabilities, Auth |
+| `penetration-tester` | Security | Active testing |
+| `test-engineer` | Testing | Unit, E2E, Coverage |
+| `devops-engineer` | Ops | CI/CD, Docker, Deploy |
+| `mobile-developer` | Mobile | React Native, Flutter |
+| `performance-optimizer` | Speed | Lighthouse, Profiling |
+| `seo-specialist` | SEO | Meta, Schema, Rankings |
+| `documentation-writer` | Docs | README, API docs |
+| `debugger` | Debug | Error analysis |
+| `game-developer` | Games | Unity, Godot |
+| `orchestrator` | Meta | Coordination |
+
+---
+
+## Orchestration Protocol
+
+### Step 1: Analyze Task Domains
+Identify ALL domains this task touches:
+```
+□ Security     → security-auditor, penetration-tester
+□ Backend/API  → backend-specialist
+□ Frontend/UI  → frontend-specialist
+□ Database     → database-architect
+□ Testing      → test-engineer
+□ DevOps       → devops-engineer
+□ Mobile       → mobile-developer
+□ Performance  → performance-optimizer
+□ SEO          → seo-specialist
+□ Planning     → project-planner
+```
+
+### Step 2: Phase Detection
+
+| If Plan Exists | Action |
+|----------------|--------|
+| NO `docs/PLAN.md` | → Go to PHASE 1 (planning only) |
+| YES `docs/PLAN.md` + user approved | → Go to PHASE 2 (implementation) |
+
+### Step 3: Execute Based on Phase
+
+**PHASE 1 (Planning):**
+```
+Use the project-planner agent to create PLAN.md
+→ STOP after plan is created
+→ ASK user for approval
+```
+
+**PHASE 2 (Implementation - after approval):**
+```
+Invoke agents in PARALLEL:
+Use the frontend-specialist agent to [task]
+Use the backend-specialist agent to [task]
+Use the test-engineer agent to [task]
+```
+
+**🔴 CRITICAL: Context Passing (MANDATORY)**
+
+When invoking ANY subagent, you MUST include:
+
+1. **Original User Request:** Full text of what user asked
+2. **Decisions Made:** All user answers to Socratic questions
+3. **Previous Agent Work:** Summary of what previous agents did
+4. **Current Plan State:** If plan files exist in workspace, include them
+
+**Example with FULL context:**
+```
+Use the project-planner agent to create PLAN.md:
+
+**CONTEXT:**
+- User Request: "A social platform for students, using mock data"
+- Decisions: Tech=Vue 3, Layout=Grid Widgets, Auth=Mock, Design=Youthful & dynamic
+- Previous Work: Orchestrator asked 6 questions, user chose all options
+- Current Plan: playful-roaming-dream.md exists in workspace with initial structure
+
+**TASK:** Create detailed PLAN.md based on ABOVE decisions. Do NOT infer from folder name.
+```
+
+> ⚠️ **VIOLATION:** Invoking subagent without full context = subagent will make wrong assumptions!
+
+
+### Step 4: Verification (MANDATORY)
+The LAST agent must run appropriate verification scripts:
+```bash
+python .achira/core/skills/vulnerability-scanner/scripts/security_scan.py .
+python .achira/core/skills/lint-and-validate/scripts/lint_runner.py .
+```
+
+### Step 5: Synthesize Results
+Combine all agent outputs into unified report.
+
+---
+
+## Output Format
+
+```markdown
+## 🎼 Orchestration Report
+
+### Task
+[Original task summary]
+
+### Mode
+[Current Antigravity Agent mode: plan/edit/ask]
+
+### Agents Invoked (MINIMUM 3)
+| # | Agent | Focus Area | Status |
+|---|-------|------------|--------|
+| 1 | project-planner | Task breakdown | ✅ |
+| 2 | frontend-specialist | UI implementation | ✅ |
+| 3 | test-engineer | Verification scripts | ✅ |
+
+### Verification Scripts Executed
+- [x] security_scan.py → Pass/Fail
+- [x] lint_runner.py → Pass/Fail
+
+### Key Findings
+1. **[Agent 1]**: Finding
+2. **[Agent 2]**: Finding
+3. **[Agent 3]**: Finding
+
+### Deliverables
+- [ ] PLAN.md created
+- [ ] Code implemented
+- [ ] Tests passing
+- [ ] Scripts verified
+
+### Summary
+[One paragraph synthesis of all agent work]
+```
+
+---
+
+## 🔴 EXIT GATE
+
+Before completing orchestration, verify:
+
+1. ✅ **Agent Count:** `invoked_agents >= 3`
+2. ✅ **Scripts Executed:** At least `security_scan.py` ran
+3. ✅ **Report Generated:** Orchestration Report with all agents listed
+
+> **If any check fails → DO NOT mark orchestration complete. Invoke more agents or run scripts.**
+
+---
+
+**Begin orchestration now. Select 3+ agents, execute sequentially, run verification scripts, synthesize results.**

package/.achira/workflows/plan.md

@@ -0,0 +1,89 @@
+---
+description: Create project plan using project-planner agent. No code writing - only plan file generation.
+---
+
+# /plan - Project Planning Mode
+
+$ARGUMENTS
+
+---
+
+## 🔴 CRITICAL RULES
+
+1. **NO CODE WRITING** - This command creates plan file only
+2. **Use project-planner agent** - NOT Antigravity Agent's native Plan mode
+3. **Socratic Gate** - Ask clarifying questions before planning
+4. **Dynamic Naming** - Plan file named based on task
+
+---
+
+## Task
+
+Use the `project-planner` agent with this context:
+
+```
+CONTEXT:
+- User Request: $ARGUMENTS
+- Mode: PLANNING ONLY (no code)
+- Output: docs/PLAN-{task-slug}.md (dynamic naming)
+
+NAMING RULES:
+1. Extract 2-3 key words from request
+2. Lowercase, hyphen-separated
+3. Max 30 characters
+4. Example: "e-commerce cart" → PLAN-ecommerce-cart.md
+
+RULES:
+1. Follow project-planner.md Phase -1 (Context Check)
+2. Follow project-planner.md Phase 0 (Socratic Gate)
+3. Create PLAN-{slug}.md with task breakdown
+4. DO NOT write any code files
+5. REPORT the exact file name created
+```
+
+---
+
+## Expected Output
+
+| Deliverable | Location |
+|-------------|----------|
+| Project Plan | `docs/PLAN-{task-slug}.md` |
+| Task Breakdown | Inside plan file |
+| Agent Assignments | Inside plan file |
+| Verification Checklist | Phase X in plan file |
+
+---
+
+## After Planning
+
+Tell user:
+```
+[OK] Plan created: docs/PLAN-{slug}.md
+
+Next steps:
+- Review the plan
+- Run `/create` to start implementation
+- Or modify plan manually
+```
+
+---
+
+## Naming Examples
+
+| Request | Plan File |
+|---------|-----------|
+| `/plan e-commerce site with cart` | `docs/PLAN-ecommerce-cart.md` |
+| `/plan mobile app for fitness` | `docs/PLAN-fitness-app.md` |
+| `/plan add dark mode feature` | `docs/PLAN-dark-mode.md` |
+| `/plan fix authentication bug` | `docs/PLAN-auth-fix.md` |
+| `/plan SaaS dashboard` | `docs/PLAN-saas-dashboard.md` |
+
+---
+
+## Usage
+
+```
+/plan e-commerce site with cart
+/plan mobile app for fitness tracking
+/plan SaaS dashboard with analytics
+```

package/.achira/workflows/preview.md

@@ -0,0 +1,81 @@
+---
+description: Preview server start, stop, and status check. Local development server management.
+---
+
+# /preview - Preview Management
+
+$ARGUMENTS
+
+---
+
+## Task
+
+Manage preview server: start, stop, status check.
+
+### Commands
+
+```
+/preview           - Show current status
+/preview start     - Start server
+/preview stop      - Stop server
+/preview restart   - Restart
+/preview check     - Health check
+```
+
+---
+
+## Usage Examples
+
+### Start Server
+```
+/preview start
+
+Response:
+🚀 Starting preview...
+   Port: 3000
+   Type: Next.js
+
+✅ Preview ready!
+   URL: http://localhost:3000
+```
+
+### Status Check
+```
+/preview
+
+Response:
+=== Preview Status ===
+
+🌐 URL: http://localhost:3000
+📁 Project: C:/projects/my-app
+🏷️ Type: nextjs
+💚 Health: OK
+```
+
+### Port Conflict
+```
+/preview start
+
+Response:
+⚠️ Port 3000 is in use.
+
+Options:
+1. Start on port 3001
+2. Close app on 3000
+3. Specify different port
+
+Which one? (default: 1)
+```
+
+---
+
+## Technical
+
+Auto preview uses `auto_preview.py` script:
+
+```bash
+python .achira/scripts/auto_preview.py start [port]
+python .achira/scripts/auto_preview.py stop
+python .achira/scripts/auto_preview.py status
+```
+

package/.achira/workflows/react+vite.md

@@ -0,0 +1,280 @@
+---
+description: Scaffold a mature, scalable React + Vite project with Absolute Imports, React Router, and a Service-oriented architecture.
+---
+
+// turbo-all
+
+## 1. Create the Vite project
+
+```
+npx -y create-vite@latest ./ --template react
+```
+
+## 2. Install scalable architecture dependencies
+
+```
+npm install axios lucide-react react-router-dom
+npm install -D eslint prettier eslint-config-prettier vitest @testing-library/react @testing-library/jest-dom jsdom
+```
+
+## 3. Configure Absolute Imports (@)
+
+### vite.config.js
+
+```javascript
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { fileURLToPath, URL } from "node:url";
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      "@": fileURLToPath(new URL("./src", import.meta.url)),
+    },
+  },
+  test: {
+    globals: true,
+    environment: "jsdom",
+    setupFiles: "./src/test/setup.js",
+  },
+});
+```
+
+### jsconfig.json
+
+Add this to the project root so VS Code resolves `@/` imports:
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}
+```
+
+## 4. Create directory structure
+
+```
+mkdir src/pages src/components src/layouts src/hooks src/services src/utils src/globals src/styles src/test
+```
+
+## 5. Global CSS Architecture
+
+### src/globals/variables.css
+
+```css
+:root {
+  --color-primary: #6366f1;
+  --color-bg: #ffffff;
+  --color-text: #0f172a;
+  --transition-default: all 0.2s ease;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg: #0f172a;
+    --color-text: #f8fafc;
+  }
+}
+```
+
+### src/globals/reset.css
+
+```css
+*,
+*::before,
+*::after {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+html {
+  font-size: 16px;
+  scroll-behavior: smooth;
+}
+body {
+  font-family: system-ui;
+  background: var(--color-bg);
+  color: var(--color-text);
+  line-height: 1.6;
+}
+img {
+  max-width: 100%;
+  display: block;
+}
+button {
+  cursor: pointer;
+}
+```
+
+### src/globals/globals.css
+
+```css
+@import "./variables.css";
+@import "./reset.css";
+```
+
+## 6. Layout & Router Setup
+
+### src/layouts/MainLayout.jsx
+
+```jsx
+export default function MainLayout({ children }) {
+  return <div className="main-layout">{children}</div>;
+}
+```
+
+### src/router.jsx
+
+```jsx
+import { createBrowserRouter } from "react-router-dom";
+import Home from "@/pages/Home/Home";
+
+export const router = createBrowserRouter([{ path: "/", element: <Home /> }]);
+```
+
+### src/main.jsx
+
+```jsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { RouterProvider } from "react-router-dom";
+import { router } from "./router";
+import "./globals/globals.css";
+
+ReactDOM.createRoot(document.getElementById("root")).render(
+  <React.StrictMode>
+    <RouterProvider router={router} />
+  </React.StrictMode>,
+);
+```
+
+## 7. Folder Philosophy Pattern
+
+### src/pages/Home/Home.jsx
+
+```jsx
+import "./Home.css";
+import MainLayout from "@/layouts/MainLayout";
+
+export default function Home() {
+  return (
+    <MainLayout>
+      <div className="home-page">
+        <h1>Home</h1>
+      </div>
+    </MainLayout>
+  );
+}
+```
+
+### src/pages/Home/Home.css
+
+```css
+.home-page {
+  padding: 2rem;
+}
+```
+
+## 8. Services Layer
+
+### src/services/apiClient.js
+
+```javascript
+import axios from "axios";
+import { API_BASE_URL } from "@/globals/config";
+
+export const apiClient = axios.create({ baseURL: API_BASE_URL });
+```
+
+## 9. Environment setup
+
+### .env.example
+
+```
+VITE_APP_ENV=development
+VITE_API_URL=
+VITE_ENABLE_ANALYTICS=false
+```
+
+### src/globals/config.js
+
+```javascript
+export const APP_NAME = "Achira Project";
+export const API_BASE_URL = import.meta.env.VITE_API_URL || "";
+```
+
+## 10. Testing Setup
+
+### src/test/setup.js
+
+```javascript
+import "@testing-library/jest-dom";
+```
+
+### src/pages/Home/Home.test.jsx
+
+```jsx
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import Home from "./Home";
+
+describe("Home", () => {
+  it("renders the heading", () => {
+    render(<Home />);
+    expect(screen.getByText("Home")).toBeInTheDocument();
+  });
+});
+```
+
+Add this to `package.json` scripts:
+
+```json
+"scripts": {
+  "test": "vitest"
+}
+```
+
+## 11. Linter & Formatter Config
+
+### .eslintrc.cjs
+
+```javascript
+module.exports = {
+  root: true,
+  env: { browser: true, es2020: true },
+  extends: [
+    "eslint:recommended",
+    "plugin:react/recommended",
+    "plugin:react/jsx-runtime",
+    "plugin:react-hooks/recommended",
+    "prettier",
+  ],
+  parserOptions: { ecmaVersion: "latest", sourceType: "module" },
+  settings: { react: { version: "detect" } },
+  rules: {
+    "react/prop-types": "off",
+  },
+};
+```
+
+### .prettierrc
+
+```json
+{
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "all",
+  "printWidth": 100
+}
+```
+
+## 12. Clean up & Execute
+
+- Remove `src/App.css`, `src/index.css`, `src/App.jsx`.
+- Run `npm run dev`.

package/.achira/workflows/registry.json

@@ -0,0 +1,35 @@
+{
+  "engine": "3.x",
+  "engine_min": "3.0.0",
+  "version": "3.1.0",
+  "templates": {
+    "react": {
+      "workflow": "react+vite.md",
+      "description": "React + Vite SPA with Router, absolute imports, services layer",
+      "tags": ["frontend", "spa", "vite"]
+    },
+    "next": {
+      "workflow": "next.js.md",
+      "description": "Next.js App Router full-stack with feature-driven architecture",
+      "tags": ["fullstack", "ssr", "nextjs"]
+    },
+    "html": {
+      "workflow": "html+js+css.md",
+      "description": "Vanilla HTML + CSS + JS multi-page site with Vite dev server",
+      "tags": ["static", "vanilla", "vite"]
+    }
+  },
+  "commands": {
+    "brainstorm": { "workflow": "brainstorm.md", "description": "Socratic discovery" },
+    "create": { "workflow": "create.md", "description": "Create new features" },
+    "debug": { "workflow": "debug.md", "description": "Debug issues" },
+    "deploy": { "workflow": "deploy.md", "description": "Deploy application" },
+    "enhance": { "workflow": "enhance.md", "description": "Improve existing code" },
+    "orchestrate": { "workflow": "orchestrate.md", "description": "Multi-agent coordination" },
+    "plan": { "workflow": "plan.md", "description": "Task breakdown" },
+    "preview": { "workflow": "preview.md", "description": "Preview changes" },
+    "status": { "workflow": "status.md", "description": "Check project status" },
+    "test": { "workflow": "test.md", "description": "Run tests" },
+    "ui-ux-pro-max": { "workflow": "ui-ux-pro-max.md", "description": "Design with 50 styles" }
+  }
+}