folio Phase X3 着手にあたり、 plugin の component 構成 (skill / hook / script / CLI の役割分担と最小実装範囲) を確定する必要があった。 folio-self-spec.html §7.2 は完成形として 8 specialist agents (spec-explorer / spec-architect / spec-review × 6) を定義済だが、 試作段階 (Phase X2) では「動くものを先に作る」 試作駆動哲学に沿って **minimal viable plugin scope** から着手すべきと user が確認 (2026-05-22)。
5 並列 researcher × 76 ソース調査 (plugin-architecture-research.html) で Claude Code 公式 plugin 仕様 (hooks 29 種、 SKILL.md frontmatter、 plugin.json manifest) と業界事例 (twill / log4brains / Beads / pre-commit / ESLint) を verify、 §7.3 で minimal viable plugin scope を導出した。
folio plugin Phase X3 着手分として以下の構成を採用する。
| category | count | component | 役割 (WHAT) |
|---|---|---|---|
| skills/ | 1 | folio-architect | spec edit の唯一 author、 caller marker 設定の起点 |
| hooks/ | 4 | SessionStart | inventory.json (Tier 1) を agent に inject (Beads pattern) |
| PreToolUse: caller marker | env var 未 set or 異値で deny (twill pattern) | ||
| PreToolUse: path boundary | spec dir 外への作成を block | ||
| PostToolUse: JSON-LD lint + README update | schema check + index 自動更新 | ||
| scripts/ | 6 | inject-inventory | SessionStart / PreCompact で inventory を context inject |
check-caller-marker | PreToolUse、 rules.html §10.1 REQ-CM-001〜003 | ||
check-path-boundary | PreToolUse、 spec dir 外 spec 作成を block | ||
lint-jsonld | PostToolUse、 ajv + pyld 2 層検証 (ADR-0004 候補) | ||
update-readme-index | 新 spec 追加時 README index 自動更新 | ||
link-integrity | CI script、 rules.html §10.2 REQ-CI-010 | ||
| bin/ | 1 | folio CLI | init / validate / inventory / prime / fix subcommands |
本 ADR の 1 skill は §7.2 完成形 8 agents の subset として位置付ける。 段階的成長 path: 1 skill (Phase X3) → 2-3 skill (Phase X4) → 8 agent 完成形 (Phase X5+)。 試作で発見した修正点 / 必要追加機能を spec に逐次反映し、 完成形に近づける。 完成形 §7.2 は変更しない、 試作段階の現状は §7.6 (新設) に局所化する。
constitution P-11 (HOW 禁止) 遵守のため、 具体的な script 内容 / binary 名 / CLI 構文は .claude-plugin/ 配下の harness に隔離する。 本 ADR は WHAT (役割分担と最小構成) のみ規定する。 具体的 binding は folio-self-spec.html §9 Bindings に集約する設計を継続する。
.claude-plugin/ + §9 Bindings に隔離init / validate / inventory / prime / fix) は WHAT 列挙、 引数仕様等の HOW は .claude-plugin/ 実装時に確定| 案 | 採用しなかった理由 |
|---|---|
| 案 A: 完成形 8 agents を初版で全部実装 | 試作駆動 (user 確定 2026-05-22) と矛盾、 「動くものを後にする」 巨大計画リスク、 Phase X3 着手遅延 |
| 案 B: 最小 1 hook のみ (caller marker check のみ) | JSON-LD lint / README update / context injection 等の核心機能を欠く、 試作の「動くもの」 として不完全 |
| 案 C: skill なし、 全部 hook + script | spec edit の context injection が agent 側で機能せず、 folio-architect SKILL が果たす「spec edit entry point」 role が欠落 |
| 案 D: MCP server 採用 | plugin-architecture-research §5.2 Beads pattern: 「CLI + Hooks > MCP」 (10-50x context efficiency)。 試作段階で MCP overhead を避ける |