Skip to content

refactor: resolve top 5 critical technical debts #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vkaylee merged 6 commits into from
Jun 22, 2026
Merged

refactor: resolve top 5 critical technical debts #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d5617b3
feat: resolve 5 critical API technical debts and add tests
Jun 21, 2026
eb4cc59
refactor: resolve critical tech debts, split src/lib.rs, enforce enca…
Jun 22, 2026
0215092
refactor: resolve 5 critical technical debts including is_alive timeo…
Jun 22, 2026
35162c5
refactor: resolve critical technical debts (structured error codes, c…
Jun 22, 2026
842d384
refactor: resolve top 5 critical technical debts
Jun 22, 2026
506503b
style: run cargo fmt
Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
312 changes: 312 additions & 0 deletions .agents/ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,312 @@
# AG Kit Architecture

> Comprehensive AI Agent Capability Expansion Toolkit — 2026.5.25

---

## 📋 Overview

AG Kit is a modular system consisting of:

- **20 Specialist Agents** - Role-based AI personas (1 major upgrade in 2026.5.13)
- **45 Skills** - Domain-specific knowledge modules with conditional loading
- **13 Workflows** - Slash command procedures

---

## 🏗️ Directory Structure

```plaintext
.agents/
├── ARCHITECTURE.md # This file
├── agent/ # 20 Specialist Agents
├── skills/ # 45 Skills (with conditional loading)
├── workflows/ # 13 Slash Commands
├── rules/ # Global Rules
├── memory/ # Persistent Memory (2026.5.13)
└── scripts/ # Master Validation Scripts
```

---

## 🤖 Agents (20)

Specialist AI personas for different domains.

| Agent | Focus | Skills Used |
| ------------------------ | -------------------------- | -------------------------------------------------------- |
| `orchestrator` | Multi-agent coordination | parallel-agents, coordinator-mode, memory-system, context-compression, verify-changes |
| `project-planner` | Discovery, task planning | brainstorming, plan-writing, architecture |
| `frontend-specialist` | Web UI/UX | frontend-design, react-best-practices, tailwind-patterns |
| `backend-specialist` | API, business logic | api-patterns, nodejs-best-practices, database-design |
| `database-architect` | Schema, SQL | database-design, prisma-expert |
| `mobile-developer` | iOS, Android, RN | mobile-design |
| `game-developer` | Game logic, mechanics | game-development |
| `devops-engineer` | CI/CD, Docker | deployment-procedures, docker-expert |
| `security-auditor` | Security compliance | vulnerability-scanner, red-team-tactics |
| `penetration-tester` | Offensive security | red-team-tactics |
| `test-engineer` | Testing strategies | testing-patterns, tdd-workflow, webapp-testing |
| `debugger` | Root cause analysis | systematic-debugging |
| `performance-optimizer` | Speed, Web Vitals | performance-profiling |
| `seo-specialist` | Ranking, visibility | seo-fundamentals, geo-fundamentals |
| `documentation-writer` | Manuals, docs | documentation-templates |
| `product-manager` | Requirements, user stories | plan-writing, brainstorming |
| `product-owner` | Strategy, backlog, MVP | plan-writing, brainstorming |
| `qa-automation-engineer` | E2E testing, CI pipelines | webapp-testing, testing-patterns |
| `code-archaeologist` | Legacy code, refactoring | clean-code, code-review-checklist |
| `explorer-agent` | Codebase analysis | - |

---

## 🧩 Skills (45)

Modular knowledge domains that agents can load on-demand based on task context. Each skill has a `when_to_use` frontmatter field for conditional/intelligent loading.

### Frontend & UI

| Skill | Description |
| ----------------------- | --------------------------------------------------------------------- |
| `react-best-practices` | React & Next.js performance optimization (Vercel - 57 rules) |
| `web-design-guidelines` | Web UI audit - 100+ rules for accessibility, UX, performance (Vercel) |
| `tailwind-patterns` | Tailwind CSS v4 utilities |
| `frontend-design` | UI/UX patterns, design systems |

### Backend & API

| Skill | Description |
| ----------------------- | ------------------------------ |
| `api-patterns` | REST, GraphQL, tRPC |
| `nestjs-expert` | NestJS modules, DI, decorators |
| `nodejs-best-practices` | Node.js async, modules |
| `python-patterns` | Python standards, FastAPI |

### Database

| Skill | Description |
| ----------------- | --------------------------- |
| `database-design` | Schema design, optimization |
| `prisma-expert` | Prisma ORM, migrations |

### TypeScript/JavaScript

| Skill | Description |
| ------------------- | ----------------------------------- |
| `typescript-expert` | Type-level programming, performance |

### Cloud & Infrastructure

| Skill | Description |
| ----------------------- | ------------------------- |
| `docker-expert` | Containerization, Compose |
| `deployment-procedures` | CI/CD, deploy workflows |
| `server-management` | Infrastructure management |

### Testing & Quality

| Skill | Description |
| ----------------------- | ------------------------ |
| `testing-patterns` | Jest, Vitest, strategies |
| `webapp-testing` | E2E, Playwright |
| `tdd-workflow` | Test-driven development |
| `code-review-checklist` | Code review standards |
| `lint-and-validate` | Linting, validation |

### Security

| Skill | Description |
| ----------------------- | ------------------------ |
| `vulnerability-scanner` | Security auditing, OWASP |
| `red-team-tactics` | Offensive security |

### Architecture & Planning

| Skill | Description |
| --------------- | -------------------------- |
| `app-builder` | Full-stack app scaffolding |
| `architecture` | System design patterns |
| `plan-writing` | Task planning, breakdown |
| `brainstorming` | Socratic questioning |

### Mobile

| Skill | Description |
| --------------- | --------------------- |
| `mobile-design` | Mobile UI/UX patterns |

### Game Development

| Skill | Description |
| ------------------ | --------------------- |
| `game-development` | Game logic, mechanics |

### SEO & Growth

| Skill | Description |
| ------------------ | ----------------------------- |
| `seo-fundamentals` | SEO, E-E-A-T, Core Web Vitals |
| `geo-fundamentals` | GenAI optimization |

### Shell/CLI

| Skill | Description |
| -------------------- | ------------------------- |
| `bash-linux` | Linux commands, scripting |
| `powershell-windows` | Windows PowerShell |

### Orchestration & Memory (2026.5.13)

| Skill | Description |
| ------------------------- | ----------------------------------------------------------- |
| `coordinator-mode` | Multi-agent orchestration with parallel workers & synthesis |
| `memory-system` | Persistent cross-session memory with MEMORY.md index |
| `context-compression` | Auto-compress context in long sessions |
| `verify-changes` | Prove code works by running it, not just inspecting |
| `batch-operations` | Multi-file pattern-based modifications |
| `simplify-code` | Reduce over-engineered complexity |
| `skillify` | Auto-create skills from repetitive workflows |
| `code-review-graph` | Token-efficient code review via Tree-sitter AST + MCP |

### Other

| Skill | Description |
| ------------------------- | ------------------------- |
| `clean-code` | Coding standards (Global) |
| `behavioral-modes` | Agent personas |
| `parallel-agents` | Multi-agent patterns |
| `mcp-builder` | Model Context Protocol |
| `documentation-templates` | Doc formats |
| `i18n-localization` | Internationalization |
| `performance-profiling` | Web Vitals, optimization |
| `systematic-debugging` | Troubleshooting |

---

## 🔄 Workflows (13)

Slash command procedures. Invoke with `/command`.

| Command | Description |
| ---------------- | ---------------------------------------------- |
| `/brainstorm` | Socratic discovery |
| `/coordinate` | **NEW** Advanced multi-agent coordination |
| `/create` | Create new features |
| `/debug` | Debug issues |
| `/deploy` | Deploy application |
| `/enhance` | Improve existing code |
| `/orchestrate` | Multi-agent coordination |
| `/plan` | Task breakdown |
| `/preview` | Preview changes |
| `/remember` | **NEW** Save to persistent memory |
| `/status` | Check project status |
| `/test` | Run tests |
| `/verify` | **NEW** Prove code works by running it |

---

## 🎯 Skill Loading Protocol (2026.5.13 — Conditional)

```plaintext
User Request → Check `when_to_use` frontmatter → Match? → Load full SKILL.md
↓ No match
Skip (save tokens)
```

### Skill Structure

```plaintext
skill-name/
├── SKILL.md # (Required) Metadata, when_to_use & instructions
├── scripts/ # (Optional) Python/Bash scripts
├── references/ # (Optional) Templates, docs
└── assets/ # (Optional) Images, logos
```

### Required Frontmatter Fields

```yaml
---
name: skill-name
description: What this skill does
when_to_use: "When to activate. NOT for X." # 2026.5.13
allowed-tools: Read, Grep, Glob
---
```

### Enhanced Skills (with scripts/references)

| Skill | Files | Coverage |
| ------------------- | ----- | ----------------------------------- |
| `app-builder` | 20 | Full-stack scaffolding |

---

## 🛠️ Scripts (2)

Master validation scripts that orchestrate skill-level scripts.

### Master Scripts

| Script | Purpose | When to Use |
| --------------- | --------------------------------------- | ------------------------ |
| `checklist.py` | Priority-based validation (Core checks) | Development, pre-commit |
| `verify_all.py` | Comprehensive verification (All checks) | Pre-deployment, releases |

### Usage

```bash
# Quick validation during development
python .agents/scripts/checklist.py .

# Full verification before deployment
python .agents/scripts/verify_all.py . --url http://localhost:3000
```

### What They Check

**checklist.py** (Core checks):

- Security (vulnerabilities, secrets)
- Code Quality (lint, types)
- Schema Validation
- Test Suite
- UX Audit
- SEO Check

**verify_all.py** (Full suite):

- Everything in checklist.py PLUS:
- Lighthouse (Core Web Vitals)
- Playwright E2E
- Bundle Analysis
- Mobile Audit
- i18n Check

For details, see [scripts/README.md](scripts/README.md)

---

## 📊 Statistics

| Metric | Value |
| ------------------- | --------------------------------- |
| **Total Agents** | 20 (1 major upgrade in 2026.5.13) |
| **Total Skills** | 45 (+7 new in 2026.5.13) |
| **Total Workflows** | 13 (+2 new in 2026.5.13) |
| **Total Scripts** | 2 (master) + 18 (skill-level) |
| **Coverage** | ~95% web/mobile + orchestration |
| **Token Efficiency**| 13-33% better than v2 (2026.5.13) |

---

## 🔗 Quick Reference

| Need | Agent | Skills |
| -------- | --------------------- | ------------------------------------- |
| Web App | `frontend-specialist` | react-best-practices, frontend-design |
| API | `backend-specialist` | api-patterns, nodejs-best-practices |
| Mobile | `mobile-developer` | mobile-design |
| Database | `database-architect` | database-design, prisma-expert |
| Security | `security-auditor` | vulnerability-scanner |
| Testing | `test-engineer` | testing-patterns, webapp-testing |
| Debug | `debugger` | systematic-debugging |
| Plan | `project-planner` | brainstorming, plan-writing |
Loading
Loading