ticks

Ticks ワークフロー

Ticks は AI エージェント向けに設計された課題トラッカーです。tk CLI でタスクを管理し、tk board で監視用の Web ベースのボードを利用できます。エピックは、現在のハーネスが references/agent-runner.md に記載された共有プロトコルと、Claude、Codex、Pi、Prime Agent のアダプターを使用して実行します。

Ticks と TodoWrite の使い分け

次のような作業には Ticks（tk）を使用します。

• 複数のセッションや会話にまたがる作業
• 他のタスクに依存する作業
• 別の作業中に見つかり、追跡が必要な作業
• 人への引き継ぎや承認ゲートが必要な作業
• 永続的な履歴やメモが役立つ作業

次のような作業には TodoWrite を使用します。

• 単純で、1 回のセッションで完了するタスク
• 現在の会話中に完了する作業
• 直近の作業の進捗管理

些細なことまで何でも Ticks に登録しすぎないでください。状況に応じて判断してください。

スキルのワークフロー

呼び出されたら、次のワークフローに従います。

ステップ 0：前提条件を確認する

1. Git リポジトリ：

git status 2>/dev/null || git init

2. Ticks が初期化済み：

ls .tick/ 2>/dev/null || tk init

3. tk がインストール済み：

which tk || echo "Install: curl -fsSL https://ticks.sh/install | sh"

現在の tk では、tk skills install ticks を実行してこのスキルを直接インストールまたは更新することもできますが、このコマンドを実行しなくてもスキルは問題なく動作します。

4. Git の追跡（重要）：

.tick/ ディレクトリは Git の追跡対象とし、gitignore の対象にしないでください。Ticks はバージョン管理され、通常の Git ワークフローを通じてマシンやチームメンバー間で同期されるように設計されています。

プロジェクトの .gitignore に .tick または .tick/ が記載されている場合は、削除してください。gitignore の対象にすべきなのは内部ファイルやローカルファイルのみで、これは .tick/.gitignore（.index.json と logs/ を無視します）で処理されます。

# Check if .tick is gitignored (should return nothing)
git check-ignore .tick/

# If it returns ".tick/", remove the entry from .gitignore

5. プロジェクトごとのランナー設定（.tick/config.md）：

プロジェクトでは、追跡対象の .tick/ ディレクトリに .tick/config.md ファイルを配置し、ディスパッチされた実装担当者に信頼できるプロジェクト固有のガイダンスを提供できます。認識される運用セクションには、次のものがあります。

• テスト — パッケージごとの個別実行コマンドを含む、正確なテストコマンドです。毎回新しいエージェントがテストの実行方法を再調査したり、誤って推測したりするという、最もよくある繰り返しの失敗を防ぎます。
• クローズアウト証拠コマンド — クローズアウト時にのみ実行できる、厳格なコントローラー所有のコマンドです。実装の子プロセス、ティックごとの検証、ウェーブ後のゲート、最終レビューのテストでは実行できません。
• 受け入れ証拠 — 任意のコントローラー所有のクローズアウト承認です。安定した受け入れ項目をそれぞれ一度だけ、- A<n>: \exact command`` の形式で対応付けます。このコマンドは、「テスト」または「クローズアウト証拠コマンド」に逐語的に記載され、かつ一意でなければなりません。トラッカーやモデルの説明文はシェル実行を許可しません。また、証拠が重複、不明瞭、不明、挿入されたもの、欠落、または項目間で共有されている場合は、安全側に倒して処理を拒否します。
• 環境 — オーケストレーターがウェーブ 1 の起動前に一度実行する事前チェックです。CLI ツールの有無、サービスの稼働状況、環境変数の設定などを確認します。エージェントに人間へ質問するよう指示するのではなく、条件を検証するコマンドとして記述してください。質問せず、テストしてください。
• ルール — 実装担当者向けのプロジェクト固有の制約です（命名規則、禁止パターン、必須のレビュー手順など）。

使用時点で最新の内容を読む — .tick/learnings.md と同じルールです。オーケストレーターは実行開始時に読み、実装担当者は自身のワークツリーから読みます。どちらも、以前のセッションの古いコピーをインライン化して使いません。

ファイルがない場合のフォールバック： 現在の動作では、実装担当者がテストコマンドを自ら見つけます。このファイルは純粋に追加のものです。

AGENTS.md や CLAUDE.md ではない理由： これらのファイルは、それぞれのハーネスで動作する対話型エージェント向けのガイドです。.tick/config.md はディスパッチされた実装担当者向けのランナー中立な契約であり、プログラムによって読み込まれます。プロジェクトでこれらのファイルを相互参照してもかまいませんが、ランナー設定は特定ベンダーの指示ファイルに依存してはなりません。

6. Pi 実行可能拡張機能（Pi でエピックを実行する場合）：

