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

根据 v1 架构验证 SKILL.spec.yaml。

1. 读取目标 SKILL.spec.yaml
2. 检查必填字段：schema_version、skill_name、description、operations
3. 对每项操作：验证是否包含 name、intent、至少一个输入或输出，以及约束
4. 对于 acceptance_tests：验证结构测试是否包含 manifest-valid 和 scripts-exist
5. 报告：通过并附上摘要，或失败并列出具体违规项

运行命令：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. 报告：逐项列出测试的通过/失败检查清单

generate-contract

根据已完成的规范 + 实现生成 SKILL.behavior.yaml（Mermaid DAG）。

1. 读取 SKILL.spec.yaml 中的操作、输入、输出和约束
2. 将操作映射为流程图中的阶段
3. 将输入映射为输入节点，将输出映射为输出节点
4. 将约束映射为错误路径
5. 编写包含嵌入式 Mermaid 图表的 SKILL.behavior.yaml

这是最后一步——仅在实现完成且测试通过后运行。

覆盖率门禁

扫描项目树，查找缺少行为规范的脚本/模块。

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 — 生成的文档（源自规范）

治理层级

组织跨文件治理文档时，请以此三层级体系作为指导：

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 仅定义单个脚本的行为（一个脚本的输入、输出、阶段和错误路径）。
• BEHAVIOR_RUNTIME.md 仅用于跨脚本场景（两个或更多脚本交互）。
• 如果某个场景只涉及一个脚本，请将其写在该脚本的 .behavior.yaml 中，而不是 BEHAVIOR_RUNTIME.md 中。
• 扩展到新阶段时，避免完整复制；采用引用/叠加模式，让共享流程保持规范统一。

指南

• 使用团队惯用的语言编写规范（英语、中文或混合语言均可，但同一规范内应保持一致）
• 约束是不变量：违反约束意味着技能存在缺陷
• 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
  }
}