Claude Code plugin 構成と HTML spec management 統合の徹底調査

§1. 調査背景

§1.1. folio の Phase X3 着手要件

folio は AI agent (Claude Code) と人間が共同で「仕様書 (architecture spec)」 を HTML 形式で書き続ける meta framework (P-2)。 Phase X1-X2 で rules.html / folio-self-spec.html / relations.html / constitution.html の 4 file が確定 (commit 75232b9)、 Phase X3 で「architecture/ という構造を作成し維持する」 試作 plugin の実装に着手する。 plugin の 6 機能候補:

1. architecture/ 構造の強制 (rule 違反 path で reject)
2. spec 追加時の README index 自動更新
3. JSON-LD lint (Edit 完了時 schema check)
4. broken link detection
5. 双方向 link auto-materialize (forward 宣言時 reverse 自動追加)
6. caller marker enforcement (REQ-CM-001〜003)

これらを Claude Code plugin の skills / hooks / scripts / slash commands でどう組み合わせるか、 業界事例 (pre-commit / husky / ESLint / log4brains / Beads / twill) を踏まえて設計判断する必要がある。

§1.2. 5 サブ質問

1. Claude Code Plugin 公式仕様 (plugin.json manifest / SKILL.md format / hooks 全種 / agents / scripts / 組み合わせ pattern)
2. Git-based hook framework 業界事例 (pre-commit / husky / lefthook / lint-staged / pre-commit.ci) と PreToolUse / PostToolUse の使い分け
3. Linter plugin architecture と SSG/catalog hook system (ESLint / Stylelint / Prettier / Sphinx / MkDocs / Antora / Docusaurus / Backstage)
4. ADR / spec management OSS の具体実装 (log4brains / Beads / MADR / adr-tools / Specmatic / Spectral / ArchUnit / twill plugin)
5. JSON-LD validation の実装 + Claude Code PostToolUse hook で「Edit 後即時 lint」 する mechanism

追加で Q3 use case matrix (8 use case × skill/hook/script/CLI) / Q6 folio Phase X3 minimal viable plugin 設計推奨 / Q7 ADR 起票候補 を全 worker findings の統合で導出。

§2. Claude Code Plugin 公式仕様 reference

§2.1. plugin.json manifest (23 field、 大半は optional)

配置先: <plugin-root>/.claude-plugin/plugin.json。 manifest は optional (省略時は directory name から自動導出 + default 位置からコンポーネントを auto-discover)。

全 path は ./ 相対指定 MUST。 環境変数: ${CLAUDE_PLUGIN_ROOT} (絶対パス) / ${CLAUDE_PLUGIN_DATA} (永続データ) / ${CLAUDE_PROJECT_DIR} (project root)。

§2.2. plugin directory layout

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/<name>/SKILL.md        ← Progressive Disclosure 3-tier (推奨)
├── commands/<name>.md             ← legacy flat .md (Skills と同一 frontmatter)
├── agents/<name>.md               ← subagent 定義 (plugin agent は hooks/mcpServers/permissionMode 非対応)
├── hooks/hooks.json               ← 自動 detection (plugin.json 明示不要)
├── scripts/                       ← 慣習 (必須でない)、 ${CLAUDE_PLUGIN_ROOT}/scripts/ で参照
├── bin/                           ← Bash の PATH に追加
├── monitors/monitors.json         ← experimental、 stdout 各行が notification
├── output-styles/, themes/
└── .mcp.json, .lsp.json

§2.3. Hooks — 29 イベント (公式 verified)

Hook 5 type: command (shell コマンド、 args で exec form 可) / http (JSON POST) / mcp_tool (MCP tool 呼出) / prompt (Claude model 推論、 yes/no) / agent (subagent spawn、 experimental)。

stdin JSON (PreToolUse 例):

{
  "session_id": "...", "transcript_path": "...", "cwd": "...",
  "hook_event_name": "PreToolUse",
  "permission_mode": "default|plan|acceptEdits|...",
  "tool_name": "Write", "tool_input": {...}, "tool_use_id": "...",
  "effort": {"level": "..."}
}

stdout JSON output (PreToolUse の deny 例):

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "caller marker not set"
  }
}

§2.4. SKILL.md + Progressive Disclosure (3-tier)

frontmatter 全フィールド optional、 description のみ強推奨:

