book-writing-workspace · git:20260714.b614d87 · 2026-07-14 · sha256 e6bd2ec12d82494a
book-writing-workspace git:20260714.b614d87A

Name: book-writing-workspace
Author: aktsmm
Immutable. This exact content is served forever at /api/v1/blob/e6bd2ec12d82494a.
---
name: book-writing-workspace
description: "Operate a reusable technical book manuscript workspace with writing structure, reader persona SSOT, review rules, and optional Markdown to Re:VIEW/PDF support. Use when organizing a book manuscript repo, defining or reviewing target readers, standardizing chapter/section files, setting writing/review agents, or assessing an existing writing workspace. Triggers on book writing workspace, reader persona, reader audience, 読者ペルソナ, persona SSOT, technical book project, 執筆ワークスペース, manuscript workflow, and Re:VIEW workspace."
argument-hint: "本のテーマ、原稿リポジトリ名、使いたい執筆フロー"
user-invocable: true
license: CC BY-NC-SA 4.0
metadata:
  author: yamapan (https://github.com/aktsmm)
---

# Book Writing Workspace

Create and maintain a reusable manuscript workspace with folders, writing agents, instructions, review rules, and optional Markdown -> Re:VIEW -> PDF support.

## When to use

- **Book writing**, **technical writing**, **執筆プロジェクト**, **Re:VIEW**
- Assessing or standardizing an existing book manuscript repository
- Creating a new technical writing project from templates when needed
- Setting up Markdown → Re:VIEW → PDF workflow
- Upgrading an existing manuscript workspace so it can generate Re:VIEW output and printable PDFs
- Standardizing chapter/section file layout, writing rules, review workflow, and page allocation
- Adding optional Re:VIEW/PDF support without turning the writing workspace into a general Git or publishing operations toolkit

## Quick Start

Start by assessing the manuscript workspace, even when creating a new project:

1. Confirm the main manuscript lives in `sections/` and uses one file per section.
2. Confirm outlines or key points live separately from final manuscript files.
3. Confirm chapter intro files use kebab-case naming (e.g. `00-introduction/00-introduction.md`).
4. Locate the workspace's declared reader-persona SSOT; do not force a new file when an existing overview or planning document already owns it.
5. For a new workspace, use `docs/reader-personas.md` to define the primary persona, secondary personas, prior knowledge, and completion outcomes.
6. Confirm writing, heading, notation, page allocation, and review rules are available.
7. Decide whether Re:VIEW/PDF output is needed for this project; keep it optional unless the workflow requires it.

## Operating Workflow

When the workspace already exists, do not stop at setup-oriented advice. This skill should also support:

1. Normalizing manuscript folders and section naming.
2. Keeping outlines, drafts, final manuscript, and images aligned by chapter.
3. Running focused writing and review loops until P1/P2 issues are resolved.
4. Applying reviewer fixes without leaving outlines, chapter maps, question digests, and progress trackers out of sync.
5. Reviewing each chapter against the book-specific reader persona and expected outcome.
6. Checking word count targets and source confidence before finalizing text.
7. Enabling Re:VIEW/PDF support only when the project needs reproducible output.

## Bootstrap Workflow

Use the setup script only when creating a new workspace or adding missing structure deliberately.

```powershell
python scripts/setup_workspace.py `
  --name "project-name" `
  --title "Book Title" `
  --path "D:\target\path" `
  --chapters 8

# Include Re:VIEW/PDF scaffolding only when needed.
python scripts/setup_workspace.py `
  --name "project-name" `
  --title "Book Title" `
  --path "D:\target\path" `
  --chapters 8 `
  --with-review
```

1. **Gather info**: Project name, title, location, chapter count
2. **Run script**: `scripts/setup_workspace.py`
3. **Review output**: Confirm README, agents, instructions, and docs were created
4. **Customize**: Edit `docs/reader-personas.md`, `docs/page-allocation.md`, `docs/schedule.md`, and `.github/copilot-instructions.md`. If `--with-review` is used, also customize `config/review-metadata/project.yml`.

Git workflows are project-specific. Do not add generic commit/push prompts here; follow the repository's existing version-control conventions.

Metadata, migration, converter verification, and sync-back rules live in references. Keep the main SKILL focused on manuscript structure and writing workflow.

## Generated Workspace

- Manuscript folders under `keypoints/`, `sections/`, and `images/`
- AI workflow files under `.github/agents/` and `.github/instructions/`
- Project docs such as `README.md`, `docs/reader-personas.md`, `docs/page-allocation.md`, and `docs/schedule.md`
- Helper scripts such as `scripts/count_chars.py`
- Optional Re:VIEW scripts and metadata when `--with-review` is used

## Recommended Writing Unit

- Use **1 file = 1 section** as the default manuscript unit.
- Keep chapter intro in `{NN}-{slug}/{NN}-{slug}.md` and section files alongside it.
- For PDF/Re:VIEW output, heading levels define hierarchy, while file split mainly improves authoring and review workflow.

## Agents Overview

| Agent               | Role                          | Default |
| ------------------- | ----------------------------- | ------- |
| `@writing`          | Write and edit manuscripts    | Yes     |
| `@writing-reviewer` | Review manuscripts (P1/P2/P3) | Yes     |
| `@converter`        | Convert Markdown to Re:VIEW   | Only with `--with-review` |

## Dependencies

| Tool        | Purpose           | Required |
| ----------- | ----------------- | -------- |
| Python 3.8+ | Scripts           | Yes      |
| Git         | Version control   | Yes      |
| Docker      | Re:VIEW PDF build | Optional, only with `--with-review` |

## Reference Map

| Topic                | Reference                                                                |
| -------------------- | ------------------------------------------------------------------------ |
| Folder structure     | [references/folder-structure.md](references/folder-structure.md)         |
| Setup workflow       | [references/setup-workflow.md](references/setup-workflow.md)             |
| Customization points | [references/customization-points.md](references/customization-points.md) |
| Re:VIEW / PDF tips   | [references/review-pdf-tips.md](references/review-pdf-tips.md)           |

## Optional Build Pipeline

For workspaces that add conversion or PDF rendering, apply [build pipeline gates](templates/docs/build-pipeline-gates.md). Keep project-specific commands, dependency versions, and formatter rules in the generated workspace.

## Done Criteria

- [ ] Workspace folder structure created
- [ ] Writing and review agents deployed to `.github/agents/`
- [ ] One reader-persona SSOT is selected; new workspaces use `docs/reader-personas.md` without placeholders
- [ ] `docs/page-allocation.md` configured
- [ ] `README.md` and `docs/schedule.md` customized
- [ ] Manuscript files follow the chapter/section naming convention
- [ ] `scripts/count_chars.py` works for target manuscript files
- [ ] Setup fails before mutation when a required template, script, or asset is missing
- [ ] A clean temporary-directory smoke test generates `docs/reader-personas.md` and exits successfully
- [ ] Re:VIEW/PDF output is either explicitly out of scope or enabled and verified