amazingteam 3.0.0

package/docs/config-reference.md

@@ -0,0 +1,458 @@
+# Configuration Reference
+
+This document describes all configuration options for `amazingteam.config.yaml`.
+
+---
+
+## Configuration File Location
+
+Default: `amazingteam.config.yaml` in project root.
+
+Custom location: Specify via CLI `--config` flag or Action input.
+
+---
+
+## Full Configuration Example
+
+```yaml
+version: "1.0"
+
+preset: "typescript"
+
+project:
+  name: "my-awesome-app"
+  description: "My awesome application"
+  language: "typescript"
+  framework: "react"
+  repository: "https://github.com/org/repo"
+
+build:
+  command: "npm run build"
+  test: "npm test"
+  lint: "npm run lint"
+  typecheck: "npm run typecheck"
+
+rules:
+  test_coverage_threshold: 80
+  max_function_lines: 30
+  max_file_lines: 500
+  commit_convention: "conventional"
+
+agents:
+  planner: true
+  architect: true
+  developer: true
+  qa: true
+  reviewer: true
+  triage: true
+  ci_analyst: true
+
+workflows:
+  feature:
+    sequence:
+      - triage
+      - architect
+      - developer
+      - qa
+      - reviewer
+    auto_merge: false
+  bugfix:
+    sequence:
+      - triage
+      - developer
+      - qa
+    auto_merge: false
+
+memory:
+  retention_days: 90
+  max_entries_per_role: 100
+
+foundation:
+  version: "3.0.0"
+  registry: "https://registry.npmjs.org"
+
+overlay:
+  name: "web-fullstack"
+  content: |
+    ## Custom Rules
+    - Use functional components
+    - Prefer hooks over class components
+```
+
+---
+
+## Configuration Fields
+
+### Top-Level Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `version` | string | No | `"1.0"` | Config file schema version |
+| `preset` | string | No | `"default"` | Preset name (default, typescript, python, go) |
+| `project` | object | **Yes** | - | Project information |
+| `build` | object | No | Preset default | Build commands |
+| `rules` | object | No | Preset default | Coding rules |
+| `agents` | object | No | All enabled | Agent configuration |
+| `workflows` | object | No | Built-in defaults | Custom workflows |
+| `memory` | object | No | Built-in defaults | Memory settings |
+| `foundation` | object | No | Latest | Foundation version settings |
+| `overlay` | object | No | None | Overlay configuration |
+
+---
+
+### project
+
+**Required**. Project information.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | string | **Yes** | - | Project name |
+| `description` | string | No | `""` | Project description |
+| `language` | string | **Yes** | - | Primary language (typescript, python, go, etc.) |
+| `framework` | string | No | `""` | Framework name (react, vue, django, etc.) |
+| `repository` | string | No | Git origin | Repository URL |
+
+**Examples:**
+
+```yaml
+# Minimal
+project:
+  name: "my-api"
+  language: "python"
+
+# Full
+project:
+  name: "my-fullstack-app"
+  description: "Full-stack web application"
+  language: "typescript"
+  framework: "react"
+  repository: "https://github.com/org/my-fullstack-app"
+```
+
+---
+
+### build
+
+Build and test commands.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `command` | string | No | Preset default | Build command |
+| `test` | string | No | Preset default | Test command |
+| `lint` | string | No | Preset default | Lint command |
+| `typecheck` | string | No | Preset default | Type check command |
+
+**Examples:**
+
+```yaml
+# TypeScript project
+build:
+  command: "npm run build"
+  test: "npm test"
+  lint: "npm run lint"
+  typecheck: "npm run typecheck"
+
+# Python project
+build:
+  command: "python -m build"
+  test: "pytest"
+  lint: "ruff check ."
+  typecheck: "mypy ."
+
+# Go project
+build:
+  command: "go build ./..."
+  test: "go test ./..."
+  lint: "golangci-lint run"
+  typecheck: ""  # Go doesn't need separate typecheck
+```
+
+---
+
+### rules
+
+Coding rules and thresholds.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `test_coverage_threshold` | number | No | `80` | Minimum test coverage % |
+| `max_function_lines` | number | No | `30` | Max lines per function |
+| `max_file_lines` | number | No | `500` | Max lines per file |
+| `commit_convention` | string | No | `"conventional"` | Commit message format |
+
+**Examples:**
+
+```yaml
+rules:
+  test_coverage_threshold: 90
+  max_function_lines: 25
+  max_file_lines: 300
+  commit_convention: "conventional"  # or "angular", "gitmoji", "none"
+```
+
+---
+
+### agents
+
+Enable/disable agents.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `planner` | boolean | No | `true` | Enable planner agent |
+| `architect` | boolean | No | `true` | Enable architect agent |
+| `developer` | boolean | No | `true` | Enable developer agent |
+| `qa` | boolean | No | `true` | Enable QA agent |
+| `reviewer` | boolean | No | `true` | Enable reviewer agent |
+| `triage` | boolean | No | `true` | Enable triage agent |
+| `ci_analyst` | boolean | No | `true` | Enable CI analyst agent |
+
+**Examples:**
+
+```yaml
+# All enabled (default)
+agents:
+  planner: true
+  architect: true
+  developer: true
+  qa: true
+  reviewer: true
+  triage: true
+  ci_analyst: true
+
+# Minimal team
+agents:
+  planner: false
+  architect: true
+  developer: true
+  qa: true
+  reviewer: false
+  triage: false
+  ci_analyst: false
+```
+
+---
+
+### workflows
+
+Custom workflow definitions.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `{workflow_name}` | object | No | Workflow definition |
+| `{workflow_name}.sequence` | string[] | **Yes** | Ordered list of roles |
+| `{workflow_name}.auto_merge` | boolean | No | Auto-merge PRs after completion |
+
+**Built-in Workflows:**
+
+| Name | Sequence | Description |
+|------|----------|-------------|
+| `feature` | triage → architect → developer → qa → reviewer | New feature development |
+| `bugfix` | triage → developer → qa | Bug fixes |
+| `tech-task` | triage → architect → developer → qa | Technical tasks |
+
+**Examples:**
+
+```yaml
+workflows:
+  # Override default feature workflow
+  feature:
+    sequence:
+      - triage
+      - architect
+      - developer
+      - developer  # Second pass
+      - qa
+      - reviewer
+    auto_merge: false
+
+  # Custom quick-fix workflow
+  quickfix:
+    sequence:
+      - developer
+      - qa
+    auto_merge: true
+
+  # Documentation workflow
+  docs:
+    sequence:
+      - developer
+    auto_merge: true
+```
+
+---
+
+### memory
+
+Memory system settings.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `retention_days` | number | No | `90` | Days to keep memory entries |
+| `max_entries_per_role` | number | No | `100` | Max entries per role |
+
+**Examples:**
+
+```yaml
+memory:
+  retention_days: 30  # Shorter retention for small projects
+  max_entries_per_role: 50
+```
+
+---
+
+### foundation
+
+Foundation version and source settings.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `version` | string | No | `"latest"` | Foundation version |
+| `registry` | string | No | `"https://registry.npmjs.org"` | NPM registry URL |
+| `github_repo` | string | No | Official repo | GitHub repo for fallback |
+
+**Examples:**
+
+```yaml
+# Use specific version
+foundation:
+  version: "3.1.0"
+
+# Use private registry
+foundation:
+  version: "3.0.0"
+  registry: "https://my-private-registry.com"
+
+# Use GitHub releases
+foundation:
+  version: "3.0.0"
+  github_repo: "my-org/amazingteam"
+```
+
+---
+
+### overlay
+
+Overlay configuration for custom rules and content.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | No | Built-in overlay name |
+| `path` | string | No | Custom overlay path |
+| `content` | string | No | Inline overlay content |
+
+**Built-in Overlays:**
+
+| Name | Description |
+|------|-------------|
+| `web-fullstack` | React/Vue/Node fullstack conventions |
+| `python-backend` | Python/Django/FastAPI conventions |
+| `cpp-qt-desktop` | C++/Qt desktop application conventions |
+
+**Examples:**
+
+```yaml
+# Use built-in overlay
+overlay:
+  name: "web-fullstack"
+
+# Use custom overlay from path
+overlay:
+  path: "./my-custom-overlay"
+
+# Inline overlay content
+overlay:
+  content: |
+    ## Project-Specific Rules
+    - Use functional components only
+    - All API calls must have error handling
+    - Use CSS modules for styling
+```
+
+---
+
+### preset
+
+Quick configuration presets.
+
+| Preset | Language | Framework | Build | Test |
+|--------|----------|-----------|-------|------|
+| `default` | Any | Any | `npm run build` | `npm test` |
+| `typescript` | TypeScript | Any | `npm run build` | `npm test` |
+| `python` | Python | Any | `python -m build` | `pytest` |
+| `go` | Go | Any | `go build ./...` | `go test ./...` |
+
+**Example:**
+
+```yaml
+# Using preset (recommended for quick setup)
+preset: "typescript"
+
+project:
+  name: "my-api"
+
+# Preset provides defaults for build, rules, etc.
+# Override as needed:
+
+build:
+  test: "npm run test:coverage"
+```
+
+---
+
+## Minimal Configuration
+
+The minimum required configuration:
+
+```yaml
+project:
+  name: "my-project"
+  language: "typescript"
+```
+
+All other fields use preset or built-in defaults.
+
+---
+
+## Configuration Merge Order
+
+Configuration is merged in this order (later overrides earlier):
+
+1. Foundation defaults
+2. Preset defaults
+3. User configuration (`amazingteam.config.yaml`)
+4. Local overlay
+
+---
+
+## Validation
+
+Validate your configuration:
+
+```bash
+npx amazingteam validate
+```
+
+This checks:
+- Required fields present
+- Valid values for enums
+- Correct types for all fields
+- Valid workflow sequences
+
+---
+
+## Environment Variables
+
+Override configuration with environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `AI_TEAM_CONFIG` | Path to config file |
+| `AI_TEAM_VERSION` | Override foundation version |
+| `AI_TEAM_REGISTRY` | Override NPM registry |
+| `AI_TEAM_DEBUG` | Enable debug logging |
+
+**Example:**
+
+```bash
+AI_TEAM_CONFIG=./custom-config.yaml npx amazingteam validate
+```