---
name: skill-name
description: "What it does... Use when..."
when_to_use: "Additional context..."        # description に連結、 合計 1536 文字上限
allowed-tools: "Read Grep Bash(git *)"
model: sonnet
effort: medium
context: fork                                # subagent で実行
agent: Explore
hooks: {...}                                 # skill ライフサイクル hook
paths: "src/**/*.ts"                         # glob で自動起動限定
---

Dynamic context injection (skill 本文): !`<command>` 構文で skill ロード前にコマンド実行・出力で置換。

§2.5. Slash Commands と Agents

公式 docs では skills と commands は統合。 /slash-commands 独立ページは存在しない (skills page に redirect)。

Agents (subagent) 配置: <plugin>/agents/<name>.md。 v2.1.63 で Task tool → Agent tool 改名 (Task は alias 継続)。 plugin agent では security 上 hooks / mcpServers / permissionMode が 無視される。 built-in: Explore (Haiku、 read-only) / Plan / general-purpose。

§2.6. 組み合わせ pattern

§3. Git-based hook framework 業界事例

§3.1. 6 tool 比較

§3.2. PreToolUse / PostToolUse vs git hook の対比

§3.3. 3 層防御 (defense in depth) 原則

Layer 1: PreToolUse / PostToolUse hook  ← AI 編集時のリアルタイムチェック
Layer 2: git pre-commit hook           ← commit 時 (human + AI 両方)
Layer 3: CI (GitHub Actions)           ← merge gate (bypass 不可)

Xygeni / AdamJ の指摘: --no-verify の使用を完全に抑制することはできないため、 git hook でチェックしているのと同じ内容を CI/CD パイプラインでも実施することがベストプラクティス。

§4. Linter + SSG plugin architecture

§4.1. 共通 4 design pattern

§4.2. ESLint Rule Unit (folio HTML lint に直接適用可能)

module.exports = {
  meta: {
    type: "problem",
    fixable: "code",
    hasSuggestions: true,
    schema: [{ type: "object", properties: {...} }],  // JSON Schema Draft-04
    docs: { url: "..." }
  },
  create(context) {
    return {
      "Identifier": (node) => {
        context.report({
          node,
          messageId: "...",
          fix(fixer) {
            return fixer.replaceText(node, newText);
          }
        });
      }
    };
  }
};

Autofix 安全性原則:

• Idempotent: ESLint は fix 適用後に最大 10 回再 lint → 固定点収束
• 競合解決: 同一 range の複数 fix は一方を棄却 (atomic でない fix の安全弁)
• Suggestion vs Fix 分離: 安全でない変更は hasSuggestions として提供
• meta.fixable 強制宣言: fix 提供時に未宣言ならエラー → 意図しない autofix の防止
• --fix-dry-run: 変更を実行せず結果のみ返す

§4.3. MkDocs Event System (folio README 自動更新パターンに最適合)

class MyPlugin(BasePlugin):
    @event_priority(-50)
    def on_files(self, files, config):
        files.append(File.generated(config, "virtual.md", content="..."))
        return files

    def on_page_markdown(self, markdown, page, **kwargs):
        return modified_markdown  # None → 元のまま

Event 分類:

• One-time: on_startup / on_shutdown / on_serve
• Global: on_config / on_pre_build / on_files / on_nav / on_env / on_post_build
• Page: on_pre_page / on_page_markdown / on_page_content / on_page_context / on_post_page

§4.4. Antora Generator Events (14 step、 SSoT enforcement に応用)

順序保証あり: contextStarted → playbookBuilt → beforeProcess → contentAggregated (ファイル追加可能) → uiLoaded → contentClassified (分類済み catalog 使用可能) → documentsConverted → navigationBuilt → pagesComposed → redirectsProduced → siteMapped → beforePublish → sitePublished → contextStopped / contextClosed。

§4.5. Backstage Catalog Auto-Discovery

EntityProvider (エッジ)
  → getProviderName() で一意 bucket
  → connect(connection)
  → connection.applyMutation({type: 'full'|'delta', entities: [...]})
     'full': bucket 全体置換
     'delta': {added, removed}

→ EntityProcessor (中継、 推奨は Provider に移行)
  → preProcessEntity / postProcessEntity
  → 新 entity / relation / error を emit

→ Stitching (最終 catalog API 出力)

Provider 削除 → 即時 purge。 Processor はオーファン化のみ。 Provider は webhook / schedule / event 駆動 (柔軟)、 Processor は固定 loop。

§5. ADR / spec management OSS の具体実装事例

