skill-system-behavior

スキルシステムの動作 — Spec Engine

どのように実装するかを書く前に、スキルが何をするのかを定義します。このスキルでは、BDD スタイルのワークフローを徹底します。

SKILL.spec.yaml  →  Acceptance Tests  →  Implementation  →  SKILL.behavior.yaml (generated)
     (WHAT)           (VERIFY)              (HOW)              (DOCUMENT)

仕様の形式

すべてのスキルの動作は SKILL.spec.yaml で定義します。

schema_version: 1
skill_name: my-skill
description: "What this skill does"

operations:
  - name: do-something
    intent: "Why this operation exists"
    inputs: [...]
    outputs: [...]
    constraints: ["Must not...", "Must always..."]
    expected_effects: [...]

acceptance_tests:
  structural:
    - id: manifest-valid
      assert: "manifest exposes all operations"
  behavioral:
    - id: happy-path
      given: "Valid input"
      when: "do-something is called"
      then: "Returns expected output"

完全なスキーマ：schema/spec-v1.yaml

v2 の動作仕様（*.behavior.yaml）では、ノード間のやり取りを記述する任意の interaction_diagram Mermaid ブロックも追加できます。

interaction_diagram: |
  flowchart LR
    Script["runtime-doctor"] -->|"reads"| Config["config/memory.yaml"]

操作

create-spec

スキーマテンプレートから新しい SKILL.spec.yaml を作成します。

1. 形式を確認するために schema/spec-v1.yaml を読みます
2. ユーザーに次の情報を尋ねます：スキル名、説明、操作（名前 + 意図 + 入出力）
3. 対象のスキルディレクトリに SKILL.spec.yaml を生成します
4. プレースホルダーの受け入れテスト（構造上のデフォルト + 動作のスタブ）を含めます

validate-spec

SKILL.spec.yaml を v1 スキーマに照らして検証します。

1. 対象の SKILL.spec.yaml を読みます
2. 必須フィールドを確認します：schema_version、skill_name、description、operations
3. 各操作について、name、intent、1 つ以上の入力または出力、および制約が記載されていることを確認します
4. acceptance_tests について、構造テストに manifest-valid と scripts-exist が含まれていることを確認します
5. 結果を報告します：概要付きの PASS、または具体的な違反内容付きの FAIL

実行方法：python3 scripts/validate_spec.py <path-to-SKILL.spec.yaml>

verify-structural

ビルド済みのスキルに対して構造上の受け入れテストを実行します。

1. スキルの SKILL.spec.yaml を読み、宣言された操作を確認します
2. スキルの SKILL.md を読み、skill-manifest ブロックを確認します
3. 次の項目を検証します：
   • 仕様内のすべての操作に、マニフェスト内の対応する操作があること
   • マニフェストで参照されるすべてのエントリーポイントスクリプトがディスク上に存在すること
   • skills-index.json にこのスキルの機能が含まれていること
4. 結果を報告します：各テストの PASS/FAIL を示すチェックリスト

generate-contract

完成した仕様と実装から SKILL.behavior.yaml（Mermaid DAG）を生成します。

1. SKILL.spec.yaml を読み、操作、入力、出力、制約を確認します
2. 操作をフローチャートのステージに対応付けます
3. 入力を入力ノードに、出力を出力ノードに対応付けます
4. 制約をエラーパスに対応付けます
5. Mermaid 図を埋め込んだ SKILL.behavior.yaml を書き込みます

これは最後の手順です。実装が完了し、テストに合格した後にのみ実行してください。

Coverage Gate

プロジェクトツリーをスキャンし、動作仕様がないスクリプト／モジュールを検出します。

1. 設定されたパターンに一致するスクリプトを project_dir からスキャンします
2. 同じツリー内の *.behavior.yaml ファイルをスキャンします
3. 正確な名前の一致と SKILL の規約に基づいて、仕様がある／ないスクリプトを報告します
4. 人が読める形式の概要と、最終行の JSON レポートを出力します

実行方法：python3 scripts/coverage_gate.py <project_dir> [--patterns ...] [--exclude ...]

「動作カバレッジが完了した」と宣言する前に実行してください。

ワークフローへの統合

skill-system-creator の場合（更新されたフロー）

1. Understand the skill (examples, triggers)
2. Create spec         → skill-system-behavior:create-spec
3. Validate spec       → skill-system-behavior:validate-spec
4. Write tests         → define acceptance criteria from spec
5. Initialize skill    → skill-system-creator:init
6. Implement skill     → edit SKILL.md, scripts, references
7. Verify structural   → skill-system-behavior:verify-structural
8. Generate contract   → skill-system-behavior:generate-contract
9. Package             → skill-system-creator:package

唯一の信頼できる情報源としての仕様

• SKILL.spec.yaml — 信頼できる定義（人が作成し、レビューします）
• SKILL.md + manifest — 実装（仕様に準拠する必要があります）
• SKILL.behavior.yaml — 生成されるドキュメント（仕様から派生します）

ガバナンス階層

ファイル間のガバナンス文書を整理する際の指針として、この 3 階層の構造を使用してください。

Tier 1 — System Architecture
  ├── SYSTEM_ARCHITECTURE.md    (system boundaries + data flow)
  └── PIPELINE_DAG.md           (zoom-in companion, state machines)

Tier 2 — Behavior Contracts
  ├── *.behavior.yaml           (single-script: inputs/outputs/stages/error_paths)
  └── BEHAVIOR_RUNTIME.md       (strictly cross-script scenarios only)

Tier 3 — Tests
  └── test_*.py                 (each test traces to a specific behavior scenario)

Tier 2 から Tier 3 へのトレーサビリティには、SKILL.spec.yaml の acceptance_tests.behavioral[].tested_by を使用して、検証テストを指定します。

