Linear project tracker

linear-project-tracker

Linear Project の child issue 群の進捗を監視し、 project 完了候補を判定 する skill。 linear-project-workflow と機能重複しないよう責務を分離:

• linear-project-workflow: project description の作成・更新、 status 遷移の 実行
• linear-project-tracker: child issue 群を 読み取り、 project 完了判定 + 遷移提案

実際の status 遷移は linear-project-workflow の Update (C) を呼んで実施 (重複防止)。

When to Use

起動すべき場面:

• pev-linear-sync outbound success の after-hook (issue が Done になった後の parent project 進捗確認)
• 定期チェック (cron-like、 1 project の進捗を確認)
• ユーザーが「project X は完了したか」と問うた時

起動すべきでない場面:

• project description の作成・更新 → linear-project-workflow
• 単一 issue の sync → pev-linear-sync
• issue の起票・更新 → linear-issue-workflow (未実装、 v1.4 候補)

Preflight check (v1.3.0+ 必須)

linear-project-workflow と 共通の preflight を実行:

1. .linear-config.yml 存在確認
2. team.id 整合性検査
3. status workflow preflight (list_issue_statuses で完了条件 status を解決)

詳細は skills/linear-project-workflow/SKILL.md の Preflight 節を参照 (single source of truth)。

MCP error handling (v1.3.0+ 必須)

linear-project-workflow と 同じ error 分類表 を使う。 詳細は同 SKILL.md 参照。

How It Works

Operation 1: Child issue 進捗確認

1. project_id を input として受け取る
2. mcp__plugin_linear_linear__list_issues(project=project_id) で子 issue 一覧取得
3. 各 issue の status (Linear API の statusType) を分類:
   - completed (Done / Released 等): 完了
   - canceled (Canceled / Duplicate 等): 取消
   - unstarted / backlog: 未着手
   - started: 進行中
4. 集計: total / completed_count / canceled_count / in_progress_count / unstarted_count

Operation 2: Project 完了判定

判定ルール:
  - all_done: completed_count + canceled_count == total かつ completed_count > 0
  - mostly_done: completed_count / total >= 0.8
  - in_progress: in_progress_count > 0 or completed_count > 0
  - not_started: unstarted_count == total

判定結果:
  - all_done → project status を `completed` に遷移 候補
  - mostly_done → warning + 残 issue 一覧を report
  - in_progress → 現状維持、 進捗 comment 投稿 候補
  - not_started → 何もしない (project 自体が未着手)

Operation 3: Project 完了条件 (description AC) との突き合わせ

project description の ## 完了条件 セクションを linear-project-workflow Read で parse:

• 完了条件の各 - [ ] / - [x] 項目を取得
• child issue Done 比率と完了条件 check 比率を比較
• 不整合がある場合は warning (例: 「child 全 Done だが完了条件 3/5 のみ check」)

これは project description の checkbox を手動更新せず、 child issue 完了で自動推進したいケースに使う。

Operation 4: Status 遷移提案 (実行は workflow に委譲)

判定が `all_done` の場合:
  1. linear-project-tracker は遷移を提案 (sync_state.json に proposal を書く)
  2. linear-project-workflow の Update (C) が呼ばれて実際の遷移を実行
     - .linear-config.yml の status_mapping.project.completed を参照
     - mcp__plugin_linear_linear__save_project(id, state='completed')
  3. 重複防止: .pev-artifacts/linear/projects/<project_id>/sync_state.json の
     last_status_transition_at をチェック、 直近 24h 以内なら skip

tracker が直接 status 遷移を実行することも spec 上は可能だが、 v1.3 では workflow に委譲する形を推奨 (関心の分離維持)。

artifacts への記録 (v1.3.0+ 命名規約)

.pev-artifacts/linear/projects/<project_id>/
└── sync_state.json
    {
      "tracker_runs": [
        {
          "at": "...",
          "snapshot": {"total": N, "completed": N, "in_progress": N, ...},
          "judgment": "all_done | mostly_done | in_progress | not_started",
          "proposal": "transition_to_completed | warning | none"
        }
      ],
      "last_tracker_run_at": "..."
    }

JSON Schema は schemas/linear-sync-state.json に従う。

When to use vs linear-project-workflow

操作	tracker	workflow
child issue 一覧取得	✅ 主責任	(利用は可)
完了判定	✅ 主責任	(read 時に補助)
status 遷移提案	✅ 主責任	(受け取って実行)
status 遷移実行	(委譲)	✅ 主責任
description 編集	❌	✅ 主責任
comment 投稿	(proposal noteのみ)	✅ 主責任

Examples

Outbound success after-hook (典型シナリオ)

[pev-linear-sync outbound success が完了直後]

1. tracker が起動 (parent project_id をinput)
2. child issue 一覧取得: 3 issues, 全 Done
3. judgment: all_done
4. proposal: transition_to_completed
5. linear-project-workflow Update (C) を呼んで実際の遷移を実行
6. project が completed status に遷移、 startedAt → completedAt 自動セット

部分完了の警告 (mostly_done)

child issue 5 件中 4 件 Done、 1 件 In Progress

judgment: mostly_done (80%)
proposal: warning + 残 issue 一覧 ("TES-7 残りで project 完了")
status 遷移: 実行しない (1 件 In Progress のため)

Limitations

• child issue が 0 件の project は判定不能 (linear-project-workflow で description の 完了条件 checkbox に依存)
• canceled issue の扱い は workspace ポリシー依存 (default では「完了扱い」だが、 yaml で canceled_as_done: false で override 可、 v1.4 候補)
• 24h 以内の重複遷移防止 は heuristic、 厳密な lock 機構ではない

Related

• linear-project-workflow — status 遷移の実行を委譲
• pev-linear-sync — outbound success 後の after-hook trigger
• linear-issue-workflow (未実装、 v1.4 候補) — child issue の起票・更新

Notes

dog food (Phase 3) で linear-project-tracker の必要性が確認された (child 1/1 = 100% Done を手動で判定したが、 通常運用では自動化必須)。 v1.3 で skill 仕様を策定、 実装挙動は v1.4 の dog food で詰める想定。