@wipal/agent-team 1.0.4 → 1.1.0

package/TUTORIAL.md

@@ -0,0 +1,256 @@
+# Agent Team Tutorial
+
+## What's New in v2.1
+
+Features from **OpenFang** patterns:
+
+- **Tool Profiles**: Each role has predefined tool access (coding, research, orchestration, full)
+- **Capability Security**: Fine-grained permissions for files, shell commands, network
+- **Operational Phases**: Consistent workflow (ANALYZE → PLAN → IMPLEMENT → VERIFY → DOCUMENT)
+- **Orchestrator Pattern**: Tech-lead can delegate to specialist agents
+- **Knowledge Graph**: Track component relationships across agents
+
+## Step-by-Step Guide
+
+### Step 1: Install
+
+```bash
+# Via npx (no installation needed)
+npx @wipal/agent-team init
+
+# Or install globally
+npm install -g @wipal/agent-team
+agent-team init
+```
+
+### Step 2: Initialize Project
+
+```bash
+cd your-existing-project
+
+# Initialize .claude/ structure
+npx @wipal/agent-team init
+```
+
+This creates:
+```
+.claude/
+├── CLAUDE.md              # Project context
+├── agents/                # Agent instances
+├── rules/                 # Rules & lessons
+└── settings.json          # MCP configs
+```
+
+### Step 3: Add Your First Agent
+
+#### Option A: CLI
+
+```bash
+# Frontend agent
+npx @wipal/agent-team add my-fe dev-fe --framework react --styling tailwind
+
+# Backend agent
+npx @wipal/agent-team add my-api dev-be --framework nestjs --orm prisma
+
+# Tech Lead (inherits FE + BE skills)
+npx @wipal/agent-team add lead tech-lead
+```
+
+#### Option B: Interactive Mode
+
+```bash
+npx @wipal/agent-team add
+```
+
+Then follow the prompts:
+1. Enter agent name
+2. Select role
+3. Choose variants
+4. Confirm creation
+
+#### Option C: Web UI
+
+```bash
+npx @wipal/agent-team ui
+# Opens http://localhost:3456
+```
+
+### Step 4: Use Agent in Claude Code
+
+After adding an agent:
+
+```bash
+# See switch instructions
+npx @wipal/agent-team switch my-fe
+```
+
+The agent's `CLAUDE.md` is at:
+```
+.claude/agents/my-fe/CLAUDE.md
+```
+
+Claude Code will automatically read this when you work in the project.
+
+### Step 5: Manage Agents
+
+```bash
+# List all agents
+npx @wipal/agent-team list
+
+# Remove an agent
+npx @wipal/agent-team remove my-fe
+```
+
+## Common Scenarios
+
+### Scenario 1: React + Tailwind Project
+
+```bash
+npx @wipal/agent-team init
+npx @wipal/agent-team add fe dev-fe --framework react --styling tailwind --testing vitest
+```
+
+Agent gets:
+- Core skills: code-review, git-automation, retrospect-work
+- Frontend skills: frontend-design, accessibility, state-management, testing-fe, performance-fe
+- Total: 8 skills
+
+### Scenario 2: Full-Stack Team
+
+```bash
+# Frontend
+npx @wipal/agent-team add fe dev-fe --framework react --styling tailwind
+
+# Backend
+npx @wipal/agent-team add api dev-be --framework nestjs --orm prisma
+
+# Tech Lead (can review both)
+npx @wipal/agent-team add lead tech-lead
+```
+
+Tech Lead gets:
+- Leadership skills: code-review-advanced, technical-decision, mentoring, technical-debt
+- Frontend skills (inherited): frontend-design, accessibility, etc.
+- Backend skills (inherited): api-design, database-design, etc.
+- Total: 17 skills
+
+### Scenario 3: DevOps Team
+
+```bash
+npx @wipal/agent-team add infra devops
+npx @wipal/agent-team add ci devops --cicd github-actions --infra docker
+```
+
+## Customizing Roles
+
+### Per-Project Override
+
+Create `.claude/roles.yaml`:
+
+```yaml
+roles:
+  tech-lead:
+    skills:
+      inherit: [dev-fe, dev-be, devops]  # Add devops skills
+```
+
+### Adding Custom Skills
+
+1. Create skill folder:
+```bash
+mkdir -p .claude/skills/custom/my-skill
+```
+
+2. Create `SKILL.md`:
+```markdown
+---
+name: my-skill
+version: 1.0.0
+description: My custom skill
+category: custom
+tags: [custom]
+depends_on: []
+---
+
+# My Skill
+
+## When to use
+...
+
+## Instructions
+...
+```
+
+3. Reference in agent or role config
+
+## Tips
+
+### 1. Naming Convention
+
+Use descriptive names:
+- `payment-fe` for payment frontend
+- `auth-api` for auth backend
+- `lead` for tech lead
+
+### 2. Knowledge Base
+
+Each agent has `knowledge.md` - use it to:
+- Store project-specific patterns
+- Learn from corrections
+- Share knowledge across sessions
+
+### 3. Retrospect
+
+Run `/retrospect-work` at end of sessions to:
+- Capture lessons learned
+- Update knowledge base
+- Improve over time
+
+### 4. Skills are Minimal
+
+Only skills you need are copied, not all 50. This keeps agents lightweight.
+
+### 5. Tool Profiles (v2.1)
+
+Each role has a predefined tool profile:
+
+| Role | Profile | Tools |
+|------|---------|-------|
+| dev-fe, dev-be, devops, qa | coding | read, write, edit, bash, grep, glob + filesystem, github |
+| pm, ba | research | read, web_search, web_fetch + context7, docs-seeker |
+| tech-lead | orchestration | coding tools + task + context7 |
+| sa | full | all tools + all MCP servers |
+| designer | minimal | read, write, edit |
+
+### 6. Operational Phases (v2.1)
+
+All agents follow consistent workflow:
+
+1. **ANALYZE** - Read context, understand requirements
+2. **PLAN** - Design approach, consider alternatives
+3. **IMPLEMENT** - Write clean code, follow conventions
+4. **VERIFY** - Run tests, validate output
+5. **DOCUMENT** - Update docs, capture lessons
+
+## Troubleshooting
+
+### "Project not initialized"
+
+Run `npx @wipal/agent-team init` first.
+
+### "Agent already exists"
+
+Use a different name or remove existing:
+```bash
+npx @wipal/agent-team remove <name>
+```
+
+### Skills not found
+
+Check if `.claude/skills/` exists. Run `init` if missing.
+
+## Next Steps
+
+- Read [docs/01-architecture.md](docs/01-architecture.md) for architecture details
+- See [docs/03-skills-guide.md](docs/03-skills-guide.md) for skills management
+- Check [docs/07-quick-reference.md](docs/07-quick-reference.md) for cheat sheet

