takt 0.22.0 → 0.23.0

package/README.md

@@ -128,6 +128,7 @@ Rules determine the next movement. `COMPLETE` ends the piece successfully, `ABOR
 | Piece | Use Case |
 |-------|----------|
 | `default-mini` | Quick fixes. Lightweight plan → implement → parallel review → fix loop. |
+| `default-test-first-mini` | Test-first development. Write tests first, then implement to pass them. |
 | `frontend-mini` | Frontend-focused mini configuration. |
 | `backend-mini` | Backend-focused mini configuration. |
 | `expert-mini` | Expert-level mini configuration. |

package/builtins/en/facets/instructions/implement-after-tests.md

@@ -0,0 +1,52 @@
+Implement according to the plan, making existing tests pass.
+Refer only to files within the Report Directory shown in the Piece Context. Do not search or reference other report directories.
+Use reports in the Report Directory as the primary source of truth. If additional context is needed, you may consult Previous Response and conversation history as secondary sources (Previous Response may be unavailable). If information conflicts, prioritize reports in the Report Directory and actual file contents.
+
+**Important**: Tests have already been written. Implement production code to make existing tests pass.
+- Review existing test files and understand the expected behavior
+- Implement production code to make tests pass
+- Tests are already written so additional tests are generally unnecessary, but may be added if needed
+- If test modifications are needed, document the reasons in the Decisions output contract before modifying
+- Build verification is mandatory. After completing implementation, run the build (type check) and verify there are no type errors
+- Running tests is mandatory. After build succeeds, always run tests and verify all tests pass
+- When introducing new contract strings (file names, config key names, etc.), define them as constants in one place
+
+**Scope output contract (create at the start of implementation):**
+```markdown
+# Change Scope Declaration
+
+## Task
+{One-line task summary}
+
+## Planned changes
+| Type | File |
+|------|------|
+| Create | `src/example.ts` |
+| Modify | `src/routes.ts` |
+
+## Estimated size
+Small / Medium / Large
+
+## Impact area
+- {Affected modules or features}
+```
+
+**Decisions output contract (at implementation completion, only if decisions were made):**
+```markdown
+# Decision Log
+
+## 1. {Decision}
+- **Context**: {Why the decision was needed}
+- **Options considered**: {List of options}
+- **Rationale**: {Reason for the choice}
+```
+
+**Required output (include headings)**
+## Work results
+- {Summary of actions taken}
+## Changes made
+- {Summary of changes}
+## Build results
+- {Build execution results}
+## Test results
+- {Test command executed and results}

package/builtins/en/facets/instructions/write-tests-first.md

@@ -0,0 +1,55 @@
+Write tests based on the plan before implementing production code.
+Refer only to files within the Report Directory shown in the Piece Context. Do not search or reference other report directories.
+
+**Important: Do NOT create or modify production code. Only test files may be created.**
+
+**Actions:**
+1. Review the plan report and understand the planned behavior and interfaces
+2. Examine existing code and tests to learn the project's test patterns
+3. Write unit tests for the planned features
+4. Write E2E tests if appropriate
+5. Run the build (type check) to verify test code has no syntax errors
+
+**Test writing guidelines:**
+- Follow the project's existing test patterns (naming conventions, directory structure, helpers)
+- Write tests in Given-When-Then structure
+- One concept per test. Do not mix multiple concerns in a single test
+- Cover happy path, error cases, boundary values, and edge cases
+- Write tests that are expected to pass after implementation is complete
+
+**Scope output contract (create at the start):**
+```markdown
+# Change Scope Declaration
+
+## Task
+{One-line task summary}
+
+## Planned changes
+| Type | File |
+|------|------|
+| Create | `src/__tests__/example.test.ts` |
+
+## Estimated size
+Small / Medium / Large
+
+## Impact area
+- {Affected modules or features}
+```
+
+**Decisions output contract (at completion, only if decisions were made):**
+```markdown
+# Decision Log
+
+## 1. {Decision}
+- **Context**: {Why the decision was needed}
+- **Options considered**: {List of options}
+- **Rationale**: {Reason for the choice}
+```
+
+**Required output (include headings)**
+## Work results
+- {Summary of actions taken}
+## Changes made
+- {List of test files created}
+## Build results
+- {Build execution results}

package/builtins/en/facets/personas/architecture-reviewer.md

@@ -17,6 +17,7 @@ Code is read far more often than it is written. Poorly structured code destroys
 - No "conditional approval". If there are issues, reject
 - If you find in-scope fixable issues, flag them without exception
 - Existing issues (unrelated to current change) are non-blocking, but issues introduced or fixable in this change must be flagged
+- Do not overlook branches that operate below a function's responsibility level
 
 ## Areas of Expertise
 

package/builtins/en/facets/policies/coding.md

@@ -115,6 +115,36 @@ function processOrder(order) {
 }
 ```
 
