book-writing-workspace

書籍執筆ワークスペース

フォルダ、執筆エージェント、指示、レビュールール、およびオプションの Markdown -> Re:VIEW -> PDF サポートを備えた、再利用可能な原稿ワークスペースを作成・維持します。

使用する場面

• 書籍執筆、テクニカルライティング、執筆プロジェクト、Re:VIEW
• 既存の書籍原稿リポジトリの評価または標準化
• 必要に応じてテンプレートから新しいテクニカルライティングプロジェクトを作成
• Markdown → Re:VIEW → PDF ワークフローのセットアップ
• Re:VIEW 出力と印刷可能な PDF を生成できるように、既存の原稿ワークスペースをアップグレード
• 章・節のファイル構成、執筆ルール、レビューワークフロー、ページ配分の標準化
• 執筆ワークスペースを汎用の Git や出版運用ツールキットにすることなく、オプションの Re:VIEW/PDF サポートを追加

クイックスタート

新しいプロジェクトを作成する場合でも、まず原稿ワークスペースを評価してください：

1. メイン原稿が sections/ にあり、1 節につき 1 ファイルを使用していることを確認します。
2. アウトラインや要点が最終原稿ファイルとは別に存在することを確認します。
3. 章のイントロファイルがケバブケースの命名（例：00-introduction/00-introduction.md）を使用していることを確認します。
4. ワークスペースで宣言された読者ペルソナの SSOT を特定します。既存の概要や計画ドキュメントがすでにそれを担っている場合、新しいファイルを無理に作成しないでください。
5. 新しいワークスペースでは、docs/reader-personas.md を使用して、プライマリペルソナ、セカンダリペルソナ、事前知識、完了時の成果を定義します。
6. 執筆、見出し、表記、ページ配分、レビューのルールが利用可能であることを確認します。
7. このプロジェクトに Re:VIEW/PDF 出力が必要かどうかを判断します。ワークフローが要求しない限り、オプションのままにしておきます。

運用ワークフロー

ワークスペースがすでに存在する場合、セットアップ指向の助言で止まらないでください。このスキルは以下もサポートする必要があります：

1. 原稿フォルダと節の命名を正規化します。
2. アウトライン、下書き、最終原稿、画像を章ごとに揃えた状態に保ちます。画像が属する章は、そのファイル名の接頭辞ではなく、それを参照する節から解決します。スクリーンショットについては、キャプチャされた状態のみを説明し、読者に不要な空または利用不可の値は省略します。画像の可視ラベルを説明する前に、その画像を紹介します。「第 N 章で扱う」といった相互参照は、図の中ではなく本文に記載します。
3. P1/P2 の問題が解決するまで、集中した執筆とレビューのループを実行します。
4. アウトライン、章マップ、質問ダイジェスト、進捗トラッカーを同期から外さずに、レビュアーの修正を適用します。
5. 各章を、書籍固有の読者ペルソナと期待される成果に照らしてレビューします。
6. テキストを確定する前に、語数目標とソースの信頼性を確認します。
7. ページ予算の超過を構造的な問題として扱う前に、ビルド後のページ数を測定します。文字数による見積もりは過大になりやすく、著者側のビルドは出版社の印刷ページ数ではありません。
8. 外部の Issue、プルリクエスト、出版社の校正コメントを 1 点ずつ判定し、まず校正がどのリビジョンから組版されたかを確認してから、各事実主張をその信頼できる情報源に照らして検証します。
9. 章扉など組版専用の要素について、著者が執筆することが確定したら、原稿内に信頼できる情報源を設け、コンバーターがそれを出力できるようにマークを付けます。
10. 著者紹介ページを出版契約の一部として扱います。その著者順、表示名、役割、確認済みプロフィール、リンクを、構造マップ、メタデータ、表紙、奥付と揃えた状態に保ちます。欠落している経歴の詳細をでっち上げないでください。著者が確認するまで暫定テキストとして追跡し、著者数が変わったときは表紙の折り返しを視覚的に検証します。
11. プロジェクトが再現可能な出力を必要とする場合にのみ、Re:VIEW/PDF サポートを有効にします。
12. リリース候補を凍結し、納品または出版の前にリリース準備ゲートを実行します。

ブートストラップワークフロー

セットアップスクリプトは、新しいワークスペースを作成する場合、または不足している構造を意図的に追加する場合にのみ使用してください。

