jj-todo-workflow

JJ TODO ワークフロー

中心となる考え方は、空のリビジョンの DAG を TODO マーカーとして使用し、実行すべきタスクを表現することです。そして後からこれらのリビジョンを編集して実際にタスクを実行します。これにより、明確なマイルストーンを伴う構造化された開発が可能になります。 リビジョンの説明（つまりコミットメッセージ）は、実装すべき内容の仕様として機能します。 JJ を使えば、このような構造を簡単に作成し、後から各リビジョンを埋めていくことができます。

JJ の基本について詳しくは、working-with-jj スキルを参照してください。ここではそのスキルからスクリプトを再利用します。

このスキルでは 2 つの役割について説明します。プランナー（空のリビジョンとその仕様を配置する役割）とワーカー（それらを実装する役割）です。 状況に応じて、プランナーとしてのみ、ワーカーとしてのみ、あるいはその両方として行動することがあります。 プロセス全体をよく理解しておくことが望ましいですが、各セクションのタイトルは、そのセクションがどの役割に最も関係するかを明示しています。

クイックスタート（プランナー & ワーカー）

計画から完了までの完全なサイクルは次のとおりです（ヘルパースクリプトへのフルパスは記載していません）：

# 1. Plan: Create a simple TODO chain
jj-todo-create @ "Add user validation" "Check email format and password strength"
# Created: abc123 (stays on current @)

jj-todo-create abc123 "Add validation tests" "Test valid/invalid emails and passwords"
# Created: def456 (@ still hasn't moved)

# 2. Start working on first TODO
jj edit abc123
jj-flag-update @ wip   # Now [task:wip]

# ... implement validation ...

# 3. Verify ALL acceptance criteria met
make test  # Or equivalent in your project

# 4. Ask to move to next task
jj-todo-next
### ... review current specs (to ensure compliance) and next possible TODOs ...

# 5. Once we're sure everything is properly done, move to next TODO
jj-todo-next --mark-as done def456   # Marks abc123 as [task:done], starts def456 as [task:wip]

以上です！ 仕様としての空のコミット、それに取り組むための編集、完全に完了したら jj-todo-next --mark-as done <next-step> を実行します。

ステータスフラグ（プランナー & ワーカー）

説明のプレフィックスを使って、ステータスを一目で追跡します。[task:*] 名前空間により、grep しやすくなり、他の規約との競合を避けることができます。

許可されているステータスフラグは以下ののみです：

フラグ	意味
[task:draft]	プレースホルダーが作成済み、完全な仕様が必要
[task:todo]	未着手、完全な仕様を持つ空のリビジョン
[task:wip]	作業中
[task:blocked]	外部依存関係を待機中
[task:standby]	何らかの判断待ち（壊れていて修正が難しく、有用性が疑問視されている、など）
[task:untested]	実装は完了したが、検証するのに十分なテストがされていない
[task:review]	レビューが必要（トリッキーなコード、設計上の選択）
[task:done]	完了、すべての受け入れ基準を満たしている

この順序は目安です。すべてのタスクがこれらのすべてのステップを経る必要はなく、また必ずしも上記の順序どおりである必要もありません。

NOTE: このスキルの以前のバージョンでは、standby は「broken」と呼ばれていました。このステータスをより広く適用できるようにするため、名前が変更されました。

draft と todo の使い分け（プランナー）

[task:draft] を使うのは：

• DAG 構造を確立するためのプレースホルダータスクを作成する場合
• タスクのタイトル／概念は明確だが、詳細がまだ詰められていない場合
• 完全な受け入れ基準の記述を先延ばしにしたい場合
• 詳細に入る前に高いレベルで計画する場合

[task:todo] を使うのは：

• タスクに完全な仕様（コンテキスト、要件、受け入れ基準）がある場合
• ワーカーが確認なしでそれを引き継ぎ、実装できる場合
• すべての依存関係とアプローチが明確に文書化されている場合

フラグの更新（ワーカー & プランナー）

