korylus-tools

日本語 | English

Korylusプロジェクトで共通利用する開発ツールを集約したリポジトリです。

koryluslint

koryluslint はKorylus共通のリンタをまとめた単一バイナリです。 サブコマンドで各リンタを呼び分けます。

サブコマンド	役割
comment	ソースコードの日本語テキストスタイル (korylus-lang.md §3) を検査する
md	Markdownドキュメントの句点改行 (semantic line break) と日本語テキストスタイル (korylus-lang.md §3) を検査する

使い方

koryluslint comment [-base=<ref>] [paths...]
koryluslint md [-base=<ref>] [--all] [--write] [paths...]

-base=<ref> を渡すと、<ref> 以降に追加された行だけを検査します (差分スコープ)。

comment が見る範囲は形式ごとに違います。

形式	検査対象
.go	コメント
.templ	行頭 // のコメント
.sh	Bashの構文解析で抽出したコメント・引数などの文字列・ヒアドキュメントの本文
.ts	TypeScriptの構文解析で抽出したコメント・文字列の本文 (テンプレートリテラルを含む)
.sql / .css / .toml	日本語を含む行

コメント以外の日本語も検査するのは、i18nの訳文やシェルが出力するメッセージも§3の対象だからです。 シェルのコマンド名・オプション・展開式や、TypeScriptの補間式の演算子などは本文に含めません。 引用符で囲まないシェルの引数どうしの区切りは、出力される文面のスペースとして検査します。 .sh / .ts では、コメント内のMarkdownインラインコードは除外しますが、文字列内のバッククォートは本文として検査します。 .sql / .css / .toml は行全体をMarkdownとして扱うため、バッククォートで囲まれた範囲は文字列の中でも除外されます。 シェル・TypeScriptの構文解析に失敗したファイルは、標準エラー出力に通知してスキップします。

日本語を含まない行は検査しません。 生成物の除外は_templ.goと、先頭20行以内に// Code generated ... DO NOT EDIT.の定型ヘッダーを持つファイルが対象です。 それ以外の生成物や、SQL・CSS・TOMLのコード中に日本語がある場合は、行単位の検査に含まれます。

.go の文字列リテラルは検査しません。 描画結果と突き合わせるテストのリテラルは、テンプレートの出力に合わせて §3に反する形を意図して持つためです。

md では、--all は差分行だけでなく全 .md ファイルを全行検査し、--write は句点改行をその場で修正します。 日本語テキストスタイルの違反は書き換え後の行番号で報告し、違反が残る場合は終了コード1を返します。

korylusflow

korylusflow は、作業計画書のタスクを役割ごとの対話セッションで進めるときに、番と次の指示を決めて状態を記録するCLIです。 実装者・レビュアー (Codex)・レビュアー (Claude Code) のセッションは、それぞれ自分の番を korylusflow に尋ね、返ってきた指示どおりに作業してから完了を記録します。 次に何をするかは korylusflow が決め、エージェントには決めさせません。 korylusflow 自身はClaude Code / Codexを起動しません。

使い方

korylusflow wait <計画書のパス> -role=<役割> [-timeout=<時間>]
korylusflow done <計画書のパス> -role=<役割>
korylusflow status <計画書のパス>
korylusflow report <計画書のパス>

どのサブコマンドもプロジェクトのルートで実行し、計画書のパスはルートからの相対パスで指定します。 役割は implementer (実装者)・reviewer-codex (レビュアー (Codex))・reviewer-claude (レビュアー (Claude Code)) のいずれかです。

サブコマンド	役割
wait	役割の番が来るまで待ち、次の指示を標準出力に書く。-timeout を過ぎても番が来なければ action: wait を返す
done	進めているステップの完了を確かめて記録し、次のステップを決める。実装のステップでは、動作確認の項目を標準入力からJSONの配列で受け取る
status	計画書の進行状況と、現在のタスク・ステップ・番の役割・人を待っている理由・所要時間を表示する
report	作業報告書の最新の版を作り直す。最新の版のあとに記録したステップがあれば、次の版を作る

指示の先頭行は action: <種類> (implement・review・fix・ask・finish・wait) です。 続けて、実行するスキルと引数、終わったあとの手順を毎回すべて書きます。 コンテキストが圧縮されたあとでも、直近の指示だけで続けられるようにするためです。

done の終了コードは次のとおりです。

終了コード	意味
0	完了を記録した
1	エラー
2	完了の条件を満たさず、記録を受け付けなかった (理由を読んで直せばやり直せる)

1タスクの流れ

1. タスクの接頭辞からリポジトリを求め、ブランチ <計画書名>-<タスク番号> を、同じリポジトリの前のタスクのブランチ (最初のタスクはdevelop、無ければmain) から作る
2. 実装者が /korylus-do-plan-task で実装し、コミットする
3. レビュアーが /korylus-review でレビューする。1回目はCodex、2回目以降は前回と別の役割が行う
4. korylusflow がレビュードキュメントの自動対応可の指摘に推奨の選択肢で回答し、レビュアーが修正してコミットする
5. Request Changesなら3へ戻り (上限3回)、Comment / Approveなら次のタスクへ進む

