# Operation Authoring And Diagnostics

> operation YAML、project workflow authoring path、source-aware operationRef、facet source 解決、output contract、output placeholder、または workflow 関連テストを安全に変更するときに読むこと。

- Skill: `atman-33/operation-authoring-and-diagnostics-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add atman-33/operation-authoring-and-diagnostics-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/atman-33/operation-authoring-and-diagnostics-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: atman-33 (https://skillmd.com/u/atman-33)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/atman-33/operation-authoring-and-diagnostics-2

---


# Operation Authoring And Diagnostics

## 目的

この文書は、この repository における builtin / project authored operation と facet を安全に変更するための authoring rule と diagnostics 観点を整理した reference です。

operation YAML、facet file、output contract、placeholder 挙動、workflow 関連テストを変更するときに参照してください。

## Change Surfaces

- operation YAML の step ownership、rule、source object を変える変更
- facet file の内容や path を変える変更
- output contract や placeholder reference を変える変更
- source-aware catalog、operation selector、operation-debug filter に影響する変更
- prompt builder / composer / report routing に影響する変更
- workflow 関連テストを更新する変更

## Runtime-Relevant Authoring Rules

頻繁に確認する schema field は次のとおりです。

- `initial_step`
- `steps[]`
- `steps[].job`
- `steps[].instruction`
- `steps[].skills`
- `steps[].policies`
- `steps[].delegation.allowed_workers`
- `steps[].delegation.worker_job`
- `steps[].delegation.worker_instruction`
- `steps[].delegation.worker_skills`
- `steps[].delegation.worker_policies`
- `steps[].output_contracts.report[].format`
- `steps[].rules[]`

意味上の役割の違いは次のとおりです。

- `job`: その step の stable な role、responsibility、decision principle、prohibition
- `instruction`: その step 固有の execution procedure と reference
- `skills`: current step の実行に必要な background skill や reference material
- `policies`: current step が従う constraint や convention
- `delegation.*`: Noctis-owned step が child task を worker へ委任するときの許可対象と delegated worker prompt 素材
- `output_contracts.report[].format`: report artifact の format 定義

Canonical な source form は次のとおりです。

- `job.file` / `job.inline`
- `instruction.file` / `instruction.inline`
- `skills[].file`
- `policies[].file` / `policies[].inline`
- `output_contracts.report[].format.file` / `output_contracts.report[].format.inline`

Canonical な authored location と identity は次のとおりです。

- builtin workflow: `builtins/<lang>/operations/*.yaml`
- project workflow: `projects/<project-id>/operations/*.yaml`
- builtin facets: `builtins/<lang>/facets/**`
- project facets: `projects/<project-id>/facets/**`
- canonical identity: `operationRef` (`builtin:<lang>:<fileName>` または `project:<projectId>:<fileName>`)

次の制約は runtime failure に直結しやすいので、設計時に先に確認してください。

- `initial_step` は `noctis` step を指すべきである
- list facet は authored order を保持する
- `file` source は operation YAML path からの相対パスで解決される
- same-name workflow が builtin / project source にまたがる場合でも selector と debug preview では collapse されない
- message body からの auto activation は catalog match が unambiguous な場合だけ成功する
- runtime state、Noctis Team selector、operation-debug preview は plain operation name ではなく `operationRef` を canonical key として使う
- `output_contracts.report[].format` は output filename と downstream reference に整合している必要がある
- `steps[].delegation.allowed_workers` は authored 上の上限であり、runtime では mission の allowed worker set との積集合が effective set になる
- `rules` を省略できるのは、Noctis が同じ parent step に留まる autonomous delegation step だけである

`initial_movement`、`movements`、`max_movements`、`edit`、`handoff_mode`、`job_file`、`knowledge_files` などの legacy field は canonical ではありません。

prompt を変えるときは operation YAML と参照先 facet file の両方をセットで確認してください。