+In orchestration functions (Step 1 → Step 2 → Step 3), pay special attention. If an individual step's internals expand with conditional branches, extract that step into a function. The criterion is not the number of branches, but **whether the branch belongs at the function's abstraction level**.
+
+```typescript
+// ❌ Low-level branching exposed in orchestration function
+async function executePipeline(options) {
+  const task = resolveTask(options);      // Step 1: high level ✅
+
+  // Step 2: low-level details exposed ❌
+  let execCwd = cwd;
+  if (options.createWorktree) {
+    const result = await confirmAndCreateWorktree(cwd, task, true);
+    execCwd = result.execCwd;
+    branch = result.branch;
+  } else if (!options.skipGit) {
+    baseBranch = getCurrentBranch(cwd);
+    branch = generateBranchName(config, options.issueNumber);
+    createBranch(cwd, branch);
+  }
+
+  await executeTask({ cwd: execCwd, ... }); // Step 3: high level ✅
+}
+
+// ✅ Extract details, keep abstraction levels consistent
+async function executePipeline(options) {
+  const task = resolveTask(options);
+  const ctx = await resolveExecutionContext(options);
+  await executeTask({ cwd: ctx.execCwd, ... });
+}
+```
+
 ### Follow Language and Framework Conventions
 
 - Write Pythonic Python, idiomatic Kotlin, etc.

package/builtins/en/piece-categories.yaml

@@ -9,6 +9,7 @@ piece_categories:
   ⚡ Mini:
     pieces:
       - default-mini
+      - default-test-first-mini
       - frontend-mini
       - backend-mini
       - backend-cqrs-mini
@@ -41,6 +42,9 @@ piece_categories:
     pieces:
       - unit-test
       - e2e-test
+  ✅ Test First:
+    pieces:
+      - default-test-first-mini
   Others:
     pieces:
       - research

package/builtins/en/pieces/default-test-first-mini.yaml

@@ -0,0 +1,252 @@
+name: default-test-first-mini
+description: Test-first development piece (plan -> write tests -> implement -> parallel review -> fix if needed -> complete)
+piece_config:
+  provider_options:
+    codex:
+      network_access: true
+    opencode:
+      network_access: true
+max_movements: 25
+initial_movement: plan
+movements:
+  - name: plan
+    edit: false
+    persona: planner
+    knowledge: architecture
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+      - Bash
+      - WebSearch
+      - WebFetch
+    rules:
+      - condition: Requirements are clear and implementation is possible
+        next: write_tests
+      - condition: User is asking a question (not an implementation task)
+        next: COMPLETE
+      - condition: Requirements are unclear, insufficient information
+        next: ABORT
+    instruction: plan
+    output_contracts:
+      report:
+        - name: 00-plan.md
+          format: plan
+  - name: write_tests
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge: architecture
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+      - Edit
+      - Write
+      - Bash
+      - WebSearch
+      - WebFetch
+    required_permission_mode: edit
+    instruction: write-tests-first
+    rules:
+      - condition: Tests written successfully
+        next: implement
+      - condition: Cannot proceed with test creation
+        next: ABORT
+      - condition: User input required because there are items to confirm with the user
+        next: write_tests
+        requires_user_input: true
+        interactive_only: true
+    output_contracts:
+      report:
+        - name: 01-test-scope.md
+          format: coder-scope
+        - name: 01-test-decisions.md
+          format: coder-decisions
+  - name: implement
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge: architecture
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+      - Edit
+      - Write
+      - Bash
+      - WebSearch
+      - WebFetch
+    required_permission_mode: edit
+    instruction: implement-after-tests
+    rules:
+      - condition: Implementation complete
+        next: reviewers
+      - condition: Cannot proceed, insufficient info
+        next: ABORT
+      - condition: User input required because there are items to confirm with the user
+        next: implement
+        requires_user_input: true
+        interactive_only: true
+    output_contracts:
+      report:
+        - name: coder-scope.md
+          format: coder-scope
+        - name: coder-decisions.md
+          format: coder-decisions
+  - name: reviewers
+    parallel:
+      - name: ai_review
+        edit: false
+        persona: ai-antipattern-reviewer
+        policy:
+          - review
+          - ai-antipattern
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - WebSearch
+          - WebFetch
+        instruction: review-ai
+        rules:
+          - condition: No AI-specific issues
+          - condition: AI-specific issues found
+        output_contracts:
+          report:
+            - name: 03-ai-review.md
+              format: ai-review
+      - name: supervise
+        edit: false
+        persona: supervisor
+        policy: review
+        knowledge: architecture
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Bash
+          - WebSearch
+          - WebFetch
+        instruction: supervise
+        rules:
+          - condition: All checks passed
+          - condition: Requirements unmet, tests failing
+        output_contracts:
+          report:
+            - name: supervisor-validation.md
+              format: supervisor-validation
+            - name: summary.md
+              format: summary
+              use_judge: false
+    rules:
+      - condition: all("No AI-specific issues", "All checks passed")
+        next: COMPLETE
+      - condition: all("AI-specific issues found", "Requirements unmet, tests failing")
+        next: fix_both
+      - condition: any("AI-specific issues found")
+        next: ai_fix
+      - condition: any("Requirements unmet, tests failing")
+        next: supervise_fix
+  - name: fix_both
+    parallel:
+      - name: ai_fix_parallel
+        edit: true
+        persona: coder
+        policy:
+          - coding
+          - testing
+        knowledge: architecture
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Bash
+          - WebSearch
+          - WebFetch
+        required_permission_mode: edit
+        rules:
+          - condition: AI Reviewer's issues fixed
+          - condition: No fix needed (verified target files/spec)
+          - condition: Cannot proceed, insufficient info
+        instruction: ai-fix
+      - name: supervise_fix_parallel
+        edit: true
+        persona: coder
+        policy:
+          - coding
+          - testing
+        knowledge: architecture
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Bash
+          - WebSearch
+          - WebFetch
+        required_permission_mode: edit
+        rules:
+          - condition: Supervisor's issues fixed
+          - condition: Cannot proceed, insufficient info
+        instruction: fix-supervisor
+    rules:
+      - condition: all("AI Reviewer's issues fixed", "Supervisor's issues fixed")
+        next: reviewers
+      - condition: any("No fix needed (verified target files/spec)", "Cannot proceed, insufficient info")
+        next: implement
+  - name: ai_fix
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge: architecture
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+      - Edit
+      - Write
+      - Bash
+      - WebSearch
+      - WebFetch
+    required_permission_mode: edit
+    pass_previous_response: false
+    rules:
+      - condition: AI Reviewer's issues fixed
+        next: reviewers
+      - condition: No fix needed (verified target files/spec)
+        next: implement
+      - condition: Cannot proceed, insufficient info
+        next: implement
+    instruction: ai-fix
+  - name: supervise_fix
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge: architecture
+    allowed_tools:
+      - Read
+      - Glob
+      - Grep
+      - Edit
+      - Write
+      - Bash
+      - WebSearch
+      - WebFetch
+    required_permission_mode: edit
+    pass_previous_response: false
+    rules:
+      - condition: Supervisor's issues fixed
+        next: reviewers
+      - condition: Cannot proceed, insufficient info
+        next: implement
+    instruction: fix-supervisor

