aigroup-workflow 1.3.0 → 2.0.1

package/docs/rules/web/performance.md

@@ -0,0 +1,64 @@
+> This file extends [common/performance.md](../common/performance.md) with web-specific performance content.
+
+# Web Performance Rules
+
+## Core Web Vitals Targets
+
+| Metric | Target |
+|--------|--------|
+| LCP | < 2.5s |
+| INP | < 200ms |
+| CLS | < 0.1 |
+| FCP | < 1.5s |
+| TBT | < 200ms |
+
+## Bundle Budget
+
+| Page Type | JS Budget (gzipped) | CSS Budget |
+|-----------|---------------------|------------|
+| Landing page | < 150kb | < 30kb |
+| App page | < 300kb | < 50kb |
+| Microsite | < 80kb | < 15kb |
+
+## Loading Strategy
+
+1. Inline critical above-the-fold CSS where justified
+2. Preload the hero image and primary font only
+3. Defer non-critical CSS or JS
+4. Dynamically import heavy libraries
+
+```js
+const gsapModule = await import('gsap');
+const { ScrollTrigger } = await import('gsap/ScrollTrigger');
+```
+
+## Image Optimization
+
+- Explicit `width` and `height`
+- `loading="eager"` plus `fetchpriority="high"` for hero media only
+- `loading="lazy"` for below-the-fold assets
+- Prefer AVIF or WebP with fallbacks
+- Never ship source images far beyond rendered size
+
+## Font Loading
+
+- Max two font families unless there is a clear exception
+- `font-display: swap`
+- Subset where possible
+- Preload only the truly critical weight/style
+
+## Animation Performance
+
+- Animate compositor-friendly properties only
+- Use `will-change` narrowly and remove it when done
+- Prefer CSS for simple transitions
+- Use `requestAnimationFrame` or established animation libraries for JS motion
+- Avoid scroll handler churn; use IntersectionObserver or well-behaved libraries
+
+## Performance Checklist
+
+- [ ] All images have explicit dimensions
+- [ ] No accidental render-blocking resources
+- [ ] No layout shifts from dynamic content
+- [ ] Motion stays on compositor-friendly properties
+- [ ] Third-party scripts load async/defer and only when needed

package/docs/rules/web/security.md

@@ -0,0 +1,57 @@
+> This file extends [common/security.md](../common/security.md) with web-specific security content.
+
+# Web Security Rules
+
+## Content Security Policy
+
+Always configure a production CSP.
+
+### Nonce-Based CSP
+
+Use a per-request nonce for scripts instead of `'unsafe-inline'`.
+
+```text
+Content-Security-Policy:
+  default-src 'self';
+  script-src 'self' 'nonce-{RANDOM}' https://cdn.jsdelivr.net;
+  style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
+  img-src 'self' data: https:;
+  font-src 'self' https://fonts.gstatic.com;
+  connect-src 'self' https://*.example.com;
+  frame-src 'none';
+  object-src 'none';
+  base-uri 'self';
+```
+
+Adjust origins to the project. Do not cargo-cult this block unchanged.
+
+## XSS Prevention
+
+- Never inject unsanitized HTML
+- Avoid `innerHTML` / `dangerouslySetInnerHTML` unless sanitized first
+- Escape dynamic template values
+- Sanitize user HTML with a vetted local sanitizer when absolutely necessary
+
+## Third-Party Scripts
+
+- Load asynchronously
+- Use SRI when serving from a CDN
+- Audit quarterly
+- Prefer self-hosting for critical dependencies when practical
+
+## HTTPS and Headers
+
+```text
+Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+```
+
+## Forms
+
+- CSRF protection on state-changing forms
+- Rate limiting on submission endpoints
+- Validate client and server side
+- Prefer honeypots or light anti-abuse controls over heavy-handed CAPTCHA defaults

package/docs/rules/web/testing.md