package/docs/how-to-use.md

@@ -0,0 +1,178 @@
+# AI Team Template 使用指南
+
+## 模板仓库 vs 项目仓库
+
+本仓库是 **模板仓库** (Template Repository)，提供可复用的 AI Team 定义。使用时有两种场景：
+
+### 场景 1: 模板仓库自身（演示/测试）
+
+模板仓库可以运行 AI 来：
+- 演示完整工作流
+- 测试新功能
+- 迭代改进模板
+
+**这是可选的**，模板仓库不需要配置 GitHub Secrets 也能作为模板使用。
+
+### 场景 2: 项目仓库（生产使用）
+
+用户复制模板后，在**自己的项目仓库**中运行 AI Team。
+
+**重要**: 项目仓库应该有自己的配置，不依赖模板仓库。
+
+---
+
+## 初始化新项目
+
+### 步骤 1: 使用模板创建仓库
+
+```bash
+# 方式 A: GitHub "Use this template" 按钮
+# 方式 B: 克隆后删除模板配置
+git clone https://github.com/your-org/ai-team-template.git my-project
+cd my-project
+rm -rf .git && git init
+```
+
+### 步骤 2: 运行初始化
+
+```bash
+node cli/ai-team.cjs init --force
+```
+
+这会：
+- 创建 `ai-team.config.yaml` (项目配置)
+- 更新 `AGENTS.md` (项目规则)
+- 创建目录结构
+
+### 步骤 3: 配置 GitHub Secrets
+
+在你的项目仓库 Settings → Secrets 添加：
+
+| Secret | 说明 |
+|--------|------|
+| `ALIBABA_CODING_PLAN_API_KEY` | OpenCode API Key |
+| `GITHUB_TOKEN` | 自动提供，无需配置 |
+
+### 步骤 4: 开始使用
+
+创建 Issue，评论：
+```
+/opencode use architect to analyze this issue
+```
+
+---
+
+## 配置文件说明
+
+### 模板仓库配置 (只读)
+
+| 文件 | 用途 | 用户是否修改 |
+|------|------|-------------|
+| `.ai-team/agents/*.md` | Agent 定义 | ❌ 不建议 |
+| `.ai-team/skills/*/skill.md` | Skill 定义 | ❌ 不建议 |
+| `.ai-team/commands/*.md` | Command 定义 | ❌ 不建议 |
+| `.ai-team/memory/*/` | Memory 模板 | ❌ 不建议 |
+| `.ai-team/opencode.template.jsonc` | 配置模板 | ❌ 不建议 |
+
+### 项目仓库配置 (可自定义)
+
+| 文件 | 用途 | 用户是否修改 |
+|------|------|-------------|
+| `opencode.jsonc` | 运行时配置 | ✅ 应该 |
+| `ai-team.config.yaml` | 项目配置 | ✅ 应该 |
+| `AGENTS.md` | 全局规则 | ✅ 应该 |
+| `docs/` | 项目文档 | ✅ 应该 |
+| `tasks/` | 任务记忆 | ✅ 自动创建 |
+
+---
+
+## opencode.jsonc vs opencode.template.jsonc
+
+### opencode.template.jsonc (模板)
+
+- 定义了完整的 Agent/Skill/Command 配置
+- 包含模板变量 `{{PROJECT_NAME}}` 等
+- **不应该直接使用**
+
+### opencode.jsonc (运行时)
+
+- 从模板生成或手动创建
+- 替换了模板变量
+- **实际运行使用的配置**
+
+### 初始化时的处理
+
+```bash
+# 初始化时会：
+# 1. 读取 opencode.template.jsonc
+# 2. 替换模板变量
+# 3. 生成 opencode.jsonc (如果不存在)
+```
+
+---
+
+## 升级模板
+
+当模板仓库有更新时：
+
+```bash
+# 在你的项目仓库中
+ai-team upgrade
+
+# 或强制升级
+ai-team upgrade --force
+```
+
+**升级只覆盖**:
+- `.ai-team/agents/`
+- `.ai-team/skills/`
+- `.ai-team/commands/`
+- `.github/workflows/` (可选)
+
+**升级不会覆盖**:
+- `opencode.jsonc`
+- `ai-team.config.yaml`
+- `AGENTS.md`
+- `docs/`
+- `tasks/`
+
+---
+
+## 常见问题
+
+### Q: 模板仓库的自举能力会影响我的项目吗？
+
+A: 不会。模板仓库和你的项目仓库是独立的。你需要在**自己的仓库**中配置 Secrets 才能运行 AI。
+
+### Q: 我可以修改 Agent/Skill 定义吗？
+
+A: 可以，但建议通过自定义 Agent 而不是修改模板文件：
+
+```yaml
+# ai-team.config.yaml
+ai_team:
+  custom_agents:
+    - name: my-custom-agent
+      enabled: true
+```
+
+### Q: 模板仓库更新后，我的项目会自动更新吗？
+
+A: 不会。需要手动运行 `ai-team upgrade` 来同步更新。
+
+### Q: 我不想用某些 Agent，可以禁用吗？
+
+A: 可以：
+
+```yaml
+# ai-team.config.yaml
+ai_team:
+  agents:
+    planner: true
+    architect: true
+    developer: true
+    qa: true
+    reviewer: true
+    triage: false      # 禁用
+    ci_analyst: false  # 禁用
+```