package/builtins/ja/facets/instructions/implement-after-tests.md

@@ -0,0 +1,52 @@
+計画に従って、テストがパスするように実装してください。
+Piece Contextに示されたReport Directory内のファイルのみ参照してください。他のレポートディレクトリは検索/参照しないでください。
+Report Directory内のレポートを一次情報として参照してください。不足情報の補完が必要な場合に限り、Previous Responseや会話履歴を補助的に参照して構いません（Previous Responseは提供されない場合があります）。情報が競合する場合は、Report Directory内のレポートと実際のファイル内容を優先してください。
+
+**重要**: テストは既に作成済みです。既存テストがパスするように実装してください。
+- 既存のテストファイルを確認し、期待される振る舞いを理解する
+- テストがパスするようにプロダクションコードを実装する
+- テストは作成済みのため基本的に追加不要だが、必要なら追加してよい
+- テストの修正が必要な場合は、修正理由をDecisions出力契約に記録した上で修正可
+- ビルド確認は必須。実装完了後、ビルド（型チェック）を実行し、型エラーがないことを確認
+- テスト実行は必須。ビルド成功後、必ずテストを実行して全テストがパスすることを確認
+- ファイル名・設定キー名などの契約文字列を新規導入する場合は、定数として1箇所で定義すること
+
+**Scope出力契約（実装開始時に作成）:**
+```markdown
+# 変更スコープ宣言
+
+## タスク
+{タスクの1行要約}
+
+## 変更予定
+| 種別 | ファイル |
+|------|---------|
+| 作成 | `src/example.ts` |
+| 変更 | `src/routes.ts` |
+
+## 推定規模
+Small / Medium / Large
+
+## 影響範囲
+- {影響するモジュールや機能}
+```
+
+**Decisions出力契約（実装完了時、決定がある場合のみ）:**
+```markdown
+# 決定ログ
+
+## 1. {決定内容}
+- **背景**: {なぜ決定が必要だったか}
+- **検討した選択肢**: {選択肢リスト}
+- **理由**: {選んだ理由}
+```
+
+**必須出力（見出しを含める）**
+## 作業結果
+- {実施内容の要約}
+## 変更内容
+- {変更内容の要約}
+## ビルド結果
+- {ビルド実行結果}
+## テスト結果
+- {テスト実行コマンドと結果}

