speccanvas

speccanvas は何をしますか？

このスキルを使用して、Spec Canvas アーティファクトをポータブルYAMLスペックとして作成・管理したり、設定済みのSpecCanvas MCPサーバーを通じて永続化したりします。

スペックを構造と意図の信頼できる情報源として扱います。余計な説明なしに、Spec Canvas、IDE、ターミナルエージェント、またはリポジトリに貼り付け可能な、コンパクトで再利用可能なスペックを優先します。

このスキル内のフォーマット記述YAMLファイルを記述ガイドとして使用します。このスキルにバンドルされているJSON Schemaのコピーとローカルの検証ロジックを事後チェックとして使用します。

コア哲学

Spec Canvasのスペックは、製品の意図と実装の間のコンパクトな橋渡しです。エージェントと人間がコード変更前に製品の形状について合意するのに役立つべきですが、すべてのCSS、レイアウト、コンポーネントの微調整を記録する実行ログになるべきではありません。

• UI Specは意図と構造を説明する。 画面、主要ブロック、ナビゲーション、主要ユーザータスク、重要な状態、意味のあるレスポンシブ構造をキャプチャします。
• Data Specは論理ドメインを説明する。 エンティティ、フィールド、列挙型、リレーション、ドメイン制約をキャプチャします。物理的なデータベースやフレームワークの詳細は避けます。
• Specファーストは意味的変更に適用される。 リクエストが製品の意味、ユーザージャーニー、またはドメイン構造を変更する場合は、実装前にスペックを更新します。
• 実装のマイクロ変更はスペックをスキップできる。 リクエストが外観のみ、レイアウトのみ、またはユーザーに影響しない場合は、実装を直接変更し、スペックはそのままにします。
• コンパクトなスペックが良いスペック。 画面/ブロックがなぜ存在するかを説明する短い目的文を、どのように構築されるかについての実装の文章よりも優先します。

粒度ゲート

UI Specを編集する前に、要求された変更がスペックに含めるのに十分な意味的変更かを判断します。

以下の場合、UI Specを更新します。

• 画面、画面グループ、または主要ブロックの変更
• ユーザージャーニー、ナビゲーション、エントリポイント、または利用可能なアクションの変更
• 重要なユーザー向け状態、モード、権限、または空/エラー/リカバリフローの変更
• 主要コンポーネントの目的または動作の変更
• 明確なデスクトップ/モバイル体験など、意味のあるレスポンシブ構造の変更
• 製品用語またはラベルの意味が変わる場合の変更
• 公開、管理、編集者、プレイヤー、オンボーディングなど、製品領域間の境界の変更

以下の実装のマイクロ調整ではUI Specを更新しないでください。

• 間隔: パディング、マージン、ギャップ、行の高さ
• 正確なサイズ: ピクセル値、フォントサイズ、幅/高さ（高レベルのレイアウト意図を表現する場合を除く）
• CSSクラス、Tailwindクラス、コンポーネント名、ファイル名、またはフレームワーク固有の構造
• 正確な色、グラデーション、影、境界線の半径、アイコン、または装飾的なスタイリング
• すでに説明されているブロック内でのローカルの配置、順序、折り返し、または視覚的なリフロー
• アニメーションのタイミング、デバウンスのタイミング、クロスフェードの秒数、トーストの位置、ローディングスピナーの仕組み
• ブラウザ/プラットフォームの実装詳細（中核的なユーザー向け機能でない限り）
• 意味を変えないローカルなコピー編集
• ユーザーに見えないリファクタリング

ユーザーが外観またはレイアウトのマイクロ変更を要求した場合は、コード変更を直接行い、UI Specには明示的に触れないでください。

デフォルトのファイル配置

ユーザーが明示的に別の場所を要求しない限り、Spec Canvasファイルをプロジェクトルートのspec/の下に作成および更新します。

• UI Specのパス: spec/ui-spec.yaml
• Data Specのパス: spec/data-spec.yaml

spec/ディレクトリが存在しない場合は、作成します。1つのアーティファクトのみが要求された場合は、該当するファイルのみを作成します。

MCPモード

ユーザーがライブのSpecCanvasプロジェクト、ドキュメント、リビジョン、実装、アーカイブを操作したい場合、またはMCPツールが環境で明らかに利用可能な場合、設定済みのspeccanvasという名前のMCPサーバーを使用します。

• MCPが利用可能な場合、ライブのSpecCanvasデータを作成または更新する前に、references/mcp-workflow.mdを読んでください。
• タスクがUI Specを作成または更新する場合は、references/ui-spec-workflow.mdも読んでください。
• タスクが画面実装を作成する場合は、references/implementation-workflow.mdも読んでください。
• MCPが利用できない場合、接続詳細をでっち上げないでください。ポータブルYAMLファイルで作業するか、ユーザーにspeccanvas MCPサーバーを設定するよう依頼してください。
• MCP URL、ベアラートークン、ステージングホスト、ローカルシークレットをこのスキルに保存しないでください。これらはエージェントのMCP設定と環境変数に属します。