階層をまたぐ参照には、SKILL.spec.yaml の任意項目 governance.tier と governance.traces_to を使用して、仕様の階層上の位置と、トレース先となる上位／下位の成果物を宣言します。

ファイル間の境界ルール

• *.behavior.yaml では、単一スクリプトの動作のみを定義します（1 つのスクリプトの入力、出力、ステージ、エラーパス）。
• BEHAVIOR_RUNTIME.md は、スクリプト間のシナリオ（2 つ以上のスクリプトが連携する場合）のみを対象とします。
• シナリオに関係するスクリプトが 1 つだけの場合は、BEHAVIOR_RUNTIME.md ではなく、そのスクリプトの .behavior.yaml に記載します。
• 新しいフェーズを追加する際は、内容全体を複製しないでください。共有フローを正式な定義として維持できるよう、参照／オーバーレイのパターンを使用します。

ガイドライン

• 仕様はチームが使用する言語で記述してください（英語、中国語、混在など。仕様内では一貫性を保ってください）
• 制約は不変条件です。違反した場合、そのスキルにはバグがあります
• intent では方法ではなく理由を説明します。実装の詳細は SKILL.md に記述してください
• 受け入れテストでは、動作については Given/When/Then を、構造については assert 文を使用してください
• すべてのテストに合格した後でのみコントラクトを生成してください。コントラクトは仕様ではなくドキュメントです

{
  "schema_version": "2.0",
  "id": "skill-system-behavior",
  "version": "2.0.0",
  "capabilities": ["spec-create", "spec-validate", "spec-verify", "contract-generate", "coverage-gate", "skill-graph-build"],
  "effects": ["fs.read", "fs.write", "proc.exec"],
  "operations": {
    "create-spec": {
      "description": "Scaffold a new SKILL.spec.yaml from the schema template.",
      "input": {
        "skill_name": { "type": "string", "required": true, "description": "Name of the skill to spec" },
        "skill_dir": { "type": "string", "required": false, "description": "Target directory (default: skills/<skill_name>)" }
      },
      "output": {
        "description": "Path to created SKILL.spec.yaml",
        "fields": { "path": "string" }
      },
      "entrypoints": {
        "agent": "Read schema/spec-v1.yaml, then scaffold SKILL.spec.yaml in skill_dir"
      }
    },
    "validate-spec": {
      "description": "Validate a SKILL.spec.yaml against the v1 schema.",
      "input": {
        "spec_path": { "type": "string", "required": true, "description": "Path to SKILL.spec.yaml" }
      },
      "output": {
        "description": "Validation result with pass/fail and violations list",
        "fields": { "status": "string", "violations": "array" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/validate_spec.py", "{spec_path}"],
        "windows": ["python", "scripts/validate_spec.py", "{spec_path}"]
      }
    },
    "verify-structural": {
      "description": "Run structural acceptance tests against a built skill or general behavior spec.",
      "input": {
        "skill_dir": { "type": "string", "required": true, "description": "Path to skill directory or direct spec path" }
      },
      "output": {
        "description": "Test results checklist",
        "fields": { "status": "string", "results": "array" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/verify_structural.py", "{skill_dir}"],
        "windows": ["python", "scripts/verify_structural.py", "{skill_dir}"]
      }
    },
    "generate-contract": {
      "description": "Generate behavior contract Mermaid DAGs from completed skill or project specs.",
      "input": {
        "skill_dir": { "type": "string", "required": true, "description": "Path to skill directory or direct spec path" }
      },
      "output": {
        "description": "Path to generated SKILL.behavior.yaml",
        "fields": { "path": "string" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/generate_contract.py", "{skill_dir}"],
        "windows": ["python", "scripts/generate_contract.py", "{skill_dir}"]
      }
    },
    "coverage-gate": {
      "description": "Scan project for scripts/modules missing behavior specs.",
      "input": {
        "project_dir": { "type": "string", "required": true, "description": "Root directory to scan" },
        "patterns": { "type": "string", "required": false, "description": "Comma-separated glob patterns (default: **/*.py,**/*.sh)" },
        "exclude": { "type": "string", "required": false, "description": "Patterns to exclude (default: test_*,__pycache__,.*)" }
      },
      "output": {
        "description": "Coverage report with covered/uncovered lists and percentage",
        "fields": { "covered": "array", "uncovered": "array", "coverage_pct": "number" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/coverage_gate.py", "{project_dir}"],
        "windows": ["python", "scripts/coverage_gate.py", "{project_dir}"]
      }
    },
    "build-graph": {
      "description": "Build a project behavior graph from discovered spec files.",
      "input": {
        "skills_dir": { "type": "string", "required": false, "description": "Root directory to scan using config/spec_discovery.yaml patterns" },
        "output_format": { "type": "string", "required": false, "description": "mermaid, json, or sql" }
      },
      "output": {
        "description": "Graph output in the requested format",
        "fields": { "graph": "string|json" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/build_graph.py", "--skills-dir", "{skills_dir}", "--format", "{output_format}"]
      }
    },
    "refresh-projections": {
      "description": "Refresh behavior projection bundles from SKILL.spec.yaml files for behavior_* tables.",
      "input": {
        "skills_dir": { "type": "string", "required": false, "description": "Root directory to scan (default: ./skills)" },
        "output_format": { "type": "string", "required": false, "description": "json or sql" }
      },
      "output": {
        "description": "Projection bundle or SQL statements for behavior_* refresh",
        "fields": { "bundle": "json|string" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/refresh_behavior_projections.py", "--skills-dir", "{skills_dir}", "--format", "{output_format}"]
      }
    }
  },
  "stdout_contract": {
    "last_line_json": true
  }
}