Skip to content

Commit dc95ac6

Browse files
zhonghuiCopilot
zhonghui
and
Copilot
committed
feat: add 'How to Use' guide with step-by-step agent invocation prompts
- docs/quick-start.md: ZH guide (6 phases, copy-paste prompts, tips) - docs/en/quick-start.md: EN guide - config.mts: add quick-start to '使用指南/Guides' sidebar (first item) - docs/index.md + en/index.md: hero primary CTA now → quick-start Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 4844c26 commit dc95ac6

5 files changed

Lines changed: 440 additions & 2 deletions

File tree

‎docs/.vitepress/config.mts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ function sidebarZh() {
88
text: '使用指南',
99
collapsed: false,
1010
items: [
11+
{ text: '如何使用 Scriptorium', link: '/quick-start' },
1112
{ text: '与 AI 工具集成', link: '/ai-tools' },
1213
],
1314
},
@@ -62,6 +63,7 @@ function sidebarEn() {
6263
text: 'Guides',
6364
collapsed: false,
6465
items: [
66+
{ text: 'How to Use Scriptorium', link: '/en/quick-start' },
6567
{ text: 'Using with AI Tools', link: '/en/ai-tools' },
6668
],
6769
},

‎docs/en/index.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,10 @@ hero:
1010
alt: Scriptorium
1111
actions:
1212
- theme: brand
13-
text: System Architecture →
13+
text: How to Use →
14+
link: /en/quick-start
15+
- theme: alt
16+
text: System Architecture
1417
link: /en/agents/00-system-overview
1518
- theme: alt
1619
text: 5-Phase Pipeline

‎docs/en/quick-start.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# How to Use Scriptorium
2+
3+
> This guide walks you through writing a technical book from scratch using the Scriptorium framework.
4+
5+
---
6+
7+
## Prerequisites
8+
9+
- An AI coding assistant ([Claude Code](https://claude.ai/code), [OpenCode](https://opencode.ai), [Cursor](https://cursor.sh), etc.)
10+
- An open-source project you want to analyze (Spring Framework, Redis, Vue.js, etc.)
11+
- A GitHub account
12+
13+
---
14+
15+
## Step 1: Create a Book Project
16+
17+
Click **"Use this template"** on GitHub to create your book repository:
18+
19+
```
20+
https://github.com/lordmos/tech-editorial
21+
```
22+
23+
Or clone locally:
24+
25+
```bash
26+
git clone https://github.com/lordmos/tech-editorial.git my-book
27+
cd my-book
28+
```
29+
30+
Open the directory with your AI tool — Claude Code, OpenCode, and Cursor will auto-read `CLAUDE.md`.
31+
32+
---
33+
34+
## Step 2: Fill in Project Details
35+
36+
Open `CLAUDE.md` in the root and fill in the book information:
37+
38+
```markdown
39+
## 📖 About This Book Project
40+
41+
- **Book Title**: Deep Dive into Spring Framework Source Code
42+
- **Source Project**: spring-projects/spring-framework
43+
- **Target Reader**: Backend engineers with 3+ years of Java experience
44+
- **One-line Description**: Understand IoC/AOP design philosophy through Spring source code
45+
```
46+
47+
---
48+
49+
## Step 3: Phase 1 — Outline
50+
51+
**Goal**: Define the book structure and build the source-code mapping.
52+
53+
**Invoke the Architect agent (copy this prompt):**
54+
55+
```
56+
Please act as the Architect agent defined in agents/02-architect.md.
57+
58+
Context:
59+
- Book title: [your title]
60+
- Source repo: [local path or GitHub URL]
61+
- Target reader: [reader profile]
62+
63+
Tasks:
64+
1. Analyze the source code directory, identify core modules
65+
2. Generate outline.md (suggest 8–12 chapters, 2–3 sentences each)
66+
3. Generate source-map.md (map each chapter to its source files/directories)
67+
68+
Output: outline.md, source-map.md
69+
```
70+
71+
Then validate the outline with the Reader Advocate:
72+
73+
```
74+
Please act as the Reader Advocate defined in agents/03-reader-advocate.md.
75+
76+
Context: outline.md (please read it)
77+
Target reader: [reader profile]
78+
79+
Task: Review the outline from a reader's perspective — is the learning curve reasonable?
80+
Are prerequisites clear? Does the chapter order flow naturally?
81+
```
82+
83+
**Phase 1 done when**: `outline.md` and `source-map.md` are confirmed.
84+
85+
---
86+
87+
## Step 4: Phase 2 & 3 — Research + Writing (per chapter)
88+
89+
For each chapter, run these two agents in sequence:
90+
91+
### Researcher
92+
93+
```
94+
Please act as the Researcher agent defined in agents/04-researcher.md.
95+
96+
File Pointers:
97+
- source-map.md (Chapter N section)
98+
- outline.md (Chapter N section)
99+
- [relevant source code file paths]
100+
101+
Task: Research Chapter N "[chapter title]" and produce a full research report.
102+
Output: research/ch0N-report.md
103+
Then update: checkpoint.md
104+
```
105+
106+
### Writer
107+
108+
```
109+
Please act as the Writer agent defined in agents/05-writer.md.
110+
111+
File Pointers:
112+
- research/ch0N-report.md
113+
- outline.md (Chapter N section)
114+
- style-guide.md
115+
- glossary.md
116+
- metaphor-registry.md
117+
118+
Task: Write the complete draft of Chapter N based on the research report.
119+
Output: chapters/ch0N-draft.md
120+
Then update: checkpoint.md, metaphor-registry.md (append new metaphors from this chapter)
121+
```
122+
123+
**Batch tip**: Tell the AI "process chapters 1 through 3 in sequence" — it will loop automatically.
124+
125+
---
126+
127+
## Step 5: Phase 4 — Triple Review
128+
129+
After each chapter draft, run three reviewers (can run in parallel across separate sessions):
130+
131+
| Reviewer | Spec | Focus |
132+
|----------|------|-------|
133+
| R1 Code | `agents/06-code-reviewer.md` | Code snippet accuracy, API versions |
134+
| R2 Consistency | `agents/07-consistency-reviewer.md` | Cross-chapter terminology, metaphors |
135+
| R3 Content | `agents/08-content-reviewer.md` | Readability, logic, length |
136+
137+
**After the three reviews**, consolidate and revise:
138+
139+
```
140+
Please consolidate the review comments in reviews/ch0N-r1.md, reviews/ch0N-r2.md,
141+
and reviews/ch0N-r3.md, then revise chapters/ch0N-draft.md accordingly.
142+
Output the revised draft to chapters/ch0N-final.md.
143+
```
144+
145+
---
146+
147+
## Step 6: Phase 5 — Publish
148+
149+
Once all chapters are finalized, run the Bookbinder:
150+
151+
```
152+
Please act as the Bookbinder agent defined in agents/10-bookbinder.md.
153+
154+
File Pointers:
155+
- outline.md
156+
- chapters/ch01-final.md through chapters/chNN-final.md
157+
- style-guide.md
158+
159+
Task: Assemble all chapters into a uniformly formatted complete manuscript.
160+
Output: output/book-final.md (or multi-file output in output/)
161+
```
162+
163+
---
164+
165+
## Tracking Progress
166+
167+
Check `checkpoint.md` at any time to see project state:
168+
169+
```bash
170+
cat checkpoint.md
171+
```
172+
173+
Recommended format:
174+
175+
```markdown
176+
## Progress Overview
177+
- [x] Phase 1: Outline finalized
178+
- [x] Phase 2: Shared resources built
179+
- [ ] Phase 3: Chapter writing (3/12 done)
180+
- [x] Chapter 1
181+
- [x] Chapter 2
182+
- [x] Chapter 3
183+
- [ ] Chapter 4 ← next
184+
...
185+
```
186+
187+
---
188+
189+
## Tips
190+
191+
**💡 Stop and resume any time**
192+
All state lives in files. Tell the AI: "Read `checkpoint.md` and continue where we left off."
193+
194+
**💡 Parallelize to go faster**
195+
Chapters in Phase 3 and Phase 4 are independent — run them in multiple AI sessions simultaneously.
196+
Details: [DAG Batch Execution Strategy](/en/framework/parallel-strategy)
197+
198+
**💡 Shared files evolve throughout writing**
199+
`glossary.md` and `metaphor-registry.md` grow over time. Always pass the latest versions to the Writer.
200+
201+
**💡 Never modify agents/ or framework/**
202+
These directories are read-only framework core. Treat them as immutable reference material.
203+
204+
---
205+
206+
## Full Pipeline at a Glance
207+
208+
```
209+
Phase 1 Outline → outline.md + source-map.md
210+
Phase 2 Shared Res. → glossary.md + style-guide.md + metaphor-registry.md
211+
Phase 3 Per-chapter → research/ch0N-report.md → chapters/ch0N-draft.md
212+
Phase 4 Triple Review → reviews/ch0N-{r1,r2,r3}.md → chapters/ch0N-final.md
213+
Phase 5 Publish → output/book-final.md
214+
```
215+
216+
> More details: [5-Phase Production Pipeline](/en/framework/workflow), [Checkpoint Recovery](/en/framework/recovery)

‎docs/index.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,10 @@ hero:
1010
alt: Scriptorium
1111
actions:
1212
- theme: brand
13-
text: 系统架构 →
13+
text: 如何使用 →
14+
link: /quick-start
15+
- theme: alt
16+
text: 系统架构
1417
link: /agents/00-system-overview
1518
- theme: alt
1619
text: 5阶段流水线

0 commit comments

Comments
 (0)