aigroup-workflow 1.3.0 → 2.0.1

package/docs/rules/dart/testing.md

@@ -0,0 +1,215 @@
+---
+paths:
+  - "**/*.dart"
+  - "**/pubspec.yaml"
+  - "**/analysis_options.yaml"
+---
+# Dart/Flutter Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Dart and Flutter-specific content.
+
+## Test Framework
+
+- **flutter_test** / **dart:test** — built-in test runner
+- **mockito** (with `@GenerateMocks`) or **mocktail** (no codegen) for mocking
+- **bloc_test** for BLoC/Cubit unit tests
+- **fake_async** for controlling time in unit tests
+- **integration_test** for end-to-end device tests
+
+## Test Types
+
+| Type | Tool | Location | When to Write |
+|------|------|----------|---------------|
+| Unit | `dart:test` | `test/unit/` | All domain logic, state managers, repositories |
+| Widget | `flutter_test` | `test/widget/` | All widgets with meaningful behavior |
+| Golden | `flutter_test` | `test/golden/` | Design-critical UI components |
+| Integration | `integration_test` | `integration_test/` | Critical user flows on real device/emulator |
+
+## Unit Tests: State Managers
+
+### BLoC with `bloc_test`
+
+```dart
+group('CartBloc', () {
+  late CartBloc bloc;
+  late MockCartRepository repository;
+
+  setUp(() {
+    repository = MockCartRepository();
+    bloc = CartBloc(repository);
+  });
+
+  tearDown(() => bloc.close());
+
+  blocTest<CartBloc, CartState>(
+    'emits updated items when CartItemAdded',
+    build: () => bloc,
+    act: (b) => b.add(CartItemAdded(testItem)),
+    expect: () => [CartState(items: [testItem])],
+  );
+
+  blocTest<CartBloc, CartState>(
+    'emits empty cart when CartCleared',
+    seed: () => CartState(items: [testItem]),
+    build: () => bloc,
+    act: (b) => b.add(CartCleared()),
+    expect: () => [const CartState()],
+  );
+});
+```
+
+### Riverpod with `ProviderContainer`
+
+```dart
+test('usersProvider loads users from repository', () async {
+  final container = ProviderContainer(
+    overrides: [userRepositoryProvider.overrideWithValue(FakeUserRepository())],
+  );
+  addTearDown(container.dispose);
+
+  final result = await container.read(usersProvider.future);
+  expect(result, isNotEmpty);
+});
+```
+
+## Widget Tests
+
+```dart
+testWidgets('CartPage shows item count badge', (tester) async {
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [
+        cartNotifierProvider.overrideWith(() => FakeCartNotifier([testItem])),
+      ],
+      child: const MaterialApp(home: CartPage()),
+    ),
+  );
+
+  await tester.pump();
+  expect(find.text('1'), findsOneWidget);
+  expect(find.byType(CartItemTile), findsOneWidget);
+});
+
+testWidgets('shows empty state when cart is empty', (tester) async {
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [cartNotifierProvider.overrideWith(() => FakeCartNotifier([]))],
+      child: const MaterialApp(home: CartPage()),
+    ),
+  );
+
+  await tester.pump();
+  expect(find.text('Your cart is empty'), findsOneWidget);
+});
+```
+
+## Fakes Over Mocks
+
+Prefer hand-written fakes for complex dependencies:
+
+```dart
+class FakeUserRepository implements UserRepository {
+  final _users = <String, User>{};
+  Object? fetchError;
+
+  @override
+  Future<User?> getById(String id) async {
+    if (fetchError != null) throw fetchError!;
+    return _users[id];
+  }
+
+  @override
+  Future<List<User>> getAll() async {
+    if (fetchError != null) throw fetchError!;
+    return _users.values.toList();
+  }
+
+  @override
+  Stream<List<User>> watchAll() => Stream.value(_users.values.toList());
+
+  @override
+  Future<void> save(User user) async {
+    _users[user.id] = user;
+  }
+
+  @override
+  Future<void> delete(String id) async {
+    _users.remove(id);
+  }
+
+  void addUser(User user) => _users[user.id] = user;
+}
+```
+
+## Async Testing
+
+```dart
+// Use fake_async for controlling timers and Futures
+test('debounce triggers after 300ms', () {
+  fakeAsync((async) {
+    final debouncer = Debouncer(delay: const Duration(milliseconds: 300));
+    var callCount = 0;
+    debouncer.run(() => callCount++);
+    expect(callCount, 0);
+    async.elapse(const Duration(milliseconds: 200));
+    expect(callCount, 0);
+    async.elapse(const Duration(milliseconds: 200));
+    expect(callCount, 1);
+  });
+});
+```
+
+## Golden Tests
+
+```dart
+testWidgets('UserCard golden test', (tester) async {
+  await tester.pumpWidget(
+    MaterialApp(home: UserCard(user: testUser)),
+  );
+
+  await expectLater(
+    find.byType(UserCard),
+    matchesGoldenFile('goldens/user_card.png'),
+  );
+});
+```
+
+Run `flutter test --update-goldens` when intentional visual changes are made.
+
+## Test Naming
+
+Use descriptive, behavior-focused names:
+
+```dart
+test('returns null when user does not exist', () { ... });
+test('throws NotFoundException when id is empty string', () { ... });
+testWidgets('disables submit button while form is invalid', (tester) async { ... });
+```
+
+## Test Organization
+
+```
+test/
+├── unit/
+│   ├── domain/
+│   │   └── usecases/
+│   └── data/
+│       └── repositories/
+├── widget/
+│   └── presentation/
+│       └── pages/
+└── golden/
+    └── widgets/
+
+integration_test/
+└── flows/
+    ├── login_flow_test.dart
+    └── checkout_flow_test.dart
+```
+
+## Coverage
+
+- Target 80%+ line coverage for business logic (domain + state managers)
+- All state transitions must have tests: loading → success, loading → error, retry
+- Run `flutter test --coverage` and inspect `lcov.info` with a coverage reporter
+- Coverage failures should block CI when below threshold

