Agent-Skills.md

Agent Skills: Task Progress Reporter

|

UncategorizedID: goldeneggg/dotfiles/task-progress-reporter

Repository

goldeneggg/dotfiles
goldeneggg
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/goldeneggg/dotfiles/tree/HEAD/ai-linux/.claude/skills/task-progress-reporter

Skill Files

Browse the full folder contents for task-progress-reporter.

Download Skill

Loading file tree…

ai-linux/.claude/skills/task-progress-reporter/SKILL.md

Skill Metadata

Name
task-progress-reporter
Description
|

Task Progress Reporter

task-starter で生成したプロジェクト構造を走査し、完了/進行中/未着手を判定して、 未着手タスクの着手しやすさ分類と推奨対応順序を中心とした進捗レポートを出力する。

スコープ

含むもの

  • task-starter プロジェクト（todos/NNN-{task}/ 構造）の進捗精査
  • 進捗正本による完了判定（PROGRESS.md の状態・AC検証とTODOのID整合性。旧形式だけ補助シグナルを使用）
  • 未着手タスクの内容単位グルーピングと着手容易性マーク（🟢🟡🔴）
  • 依存関係を踏まえた推奨対応順序（Phase A/B/C…）の提示
  • references/template-and-example.md のテンプレートに沿ったレポート出力

含まないもの

  • 新規タスクの分割・ロードマップ生成（→ task-starter）
  • タスクの実装・完了状態の書き換え（→ task-performer）
  • 成果物（PR・コミット）の要件適合レビュー（→ task-artifact-reviewer）
  • タスクファイルの編集（このスキルは読み取り専用。進捗を勝手に変更しない）

進捗状態の3区分と判定不能

実プロジェクトの実態を正確に反映するため、各タスクを3区分で扱い、正本や定義が不正な場合だけ判定不能を使用する。 テンプレートのサマリ表では、進行中は「未着手・進行中」列に含めつつ備考や別行で明示し、 判定不能は専用列へ分離する。

  • 完了 (done) — 成果が出ており、再着手不要
  • 進行中 (in_progress) — 着手済みだが受け入れ条件を満たしきっていない
  • 未着手 (not_started) — いかなる着手痕跡も無い
  • 判定不能 (unknown) — 新形式の正本欠落・不正、またはID不整合により安全に分類できない

完了判定: 進捗正本と定義の整合性

新形式では、進捗状態を複数ファイルへ書かない。TODOは静的な定義、PROGRESS.md は状態と証跡の正本として扱う。 機械的な収集と整合性検証は scripts/scan_progress.py が行うので、まずこれを実行する。

| 情報 | ソース | 用途 | | --- | --- | --- | | 作業・受け入れ条件の定義 | todos/NNN-{task}/README.* | W-ID / AC-ID の集合と順序を確定 | | 全体進捗一覧 | progresses/README.md | 全タスクの状態を一覧確認し、個別正本との同期状態を検証 | | 進捗正本 | progresses/NNN-{task}/PROGRESS.md | 状態、W-ID参照、AC-IDごとの検証状態と根拠を確定 | | コミットログ | logs/NNN-{task}/commit-*.txt | 旧形式で正本が欠落・不正な場合だけ補助判定 | | ロードマップ | todos/README.*（存在すれば） | 依存・並行性・概要の補強。完了状態の根拠にはしない |

判定ルール（スクリプトが導出、モデルが最終確認）

  • 完了: 有効な PROGRESS.md が 完了、TODOの全 AC-ID が過不足なく存在し、すべて 充足
  • 未着手: 有効な PROGRESS.md が 未着手
  • 進行中: 進行中 / ブロック中、または 完了 とAC検証状態が矛盾する状態
  • 判定不能: 新形式の PROGRESS.md が欠落・不正、またはTODOとAC-IDが不一致。コミットログから完了を推定しない
  • 旧形式: 有効な PROGRESS.md を優先する。欠落・不正な場合だけ旧チェックボックスとコミットログを読み取り専用の補助情報として使い、必ず移行警告を付ける

一般ログや progresses/ の非標準ファイルは着手・完了の根拠にしない。スクリーンショットやレビュー結果の存在だけで進捗を変えないためである。

シグナル矛盾の扱い

「状態は完了だが未確認の AC-ID がある」「TODOとPROGRESSでIDが不一致」等の矛盾は、スクリプトが notes に記録する。 矛盾は握り潰さず、レポートの該当タスクの「備考」に明示し、必要ならユーザーに確認する。 勝手にどちらかへ寄せて確定させない（進捗の誤報告は後続の意思決定を誤らせるため）。

ワークフロー

