folio self-spec

§1. 2-Layer Architecture (物理 repo 分離)

folio は物理 repo を 2 層に分離する: Layer 0 (本 repo) が rules (constitution + rules.html) と plugin harness を一体配布し (P-12)、 Layer 1 consumer は別 git repo で spec と実装の両方を持つ。 consumer は repo root の folio.config.yaml で明示的に folio を consume し、 folio constitution + rules を継承する (convention-based discovery は不採用、 P-3)。

folio は 2 layer の物理 repo 分離を採用する。 folio 自身は Layer 0 (META FRAMEWORK) を提供し、 Layer 1 (各 project の architecture spec + 実装) は別 git repo として展開する。 Layer 0 は rules (constitution + rules.html) と plugin harness (.claude-plugin/) を一体配布する (constitution P-12)。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#2a4d6e', 'primaryTextColor': '#ffffff'}}}%%
graph TB
  accTitle: 2-Layer 詳細構造 + plugin harness
  accDescr: Layer 0 folio は rules と plugin harness を一体提供する。 Layer 1 consumer projects は folio.config.yaml で folio を consume する
  subgraph L0["Layer 0 — folio (本 repo)"]
    direction TB
    subgraph L0R["rules"]
      C["constitution.html"]
      R["rules.html"]
      FSS["folio-self-spec.html (本書)"]
    end
    subgraph L0H[".claude-plugin/ — harness"]
      PJ["plugin.json"]
      SKAH["skills + agents + hooks"]
      SCBN["scripts + bin"]
    end
  end
  subgraph L1["Layer 1 — consumer project (例)"]
    direction TB
    L1CONF["folio.config.yaml"]
    L1ARCH["architecture/spec/
(Layer 1 spec、 folio rules で書かれた)"]
    L1IMPL["実装 dir
(src/、 skills/、 等)"]
  end
  L0 -->|"install + consume"| L1CONF
  L1CONF -.->|"defines"| L1ARCH
  L1ARCH -.->|"guides"| L1IMPL
  style L0 fill:#2a4d6e,color:#ffffff
  style L0R fill:#5ac8b8,color:#08131a
  style L0H fill:#5ac8b8,color:#08131a
  style L1 fill:#fefbea,color:#08131a

Resolution flow: Layer 1 consumer が folio.config.yaml で folio plugin (rules + harness) を consume する。 spec は project repo 内 architecture/spec/ に存在し、 folio constitution + rules を継承する。

Discovery mechanism: explicit (各 project repo root の folio.config.yaml で folio を consume する宣言)。 convention-based discovery は採用しない。 folio repo 自身は下流 consumer を識別しない (constitution P-3)。

§2. folio repo Layout (Layer 0)

folio repo の canonical layout: architecture/ (design-intent 空間 = spec / decisions / research / assets)、 tests/ (HOW-test sibling)、 hooks/ + .claude-plugin/ (plugin harness)、 root marker file。 folio は自身の rules を self-host し、 consumer と一意の構造を取る (X4-C 物理移植、 ADR-0022)。 下の tree と図がディレクトリ構成の SSoT。

folio/
├── FOLIO.md                          # root marker (Markdown 例外、 P-2)
├── README.md                         # GitHub 表示用 (Markdown 例外、 P-2)
├── CLAUDE.md                         # AI-agent instruction (Markdown 例外、 P-2、 P-11 root 例外)
├── common.css                        # design tokens
├── .gitignore
│
├── architecture/                     # folio 自身の design-intent 空間 (self-host、 P-7 3-domain)
│   ├── index.html                    # landing + walkable nav (folio build が graph から生成、 hero は curated、 ADR-0035/0039)
│   ├── glossary.html                 # 用語集 (folio build が vocabulary.yaml から生成、 ADR-0036)
│   ├── spec/                         # design intent (WHAT)。 全ページ chrome は build が marker 領域で維持 (ADR-0039 §2.3)
│   │   ├── README.html               # spec entry point (P-6)
│   │   ├── constitution.html         # 14 immutable principles (P-1〜P-14)
│   │   ├── rules.html                # Layer 1 consumer 向け universal rules
│   │   ├── folio-self-spec.html      # 本書 — folio 自身の self-spec
│   │   ├── relations.html            # spec 間関係性 (JSON-LD + inventory)
│   │   └── verification.html         # verification contract
│   ├── decisions/                    # decision (WHY): ADR-NNNN-<slug>.html
│   ├── research/                     # exploration (spec 反映前の探索)
│   └── assets/                       # mermaid.min.js (support、 domain でない)
│
├── tests/                     # HOW-test sibling (executable、 P-3/P-11、 ADR-0022)
│   ├── scenarios/                    # use case 別 YAML
│   ├── fixtures/  baselines/  e2e/   # テストデータ / golden / 統合検証
│   └── runner.sh                     # 軽量 runner (bash + yq + jq)
│
├── hooks/                            # Claude Code 公式仕様: plugin root 直下 MUST
│   └── hooks.json                    # hook 宣言 (PreToolUse / PostToolUse / SessionStart)
│
└── .claude-plugin/                   # plugin harness (P-12 一体配布、 HOW)
    ├── plugin.json                   # manifest (name, version, userConfig)
    ├── skills/                       # folio-architect 等 (完成形 §7.2)
    ├── agents/                       # specialist agents (完成形 §7.2)
    ├── scripts/                      # hook script 実装 (CI check)
    ├── bin/                          # CLI: folio version / init / inventory / prime / validate / fix / build
    ├── refs/                         # skill + agent 共有 reference
    └── static/                       # plugin-bundled static assets

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#2a4d6e', 'primaryTextColor': '#ffffff'}}}%%
graph TD
  accTitle: folio Repository Layout (Layer 0, canonical self-host)
  accDescr: folio repo は architecture/ (spec/decisions/research/assets の design-intent 空間) と tests/ (HOW-test sibling) と hooks/ + .claude-plugin/ (HOW harness) と root marker file が並ぶ
  ROOT["folio/"]
  ROOT --> ARCH["architecture/
(design-intent 空間)"]
  ROOT --> VER["tests/
(HOW-test sibling)"]
  ROOT --> HK["hooks/
(hooks.json)"]
  ROOT --> PLUGIN[".claude-plugin/
(plugin harness, HOW)"]
  ROOT --> MD["root marker
(FOLIO.md / README.md /
CLAUDE.md / common.css)"]
  ARCH --> SPEC["spec/ (WHAT)
constitution / rules /
folio-self-spec /
relations / verification"]
  ARCH --> DEC["decisions/ (WHY)
ADR-NNNN-*"]
  ARCH --> RES["research/
(exploration)"]
  ARCH --> AST["assets/
(mermaid, support)"]
  PLUGIN --> BN["bin/
(validate / fix / build /
init / inventory / prime)"]
  PLUGIN --> SCM["scripts/ skills/
agents/ refs/ static/"]
  style ROOT fill:#2a4d6e,color:#ffffff
  style ARCH fill:#5ac8b8,color:#08131a
  style VER fill:#fefbea,color:#08131a
  style PLUGIN fill:#5ac8b8,color:#08131a

§7. Harness Layer Components

本 §7 は folio Layer 0 の plugin harness を構成する 5 component を informative に解説する: 7-phase PR cycle (§7.1)・specialist agents (§7.2)・caller marker (§7.3)・5-Layer Defense (§7.4)・CI Gate (§7.5)。 各 component が連携して folio rules を enforce する。 規範 MUST 要件 (caller marker set/unset・CI gate enforcement) の SSoT は rules.html §10 Mandatory Actions にあり、 本 §7 は設計と enforcement flow を解説する。

本 §7 は folio Layer 0 の plugin harness を構成する 5 component を規定する。 7-phase PR cycle (§7.1) の各 phase で specialist agents (§7.2)、 caller marker (§7.3)、 5-Layer Defense (§7.4)、 CI Gate (§7.5) が連携し、 folio rules を enforce する。

規範要件と informative design の分離: §7 全体は informative design intent を記述する。 規範 MUST 要件 (caller marker set/unset MUST、 CI gate enforcement MUST) は rules.html §10 Mandatory Actions に集約する。 本 §7 では各 component の設計と enforcement flow を informative に解説する。

§7.1 7-Phase PR Cycle (folio-architect SKILL)

folio-architect は spec edit の唯一 author で、 7 phase (A Discovery → B Exploration → C Clarifying → D Design → E Implementation → F Quality Review → G Summary) を順次実行する。 Phase C (grilling) と F (review) は MUST NOT SKIP、 B/D は specialist 並列、 F は review agent 並列 (下表・図 4 の「F 7 並列固定」は完成形 vision で、 v1.0 実装は 5 agent — §7.2)。 v1.0 scope は ADR-0029 で確定し、 Phase A/B/C の adoption-aware 化は ADR-0031 による (下表・図・aside で詳説)。

folio-architect は spec edit の唯一 author。 7 phase (A〜G) を順次実行する。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#2a4d6e', 'primaryTextColor': '#ffffff'}}}%%
flowchart TB
  accTitle: 7-Phase PR Cycle
  accDescr: Discovery A から Summary G まで 7 phase を順次実行。 Phase B と D は 2-3 specialist 並列、 Phase F は 7 specialist 並列固定
  A["A
Discovery"]
  B["B
Exploration
(2-3 並列)"]
  C["C
Clarifying
(MUST NOT SKIP)"]
  D["D
Design
(2-3 並列、 optional)"]
  E["E
Implementation
(caller marker)"]
  F["F
Quality Review
(7 並列固定)"]
  G["G
Summary
(delta marker)"]
  A --> B --> C --> D --> E --> F --> G
  style A fill:#2a4d6e,color:#ffffff
  style C fill:#fefbea,color:#08131a
  style F fill:#fdf3f3,color:#08131a
  style G fill:#5ac8b8,color:#08131a

§7.2 Specialist Agents (9 個)

完成形 vision の 9 agent (= Phase B explorer 1 + Phase D architect 1 + Phase F review 7 軸) を下表に列挙する。 v1.0 で実装するのは Phase F の 5 review agent (ears / vocabulary / ssot / temporal / fidelity)。 spec-review-structure は folio validate 被覆ゆえ cut、 explorer / architect / stakeholder は post-1.0 defer (削除でなく将来 opt-in の anchor として table に残す、 ADR-0029)。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#2a4d6e', 'primaryTextColor': '#ffffff'}}}%%
flowchart LR
  accTitle: Specialist Agents 並列 spawn (Phase B / D / F)
  accDescr: Phase B では spec-explorer を 2-3 並列、 Phase D では spec-architect を 2-3 並列 (optional)、 Phase F では spec-review 7 個を並列固定で spawn する
  subgraph PB["Phase B — 2-3 並列"]
    SE1["spec-explorer #1"]
    SE2["spec-explorer #2"]
    SE3["spec-explorer #3"]
  end
  subgraph PD["Phase D — 2-3 並列 (optional)"]
    SA1["spec-architect #1
(minimal)"]
    SA2["spec-architect #2
(clean)"]
    SA3["spec-architect #3
(pragmatic)"]
  end
  subgraph PF["Phase F — 7 並列固定"]
    R1["review-vocabulary"]
    R2["review-structure"]
    R3["review-ssot"]
    R4["review-temporal"]
    R5["review-ears"]
    R6["review-stakeholder"]
    R7["review-fidelity"]
  end
  style PB fill:#e6f6f2,color:#08131a
  style PD fill:#fefbea,color:#08131a
  style PF fill:#fdf3f3,color:#08131a

§7.3 Caller Marker

caller marker は AI agent が現在 spec edit 中であることを宣言する env var で、 .claude-plugin/hooks/ の PreToolUse hook が値を check し、 未 set / 異値なら spec_path 配下 file の編集を block する。 set / unset の MUST 要件は rules.html §10.1 (REQ-CM-001〜003)、 本 §7.3 は enforcement flow (下図) を informative に解説する。

spec edit を行う AI agent が caller marker を set / unset すべき MUST 要件は rules.html §10.1 (REQ-CM-001〜003) に規定する。 本 §7.3 は PreToolUse hook による enforcement flow chart (下図) を informative に解説する。

caller marker は AI agent が現在 spec edit 中であることを宣言する。 .claude-plugin/hooks/ の PreToolUse hook が env var を check し、 未 set または異なる値の場合は spec 配下 file の編集を block する。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#2a4d6e', 'primaryTextColor': '#ffffff'}}}%%
flowchart TD
  accTitle: PreToolUse Hook による caller marker enforcement flow
  accDescr: Edit/Write ツール呼び出し時、 PreToolUse hook が caller marker env var 存在と spec_path 配下 file かを check し、 caller marker 未 set の場合 deny する
  TE["ToolUse attempt
(Edit / Write / NotebookEdit)"]
  TE --> HK["PreToolUse hook
(.claude-plugin/hooks/)"]
  HK --> SP{"target file
spec_path 配下?"}
  SP -- "No" --> AL["allow
(spec 外 edit OK)"]
  SP -- "Yes" --> CC{"caller marker
env var set?"}
  CC -- "No / 異値" --> DN["deny
(permissionDecision: deny)"]
  CC -- "Yes" --> AL2["allow
(spec edit OK)"]
  style DN fill:#fdf3f3,color:#08131a
  style AL fill:#e6f6f2,color:#08131a
  style AL2 fill:#e6f6f2,color:#08131a

§7.4 5-Layer Context Boundary Defense (3 axis)

AI agent が混同し得る 3 つの context boundary — (a) folio vs 旧 twill、 (b) folio (Layer 0) vs consumer (Layer 1)、 (c) Layer 1 の spec edit vs 実装 edit — を、 5 層の防御 (物理 git repo 分離 / root marker / HTML meta 宣言 / caller marker env var / directory naming) が pipeline で構造的に防ぐ。 5 層全てを通過した時のみ正しい layer の spec を編集できる (下表・図で詳説)。

AI agent は以下の 3 つの context boundary を混同し得る。 本 §7.4 はこれを構造的に防ぐ 5 層の boundary mechanism を informative に解説する:

• (a) folio (Layer 0) vs 旧 twill plugin (reference のみ)
• (b) folio (Layer 0、 本 repo) vs consumer projects (Layer 1、 別 repo)
• (c) Layer 1 spec edit (architecture/spec/) vs Layer 1 実装 edit (src/、 skills/ 等)

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#2a4d6e', 'primaryTextColor': '#ffffff'}}}%%
flowchart TB
  accTitle: 3 axis × 5 層防御 pipeline
  accDescr: 3 軸の混同リスク (folio vs twill、 folio vs consumer、 spec edit vs impl edit) に対し 5 層の防御 (物理分離、 root marker、 meta 宣言、 caller marker、 directory naming) が pipeline で適用される
  subgraph AX["3 axis 混同リスク"]
    A1["(a) folio vs twill"]
    A2["(b) folio vs consumer"]
    A3["(c) spec edit vs impl edit"]
  end
  subgraph DEF["5 層防御 pipeline"]
    direction TB
    L1["L1
物理 git repo
分離"]
    L2["L2
root marker
file"]
    L3["L3
HTML meta
宣言"]
    L4["L4
caller marker
env var"]
    L5["L5
directory
naming"]
    L1 --> L2 --> L3 --> L4 --> L5
  end
  AX --> DEF
  style AX fill:#fefbea,color:#08131a
  style DEF fill:#e6f6f2,color:#08131a

§7.5 CI Gate Specification

CI workflow が強制する 7 gate (link-integrity / declarative-form / what-only / vocabulary / EARS coverage / delta-marker / json-ld-validation) の MUST 要件は rules.html §10.2 にある。 ADR-0028 二層 enforcement で、 機械化可能部は deterministic floor (folio validate)、 意味的残余は LLM ceiling (Phase F agent) に分担する。 EARS coverage のみ warn 扱い (下図・aside で詳説)。

CI workflow が強制すべき 7 gate の MUST 要件は rules.html §10.2 (REQ-CI-001 + REQ-CI-010〜016) に規定する。 本 §7.5 は各 gate の script 実装参照 (.claude-plugin/scripts/) を informative に解説する。 具体的 script 実装は §9 Bindings に集約。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#2a4d6e', 'primaryTextColor': '#ffffff'}}}%%
flowchart TB
  accTitle: CI Gate Pipeline
  accDescr: PR / commit から merge までの 7 gate (link integrity、 declarative form、 what-only、 vocabulary、 EARS coverage、 delta marker consistency、 json-ld-validation) を順次通過した場合のみ merge 許可
  PR["PR / push"]
  PR --> G1["link-integrity
(P-6)"]
  G1 --> G2["declarative-form
(P-4)"]
  G2 --> G3["what-only
(P-3 / P-11)"]
  G3 --> G4["vocabulary
(P-5)"]
  G4 --> G5["EARS coverage
(§6)"]
  G5 --> G6["delta marker
consistency
(§5)"]
  G6 --> G7["json-ld-validation
(relations §3)"]
  G7 --> OK["merge allowed"]
  G1 -. "fail" .-> BL["merge blocked"]
  G2 -. "fail" .-> BL
  G3 -. "fail" .-> BL
  G4 -. "fail" .-> BL
  G5 -. "warn" .-> OK
  G6 -. "fail" .-> BL
  G7 -. "fail" .-> BL
  style OK fill:#5ac8b8,color:#08131a
  style BL fill:#fdf3f3,color:#08131a

§7.6 Phase X3 Minimal Implementation

試作段階 (Phase X3) の plugin minimal scope = 1 skill + 4 hook + 6 script + 1 CLI (WHAT enumeration の SSoT は ADR-0003 §2)。 段階的成長 path: 1 skill (X3) → 3 review agent (X4) → 5 review agent v1.0 (X5-γ + ADR-0033) → 9 agents 完成形 vision (post-1.0)。 §7.2 完成形は未来 anchor として保持し、 実機検証は verification.html sandbox で行う。

Phase X3 minimal viable plugin scope = 1 skill + 4 hook + 6 script + 1 CLI。 各 component の詳細 enumeration および役割 (WHAT) は ADR-0003 §2 Decision を SSoT として参照する MUST (本 §7.6 は ADR-0003 への entry point + 段階的成長 path 規定のみを担う、 detailed table の重複定義は禁止)。

段階的成長 path: 1 skill (Phase X3) → 7-Phase SKILL + 3 review agent (Phase X4) → 5 review agent v1.0 (Phase X5-γ + ADR-0033) → 9 agents 完成形 vision (post-1.0) (X4-D で 3 review agent ears/vocabulary/ssot、 ADR-0027; X5-γ で temporal 追加・spec-review-structure は folio validate 被覆ゆえ cut・spec-explorer/spec-architect/spec-review-stakeholder は post-1.0 defer、 ADR-0029; dual-audience spec-review-fidelity ceiling 追加、 ADR-0033)。 試作で発見した修正点 / 必要追加機能を spec に逐次反映する。 具体的 binding (script 内容 / CLI 構文) は §9 Bindings に隔離。

本 minimal plugin の実機検証は verification.html (sandbox verification framework) で実施する。 verification scope の段階的対比 (完成形 §7.2 vs 試作段階 §7.6) は verification.html §4.2 に集約 (SSoT)。

§8. Plugin Integration (Claude Code plugin としての folio)

folio は Claude Code plugin として配布される (P-12)。 公式 plugin spec に準拠した manifest (plugin.json) + component layout を採用し、 consumer は folio.config.yaml で userConfig default (spec_path / caller_marker 等) を override できる。 配布は Git marketplace + semver pinning。 §8.1〜§8.3 で schema・override 機構・distribution を解説する。

folio は Claude Code plugin として配布される (constitution P-12)。 公式 plugin spec (docs.claude.com/en/plugins) に準拠した manifest + component layout を採用する。

§8.1 plugin.json schema

下の plugin.json が manifest schema: name / version / description / homepage + userConfig (spec_path・caller_marker_env・caller_marker_value・review_model) を宣言する。 実 plugin.json は spec_path default を canonical architecture/spec/ とし、 各 userConfig に title field を持つ (claude plugin validate 要件)。

{
  "name": "folio",
  "version": "0.5.0-draft",
  "description": "folio Layer 0 META FRAMEWORK — universal architecture spec-writing rules + Claude Code plugin harness.",
  "homepage": "https://github.com/shuu5/folio",
  "userConfig": {
    "spec_path": {
      "type": "string",
      "default": "architecture/spec/",
      "description": "Relative path (from consumer project root) where folio-managed spec HTML files live."
    },
    "caller_marker_env": {
      "type": "string",
      "default": "FOLIO_ARCHITECT_CONTEXT",
      "description": "Environment variable name that AI agent must set before editing files under spec_path."
    },
    "caller_marker_value": {
      "type": "string",
      "default": "folio-architect",
      "description": "Expected value of the caller marker env var."
    },
    "review_model": {
      "type": "string",
      "default": "opus",
      "description": "LLM model for Phase F specialist review agents."
    }
  }
}

注: 実 plugin.json は spec_path default を canonical architecture/spec/ とする (folio 自身の self-host、 X4-C で scratch/specs/ 暫定 override から物理移植済、 ADR-0023)。 また実 plugin.json は各 userConfig に title field を持つ (claude plugin validate 要件)。

§8.2 userConfig override mechanism

各 Layer 1 consumer project は folio.config.yaml で plugin.json userConfig の default を override できる (下の例: spec_path / caller_marker_env / caller_marker_value の上書き)。

各 Layer 1 consumer project は folio.config.yaml で plugin.json userConfig の default を override 可能。 例:

folio_version: "^0.4"
spec_path: ".folio/spec/"          # default architecture/spec/ を上書き
caller_marker_env: "MY_PROJECT_CTX" # default FOLIO_ARCHITECT_CONTEXT を上書き
caller_marker_value: "spec-editor"

§8.3 distribution

配布は Git marketplace + semver pinning (shuu5/folio#v0.5.0)。 1.0.0 未満は development phase として MAJOR/MINOR/PATCH boundary を緩和する (constitution §5)。 npm / pip 配布は scope 外 (Claude Code plugin protocol 中心)。

• Git marketplace + semver pinning: shuu5/folio#v0.5.0
• 1.0.0 未満は development phase として MAJOR/MINOR/PATCH boundary 緩和 (constitution §5)
• npm / pip 配布は scope 外 (Claude Code plugin protocol 中心)

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#2a4d6e', 'primaryTextColor': '#ffffff'}}}%%
flowchart TB
  accTitle: Plugin Integration Flow
  accDescr: consumer project が folio.config.yaml で folio plugin を consume すると、 Claude Code が plugin.json から skills + agents + hooks を load し、 PreToolUse hook で caller marker enforce が起動する
  CP["consumer project
folio.config.yaml
(folio_version: ^0.4)"]
  CC["Claude Code"]
  PJ["folio plugin
plugin.json"]
  SK["skills/
load"]
  AG["agents/
load"]
  HK["hooks/
register"]
  CP --> CC
  CC --> PJ
  PJ --> SK
  PJ --> AG
  PJ --> HK
  HK -.-> PRE["PreToolUse hook
(caller marker enforce、 §7.3)"]
  HK -.-> POST["PostToolUse hook
(spec validate、 §7.5)"]
  style CP fill:#fefbea,color:#08131a
  style PJ fill:#2a4d6e,color:#ffffff
  style PRE fill:#5ac8b8,color:#08131a
  style POST fill:#5ac8b8,color:#08131a