package/docs/rules/git-workflow.md

@@ -0,0 +1,53 @@
+# Git Workflow
+
+## Git 安全（绝不自动）
+
+- **禁止自动** `git commit` / `push` / `merge`，必须等用户明确授权
+- `git add` / `git status` / `git diff` 可以直接执行（只读或安全）
+- **禁止破坏性操作**：force push、`git reset --hard`、`git checkout --`、删分支等，除非用户明确要求
+- 提交署名只用仓库主人，**不出现** `Co-Authored-By` 行
+
+## Commit Message Format
+
+```
+<type>: <中文描述>
+
+<可选正文>
+```
+
+可用 type：
+
+| type | 用途 |
+|------|------|
+| feat | 新功能 |
+| fix | Bug 修复 |
+| refactor | 重构（不影响功能） |
+| docs | 文档变更 |
+| style | 格式调整（不影响逻辑） |
+| test | 测试相关 |
+| chore | 构建 / 依赖 / 工具调整 |
+| ci | CI/CD 配置 |
+| perf | 性能优化 |
+
+**规则**：
+- type 用英文
+- 描述用中文，72 字符以内
+- 一个 commit 只做一件事，不混合无关变更
+
+## Pull Request Workflow
+
+创建 PR 时：
+
+1. 分析**全部 commit history**（不只是最新 commit）
+2. 用 `git diff <base-branch>...HEAD` 看完整变更
+3. 起草综合性 PR summary
+4. 包含 test plan checklist
+5. 新分支首次推送加 `-u` flag
+
+## 提交前自检（pre-commit checklist）
+
+- [ ] 已运行 `node scripts/hooks/dispatcher.cjs stop`
+- [ ] 无敏感文件（`.env` / `credentials*` / `secrets*`）
+- [ ] 无 `console.log` / `print` 调试残留
+- [ ] 改动符合 Conventional Commits 格式
+- [ ] 仅添加相关文件（`git add <file>`，不用 `git add .`）

package/docs/rules/golang/coding-style.md

@@ -0,0 +1,32 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+# Go Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Go specific content.
+
+## Formatting
+
+- **gofmt** and **goimports** are mandatory — no style debates
+
+## Design Principles
+
+- Accept interfaces, return structs
+- Keep interfaces small (1-3 methods)
+
+## Error Handling
+
+Always wrap errors with context:
+
+```go
+if err != nil {
+    return fmt.Errorf("failed to create user: %w", err)
+}
+```
+
+## Reference
+
+See skill: `golang-patterns` for comprehensive Go idioms and patterns.

package/docs/rules/golang/hooks.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+# Go Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Go specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **gofmt/goimports**: Auto-format `.go` files after edit
+- **go vet**: Run static analysis after editing `.go` files
+- **staticcheck**: Run extended static checks on modified packages

package/docs/rules/golang/patterns.md

