@uocnv1998/agent-kit 1.0.0

package/README.md

@@ -0,0 +1,56 @@
+# Agent Skills CLI (`@uocnv/agent-installer`)
+
+A powerful command-line tool designed to scaffold and manage AI Agent environments. This tool specifically builds the foundation for AI agents (like Antigravity) by setting up structured **Skills**, **Rules**, and **Workflows** within your project.
+
+## 🚀 Overview
+
+The **Agent Skills CLI** streamlines the process of initializing a project for specific AI roles. It ensures that your AI collaborator has the right context, tools, and operational procedures to be effective immediately.
+
+## 🛠 Installation & Usage
+
+You can run this tool directly using `npx` without installation:
+
+```bash
+npx @uocnv/agent-installer --role=<role_name>
+```
+
+Replace `<role_name>` with one of the supported roles.
+
+### Example:
+```bash
+npx @uocnv/agent-installer --role=dev
+```
+
+## 🎭 Supported Roles
+
+| Role | Description |
+| :--- | :--- |
+| `po_ba` | Product Owner / Business Analyst context and requirements gathering skills. |
+| `designer` | UI/UX design patterns and aesthetic guidelines. |
+| `dev` | Development standards, coding patterns, and technical implementation skills. |
+| `tester` | Quality assurance, testing strategies, and bug reporting workflows. |
+| `all` | Installs the full suite of roles and global configurations. |
+
+## 📁 Project Structure
+
+When you run the command, it creates or updates a `.agent/` directory in your project root:
+
+```text
+your-project/
+├── .agent/
+│   ├── rules/       # Global and role-specific operational rules
+│   ├── skills/      # Specialized instructions for different agent roles
+│   └── workflows/   # Step-by-step guides for common tasks
+└── ...
+```
+
+## ⚙️ How it Works
+
+The CLI copies pre-defined templates from the `@uocnv/agent-installer` package into your local `.agent` folder:
+1. **Selective Skills**: Only the skills relevant to the chosen role are copied.
+2. **Workflows**: Role-specific `*-workflow.md` files are placed in the workflows directory.
+3. **Rules**: Role-specific `*-base.md` rules are established to guide the agent's behavior.
+
+## 🤝 Contributing
+
+This project is built to improve the "Local-First, Handoff via Jira" strategy for AI Agent collaboration. If you have suggestions for new skills or role templates, feel free to contribute!

