takt-task（节拍任务）

TAKT Task Creator

TAKTのtasks.yamlエントリとタスクディレクトリ（order.md）を作成・編集する。

前提 takt バージョン: v0.30.0

参照資料

taktのタスク管理に関する資料は references/takt/ にある。必要に応じて以下を参照する。

重要: TaskRecordのステータス遷移ルールは厳密にバリデーションされる。references/task-schema.md を読んで不変条件を把握する。

ワークフロー

Step 1: 要件ヒアリング

以下を確認する（不明な点はユーザーに質問）:

1. タスク内容: 何を実行するタスクか
2. ピース: 使用するpiece名（default, dual, カスタム等）
3. 隔離実行: worktreeの要否（true / パス / 省略）
4. ブランチ: カスタムブランチ名（省略時は自動生成）
5. PR自動作成: auto_pr / draft_pr の要否
6. Issue連携: GitHub Issue番号（該当する場合）

Step 2: 並列実行戦略の設計

複数タスクを作成する場合、並列実行の可否と分割戦略を設計する。単一タスクの場合はこのステップをスキップする。

a) TAKTの並列実行モデル

TAKTは takt run 時にワーカープールで複数タスクを並列実行できる。ただし、タスク間の依存関係メカニズム（depends_on 等）はない。

原則: 並列実行するタスクには必ず worktree: true を設定する。 隔離なしの並列は作業ディレクトリの破壊につながる。

b) 直列区間の特定（Amdahl's Law 的観点）

タスク群の中に「先に完了しないと後続が作業できない」直列区間があるかを判別する。

ヒアリング質問: 「タスク間で、あるタスクの成果物が別タスクの入力になる依存関係はありますか？」

c) 共有リソース競合の分析（USL: 競合コスト α）

同じリソースを複数タスクが変更すると、マージコンフリクトが発生する。

原則: 「同じファイルを2つのタスクが変更する可能性があるなら統合する」

d) 整合性コストの分析（USL: 整合性コスト β）

タスク間で共有型やインターフェースの一貫性を保つコスト。TAKTではタスク間のライブ同期がないため、クローン時点のスナップショットで各タスクが作業する。

e) タスク分割・統合の判断表

f) 推奨 concurrency 値ガイド

注意: concurrency は takt run のグローバル設定であり、タスク単位では指定できない。段階実行が必要な場合は takt run を複数回に分ける。

g) 並列パターン集

Pattern A: 完全並列（独立モジュール）

tasks:
  - name: impl-module-a
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-100000-aaaaaa
    worktree: true
    branch: feat/module-a
    auto_pr: true
    created_at: "2026-03-01T10:00:00.000Z"
    started_at: null
    completed_at: null
  - name: impl-module-b
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-100000-bbbbbb
    worktree: true
    branch: feat/module-b
    auto_pr: true
    created_at: "2026-03-01T10:00:00.000Z"
    started_at: null
    completed_at: null
  - name: impl-module-c
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-100000-cccccc
    worktree: true
    branch: feat/module-c
    auto_pr: true
    created_at: "2026-03-01T10:00:00.000Z"
    started_at: null
    completed_at: null

takt run --concurrency 3 で並列実行。

Pattern B: 依存統合（スキーマ + 実装を1タスクに）

tasks:
  - name: add-user-profile
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-100000-dddddd
    worktree: true
    branch: feat/user-profile
    auto_pr: true
    created_at: "2026-03-01T10:00:00.000Z"
    started_at: null
    completed_at: null

order.md 内にスキーマ変更と実装の両方を記述し、1タスクとして実行。

Pattern C: 段階実行（先行タスク → マージ → 後続並列）

第1段階: 共通基盤

tasks:
  - name: define-shared-types
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-100000-eeeeee
    worktree: true
    branch: feat/shared-types
    auto_pr: true
    created_at: "2026-03-01T10:00:00.000Z"
    started_at: null
    completed_at: null

takt run で実行 → PR マージ後、第2段階のタスクを追加:

tasks:
  - name: impl-consumer-x
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-110000-ffffff
    worktree: true
    branch: feat/consumer-x
    auto_pr: true
    created_at: "2026-03-01T11:00:00.000Z"
    started_at: null
    completed_at: null
  - name: impl-consumer-y
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-110000-gggggg
    worktree: true
    branch: feat/consumer-y
    auto_pr: true
    created_at: "2026-03-01T11:00:00.000Z"
    started_at: null
    completed_at: null