jj-flag-update @ draft     # Mark as needing specification (Planners)
jj-flag-update @ todo      # Mark as ready to work on (Planners)
jj-flag-update @ wip       # Start work (Workers)
jj-flag-update @ untested  # Implementation done, tests missing (Workers)
jj-flag-update @ done      # Complete (Workers)

フラグが付いたリビジョンの検索（プランナー & ワーカー）

jj-find-flagged                     # All tasks
jj-find-flagged draft               # Only [task:draft]
jj-find-flagged todo                # Only [task:todo]
jj-find-flagged wip                 # Only [task:wip]
jj-find-flagged done                # Only [task:done]

# Manual - all tasks
jj log -r 'description(substring:"[task:")'

# Incomplete tasks only (excludes done)
jj log -r 'description(substring:"[task:") & ~description(substring:"[task:done]")'

基本的なワークフロー（プランナー & ワーカー）

1. 計画：TODO チェーンの作成（プランナー）

# Create linear chain of tasks
jj-todo-create @ "Task 1: Setup data model" "...details..."
jj-todo-create <T1-id> "Task 2: Implement core logic" "..."
jj-todo-create <T2-id> "Task 3: Add API endpoints" "..."
jj-todo-create <T3-id> "Task 4: Write tests" "..."

2. 作業：各 TODO の編集（ワーカー）

# Read the specs
jj-show-desc <task-id>    # BEWARE: Script from the `working-with-jj` skill
 
# Start working on it
jj edit <task-id>
jj-flag-update @ wip

# ... implement ...

# Mark progress
jj-flag-update @ untested

3. 完了して次へ移動（ワーカー）

jj-todo-next スクリプトは、「次のタスクへの移行」プロセスを円滑にするために用意されています。

引数なしの場合

• 現在のタスクの説明を出力して、レビューし、すべてが計画どおりに実装されていることを確認できるようにします
• 次に可能なタスクを出力します

# Review current specs and see what's next
jj-todo-next
# Shows:
#   📋 Current task specs for review:
#   ─────────────────────
#   ...
#   ─────────────────────
#
#   Current task status: [task:wip]
#   Mark as [task:done] only if FULLY COMPLIANT with specs above.
#
#   ✅ Available next tasks:
#     abc123  [task:todo] Feature B
#     def456  [task:todo] Feature C
#
#   ⚠️ Child tasks with unmet dependencies:
#     xyz789  [task:todo] Integration
#             Blocked by: abc123

引数ありの場合

• 現在のタスクのフラグを更新します
• 次のタスクへ移動（jj edit）します
• 新しいタスクのフラグを [task:wip] に更新します

# Actually mark current done and start editing next:
jj-todo-next --mark-as done abc123
# Does the `jj edit abc123` and shows its description

並列タスクの計画 (DAG) (プランナー)

独立して作業できるブランチを作成します。例:

# Linear foundation
jj-todo-create @ "Task 1: Core infrastructure"
jj-todo-create <T1-id> "Task 2: Base components"

# Parallel branches from Task 2
jj-parallel-todos <T2-id> "Widget A" "Widget B" "Widget C"

# ... edit their descriptions to add more details ...

# Merge point (all three parents must complete first)
jj new --no-edit <A-id> <B-id> <C-id> -m "[task:todo] Integration of widgets\n\n..."

結果:

          Integration
       /      |        \
   Widget A  Widget B  Widget C
       \      |        /
          Task 2: Base
              |
          Task 1: Core

リベースは不要 - 親を直接指定しています!

適切な TODO 説明の書き方 (プランナー)

構造

Short title (< 50 chars)

## Context
Why this task exists, what problem it solves.

## Requirements
- Specific requirement 1
- Specific requirement 2

## Implementation notes
Any hints, constraints, or approaches to consider.

## Acceptance criteria
How to know when this is FULLY DONE (not just "good enough"):
- Criterion 1
- Criterion 2

重要: 受け入れ基準は、いつ [task:done] としてマークできるかを定義します。具体的かつテスト可能にしてください。