MCPモデルIDルール

MCPを通じてエージェント作成の画面実装を保存する場合、常に安定したモデルIDを{ identityKey, provider, model, version }として提供します。

• add_implementationを呼び出す前に、アクティブなモデルをグローバルエージェントルール、環境変数、または現在のセッションから解決します。
• add_implementationにはmodelIdentityを直接渡します。agentNameに置き換えないでください。
• agentNameは手動/レガシーフォールバックのみです。実装が人間によってアップロードされるか、モデルIDが意図的に利用できない場合にのみ、modelIdentity: nullと一緒に使用します。
• アクティブなモデルが不明、曖昧、または登録されていない場合は、黙ってagentNameで保存する代わりに停止して確認を求めてください。

ワークフロー

1. アーティファクトの境界を特定する。 タスクに必要なものを判断します。

   • UI Specのみ
   • Data Specのみ
   • 両方のスペック
   • 既存のスペックの説明、レビュー、クリーンアップ、または検証
   • リクエストが実装のマイクロ調整であるため、スペック変更なし
   • プロジェクト、スペック、リビジョン、実装、またはアーカイブのライブMCP永続化

2. 粒度ゲートを適用する。 UI作業の場合、リクエストが製品の意図/構造を変更するのか、実装の詳細のみを変更するのかを判断します。マイクロ調整のみの場合は、スペックに触れないでください。

3. ソース資料を収集する。 構造を定義する入力のみを使用します。

   • 製品のアイデアまたは機能リクエスト
   • 既存のスクリーンショットまたはUIの説明
   • コードベースの構造
   • 現在のYAMLスペック
   • エンティティリスト、APIノート、またはドメインルール

4. 必要なワークフローとフォーマットのリファレンスを読む。

   • UI Specの作成または改訂の場合、references/ui-spec-workflow.mdを読んでください。
   • 画面実装の作成の場合、references/implementation-workflow.mdを読んでください。
   • ライブMCP永続化の場合、references/mcp-workflow.mdを読んでください。
   • UI Specの作成の場合、references/ui-spec-format-0-0-3.yamlを読んでください。
   • Data Specの作成の場合、references/data-spec-format-0-0-1.yamlを読んでください。
   • ローカル検証動作とレビューヒューリスティックについては、必要に応じてreferences/workflow.md、references/validation-rules-ui.md、およびreferences/validation-rules-data.mdを読んでください。
   • 現在バンドルされているスキーマは、schemas/ui-spec.schema.jsonとschemas/data-spec.schema.jsonにあります。

5. スペックを起草または改訂する。 ドキュメントを有効なYAMLに保ち、フォーマットフィールド内に収めます。フォーマットが明示的に許可しない限り、カスタムのトップレベルセクションを発明しないでください。意図を保持する最小の意味的更新を行います。ピクセルレベルの実装ノートでスペックを拡張しないでください。

6. 結果を検証する。 scripts/validate-spec.mjsが利用可能な場合、結果を返す前に最終的なYAMLに対して実行します。スペックを返す前に検証エラーを修正します。

7. 結果を返す。 検証済みのYAMLを返すか、レビュータスクの場合は最初に問題をリストし、その後修正されたスニペットまたはファイルを返します。

コアルール

フォーマットファイルを作成ソースとして使用する

フォーマット記述YAMLファイルは、このスキルの主要な作成リファレンスです。その構造、フィールド名、例、およびガイダンスに従います。UI Specの場合、references/ui-spec-format-0-0-3.yamlが現在のローカルの信頼できるソースであり、バンドルされているスキーマおよびバリデーターと整合性が保たれていることが期待されます。

スキーマ検証を事後チェックとして使用する

スキーマ検証は作成ガイドではありません。最終的な検証ステップです。

• フォーマットファイルからスペックを記述します。
• scripts/validate-spec.mjsで記述されたスペックを検証します。
• 最終的なYAMLを返す前に、スキーマおよび検証ルールの失敗を修正します。

schemas/にバンドルされているスキーマは、Spec Canvasの実装およびこのスキルのフォーマット記述リファレンスと同期している必要があります。これらが異なっているように見える場合は、それをスキルのバグとして扱い、黙って妥協案を発明するのではなく、明示的に指摘してください。

UIとデータの整合性を保つ

両方のスペックが存在する場合：

• 画面、エンティティ、およびアクション間で命名を一致させます
• UIアクションが実際のエンティティまたはワークフローを暗示していることを確認します
• Data SpecのリレーションがUI構造をサポートしていることを確認します
• 黙ってバックエンドの概念を発明する代わりに、ギャップをフラグします

フォーマットの移植性を保つ