Pi に /ticks-plan、/ticks-run、/ticks-status、/ticks-dashboard が登録されているか確認してください（RPC クライアントでは get_commands を確認できます）。登録されていない場合は、このスキルは手順を提供しますが拡張機能のコードは有効化できないことを説明し、次のパッケージを推奨してください。

pi install git:github.com/pengelbrecht/ticks
# Local checkout:
pi install /absolute/path/to/ticks

このスキルを読み込んだり実行したりすることで、これらのコマンドが有効になると主張しないでください。汎用スキルインストーラーでは、skills/ticks/ のみがインストールされた可能性があります。ユーザーはパッケージをインストールするか、references/pi-runner.md に記載された手動の Pi アダプターフローを選択できます。

ステップ 1：すでに分かっていることを集める

Ticks を作成する前に、すでに存在する要件を集めます。

• 既存のドキュメント — 仕様書、PRD、設計ドキュメント、README のセクション、または課題の説明（リポジトリのルートと docs/ を確認します。ただし、リポジトリで採用されている規約に従ってください）
• 会話 — ユーザーがすでに伝えたこと

見つかった内容を読みます。すでに回答されていることを再度尋ねないでください。

ステップ 2：不明点を解消する

作業を十分に理解し、分解できるか判断します。次の質問に答えられる必要があります。

• これはどのような問題を解決し、誰のためのものですか？
• 対象範囲に含まれるものと、あると望ましいものは何ですか？
• 技術的な制約や希望はありますか？
• 何をもって「完了」としますか？

不明点があれば、会話を通じて解消します。まずユーザーにアイデアの全体像を遮らずに説明してもらい、その後、不明な点について的を絞った質問をします（手早く選択肢から決めるには、AskUserQuestion が便利です）。

作業の規模に応じて、理解した内容を記録します。

• 小規模で明確なタスク — 会話の中で簡潔に範囲を言い直せば十分です。確認して先に進みます
• 大規模な機能またはエピック — 内容を書き留めます（例：SPEC.md を作成する、または既存のドキュメントを更新する）。これにより、tick を参照できる安定した資料ができます。ドキュメントがすでにある場合は、新たに作り直すのではなく、不足分を補います
• 複数のエピックにまたがるプロジェクト — ゴール設計プロトコル（references/goal-design.md）を実行します。言い換え、ヒアリング、ファクトシート、書き戻しを行い、エピックを計画する前に、検証可能なプロジェクトのゴールを作成します

上記の質問に答えられるようになったら、tick の作成に進みます。

適切なタスクの作成

すべてのタスクは、テストを伴う、コミット可能な独立した作業単位にしてください。

理想的なタスクは次のとおりです。

• 明確で、単一の成果物がある
• テストを実行して検証できる
• 前の作業を基盤として、デモ可能なソフトウェアを生み出す
• エージェントの 1～3 回の反復で完了できる

良いタスク：

tk create "Add email validation to registration" \
  -d "Validate email format on blur, show error below input.

Test cases:
- [email protected] -> valid
- invalid@ -> invalid
- @nodomain.com -> invalid

Run: go test ./internal/validation/..." \
  --acceptance "All validation tests pass" \
  --parent <epic-id>

悪いタスク：

tk create "Add email validation" -d "Make sure emails are valid"
# No test cases, no verification criteria - agent will guess

tick を作成する前に、各 tick に対して references/tick-patterns.md の Definition of Ready チェックリストを実行してください。パターンの全容については、そのファイルを参照してください。

ステップ 3：要件から tick を作成する

最上位のティアで計画を実行します。 分解は、エピックにおける最も重要な判断です。実装に低コストのモデルや低い推論強度を使う場合でも、常に最上位のティアで統合します。ハーネスが対応している場合は、読み取り専用の調査を並列で行います。references/agent-runner.md の「Planning tier」と、使用中のハーネスアダプターを参照してください。

パッケージ拡張機能をインストールした Pi では、安全な自動計画を優先します。

/ticks-plan <existing-childless-epic-id>                  # model-running dry-run
/ticks-plan --requirements "new epic requirements"        # model-running dry-run
/ticks-plan <target> --apply                              # explicit tracker apply

計画のドライランは何もしない操作ではありません。設定済みの読み取り専用スカウトと最上位のプランナーを実行し、ログやレポートを保存して、モデルの使用量とコストを報告します。一方で、トラッカーが変更されないことは保証されます。計画プロンプトには、関連する Testing、Closeout Evidence Commands、Acceptance Evidence、Rules の各セクションがコンテキストとして含まれますが、モデルが実行可能なコマンドを追加したり、実行を許可したりすることはできません。--apply は明示的に別のモードとして指定する必要があり、コントローラーの状態がクリーンで、デフォルトブランチ以外にあることが条件です。TUI で再確認を求め、tick を作成・コミットするのはこのモードだけです。スカウトの数と並列数の上書きには上限があります（--scouts 3..6、--scout-cap 2..4）。拡張機能は、変更を行う前に、厳密なバージョン管理付き JSON、依存関係の非循環性、垂直方向の受け入れ条件、同一ウェーブ内のファイル安全性を検証します。EPIC-SKELETON を追加するのはモデルではなくコントローラーです。復旧方法と TUI 外での確認の動作については、references/pi-runner.md を参照してください。

