npm - achira-wf - Versions diffs - 3.1.0 - Mend

achira-wf 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (229) hide show

package/.agent/workflows/next.js.md ADDED Viewed

@@ -0,0 +1,316 @@
+---
+description: Scaffold a scalable, production-ready Next.js App Router project with feature-based architecture.
+---
+// turbo-all
+## Goals
+- App Router for routing + layouts
+- Feature-based domain grouping
+- Clear Server vs. Client Component boundaries
+- Scalable from side project to SaaS
+---
+## 1. Create the Next.js Project
+```
+npx -y create-next-app@latest ./ --typescript --eslint --tailwind=false --app --src-dir --import-alias "@/*" --use-npm
+```
+---
+## 2. Install Core Dependencies
+```
+npm install axios lucide-react zod zustand
+```
+---
+## 3. Create the Full Directory Structure
+```
+mkdir src/components/ui src/components/layout src/components/feature
+mkdir src/features/auth src/features/user
+mkdir src/lib src/hooks src/services src/store src/styles src/types
+```
+Full structure:
+```
+src/
+├── app/                        # Next.js App Router (routing only)
+│   ├── layout.tsx
+│   ├── page.tsx
+│   ├── globals.css
+│   ├── (marketing)/            # Public-facing route group
+│   │   └── page.tsx
+│   ├── (dashboard)/            # Authenticated route group
+│   │   └── layout.tsx
+│   └── api/                    # Route handlers
+│
+├── components/                 # Shared UI
+│   ├── ui/                     # Primitives: Button, Card, Modal
+│   ├── layout/                 # Navbar, Sidebar, Footer
+│   └── feature/                # Composed feature-specific UI
+│
+├── features/                   # Feature-based domain logic
+│   ├── auth/
+│   │   ├── components/
+│   │   ├── hooks/
+│   │   ├── actions.ts          # Server Actions (Mutations)
+│   │   ├── service.ts
+│   │   └── types.ts
+│   └── user/
+│       ├── components/
+│       ├── hooks/
+│       ├── service.ts
+│       └── types.ts
+│
+├── lib/                        # Shared utilities (no external deps)
+│   ├── fetcher.ts
+│   ├── constants.ts
+│   ├── validators.ts
+│   └── env.ts                  # Zod-validated environment variables
+│
+├── hooks/                      # Global shared React hooks
+├── services/                   # External API integrations
+├── store/                      # Global state (Zustand)
+├── styles/                     # CSS Modules for complex, shared styles
+└── types/                      # Global TypeScript type definitions
+```
+---
+## 4. Set Up `src/app/globals.css`
+Replace default globals with a clean token-based reset.
+```css
+*,
+*::before,
+*::after {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+html {
+  font-size: 16px;
+  scroll-behavior: smooth;
+}
+img,
+picture,
+video,
+canvas,
+svg {
+  display: block;
+  max-width: 100%;
+}
+button {
+  cursor: pointer;
+}
+:root {
+  --color-primary: #6366f1;
+  --color-bg: #ffffff;
+  --color-text: #111827;
+  --font-sans: var(--font-geist-sans), system-ui, sans-serif;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg: #0f172a;
+    --color-text: #f8fafc;
+  }
+}
+body {
+  font-family: var(--font-sans);
+  background-color: var(--color-bg);
+  color: var(--color-text);
+  line-height: 1.6;
+}
+```
+---
+## 5. Create Root Layout `src/app/layout.tsx`
+```tsx
+import type { Metadata } from "next";
+import "./globals.css";
+export const metadata: Metadata = {
+  title: "My App",
+  description: "Generated with achira-wf",
+};
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+---
+## 6. Create Home Page `src/app/page.tsx`
+```tsx
+export default function HomePage() {
+  return (
+    <main>
+      <h1>Hello from Next.js App Router</h1>
+    </main>
+  );
+}
+```
+---
+## 7. Set Up Example Feature (`auth`)
+### `src/features/auth/types.ts`
+```ts
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+}
+```
+### `src/features/auth/service.ts`
+```ts
+import axios from "axios";
+import type { User } from "./types";
+export async function getMe(): Promise<User> {
+  const { data } = await axios.get("/api/auth/me");
+  return data;
+}
+```
+### `src/features/auth/hooks/useUser.ts`
+```ts
+"use client";
+import { useState, useEffect } from "react";
+import { getMe } from "../service";
+import type { User } from "../types";
+export function useUser() {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+  useEffect(() => {
+    getMe()
+      .then(setUser)
+      .finally(() => setLoading(false));
+  }, []);
+  return { user, loading };
+}
+```
+---
+## 8. Set Up Shared Lib
+### `src/lib/constants.ts`
+```ts
+export const APP_NAME = "My App";
+export const API_URL = process.env.NEXT_PUBLIC_API_URL ?? "";
+```
+### `src/lib/fetcher.ts`
+```ts
+export async function fetcher<T>(url: string): Promise<T> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Fetch error: ${res.status}`);
+  return res.json();
+}
+```
+### `src/lib/env.ts`
+Validate environment variables at build time with Zod. Import this in `layout.tsx` or a server-only module so it runs at startup.
+```ts
+import { z } from "zod";
+const envSchema = z.object({
+  NEXT_PUBLIC_API_URL: z.string().url().optional().default(""),
+  NEXT_PUBLIC_APP_ENV: z
+    .enum(["development", "staging", "production"])
+    .default("development"),
+  DATABASE_URL: z.string().min(1, "DATABASE_URL is required"),
+});
+export const env = envSchema.parse(process.env);
+```
+---
+## 9. Create `.env.example`
+```
+NEXT_PUBLIC_API_URL=
+NEXT_PUBLIC_APP_ENV=development
+DATABASE_URL=
+```
+---
+## 10. CSS Strategy Note
+| Location                  | Use For                                                                                 |
+| ------------------------- | --------------------------------------------------------------------------------------- |
+| `src/app/globals.css`     | CSS reset, CSS custom properties (`:root`), global body styles                          |
+| `src/styles/*.module.css` | Complex, shared styles used across multiple components (e.g., form layouts, card grids) |
+| Co-located `.module.css`  | Component-specific styles that live next to their component file                        |
+**Rule:** Default to co-located CSS Modules. Only use `src/styles/` for truly cross-cutting layouts that don't belong to any single component.
+---
+## 11. Start the Dev Server
+```
+npm run dev
+```
+---
+## Component Guidelines
+| Rule                                      | Reason                                        |
+| ----------------------------------------- | --------------------------------------------- |
+| Default to **Server Components**          | Better performance, less JS sent to client    |
+| Use `"use client"` only at the leaf level | Keeps SSR benefits higher in the tree         |
+| No business logic in `page.tsx`           | Pages are wiring only — delegate to features  |
+| Services handle all network calls         | Hooks are for state/effects, not fetching raw |
+---
+## Scalability Path
+| Stage      | Add                                                      |
+| ---------- | -------------------------------------------------------- |
+| Small      | `app/`, `components/`, `lib/`                            |
+| Growing    | Introduce `features/`, `services/`, feature-scoped hooks |
+| Enterprise | Strict feature boundaries, API abstraction, `store/`     |

package/.agent/workflows/orchestrate.md ADDED Viewed

@@ -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/.agent/workflows/plan.md ADDED Viewed

@@ -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/.agent/workflows/preview.md ADDED Viewed

@@ -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
+```