リポジトリに存在し、任意のエージェントによって再利用可能なプレーンなYAMLファイルを生成します。スペックをSpec Canvas UIの状態、非表示のメタデータ、またはチャットのみの前提に依存させないでください。

UI Specを実装詳細の上に保つ

UI SpecをCSS、コンポーネントドキュメント、または変更履歴の代わりに使用しないでください。適切なpurposeは、画面またはブロックがユーザーの視点から何のためにあるのかを説明します。正確な間隔、クラス名、ピクセルサイズ、一時的な実装メカニズム、または製品の意味を変えないすべての小さなコントロールを列挙すべきではありません。

タスクパターン

新しいUI Specを作成する

• docType、format_version、およびmetadataから始めます。
• UI Specでは、metadata.descriptionは必須であり、トップレベルの製品意図を伝える必要があります。
• 主要なアプリの形状がわかったら、screensを追加します。
• ユーザーが目に見える構造を望む場合、blocksを追加します。探索段階ではblocksは省略できます。
• templates、navigation、またはレスポンシブフィールドは、それらが実質的に役立つ場合にのみ追加します。
• 現在のローカルフォーマットでサポートされているUIレスポンシブ作成には、metadata.breakpoints、アダプティブscreen.template、アダプティブblock.columns、およびblock.visibleが含まれます。
• UIフォーマットファイルからの引用ガイダンスを含む、元のフォーマットファイルの慣例を保持します。
• 利用可能な場合、scripts/validate-spec.mjsで完成したファイルを検証します。

新しいData Specを作成する

• 物理データベースではなく、論理ドメインモデルを記述します。
• 共有される管理された語彙が重要な場合にのみ、enumsを追加します。
• ビジネス的に意味のあるfieldsを持つentitiesを定義します。
• 論理的なエンティティ間構造にはrelationsを使用します。
• ユーザーがスペックの外部で明示的に要求しない限り、インデックス、マイグレーション、またはORM固有の構文などの実装のみの懸念を漏らさないでください。
• 利用可能な場合、scripts/validate-spec.mjsで完成したファイルを検証します。

既存のスペックをレビューまたは修復する

以下をチェックします：

• 無効またはサポートされていないフィールド
• 必須セクションの欠落
• 壊れた画面、テンプレート、またはナビゲーションの参照
• Data Specの列挙型、外部キー、またはリレーションエラー
• ローカル検証ルールによって表面化されたカスタム検証の失敗
• 元のフォーマットファイルと現在のローカル実装の間のスキーマとフォーマットの不一致
• 製品の意図ではなく実装メカニズムを説明する、過度に詳細なUIのpurposeテキスト

修復する際は、元の製品意図を保持し、明確さを回復する最小の修正を行います。

過度に詳細なUI Specをコンパクトにする

• 製品構造が実際に変更されない限り、既存の画面、テンプレート、リージョン、およびブロックIDを安定させます。
• 長いpurpose段落を、ユーザー向けの意図の一文要約に置き換えます。
• 画面、主要ブロック、ナビゲーション、重要な状態、および意味のあるモードを保持します。
• CSS/レイアウトのマイクロ詳細、プラットフォームの癖、正確なタイミング、ロギング動作、およびコンポーネント内部のメカニズムを削除します。
• ファイル全体のYAML再フォーマットを避けます。差分をレビュー可能に保つために、ターゲットを絞った編集を使用します。
• 編集後に検証します。

既存のアプリからスペックを再構築する

• 目に見えるワークフローから画面を推測します
• 繰り返されるリージョンとユーザータスクからブロックを推測します
• ドメイン名詞と状態変化からエンティティを推測します
• 観察されたものと推測されたものを分離します
• ソース資料が不完全な場合、不確実性を明示的に指摘します

検証

利用可能な場合、scripts/validate-spec.mjsを使用します。

• 入力: YAMLスペックファイルへのパス
• docTypeからドキュメントタイプを検出します
• このスキルからバンドルされたJSON Schemaに対して検証します
• 該当するカスタム検証ルールを実行します
• 警告はアドバイザリとして扱います
• 修正されたスペックを返す場合、エラーは最終出力へのブロッカーとして扱います

ローカルのSpec Canvas依存関係が欠落しているためにスクリプトを実行できない場合は、簡単にその旨を述べ、フォーマットファイルと検証ルールリファレンスを使用した手動レビューにフォールバックします。

出力の期待

スペックを返す場合：

• 有効なYAMLを提供します
• フォーマットが期待する場所ではIDをsnake_caseに保ちます
• フィールド名をフォーマットファイルで定義されたとおりに正確に保ちます
• 構造に実質的に影響を与える場合は前提について言及します
• 検証が実行されたかどうかに言及します

書き換えられたファイルではなくレビューを返す場合：

• 最初に構造上の問題をリストします
• 次に具体的な修正を提供します
• 次に、有用な場合、修正されたスニペットまたは完全なスペックを提供します