takt 0.1.4 → 0.1.6

package/resources/global/en/workflows/expert-review.yaml

@@ -9,6 +9,16 @@
 # Fix destination is determined by Coder based on change impact:
 # - fix_security: MINOR→security_review, MAJOR→cqrs_es_review
 # - fix_qa: MINOR→qa_review, SECURITY→security_review, MAJOR→cqrs_es_review
+#
+# Template Variables:
+#   {iteration}      - Workflow-wide turn count (total steps executed across all agents)
+#   {max_iterations} - Maximum iterations allowed for the workflow
+#   {step_iteration} - Per-step iteration count (how many times THIS step has been executed)
+#   {task}           - Original user request
+#   {previous_response} - Output from the previous step
+#   {git_diff}       - Current uncommitted changes (git diff)
+#   {user_inputs}    - Accumulated user inputs during workflow
+#   {report_dir}     - Report directory name (e.g., "20250126-143052-task-summary")
 
 name: expert-review
 description: CQRS+ES, Frontend, Security, QA Expert Review
@@ -44,7 +54,8 @@ steps:
       | Requirements unclear | `[PLANNER:BLOCKED]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: plan (Task Analysis)
       - Report Directory: .takt/reports/{report_dir}/
       - Report File: .takt/reports/{report_dir}/00-plan.md
@@ -68,7 +79,7 @@ steps:
 
       **Report output:** Output to the `Report File` specified above.
       - If file does not exist: Create new file
-      - If file exists: Append with `## Iteration {iteration}` section
+      - If file exists: Append with `## Iteration {step_iteration}` section
 
       **Report format:**
       ```markdown
@@ -129,7 +140,8 @@ steps:
       | Cannot proceed | `[CODER:BLOCKED]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: implement
       - Report Directory: .takt/reports/{report_dir}/
       - Report Files:
@@ -148,7 +160,7 @@ steps:
 
       **Report output:** Output to the `Report Files` specified above.
       - If file does not exist: Create new file
-      - If file exists: Append with `## Iteration {iteration}` section
+      - If file exists: Append with `## Iteration {step_iteration}` section
 
       **Scope report format (create at implementation start):**
       ```markdown
@@ -213,7 +225,8 @@ steps:
       | Design issues found | `[CQRS-ES:REJECT]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: cqrs_es_review (CQRS+ES Expert Review)
       - Report Directory: .takt/reports/{report_dir}/
       - Report File: .takt/reports/{report_dir}/03-cqrs-es-review.md
@@ -242,7 +255,7 @@ steps:
 
       **Report output:** Output to the `Report File` specified above.
       - If file does not exist: Create new file
-      - If file exists: Append with `## Iteration {iteration}` section
+      - If file exists: Append with `## Iteration {step_iteration}` section
 
       **Report format:**
       ```markdown
@@ -302,7 +315,8 @@ steps:
       | Cannot proceed | `[CODER:BLOCKED]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: fix_cqrs_es
 
       ## CQRS+ES Review Feedback (This is the latest instruction - prioritize this)
@@ -358,7 +372,8 @@ steps:
       | Design issues found | `[FRONTEND:REJECT]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: frontend_review (Frontend Expert Review)
       - Report Directory: .takt/reports/{report_dir}/
       - Report File: .takt/reports/{report_dir}/04-frontend-review.md
@@ -387,7 +402,7 @@ steps:
 
       **Report output:** Output to the `Report File` specified above.
       - If file does not exist: Create new file
-      - If file exists: Append with `## Iteration {iteration}` section
+      - If file exists: Append with `## Iteration {step_iteration}` section
 
       **Report format:**
       ```markdown
@@ -447,7 +462,8 @@ steps:
       | Cannot proceed | `[CODER:BLOCKED]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: fix_frontend
 
       ## Frontend Review Feedback (This is the latest instruction - prioritize this)
@@ -503,7 +519,8 @@ steps:
       | Issues found | `[AI_REVIEW:REJECT]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: ai_review (AI-Generated Code Review)
       - Report Directory: .takt/reports/{report_dir}/
       - Report File: .takt/reports/{report_dir}/05-ai-review.md
@@ -525,7 +542,7 @@ steps:
 
       **Report output:** Output to the `Report File` specified above.
       - If file does not exist: Create new file
-      - If file exists: Append with `## Iteration {iteration}` section
+      - If file exists: Append with `## Iteration {step_iteration}` section
 
       **Report format:**
       ```markdown
@@ -588,7 +605,8 @@ steps:
       | Cannot proceed | `[CODER:BLOCKED]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: ai_fix
 
       ## AI Review Feedback (This is the latest instruction - prioritize this)