収集した要件をエピックごとに整理し、tick に変換します。

全体像 — ロードマップ、プロジェクト、日付

オプトイン式の構造規約（ラダー、コンテナの DoR、サイクル／マイルストーン／イニシアチブ）：references/big-picture.md

ほとんどの作業は、順序付けられたエピックと依存関係だけを並べた、フラットなロードマップから始まります。これが**「とにかくリリースする」**ためのデフォルトであり、単一のワークストリームなら、これだけで十分です。プロジェクト、バケット、target_date などの機能は、作業が大きくなり、必要になったときに追加します。

階層：tick → epic → project

Ticks には再帰的なコンテナー型が 1 つあります。役割は、構造と明示的な epic マーカーから決まります。

子を持つか？	epic マーカーがあるか？	子が含むもの	役割
いいえ	いいえ	—	tick — 個別の作業
いいえ	はい	—	空の epic — 計画が必要
はい	はい	任意	epic — オーケストレーション単位（wave、完了処理、ふりかえり）
はい	いいえ	すべて個別の作業	bucket — 受動的なグループ化のみ
はい	いいえ	コンテナーを含む	project — グループ化と人によるチェックポイント

基本原則：包含は自由かつ受動的であり、オーケストレーションは明示的に選択します。

• 子を持つ tick はすべてコンテナーです。進捗を集計し、子孫をグループ化します。実行コストはかかりません。
• -t epic マーカーによって、コンテナーはオーケストレーション単位になります。tk next は子を wave として実行し、EPIC-SKELETON プロセスの tick（最終レビューと完了処理／ふりかえり — 以下を参照）が追加され、ロードマップのノードになります。このマーカーの意味は、epic が空か、内容があるかにかかわらず同じです。構造だけから導出されることはありません。既存のコンテナーを epic に昇格すると（tk update <id> -t epic）、EPIC-SKELETON チェックが直ちに実行されます。昇格は通常の計画フローを経由しないため、後回しにせず、昇格時点で 2 つのプロセス tick があることを確認するか、作成してください。
• マーカーがなく、個別の子のみを持つコンテナーはbucketです。子は通常の準備完了キューでそれぞれ独立して処理され、ひとまとまりとして調整されることはありません。epic として実行することなく、無関係なタスクの集まりを見やすくグループ化したい場合は、bucket を使ってください。
• マーカーがなく、少なくとも 1 つの別のコンテナーを含むコンテナーはprojectです。project はグループ化を行い、人によるチェックポイントを設けます（続きは以下を参照）。「initiative」は project の集まりにすぎません。同じ型で、慣例が異なります。

Epic の完了条件（強く推奨）

すべての epic に明示的な完了条件を設定してください。これは、子の tick が閉じられたことだけではなく、epic 全体の完了を意味する、外部から見えるユーザー向けの条件です。epic の --acceptance として保存します。

tk create "Auth foundation" -t epic -d "<rough scope>" \
  --acceptance "New user can sign up, log in, and see their profile end-to-end against a real DB. \`go test ./internal/auth/...\` and the e2e signup test pass. No auth route 5xxs on the happy path."

任意ですが、強く推奨します。これがあると、実行時に tick がなくなっただけでなく、実際に完了したことを判断できます。Epic-close のふりかえりでは、この定義に照らしてコードを項目ごとに検証します（references/agent-runner.md → Outside-in verification）。これがない場合、ふりかえりでは epic の説明文からスコープを再導出します。

目標と両立する内容にしてください。 エージェントが人の介入なしに達成を確認できる場合、その完了条件は目標と両立するといえます。

• 確認可能 — 各項目は実行可能なコマンド、または観察可能な振る舞いとします。「うまく動く」「洗練されているように感じる」は使いません。
• 範囲が明確 — 対象範囲を示して、そこで終わるものにします。「ユーザーが望むことは何でも」は完了条件ではありません。
• 外部視点 — 内部実装の詳細ではなく、ユーザーから見える振る舞いと、それを証明するコマンドを記述します。

目標と両立する完了条件があれば、epic を安心して引き継ぎ、離れることができます（Goal-ready handoff を参照）。「見た目が適切」「速く感じる」といった、人の感覚による判断が本当に必要な項目を記述してもかまいません。ただし、自律実行に判断を期待するのではなく、--awaiting ゲートの下に置いてください。

Project の目標（目標の設計）