@@ -0,0 +1,55 @@
+> This file extends [common/testing.md](../common/testing.md) with web-specific testing content.
+
+# Web Testing Rules
+
+## Priority Order
+
+### 1. Visual Regression
+
+- Screenshot key breakpoints: 320, 768, 1024, 1440
+- Test hero sections, scrollytelling sections, and meaningful states
+- Use Playwright screenshots for visual-heavy work
+- If both themes exist, test both
+
+### 2. Accessibility
+
+- Run automated accessibility checks
+- Test keyboard navigation
+- Verify reduced-motion behavior
+- Verify color contrast
+
+### 3. Performance
+
+- Run Lighthouse or equivalent against meaningful pages
+- Keep CWV targets from [performance.md](performance.md)
+
+### 4. Cross-Browser
+
+- Minimum: Chrome, Firefox, Safari
+- Test scrolling, motion, and fallback behavior
+
+### 5. Responsive
+
+- Test 320, 375, 768, 1024, 1440, 1920
+- Verify no overflow
+- Verify touch interactions
+
+## E2E Shape
+
+```ts
+import { test, expect } from '@playwright/test';
+
+test('landing hero loads', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.locator('h1')).toBeVisible();
+});
+```
+
+- Avoid flaky timeout-based assertions
+- Prefer deterministic waits
+
+## Unit Tests
+
+- Test utilities, data transforms, and custom hooks
+- For highly visual components, visual regression often carries more signal than brittle markup assertions
+- Visual regression supplements coverage targets; it does not replace them

package/docs/templates/code-review.md

@@ -4,7 +4,7 @@
 META:
   type: code-review
   date: YYYY-MM-DD
-  author: Kyle
+  author: code-reviewer
   stage: Stage 1 / Stage 2 / 整体审查
 -->
 

package/docs/templates/implementation-plan.md

@@ -1,82 +1,82 @@
-# [功能名] 实现计划
-
-<!--
-META:
-  type: implementation-plan
-  date: YYYY-MM-DD
-  author: Max
-  design: .dev-agents/shared/designs/xxx-design.md
--->
-
-> **执行方式**：推荐使用 subagent-driven-development 技能按任务派遣子代理执行。
-> 步骤使用 checkbox (`- [ ]`) 语法追踪进度。
-
-**目标**：[一句话描述构建什么]
-
-**架构**：[2-3 句话描述方案]
-
-**技术栈**：[关键技术/库]
-
-**设计文档**：[链接到 brainstorming 产出的设计文档]
-
----
-
-## 文件结构
-
-| 操作 | 文件路径 | 职责 |
-|------|---------|------|
-| 新建 | `path/to/new-file` | [说明] |
-| 修改 | `path/to/existing-file` | [说明] |
-| 测试 | `tests/path/to/test-file` | [说明] |
-
----
-
-## 任务 1：[组件/功能名]
-
-**文件：**
-- 新建：`exact/path/to/file`
-- 测试：`tests/exact/path/to/test`
-
-- [ ] **步骤 1：编写失败测试**
-
-```
-[完整测试代码]
-```
-
-- [ ] **步骤 2：运行测试确认失败**
-
-运行：`[精确测试命令]`
-预期：失败，提示 "[预期错误信息]"
-
-- [ ] **步骤 3：编写最小实现**
-
-```
-[完整实现代码]
-```
-
-- [ ] **步骤 4：运行测试确认通过**
-
-运行：`[精确测试命令]`
-预期：通过
-
-- [ ] **步骤 5：提交**
-
-```bash
-git add [文件列表]
-git commit -m "feat: [中文描述]"
-```
-
----
-
-## 任务 2：[组件/功能名]
-
-[同上结构...]
-
----
-
-## 验收标准
-
-- [ ] 所有任务完成
-- [ ] 全量测试通过
-- [ ] Kyle Stage 1 审查通过（规格符合性）
-- [ ] Kyle Stage 2 审查通过（代码质量）
+# [功能名] 实现计划
+
+<!--
+META:
+  type: implementation-plan
+  date: YYYY-MM-DD
+  author: coordinator
+  design: .orchestration/<session>/architect/xxx-design.md
+-->
+
+> **执行方式**：推荐使用 subagent-driven-development 技能按任务派遣子代理执行。
+> 步骤使用 checkbox (`- [ ]`) 语法追踪进度。
+
+**目标**：[一句话描述构建什么]
+
+**架构**：[2-3 句话描述方案]
+
+**技术栈**：[关键技术/库]
+
+**设计文档**：[链接到 brainstorming 产出的设计文档]
+
+---
+
+## 文件结构
+
+| 操作 | 文件路径 | 职责 |
+|------|---------|------|
+| 新建 | `path/to/new-file` | [说明] |
+| 修改 | `path/to/existing-file` | [说明] |
+| 测试 | `tests/path/to/test-file` | [说明] |
+
+---
+
+## 任务 1：[组件/功能名]
+
+**文件：**
+- 新建：`exact/path/to/file`
+- 测试：`tests/exact/path/to/test`
+
+- [ ] **步骤 1：编写失败测试**
+
+```
+[完整测试代码]
+```
+
+- [ ] **步骤 2：运行测试确认失败**
+
+运行：`[精确测试命令]`
+预期：失败，提示 "[预期错误信息]"
+
+- [ ] **步骤 3：编写最小实现**
+
+```
+[完整实现代码]
+```
+
+- [ ] **步骤 4：运行测试确认通过**
+
+运行：`[精确测试命令]`
+预期：通过
+
+- [ ] **步骤 5：提交**
+
+```bash
+git add [文件列表]
+git commit -m "feat: [中文描述]"
+```
+
+---
+
+## 任务 2：[组件/功能名]
+
+[同上结构...]
+
+---
+
+## 验收标准
+
+- [ ] 所有任务完成
+- [ ] 全量测试通过
+- [ ] code-reviewer Stage 1 审查通过（规格符合性）
+- [ ] code-reviewer Stage 2 审查通过（代码质量）

