agent-readiness

agent-readiness

リポジトリが自律エージェントによる作業にどれだけ対応できるかを評価します（factory.ai のエージェント対応度評価に準拠、pylot-native）。リポジトリを読み取り専用でクローンし、8 つの側面を採点したうえで、評価対象のリポジトリにスコアと優先順位付きの改善チェックリストを記載した 🤖 Agent Readiness Report issue を 1 件登録します。冪等性があり、再実行時は重複した issue を作成せず、既存のレポート issue を更新します。

npx でインストール：

npx skills add fellowship-dev/dogfooded-skills/skills/ops/agent-readiness

使用する場面

• pylot に新しいリポジトリ／組織をオンボーディングする際 — ミッションを割り当てる前に、修正すべき点を把握します
• デモ：エージェントがコードベースに必要とするものを、改善項目リストとともに見込み顧客に具体的に示します
• アクティブなリポジトリの四半期ごとの再評価（コードベースの進化に伴い、対応状況も変化します）

入力

• $1 — 評価対象の org/repo（必須）
• $2 — pylot チーム名（任意。指定すると、ゲートウェイ経由で Pylot 接続状況の側面を確認します）

手順

0. アクセスとクローン

認証情報は環境から取得します（個人用 PAT は決して要求しません）。ポッドの git-credential-pylot ヘルパーが、Git 操作ごとに有効期間の短い App インストールトークンを発行します。通常の https URL でクローンしてください。認証情報を URL に直接埋め込むと、ヘルパーが使われません。

git clone --depth 50 "https://github.com/${REPO}.git" /tmp/assess-repo

シャロークローン（深さ 50）で十分です。必要なのはツリーと最近の履歴であり、過去をさかのぼって調査する必要はありません。

1. 8 つの側面を採点する

以下の機械的チェックを使って各項目を 0～10 で採点し、その後、判断に基づいて ±2 点を調整します（調整した場合はレポートで理由を説明してください）。捏造しないでください。すべてのスコアに、その根拠となったファイルやコマンドを記載してください。チェックを実行できない場合は、その旨を記し、保守的に採点してください。

#	側面	機械的チェック（証拠を添えて各項目を ✓／✗ で判定）
1	環境の再現性	.devcontainer/ または Dockerfile があるか、ロックファイルがあるか（package-lock/poetry.lock/Gemfile.lock/go.sum）、ランタイムが固定されているか（.nvmrc、.tool-versions、engines）、ヘッドレス環境でインストールコマンドが成功するか（npm ci／pip install -r など。実際に実行し、予算は 10 分）
2	テストの信頼性	テスト用ディレクトリ／ファイルがあるか、テストコマンドを確認できるか（package.json のスクリプト、Makefile、CI yml）、ライブ認証情報なしでヘッドレスにテストを実行できるか（実際に実行し、予算は 10 分）、成功／失敗／不安定の件数
3	エージェント向けコンテキスト	CLAUDE.md または AGENTS.md があるか、README に概要と実行方法が記載されているか、アーキテクチャ／ドキュメント用ディレクトリがあるか、コメントの密度が誤解を招くものでないか
4	CI/CD	ワークフローファイルがあるか、最新実行のデフォルトブランチにおけるステータス（API 経由）、デフォルトブランチでブランチ保護が有効か
5	タスク対応状況	オープンな issue の件数、本文が 200 文字を超える issue の割合、ラベルがあるか、issue テンプレートがあるか
6	シークレットの衛生状態	.env.example または設定に関するドキュメントがあるか、.env／キーがコミットされていないか（明らかな認証情報を検索：-----BEGIN、AKIA、sk-、ハードコードされたパスワード）、シークレットの使用方法が文書化されているか
7	Pylot 接続状況（$2 にチームが指定された場合のみ）	リポジトリがチームの repos に含まれているか（GET /crew）、devbox_config が登録されているか、ワーカーイメージが存在するか、チームの目標が設定されているか、組織のスキル用ホームが存在するか — GET $PYLOT_GATEWAY_URL/git-token?repo=<org>/pylot-skills を確認し（<org>/skills も試す）、200 = 存在し App からアクセス可能、4xx = 存在しない。チーム引数がない場合は問題なくスキップし（n/a）、
8	コードの健全性クイックスキャン	lint／format 設定があるか、最大ファイルの LOC（>1500 は要注意）、TODO／FIXME の密度、依存関係の古さ（上位 10 件の依存関係のうち、メジャーバージョンがいくつ遅れているか）

2. 判定を算出する

• 総合スコア = 加重平均：環境 20%、テスト 25%、コンテキスト 15%、CI 10%、タスク 10%、シークレット 10%、接続状況 5%、健全性 5%。（チーム引数がない場合、接続状況の 5% はテストに再配分します。）
• ティア： 8.0 以上 READY · 6.0～7.9 NEARLY READY · 4.0～5.9 NEEDS WORK · 4.0 未満 NOT READY
• 優先修正項目： ROI が最も高い改善策を 3～7 件挙げ、それぞれに作業量（S/M/L）と改善できる側面を記載します。（スコアへの影響 ÷ 作業量）の順に並べてください。具体的に記載します。「環境を改善する」ではなく、「node:22 と postCreateCommand npm ci を指定して .devcontainer/devcontainer.json を追加する」のように記載してください。

3. レポート issue を登録する

タイトルが 🤖 Agent Readiness Report（完全一致）のオープンな issue を検索します。見つかった場合は本文を更新し、見つからなければ新規作成します。発行されたインストールトークンを使用してください。

本文テンプレート：

# 🤖 Agent Readiness Report — <org/repo>

**Overall: <score>/10 — <TIER>**  ·  assessed <date> · commit <sha7>

| Dimension | Score | Evidence |
|---|---|---|
| Environment reproducibility | x/10 | <one-line: what was found/run> |
| … all 8 rows … |

## Top fixes (highest ROI first)
- [ ] **<fix>** (effort S/M/L, unblocks <dimension>) — <one concrete instruction>
…

## What agents can already do here
<2-4 bullets of work types that are safe to dispatch TODAY given current scores>

## Org setup (include ONLY if the org skills home probe failed)
- [ ] **Create your org's private skills home** — repo `<org>/pylot-skills` (private, empty is fine), then install the pylot GitHub App on it. This is where org-specific agent skills live; without it your teams can only use the shared cross-org skills. *(An org admin must do this — pylot's App token cannot create repos by design.)*

## Details
<per-dimension: checks run, outputs, and why the score>

---
_Generated by [pylot](https://pylot.fellowship.dev) `/agent-readiness`. Re-run to refresh._

4. 報告

ミッションレポート（スコア、ティア、課題の URL、優先度の高い修正点）を記載します。リポジトリごとの判定は1行で記載します。オーナーが読むのはスコアであり、記録ではありません。

ガードレール

• リポジトリは読み取り専用です：プッシュ、プルリクエストの作成、コードの変更は一切行わないでください。唯一の書き込みは、レポート用の課題への投稿です。
• 発行したトークンをログやレポートに出力しないでください。
• インストールやテストは、ネットワーク接続を許可したうえで、/tmp にあるクローン内で実行してください。各実行の制限時間は10分です。超過した場合は、証拠として timeout を記録して次に進んでください。
• クローン自体に失敗した場合は、課題を作成せず、ゲートウェイエラーとしてミッションを失敗させてください。