Project にも 1 階層上で同様の取り組みが必要です。project の説明に目標の記述を、--acceptance にファクトシート（個別に検証可能な [A<n>] マーク付きの成果記述）を設定します。子の epic を計画する前に、references/goal-design.md のプロトコル（言い換え → インタビュー → ファクトシート → 書き戻し）に沿って、人とともに目標を設計してください。これらの事実があると、project のチェックポイントは「確認のために一時停止」するだけのものではなく、目標を項目ごとに検証するものになります。また、自律実行が project の境界を正当に越えて続行できるのか、実際の不足があって停止すべきなのかを判断できます。A<n> ID はコンテナー間で重複しないようにしてください（epic とその project の両方で A1 を使うことはできません）。

ロードマップのエッジ

仕様が複数のエピックにまたがる場合は、順序エッジで結び付けます。エッジは2種類あり、正しく選ぶことが最も重要です。

• --blocked-by = ハード依存関係（実行可能性）。 ブロッカーが完了するまで、後続のエピックは決して準備完了になりません。エピックに前提となるエピックが本当に必要な場合にのみ使用してください。同じファイルでのマージ競合を避けるために順序を設定する場合も含みます（これは好みではなく、実際の制約です）。
• --after = ソフト順序（優先順位）。 順序を設定しますが、準備完了を妨げることはありません。tk next はソフト順序で後回しにされた候補を最後に並べますが、候補から除外することはありません。優先されたエピックが実行不可能な場合、選択は自然に次の実行可能なエピックへ進みます。存在しない、または完了済みの --after の対象は無視されます。

tk roadmap は、両方のエッジタイプの統合に基づいてエピックをウェーブに分け、それぞれを区別して注記します（← blocked by: と、よりソフトな ← after:）。キュー状態はハードエッジのみから決まります。オープンな前提エピックがソフトなものだけであるエピックは、準備完了／アクティブのままです。

子チケットを作成するのは、最前のエピックだけです。後続のエピックは親のみのチケットとして存在させ、詳細なタスクではなく、大まかなスコープの説明（1段落と成果物のリスト）をそれぞれ記載します。これはジャストインタイムの詳細化です。将来のエピックは、並べ替えやスコープ変更を低コストで行えます。

# Create the roadmap up front — only epic A gets child ticks now
tk create "Auth foundation" -t epic -d "<rough scope>"                      # A — flesh out now
tk create "Team workspaces" -t epic -d "<rough scope>" --blocked-by <A>    # B — genuinely needs A's auth model
tk create "Billing" -t epic -d "<rough scope>" --after <B>                 # C — preferred order only, no real dependency

EPIC-SKELETON の不変条件：実行可能なすべてのエピックは、最後に2つのプロセスチケットを持ちます。最終レビューのチケット、その次にクローズアウトのチケットです。 計画時に、エピックに子チケットを作成する際は、実装チケットの直後にこの2つを作成してください（現時点では最前のエピック、後続のエピックではクローズアウトの内容を具体化する際に作成します）。

# 1. Final review — blocked by every last-wave implementation tick
tk create "Final review of <epic A> diff" \
  --parent <A> --role review \
  --blocked-by <last-wave-tick-1> --blocked-by <last-wave-tick-2>   # every last-wave tick

# 2. Close-out — blocked by the final review, always the last child
tk create "Close out <epic A>: run epic retro, then flesh out the next feasible epic into ticks" \
  --parent <A> --role closeout \
  --blocked-by <final-review-tick>

--role review|closeout フラグによって、スケルトンは構造的なものになります。tk graph <epic> --json はこのフィールドから missing_process_ticks（どのロールも持たない子チケット）を報告するため、スケルトンの欠落や不完全さを、タイトルとの照合に頼らず機械的に検出できます。すでにこれらのチケットがあり、ロールが設定されていない場合は、tk update <id> --role review|closeout で修正してください。

最終レビューのチケットでは、エピック全体の差分をレビューし、クローズアウトによってブロックが解除される前に、指摘事項を解決するか、適切な担当に振り分けます（詳細な意味については references/agent-runner.md →「メタ作業チケット」を参照）。クローズアウトの実行内容は次のとおりです。エピック完了時のレトロスペクティブを実行し（references/agent-runner.md を参照）、ソフト順序で次の実行可能なエピックを選びます。ハードブロック中またはゲートされているものはスキップします。大まかなスコープを読み、独自の EPIC-SKELETON のペアも含めて子チケットに分割し、tk graph <that-epic> を続けて実行します。エピックの境界は構造的に処理されるため、裁量による引き継ぎも、人間による再プロンプトも必要ありません。

計画のトリガーは tk から通知されます。 3つの CLI シグナルにより、エピックの計画または修正が必要なタイミングがわかります。