説明は全体として、できる限り自己完結的であるべきです。 コンテキストをほとんど持たないエージェントが、本来事前に指定されるべきだった直前の判断を下すことなく、作業を開始するために必要なすべての情報を得られるようにする必要があります。

可能な限り以下にリンクすることで冗長性を避けてください:

• 既存の仕様ドキュメント
• コードベース内の関連する例

そのようなリンクを含める際は、単純な再フォーマットで無効になりうる行番号のような不安定な参照を避けてください。 代わりに、セクションや、仕様へのリンクがそれをサポートする形式 (Markdown の #stuff、LaTeX の \ref{stuff}、Typst の @stuff など) であればラベル参照、コードを参照する場合は関数名やクラス名を優先してください。

例

Implement user authentication

## Context
Users need to log in to access their data. Using JWT tokens
for stateless auth.

## Requirements
- POST /auth/login accepts email + password
- Returns JWT token valid for 24h
- POST /auth/refresh extends token
- Invalid credentials return 401

## Implementation notes
- Use bcrypt for password hashing (see src/auth/admin.py::AdminLogin::hash_passwd which already uses it)
- Store refresh tokens in Redis
- See auth.md (#about-tokens) for token format spec

## Acceptance criteria
- All auth endpoints return correct status codes
- Tokens expire correctly
- Rate limiting prevents brute force

AI 支援による TODO ワークフロー

TODO は AI サブエージェントと非常に相性が良いです:

• スーパーバイザーエージェントが初期計画を行い、TODO リビジョンのグラフを作成します
• スーパーバイザーエージェントは、ワーカーが開始する前に、すべての [task:draft] タスクが記入され [task:todo] としてマークされていることを確認します
• サブエージェントはグラフをただ「走り」、構造と要件に従い、各リビジョンを順番に実装します
• サブエージェントは [task:todo] タスク (完全な仕様を持つ) のみに取り組み、[task:draft] タスクには決して取り組んではいけません
• スーパーバイザーエージェントは差分とノートをレビューし、必要に応じてタスクを [task:wip] や [task:draft] などに戻すことができます

重要: サブエージェントはタスクを並列ではなく、順番に作業しなければなりません。 同じリポジトリ上で複数のエージェントを同時に実行すると、ワーキングコピー (@) を奪い合うため競合が発生します。

もし並列作業が本当に必要な場合は、JJ ワークスペース (git worktree に相当) を使用して各エージェントを分離する必要があります。 並列実行のための JJ ワークスペースの使用に関する詳細なガイドについては references/parallel-agents.md を参照してください。 ただし、以下の理由から、人間のユーザーが明示的に同意しない限りワークスペースを作成しないでください:

• 大幅に複雑さが増します
• このスキルのこの部分はまだベータです

いずれにせよ、1つの TODO をエージェントに与えるか、TODO のシーケンスを与えるかを選ぶ必要があります。サブエージェントに1つの TODO だけを割り当てる場合は、JJ をサブエージェントから抽象化し、このスキルを読み込まなくて済むようにするのが良いでしょう。 jj edit で正しいリビジョンに入って場を整え、JJ の一般的な記帳処理は自分で対処してください。 こうすることで、サブエージェントは与えられたタスクに真に集中でき、JJ の細かな仕様に気を散らされません。

停止して報告すべき場合 (ワーカー)

規定のワークフローのみに従ってください。 問題が発生した場合は、停止してユーザーに報告してください。特に以下の場合:

• 誤ったリビジョンで変更を行った
• 以前の作業に修正が必要で、amend すべきだと気づいた
• 進め方が不明確
• 依存関係や要件が不明確

このワークフローに明示的に含まれていない JJ 操作を使って問題を修正しようとしないでください。 復旧操作はユーザーに任せてください。あなたの仕事はプロセスに従うか、従えない場合に報告することです。

実装の逸脱の文書化 (ワーカー)

実装が仕様と異なる場合、理由が何であれ、それを文書化し正当化してください:

# After implementing, add notes
jj desc -r @ -m "$(jj-show-desc @)

## Post-Implementation notes
- Used argon2 instead of bcrypt. That's because contrary to admin case, here we also needed to comply with...
- Added /auth/logout endpoint. Not in original spec but necessary because...
- Set Rate limit to 5 attempts per minute. Was unspecified, had to make a choice.
"

リマインダー: working-with-jj スキルからのものである場合は jj-show-desc。

これにより意思決定の監査証跡が作成されます。

ヒント

TODO を小さく保つ (プランナー)

各 TODO は1回の集中したセッションで完了できるべきです。大きすぎる場合は、複数の TODO に分割してください。

--no-edit を徹底的に使う (プランナー & ワーカー)

TODO を作成する際は、常に jj-todo-create または jj new --no-edit を使用してください。 そうしないと @ が移動し、現在位置を失います。

完了の規律:「これで十分」はなし(ワーカー)

すべての受け入れ基準を満たすまで、タスクを完了としてマークしないでください。

✅ 完了としてマークする場合:

• すべての要件が実装されている
• すべての受け入れ基準を通過している
• テストが通る(該当する場合)
• 既知の問題が残っていない

❌ 決して完了としてマークしない場合:

• 「これで十分」または「だいたい動く」
• テストが失敗している
• 部分的な実装
• 適切な修正ではなく回避策
• 「後で戻ってくる」つもりである

未完了の場合:

• フィードバックが必要なら --mark-as review を使用
• 外部依存を待っているなら --mark-as blocked を使用
• 何らかの理由で一部をテストできなかったなら --mark-as untested を使用
• その他の理由なら --mark-as standby を使用
• [task:wip] のままにして作業を続ける

# FIRST: Verify the work
make check        # or: cargo build, pnpm tsc, uv run pytest

# ONLY if all checks pass:
jj-todo-next --mark-as done <next-id>

開始前に依存関係を確認する(ワーカー)

並列ブランチや複雑な DAG を扱う場合、新しい TODO に着手するとき:

# Check what a task depends on (its immediate ancestors)
jj log -r 'ancestors(<rev-id>,2)'  # 2 for parents, 3 for parents + grandparents, etc.

# Check what depends on a task (its immediate descendants)
jj log -r 'descendants(<rev-id>,2)'  # 2 for children, 3 for children + grandchildren, etc.

いずれかの依存関係(祖先)に [task:*] フラグがあり、それがまだ draft、todo、wip、または blocked の場合: 停止してユーザーに警告してください。続行する前にユーザーの承認を待ってください。

注: jj-todo-next は依存関係を自動的に確認し、どの子タスクが準備できていないかを示しますが、これは物事を円滑にするためのものであり、jj から抽象化するためのものではありません。必要に応じて jj log でグラフをご自身で確認してください。

ヘルパースクリプト(プランナーおよびワーカー)

ヘルパースクリプトは scripts/ にあります。PATH の設定を避けるため、フルパスで呼び出してください。

スクリプト	目的
jj-todo-create [--draft] <PARENT> <TITLE> [DESC]	TODO を作成(@ のまま)。プレースホルダータスクには --draft を使用
jj-parallel-todos [--draft] <PARENT> <T1> <T2>...	並列 TODO を作成。プレースホルダータスクには --draft を使用
jj-todo-next [--mark-as STATUS] [REV]	仕様を確認し、依存関係をチェックし、マークして任意で移動
jj-flag-update <REV> <TO_FLAG>	ステータスフラグを更新(現在のものを自動検出)
jj-find-flagged [FLAG]	フラグ付きリビジョンを検索

working-with-jj スキルにあるその他の便利なスクリプト:

スクリプト	目的
jj-show-desc [REV]	リビジョンの説明を出力

参考資料

高度なトピックと詳細ガイド:

• references/parallel-agents.md - 並列エージェント実行のための JJ ワークスペースの使用(プランナー)