@@ -0,0 +1,45 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+# Go Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Go specific content.
+
+## Functional Options
+
+```go
+type Option func(*Server)
+
+func WithPort(port int) Option {
+    return func(s *Server) { s.port = port }
+}
+
+func NewServer(opts ...Option) *Server {
+    s := &Server{port: 8080}
+    for _, opt := range opts {
+        opt(s)
+    }
+    return s
+}
+```
+
+## Small Interfaces
+
+Define interfaces where they are used, not where they are implemented.
+
+## Dependency Injection
+
+Use constructor functions to inject dependencies:
+
+```go
+func NewUserService(repo UserRepository, logger Logger) *UserService {
+    return &UserService{repo: repo, logger: logger}
+}
+```
+
+## Reference
+
+See skill: `golang-patterns` for comprehensive Go patterns including concurrency, error handling, and package organization.

package/docs/rules/golang/security.md

@@ -0,0 +1,34 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+# Go Security
+
+> This file extends [common/security.md](../common/security.md) with Go specific content.
+
+## Secret Management
+
+```go
+apiKey := os.Getenv("OPENAI_API_KEY")
+if apiKey == "" {
+    log.Fatal("OPENAI_API_KEY not configured")
+}
+```
+
+## Security Scanning
+
+- Use **gosec** for static security analysis:
+  ```bash
+  gosec ./...
+  ```
+
+## Context & Timeouts
+
+Always use `context.Context` for timeout control:
+
+```go
+ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+defer cancel()
+```

package/docs/rules/golang/testing.md

@@ -0,0 +1,31 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+# Go Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Go specific content.
+
+## Framework
+
+Use the standard `go test` with **table-driven tests**.
+
+## Race Detection
+
+Always run with the `-race` flag:
+
+```bash
+go test -race ./...
+```
+
+## Coverage
+
+```bash
+go test -cover ./...
+```
+
+## Reference
+
+See skill: `golang-testing` for detailed Go testing patterns and helpers.

package/docs/rules/hooks.md

@@ -0,0 +1,61 @@
+# Hooks
+
+> Claude Code 与 Codex 在 hook 支持上的差异是**最大的运行时不对称**，本文记录两端如何应对。
+
+## 平台支持
+
+| Harness | Hook 支持 | 配置位置 |
+|---------|-----------|---------|
+| Claude Code | ✅ 原生（`PostToolUse` / `Stop` / `SessionStart` / `PreToolUse` 等 8+ 事件） | `.claude/hooks.json` |
+| Codex CLI | ❌ 不支持任何 hook | — |
+
+## Claude Code Hook 事件
+
+| 事件 | 触发时机 | 当前脚本 | exit 行为 |
+|------|---------|---------|----------|
+| `PostToolUse` | Agent 编辑文件后 | `hook-post-edit.sh` | 0 静默 / 2 错误回注 |
+| `Stop` | Agent 准备停止时 | `hook-stop.sh` | 0 允许 / 2 阻止 |
+| `SubagentStop` | 子 agent 完成时 | `hook-subagent-stop.sh` | — |
+
+详细配置见 `.claude/hooks.json`。
+
+## Codex 兜底方案
+
+Codex 无 hook 支持，所有自动化必须**主动调用**：
+
+| Claude 自动事件 | Codex 手动替代 |
+|----------------|----------------|
+| 编辑后传感器检查 | 主动跑 `node scripts/hooks/dispatcher.cjs stop` |
+| Stop 完整性校验 | Agent prompt 内自检；或派 `reviewer` |
+| 工具调用前权限校验 | 用 `sandbox_mode = "read-only"` profile |
+| 会话开始注入上下文 | `persistent_instructions` + 自动加载 `AGENTS.md` |
+
+## Hook 编写约束
+
+### 阻塞型（PreToolUse / Stop）
+- **必须快**（< 200ms）
+- **不做网络调用**
+- **不阻塞**正常工具执行
+- 解析失败时 `exit 0`（不阻塞）
+
+### 异步型（PostToolUse 长任务）
+- 在 `settings.json` 标记 `"async": true`
+- 超时 ≤ 30s
+- 失败仅打印警告，不阻塞流程
+
+### 通用规则
+- 所有 hook 脚本错误日志加 `[HookName]` 前缀写到 stderr
+- 解析错误一律 `exit 0`，不影响主流程
+- 不要直接调用其他 hook（避免循环）
+
+## 用户可绕过吗？
+
+- **Claude Code**：无法绕过 hook（除非禁用整个 hooks.json）
+- **Codex**：完全靠 agent 自觉调用，因此 reviewer / build_fixer 的 prompt 都明确要求"主动跑 run-all.sh"
+
+## 不应该用 hook 做的事
+
+- ❌ 复杂业务逻辑（hook 不适合，应放在 agent 或 skill）
+- ❌ 长时间运算（除非异步）
+- ❌ 用户交互（hook 是无人值守的）
+- ❌ 修改 git 状态（除非用户明确授权）

