AGENTS.md

このファイルは AI エージェント向けの共通 instructions です。

基本方針

• 日本語で応答する
• 推奨案とその理由を提示する
• .env ファイルは読み取り・ステージングしない
• 破壊的な Git 操作を避ける

プロジェクト概要

gh-tasks: GitHub Projects v2 / Issues / Milestone を横断するタスク管理 CLI(gh tasks extension)+ skill bundle。3 スコープ(repo / org / user)を統一抽象でカバーし、4 エージェント(Claude Code / Codex CLI / Gemini CLI / GitHub Copilot)向け skill を adapter 機構経由で配布する。

Tech Stack

• Language / runtime: Go 1.25 + toolchain go1.26.0(repo-internal ADR-0006)
• CLI framework: spf13/cobra
• GitHub API: cli/go-gh/v2 (auth + GraphQL + REST、repo-internal ADR-0007)
• GraphQL types: internal/github/queries/operations.graphql を SSOT として Khan/genqlient で型自動生成(go.mod の tool ディレクティブで管理、internal/github/queries/genqlient.go が生成物、repo-internal ADR-0007)。REST 用ハンドコード型は rest_types.go のみ
• Binary build / release: cli/gh-extension-precompile@v2(SLSA attestations、manifest.yml 自動生成)
• Linting / formatting: golangci-lint v2(gofumpt + goimports + gci)、yamllint + yamlfmt、markdownlint-cli2、shellcheck + shfmt
• Vulnerability scan: govulncheck(text + SARIF を Code Scanning に出力)
• Git hooks: lefthook(commit-msg: commitlint、pre-commit: linters + gh tasks check-i18n (本体 + --refs)、pre-push: go test + branch 名チェック)
• Testing: 標準 testing + google/go-cmp、go test -race -shuffle=on を CI 必須(repo-internal ADR-0008)

移行履歴: 2026-04 までは Bun --compile + TypeScript で実装(ADR-0001 / 0003)。2026-05 から Go へ完全移行(計画書: docs/design/go-migration-plan.md、後継 ADR-0006 / 0007 / 0008)。

ディレクトリ構成

main.go                 → cobra root エントリ(リポルート、gh extension 慣習)
cmd/                    → cobra コマンド定義(add/list/today/done/standup/
                         review/plan/triage/link/projects、build-skills /
                         check-i18n は Hidden)
internal/               → ドメインロジック
  ├── github/           → cli/go-gh ラッパ(GraphQL + REST)
  │   └── queries/      → `operations.graphql`(SSOT)+ genqlient 自動生成型 + REST 用ハンドコード型(`rest_types.go`)
  ├── i18n/             → embed 済 en/ja JSON catalog + ResolveLocale + T
  ├── i18ncheck/        → ハードコード非 ASCII 検知 (gh tasks check-i18n)
  ├── scope/ repo/      → 3-scope (repo/org/user) 抽象 + リポ解決
  ├── project/ projectitem/ period/ config/ → ドメイン helpers
  ├── skills/           → SKILL.md frontmatter parse + Load
  ├── adapters/         → 4 エージェント向け OutputFile 生成
  └── testfake/         → GraphQL テスト用 fake (cmd/internal 共通、REST は cmd-only)
skills/             → skill SSOT(SKILL.md = ja、SKILL.en.md = en)
dist/{adapter}/         → adapter 出力(`gh tasks build-skills` で生成)
docs/manual/{en,ja}/    → ユーザーマニュアル(en SSOT、ja mirror)
docs/adr/               → repo-internal ADR(ja 単一)
docs/design/            → repo-internal な living 設計ドキュメント(ja 単一)
.agents/ ・ .claude/    → commons + skills sync 配置先

主要コマンド

mise install                          # toolchain (go / golangci-lint / govulncheck 等)
go build ./...                        # CLI バイナリ
go run . build-skills                 # adapter pipeline 実行(dist/{adapter}/ 生成)
go run . check-i18n                   # ハードコード非 ASCII 検知
go test -race -shuffle=on ./...       # テスト
golangci-lint run --timeout 5m ./...  # lint v2
govulncheck ./...                     # 脆弱性スキャン
yamllint . && yamlfmt . && markdownlint-cli2 '**/*.md'   # 共有 lint

i18n SSOT

読み手ベース SSOT(repo-internal ADR-0005、ADR-0002 を Superseded):

• README: README.md(en SSOT)+ README.ja.md(ja mirror)
• ユーザーマニュアル: docs/manual/en/(en SSOT)+ docs/manual/ja/(ja mirror、新規コンテンツは en 先行で ja 追従)
• SKILL.md: SKILL.md(ja SSOT)+ SKILL.en.md(en mirror)
• ADR(docs/adr/): ja のみ(repo-internal な意思決定記録、翻訳しない)
• 設計ドキュメント(docs/design/): ja のみ(living な設計メモ、翻訳しない)
• CLI 出力 / エラー(internal/i18n/): en SSOT + ja translation(新規キーは en に書き、ja を追従させる)
• AGENTS.md / CLAUDE.md: ja のみ

ハードコード文字列禁止: 非 ASCII を含むリテラルは i18n.T(locale, "key", args...) 経由必須(internal/i18n/{en,ja}.json に定義)。gh tasks check-i18n(internal/i18ncheck、go/parser ベース)が pre-commit / CI で強制。エラー型は i18n.Payload を埋め込んで i18n.Localized インタフェースを満たし、上位 (cmd/list.go 等の localizedError) で resolve した locale を使い localize する(例: scope.ScopeError、repo.RepoError、project.ProjectError、period.PeriodError、config.ConfigError、github.AuthError)。