@@ -613,7 +631,7 @@ steps:
     pass_previous_response: true
     transitions:
       - condition: done
-        next_step: cqrs_es_review
+        next_step: ai_review
       - condition: blocked
         next_step: plan
 
@@ -642,7 +660,8 @@ steps:
       | Vulnerabilities found | `[SECURITY:REJECT]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: security_review (Security Expert Review)
       - Report Directory: .takt/reports/{report_dir}/
       - Report File: .takt/reports/{report_dir}/06-security-review.md
@@ -667,7 +686,7 @@ steps:
 
       **Report output:** Output to the `Report File` specified above.
       - If file does not exist: Create new file
-      - If file exists: Append with `## Iteration {iteration}` section
+      - If file exists: Append with `## Iteration {step_iteration}` section
 
       **Report format:**
       ```markdown
@@ -729,7 +748,8 @@ steps:
       | Cannot proceed | `[CODER:BLOCKED]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: fix_security
 
       ## Security Review Feedback (This is the latest instruction - prioritize this)
@@ -794,7 +814,8 @@ steps:
       | Quality issues found | `[QA:REJECT]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: qa_review (QA Expert Review)
       - Report Directory: .takt/reports/{report_dir}/
       - Report File: .takt/reports/{report_dir}/07-qa-review.md
@@ -820,7 +841,7 @@ steps:
 
       **Report output:** Output to the `Report File` specified above.
       - If file does not exist: Create new file
-      - If file exists: Append with `## Iteration {iteration}` section
+      - If file exists: Append with `## Iteration {step_iteration}` section
 
       **Report format:**
       ```markdown
@@ -882,7 +903,8 @@ steps:
       | Cannot proceed | `[CODER:BLOCKED]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: fix_qa
 
       ## QA Review Feedback (This is the latest instruction - prioritize this)
@@ -951,7 +973,8 @@ steps:
       | Issues found | `[SUPERVISOR:REJECT]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: supervise (Final Review)
       - Report Directory: .takt/reports/{report_dir}/
       - Report Files:
@@ -987,7 +1010,7 @@ steps:
 
       **Report output:** Output to the `Report Files` specified above.
       - If file does not exist: Create new file
-      - If file exists: Append with `## Iteration {iteration}` section
+      - If file exists: Append with `## Iteration {step_iteration}` section
 
       **Validation report format:**
       ```markdown
@@ -1079,7 +1102,8 @@ steps:
       | Cannot proceed | `[CODER:BLOCKED]` |
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: fix_supervisor
 
       ## Supervisor Feedback (This is the latest instruction - prioritize this)

package/resources/global/en/workflows/magi.yaml

@@ -1,6 +1,16 @@
 # MAGI System Workflow
 # A deliberation workflow modeled after Evangelion's MAGI system
 # Three personas (scientist, nurturer, pragmatist) analyze from different perspectives and vote
+#
+# Template Variables:
+#   {iteration}      - Workflow-wide turn count (total steps executed across all agents)
+#   {max_iterations} - Maximum iterations allowed for the workflow
+#   {step_iteration} - Per-step iteration count (how many times THIS step has been executed)
+#   {task}           - Original user request
+#   {previous_response} - Output from the previous step
+#   {git_diff}       - Current uncommitted changes (git diff)
+#   {user_inputs}    - Accumulated user inputs during workflow
+#   {report_dir}     - Report directory name (e.g., "20250126-143052-task-summary")
 
 name: magi
 description: MAGI Deliberation System - Analyze from 3 perspectives and decide by majority

package/resources/global/en/workflows/research.yaml

@@ -5,6 +5,16 @@
 # Flow:
 # plan -> dig -> supervise -> COMPLETE (approved)
 #                          -> plan (rejected: restart from planning)
+#
+# Template Variables:
+#   {iteration}      - Workflow-wide turn count (total steps executed across all agents)
+#   {max_iterations} - Maximum iterations allowed for the workflow
+#   {step_iteration} - Per-step iteration count (how many times THIS step has been executed)
+#   {task}           - Original user request
+#   {previous_response} - Output from the previous step
+#   {git_diff}       - Current uncommitted changes (git diff)
+#   {user_inputs}    - Accumulated user inputs during workflow
+#   {report_dir}     - Report directory name (e.g., "20250126-143052-task-summary")
 
 name: research
 description: Research workflow - autonomously executes research without asking questions
@@ -49,7 +59,8 @@ steps:
       ```
     instruction_template: |
       ## Workflow Status
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: plan
 
       ## Research Request