Phase 1: 対象プロジェクトの特定

  1. ../_shared/references/task-management-contract.md を読み、正本のスキーマと非標準ファイルの扱いを確認する。
  2. $ARGUMENTS でプロジェクトパス or todos/ のパスが指定されていればそれを使う。
  3. 未指定ならカレントディレクトリを起点に todos/ を探索する（スクリプトが自動探索する）。
  4. 候補が複数 or 見つからない場合は推奨案を含む複数の選択肢を提示してユーザーに確認する。

Phase 2: 進捗シグナルの収集（スクリプト実行）

最初に集約ビューを読み取り専用で検証する。--check を外すとファイルを変更するため、このスキルでは必ず付ける。

python3 ~/.claude/skills/_shared/scripts/sync_progress_index.py "{プロジェクトパス or todos/ のパス}" --check

終了コード1なら progresses/README.md の欠落または同期ずれとして記録し、個別 PROGRESS.md を正本として以降の判定を続ける。このスキルは読み取り専用なので修復しない。

python3 scripts/scan_progress.py "{プロジェクトパス or todos/ のパス}"
  • 出力は JSON。各タスクの番号帯（main=0xx / handover=1xx）・frontmatter・定義形式・W-ID/AC-ID・ PROGRESS.md の有無/形式/宣言状態/AC検証・非標準ファイル・旧形式の補助情報・暫定ステータス・未充足依存・着手可能フラグ・全体サマリを含む。
  • error が返ったら（todos/ 不在など）、パスを見直すかユーザーに確認する。
  • needs_manual_review: true のタスク（HTML形式・README欠落など）は、該当ファイルを直接読み込んで 状態を補完する。HTMLプロジェクトは frontmatter が <script type="application/x-task-meta"> に、 進捗が本文に埋まっているため、必要箇所を読んで判断する。該当タスクが多数にのぼる場合は、この読み取りをサブエージェントに委譲し、補完済みの状態一覧だけをメインに戻させるとよい。

Why スクリプト: プロジェクト全体（数十タスク）を走査するため、全 README をメインコンテキストへ 読み込むと逼迫する。機械的に集約できるシグナルはスクリプトに任せ、本体は判断・要約・グルーピングに集中する。

Phase 3: PROGRESS.md とロードマップの突き合わせ（補強）

progresses/README.md と progresses/NNN-{task}/PROGRESS.md の状態・最終更新を突き合わせる。続いて個別正本の完了作業・残作業・ブロッカー・AC検証・成果を読み、暫定ステータスを確認する。一覧の欠落・同期ずれ、TODOとのID不一致、必須形式の欠落、progresses/ 内の非標準ファイルは備考に残す。非標準ファイルは内容を読まず、進捗判定にも使わない。

roadmap_file（todos/README.md）が存在する場合は読み、以下を補強材料にする。

  • タスクの内容概要・依存DAG・並行グループ・クリティカルパス
  • ロードマップに旧形式の完了マークが残っていれば、状態根拠には使わず移行対象として備考に明示

ロードマップが無くても、各タスク README の「概要」を必要に応じて読み込んで概要を補う。タスク数が多いプロジェクトでは、この読み取りをサブエージェントに委譲し、概要一覧だけをメインに戻させるとよい。タスク数が少ない場合は委譲せず直接読んでよい。

Phase 4: 未着手タスクの分類と推奨順序の設計

レポートの中核。スクリプト出力をもとにモデルが判断する。

  1. 内容単位のグルーピング: 未着手（進行中含む）タスクを「似た作業・同じ領域」でまとめ、 ### 🟢/🟡/🔴 Gn: {グループ概要} のセクションにする。
  2. 着手容易性マークの付与:
    • 🟢 容易: 未充足依存なし（ready_to_start: true）・工数小・編集ファイルが独立・調整不要
    • 🟡 中: 一部依存待ち or 中規模工数 or 軽い調整が必要
    • 🔴 難解: 未充足依存が多い（blocked）・大規模 or 要設計判断・他タスクと干渉
    • 判断材料: estimated_time / depends_on の充足状況 / parallel_group / priority / 対象ファイル
  3. 推奨対応順序: 依存と着手容易性から Phase A/B/C… を設計する。
    • Phase A は「即着手・並列で消化できる独立タスク群」（ready_to_start かつ非干渉）
    • 後続 Phase は依存解消後に着手するタスク
    • 並行可能なら、task-starter のロードマップに準じて並列実行を推奨してよい

Phase 5: レポート生成

必ず references/template-and-example.md を読み、その構成・テーブル形式・コメントの意図に沿って出力する。 テンプレートのプレースホルダ（T-xx, Gn, Phase A 等）は、対象プロジェクトの実際のタスクID （001-setup 等）と実データに置き換える。テンプレートとの対応は次の通り。