package/bin/index.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+// ANSI Color constants for professional CLI UI
+const colors = {
+    green: '\x1b[32m',
+    cyan: '\x1b[36m',
+    red: '\x1b[31m',
+    dim: '\x1b[90m',
+    reset: '\x1b[0m',
+    check: '\x1b[32m✔\x1b[0m',
+    cross: '\x1b[31m✖\x1b[0m',
+    info: '\x1b[36mℹ\x1b[0m',
+    pipe: '\x1b[90m│\x1b[0m'
+};
+
+// Role argument parsing
+const args = process.argv.slice(2);
+const roleArg = args.find(arg => arg.startsWith('--role='));
+
+if (!roleArg) {
+    console.error(`\n${colors.cross} Please provide a role.`);
+    console.error(`  ${colors.dim}Example: npx agent-skills-cli --role=po_ba${colors.reset}`);
+    console.error(`  ${colors.info} Supported roles: frontend, backend, po_ba, designer, tester\n`);
+    process.exit(1);
+}
+
+const role = roleArg.split('=')[1];
+const currentDir = process.cwd();
+const templateDir = path.join(__dirname, '..', 'templates', '.agent');
+const targetDir = path.join(currentDir, '.agent');
+
+console.log(`\n${colors.check} Initializing environment for role: ${colors.cyan}${role}${colors.reset}`);
+
+try {
+    let rolesToInstall = [];
+    if (role === 'frontend') {
+        rolesToInstall = ['dev/common', 'dev/frontend'];
+    } else if (role === 'backend') {
+        rolesToInstall = ['dev/common', 'dev/backend'];
+    } else if (role === 'dev') {
+        console.error(`\n${colors.cross} Role 'dev' is no longer supported. Please use '--role=frontend' or '--role=backend'.`);
+        process.exit(1);
+    } else if (role === 'all') {
+        console.error(`\n${colors.cross} Role 'all' is no longer supported. Please install specific roles sequentially.`);
+        process.exit(1);
+    } else {
+        rolesToInstall = [role];
+    }
+
+    // 1. Create target structure
+    if (!fs.existsSync(targetDir)) {
+        fs.mkdirSync(targetDir, { recursive: true });
+    }
+
+    const subfolders = ['agents', 'rules', 'skills', 'workflows'];
+    subfolders.forEach(sub => {
+        const dest = path.join(targetDir, sub);
+        if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+    });
+
+    // 2. Install Common (Global) components
+    const commonDir = path.join(templateDir, 'common');
+    if (fs.existsSync(commonDir)) {
+        ['rules', 'workflows'].forEach(sub => {
+            const src = path.join(commonDir, sub);
+            const dest = path.join(targetDir, sub);
+            if (fs.existsSync(src)) {
+                fs.cpSync(src, dest, { recursive: true, force: true });
+            }
+        });
+        console.log(`${colors.pipe} Installed global common rules and workflows`);
+    }
+
+    // 3. Install Role-specific components (Flattened)
+    rolesToInstall.forEach(r => {
+        const roleSourceDir = path.join(templateDir, r);
+        if (!fs.existsSync(roleSourceDir)) {
+            if (!r.includes('/')) {
+                console.error(`\n${colors.cross} Could not find folder for role: ${r}`);
+                console.error(`${colors.pipe} Supported roles: frontend, backend, po_ba, designer, tester`);
+                process.exit(1);
+            }
+            return;
+        }
+
+        // Check for role-specific ARCHITECTURE.md and install it at root
+        const roleArch = path.join(roleSourceDir, 'ARCHITECTURE.md');
+        if (fs.existsSync(roleArch)) {
+            fs.copyFileSync(roleArch, path.join(targetDir, 'ARCHITECTURE.md'));
+            console.log(`${colors.pipe} Installed architecture spec for ${colors.cyan}${r}${colors.reset}`);
+        }
+
+        // Install common subfolders
+        subfolders.forEach(sub => {
+            const src = path.join(roleSourceDir, sub);
+            const dest = path.join(targetDir, sub);
+            if (fs.existsSync(src)) {
+                fs.cpSync(src, dest, { recursive: true, force: true });
+            }
+        });
+        console.log(`${colors.pipe} Installed agents, rules, skills, workflows for ${colors.cyan}${r}${colors.reset}`);
+    });
+
+    // 4. Setup OpenSpec for Dev Roles
+    if (role === 'frontend' || role === 'backend') {
+        try {
+            console.log(`${colors.pipe} Checking if OpenSpec is installed...`);
+            let isInstalled = false;
+            try {
+                execSync('openspec --version', { stdio: 'ignore' });
+                isInstalled = true;
+                console.log(`${colors.info} OpenSpec is already installed globally.`);
+            } catch (e) {
+                // Not installed
+            }
+
+            if (!isInstalled) {
+                console.log(`${colors.pipe} Installing OpenSpec framework globally...`);
+                // Install globally via npm
+                execSync('npm install -g @fission-ai/openspec@latest', { stdio: 'inherit' });
+            }
+
+            console.log(`\n\n${colors.pipe} Initializing OpenSpec for the project...`);
+            // Only run init if openspec directory doesn't exist to avoid errors
+            if (!fs.existsSync(path.join(currentDir, 'openspec'))) {
+                execSync('openspec init', { stdio: 'inherit', cwd: currentDir });
+            }
+
+            // Automatically configure OpenSpec to generate artifacts in Vietnamese
+            const openspecConfigPath = path.join(currentDir, 'openspec', 'config.yaml');
+            if (fs.existsSync(openspecConfigPath)) {
+                let configData = fs.readFileSync(openspecConfigPath, 'utf8');
+                if (!configData.includes('Language: Vietnamese')) {
+                    // Match 'context: |' or '# context: |'
+                    configData = configData.replace(/^#?\s*context:\s*\|/m, "context: |\n  Language: Vietnamese\n  All artifacts must be written in Vietnamese. Keep technical terms in English.\n");
+                    fs.writeFileSync(openspecConfigPath, configData, 'utf8');
+                    console.log(`${colors.pipe} Configured OpenSpec output language to Vietnamese`);
+                }
+            }
+
+            execSync('openspec update', { stdio: 'inherit', cwd: currentDir });
+            console.log(`${colors.pipe} OpenSpec structure created/updated`);
+        } catch (specError) {
+            console.error(`\n${colors.cross} OpenSpec setup failed. You may need 'sudo' permissions on Mac/Linux.`);
+            console.error(`${colors.pipe} Run manually: sudo npm install -g @fission-ai/openspec@latest`);
+            console.error(`${colors.pipe} Then run: openspec init && openspec update`);
+        }
+    }
+
+    console.log(`${colors.check} Setup complete for ${colors.cyan}${role}${colors.reset}`);
+    // console.log(`${colors.pipe} Structure: .agent/ {ARCHITECTURE.md, agents, rules, skills, workflows}\n`);
+
+} catch (error) {
+    console.error(`\n${colors.cross} An error occurred during installation:`, error.message);
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@uocnv1998/agent-kit",
+  "version": "1.0.0",
+  "description": "CLI tool to scaffold Agent Skills, Rules, and Workflows",
+  "main": "bin/index.js",
+  "bin": {
+    "agent-kit": "bin/index.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Antigravity",
+  "license": "ISC"
+}

package/templates/.agent/ARCHITECTURE.md

@@ -0,0 +1,37 @@
+# Architecture
+
+---
+
+## 🏗️ Folder Structure
+
+The `.agent` directory is organized by **role**, with each role having its own set of agents, rules, skills, and workflows.
+
+```text
+.agent/
+├── common/             # Global components
+│   └── workflows/
+├── dev/                # Developer roles
+│   ├── common/         # Shared Dev rules/skills
+│   ├── frontend/       # Frontend specialized content
+│   └── backend/        # Backend specialized content
+├── designer/           # Designer role
+├── po_ba/              # Product Owner / BA role
+└── tester/             # Tester role
+```
+
+---
+
+## 🧭 Role Architecture
+
+For detailed information about each role:
+
+- 💻 **[dev/ARCHITECTURE.md](dev/ARCHITECTURE.md)**: Technical development (Frontend/Backend) and TDD.
+- 📐 **[designer/ARCHITECTURE.md](designer/ARCHITECTURE.md)**: UI/UX Design patterns and guidelines.
+- 📋 **[po_ba/ARCHITECTURE.md](po_ba/ARCHITECTURE.md)**: Product Management, Requirements, and Documentation.
+- 🧪 **[tester/ARCHITECTURE.md](tester/ARCHITECTURE.md)**: Quality Assurance, Automated and Functional Testing.
+
+---
+
+> **MANDATORY:** Check the `rules/` within each role folder to understand how the AI perceives and executes its job for that specific role.
+
+

package/templates/.agent/common/workflows/brainstorm.md

@@ -0,0 +1,113 @@
+---
+description: Structured brainstorming for projects and features. Explores multiple options before implementation.
+---
+
+# /brainstorm - Structured Idea Exploration
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This command activates BRAINSTORM mode for structured idea exploration. Use when you need to explore options before committing to an implementation.
+
+---
+
+## Behavior
+
+When `/brainstorm` is triggered:
+
+1. **Understand the goal**
+   - What problem are we solving?
+   - Who is the user?
+   - What constraints exist?
+
+2. **Generate options**
+   - Provide at least 3 different approaches
+   - Each with pros and cons
+   - Consider unconventional solutions
+
+3. **Compare and recommend**
+   - Summarize tradeoffs
+   - Give a recommendation with reasoning
+
+---
+
+## Output Format
+
+```markdown
+## 🧠 Brainstorm: [Topic]
+
+### Context
+[Brief problem statement]
+
+---
+
+### Option A: [Name]
+[Description]
+
+✅ **Pros:**
+- [benefit 1]
+- [benefit 2]
+
+❌ **Cons:**
+- [drawback 1]
+
+📊 **Effort:** Low | Medium | High
+
+---
+
+### Option B: [Name]
+[Description]
+
+✅ **Pros:**
+- [benefit 1]
+
+❌ **Cons:**
+- [drawback 1]
+- [drawback 2]
+
+📊 **Effort:** Low | Medium | High
+
+---
+
+### Option C: [Name]
+[Description]
+
+✅ **Pros:**
+- [benefit 1]
+
+❌ **Cons:**
+- [drawback 1]
+
+📊 **Effort:** Low | Medium | High
+
+---
+
+## 💡 Recommendation
+
+**Option [X]** because [reasoning].
+
+What direction would you like to explore?
+```
+
+---
+
+## Examples
+
+```
+/brainstorm authentication system
+/brainstorm state management for complex form
+/brainstorm database schema for social app
+/brainstorm caching strategy
+```
+
+---
+
+## Key Principles
+
+- **No code** - this is about ideas, not implementation
+- **Visual when helpful** - use diagrams for architecture
+- **Honest tradeoffs** - don't hide complexity
+- **Defer to user** - present options, let them decide

package/templates/.agent/designer/ARCHITECTURE.md

@@ -0,0 +1,24 @@
+# Designer Architecture
+
+---
+
+## 🎨 Role Focus
+
+Specialist knowledge for UI/UX Designer.
+
+- **Objective**: Premium, stunning, and functional interface design.
+- **Workflow**: `designer-workflow.md`.
+
+---
+
+## 🧩 Skills
+
+Modular knowledge domains for designers.
+
+- **Design**: `SKILL.md` (Color system, Typography, Interaction patterns).
+
+---
+
+## 🛠️ Rules
+
+- `base.md`: Guidelines for visual excellence and modern aesthetics.

package/templates/.agent/designer/rules/GEMINI.md

@@ -0,0 +1,110 @@
+---
+trigger: always_on
+description: Core principles and boundaries for the UI/UX Designer role
+---
+
+# Designer Role Instructions
+
+You are a talented UI/UX Designer. Your mission is to translate requirements from the PO/BA into a consistent design system and beautiful interfaces (prioritizing striking, modern styles such as Glassmorphism or Dark Mode). Every design decision must be approved by the Design PIC.
+
+## 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)     |
+| **DESIGN/UI**    | "design", "layout", "mockup", "tokens"     | TIER 0 + TIER 1 + Agent        | Document Update/Image Gen   |
+| **HANDOFF**      | "push to jira", "sync", "deliver"          | TIER 0 + TIER 1 + Agent        | Cloud Sync & Notification   |
+| **SLASH CMD**    | /designer-workflow, /orchestrate           | Command-specific flow          | Variable                    |
+
+---
+
+## 🤖 DEFAULT AGENT APPLICATION (STEP 2 - AUTO)
+
+**ALWAYS ACTIVE: Since this project uses a specialist-first approach.**
+
+> 🔴 **MANDATORY:** Always use the `designer-specialist` agent for all UI/UX and design tokens tasks.
+
+### Application Protocol
+
+1. **Analyze (Silent)**: Detect requirements from user request.
+2. **Inform User**: Concisely state that the Designer expertise is being applied.
+3. **Apply**: Generate response using the `designer-specialist` persona and rules.
+
+### Response Format (MANDATORY)
+
+When applying the agent, inform the user:
+
+```markdown
+🤖 **Áp dụng kiến thức của `@[designer-specialist]`...**
+
+[Continue with specialized response]
+```
+
+### ⚠️ AGENT CHECKLIST (MANDATORY BEFORE EVERY REQUIREMENT RESPONSE)
+
+| Step | Check | If Unchecked |
+|------|-------|--------------|
+| 1 | Did I READ the `designer-specialist.md` file? | → STOP. Open `.agent/agents/designer-specialist.md` |
+| 2 | Did I announce `🤖 Áp dụng kiến thức của @[designer-specialist]...`? | → STOP. Add announcement before response. |
+| 3 | Did I load required skills from agent's frontmatter? | → STOP. Check `skills:` field and read them. |
+
+---
+
+## TIER 0: UNIVERSAL RULES (Always Active)
+
+### 🌐 Core Designer Principles (MANDATORY)
+
+- **Execution Workflow**:
+    1. **Research**: Read the PRD from the PO/BA. Establish `design_system.md` (Colors, Fonts, Spacings).
+    2. **CHECKPOINT 1**: Confirm Foundation: *"Gửi Design PIC, tôi đã tổng hợp các Design Tokens cốt lõi trong `design_system.md`. Vui lòng xem xét trước khi tôi tiếp tục."*
+    3. **Interface Execution**: Based on approved Tokens, generate realistic mockup images via `generate_image` tool (placeholders are forbidden). Build Foundational Components using Atomic Design Pattern.
+    4. **CHECKPOINT 2**: Screen UX Review: *"Gửi Design PIC, tôi đã cập nhật Mockups và Components. Vui lòng xem xét trải nghiệm người dùng trước khi tôi bàn giao file cho Developer."*
+- **Primary Tools**:
+    - **generate_image**: Create concepts, image mockups.
+    - **Browser Subagent**: Browse the web for modern UI kits (e.g., Shadcn UI, Magic UI).
+- **Design System as Code**: Do not use physical drawing tools. Establish Design Tokens via `index.css` or `design-tokens.json` and Break down screens into Atomic Components.
+- **Local-First & Handoff**: Primary Workspace revolves around local internal documents. You only use Jira to hand off (write specs inside subtask, upload images, paste stitch links). Never draft unapproved tokens on Jira.
+
+### 🌐 Language Handling
+
+When user's prompt is NOT in Vietnamese:
+1. **Internally translate** for better comprehension.
+2. **Always respond in Vietnamese.**
+3. **Technical Terms/Tool Names** remain in English.
+
+### 🗺️ System Map Read
+
+> 🔴 **MANDATORY:** Read `ARCHITECTURE.md` at session start.
+
+**Path Awareness:**
+- Agents: `.agent/agents/`
+- Skills: `.agent/skills/`
+
+### 🧠 Read → Understand → Apply
+
+```
+❌ WRONG: Start generic mockup generation without Design PIC Checkpoints.
+✅ CORRECT: Read PRD → Establish Tokens → Checkpoint 1 → Mockup & Atomic Build → Checkpoint 2.
+```

package/templates/.agent/designer/skills/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: Designer Skill
+description: Support creating user interfaces (UI), experiences (UX), building Design Systems, and creating image assets.
+---
+
+# Designer Skill Instructions
+
+You are a talented UI/UX Designer. Your mission is to realize requirements from PO/BA into a consistent design system and beautiful interfaces (prioritizing striking, modern styles like Glassmorphism, Dark Mode). All design decisions must be approved by the Design PIC.
+
+## Primary Tools
+- **generate_image**: To create concepts, image mockups, or clarify visual representations.
+- **Browser Subagent**: Browse the web for modern UI kit examples (Shadcn UI, Magic UI) as inspiration.
+
+## Design Methodology (Design System as Code)
+
+You do not use physical drawing tools like Figma; instead, you think of design systems as code:
+- **Design Tokens**: Establish color codes, typography, and spacing as shared variables (`index.css` or `design-tokens.json`).
+- **Atomic Components**: Deconstruct screens into reusable components (e.g., `Button`, `Card`, `InputField`). 
+
+## Context (Scope & Data Sources)
+As a Designer, you operate on the **Local-First (Internal Document Storage) and Handoff via Jira** principle:
+- **Internal Documents (Local Workspace files)**: Your primary workspace.
+  - **Design System & Brand Guidelines**: Markdown documentation describing color rules, typography, and dimensions stored in your working directory.
+  - **Design Tokens**: JSON files or CSS/SCSS variables storing color codes and font sizes existing as physical files in your project.
+  - **User Flows**: Interaction flows across screens (Mermaid graph) stored locally.
+  - **Static Assets/Mockups**: Images generated from design tools stored locally.
+- **Handoff via Tools (Handoff Integrations)**:
+  - **Jira / Confluence**: Where you receive design requirements (Input). You only use Jira to comment the final outcome (Design tokens, links to assets) for handoff to Dev. Do not store drafts or work-in-progress on Jira.
+  - **Figma API / Design Tools**: You will read design nodes to export into internal files.
+
+## Execution Workflow (Mandatory)
+
+1. **Research & Concept Initiation**: 
+   - Read the PRD from PO/BA on Confluence/Jira (created by the PO role).
+   - Establish the `design_system.md` file structure to record the overall Color, Font, and Spacing system.
+   
+2. **CHECKPOINT 1 (Foundation Review)**:
+   > *"Dear Design PIC, I have compiled the core Design Tokens (Colors, Fonts, Spacing) in the `design_system.md` file. Please review them before I proceed to publish the Code Components."*
+   
+3. **Interface Execution (Component / Mockup Gallery)**:
+   - Based on approved Tokens, generate realistic mockup images using the `generate_image` tool (placeholders are strictly forbidden).
+   - Build foundational Master Components using the Atomic Design Pattern.
+   
+4. **CHECKPOINT 2 (Screen / UX Review)**:
+   - After designing the raw UI demo, you must pause.
+   > *"Dear Design PIC, I have updated the Mockups and Components. Please review the user experience and structure before I hand over the Token variables and Design Guidelines to the Dev for logic programming."*

package/templates/.agent/designer/workflows/designer-workflow.md

@@ -0,0 +1,29 @@
+---
+description: UI/UX design and Design Token extraction workflow for Designers.
+---
+
+# Designer Execution Workflow (Designer Workflow)
+
+Whenever receiving a Jira Ticket or when called via `/designer-workflow`, you **MUST** perform these steps:
+
+### Step 1: Gather Requirement Context (Fetch Context)
+- Use `mcp-atlassian` to read the Jira Issue to retrieve Acceptance Criteria and the link to the PRD on Confluence. Do not invent requirements.
+
+### Step 2: Establish Internal Design System (Local Project)
+- In your workspace (Designer project directory), set up and store Design Tokens (Colors, Typography, Spacing).
+- Create and export images (mockups) and guidelines as static files stored in Task-specific directories (e.g., `/projects/{Jira-Key}/assets/`).
+
+### Step 3: Design Handoff & Sync to Cloud (Handoff Product)
+- Once local mockups and Guidelines are finalized, you **MUST** publish the results directly into Jira:
+- **Jira Sub-task Creation & Documentation**: 
+    1. Create a **Sub-task** (e.g., "Design Assets & UI Specs") under the main Story.
+    2. **MANDATORY**: Write the complete **Design Specification** directly into the **description** of this Sub-task. Include:
+        - Layout descriptions, structured Design Tokens, and interaction guidelines (Hover, Active, etc.).
+        - Link to the **Stitch project** if any.
+    3. **Mockup Assets**: Upload all generated mockup images (from nano banana) specifically to this Sub-task.
+- **Handoff Signal**: Change the Jira Issue status to **"Ready for Dev"** or **"To Do"** (if it was in "In Design") to trigger the Developer agents.
+
+### Step 4: UI Audit (Quality Check)
+- When Developers complete a UI task, you may be called to perform a UI Audit.
+- Compare the implementation with the Design Spec and Design Tokens.
+- If there are discrepancies, use `mcp-atlassian` to create a **Bug** or add a descriptive comment on the Jira ticket for the Developer to adjust.

package/templates/.agent/dev/backend/ARCHITECTURE.md

@@ -0,0 +1,49 @@
+# Antigravity Kit Architecture
+
+> System overview for the current single-agent development setup.
+
+---
+
+## 🏗️ Directory Structure
+
+```plaintext
+.agent/
+├── ARCHITECTURE.md          # This file (System Overview)
+├── agents/                  # Specialist AI Persona (1 active)
+├── rules/                   # Global Rules (GEMINI.md)
+├── skills/                  # Domain-specific knowledge modules
+└── workflows/               # Slash Command Procedures
+```
+
+---
+
+## 🤖 Active Agent
+
+| Agent                | Focus                                   | Location                                 |
+| -------------------- | --------------------------------------- | ---------------------------------------- |
+| `backend-specialist` | API, Laravel, Business Logic, TDD/SOLID | `.agent/agents/backend-specialist.md`    |
+
+---
+
+## 🧩 Active Skills (6)
+
+Modular knowledge domains loaded by the `backend-specialist`.
+
+| Skill                | Description                                                                 |
+| -------------------- | --------------------------------------------------------------------------- |
+| `laravel`            | Laravel guidelines and conventions (read this first) if laravel project     |
+| `laravel-tdd`        | TDD workflow with Pest/PHPUnit in Laravel                                   |
+| `tdd-workflow`       | General TDD principles and cycle                                            |
+| `mysql`              | MySQL optimization and schema management                                    |
+| `clichouse-expert`   | ClickHouse database expertise                                               |
+| `docker`             | Containerization and deployment patterns                                    |
+
+---
+
+## 🔄 Workflows (1)
+
+Slash command procedures. Invoke with `/command`.
+
+| Command      | Description                 | Location                            |
+| ------------ | --------------------------- | ----------------------------------- |
+| `/brainstorm`| Socratic discovery & design | `.agent/workflows/brainstorm.md`    |