package/docs/rules/java/coding-style.md

@@ -0,0 +1,114 @@
+---
+paths:
+  - "**/*.java"
+---
+# Java Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Java-specific content.
+
+## Formatting
+
+- **google-java-format** or **Checkstyle** (Google or Sun style) for enforcement
+- One public top-level type per file
+- Consistent indent: 2 or 4 spaces (match project standard)
+- Member order: constants, fields, constructors, public methods, protected, private
+
+## Immutability
+
+- Prefer `record` for value types (Java 16+)
+- Mark fields `final` by default — use mutable state only when required
+- Return defensive copies from public APIs: `List.copyOf()`, `Map.copyOf()`, `Set.copyOf()`
+- Copy-on-write: return new instances rather than mutating existing ones
+
+```java
+// GOOD — immutable value type
+public record OrderSummary(Long id, String customerName, BigDecimal total) {}
+
+// GOOD — final fields, no setters
+public class Order {
+    private final Long id;
+    private final List<LineItem> items;
+
+    public List<LineItem> getItems() {
+        return List.copyOf(items);
+    }
+}
+```
+
+## Naming
+
+Follow standard Java conventions:
+- `PascalCase` for classes, interfaces, records, enums
+- `camelCase` for methods, fields, parameters, local variables
+- `SCREAMING_SNAKE_CASE` for `static final` constants
+- Packages: all lowercase, reverse domain (`com.example.app.service`)
+
+## Modern Java Features
+
+Use modern language features where they improve clarity:
+- **Records** for DTOs and value types (Java 16+)
+- **Sealed classes** for closed type hierarchies (Java 17+)
+- **Pattern matching** with `instanceof` — no explicit cast (Java 16+)
+- **Text blocks** for multi-line strings — SQL, JSON templates (Java 15+)
+- **Switch expressions** with arrow syntax (Java 14+)
+- **Pattern matching in switch** — exhaustive sealed type handling (Java 21+)
+
+```java
+// Pattern matching instanceof
+if (shape instanceof Circle c) {
+    return Math.PI * c.radius() * c.radius();
+}
+
+// Sealed type hierarchy
+public sealed interface PaymentMethod permits CreditCard, BankTransfer, Wallet {}
+
+// Switch expression
+String label = switch (status) {
+    case ACTIVE -> "Active";
+    case SUSPENDED -> "Suspended";
+    case CLOSED -> "Closed";
+};
+```
+
+## Optional Usage
+
+- Return `Optional<T>` from finder methods that may have no result
+- Use `map()`, `flatMap()`, `orElseThrow()` — never call `get()` without `isPresent()`
+- Never use `Optional` as a field type or method parameter
+
+```java
+// GOOD
+return repository.findById(id)
+    .map(ResponseDto::from)
+    .orElseThrow(() -> new OrderNotFoundException(id));
+
+// BAD — Optional as parameter
+public void process(Optional<String> name) {}
+```
+
+## Error Handling
+
+- Prefer unchecked exceptions for domain errors
+- Create domain-specific exceptions extending `RuntimeException`
+- Avoid broad `catch (Exception e)` unless at top-level handlers
+- Include context in exception messages
+
+```java
+public class OrderNotFoundException extends RuntimeException {
+    public OrderNotFoundException(Long id) {
+        super("Order not found: id=" + id);
+    }
+}
+```
+
+## Streams
+
+- Use streams for transformations; keep pipelines short (3-4 operations max)
+- Prefer method references when readable: `.map(Order::getTotal)`
+- Avoid side effects in stream operations
+- For complex logic, prefer a loop over a convoluted stream pipeline
+
+## References
+
+See skill: `java-coding-standards` for full coding standards with examples.
+See skill: `jpa-patterns` for JPA/Hibernate entity design patterns.

package/docs/rules/java/hooks.md

@@ -0,0 +1,18 @@
+---
+paths:
+  - "**/*.java"
+  - "**/pom.xml"
+  - "**/build.gradle"
+  - "**/build.gradle.kts"
+---
+# Java Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Java-specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **google-java-format**: Auto-format `.java` files after edit
+- **checkstyle**: Run style checks after editing Java files
+- **./mvnw compile** or **./gradlew compileJava**: Verify compilation after changes