• tk next <roadmap-epic> --json は、次の項目がブロックされていない子なしエピックの場合、{"action":"plan",...} を返します。人間向けの出力は <id> P<n> epic <title> (needs planning — no child ticks) のようになります。action フィールドはすべての tk next --json の結果に含まれます。準備完了のタスクでは implement、計画可能なエピックでは plan、--awaiting モードの結果では await です。そのため、オーケストレーションからこのフィールドを直接使って分岐できます。
• tk graph <epic> --json は、そのエピックが今すぐ計画可能な場合（子がゼロで、ブロックされていない場合）、{"needs_planning": true,...} を返します。ブロック中の子なしエピックと、子がすべて完了済みのエピックには、説明的な人間向け出力とともに false が設定されます。
• tk graph <epic> --json は、エピックに子があるものの EPIC-SKELETON が不完全な場合、missing_process_ticks（例：["review","closeout"]）を返します。子チケットに該当する --role が設定されていないためです。必要なのは再計画ではなく修正です。不足しているプロセスチケットを作成してください（上記のテンプレートを参照）。空の配列はスケルトンが完全であることを意味します。子なしエピックの場合も、計画を行うとスケルトンが作成されるため、配列は空です。その場合は needs_planning がシグナルになります。

いずれかのシグナルが発生したら、エピックを子チケットに具体化します（上記のロードマップのガイダンスと、references/tick-patterns.md の基盤優先手順に従ってください）。その後、tk graph <epic> を続けて実行します。 エピックの追加、削除、並べ替えなど、ロードマップレベルの変更は人間が決定します。 エージェントはレトロレポートで提案できますが、独断で実行してはなりません。

このルールは段階的な仕様にも適用されます。現在または次のフェーズのティックの作成だけに集中してください。将来のフェーズはロードマップ上の後続エピックとして扱います。親のみを作成し、大まかなスコープを設定します。詳細なタスクはまだ作成しません。

続行と停止

デフォルトでは、エピックの境界を越えて自動的に続行します。プロジェクトの境界では人間による確認のために停止します。プロジェクトの最後の子にはデフォルトで --awaiting checkpoint が設定されるため、実行は一時停止し、次のプロジェクトを開始する前に人間が確認できます。

# Auto-continue into epic B (default) — hard edge because B genuinely needs A
tk create "Team workspaces" -t epic -d "<rough scope>" --blocked-by <A>

# Force a human review before starting epic C — soft ordering plus a gate
tk create "Billing" -t epic -d "<rough scope>" --after <B> --awaiting checkpoint

すべてのプロジェクトのチェックポイントを通して完全に手放しで実行するには、tk next に --autonomous を渡すか、.tick/config.json で policy.autonomous_mode: true を設定します。その他の待機タイプ（work、approval、input、…）は自律モードでも引き続き実行を止めます。通過できるのはチェックポイントの境界だけです。

目標に沿った引き継ぎ

先頭のエピックに、目標と整合する完了の定義（上記）があれば、計画を引き継ぐ準備が整っています。実行時に詳細化、実装、レビュー、完了処理が行われ、ロードマップを確認なしで進められます。計画後、実行に移る前に、ユーザーと明示的に判断してください。

• 完了の定義が目標と整合している → 最後まで任せる方法を推奨し、実行するコマンドを1つ提示します。ハーネスからエピックを実行し（Step 5）、tk next に --autonomous を追加する（または policy.autonomous_mode: true を設定する）ことで、プロジェクトのチェックポイントも通過できます。
• 完了の定義がない、または目標と整合していない → 不明な点を伝え、先に内容を明確化することを提案するか、各プロジェクトの境界でデフォルトの人間によるチェックポイントを設けて実行します。

ここで、実行を停止するまでの範囲を、エピック1つ、プロジェクト1つ、ロードマップ全体のいずれにするか決めます。実行途中で判断するのではありません。

同じ判断はプロジェクトにも当てはまります。承認済みの受け入れ証拠マッピングにより、目標の事実をすべて自動検証できるプロジェクト（上記のプロジェクトの目標と references/goal-design.md を参照）は、最初から最後まで引き継いでも安全です。実行はプロジェクトの境界で目標を検証し、実際に不足がある場合にのみ停止します。人間の判断が必要な事実を含むプロジェクトは、自律モードの有無にかかわらず、チェックポイントで必ず停止します。

目標日と遅延シグナル

任意のティックに、オプションで target_date（ISO形式の正確な日付）を設定できます。シグナルは保存されず、そこから導出されます。そのため、古くなったり、マージの競合が発生したりすることはありません。

• 期限超過 — target_date を過ぎており、未完了の子孫が1つ以上あります。
• 予定どおり — target_date が設定されており、まだ過ぎていません。
• （日付なし）— シグナルなし。作業は依存関係のみに基づいて進みます。

日付によって実行が止まることはありません。人間への通知やフィルタークエリ用のフラグとして機能します。

tk create "v2.0 launch" -d "<release outcome>" --target-date 2026-09-30
tk update <id> --target-date 2026-10-15   # revise the date
tk list --overdue                          # past target_date with open work
tk list --due-before 2026-08-01           # target_date strictly before this date
tk list --sort target_date                # ascending; undated ticks sort last