takt run --concurrency 2 で並列実行。

Step 3: タスクディレクトリの作成

推奨形式: task_dir（order.md分離型）

slug生成

{YYYYMMDD}-{HHmmss}-{random6} 形式で生成する。

例: 20260223-143000-ab12cd

ディレクトリ構造

.takt/tasks/{slug}/
├── order.md          # タスク仕様（必須）
├── schema.sql        # 参考資料（任意）
└── wireframe.png     # 参考資料（任意）

order.md テンプレート

# タスク仕様

## 目的

{1-2文でタスクの目的を記述}

## 要件

- [ ] {要件1}
- [ ] {要件2}
- [ ] {要件3}

## 受け入れ基準

- {基準1}
- {基準2}

## 参考情報

{該当する場合に記述。API仕様、設計ドキュメント等}

注意: order.md内でテンプレート変数（{task}等）は不要。エンジンが自動注入する。

Step 4: tasks.yamlエントリの生成

.takt/tasks.yaml に新しいタスクレコードを追加する。ファイルが存在しない場合は以下で初期化する:

tasks: []

最小構成（task_dir形式）

tasks:
  - name: add-auth-feature
    status: pending
    piece: default
    task_dir: .takt/tasks/20260223-143000-ab12cd
    created_at: "2026-02-23T14:30:00.000Z"
    started_at: null
    completed_at: null

フル構成

tasks:
  - name: add-auth-feature
    status: pending
    piece: default
    task_dir: .takt/tasks/20260223-143000-ab12cd
    slug: 20260223-143000-ab12cd
    worktree: true
    branch: feat/auth-feature
    auto_pr: true
    draft_pr: false
    issue: 28
    created_at: "2026-02-23T14:30:00.000Z"
    started_at: null
    completed_at: null

content形式（レガシー、非推奨）

tasks:
  - name: fix-login-bug
    status: pending
    piece: default
    content: >-
      ログイン画面で認証エラーが発生する問題を修正する。
      原因: セッショントークンの有効期限チェックが不正。
    created_at: "2026-02-23T14:30:00.000Z"
    started_at: null
    completed_at: null

コンテンツソースの排他制約

content, content_file, task_dir のいずれか正確に1つが必須。複数指定はバリデーションエラー。

Step 5: 検証

作成したタスクの整合性を確認する（詳細は references/task-schema.md を参照）:

• task_dir が .takt/tasks/<slug> 形式か
• task_dir 指定時に order.md が実在するか
• status: pending で started_at: null, completed_at: null か
• created_at がISO8601形式か
• content, content_file, task_dir のいずれか1つのみ指定されているか
• piece 名が既存のピース（ビルトインまたはカスタム）と一致するか
• 既存タスクの tasks.yaml 全体構造が壊れていないか

並列整合性チェック（複数タスク作成時）

• 同一ファイルを変更するタスクが分離されていないか（統合すべき）
• 共有型の定義タスクが消費タスクより先に実行される構成か（段階実行）
• 並列実行タスク全てに worktree: true が設定されているか
• 推奨 concurrency 値をユーザーに伝えたか

order.md 構造バリデーション

validate-order-md.sh を実行して order.md の構造を機械的に検証できる:

bash .agents/skills/takt-task/scripts/validate-order-md.sh

検証項目:

• slug フォーマット（YYYYMMDD-HHmmss-xxxxxx）
• ## 目的 セクションの存在と内容
• ## 要件 セクションの - [] チェックボックスアイテム（1件以上）
• ## 受け入れ基準 セクションの項目（1件以上）
• tasks.yaml の task_dir → order.md 存在クロスチェック

ピース変更時の追加ゲート（必須）

このタスクで .takt/pieces/*.yaml を編集した場合は、完了判定前に以下を必ず実行する。

bash .agents/skills/takt-piece/scripts/validate-takt-files.sh --pieces

追加で、次の2点を確認する:

• loop monitor の健全時 next が cycle 先頭ノードと一致
• loop monitor の {report:...} 参照が cycle 内 movement 生成物に限定されている

上記のどちらかが満たせない場合、そのタスクは completed にしない。

ステータス遷移チェック（既存タスク編集時）