package/bin/agent-team.js

@@ -10,8 +10,9 @@ 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 { projectsCommand } from '../src/commands/projects.js';
+import { setupHooksCommand } from '../src/commands/setup-hooks.js';
 import { startServer } from '../src/server/index.js';
 
 const VERSION = '1.0.0';
@@ -42,6 +43,12 @@ program
   .command('init')
   .description('Initialize .claude/ structure in current project')
   .option('-f, --force', 'Overwrite existing files')
+  .option('-m, --merge', 'Merge with existing .claude/ without destroying content')
+  .option('--update', 'Update only package-provided files (rules, skills)')
+  .option('--update-rules', 'Update rules when merging')
+  .option('--hooks', 'Enable hooks during init')
+  .option('--no-hooks', 'Skip hooks prompt during init')
+  .option('--memory', 'Enable SimpleMem long-term memory system (requires Docker)')
   .action(initCommand);
 
 // Add command
@@ -68,12 +75,6 @@ program
   .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>')
@@ -82,6 +83,24 @@ program
   .option('-f, --force', 'Skip confirmation')
   .action(removeCommand);
 
+// Projects command
+program
+  .command('projects')
+  .description('Manage all registered projects')
+  .option('-l, --list', 'List all projects')
+  .option('--prune', 'Remove invalid project entries')
+  .option('--register', 'Register current project')
+  .action(projectsCommand);
+
+// Setup hooks command
+program
+  .command('setup-hooks')
+  .description('Setup Claude Code hooks (pre-tool-use, post-tool-use, etc.)')
+  .option('--enable <hook>', 'Enable specific hook')
+  .option('--disable <hook>', 'Disable specific hook')
+  .option('--list', 'List available hooks')
+  .action(setupHooksCommand);
+
 // UI command - Start web dashboard
 program
   .command('ui')

