@wipal/agent-team 1.0.0

package/README.md

@@ -0,0 +1,232 @@
+# @wipal/agent-team
+
+> **Template for creating AI agent teams with specialized roles, skills, and workflows**
+
+---
+
+## Overview
+
+Agent Team Template là hệ thống để:
+- Tạo team với nhiều AI agents chuyên môn
+- Mỗi agent có skills, knowledge base riêng
+- Tự học và cải thiện qua thời gian
+- Setup nhanh cho mỗi dự án
+
+## Quick Start
+
+```bash
+# Via npx (recommended)
+npx @wipal/agent-team init
+npx @wipal/agent-team add payment-fe dev-fe --framework react --styling tailwind
+
+# Or use UI dashboard
+npx @wipal/agent-team ui
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | Initialize .claude/ structure |
+| `add <name> <role>` | Add new agent |
+| `list` | List all agents |
+| `switch <name>` | Show switch instructions |
+| `remove <name>` | Remove agent |
+| `ui` | Start web dashboard |
+
+### Add Command Options
+
+```bash
+npx @wipal/agent-team add <name> <role> [options]
+
+# Frontend options
+--framework <name>      # react, vue, angular, svelte
+--styling <name>        # tailwind, css-modules, styled-components
+--state <name>          # zustand, redux, recoil
+
+# Backend options
+--database <name>       # postgresql, mysql, mongodb
+--orm <name>            # prisma, typeorm, sequelize
+
+# Common options
+--testing <name>        # vitest, jest, cypress
+-i, --interactive       # Interactive mode
+```
+
+### Examples
+
+```bash
+# Frontend agent with React + Tailwind
+npx @wipal/agent-team add payment-fe dev-fe --framework react --styling tailwind
+
+# Backend agent with NestJS + Prisma
+npx @wipal/agent-team add auth-api dev-be --framework nestjs --orm prisma
+
+# Tech Lead (inherits dev-fe + dev-be skills)
+npx @wipal/agent-team add lead tech-lead
+
+# Interactive mode
+npx @wipal/agent-team add
+```
+
+## Web Dashboard
+
+```bash
+npx @wipal/agent-team ui
+
+# Opens at http://localhost:3456
+```
+
+Features:
+- Agent management (CRUD)
+- Role configuration (YAML editor)
+- Skill browser
+- Variant picker
+- Dashboard stats
+
+## Available Roles
+
+| Role | Description | Skills Count |
+|------|-------------|--------------|
+| **dev-fe** | Frontend Developer | 8 |
+| **dev-be** | Backend Developer | 8 |
+| **sa** | Solution Architect | 9 |
+| **tech-lead** | Tech Lead (inherits dev-fe + dev-be) | 17 |
+| **devops** | DevOps Engineer | 8 |
+| **pm** | Product Manager | 8 |
+| **qa** | QA Engineer | 7 |
+
+## Skills Overview
+
+### Total: 37 Skills across 8 categories
+
+| Category | Count | Description |
+|----------|-------|-------------|
+| **Core** | 3 | Universal skills (code-review, git-automation, retrospect) |
+| **Frontend** | 5 | React/Vue/UI development |
+| **Backend** | 5 | API/Database/Security |
+| **Architecture** | 6 | System design, ADRs |
+| **DevOps** | 5 | CI/CD, Docker, Terraform |
+| **Product** | 5 | Requirements, Sprints |
+| **Quality** | 4 | Testing, QA |
+| **Leadership** | 4 | Tech Lead skills |
+
+### Skills Structure
+
+```
+.claude/skills/
+├── SKILL-INDEX.md              # Central hub with dependency graph
+│
+├── core/                       # Universal skills (3)
+│   ├── code-review/
+│   ├── git-automation/
+│   └── retrospect-work/
+│
+├── domain/                     # Domain-specific (31)
+│   ├── frontend/               # 5 skills
+│   ├── backend/                # 5 skills
+│   ├── architecture/           # 6 skills
+│   ├── devops/                 # 5 skills
+│   ├── product/                # 5 skills
+│   └── quality/                # 4 skills
+│
+├── leadership/                 # Tech Lead skills (4)
+│   ├── code-review-advanced/
+│   ├── technical-decision/
+│   ├── mentoring/
+│   └── technical-debt/
+│
+└── community/                  # Community contributions
+```
+
+### Skill Dependency Mechanism
+
+Each skill has a YAML frontmatter with dependencies:
+
+```yaml
+---
+name: skill-name
+version: 1.0.0
+description: What and WHEN to use this skill
+category: domain-name
+tags: [tag1, tag2]
+
+# Dependency mechanism - "Skill dùng Skill"
+depends_on: []           # Hard dependencies (must load)
+recommends: []           # Soft dependencies (suggest in context)
+used_by: []              # Reverse reference (for discovery)
+---
+```
+
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [TUTORIAL.md](TUTORIAL.md) | Step-by-step guide |
+| [Architecture](docs/01-architecture.md) | System design and structure |
+| [Setup Guide](docs/02-setup-guide.md) | How to setup agents |
+| [Skills Guide](docs/03-skills-guide.md) | Managing skills |
+| [Workflows](docs/04-workflows.md) | Workflow orchestration |
+| [Model Strategy](docs/05-model-strategy.md) | Model selection by task |
+| [Extend Guide](docs/06-extend-guide.md) | Creating new agents/skills |
+| [Quick Reference](docs/07-quick-reference.md) | Cheat sheet |
+
+## Key Features
+
+### 1. Base + Variants Architecture
+- Base role provides common skills/MCPs
+- Variants add tech-specific capabilities
+- Agents can combine multiple variants
+
+### 2. Skill Dependency System
+- Skills can depend on other skills
+- Progressive disclosure (metadata → instructions → resources)
+- Central hub for navigation
+
+### 3. Role Inheritance (v2)
+- Tech Lead inherits dev-fe + dev-be skills
+- Configurable via `config/roles.yaml`
+- Per-project override in `.claude/roles.yaml`
+
+### 4. Rules System
+- General rules for all agents
+- Role-specific rules
+- Lessons learned from corrections
+
+### 5. Self-Improvement
+- Capture lessons from corrections
+- Pattern promotion (Lesson → Pattern → Skill → Rule)
+- Cross-session memory
+
+## Configuration
+
+### Per-Project Role Override
+
+Create `.claude/roles.yaml`:
+
+```yaml
+roles:
+  tech-lead:
+    skills:
+      inherit: [dev-fe, dev-be, devops]  # Add devops to tech-lead
+
+  sa:
+    skills:
+      inherit: [dev-fe, dev-be]  # SA also knows code
+      include:
+        - category: architecture
+```
+
+## Research Sources
+
+Skills và architecture được xây dựng dựa trên research từ:
+
+1. **Agent-Skills-for-Context-Engineering** - Context engineering patterns
+2. **AI-Research-SKILLs** - 85 skills, 21 categories structure
+3. **everything-claude-code** - Hooks, commands, instinct system
+4. **BMAD-METHOD** - Agent YAML format, sharded workflows
+5. **spec-kit** - Extension system, multi-agent support
+
+## License
+
+MIT

package/bin/agent-team.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+/**
+ * @wipal/agent-team CLI
+ * Add AI agent teams to existing projects with minimal setup
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { initCommand } from '../src/commands/init.js';
+import { addCommand } from '../src/commands/add.js';
+import { listCommand } from '../src/commands/list.js';
+import { switchCommand } from '../src/commands/switch.js';
+import { removeCommand } from '../src/commands/remove.js';
+import { startServer } from '../src/server/index.js';
+
+const VERSION = '1.0.0';
+
+// Header
+const showHeader = () => {
+  console.log('');
+  console.log(chalk.cyan('╔═══════════════════════════════════════════════════════════════╗'));
+  console.log(chalk.cyan('║') + chalk.bold.white('        🤖 Agent Team CLI v' + VERSION + '                          ') + chalk.cyan('║'));
+  console.log(chalk.cyan('║') + chalk.gray('        Add AI agents to your project with ease               ') + chalk.cyan('║'));
+  console.log(chalk.cyan('╚═══════════════════════════════════════════════════════════════╝'));
+  console.log('');
+};
+
+program
+  .name('agent-team')
+  .description('Add AI agent teams to existing projects')
+  .version(VERSION)
+  .hook('preAction', () => {
+    // Show header for all commands except help
+    if (process.argv.length > 2 && !process.argv.includes('--help') && !process.argv.includes('-h')) {
+      showHeader();
+    }
+  });
+
+// Init command
+program
+  .command('init')
+  .description('Initialize .claude/ structure in current project')
+  .option('-f, --force', 'Overwrite existing files')
+  .action(initCommand);
+
+// Add command
+program
+  .command('add [name] [role]')
+  .description('Add a new agent to the project')
+  .option('--framework <name>', 'UI/Backend framework (react, vue, nestjs, etc.)')
+  .option('--styling <name>', 'CSS solution (tailwind, css-modules, etc.)')
+  .option('--state <name>', 'State management (zustand, redux, etc.)')
+  .option('--data <name>', 'Data fetching (tanstack-query, swr, etc.)')
+  .option('--testing <name>', 'Test framework (vitest, jest, etc.)')
+  .option('--form <name>', 'Form handling (react-hook-form, formik, etc.)')
+  .option('--ui-lib <name>', 'UI component library (shadcn, mui, etc.)')
+  .option('--i18n <name>', 'Internationalization (react-i18next, etc.)')
+  .option('--database <name>', 'Database type (postgresql, mysql, mongodb, etc.)')
+  .option('--orm <name>', 'ORM tool (prisma, typeorm, etc.)')
+  .option('-i, --interactive', 'Run in interactive mode')
+  .action(addCommand);
+
+// List command
+program
+  .command('list')
+  .alias('ls')
+  .description('List all agents in the project')
+  .action(listCommand);
+
+// Switch command
+program
+  .command('switch <name>')
+  .description('Show instructions to switch to an agent')
+  .action(switchCommand);
+
+// Remove command
+program
+  .command('remove <name>')
+  .alias('rm')
+  .description('Remove an agent from the project')
+  .option('-f, --force', 'Skip confirmation')
+  .action(removeCommand);
+
+// UI command - Start web dashboard
+program
+  .command('ui')
+  .description('Start web dashboard for managing agents')
+  .option('-p, --port <number>', 'Port to run server on', '3456')
+  .option('--no-open', 'Don\'t open browser automatically')
+  .action(async (options) => {
+    const port = parseInt(options.port, 10);
+    const openBrowser = options.open !== false;
+
+    console.log(chalk.blue('🎨 Starting Agent Team UI Dashboard...'));
+    console.log('');
+
+    try {
+      await startServer({ port, openBrowser, projectRoot: process.cwd() });
+    } catch (error) {
+      console.error(chalk.red('Failed to start server:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Parse arguments
+program.parse();

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@wipal/agent-team",
+  "version": "1.0.0",
+  "description": "CLI tool to add AI agent teams to existing projects with minimal setup",
+  "type": "module",
+  "bin": {
+    "agent-team": "./bin/agent-team.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    ".claude/skills",
+    ".claude/rules"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "claude",
+    "claude-code",
+    "cli",
+    "team",
+    "productivity"
+  ],
+  "author": "wipal",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "express": "^5.2.1",
+    "fs-extra": "^11.2.0",
+    "glob": "^13.0.6",
+    "inquirer": "^9.2.0",
+    "js-yaml": "^4.1.1",
+    "open": "^11.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wipal/agent-team.git"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,227 @@
+/**
+ * Add command - Add a new agent to the project
+ */
+
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import {
+  getClaudeDir,
+  getAgentDir,
+  isInitialized,
+  agentExists,
+  readTemplate,
+  processTemplate,
+  copySkills
+} from '../utils/file-utils.js';
+import {
+  resolveSkills,
+  getAllSkills,
+  AVAILABLE_ROLES,
+  getVariantsForRole
+} from '../utils/skill-resolver.js';
+import { runInteractiveAdd } from '../interactive/prompts.js';
+
+/**
+ * Add a new agent
+ */
+export async function addCommand(name, role, options) {
+  const projectRoot = process.cwd();
+
+  // Check if initialized
+  if (!(await isInitialized(projectRoot))) {
+    console.log(chalk.red('❌ Project not initialized'));
+    console.log(chalk.gray('   Run `npx @wipal/agent-team init` first'));
+    return;
+  }
+
+  // If no name/role provided, run interactive mode
+  if (!name || !role || options.interactive) {
+    await runInteractiveAdd(projectRoot, { name, role, ...options });
+    return;
+  }
+
+  // Validate role
+  const validRole = AVAILABLE_ROLES.find(r => r.name === role);
+  if (!validRole) {
+    console.log(chalk.red(`❌ Invalid role: ${role}`));
+    console.log(chalk.gray('   Available roles:'));
+    AVAILABLE_ROLES.forEach(r => {
+      console.log(chalk.gray(`     - ${r.name}: ${r.description}`));
+    });
+    return;
+  }
+
+  // Check if agent already exists
+  if (await agentExists(name, projectRoot)) {
+    console.log(chalk.red(`❌ Agent '${name}' already exists`));
+    console.log(chalk.gray('   Use a different name or remove the existing agent first'));
+    return;
+  }
+
+  // Parse variants from options
+  const variants = {};
+  const variantOptions = [
+    'framework', 'metaFramework', 'styling', 'state', 'data',
+    'testing', 'form', 'uiLib', 'i18n', 'database', 'orm',
+    'infra', 'cicd', 'monitoring'
+  ];
+
+  for (const opt of variantOptions) {
+    const key = opt.charAt(0).toLowerCase() + opt.slice(1);
+    // Handle kebab-case to camelCase
+    const optKey = opt.replace(/([A-Z])/g, (m) => m.toLowerCase());
+    if (options[optKey]) {
+      variants[optKey] = options[optKey];
+    }
+  }
+
+  // Create the agent
+  await createAgent(name, role, variants, projectRoot);
+}
+
+/**
+ * Create agent with given configuration
+ */
+export async function createAgent(name, role, variants, projectRoot) {
+  const agentDir = getAgentDir(name, projectRoot);
+  const projectName = path.basename(projectRoot);
+
+  console.log(chalk.blue('🚀 Creating agent...'));
+  console.log(chalk.gray(`   Name: ${name}`));
+  console.log(chalk.gray(`   Role: ${role}`));
+
+  // Show selected variants
+  const variantEntries = Object.entries(variants).filter(([_, v]) => v);
+  if (variantEntries.length > 0) {
+    console.log(chalk.gray(`   Variants: ${variantEntries.map(([k, v]) => `${k}=${v}`).join(', ')}`));
+  }
+  console.log('');
+
+  // Create agent directory
+  await fs.ensureDir(agentDir);
+  await fs.ensureDir(path.join(agentDir, 'skills'));
+
+  // Resolve skills
+  console.log(chalk.blue('   Resolving skills...'));
+  const skills = resolveSkills(role, variants);
+  const allSkills = getAllSkills(role, variants);
+
+  console.log(chalk.gray(`   Core skills: ${skills.core.join(', ')}`));
+  console.log(chalk.gray(`   Role skills: ${skills.role.join(', ')}`));
+  if (skills.variants.length > 0) {
+    console.log(chalk.gray(`   Variant skills: ${skills.variants.join(', ')}`));
+  }
+
+  // Copy skills
+  console.log(chalk.blue('   Copying skills...'));
+  const copiedSkills = await copySkills(allSkills, agentDir);
+  console.log(chalk.green(`   ✓ Copied ${copiedSkills.length} skills`));
+
+  // Create CLAUDE.md
+  console.log(chalk.blue('   Creating CLAUDE.md...'));
+  await createClaudeMd(name, role, variants, skills, projectName, agentDir);
+  console.log(chalk.green('   ✓ Created CLAUDE.md'));
+
+  // Create knowledge.md
+  console.log(chalk.blue('   Creating knowledge.md...'));
+  await createKnowledgeMd(name, role, agentDir);
+  console.log(chalk.green('   ✓ Created knowledge.md'));
+
+  // Create variants.json
+  console.log(chalk.blue('   Creating variants.json...'));
+  await createVariantsJson(name, role, variants, skills, agentDir);
+  console.log(chalk.green('   ✓ Created variants.json'));
+
+  // Summary
+  console.log('');
+  console.log(chalk.green('✅ Agent created successfully!'));
+  console.log('');
+  console.log(chalk.blue('Agent location:'));
+  console.log(chalk.gray(`   ${agentDir}`));
+  console.log('');
+  console.log(chalk.blue('To use this agent in Claude Code:'));
+  console.log(chalk.cyan(`   npx @wipal/agent-team switch ${name}`));
+  console.log('');
+}
+
+/**
+ * Create CLAUDE.md for agent
+ */
+async function createClaudeMd(name, role, variants, skills, projectName, agentDir) {
+  const roleInfo = AVAILABLE_ROLES.find(r => r.name === role);
+
+  // Build role skills list
+  const roleSkillsList = skills.role.map(s => `  - ${s}`).join('\n');
+
+  // Build tech stack from variants
+  const techStack = Object.entries(variants)
+    .filter(([_, v]) => v)
+    .map(([k, v]) => `- ${k}: ${v}`)
+    .join('\n');
+
+  // Build variants list
+  const variantsList = Object.entries(variants)
+    .filter(([_, v]) => v)
+    .map(([k, v]) => `- ${k}: ${v}`)
+    .join('\n');
+
+  // Build skills list
+  const skillsList = allSkills => allSkills.map(s => `- ${s}`).join('\n');
+
+  const template = await readTemplate('CLAUDE.md.tmpl');
+  const content = processTemplate(template, {
+    PROJECT_NAME: projectName,
+    AGENT_NAME: name,
+    ROLE_NAME: role,
+    ROLE_SKILLS: roleSkillsList,
+    TECH_STACK: techStack || '- [Configure your tech stack]',
+    VARIANTS_LIST: variantsList || '- [No variants selected]',
+    SKILLS_LIST: skillsList(getAllSkills(role, variants))
+  });
+
+  await fs.writeFile(path.join(agentDir, 'CLAUDE.md'), content);
+}
+
+/**
+ * Create knowledge.md for agent
+ */
+async function createKnowledgeMd(name, role, agentDir) {
+  const now = new Date().toISOString();
+  const template = await readTemplate('knowledge.md.tmpl');
+  const content = processTemplate(template, {
+    AGENT_NAME: name,
+    ROLE_NAME: role,
+    CREATED_AT: now,
+    DATE: now.split('T')[0]
+  });
+
+  await fs.writeFile(path.join(agentDir, 'knowledge.md'), content);
+}
+
+/**
+ * Create variants.json for agent
+ */
+async function createVariantsJson(name, role, variants, skills, agentDir) {
+  const now = new Date().toISOString();
+
+  const content = {
+    agent_name: name,
+    base_role: role,
+    created_at: now,
+    updated_at: now,
+    installed_variants: variants,
+    skills: {
+      core: skills.core,
+      role: skills.role,
+      variants: skills.variants
+    },
+    skill_status: {
+      last_checked: now,
+      all_available: true,
+      missing_skills: []
+    }
+  };
+
+  await fs.writeJson(path.join(agentDir, 'variants.json'), content, { spaces: 2 });
+}