使用例

例1 — 日付付きリリースのためにエピックをまとめる（プロジェクト）

# "v2.0 launch" is created without -t epic, so it is a project — it groups and
# provides a checkpoint boundary but is not "run as a unit" itself.
# Its epics run exactly as epics do today.
tk create "v2.0 launch" -d "<release outcome>" --target-date 2026-09-30
tk create "Auth revamp" -t epic --parent <v2>                    # front epic — flesh out now
tk create "Billing"     -t epic --parent <v2> --after <auth>     # downstream — rough scope only
tk create "Dashboard"   -t epic --parent <v2> --after <billing>

# Epics auto-continue into each other. When the last one closes, the v2.0
# project boundary stops for human sign-off. target_date feeds the overdue /
# on-track signal; it never gates execution.

例2 — 入れ子になったプロジェクト（Linearでいう「イニシアチブ」— 単なる慣習）

tk create "Q3 Platform" --target-date 2026-09-30                  # top-level project
tk create "Payments"    --parent <q3> --target-date 2026-08-15    # sub-project (milestone-ish)
tk create "Auth revamp" -t epic --parent <payments>               # epic under the sub-project

# Each sub-project boundary is its own checkpoint; the engine ascends the tree as
# each level completes.

例3 — 受動的なバケット（オーケストレーションを行わないグループ化）

# No -t epic means a bucket. Groups for visibility and rolls up a count;
# the bugs inside flow through the normal ready queue independently, never
# coordinated as a unit.
tk create "Q3 bug triage"
tk create "Fix flaky login test"       --parent <triage>
tk create "Dashboard chart off-by-one" --parent <triage>

並列実行を想定した設計

同じウェーブ内のティック（ブロック関係がないティック）は、それぞれ独自の git worktree で同時に実行されます。worktree により、実行中にエージェント同士が互いの変更を上書きするのを防げます。ただし、同じファイルを編集する 2 つのティックはブランチのマージ時に衝突します。また、隔離できない同じリソース（1 つのテスト DB、固定ポートなど）をテストで使用する 2 つのティックは、互いの実行結果を壊します。

制約の境界で分割します。 2 つの成果物が同じファイルやリソースを共有する場合、その共有要素である 制約の境界 を基準にティックの境界を決めます。機能一覧を基準にしてはいけません。共有する各要素は、次の順序で解決します（手順の詳細は references/tick-patterns.md を参照してください）。

• 両方が編集する継ぎ目となるファイル → 1 つのティックに割り当てます。 所有者を 1 つにすれば、それ自体との競合は起きません。2 つのティックを順番に実行しても、衝突を先送りするだけです。まとめたティックが大きくなりすぎる場合に限り、--blocked-by で分割して順序付けします。予測できるマージ競合はハード依存関係であり、--after ではありません。
• 共有する隔離不能なリソース（1 つのテスト DB、固定ポートなど） → 1 つのウェーブでそのリソースに触れるティックは最大 1 つです。 これにより、機能のまとまりをまたいで作業をまとめる場合もあります。
• ロックファイルと生成ファイルも継ぎ目です。 同じウェーブ内の 2 つのティックがそれぞれ依存関係を追加すると、どちらも pnpm-lock.yaml／go.sum を書き換えます。依存関係の追加はすべて 1 つの早い段階のティックにまとめるか、順次実行してください。

各制約グループ内で垂直に分割します。 ティックはレイヤー別（スキーマをすべて、次に API をすべて、最後に UI をすべて）ではなく、ユーザーから見える機能別（1 つの機能を最初から最後まで）に分割し、どのティックの後もシステムが動作し、デモできる状態にします。垂直分割と制約の境界が食い違う場合は、制約の境界を優先します。詳しい理由は references/tick-patterns.md を参照してください。

共有コントラクトを先に定義します。 複数のティックが同じインターフェース（API の形状、DB スキーマ、共有型など）を使用する場合は、それを定義するティックを 1 つ作り、他のティックから --blocked-by で依存させます。最初に安定したコントラクトを用意すれば、依存するティックは形状を推測するのではなく、既知の形状に対して並行して実行できます。また、説明内で同じものを同じ名前で呼ぶことができます。

作業可能な状態を保ち、早期に問題を検出できる順序にします。 各ティックの後にビルドが成功し、アプリを実行できるよう、ティックを順序付けます。また、リスクや不確実性が最も高いティックを早い段階に配置します。誤った前提には 12 番目ではなく 2 番目のティックで気付けます。フェーズの境界で先に確認したい場合は、--awaiting checkpoint ティックを作成します。真に未解決の疑問がある場合は、推測するのではなく --awaiting input ティックを作成します。

実行前にエピックのティックを確認します。 ティックを作成したら、次の項目を簡単に確認します。