python scripts/setup_workspace.py --name "project-name" --title "Book Title" --path "<parent-dir>" --chapters 8  # add --with-review only when Re:VIEW/PDF is needed

すべてのオプション: references/setup-workflow.md。

1. 情報を収集: プロジェクト名、タイトル、場所、章数
2. スクリプトを実行: scripts/setup_workspace.py
3. 出力を確認: README、エージェント、instructions、docs が作成されたことを確認
4. カスタマイズ: docs/reader-personas.md、docs/page-allocation.md、docs/schedule.md、.github/copilot-instructions.md を編集します。--with-review を使用する場合は、config/review-metadata/project.yml もカスタマイズします。

Git ワークフローはプロジェクト固有です。ここに汎用的なコミット/プッシュのプロンプトを追加しないでください。リポジトリに既存のバージョン管理の慣習に従ってください。

メタデータ、マイグレーション、コンバーターの検証、および同期バックのルールは references にあります。メインの SKILL は原稿の構造と執筆ワークフローに集中させてください。

生成されるワークスペース

• keypoints/、sections/、images/ 配下の原稿フォルダー
• .github/agents/ および .github/instructions/ 配下の AI ワークフローファイル
• README.md、docs/reader-personas.md、docs/page-allocation.md、docs/schedule.md、docs/release-readiness-record.md などのプロジェクトドキュメント
• scripts/count_chars.py などのヘルパースクリプト（このスキルの templates/scripts/ からコピーされます）
• --with-review を使用する場合のオプションの Re:VIEW スクリプトとメタデータ

推奨される執筆単位

• デフォルトの原稿単位として 1 ファイル = 1 セクション を使用します。
• 章のイントロは {NN}-{slug}/{NN}-{slug}.md に置き、セクションファイルをその横に並べます。
• PDF/Re:VIEW 出力では、見出しレベルが階層を定義しますが、ファイル分割は主に執筆とレビューのワークフローを改善します。

エージェントの概要

エージェント	役割	デフォルト
@writing	原稿の執筆と編集	はい
@writing-reviewer	原稿のレビュー（P1/P2/P3）	はい
@converter	Markdown から Re:VIEW への変換	--with-review の場合のみ

依存関係

ツール	目的	必須
Python 3.8+	スクリプト	はい
Git	バージョン管理	はい
Docker	Re:VIEW PDF ビルド	オプション、--with-review の場合のみ

リファレンスマップ

トピック	リファレンス
フォルダー構造	references/folder-structure.md
セットアップワークフロー	references/setup-workflow.md
カスタマイズポイント	references/customization-points.md
外部レビュー	references/external-review-handling.md
Re:VIEW / PDF のヒント	references/review-pdf-tips.md
スクリーンショットのキャプチャ	references/screenshot-capture.md
リリース準備	references/release-readiness-review.md

オプションのビルドパイプライン

変換や PDF レンダリングを追加するワークスペースでは、ビルドパイプラインゲートを適用してください。プロジェクト固有のコマンド、依存関係のバージョン、フォーマッタールールは、生成されたワークスペースに保持してください。

完了条件

• ワークスペースのフォルダー構造が作成されている
• 執筆エージェントとレビューエージェントが .github/agents/ に配置されている
• 読者ペルソナの SSOT が 1 つ選択されている。新しいワークスペースではプレースホルダーなしの docs/reader-personas.md を使用する
• docs/page-allocation.md が設定されている
• docs/release-readiness-record.md がリリース候補向けに利用可能である
• README.md と docs/schedule.md がカスタマイズされている
• 原稿ファイルが章・節の命名規則に従っている
• 著者紹介、メタデータ、表紙、奥付で著者の順序と表示名が一致している。暫定プロファイルはリリース可能として扱われていない
• scripts/count_chars.py が対象の原稿ファイルに対して動作する
• 必須のテンプレート、スクリプト、アセットが欠落している場合、セットアップは変更を加える前に失敗する
• クリーンな一時ディレクトリでのスモークテストが docs/reader-personas.md を生成し、正常終了する
• スモークテストは docs/release-readiness-record.md も生成し、タイトルを展開し、Gate 8 の行とマニフェストロックのフィールドを含める
• Re:VIEW/PDF 出力が明示的にスコープ外であるか、有効化されて検証済みである