§5.1. log4brains — 双方向 link auto-materialize (TypeScript verified)

GitHub source 直接 fetch (packages/core/src/adr/domain/Adr.ts):

class Adr extends AggregateRoot<Props> {
  // ADR-A が ADR-B に supersede される時
  supersedeBy(superseder: Adr): void {
    const relation = new AdrRelation(this, "superseded by", superseder);
    this.body.setHeaderMetadata("Status", relation.toMarkdown());
    superseder.markAsSuperseder(this);  // ← ADR-B 側に逆参照を自動追加
  }

  private markAsSuperseder(superseded: Adr): void {
    const relation = new AdrRelation(this, "Supersedes", superseded);
    this.body.addLinkNoDuplicate(relation.toMarkdown());  // 重複防止
  }
}

双方向 materialize の仕組み:

1. adr-A.supersedeBy(adr-B) を呼ぶ
2. adr-A の Status header が "superseded by: [adr-B-slug]" に書き換え
3. 同時に adr-B.markAsSuperseder(adr-A) 自動呼び出し
4. adr-B の Links section に "Supersedes: [adr-A-slug]" 追加 (重複防止付き)

ADR link resolver の設計決定 (log4brains ADR 20201027): markdown parsing はドメイン層責務 (infra 層ではない)。 slug と filename を分離 → rename に強い。

§5.2. Beads — 動的 context injection (Claude Code 統合 verified)

steveyegge/beads は SQLite + Dolt のデュアルストレージで Issue dependency graph を管理し、 AI agent (Claude Code 等) に動的 context を inject する。

bd setup claude    # ~/.claude/settings.json に自動登録

{
  "hooks": {
    "SessionStart": [{"command": "bd prime"}],
    "PreCompact": [{"command": "bd prime --stealth"}]
  }
}

• bd prime: 現在の issue 状態 + workflow rules を agent に注入 (~1-2k tokens、 MCP mode は ~50 tokens)
• PreCompact: context compaction 前に再注入 → 状態連続性保持
• CLAUDE.md minimal profile: static (mandate / rules) + dynamic (bd prime で real-time data 注入)

コンテキスト効率化: IssueMinimal model で ~80-95% トークン削減、 ~10-50k → ~2-5k。 9 ツール対応 (Aider / Claude Code / Cursor / Factory.ai / Gemini CLI / Mux / Junie / OpenCode / Codex CLI)。

§5.3. adr-tools (npryce) — bash 双方向

# adr new -s OLD_ID で supersede
_adr_add_link "$old_adr" "Superceded by" "$new_adr"
_adr_add_link "$new_adr" "Supercedes" "$old_adr"

# custom: TARGET:LINK:REVERSE-LINK
adr new -l "0004:Amended by:Amends"

_adr_add_link ヘルパで grep/sed/awk による markdown 操作。 MADR (Markdown ADR) 自体には自動 cross-ref 更新機能はなく、 テンプレートのみ提供 (adr-tools / log4brains 等ツール層でカバー)。

§5.4. Spectral — declarative rule (folio の lint rule 設計に応用)

extends: ["spectral:oas"]
rules:
  my-rule:
    description: "パス名は kebab-case"
    severity: warn  # error / warn / info / hint / off
    given: "$.paths[*]~"  # JSONPath
    then:
      function: pattern
      functionOptions:
        match: "^[a-z/-]+$"

severity 5 段階: error / warn / info / hint / off。 autofix は公式未対応 (validation のみ)。 Specmatic は specmatic backward-compatibility-check で非互換変更を exit 1 でブロック (folio の breaking change gate に応用可能)。

§5.5. twill plugin (folio predecessor) hook architecture

verified: ローカル file 直接読取 (/home/shuu5/projects/local-projects/twill/main/plugins/twl/hooks/hooks.json 他)。

twill hooks.json の要点抜粋:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Edit|Write|NotebookEdit",
        "hooks": [{"type": "command", "command": "pre-tool-use-worktree-boundary.sh"}] },
      { "matcher": "Bash",
        "hooks": [{"type": "command", "command": "pre-tool-use-host-safety.sh"}] },
      { "matcher": "Edit|Write",
        "hooks": [{"type": "command", "if": "Edit(deps.yaml)|Write(deps.yaml)",
                   "command": "pre-tool-use-deps-yaml-guard.sh"}] },
      { "matcher": "Edit|Write|NotebookEdit",
        "hooks": [{"type": "command", "command": "pre-tool-use-spec-write-boundary.sh"}] },
      { "matcher": "Skill",
        "hooks": [{"type": "command", "if": "Skill(phaser-*)",
                   "command": "pre-tool-use-phase-gate.sh"}] }
    ],
    "PostToolUse":        [{ "matcher": "Edit|Write|NotebookEdit", ... }],
    "PostToolUseFailure": [{ "matcher": "Bash", ... }],
    "PreCompact":         [...],
    "PostCompact":        [...]
  }
}