package/config/roles.yaml

@@ -1,11 +1,67 @@
 # Role Definitions for Agent Team
 # Each role defines which skills are included
 
+# Tool Profiles - Pattern từ OpenFang
+# Predefined tool sets for different role types
+tool_profiles:
+  minimal:
+    description: Basic file operations only
+    tools:
+      - read
+      - write
+      - edit
+    mcp_servers: []
+
+  coding:
+    description: Full coding capabilities
+    tools:
+      - read
+      - write
+      - edit
+      - bash
+      - grep
+      - glob
+    mcp_servers:
+      - filesystem
+      - github
+
+  research:
+    description: Research and documentation
+    tools:
+      - read
+      - web_search
+      - web_fetch
+    mcp_servers:
+      - context7
+      - docs-seeker
+
+  full:
+    description: All tools and MCP servers
+    tools: all
+    mcp_servers: all
+
+  orchestration:
+    description: Tech lead and coordination
+    tools:
+      - read
+      - write
+      - edit
+      - bash
+      - grep
+      - glob
+      - task
+    mcp_servers:
+      - filesystem
+      - github
+      - context7
+
 roles:
   # Frontend Developer
   dev-fe:
     name: Frontend Developer
     description: React/Vue/Angular development, UI/UX implementation
+    template: templates/roles/dev-fe.md
+    tool_profile: coding
     skills:
       inherit: []
       include:
@@ -17,6 +73,8 @@ roles:
   dev-be:
     name: Backend Developer
     description: API design, database, server-side logic
+    template: templates/roles/dev-be.md
+    tool_profile: coding
     skills:
       inherit: []
       include:
@@ -28,6 +86,8 @@ roles:
   sa:
     name: Solution Architect
     description: System design, architecture decisions, tech selection
+    template: templates/roles/sa.md
+    tool_profile: full
     skills:
       inherit: []
       include:
@@ -43,6 +103,8 @@ roles:
   tech-lead:
     name: Tech Lead
     description: Technical leadership, code review, mentoring
+    template: templates/roles/tech-lead.md
+    tool_profile: orchestration
     skills:
       inherit:
         - dev-fe
@@ -55,6 +117,8 @@ roles:
   devops:
     name: DevOps Engineer
     description: CI/CD, infrastructure, deployment, monitoring
+    template: templates/roles/devops.md
+    tool_profile: coding
     skills:
       inherit: []
       include:
@@ -66,17 +130,38 @@ roles:
   pm:
     name: Product Manager
     description: Requirements, user stories, sprint planning
+    template: templates/roles/pm.md
+    tool_profile: research
     skills:
       inherit: []
       include:
         - category: product
         - category: core
+      optional:
+        - category: architecture
+      exclude: []
+
+  # Business Analyst
+  ba:
+    name: Business Analyst
+    description: Requirements analysis, PRD creation, stakeholder communication
+    template: templates/roles/ba.md
+    tool_profile: research
+    skills:
+      inherit: []
+      include:
+        - category: product
+        - category: core
+      optional:
+        - category: architecture
       exclude: []
 
   # QA Engineer
   qa:
     name: QA Engineer
     description: Testing, quality assurance, automation
+    template: templates/roles/qa.md
+    tool_profile: coding
     skills:
       inherit: []
       include:
@@ -84,6 +169,22 @@ roles:
         - category: core
       exclude: []
 
+  # UI/UX Designer
+  designer:
+    name: UI/UX Designer
+    description: User interface design, component systems, design tokens, HTML/CSS output
+    template: templates/roles/designer.md
+    tool_profile: minimal
+    variants:
+      - web
+      - mobile
+    skills:
+      inherit: []
+      include:
+        - category: design
+        - category: core
+      exclude: []
+
 # Category to skill folder mapping
 # Used when scanning skills
 categories:
@@ -115,6 +216,10 @@ categories:
     description: QA and testing skills
     folder: domain/quality
 
+  design:
+    description: UI/UX design skills
+    folder: domain/design
+
   leadership:
     description: Tech lead and management skills
     folder: leadership
@@ -128,3 +233,5 @@ core_skills:
   - code-review
   - git-automation
   - retrospect-work
+  - agent-creation
+  - sequential-thinking