@@ -111,7 +122,8 @@ steps:
       ```
     instruction_template: |
       ## Workflow Status
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: dig
 
       ## Original Research Request
@@ -188,7 +200,8 @@ steps:
       ```
     instruction_template: |
       ## Workflow Status
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations} (workflow-wide)
+      - Step Iteration: {step_iteration} (times this step has run)
       - Step: supervise (research quality evaluation)
 
       ## Original Research Request

package/resources/global/ja/agents/default/architect.md

@@ -159,7 +159,68 @@ Vertical Slice の判定基準:
 | 隠れた依存 | 子コンポーネントが暗黙的にAPIを呼ぶ等 |
 | 非イディオマティック | 言語・FWの作法を無視した独自実装 |
 
-### 6. 不要な後方互換コードの検出
+### 6. 抽象化レベルの評価
+
+**条件分岐の肥大化検出:**
+
+| パターン | 判定 |
+|---------|------|
+| 同じif-elseパターンが3箇所以上 | ポリモーフィズムで抽象化 → **REJECT** |
+| switch/caseが5分岐以上 | Strategy/Mapパターンを検討 |
+| フラグ引数で挙動を変える | 別関数に分割 → **REJECT** |
+| 型による分岐（instanceof/typeof） | ポリモーフィズムに置換 → **REJECT** |
+| ネストした条件分岐（3段以上） | 早期リターンまたは抽出 → **REJECT** |
+
+**抽象度の不一致検出:**
+
+| パターン | 問題 | 修正案 |
+|---------|------|--------|
+| 高レベル処理の中に低レベル詳細 | 読みにくい | 詳細を関数に抽出 |
+| 1関数内で抽象度が混在 | 認知負荷 | 同じ粒度に揃える |
+| ビジネスロジックにDB操作が混在 | 責務違反 | Repository層に分離 |
+| 設定値と処理ロジックが混在 | 変更困難 | 設定を外部化 |
+
+**良い抽象化の例:**
+
+```typescript
+// ❌ 条件分岐の肥大化
+function process(type: string) {
+  if (type === 'A') { /* 処理A */ }
+  else if (type === 'B') { /* 処理B */ }
+  else if (type === 'C') { /* 処理C */ }
+  // ...続く
+}
+
+// ✅ Mapパターンで抽象化
+const processors: Record<string, () => void> = {
+  A: processA,
+  B: processB,
+  C: processC,
+};
+function process(type: string) {
+  processors[type]?.();
+}
+```
+
+```typescript
+// ❌ 抽象度の混在
+function createUser(data: UserData) {
+  // 高レベル: ビジネスロジック
+  validateUser(data);
+  // 低レベル: DB操作の詳細
+  const conn = await pool.getConnection();
+  await conn.query('INSERT INTO users...');
+  conn.release();
+}
+
+// ✅ 抽象度を揃える
+function createUser(data: UserData) {
+  validateUser(data);
+  await userRepository.save(data);  // 詳細は隠蔽
+}
+```
+
+### 7. 不要な後方互換コードの検出
 
 **AIは「後方互換のために」不要なコードを残しがちである。これを見逃さない。**
 

package/resources/global/ja/agents/default/coder.md

@@ -105,7 +105,45 @@
 | ボーイスカウト | 触った箇所は少し改善して去る |
 | Fail Fast | エラーは早期に検出。握りつぶさない |
 
-**迷ったら**: Simple を選ぶ。抽象化は後からでもできる。
+**迷ったら**: Simple を選ぶ。
+
+## 抽象化の原則
+
+**条件分岐を追加する前に考える:**
+- 同じ条件が他にもあるか → あればパターンで抽象化
+- 今後も分岐が増えそうか → Strategy/Mapパターンを使う
+- 型で分岐しているか → ポリモーフィズムで置換
+
+```typescript
+// ❌ 条件分岐を増やす
+if (type === 'A') { ... }
+else if (type === 'B') { ... }
+else if (type === 'C') { ... }  // また増えた
+
+// ✅ Mapで抽象化
+const handlers = { A: handleA, B: handleB, C: handleC };
+handlers[type]?.();
+```
+
+**抽象度を揃える:**
+- 1つの関数内では同じ粒度の処理を並べる
+- 詳細な処理は別関数に切り出す
+- 「何をするか」と「どうやるか」を混ぜない
+
+```typescript
+// ❌ 抽象度が混在
+function processOrder(order) {
+  validateOrder(order);           // 高レベル
+  const conn = pool.getConnection(); // 低レベル詳細
+  conn.query('INSERT...');        // 低レベル詳細
+}
+
+// ✅ 抽象度を揃える
+function processOrder(order) {
+  validateOrder(order);
+  saveOrder(order);  // 詳細は隠蔽
+}
+```
 
 **言語・フレームワークの作法に従う:**
 - Pythonなら Pythonic に、KotlinならKotlinらしく