| テンプレートの呼称 | このプロジェクトでの実体 | | --- | --- | | メインタスク (T-xx〜T-yy) | 0xx 番台タスク（band=main） | | 申し送り事項 (T-100番台) | 1xx 番台タスク（band=handover） | | 🟢/🟡/🔴 Gn | Phase 4 でグルーピングした未着手タスク群 | | Phase A/B/C | Phase 4 で設計した推奨対応順序 |

レポートに必ず含める要素（テンプレート準拠）:

  1. 現状サマリ — 完了/未着手・進行中/判定不能の集計表（メイン・申し送りで分割、合計）＋メイン残の概要＋前提条件。 進行中タスクがあれば未着手側に含めつつ件数を明示。判定不能は未着手へ混ぜず、別件数と理由を示す。
  2. 未着手タスク 分類マトリクス — 🟢🟡🔴 グループごとのタスク表（# / 概要 / 工数 / 依存 / 備考）。 シグナル矛盾・手動確認要のタスクは備考に明記。
  3. 推奨対応順序 — Phase A/B/C…。各 Phase に短い解説と着手順序。
  4. 次の一手の提案 — 直近で着手すべき最有力タスクと理由。
  5. 補足: 完了済みタスク一覧 — メイン完了・申し送り完了の件数とID羅列。

タイトルの日付は会話で既知の現在日付を使う（YYYY-mm-dd）。

Phase 6: 出力先の確認

既定ではレポートを会話内に出力する。ユーザーがファイル保存を希望する場合のみ、 保存先を推奨案を含む複数の選択肢の提示で確認して書き出す（既定の保存はしない＝最小限の変更）。

Degrees of Freedom

  • シグナル収集: Low — scripts/scan_progress.py を必ず実行し、機械判定可能な部分は手作業で代替しない
  • ステータス確定: Low — 判定ルールに従う。矛盾は備考で明示し、勝手に寄せない
  • グルーピング・難易度マーク・推奨順序: High — プロジェクト特性に応じてモデルが判断する
  • レポート体裁: Low — references/template-and-example.md の構成・テーブル形式を厳守する
  • タスクファイルの編集: 禁止 — このスキルは読み取り専用。進捗の書き換えは task-performer の領域

エラーハンドリング

| 状況 | 対応 | | --- | --- | | todos/ が見つからない | スクリプトが error を返す。パスを見直し、不明なら選択肢提示で確認 | | タスクが0件 | 「対象プロジェクトに 0xx/1xx タスクが無い」旨を報告し、パス誤りの可能性を提示 | | needs_manual_review タスクあり | 該当 README を直接読み込んで補完。HTML形式は本文・task-meta を読む | | 新形式の PROGRESS.md が欠落・不正 | 警告を備考へ記載し、完了とは推定せず判定不能として扱う | | progresses/README.md が欠落・同期ずれ | 個別 PROGRESS.md を正本として判定を続け、一覧の修復が必要と備考へ記載。読み取り専用のため自動修復しない | | 旧形式の PROGRESS.md が欠落・不正 | 警告を備考へ記載し、旧チェックボックスとコミットログによる補助判定および移行必要性を明示 | | TODOと AC-ID が不一致 | 欠落・重複・未知IDを備考へ記載し、完了とは判定しない | | progresses/ に非標準ファイルあり | 内容を読まずファイル名を備考へ記載し、logs/ への手動移動を案内 | | シグナル矛盾 | 握り潰さず備考に明示。判断に影響するなら選択肢提示で確認 | | ロードマップ未存在 | Phase 3 をスキップし、各タスク README の概要で補う | | Python 3 未導入 | 各タスク README・PROGRESS.md・コミットログをファイル名検索・内容検索で手動走査する代替手順に切り替え。一般ログと非標準ファイルは判定から除外する。タスク数が多い場合はこの走査をサブエージェントに委譲し、集約済みの進捗シグナルだけをメインに戻させる |

前提条件

  • 対象が task-starter で生成された構造（todos/NNN-{task}/README.* と任意の progresses/・logs/）であること
  • Python 3.x（scripts/scan_progress.py の実行に必要。未導入時は手動走査に切替）

リソース

scripts/

  • scripts/scan_progress.py — todos/ を走査し各タスクの進捗シグナルと暫定ステータスをJSON出力（Phase 2で毎回実行）
  • ../_shared/scripts/sync_progress_index.py — Phase 2で --check 付きで実行する整合性検証スクリプト。このスキルからは書き込みモードで実行しない

references/

  • references/template-and-example.md — レポートの出力テンプレートと記載例（Phase 5で必ず参照）
  • ../_shared/references/task-management-contract.md — Phase 1で毎回参照する共有保存契約。PROGRESS.md の固定スキーマと logs/ への振り分けを定義