日本語 | English
Korylusプロジェクトで共通利用する開発ツールを集約したリポジトリです。
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 は、作業計画書のタスクを役割ごとの対話セッションで進めるときに、番と次の指示を決めて状態を記録するCLIです。
実装者・レビュアー (Codex)・レビュアー (Claude Code) のセッションは、それぞれ自分の番を korylusflow に尋ね、返ってきた指示どおりに作業してから完了を記録します。
次に何をするかは korylusflow が決め、エージェントには決めさせません。
korylusflow 自身はClaude Code / Codexを起動しません。
korylusflow wait <計画書> -role=<役割> [-timeout=<時間>]
korylusflow done <計画書> -role=<役割>
korylusflow status <計画書>
korylusflow report <計画書>どのサブコマンドもプロジェクトのルートで実行します。
計画書は、WikinoのページのURL (https://wikino.app/s/<スペース>/pages/<ページ番号>) で指定します。
パスやページ番号だけの指定は受け付けません (「計画書名とWikinoのページの計画書」)。
役割は implementer (実装者)・reviewer-codex (レビュアー (Codex))・reviewer-claude (レビュアー (Claude Code)) のいずれかです。
| サブコマンド | 役割 |
|---|---|
wait |
役割の番が来るまで待ち、次の指示を標準出力に書く。-timeout を過ぎても番が来なければ action: wait を返す |
done |
進めているステップの完了を確かめて記録し、次のステップを決める。実装のステップでは動作確認の項目を、作業報告書のステップではURLと処理の流れを書かなかった理由を、標準入力からJSONで受け取る |
status |
計画書の進行状況と、現在のタスク・ステップ・番の役割・人を待っている理由・所要時間を表示する |
report |
マージするPRなど、状態・計画書・gitから集めた事実を標準出力に書く。状態は書き換えない |
指示の先頭行は action: <種類> (implement・work・review・fix・ask・report・finish・wait) です。
続けて、実行するスキルと引数、終わったあとの手順を毎回すべて書きます。
コンテキストが圧縮されたあとでも、直近の指示だけで続けられるようにするためです。
done の終了コードは次のとおりです。
| 終了コード | 意味 |
|---|---|
| 0 | 完了を記録した |
| 1 | エラー |
| 2 | 完了の条件を満たさず、記録を受け付けなかった (理由を読んで直せばやり直せる) |
計画書名は、状態の置き場所・ブランチ名・korylusflow report の見出しに使う名前です。
計画書の最初の ## の見出しより前に、次の形の行で書きます。
値には英小文字・数字と、間に挟むハイフンだけを使います。
**計画書名**: feature-nameこの行は必須です。 ループの途中で計画書名を変えると、状態の置き場所が変わって続きから進められなくなります。
Wikinoのページの計画書は、Wikino CLI の wikino コマンドで、下書きがあれば下書きを、無ければページを読み
8000
す。
実装者が付けたチェックや実装判断ログは、公開するまで下書きにしか無いためです。
korylusflow はWikinoに書き込まないため、wikino auth login <スペース> でログインするトークンには読み取りの権限があれば足ります。
korylusflow は https://wikino.app のページを読むため、既定の接続先を変えている環境では --host=https://wikino.app を付けてログインします。
未ログインやレート制限で読めなかったときは、状態を書き換えずにエラーで終わります。
別の計画書のマージ前のブランチの上に積むときは、計画書の最初の ## の見出しより前に、リポジトリの最初のタスクのブランチを作る元のブランチを書きます。
値は <ディレクトリのパス>=<ブランチ名> を , で区切って並べます。
パスはタスクの接頭辞と同じく、リポジトリの中のディレクトリの絶対パスで、そのディレクトリを含むリポジトリのベースになります。
**ベースブランチ**: /workspace=prev-feature-1-3, /korylus-tools=prev-feature-1-2タスクのブランチを作る元のブランチは、次の順で決めます。 作業ツリーの現在のブランチは使いません。
- 同じリポジトリの前のタスクのブランチがローカルにあれば、そのブランチ
- ベースブランチの行にそのリポジトリのブランチがあれば、そのブランチ
- どちらも無ければ、develop、無ければmain
行のパスからリポジトリを求められないとき・同じリポジトリに別々のブランチを書いたとき・行に書いたブランチがローカルに無いときは、自動で進めず、実装者に人へ尋ねるよう指示します。
行の書式の誤り (= が無い・パスが / で始まらない・ブランチ名が空・同じパスや行の重複) は、計画書を読み取れないエラーになります。
ブランチを準備し終えたタスクのベースは、あとから行を直しても変わりません。
- タスクの接頭辞からリポジトリを求め、ブランチ
<計画書名>-<タスク番号>を作る。元のブランチは「ベースブランチ」の順で決める - 実装者が
/korylus-do-plan-taskで実装し、コミットする - レビュアーが
/korylus-reviewでレビューする。1回目はCodex、2回目以降は前回と別の役割が行う korylusflowがレビュードキュメントの自動対応可の指摘に推奨の選択肢で回答し、レビュアーが修正してコミットする- Request Changesなら3へ戻り (上限3回)、Comment / Approveなら次のタスクへ進む
人が行うタスク・要人間判断の指摘・レビューの上限に当たったときは、そのときのセッションに人へ尋ねるよう指示します。
計画書の最後まで進むと、実装者へWikinoの作業報告書を書くよう指示します (action: report)。
指示には、リポジトリごとの最後のタスクのブランチとその先頭のコミット、前の回で書いた作業報告書のURLを書きます。
実装者は /korylus-write-report で作業報告書を書き、URL ({"location":"<URL>"}) を done に渡します。
処理の流れを書かなかったときは、理由を添えます ({"location":"<URL>","walkthrough_skipped":"<理由>"})。
URLは https:// で始まるものにします。
korylusflow はURLと理由を記録するだけで、作業報告書の本文は読まず、Wikinoにも書き込みません。
処理の流れを書いたときは、続けて作業報告書をレビューします。
- レビュアーが
/korylus-review-doc <作業報告書のURL> prefix=<計画書名>-reportでレビューする。1回目はCodex、2回目以降は前回と別の役割が行う korylusflowがレビュードキュメントの自動対応可の指摘に推奨の選択肢で回答し、レビュアーが作業報告書の下書きを修正する。下書きはコミットしないため、修正の完了ではブランチとコミットを確かめない- Request Changesなら1へ戻り (上限3回)、Comment / Approveなら作業報告書のレビューを終える
要人間判断の指摘と上限の扱いは、タスクのレビューと同じです。
レビュードキュメントは回をまたいで同じ接頭辞 (<計画書名>-report) の連番で書き、前の回のレビューの修正検証の対象にします。
処理の流れを書かなかったときは、コードと照合する処理が無いため、レビューを飛ばします。
タスクの接頭辞は次のとおりに読みます。
| 接頭辞 | 作業するディレクトリ |
|---|---|
[/workspace/go] など / で始まるもの |
そのパス |
[Go]・[Rails]・接頭辞無し |
/workspace/go・/workspace/rails・/workspace として読む |
[implementer] |
なし (実装者がブランチを作らずに行うタスク) |
| それ以外 (作業する人の名前) | なし (人が行うタスク) |
[implementer] のタスクは、Wikinoの下書きの作成や、ブランチを作らずに直接コミットしているリポジトリの編集のように、実装者が行えてブランチとPRを作らない作業に使います。
ブランチを準備せず、レビューも挟まずに、実装者へ作業を指示します (action: work)。
実装者はコミットせず、取り返しのつかない操作の前には人の了承を得て、結果を人に示します。
人が結果を確かめて計画書のタスクにチェックを付けたら、完了にします。
タスクの下に **担当**: の行があるときは、接頭辞をブランチを作るリポジトリのパスとしてだけ読み、担当を行の値から読みます。
- [ ] **1-1**: [/workspace/go] マイグレーションを作る
- [ ] **1-2**: ヘルプページの下書きを作る
- **担当**: implementer
- [ ] **1-3**: ヘルプページの下書きを公開する
- **担当**: shimbaco| 担当の行 | 接頭辞 | タスクの対象 |
|---|---|---|
| 無し | 上の表のとおり | 上の表のとおり |
implementer |
パス | 実装者がそのリポジトリでブランチを作るタスク |
implementer |
無し | 実装者がブランチを作らずに行うタスク |
| それ以外 (人の名前) | パス・無し | 人が行うタスク |
| 有り | パス以外 | 人に尋ねる (接頭辞と担当の行が食い違っている) |
1つのタスクに担当の行が複数あるときと、値が空のときは、計画書を読み取れないエラーにします。
korylusflow status と korylusflow report では、担当の行があるタスクに担当を添えて示します (例: 1-2 ヘルプページの下書きを作る (担当: implementer))。
作業報告書は、実装者がWikinoのページに書く、処理の流れとフィードバックの節を持つドキュメントです。
人は作業報告書を読んでフィードバックを溜め、計画書にフィードバック対応のタスクを足してループを再び回します。
計画書の最後まで進むたびに、実装者が同じ作業報告書を更新し、korylusflow はその回のURLを記録します。
korylusflow report は、状態・所要時間の記録・計画書・gitから集めた事実を標準出力に書きます。
エージェントの説明を混ぜず、記録にある事実だけを並べます。
状態を書き換えないため、ループの途中でも実行できます。
- 概要 (計画書・計画書の開始・最新の回の作業報告書のURL・リポジトリごとにマージするPR)
- タスクごとの変更 (1タスク1行の表で、ブランチ・変更行数・想定行数・レビューの評価)
- 実装者がブランチを作らずに行ったタスク
- 先送りした指摘
- 保護領域 (宣言の内容と、差分を見るコマンド)
所要時間と人を待った時間は、korylusflow status で表示します。
korylusflow はpushとPRの作成・マージを行いません。
人が作業報告書を確かめてから、korylusflow report のマージするPRのとおりに、リポジトリごとに最後のタスクのブランチから最初のタスクの元のブランチへのPRを1つ作り、merge commitでマージします。
前のタスクのブランチが残っておらず、最初のベースから作り直したなどでブランチが1本に繋がっていないときは、繋がった並びごとにPRを示します。
「ベースブランチ」の行で、既定のベース (develop、無ければmain) と違うブランチの上に積んだときは、そのベースが既定のベースに取り込み済みかをローカルのブランチで確かめて示します。
| ベースの状態 | ベースの列 | 添える説明 |
|---|---|---|
| 既定のベースに取り込み済み | 既定のベース | 取り込み済みであること |
| まだ取り込まれていない | 積んだブランチ | 積んだブランチのPRを先にマージしてから、既定のベースへ出す |
| ローカルに無い | 積んだブランチ | 取り込み済みかを確かめられないこと |
Markdownの作業報告書 (report-<版>.md) を作っていたときの状態も、そのまま読めます。
それまでの版はページを持たない回として引き継ぎ、次に計画書の最後まで進んだときに作業報告書のページを新しく作ってもらいます。
すでに作った report-<版>.md は消しません。
状態は、計画書と一緒に履歴として残すため docs/private/plans/files/<計画書名>/ に置きます。
| ファイル | 内容 |
|---|---|
flow.json |
現在のタスク・ステップ・番の役割と、タスクごとの記録 |
flow.lock |
ファイルロック用の空のファイル |
timeline.jsonl |
ステップごとの開始と終了の時刻 |
make install-korylusflow でビルドし、~/.local/bin/korylusflow に置きます (BINDIR=<ディレクトリ> で置き場所を変えられます)。
ループの途中でブランチを切り替えても実行中のコードが変わらないよう、作業ツリーから go run で実行せず、ビルドした実行ファイルを使います。
ビルドには、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:バックエンドで固定取得する
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 # フォーマットチェック