規約

• コミット: Conventional Commits(commitlint で強制)
• ブランチ: GitHub Flow + squash merge のみ、<type>/<short-description>
• type: feat / fix / docs / style / refactor / perf / test / build / ci / chore / revert

Available Skills

• commit — 変更をステージし、Conventional Commits でコミットする。プッシュや PR 作成は行わない。
• commit-conventions — Conventional Commits のメッセージ生成ルール（Type/Scope 判定表、フォーマット）。他スキルから参照される。
• drive — Issue または指示から実装・PR 作成・セルフレビュー・修正を自動で回し、merge-ready な PR を出す。単一/複数の Issue/PR と明示依存記法に対応。オプションでマージまで実行可能。
• health — リポジトリ改修中に意図せず残る状態（working tree, stash, branch, worktree, PR, issue, actions など）と skill catalog 整合性を一発で確認し、16 領域のステータス表で俯瞰しつつ各項目に固定語彙の推奨アクションを inline で付与して報告する。--deep 指定時は 要確認 項目を read-only コマンドで追加調査し、機械判定可能な範囲でラベルを格上げする。検査と提示のみで、削除・close 等の実行は行わない。
• implement — Issue または指示をもとに、ブランチ作成・実装計画・コード変更を行う。Issue 番号またはテキスト指示を受け取る。
• lint — 全リンターを自動修正付きで実行し、結果を報告する。コード品質チェック、フォーマット、型チェック、セキュリティスキャンを含む。
• lint-rules — 拡張子別リンター・フォーマッターのコマンド対応表と型チェックルール。他スキルから参照される。
• phase-issue — Phase-N tracking issue を生成する。cross-session handoff context、決定事項表、PR ごとのタスク、DoD、Phase N+1 outlook を含む構造化された issue body を組み立てて gh issue create で起票する。引数で全項目を渡す非対話モードと、不足分を補う対話モード（Claude Code companion）に対応する。
• pr — コミット済みの変更をリモートにプッシュし、PR を作成・更新する。
• review — コード変更や PR を 11 観点（perspectives）でレビューし、JSON 構造化出力 + 人間可読レポートで報告する。quick / deep モードを切替可能。PR 番号またはワーキングツリー差分を入力に取る。
• ship — lint・コミット・PR 作成を一括実行する。変更に対して lint → コミット → PR 作成を順に実行する統合パイプライン。
• sync-consumers — skills / commons の更新を sync-targets.yaml に記載された 14 consumer リポへ並列に push し、PR auto-merge まで完結させる。drive の Phase Final 仕様（worktree drift 検出 + cleanup）を踏襲する push 型同期スキル。
• test — ビルド・テスト・型チェックを実行し、結果を報告する。
• topics — GitHub topics 候補を制約検証・人気度測定・broad+narrow / 単数複数比較・ozzy-labs 慣行ハードコードで選定し、gh repo edit --add-topic で適用する。スコープは ozzy-labs 内利用のみ。

gh-tasks Skills

• task-add — 会話文脈からタスクを追加する。scope に応じて GitHub Issue (repo) または Project draft item (org/user) を作成し、gh tasks add を呼び出す。
• task-link-pr — PR を Issue / Project 項目と紐付ける。gh tasks link <pr> <task> を呼び出し、repo scope は PR body に Closes #N を追記、org/user scope は PR と Issue を同じ Project v2 に bind する。
• task-plan — 日次 / 週次 / イテレーション計画を実行する。gh tasks plan を呼び出して該当 scope の Milestone (repo) または Iteration (org/user) で計画項目を整理する。
• task-review — 振り返りサマリを生成する。gh tasks review --period daily|weekly|sprint を呼び出して期間内の Issue close / PR merge / Project アイテムの完了を要約する。
• task-standup — 直近活動のスタンドアップ用サマリを生成する。gh tasks standup [--mine] を呼び出してチーム / 個人の動きを共有可能な形に整形する。
• task-triage — 未トリアージの Issue / Project draft item を整理する。gh tasks triage を呼び出してラベル付け、scope 振り分け、close 判断を補助する。

Adapter Files

skill の consumer リポへの配信経路は 2 つあり、どちらも同じ on-disk layout と marker tag を target にする(相互運用可能):

1. gh tasks install-skills(ワンショット、推奨) — embed 済 SSOT から直接 consumer リポへ書き込み、adapter ごとの manifest で provenance を記録。auto-detect / --namespace rename / --force 上書き(<path>.bak 退避) / --uninstall(reference count 付き)に対応。internal/install/ 実装、cmd は cmd/install_skills.go
2. gh tasks build-skills → dist/{adapter}/ → Renovate sync — cmd/build_skills.go(Hidden)で dist/ を再生成し、consumer リポは configs/skills-sync/<adapter> Renovate preset を extends して PR 経由で取り込む。auto-update 派向け

両経路で共通の配置先:

Shared (consumer-owned aggregator) ファイルは marker block (<!-- begin: @ozzylabs/gh-tasks --> ～ <!-- end: @ozzylabs/gh-tasks -->) または特定の JSON キーのみ gh-tasks 所有で、それ以外のコンテンツは byte-for-byte 保護される(idempotent)。AGENTS.md は codex-cli と gemini-cli が共有する単一 marker block で、--uninstall は他 adapter の manifest を見て reference count する。