package/docs/workflow-pipeline.md

@@ -1,148 +1,76 @@
-# 强制工作流管道
+# 工作流 Phase 心智模型
 
-## 管道总览
+> 8 个 phase 是**完整路径上限**，不是强制路径——主会话按任务复杂度和风险**裁剪**。
+> 状态真相源：`.orchestration/<session>/<worker>/status.md`。
+
+## 完整路径
 
 ```
 需求收集 → 需求验证 → 方案设计 → 任务拆解 → 实施开发 → 测试验证 → 文档更新 → 分支收尾
-(brainstorming) (validation) (design) (planning) (development) (testing) (documentation) (finishing)
 ```
 
-状态机命令：`bash scripts/harness/workflow-state.sh {init|advance|gate|status|reset|exempt}`
-
-## advance 命令副作用
-
-自 2026-04-23 起，`workflow-state.sh {init|advance|reset|exempt}` 会：
-1. 写入事件到 `.dev-agents/shared/logs/events-YYYY-MM-DD.jsonl`（见 `docs/ARCHITECTURE.md` 六层架构映射）
-2. 在特定阶段切换时输出 `[REMIND]` 文案提示更新记忆文件：
-   - → design：提示更新 `projectContext.md` 记录架构决策
-   - → documentation：提示更新 `systemPatterns.md` 沉淀代码模式
-   - 所有 advance：提示更新 `activeContext.md` 反映当前状态
-
-## 各环节详细规则
-
-### 1. 需求收集 (brainstorming)
-
-| 属性 | 值 |
-|------|-----|
-| 执行者 | Max |
-| 技能路径 | `skills/max/workflow/brainstorming/` |
-| 产出位置 | `.dev-agents/shared/designs/` |
-| 触发条件 | 任何创造性工作之前（功能、组件、行为修改） |
-| 完成标准 | 产出需求文档，包含功能需求、用户场景、约束条件 |
-| 推进门控 | `.dev-agents/shared/designs/` 中有需求文档 |
-
-**聚焦**：收集和分析功能需求。通过协作对话理解用户意图，明确需要做什么、为谁做、成功标准是什么。此阶段**不做**方案设计。
-
-### 2. 需求验证 (validation)
-
-| 属性 | 值 |
-|------|-----|
-| 执行者 | Max |
-| 技能路径 | `skills/max/workflow/requirement-validation/` |
-| 产出位置 | 在需求文档上追加验证结论 |
-| 触发条件 | 需求收集完成后 |
-| 完成标准 | 需求无歧义、完整、可行，用户确认 |
-| 推进门控 | 需求文档存在且通过验证 |
-
-**聚焦**：验证需求的完整性和可行性。逐条审视需求，检查歧义、矛盾、遗漏、技术可行性。
-
-### 3. 方案设计 (design)
-
-| 属性 | 值 |
-|------|-----|
-| 执行者 | Max（UI 相关可派遣 Ella） |
-| 技能路径 | `skills/max/workflow/solution-design/` |
-| 产出位置 | `.dev-agents/shared/designs/` |
-| 触发条件 | 需求验证通过后 |
-| 完成标准 | 产出技术方案文档，包含架构、方案对比、技术选型 |
-| 推进门控 | 设计文档包含方案/架构/技术栈关键词 |
-
-**聚焦**：设计技术方案和架构。提出 2-3 种方案及取舍，选定方案，定义架构、数据流、接口。
-
-### 4. 任务拆解 (planning)
-
-| 属性 | 值 |
-|------|-----|
-| 执行者 | Max |
-| 技能路径 | `skills/max/workflow/writing-plans/` |
-| 产出位置 | `.dev-agents/shared/tasks/` |
-| 触发条件 | 有设计方案后、编码前 |
-| 完成标准 | 产出实现计划，含文件变更列表、TDD 步骤、验收条件 |
-| 推进门控 | `.dev-agents/shared/tasks/` 中有实现计划 |
-
-**聚焦**：将需求拆解为可执行任务。每个任务 2-5 分钟粒度，包含精确文件路径、完整代码、验证命令。
-
-### 5. 实施开发 (development)
-
-| 属性 | 值 |
-|------|-----|
-| 执行者 | Jarvis（子代理） |
-| 技能路径 | `skills/max/workflow/subagent-driven-development/` |
-| 产出 | 代码变更 |
-| 关键规则 | 每任务一个新 Jarvis 子代理，不并行实施 |
-| 状态报告 | DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED |
-| 推进门控 | 无强制检查（由测试验证阶段覆盖） |
-
-**聚焦**：按照任务进行开发。严格遵循 TDD，先写失败测试再写实现。
-
-### 6. 测试验证 (testing)
-
-| 属性 | 值 |
-|------|-----|
-| 执行者 | Kyle（子代理） |
-| 技能路径 | `skills/max/workflow/testing/` |
-| 产出位置 | `.dev-agents/shared/reviews/` |
-| 触发条件 | 开发完成后 |
-| 完成标准 | 测试计划编写、测试用例执行、两阶段审查通过 |
-| 推进门控 | `.dev-agents/shared/reviews/` 中有审查报告 |
+按序推进、不可跳步的假设**已废弃**。实际：
 