人が行うタスク・要人間判断の指摘・レビューの上限に当たったときは、そのときのセッションに人へ尋ねるよう指示します。

タスクの接頭辞は次のとおりに読みます。

接頭辞	作業するディレクトリ
[/workspace/go] など / で始まるもの	そのパス
[Go]・[Rails]・接頭辞無し	/workspace/go・/workspace/rails・/workspace として読む
それ以外 (作業する人の名前)	なし (人が行うタスク)

作業報告書

計画書の最後まで進むと、状態・所要時間の記録・計画書・gitから、Markdownの作業報告書 report-<版>.md を組み立てます。 LLMに文章を書かせず、記録にある事実だけを並べます。

• 概要 (計画書・期間・リポジトリごとのブランチの順序)
• タスクごとの変更 (ブランチ・コミット・変更ファイルと行数・想定行数・レビューの結果・実装判断ログの論点)
• 先送りした指摘と、人を待った履歴
• 所要時間 (役割・ステップごとの合計と、タスクごとの内訳)
• 保護領域 (宣言の内容と、差分を見るコマンド)
• 動作確認チェックリストと、全体へのコメント欄

人はチェックリストの項目ごとにOKかNGにチェックを付け、コメントを書きます。 計画書にタスクを足してループを再び回すと、計画書の最後で次の版を作ります。 次の版では、前の版でNGだった項目と新しい項目を先に並べ、前の版までにOKになった項目は確認済みとして一覧だけを載せます。 report で同じ版を作り直したときも、書き込まれた結果は引き継ぎます。 閉じていないコードブロックなどで書き込みが作業報告書の区切りを隠しているときは、作り直さずに直す箇所を示します。

状態と作業報告書の置き場所

状態と作業報告書は、計画書と一緒に履歴として残すため docs/private/plans/files/<計画書名>/ に置きます。

ファイル	内容
flow.json	現在のタスク・ステップ・番の役割と、タスクごとの記録
flow.lock	ファイルロック用の空のファイル
timeline.jsonl	ステップごとの開始と終了の時刻
report-<版>.md	作業報告書

インストール

make install-korylusflow でビルドし、~/.local/bin/korylusflow に置きます (BINDIR=<ディレクトリ> で置き場所を変えられます)。 ループの途中でブランチを切り替えても実行中のコードが変わらないよう、作業ツリーから go run で実行せず、ビルドした実行ファイルを使います。

koryluspilot

koryluspilot は、作業計画書1本のタスクを最後まで自動で進めるオーケストレーターです。 タスクごとに、役割ごとのコンテナで実装・コミット・ゲート検査・レビュー・回答・修正を行い、計画書の最後で作業報告書 (HTML) を作ります。 人間が介入するのは、合意した方針から外れる変更を検知して止まったときと、作業報告書での動作確認に限ります。

次に何をするかはkoryluspilotだけが決め、エージェントに次の役割を呼ばせません。 役割のコンテナには秘密情報を渡さないため、エージェントはpushできません。 pushとPRの作成は、作業報告書に載るブランチの順序をもとに人間が行います。

使い方

koryluspilot run <計画書のパス> [-note=<補足>] [-approve] [-config=<設定ファイル>]
koryluspilot report <計画書のパス> [-addr=<待ち受けるアドレス>]
koryluspilot status <計画書のパス>
koryluspilot usage [-config=<設定ファイル>]

どのサブコマンドもプロジェクトのルート (人間のチェックアウト) で実行し、計画書のパスはルートからの相対パスで指定します。

サブコマンド	役割
run	計画書の未完了のタスクを先頭から順に進め、最後に作業報告書を作る。動作確認の結果を読み、フィードバックのループを回す
report	最新の版の作業報告書を /_koryluspilot/ で配信し、ブラウザで付けた動作確認の結果を保存する
status	計画書の進行状況・実行中のステップ・止まった理由を表示する
usage	Claude Code / Codexの使用率と、上限に達する見込みを表示する

run の終了コードは次のとおりです。

終了コード	意味
0	作業報告書の確認待ちになったか、計画書を確認済みとして終えた
1	エラー
2	停止条件で止まった

計画書から読むもの

タスクは計画書の「タスクリスト」節に - [ ] **<タスク番号>**: [<プラットフォーム>] <タスク名> の形で書きます。 koryluspilotは、タスクの下の次の行も読みます。

