folio は public OSS (MIT) 化 + v1.0 stability criteria 確定 (ADR-0030 accepted) まで到達した。 並行して folio の初の実 consumer adoption (whisper project に folio-architect で folio 導入) を全ログ精読でレビューしたところ、 folio-architect の adoption-state ギャップが実証された: SKILL は「既存 spec の編集」前提で枠付けされており、 greenfield (folio 未導入 / 新規 project) の経路が無い。 結果、 init の最終判断を人間が迫られ、 constitution.html は 空 placeholder のまま "done" に到達した (folio validate は構造妥当 = clean だが中身が空虚)。 「validate clean ≠ 完成」 を露わにした failure である。
その処方を探す中で Matt Pocock の skill 群 (github.com/mattpocock/skills、 MIT) を調査した。 中核は grill-me / grill-with-docs = 「実装前に AI と執拗に 1 問ずつ対話して設計を詰める」 pattern。 これは folio 固有でなくほぼ全ての project 開発文脈で真な普遍的 upstream 活動である。 grill-with-docs は加えて (a) ubiquitous-language glossary (CONTEXT.md) の inline 更新、 (b) ADR-sparingly (3 条件)、 (c) code-cross-reference (spec-vs-code)、 (d) lazy 作成 (空 scaffold 禁止) を反射的に行う。
本 ADR は、 この authoring pattern を folio に吸収する設計を記録する。 scope = protocol/振る舞いの吸収のみ (folio の機械検証 artifact 核 = ADR-0028 deterministic floor は不変)。 timing = post-1.0 (v1.x roadmap): ADR-0030 の v1.0 criteria / bump scope は不変で、 本設計は今確定し実装は WS5 (v1.0 bump) 後に stage する。 設計は /grill-me による 1 問ずつの対話 (2026-05-27) で 8+1 論点を解決して確定した。 status = proposed (user 承認待ち); 承認で accepted へ flip する。
refs/ に MIT-attribution 付きで内包し、 folio-architect SKILL が参照する (rules 由来の write-a-skill 規律: SKILL 本体 <100 行 + refs/ で深さ)。folio-architect は何度でも安全に再起動でき、 各 run は persist 済み artifact から settled を認識し gap だけ grill する。 grill-me 先行も複数回反復も非冗長。 これは明示的「再実行モード」ではなく read-persist ループから創発する性質 (mattpocock が standalone ubiquitous-language skill の明示 re-run ロジックを deprecate し grill-with-docs の創発的 repeatability へ移行したのと同型)。 反復ごとに Phase E/F の materialize+review コストは生じるが、 これは変更単位の品質 gate であり冗長ではない。folio-init SKILL は作らない。 whisper の失敗は本質的に routing / adoption-state 問題であり、 mattpocock はそれを「1 つの適応的 skill が探索して足りないものを lazy 作成」 で解いている。 folio も同型に: folio-architect の Phase A (Discovery) を adoption-state 検出に拡張する — folio.config.yaml 不在 → greenfield → onboarding grill 分岐 (depth-elicit + constitution 原則 / overview を grill して lazy-write) / 在 → maintenance grill 分岐。folio init CLI は構造 scaffold のみに narrowing (ADR-0024 の seed 挙動を revise): dir / folio.config.yaml / README index skeleton という純粋な構造 (P-3 WHAT) だけを決定論的に生成し、 constitution 原則 / overview 本文の seed placeholder 出力は廃止する。 実体は grilling で引き出した中身がある時のみ書く (lazy)。 README index も実在ファイルのみ hasPart 宣言し、 各段階で folio validate clean を維持する。 これで whisper の空 constitution (placeholder が "done" に残る) を構造的に不可能にする。vocabulary.yaml schema は terms: [{ canonical, forbidden: [...] }] = forbidden-synonym ブロックリストのみで、 mattpocock CONTEXT.md より薄い (definition / relationships / 曖昧フラグ欠落)。 これに optional な definition / relationships / flagged_ambiguities フィールドを追加する (後方互換 — folio validate の vocabulary gate は forbidden のみ読むため既存挙動不変)。spec-review-vocabulary agent (P-5 canonical naming review) が実定義を grounding として得る。folio validate (普遍提供) / (b) 実装適合性 = 各 stack 慣習、 folio 非 mandate」 と境界を引いている。folio-architect の Phase B (Exploration) を拡張し、 consumer code も読んで spec の問いを grounding し、 spec-vs-現実の食い違いを Phase C grilling で surface する。 code は spec を研ぐ証拠として使うのであって test する gate ではない (出力は良い spec であり pass する test ではない)。| grill-with-docs 反射 | folio への翻訳 |
|---|---|
| challenge against glossary / sharpen fuzzy language | enriched vocabulary.yaml を参照 → Phase C grilling + Phase F spec-review-vocabulary |
| discuss concrete scenarios | Phase C grilling 技法 (EARS scenario と接続) |
| cross-reference with code | Phase B 拡張 (§2.6、 gate 化しない) |
| update CONTEXT.md inline | grilling 中に vocabulary.yaml / ADR を inline persist (§2.2 persist-as-you-go) |
| offer ADRs sparingly | rules.html §10.3 (§2.5) |
| lazy file creation | folio init = 構造のみ / 実体は grill 後 lazy-write (§2.3) |
意識的 scope 外: mattpocock の engineering workflow skills (to-prd / to-issues / triage / tdd / diagnose / zoom-out 等) は consumer の SDLC 関心であり folio の design-intent mandate の外ゆえ吸収しない。 folio 関連成分は grill-with-docs (grilling + glossary + ADR-sparingly + code-xref + lazy) に集約される。
folio init CLI の seed placeholder 廃止 (構造のみ)、 (4) vocabulary.yaml schema enrich、 (5) rules.html §10.3 新設、 (6) Phase B code-cross-reference 拡張。 各々に verification (sandbox scenario / e2e) を伴う。grill-me 等が何も persist しなければ settled 状態が残らない。 persist-as-you-go で緩和されるが消去はされない (mattpocock と同じ限界)。| 論点 / 案 | 採否 |
|---|---|
| protocol-only 吸収・核不変 (採用) | folio の機械検証グラフ核 = 固有資産を守りつつ著述を人間的に。 「artifact 軽量化」 「哲学から再検討」 は不採用 (核を溶かすと folio の存在意義を失う) |
| 1.0 先行 → 吸収は 1.x (採用) | v1.0 を動く標的にしない (ADR-0030 の目的)。 「吸収を 1.0 前提に (ADR-0030 改訂)」 「判断保留」 は不採用 |
| grilling を folio 自前所有 (採用) | 配布 plugin ゆえ外部 skill 依存 (delegate) は脆い。 spec-aware に folio 化 |
| folio-init 分離撤回・architect 統合 (採用) | whisper の routing gap を単一適応 skill で解消 (mattpocock の lazy-adaptive と整合)。 「別 skill 分離維持 (前 lock)」 「1 skill 2 mode 明示引数」 は不採用 (前者は routing 別途要 / 後者は人間判断が残る) |
| glossary = vocabulary.yaml を enrich (採用) | 単一 SSoT + config ゆえ grilling 中 inline 追記可。 「HTML glossary SSoT + yaml projection」 は P-2 最適だが inline 更新が重く不採用、 「discipline のみ」 は定義を永続化せず不採用 |
| code-cross-reference = Phase B technique のみ (採用) | ADR-0026 の実装適合性境界を守る。 「spec-review-drift agent 新設」 は境界侵犯リスクで不採用、 「scope 外」 は grill-with-docs の価値を捨てるため不採用 |
| 合成 = gap-driven + persist-as-you-go (採用) | mattpocock 自身が durable artifact-reading で解いており忠実。 「明示 design-brief 入力」 「folio-grill 別 skill 分離」 は不採用 (前者は brief 形式規定要 / 後者は skill 再 2 本化) |
folio-architect の adoption-state ギャップ + 空 constitution failure を実証 → mattpocock grill-me / grill-with-docs 調査 (doobidoo 3eb9160f / 5a8f6e53、 repo mattpocock-skills MIT)。/grill-me 対話 (2026-05-27、 1 問ずつ + 推奨回答) で 8+1 論点を解決 — 吸収 scope / v1.0 関係 / grill 自前所有 / init lazy / glossary enrich / ADR-worthiness / code-xref 境界 / skill 統合 / 合成 (gap-driven + persist-as-you-go + 創発 repeatability)。