@@ -134,6 +172,121 @@
 - 子は状態を直接変更しない（イベントを親に通知）
 - 状態の流れは単方向
 
+## エラーハンドリング
+
+**原則: エラーは一元管理する。各所でtry-catchしない。**
+
+```typescript
+// ❌ 各所でtry-catch
+async function createUser(data) {
+  try {
+    const user = await userService.create(data)
+    return user
+  } catch (e) {
+    console.error(e)
+    throw new Error('ユーザー作成に失敗しました')
+  }
+}
+
+// ✅ 上位層で一元処理
+// Controller/Handler層でまとめてキャッチ
+// または @ControllerAdvice / ErrorBoundary で処理
+async function createUser(data) {
+  return await userService.create(data)  // 例外はそのまま上に投げる
+}
+```
+
+**エラー処理の配置:**
+
+| 層 | 責務 |
+|----|------|
+| ドメイン/サービス層 | ビジネスルール違反時に例外をスロー |
+| Controller/Handler層 | 例外をキャッチしてレスポンスに変換 |
+| グローバルハンドラ | 共通例外（NotFound, 認証エラー等）を処理 |
+
+## 変換処理の配置
+
+**原則: 変換メソッドはDTO側に持たせる。**
+
+```typescript
+// ✅ Request/Response DTOに変換メソッド
+interface CreateUserRequest {
+  name: string
+  email: string
+}
+
+function toUseCaseInput(req: CreateUserRequest): CreateUserInput {
+  return { name: req.name, email: req.email }
+}
+
+// Controller
+const input = toUseCaseInput(request)
+const output = await useCase.execute(input)
+return UserResponse.from(output)
+```
+
+**変換の方向:**
+```
+Request → toInput() → UseCase/Service → Output → Response.from()
+```
+
+## 共通化の判断
+
+**3回ルール:**
+- 1回目: そのまま書く
+- 2回目: まだ共通化しない（様子見）
+- 3回目: 共通化を検討
+
+**共通化すべきもの:**
+- 同じ処理が3箇所以上
+- 同じスタイル/UIパターン
+- 同じバリデーションロジック
+- 同じフォーマット処理
+
+**共通化すべきでないもの:**
+- 似ているが微妙に違うもの（無理に汎用化すると複雑化）
+- 1-2箇所しか使わないもの
+- 「将来使うかも」という予測に基づくもの
+
+```typescript
+// ❌ 過度な汎用化
+function formatValue(value, type, options) {
+  if (type === 'currency') { ... }
+  else if (type === 'date') { ... }
+  else if (type === 'percentage') { ... }
+}
+
+// ✅ 用途別に関数を分ける
+function formatCurrency(amount: number): string { ... }
+function formatDate(date: Date): string { ... }
+function formatPercentage(value: number): string { ... }
+```
+
+## テストの書き方
+
+**原則: テストは「Given-When-Then」で構造化する。**
+
+```typescript
+test('ユーザーが存在しない場合、NotFoundエラーを返す', async () => {
+  // Given: 存在しないユーザーID
+  const nonExistentId = 'non-existent-id'
+
+  // When: ユーザー取得を試みる
+  const result = await getUser(nonExistentId)
+
+  // Then: NotFoundエラーが返る
+  expect(result.error).toBe('NOT_FOUND')
+})
+```
+
+**テストの優先度:**
+
+| 優先度 | 対象 |
+|--------|------|
+| 高 | ビジネスロジック、状態遷移 |
+| 中 | エッジケース、エラーハンドリング |
+| 低 | 単純なCRUD、UIの見た目 |
+
 ## 禁止事項
 
 - **フォールバック値の乱用** - `?? 'unknown'`、`|| 'default'` で問題を隠さない
@@ -142,4 +295,5 @@
 - **any型** - 型安全を破壊しない
 - **オブジェクト/配列の直接変更** - スプレッド演算子で新規作成
 - **console.log** - 本番コードに残さない
-- **機密情報のハードコーディング**
+- **機密情報のハードコーディング**
+- **各所でのtry-catch** - エラーは上位層で一元処理