• **保護領域**: そのタスクで触れてよい保護領域 (設定ファイルで定義した名前)
• **想定行数**: ゲート検査で実装の行数と比べる基準
• **対応する確認項目**: フィードバック対応のタスクが対応する作業報告書の項目 (第N版 #M)

1回の実行の流れ

1. 最初のタスクを始めるときに、設定の base_branch をGitHubから認証なしで取り込み、<計画書名>-base として固定する
2. タスクごとにブランチ <計画書名>-<タスク番号> を前のタスクのブランチから切り、実装者に /korylus-do-plan-task を無人実行モードで実行させる
3. 実装者にコミットさせ、ハブへ取り込んでゲート検査を行う
4. レビュアーに /korylus-review でレビューさせ、推奨どおりに回答して修正させる。Request Changesなら別の役割で再レビューする
5. 計画書の最後で、ハブのブランチを人間のチェックアウトへ取り込み、作業報告書を作る

各エージェントの起動前には使用率を確かめ、上限を超えそうならリセットまで待ちます。

止まったときの再開

止まると、理由と解消に使う役割 (コンテナ) を表示し、終了コード2で終わります。 その役割のコンテナで原因を直し、次のコマンドで止まったステップから再開します。

koryluspilot run <計画書のパス> -note=<補足>

-note の補足は、再開したステップのエージェントに渡します。 計画書や設定ファイルを直したときは -approve を付け、現在の内容を新しい基準として受け入れます。

動作確認とフィードバックのループ

計画書の最後まで進んだら、次の手順で動作確認します。

1. koryluspilot report <計画書のパス> で作業報告書を配信し、devサイトの /_koryluspilot/ を開く
2. チェックリストの項目ごとにOK / NGとコメントを付け、必要なら全体へのコメントを書いて保存する
3. もう一度 koryluspilot run <計画書のパス> を実行する

run は最新の版の確認結果で次のように分岐します。

確認結果	次の動き
未確認の項目が残っている	確認を促して終える
すべてOKで、全体へのコメントも無い	計画書を確認済みとして終える
NGの項目か全体へのコメントがある	設計者に /korylus-add-feedback-phase でフェーズfbNを起票させ、そのタスクを実行して作業報告書の次の版を作る

前の版までにOKになった項目は確認済みとして畳まれ、確かめ直さなくても未確認として扱いません。

起票のあと、計画書の変更がタスクリスト末尾へのフェーズfbNの追加だけかを確かめ、それ以外の変更があれば止めます。 追加されたタスクが保護領域を宣言しているときは、実行する前に止まります。 タスクの内容を確かめ、koryluspilot run <計画書のパス> -approve で承認すると実行します。

設定ファイル

プロジェクトのルートに koryluspilot.toml を置きます。 秘密情報は書きません。

項目	内容
project / base_branch	プロジェクト名 (ハブの置き場所に使う) と、最初のタスクを切る元のブランチ
max_reviews / reviewers	1タスクのレビュー回数の上限 (既定3) と、レビューに順に使う役割
[hub]	upstream (base_branch を取り込むURL) と path (コンテナの中から見たハブのパス)
[usage]	5時間枠・週枠の上限 (既定90%・80%)、安全係数 (既定1.5)、消費の見積もりの初期値
[roles.<役割>]	tool (claude / codex)・model・effort・fix_effort・sandbox・runner (コンテナで起動する接頭辞)。designer と implementer は必須
[report]	addr (待ち受けるアドレス。既定は 127.0.0.1:4190) と setup (作業報告書に載せる動作確認の前の準備のコマンド)
[gate]	runner・commands (プラットフォームごとのコマンド)・suppress_patterns・test_globs・generated_globs・size_factor・watch
[[protected]]	保護領域の name・label、検知方法 (paths・patterns・go_funcs_calling・go_import_prefix)、on_undeclared、review_points

状態と作業報告書の置き場所

パス	内容
tmp/koryluspilot/<計画書名>/	実行の状態・計画書と設定ファイルのスナップショット・ログ・所要時間の記録
docs/private/plans/files/<計画書名>/	作業報告書 (report-<版>.html / report-<版>.json) と動作確認の結果 (verification-<版>.json)
$XDG_DATA_HOME/koryluspilot/<project>/	ハブ (hub.git) と役割ごとのクローン (XDG_DATA_HOME が無ければ ~/.local/share)

取得・実行

ビルドには、Goに加えてCコンパイラ (GCCまたはClang) とCGO_ENABLED=1が必要です。 シェル・TypeScriptの構文解析にTree-sitterのGoバインディングを使っています。

各プロジェクトはバージョンを固定して koryluslint を取得します。

• Goプロジェクト: go.mod のtoolディレクティブで github.com/korylus/tools/cmd/koryluslint を固定し、go tool koryluslint ... で実行する
• 非Goプロジェクト: miseの go: バックエンドで固定取得する

koryluspilot はDockerを操作するため、コンテナの中ではなくDockerが動くホストで直接実行します。 go build -o bin/koryluspilot ./cmd/koryluspilot でビルドできます。

開発

make build       # koryluslintをビルド (bin/koryluslint)
make install-korylusflow  # korylusflowをビルド (~/.local/bin/korylusflow)
make test        # テストを実行
make vet         # go vetを実行
make lint        # golangci-lintを実行
make fmt         # gofmt + goimports + Oxfmtでフォーマット
make fmt-check   # フォーマットチェック