spec-write-boundary.sh の caller marker pattern:

caller="${TWL_TOOL_CONTEXT:-}"
case "$caller" in
  "")           exit 0 ;;           # user manual → allow
  tool-architect) ... allow + warn ;;
  *)  jq -nc '{hookSpecificOutput:{permissionDecision:"deny",...}}'; exit 0 ;;
esac

R-N 規律体系 (R-1〜R-44) — folio が継承すべき pattern:

twill 多層防御 L1-L5: L1 Skill (SKILL.md + rules) / L2 bats (unit test) / L3 PreToolUse hook + MCP tool / L4 Vale / textlint (optional) / L5 CI (spec-link-check.yml + spec-content-check.yml)。

§5.6. 5 共通設計原則 (抽出)

§6. JSON-LD validation + lint mechanism

§6.1. JSON-LD validation tool 比較

folio 推奨 2 層構成:

1. ajv (or jsonschema): JSON Schema check (@context存在・値、 @type enum、 @id URI format)
2. pyld (FrozenDocumentLoader): expansion check (unmapped property をエラー化、 context resolution offline)

§6.2. folio 用 JSON Schema 例

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["@context", "@type", "@id"],
  "properties": {
    "@context": { "type": ["string", "object", "array"] },
    "@type":    { "type": "string" },
    "@id":      { "type": "string", "format": "uri" },
    "dc:title": { "type": "string" },
    "folio:version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+" },
    "folio:depends-on": { "type": "array", "items": {...} }
  },
  "additionalProperties": true
}

§6.3. PostToolUse hook lint flow

#!/usr/bin/env bash
set -euo pipefail

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

[[ -z "$FILE_PATH" || "$FILE_PATH" != *.html ]] && exit 0
[[ ! -f "$FILE_PATH" ]] && exit 0

VALIDATION_OUTPUT=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/validate_jsonld.py" "$FILE_PATH" 2>&1)
VALIDATION_EXIT=$?

if [[ $VALIDATION_EXIT -ne 0 ]]; then
    echo "JSON-LD validation failed: $FILE_PATH" >&2
    echo "$VALIDATION_OUTPUT" >&2
    exit 2  # ← Claude が stderr を読んで修正に取り組む
fi
exit 0

§6.4. failure 挙動 3 pattern

auto-fix の安全性: idempotent + Biome の lint --write バグから学び、 まずは warn → 手動修正が安全。

§6.5. false positive 抑制 4 戦略

1. inline suppression comment: <!-- folio-lint-disable jsonld-required:dcterms:contributor --> (HTML comment、 lint script で parse)
2. severity tuning: .folio-lint.json で rule 別に error/warn/off
3. allowlist: .folio-lint-allow.json で file glob + rule 組み合わせ
4. temporal downgrade: 規約変更時は一時 warn に降格、 移行後 error 復帰

実績例: ESLint // eslint-disable-next-line + reportUnusedDisableDirectives / Ruff # noqa: E501 / golangci-lint //nolint:errcheck。

§6.6. security 考慮

• Hook は user full permission で実行、 sandbox なし
• v2.1.139+ で hooks は controlling terminal なし (/dev/tty 不可)
• shell injection 防止: subprocess.run(['python3', 'script.py', file_path], shell=False)
• --dangerously-skip-permissions でも hook は動作 (PreToolUse deny で override 可能)

§6.7. pre-commit vs PostToolUse 使い分け

[Claude Edit/Write]
    ↓ PostToolUse hook ← AI 即時 feedback (修正コスト最低)
[Claude が修正完了と判断]
    ↓ git commit
    ↓ pre-commit hook ← human + AI 両対応、 final gate (`--no-verify` 回避リスクあり)
[push]
    ↓ CI lint ← 唯一 bypass 不可

推奨: 3 つ全て併用。

§8. ADR 起票候補 (Q7 統合)