1. 網羅性 — 収集した要件（このフェーズのもの）を 1 つずつ確認し、実装するティックを特定します。漏れがあればティックを追加します。
2. 規模 — タイトルに「および」が必要なティックや、受け入れ条件が 3 つの箇条書きに収まらないティックは分割します。
3. 命名の一貫性 — 同じインターフェースは、ティックの説明全体で同じ名前にします。あるティックでは clearLayers、別のティックでは clearFullLayers と呼ぶような契約は、潜在的なバグです。
4. ウェーブの安全性 — tk graph <epic> を実行し、同じウェーブ内の 2 つのティックが同じファイルや隔離不能なリソースを共有していないことを確認します。

この確認は手間がかからず、エージェントの実行開始後に解消するのが大変な分割ミスを見つけられます。

ステップ 4：ブロック要因となる人手のタスクをユーザーに案内する

人手のタスクが自動化タスクをブロックする場合は、エージェントを実行する前にユーザーを案内して対応してもらいます。

# Check for blocking human tasks
tk list --awaiting work
tk blocked  # See what's waiting

ブロック要因となる各タスクをユーザーに案内したら、そのタスクをクローズします。

tk close <id> --reason "Completed: connection string in .env"

ステップ 5：エピックを実行する

現在のハーネスからエピックを実行します。まず references/agent-runner.md を読み、次に使用しているハーネスのアダプターを読みます。Codex で実行する場合は references/codex-runner.md、Claude Code で実行する場合は references/claude-runner.md、Pi で実行する場合は references/pi-runner.md、Prime Agent で実行する場合は references/prime-runner.md を読んでください。アダプターによって 誰がオーケストレーションするか が決まります。それとは独立した 2 つ目の選択として、ワーカーをどのようにディスパッチするか、つまり 基盤 を決めます。基盤は、ハーネス独自のサブエージェントか、異種混成の herdr フリートです（references/herdr-runner.md はハーネスのアダプターと併せて読み、アダプターの代わりにはしないでください）。.tick/runners.toml の [orchestration].substrate（herdr | harness | auto、デフォルトは auto）によって選択されます。herdr が指定されているものの利用できない場合は、ハーネスによるディスパッチに明示的にフォールバックします。詳しくは references/runners-config.md のセマンティクスを参照してください。まだ決めていない場合は、起動前に Goal-ready handoff の判断（上記）を済ませてください。人間に引き継ぐ前に、この実行をどこまで進めるべきかを決めます。実行の流れは次のとおりです。

1. tk graph <epic-id> --json を実行して、ウェーブと並行実行できる範囲を確認します。結果に "needs_planning": true が含まれている場合、エピックには子ティックがまだありません。まず分解し（上記の「全体像」セクションを参照）、その後 tk graph を再実行します。
2. EPIC-SKELETON の事前確認：同じ結果に空でない missing_process_ticks が含まれている場合は、ウェーブ 1 の前に --role を指定して不足しているプロセスティックを作成します（テンプレートは上記の「全体像」セクションを参照）。
3. 各ウェーブで、準備ができたティックごとに 1 人の実装担当者を起動し、それぞれ専用の Git ワークツリーを使って、アダプターの並列ディスパッチ機能で実行します。
4. アダプターの完了待ち機能を使って待機し、検証済みの各ブランチを暫定的にマージします。ブランチとワークツリーは保持し、成功したトラッカーの状態遷移は保留します。
5. 完全にマージされたツリーに対して、状態を永続化したうえでウェーブ後のテストゲートを実行します。成功した場合に限り、ウェーブを永続的に完了し、クリーンアップします。失敗した場合は、影響を受けたすべてのティックを修復状態を保持したまま未完了とし、依存するティックをブロックします。その後、次のウェーブに進みます。実装ウェーブが完了すると、最終レビューとクローズアウトのティックが順にブロック解除されます。

すべてのティックの状態はあなたが管理します。実装担当者がコードを書き込むのは、それぞれのワークツリーだけです。実際のブロッカーに遭遇しない限り、ウェーブから次のウェーブへ連続して実行してください。

クイックリファレンス

ティックの作成

tk create "Title" -d "Description" --acceptance "Tests pass"  # Task
tk create "Title" -t epic                                     # Epic
tk create "Title" --parent <epic-id>                          # Under epic
tk create "Title" --blocked-by <task-id>                      # Blocked (hard dependency)
tk create "Title" --after <task-id>                           # Soft ordering preference (never blocks)
tk create "Title" --awaiting work                             # Human task
tk create "Title" --requires approval                         # Needs approval gate
tk create "Title" --parent <epic> --role review               # Epic's final-review process tick
tk create "Title" --parent <epic> --role closeout             # Epic's close-out process tick

エピックにも --acceptance を指定できます。エピックの 完了の定義 に使用してください（強く推奨します。「エピックの完了の定義」を参照）。ゴールと整合した完了条件があれば、エピックを引き継いで作業を離れられます。