-**聚焦**：编写和执行测试用例。包含三个子步骤：
+- 大部分 bugfix 只需要 planning + development + testing
+- 探索性调研不需要任何 phase（直接读文件）
+- 架构性任务才需要完整 8 phase
 
-1. **测试计划**：基于实现计划编写测试用例（功能测试、边界测试、异常测试）
-2. **Stage 1 审查（规格符合性）**：代码是否实现了计划的每条要求
-3. **Stage 2 审查（代码质量）**：代码是否干净、安全、可维护
+## Phase 清单
 
-Stage 1 不通过 → Jarvis 修复 → 重审。Stage 2 不通过 → Jarvis 修复 → 重审。
+| # | Phase | 负责者 | worker 目录（session 下） | 完成标志 |
+|---|-------|--------|---------------------------|---------|
+| 1 | 需求收集 | 主会话 | `architect/requirements.md` | 需求文档包含目标 / 用户场景 / 成功标准 |
+| 2 | 需求验证 | 主会话 | 在 requirements.md 追加验证结论 | 无歧义、无矛盾、用户确认 |
+| 3 | 方案设计 | `architect` | `architect/handoff.md`（ADR 格式） | 至少 2 个候选方案 + 推荐理由 |
+| 4 | 任务拆解 | `planner` | `planner/handoff.md` | 3–7 个阶段，每个含 agent / 验证命令 |
+| 5 | 实施开发 | `tdd-guide`（TDD 路径）/ 主对话直接实现 | `<agent>/handoff.md` 或直接改代码 | 改动文件清单 + 验证证据（typecheck / test） |
+| 6 | 测试验证 | `code-reviewer`（安全敏感 + `security-reviewer`、关键路径 + `e2e-runner`） | `code-reviewer/handoff.md` 含 Stage 1 + Stage 2 | 规格符合性 ✓ 代码质量 ✓ |
+| 7 | 文档更新 | `doc-updater` 或主会话直接改 | 直接改 `docs/`；session `README.md` 留笔记 | docs/ARCHITECTURE / docs/PROJECT_CONTEXT / API 文档已同步 |
+| 8 | 分支收尾 | 主会话 | session `README.md` 总结 | 集成 / PR / 归档 |
 
