naatin777/plugumi / .agents/skills/specbook-authoring
specbook-authoring
Verifieddocs/goals, requirements, architecture, designs, decisions, contracts, verification, guides 配下の Specbook 形式 Markdown/YAML ドキュメントの作成・編集・整理・手動レビュー。設計計画・機能要件・プロトコル決定・ドキュメント再構成・relation/frontmatter の確認に使う。旧Plugumi実装を既定仕様として使わない。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.8 KB |
| references/architecture.md | markdown | 1.6 KB |
| references/contract.md | markdown | 1.5 KB |
| references/conventions.md | markdown | 5.5 KB |
| references/decision.md | markdown | 1.4 KB |
| references/design.md | markdown | 1.5 KB |
| references/goal.md | markdown | 1.3 KB |
| references/guide.md | markdown | 1.2 KB |
| references/japanese-writing.md | markdown | 5.6 KB |
| references/requirement.md | markdown | 1.4 KB |
| references/verification.md | markdown | 1.5 KB |
| templates/architecture.md | markdown | 557 B |
| templates/contract.md | markdown | 557 B |
| templates/decision.md | markdown | 434 B |
| templates/design.md | markdown | 580 B |
| templates/goal.md | markdown | 373 B |
| templates/guide.md | markdown | 362 B |
| templates/requirement.md | markdown | 386 B |
| templates/verification.md | markdown | 578 B |
references/conventions.md
View on GitHub# 形式・識別子・relation の規約
旧Plugumi Specbook実装のartifactモデルに倣った規約。新しい作り直しの**出発形式**であり、現在validatorが導入済みであることの証明ではない。新プロジェクトが別の契約を明示採用した場合は、artifactを書く前にこのreferenceとtemplatesを一緒に更新する。
## ディレクトリとファイル名
```
docs/
├── glossary.md # 用語の正本(typeを持たない単一ファイル)
├── goals/ # type: goal
├── requirements/ # type: requirement
├── architecture/ # type: architecture
├── designs/ # type: design
├── decisions/ # type: decision
├── contracts/ # type: contract
├── verification/ # type: verification
└── guides/ # type: guide
```
`docs/glossary.md` はtype・IDを持たない単一ファイルで、プロジェクト用語の正本とする。
各artifactファイルは `docs/<folder>/<5桁ID>-<kebab-case-slug>.md`。例: `docs/designs/00007-tool-execution.md`。IDは**各typeディレクトリ内で一意**(フォルダ内連番・グローバル連番ではない)で、YAMLではなくファイル名から導かれる。作成時はそのフォルダの既存IDを走査して max + 1 を使い、deprecated IDを再利用しない。
## frontmatter
```yaml
---
type: design
title: Tool実行
description: designが管轄する内容
status: draft
relations:
requirement:
- '00002'
---
```
必須キー: `type`・`title`・`description`・`status`。`status` は `draft | accepted | deprecated`。任意キー: `tags`・`sources`・`subtype`・`relations`・`perspective`(**design と architecture のみ**)。推奨: 5桁IDは引用符で囲み、先頭ゼロを保つ。本文の見出しは提案であり、スキーマ要件ではない。
`status: accepted` は明示的な合意を要する。実装した・草案を書いただけでは自動的にacceptedにならない。`deprecated` artifactは履歴として残し、新しい側は同typeキーのrelationで旧版を指す(本文で「supersedes」等の関係を明記する)。
`id`・`path`・`slug`・`updated_at`・`incoming`・`children`・`siblings` を frontmatter に永続化**しない**。逆リンクは導出される。外向きリンクはすべて `relations` 内に置く。
## relation
`relations` の**キーは参照先のtype名**、値はそのtypeフォルダ内の5桁IDのリスト。
```yaml
relations:
architecture:
- '00001'
requirement:
- '00002'
- '00004'
```
- 使えるキー: `goal` `requirement` `architecture` `design` `decision` `contract` `verification` `guide`
- IDはキーのtypeフォルダ内で解決されるため、`'00001'` が複数フォルダに存在しても一意になる
- 保存するのは外向きrelationのみ。逆参照は自動的に算出し、保存しない
- IDの振り直し・再利用はしない
**関係の意味はキーには含まれない。** 「addressする」「verifyする」「supersedeする」等の意味は本文で記述する。この形式では旧来のrelation名(`parent`/`addresses`/`applies_to`/`verifies`/`depends_on`/`related_to`/`contributes_to`/`documents`/`supersedes`)は使わない。
残る構造的なルール:
| 元type | 必須relation | 備考 |
|---|---|---|
| `design` | `requirement` キー ≥ 1 | 少なくとも1つのrequirementを満たす |
| `verification` | `requirement`・`design`・`architecture`・`contract` のいずれか ≥ 1 | 検証対象が必須 |
| その他 | なし | 階層(parent相当)・置換(supersedes相当)・依存は本文と同typeキーで表現 |
対象IDの実在とキーのtype名の正しさを確認する。対象の重複・自己参照を避ける。draftを改訂しても必須relationは維持する。前提が不明なartifactにはIDを捏造せず、前提を作るか「まだ妥当になれない」ことを明示して報告する。
## `sources` と contract ファイル
`sources` はリポジトリルート相対の**実在するソースパス**(絶対パスでも任意URLでもない)。実装ができるまで省略する。`contract` ドキュメントはリポジトリ内の実在する OpenAPI・JSON Schema・`.proto` 等を指してバージョン管理・意味を説明してよいが、それらのファイルが存在するふりをしない。
## 手動レビューのチェックリスト
1. すべての `NNNNN-*.md` のIDがそのフォルダ内で一意である
2. フォルダ・`type`・ファイル名が一致し、`title`・`description`・`status` がある
3. 計算フィールドを永続化していない、`sources` を捏造していない
4. `relations` のキーが有効なtype名であり、値のIDがそのtypeフォルダ内に実在し、引用符付き5桁文字列である
5. すべてのdesignが `requirement` キー ≥ 1 を持ち、すべてのverificationが `requirement`・`design`・`architecture`・`contract` のいずれか ≥ 1 を持つ
6. 同type relationの循環(parent相当)がない。異type間の循環は指摘する
7. 節が一貫した主題を記述し、合意済みの事実と未解決の問いを区別する
8. あるartifactの変更が、依存するcontract・design・テスト・guideと整合している
**手動レビュー** は `validation/repository` の実行成功と同等ではない。現行validatorを実際に実行しない限り、エンジン検証済みの互換性を主張しない。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |