| name | scriptorium-overview |
| description | Guide for the scriptorium multi-agent framework for writing technical books about open-source source code. Use when: starting a new book writing project, understanding the system architecture, asking what scriptorium is or does, deciding which agent or phase to use, getting a quick-start setup guide, or understanding the hub-spoke design and file pointer mechanism. |
| license | MIT |
Tech-Editorial: Multi-Agent Book Writing Framework
Core Philosophy
Agents are stateless; the file system is stateful.
Each agent is a one-time worker with no memory of past calls. All cross-agent state lives in shared files on the file system. The Orchestrator (#0) controls information flow via File Pointers — explicit file path lists injected into each agent's context.
Architecture: Hub-Spoke
┌─────────────┐
│ Orchestrator │ ← Hub (sole coordinator)
│ #0 │
└──────┬───────┘
┌─────────────┼─────────────┐
│ │ │
┌────▼────┐ ┌────▼────┐ ┌───▼─────┐
│ Agent A │ │ Agent B │ │ Agent C │ ← Spokes (no direct inter-agent talk)
└─────────┘ └─────────┘ └─────────┘
- Sub-agents NEVER communicate with each other directly
- All state passes through shared files
- Orchestrator is the only entity that reads all files and issues next instructions
The 12-Agent Team
| # | Agent | Analogy | Phase | Key Output |
|---|
| #0 | Orchestrator | Film Director | All | Task scheduling, file pointer injection |
| #1 | Architect | Tech Director | 1 | outline-draft.md, source-map.md |
| #2 | Reader Advocate | Product Manager | 1 | outline-reader-feedback.md |
| #3 | Researcher | Code Archaeologist | 3 | research/chXX-research.md |
| #4 | Writer | Technical Author | 3 | drafts/chXX-draft.md |
| R1 | Code Reviewer | Principal Engineer | 3,4 | reviews/chXX-r1-code.md |
| R2 | Consistency Reviewer | Memory Curator | 3,4 | reviews/chXX-r2-consistency.md |
| R3 | Content Reviewer | Senior Editor | 1,3,4 | reviews/chXX-r3-content.md |
| RS | Student Reader | CS Junior | 3 | reader-feedback/chXX-rs.md |
| RE | Engineer Reader | 8yr Engineer | 3 | reader-feedback/chXX-re.md |
| RH | Hobbyist Reader | Tech Enthusiast | 3 | reader-feedback/chXX-rh.md |
| #11 | Bookbinder | Layout Designer | 5 | publish/*.html |
5-Phase Pipeline
Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5
大纲定稿 共享资源 逐章写作 统稿审计 HTML发布
构建 ×N章
Quick-Start (4 Steps)
- Copy
agents/, framework/, templates/ into your book project directory
- Fill in templates:
source-map.md (target codebase map), outline.md (chapter structure), style-guide.md (writing rules), glossary.md (initial terms)
- Configure Orchestrator with: project name, source repo path, total chapters, parallel batch size, target audience
- Execute Phase 1: Invoke Architect (#1) → Reader Advocate (#2) → R3 review → human approval of
outline-final.md
File Pointer Protocol
Every agent invocation includes explicit file lists:
- 📥 Must-read files: injected as context before the task
- 📤 Must-write files: the agent's sole output targets
- 🚫 Forbidden files: explicitly listed as read-only
This prevents context overload and accidental overwrites.
Completion Marker System
Each agent appends an HTML comment as the last line of its output:
<!-- RESEARCH_COMPLETE -->
<!-- DRAFT_COMPLETE -->
<!-- R1_CODE_REVIEW_COMPLETE -->
<!-- R2_CONSISTENCY_REVIEW_COMPLETE -->
<!-- R3_CONTENT_REVIEW_COMPLETE -->
<!-- REVIEW_COMPLETE -->
<!-- READER_PANEL_COMPLETE -->
<!-- CHAPTER_FINAL -->
<!-- HTML_COMPLETE -->
The Orchestrator uses these markers (not SQL alone) to detect true completion.
For detailed specs, use the other skills:
/scriptorium-workflow — full phase-by-phase execution guide/scriptorium-agents — all 12 agent specifications with example prompts/scriptorium-templates — how to fill each of the 8 project templates