package/builtins/ja/facets/instructions/write-tests-first.md

@@ -0,0 +1,55 @@
+計画に基づいて、プロダクションコードの実装前にテストを作成してください。
+Piece Contextに示されたReport Directory内のファイルのみ参照してください。他のレポートディレクトリは検索/参照しないでください。
+
+**重要: プロダクションコードは作成・変更しないでください。テストファイルのみ作成可能です。**
+
+**やること:**
+1. 計画レポートを確認し、実装予定の振る舞いとインターフェースを理解する
+2. 対象モジュールの既存コードと既存テストを確認し、テストパターンを把握する
+3. 計画された機能に対する単体テストを作成する
+4. 必要に応じてE2Eテストも作成する
+5. ビルド（型チェック）を実行し、テストコードに構文エラーがないことを確認する
+
+**テスト作成の方針:**
+- プロジェクトの既存テストパターン（命名規約、ディレクトリ構成、ヘルパー）に従う
+- Given-When-Then 構造で記述する
+- 1テスト1概念。複数の関心事を1テストに混ぜない
+- 正常系・異常系・境界値・エッジケースを網羅する
+- テストは実装完了後にパスすることを前提に書く
+
+**Scope出力契約（作成開始時に作成）:**
+```markdown
+# 変更スコープ宣言
+
+## タスク
+{タスクの1行要約}
+
+## 変更予定
+| 種別 | ファイル |
+|------|---------|
+| 作成 | `src/__tests__/example.test.ts` |
+
+## 推定規模
+Small / Medium / Large
+
+## 影響範囲
+- {影響するモジュールや機能}
+```
+
+**Decisions出力契約（完了時、決定がある場合のみ）:**
+```markdown
+# 決定ログ
+
+## 1. {決定内容}
+- **背景**: {なぜ決定が必要だったか}
+- **検討した選択肢**: {選択肢リスト}
+- **理由**: {選んだ理由}
+```
+
+**必須出力（見出しを含める）**
+## 作業結果
+- {実施内容の要約}
+## 変更内容
+- {作成したテストファイル一覧}
+## ビルド結果
+- {ビルド実行結果}

package/builtins/ja/facets/personas/architecture-reviewer.md

@@ -24,3 +24,4 @@
 - 軽微な問題でも後に持ち越さない。今修正できる問題は今修正させる
 - 「条件付き承認」はしない。問題があれば差し戻す
 - 既存コードの踏襲を理由にした問題の放置は認めない
+- 関数の責務より低い粒度の分岐が混入していたら見逃さない

package/builtins/ja/facets/policies/coding.md

@@ -115,6 +115,36 @@ function processOrder(order) {
 }
 ```
 
+オーケストレーション関数（Step 1 → Step 2 → Step 3 と処理を並べる関数）では特に注意する。あるStepの内部に条件分岐が膨らんでいたら、そのStepを関数に抽出する。判定基準は分岐の数ではなく、**その分岐がその関数の抽象レベルに合っているか**。
+
+```typescript
+// ❌ オーケストレーション関数に詳細な分岐が露出
+async function executePipeline(options) {
+  const task = resolveTask(options);      // Step 1: 高レベル ✅
+
+  // Step 2: 低レベル詳細が露出 ❌
+  let execCwd = cwd;
+  if (options.createWorktree) {
+    const result = await confirmAndCreateWorktree(cwd, task, true);
+    execCwd = result.execCwd;
+    branch = result.branch;
+  } else if (!options.skipGit) {
+    baseBranch = getCurrentBranch(cwd);
+    branch = generateBranchName(config, options.issueNumber);
+    createBranch(cwd, branch);
+  }
+
+  await executeTask({ cwd: execCwd, ... }); // Step 3: 高レベル ✅
+}
+
+// ✅ 詳細を関数に抽出し、抽象度を揃える
+async function executePipeline(options) {
+  const task = resolveTask(options);
+  const ctx = await resolveExecutionContext(options);
+  await executeTask({ cwd: ctx.execCwd, ... });
+}
+```
+
 ### 言語・フレームワークの作法に従う
 
 - Pythonなら Pythonic に、KotlinならKotlinらしく

package/builtins/ja/piece-categories.yaml

@@ -9,6 +9,7 @@ piece_categories:
   ⚡ Mini:
     pieces:
       - default-mini
+      - default-test-first-mini
       - frontend-mini
       - backend-mini
       - backend-cqrs-mini
@@ -41,6 +42,9 @@ piece_categories:
     pieces:
       - unit-test
       - e2e-test
+  ✅ テストファースト:
+    pieces:
+      - default-test-first-mini
   その他:
     pieces:
       - research