| name | extend-clargo |
| description | clargo(このリポジトリのArgo Workflows向けVSCode拡張)を、新しい業務yamlに対応させるためのスキル。 ユーザーが実際のワークフローyamlを貼り付けて/ファイルで渡して「これに対応して」「これも色が付くようにして」 「このyamlでもホバー(説明)が出るようにして」「この書き方をサポートして」と言ったら必ず使うこと。 syntax/semanticハイライトの判定、色付け、キー説明辞書、kind判定、定義ジャンプ、変数フロー等を 横断的に見て、その yaml が正しく扱われるよう関係箇所をまとめて修正する。 最重要の制約: 渡された yaml は業務コードなので、その固有の内容(テンプレート名/イメージ/リポジトリ/ ドメイン用語など)を サンプル・テスト・コメント・辞書の例に一切残してはいけない。追加する場合は Argo Workflows 一般の概念に抽象化するか、全く無関係な例に置き換える。 |
extend-clargo: 新しい業務yamlにclargoを対応させる
このスキルの前提と目的
clargo は Argo Workflows の yaml を VSCode で「読みやすくする」拡張。公式の全機能サポートは目指さない。
作者が業務で実際に登場する yaml だけをサポートすれば良い、と割り切って開発している。
そのため運用は「業務で使っている yaml を渡す → clargo がそれをちゃんと扱えるように全体を直す」という形になる。
このスキルはその修正作業を、抜け漏れなく・正しいファイルに・業務コードを漏らさずに行うためのもの。
「ちゃんと扱える」とは具体的に:
- 意味のある値(定義名・参照・変数など)に色が付く（semantic highlight）
- キーにホバーすると説明が出る（辞書に載っている）
- ブロックの色バー・アウトライン・グラフが正しく構成される
- 定義ジャンプ・変数フローが機能する
- そもそも Argo ドキュメントとして認識される（kind 判定）
最重要ルール: 業務コードを絶対に持ち込まない
これが他の何よりも優先する制約。やりがちなミスなので毎回意識すること。
渡される yaml は基本的に業務のコード。だからその固有の内容を clargo の成果物に残してはいけない。
具体的に「残してはいけない」もの:
- テンプレート名・step/task 名（例: 業務の処理名そのもの）
- コンテナイメージ名・レジストリ・リポジトリ URL・内部ホスト名
- ドメイン固有の用語、チーム名、サービス名、パラメータ名
- 「〜の業務では」「渡された yaml では」といった、その案件を指す言及
これらを サンプル(samples/)・テスト(*.test.ts の fixture)・コメント・辞書(dictionary.json)の説明文や例 の
どこにも書かない。
どうするか
- 抽象化する: サポートしたいのは「Argo の◯◯という機能」であって「その業務の処理」ではない。
機能を切り出した最小の合成 yaml を書く。名前は Argo 界隈で一般的なもの（
build / test / deploy /
hello / main / step-a / task-b など）か、機能を表す中立な名前にする。
- 無関係な例にする: 例が必要なら、業務と全く関係ない題材（CI パイプライン、hello world 的なもの）で書く。
- 辞書の説明文: フィールドの一般的な意味だけを書く。業務固有の値を例に使わない
（良い例:
"depends": "先行タスクの完了条件をブール式で表す(例: \"a.Succeeded && b.Failed\")")。
- そもそも追加しない選択: サンプルやテストは「無いと機能を検証できない/回帰を守れない」ときだけ足す。
惰性で足さない。既存テストの網に入るなら新規追加は不要なことも多い。
判断に迷ったら: 「この行を、渡された yaml を知らない第三者が見て、どの業務のものか推測できるか？」
推測できるなら抽象化が足りない。
作業の進め方
Step 1. 渡された yaml を解析し、未対応点を洗い出す
渡された yaml を読み、どの Argo 機能を使っているかを列挙する。そのうえで、clargo が今それを扱えているかを確認する。
チェック観点（→ 対応するファイルは次節のマップ参照）:
kind: は既知か（Workflow/WorkflowTemplate/ClusterWorkflowTemplate/CronWorkflow）。未知の kind なら認識されない。- 使われているトップレベル/テンプレートの構造（
steps/dag/container/script/resource/suspend 等）。
- 参照の形（
templateRef/ローカル template:/entrypoint/dependencies/depends）。これらが色付け・ジャンプ対象か。
{{...}} 変数の形（inputs.parameters.X/steps.X.*/tasks.X.*/workflow.*/item.* など）。- 出てくるキーのうち、ホバー辞書に未登録のもの。
- ヒント: 設定
clargo.debugHover を on にすると未登録キーに「未登録」ホバーが出る。辞書育成の目安になる。
まず「何が足りていないか」を短くユーザーに共有してから直し始めると手戻りが少ない。
Step 2. 機能ごとの正しいファイルを直す
このリポジトリは package by feature。機能ごとにディレクトリが分かれ、各機能は
純粋ロジック(*.ts) + provider.ts(VSCode連携) + *.test.ts の構成。次のコードベースマップに従って、
該当機能のファイルだけを触る。
Step 3. 抽象化ルールを守ってサンプル/テストを（必要なら）追加
前述の「最重要ルール」を必ず適用する。追加が不要なら足さない。
Step 4. 検証する
- 型チェック:
bun run typecheck
- テスト:
bun run test（vitest）
- ビルド:
bun run build
- 可能なら実際の拡張として動かして、色・ホバー・ジャンプが期待通りか確認する。
（テストの fixture も抽象化した yaml を使うこと。渡された業務 yaml をそのまま貼らない。）
コードベースマップ（どの対応で何を触るか）
パッケージマネージャは Bun、言語は TypeScript、テストは vitest。パーサは yaml(eemeli/yaml)。
このリポジトリは TextMate 文法を持たず、色付けは Semantic Tokens で行う。
| やりたいこと | 触るファイル |
|---|
新しい kind: を Argo 文書として認識させる | src/core/argo.ts（KIND_RE と isArgoDocument） |
| 新しい値を semantic highlight（色付け）の対象にする | src/highlight/tokens.ts（AST 走査・トークン判定の核心） |
| 新しいトークン種別を増やす（新しい色区分） | src/highlight/tokens.ts の TOKEN_TYPES ＋ package.json の contributes.semanticTokenTypes と configurationDefaults の色定義 |
| 既存トークンの色を変える | package.json の editor.semanticTokenColorCustomizations.rules |
| ブロックのネスト色バー/濃淡の色を変える | src/block-visualize/decorations.ts（BAR_RGB / alphaFor）、種別は src/block-visualize/blocks.ts の BarColor |
| キーのホバー説明を足す/直す | src/hover/dictionary.json（"キー": "説明" を1行足すだけ）。引くロジックは src/hover/resolve.ts |
| 定義ジャンプの対象参照を増やす | src/goto/resolve.ts（＋索引は同ディレクトリ） |
{{...}} 変数のホバー/ジャンプを増やす | src/var-flow/resolve.ts |
| ワークフローグラフの構成を直す | src/graph/build.ts（レイアウト計算）/ src/graph/html.ts（inline SVG） |
| 共通のドメインモデル/パースを直す | src/core/（model.ts 型定義 / parser.ts / yaml-ast.ts / text-index.ts） |
覚えておくと事故らない要点
- 色はキーではなく「値」に付ける。文脈判別のため行ベースではなく AST を使う（
tokens.ts）。
トークン種別: argoName(定義名・黄) / argoRefCross(他ファイル参照・青+下線) / argoRefLocal(同ファイル参照・青) /
argoDep(dependencies・オレンジ) / argoVar({{}}・緑)。
- cross/local 判定: そのファイル内の全リソース
metadata.name を集め、templateRef.name がその集合にあれば local、
無ければ cross。新しい参照の形を足すときはこの判定に載せる。
- 辞書はコードから分離された資産。実行時に JSON を読むので、辞書だけ編集して拡張リロードで反映（再ビルド不要）。
多義的で誤爆しやすいキー（
name/key/help 等）は辞書に入れない設計。むやみに足さない。
- 辞書はフラット照合。ネスト文脈は見ずキー名だけで引く。同名キーの意味が文脈で割れる場合は要注意。
SemanticTokensBuilder は位置の昇順 push が必須。収集後に (line,char) でソートしてから push する。- ブロック色バーの連続/切断ルール: template のバーは全行に描いて1本の連続線に、step/task のバーは
各ブロック先頭行をスキップして切る。ここは
design/ に詳しい。
より詳しい機能仕様・設計判断・ハマりどころは design/20-features.md（各機能）と design/10-argo-domain.md
（Argo ドメイン）にまとまっている。込み入った変更のときは先に読むこと。
完了時に確認すること