起票手順: 各 ADR について (1) user に提示 → (2) user 承認取得 → (3) scratch/decisions/ADR-NNNN-<slug>.html に Accepted status で起票 → (4) 関連 spec section に cross-ref を追加。 CLAUDE.md の制約により自動起票は禁止。

§9. Open Questions / Future Work

§9.1. WARNING (実装段階で要確認)

1. twill hooks.json の完全構成: §5.5 の抜粋は folio が継承すべき要点 pattern に絞っており、 twill の完全な hook 構成 (host-safety / deps-yaml-guard / phase-gate / failure-learn / PostCompact) は省略している。 folio 設計時に実 file (~/projects/local-projects/twill/main/plugins/twl/hooks/hooks.json) を直接参照のこと。
2. log4brains TypeScript 行番号: §5.1 の関数名 (supersedeBy / markAsSuperseder / addLinkNoDuplicate) は verified だが、 行番号は本調査範囲外。 将来 log4brains バージョンアップで実装位置が変わっても追跡可能なように、 直接 URL (Adr.ts) を保持する。
3. ADR 起票の user 承認制約: §8 の ADR-0003〜ADR-0012 は推奨候補。 folio CLAUDE.md により scratch/decisions/ 配下への新規起票は user 承認必須。 自動生成 + commit は禁止。 各 ADR を起票する前に user に提示し承認を取得する手続きを徹底する。
4. architecture/ 未存在状態と check-path-boundary.sh の対象パス: folio CLAUDE.md では architecture/ dir は Phase X3 完了後に user 主導で作成予定であり、 現時点では存在しない。 §7.2 / §7.3 の path boundary 機能は実装時に対象パスを scratch/specs/ (現状) から architecture/spec/ (Phase X3 完了後) に切替可能な userConfig 駆動の設計とすること。 例: ${FOLIO_SPEC_PATH:-scratch/specs}。

§9.2. 追加検討事項