tk では、長いフラグに標準の二重ハイフンを使用します。-acceptance／-parent／-blocked-by（ハイフン 1 つ）は 機能しません。--acceptance／--parent／--blocked-by を使用してください。-d、-t、-p、-l、-b などの 1 文字の短縮形は使用できます。

クエリ

tk list                      # All open ticks
tk list -t epic              # Epics only
tk list --parent <epic-id>   # Tasks in epic
tk ready                     # Unblocked tasks
tk next <epic-id>            # Next task for agent
tk next <epic-id> --json     # JSON: action field is "implement" | "plan" | "await"
tk blocked                   # Blocked tasks
tk list --awaiting=          # Tasks awaiting human
tk graph <epic-id>           # Dependency graph with parallelization
tk graph <epic-id> --json    # JSON output; needs_planning:true means epic needs child ticks;
                             # non-empty missing_process_ticks means EPIC-SKELETON needs repair

管理

tk show <id>                                           # Show details
tk close <id> --reason "Completed: <one-line summary>" # Close tick — always pass --reason
tk note <id> "text"                                    # Add note
tk approve <id>                                        # Approve awaiting tick
tk reject <id> "feedback"                              # Reject with required feedback

クローズ理由の規約： クローズ時には必ず --reason を指定し、具体的な概要を記載してください。 tk close <id> --reason "Completed: <取り込まれた内容の1行概要>" のように指定してください。理由を指定しない tk close は使用しないでください。

実行者の規約（オーケストレーション実行時）： 実行開始時に TK_ACTOR=<runner>:orchestrator をエクスポートします。たとえば claude:orchestrator、codex:orchestrator、pi:orchestrator、prime:orchestrator のように指定すると、アクティビティエントリーに実行元が保持されます。1 回の呼び出しで上書きするには --actor <name> を使用します。 優先順位：--actor フラグ > TK_ACTOR 環境変数 > ティック所有者のデフォルト値。

Epic の実行

現在のハーネスから実行します（共通の詳細は references/agent-runner.md、Codex の場合は codex-runner.md、Claude Code の場合は claude-runner.md、Pi の場合は pi-runner.md、Prime Agent の場合は prime-runner.md を参照してください）。

次に、ディスパッチの基盤を選択します。ハーネスネイティブのサブエージェント、または各ティックで独立して動作するワーカー群の herdr フリートです（ハーネスアダプターに加えて references/herdr-runner.md を参照してください）。設定は .tick/runners.toml の [orchestration].substrate（herdr | harness | auto、デフォルトの auto は読み取り専用プローブで検出された場合は herdr、そうでなければ harness）で指定します。判断表と明示的な縮退ルールについては references/runners-config.md を参照してください。

# 1. Get the dependency graph (waves + max parallelism)
tk graph <epic-id> --json

# 2. Select the role tier, then launch one isolated implementer per ready tick.
#    Planning and final review use frontier settings. Implementation uses the
#    adapter's economy/balanced/strong mapping.
#
# 3. Wait using the adapter's native primitive, then integrate each tick:
git diff --name-only HEAD...<agent-branch> -- .tick/   # boundary check: must be empty
git merge <agent-branch>   # if it conflicts: abort, have the agent rebase + resolve in its worktree
tk close <tick-id> --reason "Completed: <one-line summary of what landed>"

# 4. After the wave's merges land, run the test suite before launching the next wave

並列実行の計画

エージェントを起動する前に、tk graph を使って並列化の可能性を把握してください。

tk graph <epic-id>        # Human-readable wave breakdown
tk graph <epic-id> --json # Machine-readable for orchestration

グラフには次の内容が表示されます。

• ウェーブ：並列実行できるティックのグループ
• 最大並列数：最も幅の広いウェーブで同時に起動できるサブエージェントの数
• クリティカルパス：Epic の完了に必要な逐次ウェーブの最小数
• 依存関係：各ティックが何によってブロックされているか

ウェーブごとに max_parallel 個までサブエージェントを起動します（コストやノイズを抑えたい場合は上限を設定してください）。次のウェーブを開始する前に各ウェーブの作業をマージし、依存するティックが完了済みの作業を基に進められるようにします。

詳しくは references/tk-commands.md を参照してください。

実行待ちのティックへの対応

対話形式で作業する際は、ユーザーが実行待ちのティックを処理できるよう支援します。

tk list --awaiting=   # Find ticks awaiting human
tk next --awaiting=   # Next one needing attention

AskUserQuestion を使ってユーザーの判断を支援し、その後、次を実行します。

# User approves
tk approve <id>

# User rejects
tk reject <id> "feedback here"

# User provides input
tk note <id> "Use sliding window algorithm" --from human
tk approve <id>

ユーザーに代わってメモを追加する場合は、必ず --from human を使用してください。