-### 7. 文档更新 (documentation)
+> **派遣的具体 agent 选择**见 `docs/rules/agents.md`。
+> **按语言栈的实施开发约束**见 `docs/rules/<lang>/`（cpp / golang / java / python / rust / typescript / web 等）。
 
-| 属性 | 值 |
-|------|-----|
-| 执行者 | Max（可派遣 Jarvis 协助） |
-| 技能路径 | `skills/max/workflow/documentation/` |
-| 产出 | 更新后的文档 |
-| 触发条件 | 测试验证通过后 |
-| 完成标准 | 相关文档已更新，无文档与代码不一致 |
-| 推进门控 | 无强制检查（由 Agent 自行判断） |
+## 横切关注点（任何 phase 可触发）
 
-**聚焦**：更新相关文档。包括 API 文档、README、ARCHITECTURE、模块文档、注释等。
+| 关注点 | 触发场景 |
+|--------|---------|
+| 系统化调试 | bug、测试失败、异常行为 |
+| 完成前验证 | 任何"完成 / 通过 / 修复"声明前 |
+| 熵管理 | 代码库漂移、规则模糊、文档与代码不一致 |
 
-### 8. 分支收尾 (finishing)
+## 裁剪示例
 
-| 属性 | 值 |
-|------|-----|
-| 执行者 | Max |
-| 技能路径 | `skills/max/workflow/finishing-a-development-branch/` |
-| 触发条件 | 文档更新完成后 |
-| 产出 | 集成/PR/归档 |
+| 任务类型 | 建议 phases | 入口 |
+|---------|------------|------|
+| 配置项调整 / 笔误修正 | 直接做 | 主对话 |
+| 纯文档 | 7 | 主对话或 `doc-updater` |
+| 纯 bugfix（单文件，已知根因） | 5 → 6 | `/tdd` + `/review` |
+| 有根因待查的 bugfix | 4 → 5 → 6 | `/plan` 然后 `/tdd` |
+| 小功能增补 | 3 → 4 → 5 → 6 | `/workflow-start` |
+| 重构 | 3 → 4 → 5 → 6 | `/workflow-start` |
+| 新模块 / 架构决策 | 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 | `/workflow-start` |
 
-## 横切技能
+## Session 存在条件
 
-| 技能 | 触发时机 | 路径 |
-|------|---------|------|
-| systematic-debugging | Bug、测试失败、异常行为 | `skills/max/workflow/systematic-debugging/` |
-| verification-before-completion | 声称完成/通过/修复之前 | `skills/max/workflow/verification-before-completion/` |
-| entropy-management | 定期维护、漂移检测 | `skills/max/workflow/entropy-management/` |
+建 session 的判断标准：
 
-## 简单任务豁免
+- 涉及 2+ 文件变更
+- 需要架构决策或跨模块协作
+- 有明确验收标准、需追溯证据链
+- ≥2 个 worker 产生 handoff
 
-以下情况可跳过完整管道，Max 直接回答或直接派遣：
+不满足以上条件 → 不建 session。直接走主对话或单 agent 轻量命令（`/plan` / `/review` / `/fix-build` / `/tdd`）。
 
-- 纯知识问答
-- 单行代码修改
-- 配置项调整
-- 文档笔误修复
+主会话识别出复杂任务时，应**建议**启动 session 而非强制。
 
-**判断标准**：如果任务涉及 2 个以上文件或需要设计决策，走完整管道。
+## 与其他文档的关系
 
-豁免时运行：`bash scripts/harness/workflow-state.sh exempt <原因>`
+| 文档 | 关系 |
+|------|------|
+| `docs/rules/agents.md` | 派遣规则（什么时候派谁） |
+| `docs/rules/<lang>/` | 实施开发 phase 的语言专项约束 |
+| `docs/red-flags.md` | 任何 phase 都需监测的危险信号 |
+| `docs/PROJECT_CONTEXT.md` | phase 8 文档更新的产物归属 |
+| `docs/ARCHITECTURE.md` | phase 3 方案设计 / phase 7 文档更新的产物归属 |
+| `.orchestration/README.md` | session/worker 三件套协议 |