1. 完成形 8 skill vs Phase X3 minimal 1 skill の関係: folio-self-spec.html §7.2 は完成形として 8 skill (folio-init / folio-architect / folio-spec-edit / folio-validate / review-* × 4) を定義。 本レポート §7.3 の minimal viable plugin は「1 skill (folio-architect) から着手」 を推奨。 試作駆動哲学に合致した段階的成長 (1 → 8) を意図しており、 完成形 8 skill は Phase X3 完遂後 (Phase X4+) の目標と位置付ける。
2. PreToolUse deny bug (#37210) の動作確認: §2.3 の注記で「exit 2 + stderr が確実な fallback」 と述べているが、 twill spec-write-boundary.sh は実際には exit 0 + JSON output のみ (exit 2 未使用)。 folio 実装時は Phase X3 Step 2 (boundary 強制) で empirically verify する。
3. Beads DeepWiki sources の二次性: §5.2 の Beads 記述は GitHub README (一次) + DeepWiki (AI 生成 wiki、 二次) を参照。 DeepWiki は信頼度高いが AI 生成のため、 重要設計判断は実 source code を一次資料として優先する。

§9.3. 本調査の範囲外 (将来の調査候補)

• mkdocs-material customization hooks (overrides/ dir) の詳細 — folio が SSG patterns を直接採用しないなら不要
• Prettier の HTML サポート (prettier-plugin-html) の AST 詳細 — folio HTML spec の format 統一が必要になった時点で再調査
• ESLint v9 Language Plugin (HTML/CSS 対応) — folio HTML lint に最も関連する可能性ありだが Phase X3 minimal の scope 外
• log4brains の file watcher 実装 (chokidar 等) — folio が live preview を実装する場合に調査
• folio カスタム prefix の SHACL shapes 設計 — folio vocab 確定後に検討 (現時点では JSON Schema check が先行)

§10. References

全 76 sources (公式 docs 35 + GitHub リポジトリ 14 + 技術 blog / 比較記事 23 + ローカル twill 4)。 確認日 2026-05-23。

§10.1. 公式 docs (一次資料、 35 件)

Claude Code (7 件)

1. Create plugins - Claude Code Docs
2. Plugins reference - Claude Code Docs
3. Extend Claude with skills - Claude Code Docs
4. Hooks - Claude Code Docs
5. Create custom subagents - Claude Code Docs
6. Agent Skills overview - platform.claude.com
7. Claude Code Security

Git hook frameworks (6 件)

8. pre-commit official documentation
9. Husky official documentation
10. Lefthook GitHub README
11. lint-staged GitHub README
12. simple-git-hooks GitHub README
13. pre-commit.ci official site

Linter / SSG (15 件)

14. ESLint Plugins Documentation
15. ESLint Custom Rules
16. ESLint Architecture
17. ESLint Shareable Configs
18. Stylelint Writing Plugins
19. Prettier Plugins
20. Sphinx Extension API
21. Sphinx Application API
22. Sphinx Event Callbacks API
23. MkDocs Plugin Dev Guide
24. Antora Extensions Overview
25. Antora Generator Events Reference
26. Docusaurus Plugin Lifecycle APIs
27. Backstage External Integrations
28. Backstage Life of an Entity
29. ESLint Custom Rule Tutorial

ADR / spec OSS (2 件)

30. Specmatic Backward Compatibility Rules
31. ArchUnit User Guide

JSON-LD / validation (5 件)

32. Ajv JSON schema validator
33. jsonschema Python
34. W3C SHACL Spec
35. ESLint Configure Rules
36. golangci-lint False Positives

§10.2. GitHub リポジトリ (一次ソース、 14 件)

37. thomvaill/log4brains
38. log4brains Adr.ts (TypeScript verified)
39. steveyegge/beads
40. adr/madr
41. npryce/adr-tools
42. stoplightio/spectral
43. TNG/ArchUnit
44. digitalbazaar/pyld
45. digitalbazaar/jsonld.js README
46. ajv-validator/ajv-cli
47. RDFLib/pySHACL
48. mulesoft-labs/json-ld-schema (archived 2024/01)
49. chharvey/schemaorg-jsd
50. PreToolUse permissionDecision deny ignored - Issue #37210

§10.3. 技術 blog / 比較記事 (二次資料、 23 件)

51. Git Hooks with Claude Code (dev.to)
52. Git Hook Frameworks Comparison 2026 (Andy Madge)
53. Claude Code Hooks production CI/CD patterns (Pixelmojo)
54. husky vs lefthook vs lint-staged 2026 (PkgPulse)
55. Lefthook advanced config (Evil Martians)
56. Why Pre-Commit Hooks Fail at Stopping Secrets (Xygeni)
57. log4brains ADR link resolver
58. log4brains Use Next.js for SSG
59. Beads AI Tool Integrations (DeepWiki)
60. Beads Agent Workflow Guidelines (DeepWiki)
61. Beads MCP Server (DeepWiki)
62. Beads Claude Plugin (DeepWiki)
63. Beads memory for coding agent (Ian Bull)
64. ArchUnit Baeldung intro
65. Claude Code Hooks Tutorial (Blake Crosley)
66. Claude Code Hook Control Flow (Steve Kinney)
67. Pre-commit vs CI (Sebastian Witowski)
68. Python os.replace() atomic file updates
69. Scraping JSON-LD with BeautifulSoup
70. Core Architecture lint-staged (DeepWiki)
71. Claude Code Hooks reference (eesel.ai)
72. PyLD - PyPI
73. log4brains official site (additional ADRs)

§10.4. ローカルファイル (twill plugin、 folio predecessor verified、 4 件)

74. ~/projects/local-projects/twill/main/plugins/twl/hooks/hooks.json — twill hooks.json (verified)
75. ~/projects/local-projects/twill/main/architecture/spec/gate-hook.html — twill gate-hook spec
76. ~/projects/local-projects/twill/main/plugins/twl/skills/tool-architect/refs/spec-management-rules.md — twill R-N 規律
77. ~/projects/local-projects/twill/main/architecture/decisions/ADR-0013-spec-clean-architecture.md — twill ADR-0013

§11. 調査メタデータ

調査日

2026-05-23

session_id

5592bf08

parallel researcher

5 (researcher-1〜5)

収集 sources

76 (公式 35 + GitHub 14 + 技術 blog 23 + ローカル twill 4)

critique 判定

PASS (WARNING 4 件は §9 Open Questions に反映済)

snapshot dir

/tmp/research-search-5592bf08/

前回調査との関係

本レポートは spec-graph-management-research.html (session c3c53fbb、 2026-05-22) の plugin architecture 実装局面における後続調査。 前回は spec 関係性管理 + AI agent indexing を扱い、 本回は plugin harness 設計 (hook + script + skill + CLI) を扱う。

folio 整合性

constitution P-11 (HOW 禁止)、 P-12 (Layer 0 一体配布)、 試作駆動哲学 (2026-05-22 user 確定) と整合。 ADR 起票候補は user 承認必須 (CLAUDE.md 制約)。